Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.iterapay.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Withdrawals let you move funds from your IteraPay merchant balance to an external crypto wallet address. Before creating a withdrawal, you should verify that you have sufficient funds, understand any applicable fees, and confirm that your withdrawal amount meets the minimum threshold. This guide walks you through each step.

​
Prerequisites

  • A funded merchant balance (see Collect Funds)
  • The destination wallet address
  • The payment method ID for the network you’re withdrawing on
  • Your merchantID and a valid API key or JWT bearer token

​
Withdrawal flow

1

Check your available balance

Before creating a withdrawal, confirm that you have enough funds in your merchant balance.
curl --request GET \
  --url 'https://api.iterapay.com/merchants/{merchantID}/funds' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN'
Expected response:
{
  "balances": [
    {
      "methodID": "method_usdt_tron",
      "available": "346.500000",
      "pending": "0.000000",
      "currency": "USDT"
    }
  ]
}
Use the available field. Funds that are still pending (e.g., in an active collection) cannot yet be withdrawn.
2

Check withdrawal limits

Retrieve the minimum and maximum withdrawal limits for your account. Submitting a withdrawal below the minimum will be rejected.
curl --request GET \
  --url 'https://api.iterapay.com/merchants/{merchantID}/limits' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN'
Expected response:
{
  "withdrawal": {
    "minimum": "10.000000",
    "maximum": "100000.000000",
    "currency": "USD"
  }
}
3

Preview withdrawal fees

Check the fee that will be applied to your withdrawal before submitting. This lets you calculate the exact net amount that will arrive at the destination.
curl --request GET \
  --url 'https://api.iterapay.com/merchants/{merchantID}/fees?type=withdrawal' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN'
Expected response:
{
  "type": "withdrawal",
  "feePercentage": "1.00",
  "minimumFee": "0.500000",
  "currency": "USD"
}
Network (gas) fees may apply in addition to the IteraPay withdrawal fee, depending on the blockchain you’re withdrawing on. These are reflected in the final transaction.
4

Create the withdrawal

Submit the withdrawal order with the destination address, amount, and payment method ID.
curl --request POST \
  --url 'https://api.iterapay.com/merchants/{merchantID}/withdrawals' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "address": "TRX9xKqP2mNvLwXbY3zJdR7oU5cH1sA4fE",
    "amount": "200.000000",
    "methodID": "method_usdt_tron"
  }'
Expected response:
{
  "id": "wdr_d4e5f6a7-b8c9-0123-defa-234567890123",
  "address": "TRX9xKqP2mNvLwXbY3zJdR7oU5cH1sA4fE",
  "amount": "200.000000",
  "fee": "2.000000",
  "net": "198.000000",
  "status": "pending",
  "createdAt": "2024-01-01T15:00:00Z"
}
Save the id to track the withdrawal status.
5

Monitor withdrawal status

Check the status of a specific withdrawal using its ID.
curl --request GET \
  --url 'https://api.iterapay.com/merchants/{merchantID}/withdrawals/{withdrawalID}' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN'
Expected response:
{
  "id": "wdr_d4e5f6a7-b8c9-0123-defa-234567890123",
  "status": "completed",
  "txHash": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef12345678",
  "completedAt": "2024-01-01T15:08:42Z"
}
Possible status values are pending, processing, and completed. A txHash is included once the on-chain transaction is broadcast.

​
View pending withdrawals

To see all withdrawals that haven’t completed yet, use the pending withdrawals endpoint: 
curl --request GET \
  --url 'https://api.iterapay.com/merchants/{merchantID}/withdrawals/pending' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN'
Expected response: 
{
  "withdrawals": [
    {
      "id": "wdr_d4e5f6a7-b8c9-0123-defa-234567890123",
      "address": "TRX9xKqP2mNvLwXbY3zJdR7oU5cH1sA4fE",
      "amount": "200.000000",
      "status": "processing",
      "createdAt": "2024-01-01T15:00:00Z"
    }
  ]
}
Do not submit duplicate withdrawal requests while a withdrawal is still pending or processing. Check the pending withdrawals list before creating a new one.

​
Next steps

To receive automatic notifications when withdrawals complete or when payments arrive, configure a webhook endpoint. See Webhooks for setup instructions.