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)

All fields are required.

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

Field Descriptions

amount — Withdrawal amount as a decimal string with up to 8 decimal places. Minimum: 0, no maximum limit
asset.short — Asset ticker symbol. Supported values: USDT, USDC
asset.network — Blockchain network. Supported values: tron, ethereum
addressTo — Destination wallet address (currently no validation)
customer.id — Your internal customer identifier (integer) for linking with ALPPAY database
customer.name — Customer's name (no length restrictions)
customer.email — Valid email address of the customer
destTag — Destination tag/memo (pass empty string if not applicable)
invoice — Your internal invoice/order ID for transaction tracking

Supported Asset Combinations

USDT on tron
USDT on ethereum
USDC on tron
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

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