Pagamentos - Estorno e Baixa Manual

Cobrança em aberto

Para criar uma cobrança sem cobrar na hora, e deixar o cliente escolher como pagar no checkout embutido, use open: true com allowed_methods. O passo a passo está no guia do checkout embutido.

Estorno

Estorna um pagamento pago no cartão ou no PIX e devolve o valor ao cliente:

Shell

curl -X POST https://payments.cefis.com.br/api/v1/payment/reversal \
  -H "Authorization: Bearer $NINEPAY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "payment": { "id": 1470491 } }'

Só pode ser estornado o pagamento:

com status: "paid";
no cartão (credit), pago há menos de 350 dias, ou no PIX (pix), pago há menos de 90 dias;
com saldo suficiente na sua conta para a devolução.

Boleto e baixa manual não têm estorno pela API. O campo can_refund do pagamento diz se ele pode ser estornado agora.

Quando não pode, a API responde 422 REFUND_NOT_ALLOWED, com o motivo em message (já estornado, fora do prazo, saldo insuficiente, estorno já pedido...).

Acompanhando o estorno

O estorno do cartão costuma ser imediato: o pagamento passa a reversed e sai o webhook payment.updated. O do PIX pode ficar em processamento; consulte o pagamento com os reembolsos:

Shell

curl "https://payments.cefis.com.br/api/v1/payments/1470491?with[]=refunds" \
  -H "Authorization: Bearer $NINEPAY_TOKEN" \
  -H "Accept: application/json"

Cada item de refunds tem id, method, value (centavos), status e as datas. O status vai de new e processing para completed (devolvido) ou failed. Enquanto um estorno está em processing, outro pedido para o mesmo pagamento é recusado.

Baixa manual

Marca como pago um pagamento que o cliente quitou por fora da NinePay (em dinheiro ou transferência, por exemplo):

Shell

curl -X POST https://payments.cefis.com.br/api/v1/payment/1470491/write-off \
  -H "Authorization: Bearer $NINEPAY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "value_type": "normal" }'

value_type: normal (o padrão) mantém o valor do pagamento; zero dá a baixa com valor 0 (um pagamento perdoado, por exemplo).
Só vale para pagamentos unpaid ou unauthorized. Nos outros, a API responde 400 INVALID_STATE_ERROR.
O pagamento passa a paid com method: "manual", e sai o webhook payment.updated.
Por ser manual, ele não tem estorno pela API.