Skip to main content

​
Create withdrawal

Creates a withdrawal for the merchant associated with your secret key. SpacePay converts the requested USD amount to crypto and sends it to the specified recipient address on the chosen chain.
Withdrawals must be enabled for your merchant account. If withdrawals are disabled, contact the SpacePay support team.
curl -X POST https://api.spacepay.co.uk/v1/external/secretkey-auth/withdrawals \
  -H "X-SpacePay-Secret-Key: sk_test_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amountInCents": 5000,
    "chainId": 84532,
    "recipientAddress": "0xRecipientAddressHere",
    "orderId": "order_123",
    "currency": "USD",
    "customMetadata": "{\"note\":\"payout for March\"}"
  }'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "merchantId": "4e29f55d-d6a8-42d7-8230-cb8efeded39e",
  "amountInCents": 5000,
  "chainId": 84532,
  "recipientAddress": "0xRecipientAddressHere",
  "status": "pending",
  "currency": "USD",
  "orderId": "order_123",
  "customMetadata": "{\"note\":\"payout for March\"}",
  "errorMessage": null,
  "receipt": null,
  "createdAt": "2025-10-10T21:44:06.733Z",
  "updatedAt": "2025-10-10T21:44:06.733Z"
}

​
Request Parameters

​
amountInCents
number
required
Withdrawal amount in cents (for example, 5000 = $50.00). Minimum: 100 cents, maximum: 100000000 cents.
​
chainId
number
required
EVM chain ID to settle the withdrawal on. Use your withdrawal config endpoint to get supported chain IDs.
​
recipientAddress
string
required
Beneficiary wallet address that will receive the funds.
​
orderId
string
Your order or reference ID for reconciliation. Maximum 255 characters.
​
currency
string
default:"USD"
Currency of the withdrawal amount. Supports USD.
​
customMetadata
string
Optional metadata as a JSON string. Maximum 2048 characters.

​
Response Fields

​
id
string
required
Unique withdrawal identifier.
​
merchantId
string
required
ID of the merchant who created the withdrawal.
​
amountInCents
number
required
Withdrawal amount in USD cents.
​
chainId
number
required
EVM chain ID used for settlement.
​
recipientAddress
string
required
Beneficiary wallet address that receives the funds.
​
status
string
required
Initial status will be pending. Possible values: pending, processing, completed, failed, cancelled.
​
currency
string
required
Withdrawal currency (USD).
​
orderId
string
Merchant’s order identifier, if provided.
​
customMetadata
string
Custom metadata string, if provided.
​
errorMessage
string
Error description. null on creation; populated if the withdrawal later fails.
​
receipt
object
On-chain settlement details. null on creation; populated once the withdrawal is completed.
​
createdAt
string
required
Timestamp when the withdrawal was created.
​
updatedAt
string
required
Timestamp when the withdrawal was last updated.

​
Error Responses

{
  "error": {
    "type": "invalid_request_error",
    "message": "The amount must be greater than 100 cents",
    "code": "invalid_amount",
    "param": "amountInCents"
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid or missing X-SpacePay-Secret-Key header",
    "code": "invalid_api_key"
  }
}