/transactions/:transactionId/payments.
Todas as requisições usam o header
x-api-key: SUA_CHAVE_DE_SANDBOX. Veja Autenticação para detalhes. A base URL de sandbox é https://api.sandbox.z2pay.com.Endpoints
| Método | Rota | Descrição |
|---|---|---|
GET | /transactions/{transactionId}/payments | Lista os payments da transação |
GET | /transactions/{transactionId}/payments/{paymentId} | Busca um payment por ID |
POST | /transactions/{transactionId}/payments/process | Processa payments pendentes via gateway |
POST | /transactions/{transactionId}/payments/{paymentId}/refund | Estorna (refund) um payment |
O objeto Payment
Valores monetários são inteiros em centavos (ex.:15000 = R$ 150,00). Datas são strings ISO 8601 com timezone, e ficam null quando ainda não ocorreram.
Identificador do payment (prefixo
pay_).ID da transação à qual o payment pertence (prefixo
txn_).Quando o payment foi substituído (status
replaced), aponta para o novo payment que o substituiu. null caso contrário.ID da company dona do payment.
Valor do payment, em centavos.
Moeda do payment. Default:
BRL.Número de parcelas. Default:
1.Forma de pagamento. Um de:
credit_card, boleto, pix.Identificador interno do provedor que processou o payment.
null enquanto não processado.ID da configuração de gateway escolhida pelo routing.
null enquanto não processado.ID do cartão usado (prefixo
card_), quando aplicável. null para boleto/PIX.Status atual do payment. Veja a lista de valores em Status do payment.
Metadados livres associados ao payment.
null quando ausente.Soft descriptor enviado ao portador na fatura (já normalizado, máximo 13 caracteres).
null quando não definido.URL do boleto (PDF/visualização). Preenchido após o processamento de um payment de boleto.
Linha digitável do boleto.
Código de barras do boleto.
URL da imagem do QR Code do PIX (para exibir/escanear).
Payload BR Code do PIX (copia-e-cola, EMV iniciando em
00020126...), para colar no app do banco.ID da configuração de split aplicada ao payment, quando houver.
Valor original antes de ajustes (em centavos), quando aplicável.
Código de retorno do adquirente.
Mensagem de retorno do adquirente.
Indica se uma falha pode ser retentada.
null quando não aplicável.Código de recusa, quando o payment foi recusado.
Mensagem de erro do processamento, quando houver.
Data de criação (ISO 8601).
Data da última atualização (ISO 8601).
Data em que o payment foi pago.
null enquanto não pago.Data de expiração do instrumento (ex.: TTL do QR Code PIX, vencimento do boleto).
null quando não aplicável.Data de cancelamento.
null quando não cancelado.Data do estorno.
null quando não estornado.Data do chargeback.
null quando não houve.Data de entrada em protesto.
null quando não aplicável.Data de exclusão lógica (soft delete).
null para payments ativos.Versão de concorrência otimista do registro.
Status do payment
O campostatus assume um dos valores abaixo:
| Status | Significado |
|---|---|
pending | Criado, ainda não processado |
waiting_payment | Aguardando pagamento (boleto/PIX emitido) |
authorized | Autorizado (cartão), ainda não capturado/liquidado |
paid | Pago |
partially_paid | Parcialmente pago |
refused | Recusado pelo adquirente |
failed | Falha no processamento |
canceled | Cancelado |
expired | Expirou antes da conclusão (ex.: QR Code PIX ou boleto vencido) |
replaced | Substituído por outro payment |
waiting_refund | Estorno solicitado, aguardando processamento |
refunded | Estornado integralmente |
partially_refunded | Estornado parcialmente |
chargeback | Chargeback registrado |
in_protest | Em protesto |
deleted | Removido logicamente |
Veja também
Transactions
O recurso pai dos payments.
Refunds
Detalhes completos do recurso de estorno.
Tokenizer
Gere o token de cartão para pagar com
credit_card.Simular pagamentos (Sandbox)
Force o desfecho de um PIX/boleto no ambiente de testes.