Withdraw Funds to an External Wallet

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

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.

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"
  }
}

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.

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.

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.

Get Started

Core Concepts

Guides

Withdraw Funds to an External Wallet

Prerequisites

Withdrawal flow

View pending withdrawals

Next steps

​Prerequisites

​Withdrawal flow

​View pending withdrawals

​Next steps

Prerequisites

Withdrawal flow

View pending withdrawals

Next steps