Core concepts

Refunds

A refund returns all or part of a payment to the payer. You request it through the API, and the result arrives later as a webhook event.

On this page

What a refund is
Refund rules
Lifecycle
How you learn the result
Refunds and the fee
Refunds and invoices
What to build

What a refund is#

A refund belongs to one payment. A refund ID starts with rfnd_, for example rfnd_9KcT4mW2xQ7bN5vLp. The refund object uses refundId for its ID.

You create a refund with POST/v1/payments/{paymentId}/refunds and read it with GET/v1/refunds/{refundId}.

Refund rules#

You can refund a payment in the succeeded or partially_refunded state.
Without amount, the refund is for the full amount that is not yet refunded.
With amount, the amount must be more than zero, in the currency of the payment, and not more than the amount that is not yet refunded.
You can refund one payment more than once, up to the amount collected.
reference holds your own reference, for example a return number. The refund returns it.
reason is at most 500 characters. Merxian does not return it.

A request that breaks a rule returns 422 with the code refundValidationFailed.

Lifecycle#

The states of a refund. A double border marks a final state.

From	To	Cause
(new)	`requested`	You request the refund. The API returns `202`.
`requested`	`submitted`	Merxian sent the refund for processing.
`requested`, `submitted`	`refunded`	The money was sent back to the payer.
`requested`, `submitted`	`failed`	The refund could not be completed.
`refunded`	`reversed`	The refund was returned after it succeeded. The money came back to your balance.

How you learn the result#

The response to a refund request has the state requested. It does not mean that money moved. Listen for these events:

Event	Meaning
`refund.succeeded`	The refund reached `refunded`.
`refund.failed`	The refund failed.
`refund.reversed`	A refund that succeeded was reversed.
`transaction.partially_refunded`	Money is still collected on the transaction after the refund.
`transaction.refunded`	All collected money was refunded.

In webhook payloads, the state of a refund that succeeded is succeeded. The API reports the same state as refunded.

Refunds and the fee#

A refund returns part of the percentage fee, in proportion to the refunded amount. The fixed charge is not returned, also not on a full refund. See Fees.

Refunds and invoices#

When Merxian is the merchant of record, a refund reduces an invoiced amount. Merxian then issues a credit note and sends invoice.credited. See Invoices.

What to build#

Store the refund ID and your reference with your record of the return.
Confirm the refund to the buyer after refund.succeeded, not after the API response.
On refund.failed, decide how to return the money to the buyer. You can request a new refund.