Create Withdrawal

HTTP Method: POST
Endpoint URL: /withdrawal
Description: Creates a new withdrawal request that requires approval before processing.
Security: Requires both API-KEY and X-HMAC headers.

Request Headers

Content-Type: application/json
API-KEY: your_account_api_key
X-HMAC: your_hmac_signature (calculated from all request body fields)

Request Body (JSON)

{
  "amount": "10",
  "asset": {
    "short": "USDT",
    "network": "tron"
  },
  "addressTo": "TPSMckmxoQBQWfUcasbUs2cRUdh2EMQu4n",
  "customer": {
    "id": 1,
    "name": "Customer Name",
    "email": "[email protected]"
  },
  "destTag": "",
  "invoice": "your-system-invoice-id"
}

Required Fields

amount (string) — Withdrawal amount as a decimal string with up to 8 decimal places
asset (object) — Cryptocurrency asset:
- short — Asset ticker symbol. Supported: USDT, USDC
- network — Blockchain network. Supported: tron, ethereum
addressTo (string) — Destination wallet address
customer (object) — Customer information:
- id — Your internal customer identifier (integer)
- name — Customer name
- email — Customer email address
destTag (string | null) — Destination tag/memo (pass empty string or null if not applicable)
invoice (string) — Your internal invoice/order ID for transaction tracking

Optional Fields

addressFrom (string) — Source wallet address for withdraw-direct mode. Must be provided together with clientId. See Withdraw-Direct section below.
clientId (string) — Client identifier for address ownership validation. Must be provided together with addressFrom. See Client ID documentation for details.
transferAll (boolean) — When true, withdraws the entire balance from the source address instead of the specified amount. Used with withdraw-direct mode.

Validation: addressFrom and clientId must both be provided together. Sending only one will return a 400 Bad Request error.

Supported Asset Combinations

USDT on tron
USDT on ethereum
USDC on ethereum

Example cURL

curl https://api.alppay.io/v2/withdrawal \
  -X POST \
  -H "Content-Type: application/json" \
  -H "API-KEY: ak_live_1234567890abcdef" \
  -H "X-HMAC: your_calculated_signature" \
  -d '{
    "amount": "10",
    "asset": {
      "short": "USDT",
      "network": "tron"
    },
    "addressTo": "TPSMckmxoQBQWfUcasbUs2cRUdh2EMQu4n",
    "customer": {
      "id": 1,
      "name": "Customer Name",
      "email": "[email protected]"
    },
    "destTag": "",
    "invoice": "your-system-invoice-id"
  }'

Successful Response (200 OK)

{
  "id": "5f5a8ced-5c6a-4038-9d73-662441242fd3",
  "txnId": "",
  "amount": "10",
  "receivedAmount": "0",
  "asset": {
    "short": "USDT",
    "name": "Tether",
    "logoUrl": "https://cryptologos.cc/logos/tether-usdt-logo.png",
    "network": "tron"
  },
  "addressFrom": "",
  "addressTo": "TPSMckmxoQBQWfUcasbUs2cRUdh2EMQu4n",
  "destTag": "",
  "status": "OPEN",
  "customer": {
    "id": 1,
    "name": "Customer Name",
    "email": "[email protected]"
  },
  "merchant": {
    "id": 1,
    "name": "TestMerchant",
    "email": "[email protected]",
    "siteUrl": "",
    "logoUrl": ""
  },
  "invoice": "your-system-invoice-id",
  "createdAt": "2025-08-07T09:08:58.780375195Z",
  "updatedAt": "2025-08-07T09:08:58.780375285Z",
  "timeToApprove": null
}

Response Field Descriptions

id — Unique UUID identifier of the withdrawal request
txnId — Transaction ID on blockchain (empty until processing)
amount — Requested withdrawal amount as decimal string
receivedAmount — Amount actually sent as decimal string (0 until processed)
asset — Asset details object including name and logo URL
addressFrom — Source address (empty until processing)
addressTo — Destination wallet address
destTag — Destination tag if applicable, otherwise null
status — Current status: OPEN, APPROVED, CANCELLED, or COMPLETE
customer — Customer information object
merchant — Merchant account details object
invoice — Your internal invoice ID
createdAt — ISO 8601 timestamp of withdrawal creation
updatedAt — ISO 8601 timestamp of last update
timeToApprove — ISO 8601 timestamp when withdrawal will be auto-approved by ALPPAY system (null if manual approval required)

Withdrawal Status Flow

OPEN - Initial status after creation, awaiting approval
APPROVED - Withdrawal approved (manually or automatically after timeToApprove)
COMPLETE - Withdrawal successfully processed on blockchain
CANCELLED - Withdrawal cancelled before processing

Important Notes

Approval Required: All withdrawals require approval before processing. This can happen:
- Manually through ALPPAY dashboard
- Automatically after the time specified in timeToApprove
HMAC Signature: The X-HMAC header must be calculated using ALL fields sent in the request body
Customer ID: The customer.id field should be your internal customer identifier to maintain linkage between your system and ALPPAY
Invoice Field: Use the invoice field to store your internal transaction reference. This helps recover transaction links if the withdrawal ID is lost
Webhooks: Status change notifications are sent automatically to your configured webhook URL. See the Withdrawal Webhooks documentation for details

Withdraw-Direct Mode

When you provide addressFrom and clientId together, the withdrawal operates in withdraw-direct mode — funds are sent directly from the specified deposit address rather than from the merchant's pooled balance.

Withdraw-Direct Request Example

{
  "amount": "10",
  "asset": {
    "short": "USDT",
    "network": "tron"
  },
  "addressTo": "TPSMckmxoQBQWfUcasbUs2cRUdh2EMQu4n",
  "addressFrom": "TXkFpL3HmzE9KPpXGWNXdCbNcDYYn73U4C",
  "clientId": "client-12345",
  "transferAll": true,
  "customer": {
    "id": 1,
    "name": "Customer Name",
    "email": "[email protected]"
  },
  "destTag": "",
  "invoice": "your-system-invoice-id"
}

Key Points

addressFrom must belong to the authenticated merchant and the specified clientId
If addressFrom does not match ownership, a 403 Forbidden error is returned
transferAll: true ignores the amount field and transfers the full address balance

Error Responses

400 Bad Request

Returned when request validation fails (invalid email, unsupported asset/network combination, etc.)

401 Unauthorized

Invalid or missing API-KEY header

403 Forbidden

Invalid HMAC signature

500 Internal Server Error

Server-side error occurred