Refunds

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

Read Refunds for the model and the lifecycle. For a walkthrough, read Refund a payment.

The refund object#

A return of all or part of a payment.

Attributes

refundIdstring
paymentIdstring
transactionIdstring
amountobject
An amount in minor units with its currency.
Child attributes of amount
- amountMinorinteger
  The amount in the smallest unit of the currency, for example cents.
- currencystring
  An ISO 4217 alphabetic currency code.
  Pattern ^[A-Z]{3}$.
statusstring
The state of the refund. See the refund lifecycle.
referencestringCan be absent
Your own reference for the refund. Absent when you did not send one.
createdAtstring (date-time)
updatedAtstring (date-time)

The response can include fields that this page does not list. Ignore fields that you do not know.

The refund object

{
  "refundId": "rfnd_9KcT4mW2xQ7bN5vLp",
  "paymentId": "pay_3RtN6wYc8mK2hQvJd",
  "transactionId": "txn_0F8mQ2rXbT4kL9pZa",
  "amount": {
    "amountMinor": 5000,
    "currency": "EUR"
  },
  "status": "refunded",
  "reference": "RMA-2291",
  "createdAt": "2026-09-20T13:02:11Z",
  "updatedAt": "2026-09-20T13:02:58Z"
}

Refund a payment#

POST/v1/payments/{paymentId}/refunds

Refunds all or part of a succeeded or partially_refunded payment. Without amount, the refund is for the full amount that is not yet refunded. You can refund a payment more than once, up to the amount collected.

The refund starts in the requested state. The result arrives later, as refund.succeeded or refund.failed.

A payment that does not exist returns 422.

Requires the payments:refund scope.

Path parameters

paymentIdstringRequired
The payment id.

Headers

Idempotency-KeystringRequired
A unique key for this request, at most 200 characters. A retry with the same key and body returns the first result.
At most 200 characters.

Request body

amountobject
The amount to refund. Absent when the whole remaining amount is refunded.
Child attributes of amount
- amountMinorintegerRequired
  The amount in the smallest unit of the currency, for example cents.
- currencystringRequired
  An ISO 4217 alphabetic currency code.
  Pattern ^[A-Z]{3}$.
referencestring
Your own reference for the refund.
reasonstring
Why you refund the payment. At most 500 characters. It is not returned.

Returns

202The refund object.

Errors

Status	Meaning
400	The request is not valid. See the error body for the field at fault.
401	The API key is missing, malformed, revoked, or unknown.
403	The API key does not hold the scope that this operation requires.
409	The request conflicts with the current state of the resource, or the idempotency key was used with a different request.
422	The request is valid, but Merxian cannot apply it to the current data.
500	An unexpected error occurred. Retry with the same idempotency key.
502	Merxian could not complete the request. Retry with the same idempotency key.
503	Merxian could not verify the API key. Retry later.

The error reference lists the codes in each error body.

Webhook events

This call can cause these events, later and in any order:

POST /v1/payments/{paymentId}/refunds

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"
  }'

const response = await fetch('https://api.merxian.com/v1/payments/pay_3RtN6wYc8mK2hQvJd/refunds', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MERXIAN_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "amount": {
      "amountMinor": 5000,
      "currency": "EUR"
    },
    "reason": "Returned one seat.",
    "reference": "RMA-2291"
  }),
})
const result = await response.json()

Response · 202

{
  "refundId": "rfnd_9KcT4mW2xQ7bN5vLp",
  "paymentId": "pay_3RtN6wYc8mK2hQvJd",
  "transactionId": "txn_0F8mQ2rXbT4kL9pZa",
  "amount": {
    "amountMinor": 5000,
    "currency": "EUR"
  },
  "status": "requested",
  "reference": "RMA-2291",
  "createdAt": "2026-09-20T13:02:11Z",
  "updatedAt": "2026-09-20T13:02:11Z"
}

Retrieve a refund#

GET/v1/refunds/{refundId}

Returns one refund. A refund that does not exist, or that belongs to another account, returns 404 with an empty body.

Requires the payments:read scope.

Path parameters

refundIdstringRequired
The refund id.

Returns

200The refund object.

Errors

Status	Meaning
401	The API key is missing, malformed, revoked, or unknown.
403	The API key does not hold the scope that this operation requires.
404	The resource does not exist, or it belongs to another account.
500	An unexpected error occurred. Retry with the same idempotency key.
502	Merxian could not complete the request. Retry with the same idempotency key.
503	Merxian could not verify the API key. Retry later.

The error reference lists the codes in each error body.

GET /v1/refunds/{refundId}

curl "https://api.merxian.com/v1/refunds/rfnd_9KcT4mW2xQ7bN5vLp" \
  -H "Authorization: Bearer $MERXIAN_API_KEY"

const response = await fetch('https://api.merxian.com/v1/refunds/rfnd_9KcT4mW2xQ7bN5vLp', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.MERXIAN_API_KEY}`,
  },
})
const result = await response.json()

Response · 200

{
  "refundId": "rfnd_9KcT4mW2xQ7bN5vLp",
  "paymentId": "pay_3RtN6wYc8mK2hQvJd",
  "transactionId": "txn_0F8mQ2rXbT4kL9pZa",
  "amount": {
    "amountMinor": 5000,
    "currency": "EUR"
  },
  "status": "refunded",
  "reference": "RMA-2291",
  "createdAt": "2026-09-20T13:02:11Z",
  "updatedAt": "2026-09-20T13:02:58Z"
}