Skip to main content
POST
/
v1
/
payments
Create a new payment
curl --request POST \
  --url https://api.pay.walletconnect.com/v1/payments \
  --header 'Api-Key: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Merchant-Id: <merchant-id>' \
  --data '
{
  "amount": {
    "unit": "iso4217/USD",
    "value": "100"
  },
  "checkout": null,
  "expiresAt": null,
  "referenceId": "ORDER-123"
}
'
{
  "expiresAt": 1718236800,
  "gatewayUrl": "https://api.pay.walletconnect.com/pay_123",
  "isFinal": false,
  "paymentId": "pay_6ea2ecc101KMNV56BF1FXA71QKXJVHTJ4T",
  "pollInMs": 1000,
  "status": "requires_action"
}

Authorizations

​
Api-Key
string
header
required

Headers

​
Api-Key
string
required
​
Merchant-Id
string
required
​
WCP-Version
string | null
​
Sdk-Name
string | null
​
Sdk-Version
string | null
​
Sdk-Platform
string | null
​
Idempotency-Key
string | null

Body

application/json
​
amount
object
required

Amount to be paid

Example:
{ "unit": "iso4217/USD", "value": "100" }
​
referenceId
string
required

Merchant/PSP order ID

​
checkout
object
Example:
{
  "errorUrl": "https://example.com/error",
  "successUrl": "https://example.com/success"
}
​
expiresAt
integer<int64> | null

Optional custom expiration timestamp (Unix seconds since epoch). Must be in the future if provided. If not provided, defaults to 5 minutes from now.

Response

Payment created successfully

​
expiresAt
integer<int64>
required

Payment expiration timestamp, in seconds since epoch

Required range: x >= 0
​
gatewayUrl
string
required

Gateway URL to redirect the user to for payment

​
isFinal
boolean
required

True if the payment is in a final state and no longer requires polling

​
paymentId
string
required

Payment ID

Example:

"pay_7fa2ecc101ARZ3NDEKTSV4RRFFQ69G5FAV"

​
status
enum<string>
required

Payment status

Available options:
requires_action,
processing,
succeeded,
failed,
expired,
cancelled
​
pollInMs
integer<int64> | null

Time to poll for payment status, in milliseconds. Not present if the payment is in a final state.

Required range: x >= 0