Create Withdrawal Order

​

Overview

​

Path Parameters

​

Request Body

​

Response

curl --request POST \
  --url https://gateway.dev.waypay.live/Gateway/v1/Payment/withdraw \
  --header 'SWICH-API-Key: pk_test_xxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 5000,
    "currency": "PKR",
    "description": "Freelancer Payment",
    "intentType": "withdrawal",
    "autoProcessPayout": true,
    "callbackUrl": "https://yoursite.com/withdrawal/callback",
    "customerRef": {
      "name": "Ahmed Ali",
      "email": "ahmed@example.com",
      "cnic": "3520108345678",
      "phone": "03123456789",
      "bankAccountNumber": "PK36SCBL0000001123456702",
      "bankCode": "SCB",
      "bankName": "Standard Chartered Bank",
      "accountTitle": "Ahmed Ali"
    },
    "orderRef": {
      "orderRef": "WD123456"
    },
    "signature": "a1b2c3d4e5f6789012345678abcdef12"
  }'

{
  "paymentIntentId": "880e8400-e29b-41d4-a716-446655440000",
  "amount": 5000,
  "currency": "PKR",
  "merchantReference": "WD123456",
  "isLive": false,
  "fee": 150.00,
  "totalRequired": 5150.00,
  "availableBalance": 10000.00,
  "payoutInfo": {
    "status": "Processing",
    "provider": "JazzCash",
    "transactionReference": "WD20251213123456",
    "message": "Payout initiated successfully",
    "isSuccess": true,
    "errorDetails": null,
    "estimatedCompletionTime": "2025-12-14T10:00:00Z",
    "customerBankName": "Standard Chartered Bank",
    "customerAccountNumber": "PK36SCBL0000001123456702"
  }
}

​

Validation Rules

​

CNIC Format (Optional)

• Must be exactly 13 digits when provided
• Pattern: ^\d{13}$
• Example: 3520108345678

​

Phone Number (Optional)

• No specific format required
• Recommended format for Pakistani numbers: 03XXXXXXXXX or +923XXXXXXXXX

​

Bank Account Number (Required)

• Length: 10-24 characters
• Supports both IBAN and regular account numbers
• Example IBAN: PK36SCBL0000001123456702

​

Bank Code (Required)

• Length: 2-20 characters
• Must be a valid standard bank code from the supported banks list
• Case-insensitive (will be automatically normalized)
• Examples: HBL, UBL, MCB, JAZZCASH, EASYPAISA, SCB
• See Bank Codes Reference for complete list

​

Bank Name (Optional)

• Length: 2-100 characters
• For informational/display purposes only
• The bankCode field is used for actual transaction processing
• Examples: Habib Bank Limited, United Bank Limited, Standard Chartered Bank

​

Account Title (Required)

• Length: 2-100 characters
• Must match the bank account holder’s name

​

Currency (Required)

• Must be exactly 3 characters
• Examples: PKR, USD, EUR

​

Description (Required)

• Length: 1-200 characters
• Pattern: ^[A-Za-z0-9 ]{1,200}$
• Only alphanumeric characters and spaces allowed

​

Required vs Optional Fields

​

Required Fields

• amount - Withdrawal amount
• currency - Payment currency (3 characters)
• description - Transaction description
• customerRef - Customer information object
• customerRef.bankAccountNumber - Bank account or IBAN
• customerRef.bankCode - Standard bank code for IBFT processing
• customerRef.accountTitle - Account holder name
• orderRef - Order information object
• orderRef.orderRef - Unique order reference
• signature - Request signature for security verification

​

Optional Fields

• intentType - Payment intent type
• autoProcessPayout - Auto-process flag (default: false)
• metadataJson - Additional metadata
• callbackUrl - Dynamic callback URL for post-payout redirect
• customerRef.name - Customer full name
• customerRef.email - Customer email
• customerRef.cnic - Customer CNIC
• customerRef.phone - Customer phone
• customerRef.bankName - Bank name (informational only)
• orderRef.discount - Discount information
• orderRef.tax - Tax information

​

Auto Process Payout

• Automated disbursement systems
• Real-time payouts
• High-volume withdrawal processing

​

Best Practices

• Always verify the customer’s bank account details before processing
• Use the correct standardized bankCode from the Bank Codes Reference section
• Ensure sufficient balance in your merchant wallet (including transaction fees)
• Use autoProcessPayout: false for high-value transactions that need review
• Monitor the payoutInfo.status to track withdrawal completion
• Store the paymentIntentId for future reference and reconciliation
• Provide name, email and phone when available for better customer communication
• Include CNIC for compliance and verification purposes when available
• Verify account title matches the bank account holder’s name
• Use metadataJson to store additional transaction context
• The bankName field is optional and informational only - use bankCode for processing

​

Processing Time

• Instant: Some banks support real-time transfers
• Same Day: Most local banks (2-4 hours)
• Next Day: For high-value transactions or certain banks

​

Common Error Scenarios

​

Bank Codes Reference

​

Major Banks

​

Islamic Banks

​

Foreign Banks

​

Public Sector Banks

​

Digital & Wallet Banks

​

Microfinance Banks

​

Other Banks

​

Financial Services

​

Non-Bank Financial Institutions

​

Special Codes

​

Security Considerations

• Never store sensitive bank account information in plain text
• Use HTTPS for all API communications
• Validate bank account details before processing withdrawals
• Implement rate limiting to prevent abuse
• Monitor for suspicious withdrawal patterns
• Keep API keys secure and rotate regularly
• Set up alerts for large withdrawal amounts
• Use autoProcessPayout: false for manual review of high-value transactions

​

Testing

• Name: Test User
• Email: test@example.com (optional)
• CNIC: 3520108345678 (optional)
• Phone: 03123456789 (optional)
• Bank Account: PK36SCBL0000001123456702
• Bank Code: SCB (required)
• Bank Name: Standard Chartered Bank (optional)
• Account Title: Test User

​

Next Steps