txn_) reúne o que o comprador está pagando (os itens) e como está pagando
(os pagamentos). Cada pagamento é uma tentativa por uma forma específica — cartão, boleto ou Pix — e
uma mesma transação pode ter mais de um.
O status da transação é derivado: você nunca o define. Ele é recalculado a cada mudança nos
pagamentos — é por isso que uma transação com dois pagamentos pode ficar partially_paid.
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 da transação
Você nunca define o status da transação — ele é derivado dos pagamentos e recalculado sempre que um deles muda de estado. Com um único pagamento, a transação acompanha o status dele. Com mais de um, ela resume o conjunto (veja Quando há mais de um pagamento).Quando há mais de um pagamento
Uma transação pode ter vários pagamentos: Pix + cartão, dois cartões, ou uma nova tentativa depois de uma recusa. Nesses casos, quatro regras explicam o status que você vê.paid significa que o valor pago cobre o total — não que todos os pagamentos foram aprovados.
A diferença aparece quando a transação recebe mais do que foi cobrado: o caso mais comum é o
comprador gerar um Pix, desistir e pagar no cartão, e depois acabar pagando o Pix também. Estornar
o excedente mantém a transação paid, porque o valor que restou continua cobrindo o total — e ela
segue paid inclusive enquanto esse estorno está sendo processado.Pagamento incompleto e sem estorno fica
partially_paid. Assim que qualquer estorno entra em
cena, a transação passa a refletir o ciclo de estorno (waiting_refund, partially_refunded ou
refunded) em vez de continuar como parcialmente paga — mesmo que parte do dinheiro ainda esteja
retida.Recusa prevalece sobre falha técnica. Se um pagamento foi recusado pelo emissor e outro falhou
por erro do gateway, a transação fica
refused — a informação acionável para você e para o
comprador é a recusa.Pagamentos cancelados não travam o estorno. Numa transação com Pix cancelado e cartão pago, o
estorno do cartão leva a transação a
refunded: a parte cancelada é ignorada, porque nunca houve
cobrança ali.Veja também
Pagamentos
Detalhes de cada forma de pagamento dentro da transação.
Reembolsos
Estorno de um pagamento específico e estornos parciais.
Tokenizer
Gere o
token do cartão antes de criar a transação.Split
Configure repasses por pagamento com
split ou splitId.Clientes
Cadastre clientes para reusar via
customerId.Webhooks
Receba notificações de mudança de status da transação.