API reference

Refunds

Refund all or part of a successful payment. Refunds carry their own reference, can be queried independently, and complete asynchronously.

Create a refund

POST/api/v1/refunds/create

Identify the original payment by either reference, and give the refund its own unique number.

Field	Type	Required	Description
`original_order_no`	string	One of two	StablePay order number of the original payment.
`original_merchant_order_no`	string	One of two	Your order number of the original payment.
`merchant_refund_no`	string	Yes	Your refund number. Unique; used for idempotency.
`refund_amount`	string	Yes	Amount to refund as a decimal string, e.g. `10.00`, in the original currency.
`reason`	string	No	Refund reason.
`notify_url`	string	No	URL that receives the signed refund notification.
`metadata`	string	No	Opaque passthrough.

{
  "original_merchant_order_no": "M202606240001",
  "merchant_refund_no": "MR202606240001",
  "refund_amount": "10.00",
  "reason": "customer requested",
  "notify_url": "https://merchant.example.com/callback/refund",
  "metadata": "refund=manual"
}

Field	Type	Description
`refund_no`	string	StablePay refund number.
`merchant_refund_no`	string	Your refund number.
`original_order_no`	string	Original StablePay order number.
`original_merchant_order_no`	string	Original merchant order number.
`status`	string	`PENDING`, `SUCCESS` or `FAILED`.
`refund_amount`	object	`currency` and `value`.
`reason`	string	Refund reason.
`psp_refund_no`	string	StablePay processing reference.
`created_at`	string	Creation time.
`updated_at`	string	Last update time.

200 · response

{
  "code": 0,
  "msg": "success",
  "data": {
    "refund_no": "R202606240001",
    "merchant_refund_no": "MR202606240001",
    "original_order_no": "O202606240001",
    "original_merchant_order_no": "M202606240001",
    "status": "SUCCESS",
    "refund_amount": {
      "currency": "USD",
      "value": "10.00"
    },
    "reason": "customer requested",
    "psp_refund_no": "SPR_R_001",
    "created_at": "2026-06-24T11:00:00Z",
    "updated_at": "2026-06-24T11:00:05Z"
  }
}

Request vs. response amount shape

You send refund_amount as a plain string; the response returns it as an amount object with currency and value.

The final outcome is delivered as a REFUND event to notify_url — see Webhooks.

Query a refund

POST/api/v1/refunds/query

Provide exactly one identifier.

Field	Type	Required	Description
`refund_no`	string	One of two	StablePay refund number.
`merchant_refund_no`	string	One of two	Your refund number.

{
  "merchant_refund_no": "MR202606240001"
}

Field	Type	Description
`refund_no`	string	StablePay refund number.
`merchant_refund_no`	string	Your refund number.
`original_order_no`	string	Original StablePay order number.
`original_merchant_order_no`	string	Original merchant order number.
`status`	string	`PENDING`, `SUCCESS` or `FAILED`.
`refund_amount`	object	`currency` and `value`.
`reason`	string	Refund reason.
`psp_refund_no`	string	StablePay processing reference.
`created_at`	string	Creation time.
`updated_at`	string	Last update time.

200 · response

{
  "code": 0,
  "msg": "success",
  "data": {
    "refund_no": "R202606240001",
    "merchant_refund_no": "MR202606240001",
    "original_order_no": "O202606240001",
    "original_merchant_order_no": "M202606240001",
    "status": "SUCCESS",
    "refund_amount": {
      "currency": "USD",
      "value": "10.00"
    },
    "reason": "customer requested",
    "psp_refund_no": "SPR_R_001",
    "created_at": "2026-06-24T11:00:00Z",
    "updated_at": "2026-06-24T11:00:05Z"
  }
}