Refunds

Refunds

Two read-only endpoints cover the refunds domain:

• List Refunds — page through the refunds issued against your payin orders.
• Get Refund Info — for one payin order, get the refundable/refunded amounts and the full history of refund attempts against it.

All requests must be authenticated with your API Key. The gateway resolves your merchant identity from the API Key, so you do not send merchant_id in the query — it is ignored if present.

Base URL

https://pay-openapi.morph.network/pro/merchant/payout/v1

Endpoint paths in this page are relative to that base URL.

Response envelope

Every response is wrapped in a common envelope:

{
  "error_code": 0,
  "msg": "success",
  "data": {},
  "trace": "..."
}

note

Business success or failure is determined by error_code (error_code == 0 means success), not by the HTTP status code alone. See the Error Codes reference for the full list.

List Refunds

GET /refunds

Returns your refund records in reverse-chronological order by default, with cursor-based pagination. Omit refund_status to return refunds in every status.

Query parameters

Parameter	Type	Required	Description
refund_status	string	No	One of pending, success, failed; omit to return all statuses.
start	string	No	Range start. Accepted but not yet effective downstream; reserved for forward compatibility. Max 32 characters.
end	string	No	Range end. Accepted but not yet effective downstream; reserved for forward compatibility. Max 32 characters.
sort_by	string	No	Sort field. Accepted but not yet effective downstream; reserved for forward compatibility. Max 32 characters.
order	string	No	Sort direction. One of asc, desc (default). Accepted but not yet effective downstream.
cursor	string	No	Pagination cursor; omit for the first page. Max 512 characters.
limit	integer	No	Page size. 1–100, default 20 when omitted.

note

Any value outside the ranges/enums above is rejected with error_code: 90000 before the request reaches order-service — you will not get a partial or best-effort match. start/end/sort_by are validated for shape but the downstream refund list does not yet filter/sort by them.

Request example

GET /pro/merchant/payout/v1/refunds?refund_status=success&limit=20

Success response

{
  "error_code": 0,
  "msg": "success",
  "data": {
    "items": [
      {
        "refund_id": "rfd_xxx",
        "platform_order_id": "ord_xxx",
        "refund_amount": "10.00",
        "payer_total_amount": "10.20",
        "service_fee": "0.20",
        "refund_from_network": "ETH",
        "refund_from_token_symbol": "USDT",
        "refund_to_network": "ETH",
        "refund_to_token_symbol": "USDT",
        "refund_tx_hash": "0x...",
        "status": "success",
        "created_at": 1780000000000,
        "updated_at": 1780000001000
      }
    ],
    "next_cursor": null
  },
  "trace": "..."
}

To fetch the next page, pass the returned next_cursor on the next request. An empty or missing next_cursor means there are no more results.

note

The fields shown above are the stable query-side fields. Each items[] entry may carry additional refund detail fields; treat the refund record itself as the source of truth for those. This list is not filterable by platform_order_id — if you need every refund attempt for one specific order, use Get Refund Info instead.

Get Refund Info

GET /refunds/info

Returns a per-order refund summary: the order's total amount, how much of it is still refundable, how much has already been refunded, and the full list of refund attempts (including ones that failed or are still in progress) — for one platform_order_id.

Query parameters

Parameter	Type	Required	Description
platform_order_id	string	Yes	The payin order id to look up refund info for.

Omitting platform_order_id is rejected with error_code: 90000.

Request example

GET /pro/merchant/payout/v1/refunds/info?platform_order_id=ord_f7d9152dc6624bb08e4844b5a7fae845

Success response

{
  "error_code": 0,
  "msg": "success",
  "data": {
    "platform_order_id": "ord_f7d9152dc6624bb08e4844b5a7fae845",
    "order_amount": "100.00",
    "refundable_amount": "90.00",
    "refunded_amount": "10.00",
    "refunds": [
      {
        "refund_id": "rfd_xxx",
        "status": "success",
        "refund_amount": "10.00",
        "cross_chain_fee": "0.00",
        "payer_total_amount": "10.20",
        "bgw_cashier_txn_id": "crt_01HXXX",
        "payout_network": "morph",
        "payout_token_symbol": "USDT",
        "payout_address": "0x65c17d0410e1a7c038ce7f44964174e8611b3631",
        "refund_network": "ETH",
        "refund_token_symbol": "USDT",
        "refund_to_address": "0x...",
        "tx_hash": "0x...",
        "created_at": 1780000000000,
        "updated_at": 1780000001000
      }
    ]
  },
  "trace": "..."
}

Response fields

Field	Type	Description
order_amount	string	The original order's total amount.
refundable_amount	string	Remaining amount that can still be refunded.
refunded_amount	string	Total amount already refunded (across all refunds[] entries in a terminal success state).
refunds[]	array	One entry per refund attempt against this order, in any status (success, refund_pending, failed, etc.).

note

If the order has never had a refund attempt, refunds is an empty array and refunded_amount is 0; this is not an error.

Errors

error_code	Meaning	Description
0	Success	—
90000	Invalid parameters	A query parameter is out of its allowed enum/range (e.g. refund_status, order, limit outside 1–100, or missing platform_order_id on Get Refund Info).
90001	Unauthorized	Authentication failed or merchant identity is missing.
90002	Forbidden	(Get Refund Info only) platform_order_id exists but does not belong to your merchant account.
90201	Order not found	(Get Refund Info only) No order matches platform_order_id.
80000 – 80099	System error	The service is temporarily unavailable or hit an internal error; treat as a retryable system error.

See the Error Codes reference for details.