Listar transações

curl --request GET \
  --url https://api.sandbox.z2pay.com/v1/transactions \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.sandbox.z2pay.com/v1/transactions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": [
    {
      "id": "txn_raqtaj22an9s5dexc1vthopl8",
      "customerId": "cust_f7vm6b4j4cckf8gli2b2472ix",
      "amount": 19990,
      "currency": "BRL",
      "paidAmount": 19990,
      "refundedAmount": 0,
      "status": "paid",
      "parentTransactionId": null,
      "referenceCode": "ORDER-2025-00123",
      "ip": "189.45.12.34",
      "additionalInfo": {
        "source": "checkout-web"
      },
      "customerName": "Maria Silva",
      "customerEmail": "maria.silva@example.com",
      "customerDocument": "12345678909",
      "customerDocumentType": "cpf",
      "customerPhone": "+5511987654321",
      "createdAt": "2025-06-29T13:45:30.000Z",
      "updatedAt": "2025-06-29T13:46:10.000Z",
      "paidAt": "2026-06-24T12:05:00.000Z",
      "expiresAt": "2026-06-25T12:00:00.000Z",
      "canceledAt": null,
      "refundedAt": null,
      "chargedbackAt": null,
      "protestedAt": null,
      "items": [
        {
          "id": "item_s4206yea51f6fsiugybgb51sr",
          "transactionId": "txn_raqtaj22an9s5dexc1vthopl8",
          "code": "PLANO-PRO",
          "description": "Plano Pro (mensal)",
          "unitValue": 19990,
          "quantity": 1,
          "amount": 19990,
          "createdAt": "2026-06-24T12:00:00.000Z",
          "updatedAt": "2026-06-24T12:00:00.000Z"
        }
      ],
      "payments": [
        {
          "id": "pay_kd6z67zbp52rgtg2idms96fhm",
          "transactionId": "txn_raqtaj22an9s5dexc1vthopl8",
          "replacedByPaymentId": null,
          "amount": 19990,
          "currency": "BRL",
          "installments": 1,
          "paymentMethod": "pix",
          "cardId": null,
          "status": "paid",
          "additionalInfo": null,
          "statementDescriptor": null,
          "billingAddress": null,
          "boletoUrl": null,
          "boletoDigitableLine": null,
          "boletoBarcode": null,
          "pixUrl": "https://pix.z2pay.com/qr/pay_kd6z67zbp52rgtg2idms96fhm/qr.png",
          "pixCopyPaste": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890520400005303986540519.905802BR5913LOJA EXEMPLO6009SAO PAULO62070503***6304A1B2",
          "splitConfigId": null,
          "originalAmount": null,
          "acquirerReturnCode": null,
          "acquirerReturnMessage": null,
          "retryable": null,
          "declineCode": null,
          "errorMessage": null,
          "createdAt": "2026-06-24T12:00:00.000Z",
          "updatedAt": "2026-06-24T12:05:00.000Z",
          "paidAt": "2026-06-24T12:05:00.000Z",
          "expiresAt": "2026-06-25T12:00:00.000Z",
          "canceledAt": null,
          "refundedAt": null,
          "chargedbackAt": null,
          "protestedAt": null,
          "card": null,
          "splits": []
        }
      ],
      "customerAddress": {
        "street": "Av. Paulista",
        "number": "1000",
        "complement": "Conj. 101",
        "neighborhood": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "postalCode": "01310100",
        "country": "BR"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "issues": [
      {
        "path": "status",
        "message": "Status inválido. Valores aceitos: pending, waiting_payment, paid, refused, canceled, refunded"
      },
      {
        "path": "startDate",
        "message": "Data deve ser ISO 8601 com timezone (ex.: 2026-06-24T00:00:00Z)"
      }
    ]
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

GET

transactions

Listar transações

curl --request GET \
  --url https://api.sandbox.z2pay.com/v1/transactions \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.sandbox.z2pay.com/v1/transactions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": [
    {
      "id": "txn_raqtaj22an9s5dexc1vthopl8",
      "customerId": "cust_f7vm6b4j4cckf8gli2b2472ix",
      "amount": 19990,
      "currency": "BRL",
      "paidAmount": 19990,
      "refundedAmount": 0,
      "status": "paid",
      "parentTransactionId": null,
      "referenceCode": "ORDER-2025-00123",
      "ip": "189.45.12.34",
      "additionalInfo": {
        "source": "checkout-web"
      },
      "customerName": "Maria Silva",
      "customerEmail": "maria.silva@example.com",
      "customerDocument": "12345678909",
      "customerDocumentType": "cpf",
      "customerPhone": "+5511987654321",
      "createdAt": "2025-06-29T13:45:30.000Z",
      "updatedAt": "2025-06-29T13:46:10.000Z",
      "paidAt": "2026-06-24T12:05:00.000Z",
      "expiresAt": "2026-06-25T12:00:00.000Z",
      "canceledAt": null,
      "refundedAt": null,
      "chargedbackAt": null,
      "protestedAt": null,
      "items": [
        {
          "id": "item_s4206yea51f6fsiugybgb51sr",
          "transactionId": "txn_raqtaj22an9s5dexc1vthopl8",
          "code": "PLANO-PRO",
          "description": "Plano Pro (mensal)",
          "unitValue": 19990,
          "quantity": 1,
          "amount": 19990,
          "createdAt": "2026-06-24T12:00:00.000Z",
          "updatedAt": "2026-06-24T12:00:00.000Z"
        }
      ],
      "payments": [
        {
          "id": "pay_kd6z67zbp52rgtg2idms96fhm",
          "transactionId": "txn_raqtaj22an9s5dexc1vthopl8",
          "replacedByPaymentId": null,
          "amount": 19990,
          "currency": "BRL",
          "installments": 1,
          "paymentMethod": "pix",
          "cardId": null,
          "status": "paid",
          "additionalInfo": null,
          "statementDescriptor": null,
          "billingAddress": null,
          "boletoUrl": null,
          "boletoDigitableLine": null,
          "boletoBarcode": null,
          "pixUrl": "https://pix.z2pay.com/qr/pay_kd6z67zbp52rgtg2idms96fhm/qr.png",
          "pixCopyPaste": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890520400005303986540519.905802BR5913LOJA EXEMPLO6009SAO PAULO62070503***6304A1B2",
          "splitConfigId": null,
          "originalAmount": null,
          "acquirerReturnCode": null,
          "acquirerReturnMessage": null,
          "retryable": null,
          "declineCode": null,
          "errorMessage": null,
          "createdAt": "2026-06-24T12:00:00.000Z",
          "updatedAt": "2026-06-24T12:05:00.000Z",
          "paidAt": "2026-06-24T12:05:00.000Z",
          "expiresAt": "2026-06-25T12:00:00.000Z",
          "canceledAt": null,
          "refundedAt": null,
          "chargedbackAt": null,
          "protestedAt": null,
          "card": null,
          "splits": []
        }
      ],
      "customerAddress": {
        "street": "Av. Paulista",
        "number": "1000",
        "complement": "Conj. 101",
        "neighborhood": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "postalCode": "01310100",
        "country": "BR"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "issues": [
      {
        "path": "status",
        "message": "Status inválido. Valores aceitos: pending, waiting_payment, paid, refused, canceled, refunded"
      },
      {
        "path": "startDate",
        "message": "Data deve ser ISO 8601 com timezone (ex.: 2026-06-24T00:00:00Z)"
      }
    ]
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

GET /transactions Faz parte do recurso Transações — o conceito, o ciclo de vida e a tabela de status estão lá. Retorna uma lista paginada. Todos os filtros são opcionais e podem ser combinados. Os valores aceitos em status são os de Status da transação, e as datas seguem ISO 8601 com timezone (veja Convenções).

Filtro com valor inválido é rejeitado, não ignorado. ?status=xpto responde 400 com error.issues[] apontando o campo e os valores aceitos.O formato do erro e a lista de códigos estão em Erros.

Vários valores no mesmo filtro. status, currency, paymentMethod e recipientIds aceitam uma lista separada por vírgula, e o resultado traz qualquer transação que case com um dos valores. Ex.: ?status=paid,refused&paymentMethod=pix,boleto.

Sincronização incremental. Para trazer só o que mudou desde a última execução, combine dateField=updatedAt com startDate e ordene por updatedAt. O campo updatedAt é atualizado a cada mudança de estado da transação — inclusive um estorno meses depois da venda, que uma busca por createdAt não traria.

?dateField=updatedAt&startDate=2026-06-24T00:00:00.000Z&sortBy=updatedAt&sortDir=asc

Prefira janelas fechadas (startDate + endDate) a varrer muitas páginas de um período ainda em aberto: registros alterados durante a varredura mudam de posição e podem escapar da paginação.

Exemplo

curl "https://api.sandbox.z2pay.com/v1/transactions?status=paid,partially_paid&sortBy=createdAt&sortDir=desc&limit=20" \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "data": [
    {
      "id": "txn_ebgsvfsb4151nmbgvj4sek6ol",
      "referenceCode": "pedido-2026-0001",
      "status": "paid",
      "amount": 9990,
      "currency": "BRL",
      "customerId": "cust_lhsmn6ugmjotm5qvnunrr2hz1",
      "createdAt": "2026-06-24T12:00:00.000Z",
      "payments": [
        {
          "id": "pay_kd6z67zbp52rgtg2idms96fhm",
          "paymentMethod": "pix",
          "status": "paid",
          "amount": 9990
        }
      ],
      "items": [
        {
          "id": "item_s4206yea51f6fsiugybgb51sr",
          "description": "Plano Pro (mensal)",
          "quantity": 1,
          "unitValue": 9990,
          "amount": 9990
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

A listagem já traz payments e items. Cada item de data vem com os pagamentos (com dados do cartão e os splits, quando houver) e os itens da transação. Para percorrer transações com seus pagamentos não é preciso chamar GET /transactions/{id} de novo para cada uma.Como o payload por transação é grande, prefira limit menor quando estiver varrendo muitos registros.

Os dados do cliente vêm em duas formas. A transação carrega o snapshot do comprador no momento da compra — customerName, customerEmail, customerDocument, customerDocumentType e customerPhone — que não muda depois, mesmo que o cliente atualize o cadastro. É o que você quer para conferir uma venda antiga.Para o cadastro atual (incluindo endereço), use o customerId em GET /customers/{id}. O objeto customer completo vem em GET /transactions/{id}, não na listagem.

Authorizations

x-api-key

string

header

required

API Key da Credential (gerada no Backoffice)

Query Parameters

page

integer

default:1

Página da listagem. Padrão: 1.

Required range: x >= 1

limit

integer

default:20

Itens por página. Padrão: 20. Máximo: 100.

Required range: 1 <= x <= 100

currency

enum<string>[]

Moeda (ISO 4217). Hoje o único valor aceito é 'BRL'.

Available options:

BRL

status

string[]

Status da transação. Aceita vários valores separados por vírgula.

customerName

string | null

Nome do cliente. Busca parcial (contém).

customerEmail

string | null

E-mail do cliente. Busca parcial (contém).

customerDocument

string | null

Documento do cliente. Match exato — precisa ser idêntico ao cadastrado.

referenceCode

string | null

Seu código de referência para a transação. Match exato.

recipientIds

string[]

IDs de recebedores (rec_) que devem aparecer em algum split da transação. Aceita vários valores separados por vírgula.

Minimum string length: 1

additionalInfoSearch

string | null

Busca textual dentro de additionalInfo. O match é parcial e roda sobre o JSON inteiro, então casa também o nome da chave, não só o valor.

startDate

string<date-time> | null

Data inicial, ISO 8601 com timezone. Aplica-se ao campo indicado em dateField.

endDate

string<date-time> | null

Data final, ISO 8601 com timezone. Aplica-se ao campo indicado em dateField.

paymentMethod

enum<string>[]

Método de pagamento usado na transação. Aceita vários valores separados por vírgula. combined traz as transações com dois ou mais pagamentos ativos.

Available options:

credit_card,

boleto,

pix,

combined

dateField

enum<string> | null

Campo de data ao qual startDate/endDate se aplicam. Padrão: createdAt.

Available options:

createdAt,

updatedAt,

paidAt,

refundedAt,

canceledAt,

chargedbackAt,

protestedAt

sortBy

enum<string> | null

Campo de ordenação. Padrão: createdAt. Use updatedAt para sincronização incremental (o campo muda a cada alteração da transação).

Available options:

createdAt,

updatedAt

sortDir

enum<string> | null

Direção da ordenação. Padrão: desc.

Available options:

asc,

desc

Response

Lista paginada de transações

data

object[]

Lista de registros retornados na página atual.

Show child attributes

pagination

object

Dados de paginação do resultado.

Show child attributes

Cobranças

Clientes & Cartões

Checkout

Cobrança recorrente

Split & Recebedores

Webhooks & Eventos

Valores & Taxas

Listar transações

Exemplo

Authorizations

Query Parameters

Response

​Exemplo

Authorizations

Query Parameters

Response

Exemplo