Refunds and disputes

Refunds#

Refund a successful payment in full or in part:

bash

curl https://sandbox.api.biftpay.com/v1/refunds \
  -H "Authorization: Bearer bp_test_..." \
  -H "Idempotency-Key: refund-order-1042" \
  -H "Content-Type: application/json" \
  -d '{ "payment_intent": "5b0c3f6e-...", "amount": 250000, "reason": "requested_by_customer" }'

Leave out amount to refund everything not yet refunded. reason is optional: requested_by_customer, duplicate or fraudulent.

The money goes back the way the customer paid. Processing fees aren't returned.
The amount is taken from your balance straight away: from pending if the payment hasn't been released yet, otherwise from available. It sits in refund_in_flight until the provider confirms.
A refund starts pending, then becomes succeeded (webhook refund.succeeded) or failed (refund.failed, and the money comes back to your balance).
A payment with an open dispute can't be refunded (409 payment_disputed): the chargeback already returns the money.

Disputes#

A dispute (chargeback) is a customer asking their bank to reverse a card payment. You'll get a dispute.created webhook, and the disputed amount is held from your balance while it's decided.

Status	Meaning
`needs_response`	Send your evidence before `respond_by`.
`under_review`	Evidence sent; the bank is deciding.
`won`	Decided in your favour. The held money is released back to you (`dispute.won`).
`lost`	Decided for the customer. The money goes back to them and a chargeback fee applies (`dispute.lost`).

The chargeback fee is only charged when you lose; it's 0 otherwise.

Responding#

Attach files: receipts, proof of delivery, messages with the customer. POST /v1/disputes/{id}/files.
Submit your explanation, once: POST /v1/disputes/{id}/respond with { "evidence": "..." }.

Respond before respond_by. With no response, the dispute is usually lost.

The fewer disputes you have, the better. Clear descriptions at checkout (what the customer bought, under a name they'll recognise on their statement) prevent most of them.