Payments - Refunds and Manual Settlement

Open charge

To create a charge without charging right away, and let the customer choose how to pay in the embedded checkout, use open: true with allowed_methods. The step-by-step is in the embedded checkout guide.

Refund

Refunds a payment paid by card or PIX and returns the amount to the customer:

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 } }'

A payment can only be refunded if it is:

status: "paid";
paid by card (credit) less than 350 days ago, or by PIX (pix) less than 90 days ago;
covered by enough balance in your account for the refund.

Bank slips and manual settlements cannot be refunded through the API. The payment's can_refund field tells whether it can be refunded right now.

When it cannot, the API responds with 422 REFUND_NOT_ALLOWED, with the reason in message (already refunded, past the deadline, insufficient balance, refund already requested...).

Tracking the refund

Card refunds are usually immediate: the payment becomes reversed and the payment.updated webhook is sent. PIX refunds may stay in processing; fetch the payment with its refunds:

Shell

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

Each item in refunds has id, method, value (cents), status and the dates. The status goes from new and processing to completed (returned) or failed. While a refund is processing, another request for the same payment is rejected.

Manual settlement

Marks as paid a payment that the customer settled outside NinePay (in cash or by bank transfer, for example):

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 (the default) keeps the payment amount; zero settles it with an amount of 0 (a waived payment, for example).
Only valid for unpaid or unauthorized payments. For others, the API responds with 400 INVALID_STATE_ERROR.
The payment becomes paid with method: "manual", and the payment.updated webhook is sent.
Because it is manual, it cannot be refunded through the API.