Withdrawal Flow

Overview

The withdrawal flow allows you to send funds from your merchant wallet to customer bank accounts. This is ideal for disbursements, refunds, commission payments, vendor payouts, and any scenario where you need to transfer money to customers or partners.

Flow Diagram

How It Works

Step 1: User Initiates Withdrawal Request

The customer visits your merchant site and requests a withdrawal (e.g., refund request, payout request, commission withdrawal).

Step 2: Merchant Server Receives Request

Your merchant site captures the withdrawal request from the user and sends it to your backend server for processing.

Step 3: Merchant Server Calls Payout API

Your backend server calls the Waypay /Payment/withdraw endpoint with:

Withdrawal amount
Customer’s bank account details (IBAN or account number)
Customer’s bank name
Customer’s full name and CNIC
Withdrawal description and reference

curl --request POST \
  --url https://waypay-merchant-api.icydesert-41d42f7e.uaenorth.azurecontainerapps.io/Gateway/v1/Payment/withdraw \
  --header 'SWICH-API-Key: pk_test_xxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 5000,
    "description": "Refund Payment",
    "cnic": "4210112345678",
    "customerAccountNumber": "PK36SCBL0000001123456702",
    "customerBankName": "Standard Chartered Bank",
    "customerFullName": "Ahmed Ali",
    "customerEmail": "ahmed@example.com",
    "billReference": "REF-2025-001",
    "autoProcessPayout": true,
    "currency": "PKR",
    "customerRef": {
      "name": "Ahmed Ali",
      "email": "ahmed@example.com",
      "cnic": "4210112345678",
      "phone": "03001234567"
    },
    "orderRef": {
      "orderRef": "WD123456"
    }
  }'

Step 4: WayPay Creates Order and Calls Payment Service Provider

WayPay processes your withdrawal request and communicates with the Payment Service Provider (bank) to initiate the fund transfer.

Step 5: Payment Service Provider Confirms Transaction

The Payment Service Provider:

Validates the bank account details
Checks account holder name against CNIC
Initiates the bank transfer
Returns confirmation (indicated by dotted line showing async confirmation)

Step 6: Transaction Reference Returned

WayPay returns a transaction reference to your merchant server:

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

Step 7: Merchant Provides Reference to User

Your site displays the transaction reference to the customer, allowing them to track the withdrawal status.

Fee Structure

Important: A transaction fee is added to the withdrawal amount and deducted from your merchant balance.

How Fees Work

When processing a withdrawal:

Withdrawal amount: Amount to send to customer (e.g., PKR 5,000)
Transaction fee added: Based on your merchant rate (e.g., PKR 150)
Deducted from balance: Amount plus fee (e.g., PKR 5,150)
Customer receives: Full withdrawal amount (e.g., PKR 5,000)

Example Calculation:

Withdrawal Amount:       PKR 5,000
Transaction Fee:         PKR 150 (3%)
Total Deduction:         PKR 5,150
─────────────────────────────────
Amount Deducted from 
Merchant Balance:        PKR 5,150

Customer Receives:       PKR 5,000

Fee Breakdown

The transaction fee covers:

Bank transfer charges
Platform processing fee
Payment service provider costs
Interbank transfer fees

Fee rates vary based on:

Your merchant agreement
Transaction volume
Destination bank
Transfer type (instant/standard)

Check your merchant dashboard for your specific fee structure.

Balance Check Before Withdrawal

Always ensure you have sufficient balance to cover both the withdrawal amount and the fee:

// Check balance before initiating withdrawal
const balanceResponse = await fetch(
  'https://waypay-merchant-api.icydesert-41d42f7e.uaenorth.azurecontainerapps.io/Gateway/v1/Account/query-balance',
  {
    method: 'POST',
    headers: {
      'SWICH-API-Key': process.env.WAYPAY_API_KEY
    }
  }
);

const balance = await balanceResponse.json();
const withdrawalAmount = 5000;
const estimatedFee = withdrawalAmount * 0.03; // 3% example rate
const totalRequired = withdrawalAmount + estimatedFee;

if (balance.availableBalance >= totalRequired) {
  // Proceed with withdrawal
} else {
  // Insufficient balance
  console.log('Insufficient balance. Need:', totalRequired, 'Have:', balance.availableBalance);
}

Processing Modes

Auto Process Payout

When autoProcessPayout is set to true:

✅ Withdrawal is processed immediately
✅ No manual approval required
✅ Ideal for automated systems
✅ Best for trusted transactions
⚠️ Ensure sufficient balance including fees

Manual Approval

When autoProcessPayout is set to false (default):

⏳ Withdrawal requires manual approval
🔒 Additional security layer
👥 Suitable for high-value transactions
📊 Allows review before processing

Processing Time

Withdrawal processing times vary by bank and amount:

Processing Type	Timeframe	Use Case
Instant	Real-time	Some banks support instant transfers
Same Day	2-4 hours	Most local banks during business hours
Next Day	24 hours	High-value transactions or after business hours
2-3 Days	48-72 hours	International transfers or special cases

The estimatedCompletionTime field in the response provides the expected completion timestamp based on the specific transaction.

Bank Account Validation

Supported Account Formats

IBAN: PK36SCBL0000001123456702
Account Number: 0123456789012345

Validation Requirements

Account Holder Name

Must match the name associated with the bank account. Minor variations are acceptable (e.g., “Muhammad Ali” vs “M Ali”).

CNIC Verification

The CNIC provided must match the account holder’s CNIC registered with the bank.

Bank Name

Must be the exact name of the bank. Use standard bank names (e.g., “Habib Bank Limited”, “MCB Bank”, “Standard Chartered Bank”).

Account Status

The destination bank account must be active and able to receive funds.

Best Practices

Verify Bank Details

Always verify bank account details before processing withdrawals to prevent failed transactions

Check Balance + Fees

Ensure sufficient balance for withdrawal amount PLUS transaction fees before initiating

Set Up Webhooks

Configure webhooks to receive real-time updates on withdrawal status changes

Store References

Save paymentIntentId and transactionReference for reconciliation and support

Reconciliation

When reconciling withdrawals, use the Transaction API to get detailed fee information:

{
  "id": "880e8400-e29b-41d4-a716-446655440000",
  "amount": 5000.00,
  "currency": "PKR",
  "fee": 150.00,
  "netAmount": 5150.00,
  "txType": "Withdrawal",
  "status": "Completed",
  "createdAtUtc": "2025-12-13T10:30:00Z"
}

Note: For withdrawals, netAmount represents the total deducted from your balance (withdrawal amount + fee).

Error Handling

Common errors and solutions:

Error	Cause	Solution
Invalid account number	Incorrect format or non-existent	Validate format and verify with customer
Insufficient balance	Merchant wallet balance too low (including fees)	Add funds to wallet before retry
Account holder mismatch	Name doesn’t match bank records	Verify exact name spelling with customer
Bank account inactive	Account closed or frozen	Request alternative account from customer
CNIC mismatch	CNIC doesn’t match account	Verify CNIC number with customer

Webhook Events

You’ll receive webhook notifications for these events:

withdrawal.created - Withdrawal order created
withdrawal.processing - Bank transfer initiated
withdrawal.completed - Funds successfully transferred (includes fee details)
withdrawal.failed - Transfer failed (with reason)
withdrawal.cancelled - Withdrawal cancelled

Security Considerations

Important Security Measures

Always validate withdrawal requests on your server
Implement daily/monthly withdrawal limits
Use autoProcessPayout: false for amounts above your threshold
Maintain audit logs of all withdrawal requests
Verify customer identity for high-value withdrawals
Account for fees in your withdrawal limits

Compliance Requirements

For Pakistani banks, ensure:

✅ Valid CNIC provided (13 digits without dashes)
✅ Account holder name matches CNIC records
✅ Bank account is registered in Pakistan
✅ Transaction purpose is documented
✅ AML/KYC requirements met for large transactions

Next Steps

Withdrawal API Reference

View complete API documentation

Webhook Setup

Configure webhook notifications

Balance Check

Query your wallet balance

Fee Structure

Understand transaction fees

Getting started

Core Business Processes

Overview

Flow Diagram

How It Works

Step 1: User Initiates Withdrawal Request

Step 2: Merchant Server Receives Request

Step 3: Merchant Server Calls Payout API

Step 4: WayPay Creates Order and Calls Payment Service Provider

Step 5: Payment Service Provider Confirms Transaction

Step 6: Transaction Reference Returned

Step 7: Merchant Provides Reference to User

Fee Structure

How Fees Work

Fee Breakdown

Balance Check Before Withdrawal

Processing Modes

Auto Process Payout

Manual Approval

Processing Time

Bank Account Validation

Supported Account Formats

Validation Requirements

Best Practices

Verify Bank Details

Check Balance + Fees

Set Up Webhooks

Store References

Reconciliation

Error Handling

Webhook Events

Security Considerations

Compliance Requirements

Next Steps

Withdrawal API Reference

Webhook Setup

Balance Check

Fee Structure

Getting started

Core Business Processes

​Overview

​Flow Diagram

​How It Works

​Step 1: User Initiates Withdrawal Request

​Step 2: Merchant Server Receives Request

​Step 3: Merchant Server Calls Payout API

​Step 4: WayPay Creates Order and Calls Payment Service Provider

​Step 5: Payment Service Provider Confirms Transaction

​Step 6: Transaction Reference Returned

​Step 7: Merchant Provides Reference to User

​Fee Structure

​How Fees Work

​Fee Breakdown

​Balance Check Before Withdrawal

​Processing Modes

​Auto Process Payout

​Manual Approval

​Processing Time

​Bank Account Validation

​Supported Account Formats

​Validation Requirements

​Best Practices

Verify Bank Details

Check Balance + Fees

Set Up Webhooks

Store References

​Reconciliation

​Error Handling

​Webhook Events

​Security Considerations

​Compliance Requirements

​Next Steps

Withdrawal API Reference

Webhook Setup

Balance Check

Fee Structure

Overview

Flow Diagram

How It Works

Step 1: User Initiates Withdrawal Request

Step 2: Merchant Server Receives Request

Step 3: Merchant Server Calls Payout API

Step 4: WayPay Creates Order and Calls Payment Service Provider

Step 5: Payment Service Provider Confirms Transaction

Step 6: Transaction Reference Returned

Step 7: Merchant Provides Reference to User

Fee Structure

How Fees Work

Fee Breakdown

Balance Check Before Withdrawal

Processing Modes

Auto Process Payout

Manual Approval

Processing Time

Bank Account Validation

Supported Account Formats

Validation Requirements

Best Practices

Reconciliation

Error Handling

Webhook Events

Security Considerations

Compliance Requirements

Next Steps