Skip to main content

Quickstart

Quickstart​

This guide takes you from zero to a working payment: get credentials, sign your first request, create a Payment Link, and receive an order webhook. For the full picture of what the API offers, see the Overview.

Prerequisites​

  • An APIKey / APISecret pair. Apply at account.morph.network.
  • At least one receiving wallet configured under your merchant account and bound to the chain you want to settle into.
  • The ability to send a signed HTTPS request (any language).

Step 1 — Know the basics​

All requests go to a single production gateway:

https://pay-openapi.morph.network

Every response uses one common envelope. Determine success from error_code (error_code == 0), not from the HTTP status alone:

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

Step 2 — Pick a receiving chain and token​

The receiving_network / receiving_token_symbol / receiving_token_address you send must come from the supported list. Either read them live from the Receiving currencies endpoint, or copy a row from Supported Tokens & Networks.

For this guide we use USDT on Morph:

FieldValue
receiving_networkmorph
receiving_token_symbolUSDT
receiving_token_address0xe7cd86e13ac4309349f30b3435a9d337750fc82d

Step 3 — Sign the request​

Each request is signed with HMAC-SHA256 and carries these headers: x-api-key, x-api-timestamp (Unix milliseconds), x-api-signature, and Content-Type: application/json. See Authentication for the exact signing scheme and Go / Node.js examples.

caution

The body you sign must be byte-for-byte identical to the body you send: decide the body text first, sign it, then send that same text.

Step 4 — Create a Payment Link​

Send a POST to /pro/merchant/payin/v1/payment-links. The receiving_address must be a wallet you configured at account.morph.network and bound to receiving_network.

curl -X POST 'https://pay-openapi.morph.network/pro/merchant/payin/v1/payment-links' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: <APIKey>' \
  -H 'x-api-timestamp: 1782777600000' \
  -H 'x-api-signature: <base64 signature>' \
  -d '{
    "amount": "100.00",
    "receiving_network": "morph",
    "receiving_token_symbol": "USDT",
    "receiving_token_address": "0xe7cd86e13ac4309349f30b3435a9d337750fc82d",
    "receiving_address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "description": "July subscription",
    "support_networks": ["morph"],
    "support_tokens": [
      { "network": "morph", "address": "0xe7cd86e13ac4309349f30b3435a9d337750fc82d", "symbol": "USDT" }
    ]
  }'

A successful response returns the checkout URL to share with your customer:

{
  "error_code": 0,
  "msg": "success",
  "data": {
    "payin_id": "plink_01HXXX",
    "payment_link_url": "https://pay.example.com/paylink/eyJ...",
    "status": "ACTIVE"
  },
  "trace": "..."
}
note

Do not send merchant_id — the gateway resolves your merchant identity from the API Key and ignores it if present. Need invoice fields like payer, due_date, or line items? Use Create Invoice instead.

Step 5 — Share the checkout​

Send payment_link_url to your customer. They complete payment on the Hosted Checkout page using any supported paying currency. Morph watches the chain and finalizes the order.

Step 6 — Receive the order webhook​

Register a webhook URL for your merchant account. When the order settles, Morph sends a signed POST with the order status (success, failed, or expired):

{
  "event_id": "evt_9f2c1a7b3d",
  "platform_order_id": "ord_20260715_0001",
  "payee_order_id": "your-order-42",
  "status": "success",
  "amount": "100.000000",
  "pay_token": "USDT",
  "pay_network": "morph",
  "tx_hash": "0xabc123...",
  "paid_at": 1752566400000
}

Always verify the signature before trusting a payload, respond with a 2xx quickly, and treat event_id as the idempotency key. See the full Events Reference for every field and the retry schedule.

Next steps​