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));import requests
url = "https://api.sandbox.z2pay.com/v1/transactions/{id}"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text){
"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,
"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"
}
}Transações
Buscar transação por ID
Retorna os dados completos de uma transação, incluindo seus pagamentos e itens.
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));import requests
url = "https://api.sandbox.z2pay.com/v1/transactions/{id}"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text){
"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,
"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
API Key da Credential (gerada no Backoffice)
Path Parameters
ID da transação
Response
Dados da transação com payments e items
Identificador único do registro.
ID do cliente associado à transação.
Valor em centavos.
Moeda no padrão ISO 4217 (ex.: BRL).
Valor efetivamente pago, em centavos.
Valor total estornado, em centavos.
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.
ID da transação de origem, quando esta é derivada de outra.
Código de referência definido pelo integrador na criação.
Endereço IP de origem da transação.
Informações adicionais do registro (dados livres).
Nome do cliente da transação.
E-mail do cliente da transação.
Documento (CPF ou CNPJ) do cliente da transação.
Tipo de documento do cliente: cpf ou cnpj.
Telefone do cliente da transação.
Data e hora de criação do registro (ISO 8601).
Data e hora da última atualização do registro (ISO 8601).
Data e hora em que o pagamento foi liquidado (ISO 8601).
Data e hora em que o registro expira (ISO 8601).
Data e hora em que a transação foi cancelada (ISO 8601).
Data e hora em que o estorno foi concluído (ISO 8601).
Data e hora em que a transação sofreu chargeback (ISO 8601).
Data e hora em que a transação foi protestada (ISO 8601).
Itens da transação. Vazio quando a transação não tem itens.
Show child attributes
Show child attributes
Pagamentos da transação, com cartão e splits quando houver.
Show child attributes
Show child attributes
Cliente da transação, quando customerId está preenchido. Não vem na listagem — use GET /customers/{id}.
Show child attributes
Show child attributes
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
Show child attributes