Create a withdrawal session

curl --request POST \
  --url https://server.hypermid.io/v1/payments/withdrawal \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "orderId": "order_1029",
  "chain": 8453,
  "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "amount": "10000000",
  "recipient": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "destinations": [
    {
      "chain": "9270000000000000",
      "token": "<string>",
      "recipient": "<string>",
      "amount": "<string>",
      "minAmount": "<string>",
      "maxAmount": "<string>"
    }
  ],
  "metadata": {},
  "successUrl": "<string>",
  "cancelUrl": "<string>",
  "minAmount": "<string>",
  "maxAmount": "<string>",
  "expiresIn": 1800
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    orderId: 'order_1029',
    chain: 8453,
    token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
    amount: '10000000',
    recipient: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
    destinations: [
      {
        chain: '9270000000000000',
        token: '<string>',
        recipient: '<string>',
        amount: '<string>',
        minAmount: '<string>',
        maxAmount: '<string>'
      }
    ],
    metadata: {},
    successUrl: '<string>',
    cancelUrl: '<string>',
    minAmount: '<string>',
    maxAmount: '<string>',
    expiresIn: 1800
  })
};

fetch('https://server.hypermid.io/v1/payments/withdrawal', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://server.hypermid.io/v1/payments/withdrawal"

payload = {
    "orderId": "order_1029",
    "chain": 8453,
    "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "10000000",
    "recipient": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "destinations": [
        {
            "chain": "9270000000000000",
            "token": "<string>",
            "recipient": "<string>",
            "amount": "<string>",
            "minAmount": "<string>",
            "maxAmount": "<string>"
        }
    ],
    "metadata": {},
    "successUrl": "<string>",
    "cancelUrl": "<string>",
    "minAmount": "<string>",
    "maxAmount": "<string>",
    "expiresIn": 1800
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "code": "OK",
  "error": null,
  "data": {
    "id": "co_01JABC123",
    "url": "https://pay.hypermid.io/pay/co_01JABC123",
    "embedUrl": "https://pay.hypermid.io/embed?paymentId=co_01JABC123",
    "status": "created",
    "mode": "checkout",
    "expiresAt": "2023-11-07T05:31:56Z",
    "created": true
  }
}

{
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "code": "OK",
  "error": null,
  "data": {
    "id": "co_01JABC123",
    "url": "https://pay.hypermid.io/pay/co_01JABC123",
    "embedUrl": "https://pay.hypermid.io/embed?paymentId=co_01JABC123",
    "status": "created",
    "mode": "checkout",
    "expiresAt": "2023-11-07T05:31:56Z",
    "created": true
  }
}

{
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "code": "INVALID_PARAMS",
  "error": "orderId is required",
  "data": null
}

{
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "code": "INVALID_PARAMS",
  "error": "orderId is required",
  "data": null
}

{
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "code": "INVALID_PARAMS",
  "error": "orderId is required",
  "data": null
}

{
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "code": "INVALID_PARAMS",
  "error": "orderId is required",
  "data": null
}

{
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "code": "INVALID_PARAMS",
  "error": "orderId is required",
  "data": null
}

{
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "code": "INVALID_PARAMS",
  "error": "orderId is required",
  "data": null
}

POST

payments

withdrawal

Create a withdrawal session

curl --request POST \
  --url https://server.hypermid.io/v1/payments/withdrawal \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "orderId": "order_1029",
  "chain": 8453,
  "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "amount": "10000000",
  "recipient": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "destinations": [
    {
      "chain": "9270000000000000",
      "token": "<string>",
      "recipient": "<string>",
      "amount": "<string>",
      "minAmount": "<string>",
      "maxAmount": "<string>"
    }
  ],
  "metadata": {},
  "successUrl": "<string>",
  "cancelUrl": "<string>",
  "minAmount": "<string>",
  "maxAmount": "<string>",
  "expiresIn": 1800
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    orderId: 'order_1029',
    chain: 8453,
    token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
    amount: '10000000',
    recipient: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
    destinations: [
      {
        chain: '9270000000000000',
        token: '<string>',
        recipient: '<string>',
        amount: '<string>',
        minAmount: '<string>',
        maxAmount: '<string>'
      }
    ],
    metadata: {},
    successUrl: '<string>',
    cancelUrl: '<string>',
    minAmount: '<string>',
    maxAmount: '<string>',
    expiresIn: 1800
  })
};

fetch('https://server.hypermid.io/v1/payments/withdrawal', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://server.hypermid.io/v1/payments/withdrawal"

payload = {
    "orderId": "order_1029",
    "chain": 8453,
    "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "10000000",
    "recipient": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "destinations": [
        {
            "chain": "9270000000000000",
            "token": "<string>",
            "recipient": "<string>",
            "amount": "<string>",
            "minAmount": "<string>",
            "maxAmount": "<string>"
        }
    ],
    "metadata": {},
    "successUrl": "<string>",
    "cancelUrl": "<string>",
    "minAmount": "<string>",
    "maxAmount": "<string>",
    "expiresIn": 1800
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "code": "OK",
  "error": null,
  "data": {
    "id": "co_01JABC123",
    "url": "https://pay.hypermid.io/pay/co_01JABC123",
    "embedUrl": "https://pay.hypermid.io/embed?paymentId=co_01JABC123",
    "status": "created",
    "mode": "checkout",
    "expiresAt": "2023-11-07T05:31:56Z",
    "created": true
  }
}

{
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "code": "OK",
  "error": null,
  "data": {
    "id": "co_01JABC123",
    "url": "https://pay.hypermid.io/pay/co_01JABC123",
    "embedUrl": "https://pay.hypermid.io/embed?paymentId=co_01JABC123",
    "status": "created",
    "mode": "checkout",
    "expiresAt": "2023-11-07T05:31:56Z",
    "created": true
  }
}

{
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "code": "INVALID_PARAMS",
  "error": "orderId is required",
  "data": null
}

{
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "code": "INVALID_PARAMS",
  "error": "orderId is required",
  "data": null
}

{
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "code": "INVALID_PARAMS",
  "error": "orderId is required",
  "data": null
}

{
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "code": "INVALID_PARAMS",
  "error": "orderId is required",
  "data": null
}

{
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "code": "INVALID_PARAMS",
  "error": "orderId is required",
  "data": null
}

{
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "code": "INVALID_PARAMS",
  "error": "orderId is required",
  "data": null
}

Authorizations

Authorization

string

header

required

Secret partner API key (sk_live_… or sk_test_…). Required to create or manage payment sessions. Server-side only — it can move money, so it must never reach a browser bundle. The key's prefix also selects the environment: sk_test_ is confined to testnets.

Body

application/json

orderId

string

required

Your identifier for this payment, and the IDEMPOTENCY key. Creating twice with the same orderId returns the existing non-terminal session with a 200 instead of a 201, rather than charging the payer twice. Send one, and send the same one on retry.

Example:

"order_1029"

chain

number

Destination chain id — where the recipient is paid.

Example:

8453

token

string

Destination token address on chain.

Example:

"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"

amount

string

Amount in BASE UNITS, as a string (10 USDC at 6 decimals is "10000000"). A string because these exceed IEEE-754 safe range at 18 decimals. Omit for an OPEN amount — the payer names it — which is the normal shape for deposit and legal for withdrawal; a checkout almost always fixes it.

Example:

"10000000"

recipient

string

Address that receives the funds on the destination chain.

Example:

"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"

destinations

object[]

Alternative destinations offered to the payer. Mutually exclusive with top-level chain/token/recipient/amount/minAmount/maxAmount. One entry takes the legacy single-session path; two or more require payer selection.

Show child attributes

metadata

object

Arbitrary JSON echoed back on reads and webhooks. Never shown to the payer.

successUrl

string

Where to send the payer after a completed payment.

cancelUrl

string

Where to send the payer if they abandon the payment.

minAmount

string

Lower bound for an OPEN-amount session, base units. Ignored when amount is fixed.

maxAmount

string

Upper bound for an OPEN-amount session, base units. Ignored when amount is fixed.

expiresIn

number

Session lifetime in seconds. Defaults to the server's configured TTL.

Example:

1800

Response

Idempotent replay: the existing non-terminal session for the same partner and orderId.

traceId

string

required

W3C trace id of the request — correlate with logs/traces in SigNoz.

Example:

"4bf92f3577b34da6a3ce929d0e0e4736"

code

enum<string>

required

Domain error code. OK on success; non-OK values come with a non-null error.

Available options:

OK,

BAD_REQUEST,

UNAUTHORIZED,

FORBIDDEN,

NOT_FOUND,

CONFLICT,

RATE_LIMITED,

PAYLOAD_TOO_LARGE,

UNSUPPORTED_CHAIN,

INTERNAL_ERROR,

UPSTREAM_TIMEOUT,

UPSTREAM_ERROR,

SERVICE_UNAVAILABLE,

KILL_SWITCH_ACTIVE,

CIRCUIT_BREAKER_OPEN,

NO_QUOTE_AVAILABLE,

QUOTE_STALE,

SIMULATION_REVERTED,

INVALID_PARAMS,

AMOUNT_OUT_OF_BOUNDS,

PAYOUT_TOKEN_NOT_ALLOWED,

RECIPIENT_NOT_ALLOWLISTED,

PAYMENT_EXPIRED,

PAYMENT_NOT_FOUND,

NOT_CONFIGURED,

INSUFFICIENT_LIQUIDITY,

ROUTE_TEMPORARILY_UNAVAILABLE,

UNSUPPORTED_ROUTE,

OVER_DELIVERY_CAP

Example:

"OK"

error

string | null

required

Human-readable error message. null on success.

Example:

null

data

object

required

Endpoint-specific payload. null on error.

Show child attributes

Overview

Endpoints

Webhooks

Create a withdrawal session

Authorizations

Body

Response