Buscar transação por ID

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

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

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

{
  "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": []
    }
  ],
  "customer": {
    "id": "cust_f7vm6b4j4cckf8gli2b2472ix",
    "name": "Maria Silva",
    "email": "maria.silva@example.com",
    "type": "individual",
    "document": "12345678909",
    "documentType": "cpf",
    "phone": "+5511999998888",
    "address": {
      "street": "Av. Paulista",
      "number": "1000",
      "complement": "Conj. 101",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postalCode": "01310100",
      "country": "BR"
    },
    "createdAt": "2026-06-24T12:00:00.000Z",
    "updatedAt": "2026-06-24T12:00:00.000Z"
  },
  "customerAddress": {
    "street": "Av. Paulista",
    "number": "1000",
    "complement": "Conj. 101",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "postalCode": "01310100",
    "country": "BR"
  }
}

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

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Transaction not found"
  }
}

GET

transactions

{id}

Buscar transação por ID

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

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

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

{
  "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": []
    }
  ],
  "customer": {
    "id": "cust_f7vm6b4j4cckf8gli2b2472ix",
    "name": "Maria Silva",
    "email": "maria.silva@example.com",
    "type": "individual",
    "document": "12345678909",
    "documentType": "cpf",
    "phone": "+5511999998888",
    "address": {
      "street": "Av. Paulista",
      "number": "1000",
      "complement": "Conj. 101",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postalCode": "01310100",
      "country": "BR"
    },
    "createdAt": "2026-06-24T12:00:00.000Z",
    "updatedAt": "2026-06-24T12:00:00.000Z"
  },
  "customerAddress": {
    "street": "Av. Paulista",
    "number": "1000",
    "complement": "Conj. 101",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "postalCode": "01310100",
    "country": "BR"
  }
}

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

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Transaction not found"
  }
}

GET /transactions/:id Faz parte do recurso Transações — o conceito, o ciclo de vida e a tabela de status estão lá. Retorna a transação com tudo o que ela agrega: os payments (cada um com cartão e splits, quando houver), os items e o objeto customer. É a visão completa — a listagem devolve o mesmo objeto sem o customer, então é por aqui que se obtêm os dados do comprador.

O status é derivado, não armazenado. Ele é recalculado a partir dos pagamentos a cada consulta — por isso uma transação com dois pagamentos, um pago e outro pendente, aparece como partially_paid sem que ninguém tenha escrito esse valor. A tabela completa está em Status da transação.

Exemplo

curl https://api.sandbox.z2pay.com/v1/transactions/txn_ebgsvfsb4151nmbgvj4sek6ol \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "id": "txn_ebgsvfsb4151nmbgvj4sek6ol",
  "referenceCode": "pedido-2026-0001",
  "status": "paid",
  "amount": 9990,
  "currency": "BRL",
  "customerId": "cust_lhsmn6ugmjotm5qvnunrr2hz1",
  "payments": [
    {
      "id": "pay_kd6z67zbp52rgtg2idms96fhm",
      "paymentMethod": "pix",
      "status": "paid",
      "amount": 9990
    }
  ],
  "items": [
    {
      "id": "item_s4206yea51f6fsiugybgb51sr",
      "description": "Plano Pro (mensal)",
      "quantity": 1,
      "unitValue": 9990,
      "amount": 9990
    }
  ]
}

Cada item traz unitValue (o valor unitário que você enviou em items[].amount na criação) e amount (o total da linha, unitValue × quantity). Com quantity: 1 os dois coincidem, o que esconde a diferença — confira num item com quantidade maior.

Authorizations

x-api-key

string

header

required

API Key da Credential (gerada no Backoffice)

Path Parameters

string

required

ID da transação

Response

Dados da transação com payments e items

string

Identificador único do registro.

customerId

string | null

ID do cliente associado à transação.

amount

integer

Valor em centavos.

currency

string

Moeda no padrão ISO 4217 (ex.: BRL).

paidAmount

integer

Valor efetivamente pago, em centavos.

refundedAmount

integer

Valor total estornado, em centavos.

status

string

Situação da transação, derivada dos pagamentos. Valores: pending, waiting_payment, partially_paid, paid, refused, failed, canceled, waiting_refund, partially_refunded, refunded, chargeback, in_protest.

parentTransactionId

string | null

ID da transação de origem, quando esta é derivada de outra.

referenceCode

string | null

Código de referência definido pelo integrador na criação.

string | null

Endereço IP de origem da transação.

additionalInfo

object | null

Informações adicionais do registro (dados livres).

customerName

string | null

Nome do cliente da transação.

customerEmail

string | null

E-mail do cliente da transação.

customerDocument

string | null

Documento (CPF ou CNPJ) do cliente da transação.

customerDocumentType

string | null

Tipo de documento do cliente: cpf ou cnpj.

customerPhone

string | null

Telefone do cliente da transação.

createdAt

string<date-time>

Data e hora de criação do registro (ISO 8601).

updatedAt

string<date-time>

Data e hora da última atualização do registro (ISO 8601).

paidAt

string<date-time> | null

Data e hora em que o pagamento foi liquidado (ISO 8601).

expiresAt

string<date-time> | null

Data e hora em que o registro expira (ISO 8601).

canceledAt

string<date-time> | null

Data e hora em que a transação foi cancelada (ISO 8601).

refundedAt

string<date-time> | null

Data e hora em que o estorno foi concluído (ISO 8601).

chargedbackAt

string<date-time> | null

Data e hora em que a transação sofreu chargeback (ISO 8601).

protestedAt

string<date-time> | null

Data e hora em que a transação foi protestada (ISO 8601).

items

object[]

Itens da transação. Vazio quando a transação não tem itens.

Show child attributes

payments

object[]

Pagamentos da transação, com cartão e splits quando houver.

Show child attributes

customer

object | null

Cliente da transação, quando customerId está preenchido. Não vem na listagem — use GET /customers/{id}.

Show child attributes

customerAddress

object | null

Endereço informado nesta compra, congelado no momento da criação. É este que vale para nota fiscal e antifraude: editar o cadastro do cliente depois não o altera. Compare com customer.address, que reflete o cadastro atual.

Show child attributes

Cobranças

Clientes & Cartões

Checkout

Cobrança recorrente

Split & Recebedores

Webhooks & Eventos

Valores & Taxas

Buscar transação por ID

Exemplo

Authorizations

Path Parameters

Response

​Exemplo

Authorizations

Path Parameters

Response

Exemplo