cbk_) é a contestação que o portador do cartão abre junto ao banco emissor. Quando
a adquirente nos notifica, o caso é criado automaticamente e o pagamento correspondente entra em
contestação. A partir daí você tem uma janela para anexar provas — nota fiscal, comprovante de
entrega, contrato assinado — e defender a cobrança.
Você não abre nem decide um chargeback pela API: o caso nasce de um webhook da adquirente, e é
ela quem julga o desfecho. O que a API oferece é acompanhar o andamento e enviar documentos dentro
do prazo.
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 chargeback
Quem move o status é a adquirente, não você: o caso avança em linha reta, sem voltar atrás. Só um dos estados aceita ação sua —under_review, a janela em que as provas são recebidas.
O que o chargeback faz com o seu dinheiro
O caso não mexe só no status do pagamento — ele movimenta a sua carteira desde a abertura, antes de qualquer decisão. Três regras explicam os lançamentos que você vai ver.O pagamento entra em contestação antes de o caso existir. A ordem é: a adquirente notifica, o
pagamento vai para
in_protest — e é desse evento que o chargeback nasce, já em opened. Não há
um momento com o caso aberto e o pagamento ainda paid.O valor sai assim que a análise começa. Ao entrar em
under_review, o valor contestado é
descontado, junto com a taxa de chargeback — a adquirente retém na abertura da disputa, não no
desfecho. O dinheiro fica fora do seu saldo enquanto o caso corre.Ganhar devolve tudo, inclusive a taxa. Em
won, o pagamento volta para paid, o valor
retido volta ao seu saldo e a taxa de chargeback é estornada. Em lost, o pagamento vai para
chargeback — o principal já tinha saído na abertura, então o que ainda incide é a multa,
configurável por conta.A janela de envio fecha sozinha. Documentos só são aceitos enquanto o caso está em
under_review e dentro do prazo em deadlineAt. Passado isso, o upload é recusado — e quem define
esse prazo é a adquirente, não você.Veja também
Pagamentos
O pagamento contestado, e os status
in_protest e chargeback.Carteiras
Onde aparecem a reserva, o estorno da reserva e a multa.
Taxas
Como a taxa e a multa de chargeback são configuradas.
Simular eventos
Dispare um chargeback de teste para exercitar a consulta e o upload.