Refunds

Refunds

One read-only endpoint covers the refunds domain:

• List Refunds — page through the refunds issued against your payin orders.

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.

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, or limit outside 1–100).
90001	Unauthorized	Authentication failed or merchant identity is missing.
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.