> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spacepay.solutions/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Withdrawal

> Retrieve withdrawal details and current status

# Get Withdrawal

Retrieve full withdrawal details by ID, including status, recipient address, chain, and optional receipt (populated once the withdrawal is settled on-chain).

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET \
  "https://api.spacepay.solutions/v1/external/secretkey-auth/withdrawals/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  \ -H "X-SpacePay-Secret-Key: sk_test_your_secret_key"
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response (200) theme={null}
  {
    "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"
  }
  ```
</ResponseExample>

## Path Parameters

<ParamField path="withdrawalId" type="string" required>
  Unique identifier of the withdrawal to retrieve.
</ParamField>

## Response Fields

<ResponseField name="id" type="string" required>
  Unique withdrawal identifier.
</ResponseField>

<ResponseField name="merchantId" type="string" required>
  ID of the merchant who created the withdrawal.
</ResponseField>

<ResponseField name="amountInCents" type="number" required>
  Withdrawal amount in USD cents.
</ResponseField>

<ResponseField name="chainId" type="number" required>
  EVM chain ID used for settlement.
</ResponseField>

<ResponseField name="recipientAddress" type="string" required>
  Beneficiary wallet address that receives the funds.
</ResponseField>

<ResponseField name="status" type="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
</ResponseField>

<ResponseField name="currency" type="string" required>
  Withdrawal currency (`USD`).
</ResponseField>

<ResponseField name="orderId" type="string">
  Merchant's order or reference identifier.
</ResponseField>

<ResponseField name="customMetadata" type="string">
  Arbitrary metadata attached to the withdrawal as a JSON string.
</ResponseField>

<ResponseField name="errorMessage" type="string">
  Human-readable error description. Only present when `status` is `failed`.
</ResponseField>

<ResponseField name="receipt" type="object">
  On-chain settlement details. Only present for `completed` withdrawals.

  <Expandable title="Receipt properties">
    <ResponseField name="settledToken" type="object">
      Token used to settle the withdrawal (symbol, decimals, contract address, chain).
    </ResponseField>

    <ResponseField name="settledChain" type="object">
      Chain on which the withdrawal was settled.
    </ResponseField>

    <ResponseField name="settledAmountAsset" type="string">
      Amount sent in the token's smallest unit.
    </ResponseField>

    <ResponseField name="settledAmountUsd" type="string">
      USD value of the settled amount.
    </ResponseField>

    <ResponseField name="txHash" type="string">
      Blockchain transaction hash.
    </ResponseField>

    <ResponseField name="txBlockNumber" type="integer">
      Block number where the transaction was confirmed.
    </ResponseField>

    <ResponseField name="txTimestamp" type="string">
      Timestamp of the on-chain transaction.
    </ResponseField>

    <ResponseField name="txSenderAddress" type="string">
      Address that sent the on-chain transaction.
    </ResponseField>

    <ResponseField name="txGasUsed" type="integer">
      Gas units consumed by the transaction.
    </ResponseField>

    <ResponseField name="txTotalCost" type="string">
      Total gas cost in the native token's smallest unit.
    </ResponseField>

    <ResponseField name="txTotalCostUsdFractions" type="number">
      Total gas cost in USD, with 6 decimal places of precision.
    </ResponseField>

    <ResponseField name="txIsSponsored" type="boolean">
      Whether the transaction gas was sponsored by SpacePay.
    </ResponseField>

    <ResponseField name="processedBy" type="string">
      Internal processor that submitted the transaction (`webhook`, `frontend`,
      `cron`, or `manual`).
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      Timestamp when the receipt record was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="createdAt" type="string" required>
  Timestamp when the withdrawal was created.
</ResponseField>

<ResponseField name="updatedAt" type="string" required>
  Timestamp when the withdrawal was last updated.
</ResponseField>

## Error Responses

<ResponseExample>
  ```json Error Response (401) theme={null}
  {
    "error": {
      "type": "authentication_error",
      "message": "Invalid or missing X-SpacePay-Secret-Key header",
      "code": "invalid_api_key"
    }
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json Error Response (404) theme={null}
  {
    "error": {
      "type": "not_found_error",
      "message": "Withdrawal not found",
      "code": "withdrawal_not_found"
    }
  }
  ```
</ResponseExample>