Orders

Orders

Two read-only endpoints cover the orders domain:

• List Orders — page through the payin orders (Payment Link and Invoice payments) created by your merchant account.
• Get Order — fetch the full detail of a single order by its platform_order_id or your own reference_id.

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/payin/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 Orders

GET /orders

Returns your payin orders in reverse-chronological order by default, with cursor-based pagination.

Query parameters

Parameter	Type	Required	Description
status	string	No	Filter by order status. One of pending, success, expired, failed.
source_type	string	No	Filter by the source that created the order. One of PAYMENT_LINK, INVOICE.
source_id	string	No	Filter by the id of the source above (e.g. a specific payment link id). Max 64 characters.
start	string	No	Range start, Unix milliseconds or RFC3339. Max 32 characters.
end	string	No	Range end, Unix milliseconds or RFC3339. Max 32 characters.
sort_by	string	No	Sort field. One of created_at (default), paid_at, amount.
order	string	No	Sort direction. One of asc, desc (default).
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.

Request example

GET /pro/merchant/payin/v1/orders?status=success&limit=20

Success response

{
  "error_code": 0,
  "msg": "success",
  "data": {
    "items": [
      {
        "platform_order_id": "ord_...",
        "amount": "1.00000000",
        "status": "success",
        "pay_network": "matic",
        "pay_token": "USDT",
        "receiving_network": "morph",
        "receiving_token_symbol": "USDT",
        "receiving_address": "0xabc1...def0",
        "payment_txn_id": "P29240812885523456",
        "tx_hash": "0x...",
        "source_type": "PAYMENT_LINK",
        "source_id": "plink_...",
        "refund_status": "unrefunded",
        "created_at": 1784717583460,
        "paid_at": 1784717600000
      }
    ],
    "next_cursor": "eyJ0Ijoib3JkZXIiLCJzIjoi..."
  },
  "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 order detail fields; treat the order record itself as the source of truth for those.

Get Order

GET /orders/detail

Returns the full detail of a single order. The response shape is identical to a List Orders items[] entry (same fields, no next_cursor).

Query parameters

Parameter	Type	Required	Description
platform_order_id	string	One of platform_order_id / reference_id	The order id returned by List Orders or when the order was created.
reference_id	string	One of platform_order_id / reference_id	Your own business reference, as set on invoice/payment link creation. Scoped to your merchant account — you cannot use it to look up another merchant's order.

You must pass at least one of platform_order_id or reference_id. Omitting both is rejected with error_code: 90000. If you pass both, platform_order_id takes precedence.

Request example

GET /pro/merchant/payin/v1/orders/detail?platform_order_id=ord_...

Or, looking up the same order by your own reference:

GET /pro/merchant/payin/v1/orders/detail?reference_id=your-ref-...

Success response

{
  "error_code": 0,
  "msg": "success",
  "data": {
    "platform_order_id": "ord_...",
    "amount": "1.00000000",
    "status": "success",
    "pay_network": "matic",
    "pay_token": "USDT",
    "receiving_network": "morph",
    "receiving_token_symbol": "USDT",
    "receiving_address": "0xabc1...def0",
    "payment_txn_id": "P29240812885523456",
    "tx_hash": "0x...",
    "source_type": "PAYMENT_LINK",
    "source_id": "plink_...",
    "refund_status": "unrefunded",
    "created_at": 1784717583460,
    "paid_at": 1784717600000
  },
  "trace": "..."
}

Errors

error_code	Meaning	Description
0	Success	—
90000	Invalid parameters	A query parameter is out of its allowed enum/range (e.g. status=bogus, limit=500), or neither platform_order_id nor reference_id is provided on Get Order.
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.