Create Withdrawal Order

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

bankName

string

required

Name of the customer’s bank (2-100 characters)Examples:

Bank Alfalah
JazzCash
Easypaisa
Standard Chartered
HBL
UBL

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",
      "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 Name (Required)

Length: 2-100 characters
Examples: Bank Alfalah, JazzCash, Easypaisa, Standard Chartered, HBL, UBL

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.bankName - Bank name
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
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
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

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)
Bank not found	Invalid or unsupported bank name	Use exact bank name from supported list
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

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 Name: Standard Chartered Bank
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

API documentation

Authentication

Account Balance

Hosted Page Checkout

Deposit

Withdrawal

Order Status

Refund Endpoints

Settlement Endpoints

Errors

Overview

Path Parameters

Request Body

Response

Validation Rules

CNIC Format (Optional)

Phone Number (Optional)

Bank Account Number (Required)

Bank Name (Required)

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

Security Considerations

Testing

Next Steps

Check Transaction Status

Setup Webhooks

Handle Refunds

View Settlement

API documentation

Authentication

Account Balance

Hosted Page Checkout

Deposit

Withdrawal

Order Status

Refund Endpoints

Settlement Endpoints

Errors

​Overview

​Path Parameters

​Request Body

​Response

​Validation Rules

​CNIC Format (Optional)

​Phone Number (Optional)

​Bank Account Number (Required)

​Bank Name (Required)

​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

​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 Name (Required)

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

Security Considerations

Testing

Next Steps