Integration guides

Refund a payment

A refund returns all or part of a payment to the payer. You request it with one call. The result arrives later as a webhook event.

On this page

Before you start
Rules for the amount
Request the refund
Follow the result
Retry a refund request safely
Credit notes

Before you start#

You need an API key with the payments:refund scope, and the payment ID, pay_…. To find the payments of a transaction, call GET/v1/transactions/{transactionId}/payments. See Refunds for the model.

Rules for the amount#

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 refund is for exactly that amount. It 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.

A request that breaks a rule returns 422 with the code refundValidationFailed. See Payment and refund errors.

Request the refund#

Refund part of a payment

curl -X POST https://api.merxian.com/v1/payments/pay_3RtN6wYc8mK2hQvJd/refunds \
  -H "Authorization: Bearer $MERXIAN_API_KEY" \
  -H "Idempotency-Key: 9b3f6c1e-2a47-4d8b-b5e0-7c1d2e3f4a5b" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": { "amountMinor": 5000, "currency": "EUR" },
    "reason": "Returned one seat.",
    "reference": "RMA-2291"
  }'

This refunds €50.00. The response is 202 with a refund in the requested state, for example rfnd_9KcT4mW2xQ7bN5vLp. Store the refund ID with your record.

reference is your own reference. It is returned on the refund.
reason has at most 500 characters. Merxian does not return it on the refund.

See POST/v1/payments/{paymentId}/refunds.

Follow the result#

The 202 response does not mean that money moved. Wait for one of these events:

Event	Meaning	What to do
`refund.succeeded`	The money was sent back to the payer.	Confirm the refund to the buyer.
`refund.failed`	The refund could not complete.	Decide how to return the money. You can request a new refund.
`refund.reversed`	A refund that succeeded came back to your balance.	Mark the refund as not paid and contact the buyer.

The transaction also changes. You receive transaction.partially_refunded while money is still collected, or transaction.refunded when all collected money is refunded. The transaction stays completed; paymentStatus and refundedAmount show the refunds.

To read one refund, call GET/v1/refunds/{refundId}. In the API, a refund that succeeded has the state refunded. In webhook payloads the same state is succeeded.

Retry a refund request safely#

A retry with the same Idempotency-Key and the same body is meant to return the first result. For refunds, this does not always hold today: a retry after a refund that succeeded can return 422 or 409 instead of the first result.

Credit notes#

When Merxian is the merchant of record on your account, Merxian issues the invoice to the buyer. A refund then leads to a credit note. You receive invoice.credited with negative amounts. Store the credit note number with the refund. See Invoices.