pay_) é uma tentativa de cobrança dentro de uma transação, por uma forma
específica — cartão, boleto ou Pix. Uma mesma transação pode ter mais de um, e é por isso que todas
as rotas vivem sob /transactions/:transactionId/payments.
Você não cria um pagamento avulso: ele nasce junto com a transação, no POST /transactions —
que exige pelo menos um —, ou quando o comprador troca a forma de pagamento no Checkout. Não existe
rota de criação aqui: os endpoints abaixo consultam, processam e estornam o que a transação já
criou.
Todas as rotas exigem o header
x-api-key (sua chave de sandbox). Veja
Autenticação. Os exemplos nas páginas de cada endpoint usam a base URL de
sandbox https://api.sandbox.z2pay.com/v1.Endpoints
Cada endpoint tem sua própria página, com os campos aceitos, exemplos e o playground para testar.Status do pagamento
O status do pagamento diz o que aquela tentativa conseguiu — diferente do status da transação, que resume o conjunto (veja Status da transação). O estado inicial já depende do método: cartão nascepending, Pix e boleto nascem waiting_payment,
porque o QR Code e o boleto são emitidos na própria criação.
Expiração chega como
canceled. Pode-se esperar um status expired para o Pix que venceu ou o
boleto que passou da data — ele não existe na prática. Os gateways o convertem para canceled
antes de chegar até você, então um case 'expired' no seu código nunca seria executado. Para
distinguir vencimento de cancelamento ativo, compare expiresAt com canceledAt.Quando uma tentativa é substituída
Um pagamento não é editado quando o comprador muda de ideia: a tentativa antiga é encerrada comoreplaced e uma nova nasce apontada por ela. Três consequências explicam o que você vê.
Tentativas substituídas não aparecem nas listagens. Um pagamento
replaced fica de fora do
payments que vem embutido em GET /transactions/:id e em
GET /transactions. Para alcançar a tentativa anterior, use o
replacedByPaymentId do pagamento novo em
GET /transactions/:transactionId/payments/:paymentId, que não filtra por
status.Só tentativa em aberto ou malsucedida é substituída. Um pagamento já pago nunca vira
replaced — para desfazer uma cobrança liquidada existe o estorno, que é outro
caminho e deixa rastro próprio.Não existe status
processing para pagamento. Ele existe em reembolsos e em
saques, e a confusão é comum: um pagamento que está sendo processado continua
pending até o gateway responder.Veja também
Transactions
O recurso pai, e como o status da transação sai do conjunto de pagamentos.
Reembolsos
Como estornar um pagamento, no todo ou em parte.
Tokenizer
Gere o token de cartão antes de pagar com
credit_card.Simular pagamentos (Sandbox)
Force o desfecho de um Pix ou boleto no ambiente de testes.