Overpayments

When a customer sends more than asked, or money arrives on a canceled payment, and how you close it out.

Because the money goes straight to your card or account, Bezanbecard cannot send any of it back. What it does is keep an exact record of what you owe, so nothing is forgotten.

When an overpayment is recorded

The customer sent more. A payment asked for 12,500,470 rial and 15,000,000 arrived. The payment succeeds, amount_overpaid is 2,500,000 and overpayment.status becomes pending. The unique sum on top of amount is never an overpayment: paying expected_amount exactly is paying in full.
Your team approved more. A receipt approved for more than the payment still asks for, or a second receipt on a payment that already succeeded. Either is refused with receipt_payment_settled until the reviewer confirms the overpayment (overpay: true); the dashboard names the figure first, and linking a bank SMS to a receipt asks for the same confirm.
Money arrived on a payment you canceled. Canceling a payment that had already received money records all of it as owed back: overpayment.status is pending with the amount received.

Either way the payment emits payment.overpaid, the dashboard flags it on the overview, and the store plugins add a note to the order.

Resolving it

Once you have dealt with the money, record what you did:

Resolving it
`status`	Meaning
`refunded`	You transferred it back. Put the bank's trace number in `reference`.
`credited`	You kept it as credit for the customer. It is added to the customer's `credit`.
`kept`	You keep it, for example a tip the customer meant to give.

curl https://a.bezanbecard.com/v1/payments/pay_…/resolve_overpayment \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: refund-1042" \
  -H "Content-Type: application/json" \
  -d '{"status":"refunded","reference":"665544"}'

In the dashboard you can also attach a photo of the refund receipt. Resolving emits payment.overpayment_resolved. A payment with nothing pending answers payment_overpayment_not_pending.

Credit

credited adds the amount to the customer's credit (rial), once per payment. Credit is a record for you to honour on a later order; it is not applied to new payments automatically. The customer's page in the dashboard shows it, and GET /v1/customers/:id returns it.

The overpayment object

overpayment on a payment is { "status": "none" | "pending" | "refunded" | "credited" | "kept", "reference": string | null }, and amount_overpaid holds the overpaid amount. Money you refunded or credited no longer counts toward the payment: when new money reopens a canceled payment whose money went back, it asks for what it did not keep (amount_remaining).