A refund sends a pay-in back to the person who paid. You can refund a successful pay-in yourself. Payve also creates refunds automatically when a payment link is overpaid or underpaid.

What a refund returns

A refund you request returns the full amount the payer sent: the pay-in’s amount, not the net amount that reached your wallet. Fees you were charged on the pay-in are yours to carry.
  • Refunds are for the whole pay-in. There is no partial refund.
  • A pay-in can be refunded once.
  • The refund goes back on the same kind of rail the payment came in on.

Refund a pay-in

POST /v1/refunds · needs the payouts:write scope
string
required
The publicId of the pay-in, such as pin_3f9a2c1d8e7b6a50.
Response · 201
string
The ref_ id. Use it in refund URLs.
string
The amount being refunded, in minor units.
string
Where the refund is. See the table below.
string
merchant_initiated, overpayment or underpayment.
object | null
Where the refund is going.
string | null
What the refund is waiting for, in plain words.
integer | null
The payout that carries the refund, once it has been sent.
Only a pay-in that succeeded can be refunded. Asking to refund the same pay-in again returns the refund that already exists.

Refund statuses

Refunds use succeeded, not successful. Do not reuse your transaction status handling for them.

When the destination is known

For a bank transfer, the bank usually tells Payve which account paid. Payve stores it as senderDetails on the pay-in and uses it for the refund. The refund then starts in processing with recipientInfo filled in, and you do nothing more.

When the destination is not known

The refund starts in awaiting_recipient. Supply the destination: POST /v1/refunds/{id}/process · needs the payouts:write scope
For a mobile money refund, send phoneNumber and operator instead of the bank fields.
You can set the destination once. A second submission for the same refund is refused. Run a name check on the account and confirm it with the payer before you send it. Money refunded to the wrong account is not something Payve can pull back.
When a fixed-amount payment link is overpaid or underpaid beyond your tolerances, Payve creates the refund for you with a reason of overpayment or underpayment. See Overpayment and underpayment. These refunds wait in awaiting_approval for Payve’s review, or in awaiting_recipient if the paying account is not known. In that case the hosted checkout asks the payer for the destination.

Track a refund

There is no webhook event for refunds. Fetch the refund to follow it.
Poll a refund that is processing every few minutes until it is succeeded or failed. Do not tell the payer it has arrived before succeeded.

When it fails