Create Withdrawal Order - Waypay API Documentation

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

POST

Gateway

{version}

Payment

withdraw

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

Overview

This endpoint creates a withdrawal order that processes a payout from your merchant wallet to a customer’s bank account. Use this for disbursements, refunds, commission payments, or any scenario where you need to send money to customers.

Path Parameters

version

string

required

API version (e.g., “1”)

Request Body

amount

number

required

Withdrawal amount (must be greater than 10)

currency

string

required

Payment currency - exactly 3 characters (e.g., “PKR”, “USD”)

description

string

required

Withdrawal description (1-200 alphanumeric characters and spaces only)Pattern: ^[A-Za-z0-9 ]{1,200}$

intentType

string

Payment intent type (e.g., “withdrawal”)

autoProcessPayout

boolean

Whether to automatically process the payout (default: false)

metadataJson

string

Optional JSON string containing additional metadata for the transaction

callbackUrl

string

Webhook URL on your server to receive real-time payout status updatesThis should be a publicly accessible HTTPS endpoint in your merchant system that can receive POST requests from Waypay. When a payout/withdrawal status changes, Waypay will send a webhook notification to this URL with the transaction details.When to use this parameter:

Use this parameter only if you need a dynamic webhook URL that varies per transaction (e.g., session-specific, order-specific URLs)
If your webhook URL is static (same for all transactions), configure it in your Merchant Portal instead. The system will automatically use the portal-configured URL when this parameter is not provided.

Maximum length: 2048 charactersRequired: HTTPS URL that can accept POST requestsExample (Dynamic): https://yoursite.com/api/webhooks/withdrawal?payout_id=12345Example (Static): Configure https://yoursite.com/api/webhooks/payout in Merchant Portal and omit this parameter

Best Practice: Use the Merchant Portal for static webhook URLs. Use this parameter only when you need dynamic, per-transaction webhook URLs.

See the Initiate Checkout documentation for complete webhook payload structure and implementation examples.

customerRef

object

required

Customer information with bank account details

Show properties

name

string

Customer full name

string

Customer email address (must be valid email format)

cnic

string

Customer CNIC number - must be exactly 13 digitsPattern: ^\d{13}$Example: 3520108345678

phone

string

Customer phone number

bankAccountNumber

string

required

Customer’s bank account number or IBAN (10-24 characters)Example: PK36SCBL0000001123456702

bankCode

string

required

Standard bank code for IBFT withdrawals (2-20 characters)This code identifies the target bank for processing the withdrawal. Use the standardized bank codes listed in the Bank Codes Reference section below.Examples:

HBL - Habib Bank Limited
UBL - United Bank Limited
MCB - MCB Bank Limited
JAZZCASH - JazzCash
EASYPAISA - Easypaisa

See the complete list of valid bank codes below.

bankName

string

Name of the customer’s bank (optional, for display purposes only)This field is informational only. The bankCode is used for actual processing.Examples:

Habib Bank Limited
United Bank Limited
Standard Chartered Bank
JazzCash
Easypaisa

accountTitle

string

required

Account holder name as per bank account (2-100 characters)

orderRef

object

required

Order information

Show properties

orderRef

string

required

Order reference (alphanumeric characters)Pattern: ^[A-Za-z0-9]+$

discount

string

Discount amount or percentage

tax

string

Tax amount or percentage

signature

string

required

Request signature for security verificationA cryptographic signature generated using MD5 hash algorithm to ensure the integrity and authenticity of the request. The signature is calculated using all request parameters (excluding the signature field itself) combined with your merchant secret key.Format: 32-character lowercase hexadecimal stringExample: a1b2c3d4e5f6789012345678abcdef12

Never expose your secret key in client-side code. Always generate signatures on your server.

Learn how to generate signatures: See the complete Signature Generation Guide for step-by-step instructions and implementation examples in C#, Node.js, Python, PHP, and Java.

Response

paymentIntentId

uuid

Unique identifier for the payment intent

amount

number

Withdrawal amount

currency

string

Payment currency

merchantReference

string

Your merchant reference for this transaction

isLive

boolean

Whether this is a live or test transaction

fee

number

Transaction fee amount

totalRequired

number

Total amount required (withdrawal amount + fee)

availableBalance

number

Your current available wallet balance

payoutInfo

object

Information about the payout processing

Show properties

status

string

Payout status

provider

string

Provider from which transaction is completed

transactionReference

string

Transaction reference number

message

string

Status message

isSuccess

boolean

Whether the payout was successful

errorDetails

string

Error details if payout failed

estimatedCompletionTime

datetime

Estimated time when payout will be completed

customerBankName

string

Customer’s bank name

customerAccountNumber

string

Customer’s account number

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

When autoProcessPayout is set to true, the system will automatically initiate the bank transfer without requiring manual approval. This is useful for:

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

When set to false (default), the withdrawal will be created but require manual approval before 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

Withdrawal processing times vary by bank and amount:

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

The estimatedCompletionTime field provides the expected completion timestamp.

Common Error Scenarios

Error	Cause	Solution
Invalid bank account	Incorrect IBAN or account number format	Verify account number format (10-24 characters)
Invalid bank code	Unsupported or incorrect bank code	Use a valid bank code from the supported list
Bank not found	Bank code not recognized	Check the Bank Codes Reference section for valid codes
Account mismatch	Account title doesn’t match bank records	Verify account holder name
Insufficient balance	Not enough funds in merchant wallet	Top up wallet or reduce withdrawal amount
Validation error	Missing required fields	Ensure all required fields are provided including bankCode

Bank Codes Reference

Use these standardized bank codes in the bankCode field when creating withdrawal orders. The codes are case-insensitive.

Major Banks

Bank Code	Bank Name	Also Accepts
`HBL`	Habib Bank Limited	HBL, Habib Bank
`UBL`	United Bank Limited	UBL, United Bank
`MCB`	MCB Bank Limited	MCB, MCB Bank
`ABL`	Allied Bank Limited	ABL, Allied Bank, Allied
`ASKARI`	Askari Bank Limited	Askari, Askari Bank
`MEEZAN`	Meezan Bank Limited	Meezan, Meezan Bank
`FAYSAL`	Faysal Bank Limited	Faysal, Faysal Bank
`ALFALAH`	Bank Alfalah Limited	Alfalah, Bank Alfalah
`ALHABIB`	Bank Al Habib Limited	AlHabib, Al Habib, Bank Al Habib
`JSBANK`	JS Bank Limited	JS, JS Bank, JSBANK

Islamic Banks

Bank Code	Bank Name	Also Accepts
`BANKISLAMI`	BankIslami Pakistan Limited	BankIslami, Bank Islami
`DIB`	Dubai Islamic Bank Pakistan Limited	DubaiIslamic, Dubai Islamic, Dubai Islamic Bank
`ALBARKA`	Al Baraka Bank (Pakistan) Limited	Albarka, Al Baraka, ALBARAKA

Foreign Banks

Bank Code	Bank Name	Also Accepts
`CITI`	Citibank N.A.	Citi, Citibank
`SCB`	Standard Chartered Bank (Pakistan) Limited	SCB, Standard Chartered, Standard Chartered Bank
`BOK`	Bank of Korea	BOK
`ICBC`	Industrial and Commercial Bank of China Limited	ICBC

Public Sector Banks

Bank Code	Bank Name	Also Accepts
`NBP`	National Bank of Pakistan	NBP, National Bank
`SINDH`	Sindh Bank Limited	SindhBank, Sindh Bank
`BOP`	The Bank of Punjab	PunjabBank, Bank of Punjab, BOP
`ZTBL`	Zarai Taraqiati Bank Limited	Zarai Taraqiati Bank, ZTBL

Digital & Wallet Banks

Bank Code	Bank Name	Also Accepts
`JAZZCASH`	JazzCash - Mobilink Bank	JazzCash, Jazz Cash, Mobilink Bank
`EASYPAISA`	Easypaisa - Telenor Microfinance Bank	EasyPaisa, Easypaisa, Telenor Microfinance
`SADAPAY`	SadaPay	SADAPAY, Sada Pay
`NAYAPAY`	Nayapay	NAYAPAY, NayaPay, Naya Pay
`UPAISA`	UPaisa - U Microfinance Bank Limited	UPaisa, U Paisa, U Microfinance Bank
`KEENU`	Keenu	KEENU, Keenu Bank
`TAG`	TAG	TAG
`FINJA`	Finja	FINJA, Finja Lending
`BYKEA`	Bykea	BYKEA

Microfinance Banks

Bank Code	Bank Name	Also Accepts
`NRSP`	NRSP Microfinance Bank Limited	NRSP, NRSP Microfinance
`FMFB`	First Microfinance Bank Limited	First Microfinance Bank, FMFB
`FINCA`	FINCA Microfinance Bank Limited	FINCA, FINCA Microfinance
`FWBL`	First Women Bank Limited	FWBL, First Women Bank
`APNA`	Apna Microfinance Bank Limited	Apna, Apna Microfinance
`BURJ`	Burj Bank Limited	Burj, Burj Bank
`MIB`	Mobilink Microfinance Bank Limited	MIB, Mobilink Microfinance
`ADVANS`	Advans Pakistan Microfinance Bank Limited	Advans, Advans Pakistan

Other Banks

Bank Code	Bank Name	Also Accepts
`SILK`	Silk Bank Limited	Silk, Silk Bank
`SONERI`	Soneri Bank Limited	Soneri, Soneri Bank
`SUMMIT`	Summit Bank Limited	Summit, Summit Bank
`NIB`	NIB Bank Limited	NIB, NIB Bank
`HMB`	Habib Metropolitan Bank Limited	HabibMetro, Habib Metro, Habib Metropolitan Bank
`SAMBA`	Samba Bank Limited	Samba, Samba Bank
`WASEELA`	Waseela Microfinance Bank Limited	Waseela, Waseela bank

Financial Services

Bank Code	Bank Name	Also Accepts
`CDNS`	Central Directorate of National Savings	CDNS, National Savings
`PAYMAX`	PayMax	PayMax
`ALMEEZAN`	Al Meezan Investment Management Limited	Al Meezan, Al Meezan Investment
`HBLAM`	HBL Asset Management Limited	HBL ASSET MANAGEMENT, HBL Asset Management
`NBPFM`	NBP Fund Management Limited	NBP Fund Management
`MCBAH`	MCB-Arif Habib Savings and Investments Limited	MCB-Arif Habib, MCB Arif Habib

Non-Bank Financial Institutions

Bank Code	Bank Name	Also Accepts
`ABHI`	Abhi Finance Services Limited	ABHI
`SEEDCREED`	SeedCreed Financial Services Limited	SEEDCREED, SeedCreed, Seed Creed
`HUMRAH`	Humrah Financial Services	Humrah, HUMRAH
`NUMBERS`	Numbers Private Limited	Numbers, NUMBERS
`TEZPAY`	TezPay	TezPAy, Tez Pay, TEZPAY
`EZWAGE`	EZ wage	EZ wage, EZwage, EZWAGE

Special Codes

Bank Code	Bank Name	Also Accepts
`AFTIBFT`	AFT IBFT	AFT IBFT, AFT

Important: The bankCode field is required and must match one of the standard codes listed above. The system will validate the bank code before processing the withdrawal. Bank codes are case-insensitive, so you can use hbl, HBL, or Hbl.

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

Use these test credentials in sandbox mode:

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

Check Transaction Status

Monitor withdrawal status by transaction reference

Setup Webhooks

Receive real-time notifications for withdrawal events

Handle Refunds

Process refunds if needed

View Settlement

Check settlement details

Create Deposit Order Query Transaction/Order Status

​Overview

​Path Parameters

​Request Body

​Response

​Validation Rules

​CNIC Format (Optional)

​Phone Number (Optional)

​Bank Account Number (Required)

​Bank Code (Required)

​Bank Name (Optional)

​Account Title (Required)

​Currency (Required)

​Description (Required)

​Required vs Optional Fields

​Required Fields

​Optional Fields

​Auto Process Payout

​Best Practices

​Processing Time

​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

​Testing

​Next Steps

Check Transaction Status

Setup Webhooks

Handle Refunds

View Settlement

Overview

Path Parameters

Request Body

Response

Validation Rules

CNIC Format (Optional)

Phone Number (Optional)

Bank Account Number (Required)

Bank Code (Required)

Bank Name (Optional)

Account Title (Required)

Currency (Required)

Description (Required)

Required vs Optional Fields

Required Fields

Optional Fields

Auto Process Payout

Best Practices

Processing Time

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

Testing

Next Steps