Create a Payment Session

Create a payment session

post

Creates a payment session. ON_RAMP routes to MELD; OFF_RAMP is accepted in the contract but returns 501 in Phase 1. Country is mandatory; custom_wallet_address requires the merchant's allow_custom_external_wallet flag.

Body

application/json

Request to create a payment session (ON_RAMP today; OFF_RAMP returns 501)

amountstring · decimalOptional

Optional fiat amount.

countrystringRequired

ISO 3166-1 alpha-2 country code. REQUIRED — no default.

currency_idstring · uuidRequired

Target currency id.

custom_wallet_addressstringOptional

Self-custody destination. Only honoured when the merchant flag is on.

metadataobjectOptional

Free-form merchant metadata.

payment_typestring · enumRequired

ON_RAMP routes to MELD. OFF_RAMP is accepted but returns 501 in Phase 1.

Possible values:

redirect_urlstringOptional

URL the MELD widget redirects the user to on completion. Required for ON_RAMP; must start with http:// or https://.

session_referencestringOptional

Merchant's own id for this session; echoed back in webhooks.

user_reference_idstringOptional

Merchant's stable player id. Required unless custom_wallet_address is supplied.

Responses

200

Created payment session

application/json

A created payment session

correlation_keystringRequired

Server-generated key, also the provider's externalSessionId.

expires_atstring · date-time · nullableOptional

Link expiry. Null until a self-imposed TTL is introduced.

linkstringRequired

Provider-hosted URL the user is sent to.

403

Custom wallet not allowed for merchant

application/json

422

Validation error

application/json

501

Payment type not available in Phase 1

application/json

post/v1/user/payments

HTTPcURLJavaScriptPython

POST /v1/user/payments HTTP/1.1
Host: gateway.stage.pay.io
Content-Type: application/json
Accept: */*
Content-Length: 183

{
  "country": "US",
  "currency_id": "c872e749-fd56-533e-b01f-de87ae38e7f1",
  "payment_type": "ON_RAMP",
  "redirect_url": "https://example.com/deposit-complete",
  "user_reference_id": "hub_player_2"
}

{
  "correlation_key": "f47ac10b-58cc-4372-a567-0e02b2c3d479:order_9981",
  "expires_at": null,
  "link": "https://meld.io/session/abc123..."
}