Skip to main content

​
Get Withdrawal

Retrieve full withdrawal details by ID, including status, recipient address, chain, and optional receipt (populated once the withdrawal is settled on-chain). 
curl -X GET \
"https://api.spacepay.co.uk/v1/external/secretkey-auth/withdrawals/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
\ -H "X-SpacePay-Secret-Key: sk_test_your_secret_key"

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "merchantId": "4e29f55d-d6a8-42d7-8230-cb8efeded39e",
  "amountInCents": 5000,
  "chainId": 84532,
  "recipientAddress": "0xRecipientAddressHere",
  "status": "completed",
  "currency": "USD",
  "orderId": "order_123",
  "customMetadata": "{\"note\":\"payout for March\"}",
  "errorMessage": null,
  "receipt": {
    "withdrawalId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "settledToken": {
      "id": "f9d14525-367d-4e16-b247-8d4ed23f1413",
      "symbol": "ETH",
      "decimals": 18,
      "contractAddress": "0x0000000000000000000000000000000000000000",
      "type": "volatile",
      "assetType": "native",
      "status": "active"
    },
    "settledChain": {
      "chainId": 84532,
      "name": "Base Sepolia",
      "nativeSymbol": "ETH",
      "nativeDecimals": 18,
      "isEnabled": true
    },
    "settledAmountAsset": "1336164741602324",
    "settledAmountUsd": "50.00",
    "txHash": "0xda3be87732110de6c1354c83770aae630ede9ac308d9f7b399ecfba23d923384",
    "txBlockNumber": 18500000,
    "txTimestamp": "2025-10-10T21:50:00.000Z",
    "txSenderAddress": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
    "txGasUsed": 21000,
    "txTotalCost": "441000000000000",
    "txTotalCostUsdFractions": 118,
    "txIsSponsored": false,
    "processedBy": "cron",
    "createdAt": "2025-10-10T21:50:05.000Z"
  },
  "createdAt": "2025-10-10T21:44:06.733Z",
  "updatedAt": "2025-10-10T21:50:05.000Z"
}

​
Path Parameters

​
withdrawalId
string
required
Unique identifier of the withdrawal to retrieve.

​
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
Current withdrawal status. Possible values: - pending: Withdrawal created, waiting to be processed - processing: Withdrawal is being submitted on-chain
  • completed: Withdrawal confirmed and settled - failed: Withdrawal failed (see errorMessage) - cancelled: Withdrawal cancelled
​
currency
string
required
Withdrawal currency (USD).
​
orderId
string
Merchant’s order or reference identifier.
​
customMetadata
string
Arbitrary metadata attached to the withdrawal as a JSON string.
​
errorMessage
string
Human-readable error description. Only present when status is failed.
​
receipt
object
On-chain settlement details. Only present for completed withdrawals.
​
createdAt
string
required
Timestamp when the withdrawal was created.
​
updatedAt
string
required
Timestamp when the withdrawal was last updated.

​
Error Responses

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

{
  "error": {
    "type": "not_found_error",
    "message": "Withdrawal not found",
    "code": "withdrawal_not_found"
  }
}