HansaPay
Products
Developers
Resources
Company
Open an accountSign in
DocsRefunds

API reference

中文

Refunds

Refund a payment and query a refund. Card refunds are full refunds, and are reviewed before they complete.

Create Refund

POST/api/v1/refunds/create

Request fields

FieldTypeRequiredDescription
original_order_nostringOne of twoHansaPay original order number
original_merchant_order_nostringOne of twoMerchant original order number
merchant_refund_nostringYesMerchant refund order number, max 64 characters
refund_amountstringYesRefund amount, in the original order's currency
reasonstringNoRefund reason
notify_urlstringNoRefund notification URL. If omitted, no refund notification is sent
metadatastringNoMerchant passthrough field, returned in the refund notification

Notes:

  • Card, Apple Pay and Google Pay payments support one refund of the full amount only. A partial amount is rejected with This payment channel does not support partial refunds; only full refunds are allowed
  • These refunds start as PENDING and are reviewed before they complete; HansaPay checks them every few minutes and sends refund.updated when they finish. A refund the provider has no record of after 30 minutes becomes FAILED
  • Cash App refunds complete immediately and can be partial
  • The refund amount and the refund fee are held from your available balance while the refund is pending, and released if it fails. If the balance does not cover them, the refund is rejected
  • A rejected refund still uses up its merchant_refund_no; the refused refund is recorded as FAILED
  • Refund statuses: PENDING / SUCCESS / FAILED

Successful data

FieldTypeDescription
refund_nostringHansaPay refund number
merchant_refund_nostringMerchant refund number
original_order_nostringOriginal HansaPay order number
original_merchant_order_nostringOriginal merchant order number
statusstringRefund status
refund_amountobjectRefund amount
created_atstringCreation time

Full success response example

JSON
{
  "code": 0,
  "msg": "success",
  "data": {
    "refund_no": "R202406240001",
    "merchant_refund_no": "MR202406240001",
    "original_order_no": "O202406240001",
    "original_merchant_order_no": "M202406240001",
    "status": "PENDING",
    "refund_amount": {
      "currency": "USD",
      "value": "99.99"
    },
    "created_at": "2026-06-24T11:00:00+08:00"
  }
}

Query Refund

POST/api/v1/refunds/query

Request fields

FieldTypeRequiredDescription
refund_nostringOne of twoHansaPay refund number
merchant_refund_nostringOne of twoMerchant refund number

Successful data

FieldTypeDescription
refund_nostringHansaPay refund number
merchant_refund_nostringMerchant refund number
original_order_nostringOriginal HansaPay order number
original_merchant_order_nostringOriginal merchant order number
statusstringRefund status
refund_amountobjectRefund amount
reasonstringRefund reason
created_atstringCreation time
updated_atstringUpdate time

Full success response example

JSON
{
  "code": 0,
  "msg": "success",
  "data": {
    "refund_no": "R202406240001",
    "merchant_refund_no": "MR202406240001",
    "original_order_no": "O202406240001",
    "original_merchant_order_no": "M202406240001",
    "status": "SUCCESS",
    "refund_amount": {
      "currency": "USD",
      "value": "99.99"
    },
    "reason": "customer requested",
    "created_at": "2026-06-24T11:00:00+08:00",
    "updated_at": "2026-06-24T11:00:05+08:00"
  }
}