Create Deposit Order

curl --request POST \
  --url https://gateway.waypay.live/Gateway/v1/Payment/deposit \
  --header 'SWICH-API-Key: pk_test_xxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "mobileNumber": "03123456789",
    "amount": 1500,
    "walletProvider": 1,
    "paymentMethod": 1,
    "currency": "PKR",
    "description": "Product Purchase",
    "intentType": "deposit",
    "callbackUrl": "https://yoursite.com/payment/callback",
    "orderRef": {
      "orderRef": "ORD123456"
    },
    "signature": "a1b2c3d4e5f6789012345678abcdef12"
  }'

const response = await fetch(
  'https://gateway.waypay.live/Gateway/v1/Payment/deposit',
  {
    method: 'POST',
    headers: {
      'SWICH-API-Key': 'pk_test_xxxxxxxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      mobileNumber: '03123456789',
      amount: 1500,
      walletProvider: 1,
      paymentMethod: 1,
      currency: 'PKR',
      description: 'Product Purchase',
      intentType: 'deposit',
      callbackUrl: 'https://yoursite.com/payment/callback',
      orderRef: {
        orderRef: 'ORD123456'
      },
      signature: 'a1b2c3d4e5f6789012345678abcdef12'
    })
  }
);

const data = await response.json();
console.log('Payment Intent ID:', data.paymentIntentId);

import requests

response = requests.post(
    'https://gateway.waypay.live/Gateway/v1/Payment/deposit',
    headers={
        'SWICH-API-Key': 'pk_test_xxxxxxxx',
        'Content-Type': 'application/json'
    },
    json={
        'mobileNumber': '03123456789',
        'amount': 1500,
        'walletProvider': 1,
        'paymentMethod': 1,
        'currency': 'PKR',
        'description': 'Product Purchase',
        'intentType': 'deposit',
        'callbackUrl': 'https://yoursite.com/payment/callback',
        'orderRef': {
            'orderRef': 'ORD123456'
        },
        'signature': 'a1b2c3d4e5f6789012345678abcdef12'
    }
)

data = response.json()
print(f"Charge Status: {data['walletChargeInfo']['status']}")

{
  "paymentIntentId": "770e8400-e29b-41d4-a716-446655440000",
  "amount": 1500,
  "currency": "PKR",
  "merchantReference": "ORD123456",
  "walletChargeInfo": {
    "provider": "JazzCash",
    "status": "Pending",
    "transactionReference": "JC20251213123456",
    "message": "OTP sent to customer",
    "isSuccess": true,
    "errorCode": null,
    "errorDetails": null,
    "traceId": "8f3a1c22d4b64e0fa1c9b7e5d2f30a41"
  }
}

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid mobile number format or CNIC digits"
}

{
  "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing API key"
}

{
  "type": "https://tools.ietf.org/html/rfc4918#section-11.2",
  "title": "Unprocessable Content",
  "status": 422,
  "detail": "Wallet provider not available or insufficient customer wallet balance"
}

POST

Gateway

{version}

Payment

deposit

curl --request POST \
  --url https://gateway.waypay.live/Gateway/v1/Payment/deposit \
  --header 'SWICH-API-Key: pk_test_xxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "mobileNumber": "03123456789",
    "amount": 1500,
    "walletProvider": 1,
    "paymentMethod": 1,
    "currency": "PKR",
    "description": "Product Purchase",
    "intentType": "deposit",
    "callbackUrl": "https://yoursite.com/payment/callback",
    "orderRef": {
      "orderRef": "ORD123456"
    },
    "signature": "a1b2c3d4e5f6789012345678abcdef12"
  }'

const response = await fetch(
  'https://gateway.waypay.live/Gateway/v1/Payment/deposit',
  {
    method: 'POST',
    headers: {
      'SWICH-API-Key': 'pk_test_xxxxxxxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      mobileNumber: '03123456789',
      amount: 1500,
      walletProvider: 1,
      paymentMethod: 1,
      currency: 'PKR',
      description: 'Product Purchase',
      intentType: 'deposit',
      callbackUrl: 'https://yoursite.com/payment/callback',
      orderRef: {
        orderRef: 'ORD123456'
      },
      signature: 'a1b2c3d4e5f6789012345678abcdef12'
    })
  }
);

const data = await response.json();
console.log('Payment Intent ID:', data.paymentIntentId);

import requests

response = requests.post(
    'https://gateway.waypay.live/Gateway/v1/Payment/deposit',
    headers={
        'SWICH-API-Key': 'pk_test_xxxxxxxx',
        'Content-Type': 'application/json'
    },
    json={
        'mobileNumber': '03123456789',
        'amount': 1500,
        'walletProvider': 1,
        'paymentMethod': 1,
        'currency': 'PKR',
        'description': 'Product Purchase',
        'intentType': 'deposit',
        'callbackUrl': 'https://yoursite.com/payment/callback',
        'orderRef': {
            'orderRef': 'ORD123456'
        },
        'signature': 'a1b2c3d4e5f6789012345678abcdef12'
    }
)

data = response.json()
print(f"Charge Status: {data['walletChargeInfo']['status']}")

{
  "paymentIntentId": "770e8400-e29b-41d4-a716-446655440000",
  "amount": 1500,
  "currency": "PKR",
  "merchantReference": "ORD123456",
  "walletChargeInfo": {
    "provider": "JazzCash",
    "status": "Pending",
    "transactionReference": "JC20251213123456",
    "message": "OTP sent to customer",
    "isSuccess": true,
    "errorCode": null,
    "errorDetails": null,
    "traceId": "8f3a1c22d4b64e0fa1c9b7e5d2f30a41"
  }
}

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid mobile number format or CNIC digits"
}

{
  "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing API key"
}

{
  "type": "https://tools.ietf.org/html/rfc4918#section-11.2",
  "title": "Unprocessable Content",
  "status": 422,
  "detail": "Wallet provider not available or insufficient customer wallet balance"
}

Overview

This endpoint creates a deposit order that initiates a mobile wallet charge from your customer. Use this for collecting payments directly from mobile wallets like JazzCash, Easypaisa.

Path Parameters

string

required

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

Request Body

string

required

Customer’s mobile wallet number

number

required

Deposit amount. Minimum depends on the wallet provider:

JazzCash: minimum 100
Easypaisa: minimum 200

integer

Mobile wallet provider code:

1: JazzCash
2: Easypaisa

integer

Payment method (same as walletProvider):

1: JazzCash
2: Easypaisa

string

Payment currency (e.g., “PKR”)

string

required

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

string

Webhook URL on your server to receive real-time transaction status updatesThis should be a publicly accessible HTTPS endpoint in your merchant system that can receive POST requests from Waypay. When a transaction 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/deposit?order_id=12345Example (Static): Configure https://yoursite.com/api/webhooks/payment 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.

string

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

object

Customer information (optional object, all fields within are also optional)

Show properties

string

Customer full name

string

Customer email address (must be valid email format)

string

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

string

Customer phone number

string

Optional shipping address

string

Estimated delivery days

object

required

Order information

Show properties

string

required

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

string

Discount amount or percentage

string

Tax amount or percentage

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

uuid

Unique identifier for the payment intent

number

Deposit amount

string

Payment currency

string

Your merchant reference for this transaction

object

Information about the wallet charge attempt

Show properties

string

Wallet provider name (e.g., “JazzCash”, “Easypaisa”)

string

Charge status. For mobile wallet payments this is Processing — the request has been accepted and the customer must still approve it on their handset. It is not a completed payment. The terminal outcome arrives by webhook or via a status query.

string

Provider’s transaction reference number

string

Status message from the wallet provider

boolean

Whether the charge request was accepted, not whether the payment completed. Do not fulfil an order on this field alone. Whether the charge initiation was successful

string

Stable, machine-readable error code. Branch on this, not on errorDetails. null when there is no error. See the withdraw endpoint for the shared code vocabulary.

string

Correlation id for this request, always present. Quote it to WayPay support to retrieve the full server-side trace for this exact call.

string

Detailed error information if charge failed

curl --request POST \
  --url https://gateway.waypay.live/Gateway/v1/Payment/deposit \
  --header 'SWICH-API-Key: pk_test_xxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "mobileNumber": "03123456789",
    "amount": 1500,
    "walletProvider": 1,
    "paymentMethod": 1,
    "currency": "PKR",
    "description": "Product Purchase",
    "intentType": "deposit",
    "callbackUrl": "https://yoursite.com/payment/callback",
    "orderRef": {
      "orderRef": "ORD123456"
    },
    "signature": "a1b2c3d4e5f6789012345678abcdef12"
  }'

const response = await fetch(
  'https://gateway.waypay.live/Gateway/v1/Payment/deposit',
  {
    method: 'POST',
    headers: {
      'SWICH-API-Key': 'pk_test_xxxxxxxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      mobileNumber: '03123456789',
      amount: 1500,
      walletProvider: 1,
      paymentMethod: 1,
      currency: 'PKR',
      description: 'Product Purchase',
      intentType: 'deposit',
      callbackUrl: 'https://yoursite.com/payment/callback',
      orderRef: {
        orderRef: 'ORD123456'
      },
      signature: 'a1b2c3d4e5f6789012345678abcdef12'
    })
  }
);

const data = await response.json();
console.log('Payment Intent ID:', data.paymentIntentId);

import requests

response = requests.post(
    'https://gateway.waypay.live/Gateway/v1/Payment/deposit',
    headers={
        'SWICH-API-Key': 'pk_test_xxxxxxxx',
        'Content-Type': 'application/json'
    },
    json={
        'mobileNumber': '03123456789',
        'amount': 1500,
        'walletProvider': 1,
        'paymentMethod': 1,
        'currency': 'PKR',
        'description': 'Product Purchase',
        'intentType': 'deposit',
        'callbackUrl': 'https://yoursite.com/payment/callback',
        'orderRef': {
            'orderRef': 'ORD123456'
        },
        'signature': 'a1b2c3d4e5f6789012345678abcdef12'
    }
)

data = response.json()
print(f"Charge Status: {data['walletChargeInfo']['status']}")

{
  "paymentIntentId": "770e8400-e29b-41d4-a716-446655440000",
  "amount": 1500,
  "currency": "PKR",
  "merchantReference": "ORD123456",
  "walletChargeInfo": {
    "provider": "JazzCash",
    "status": "Pending",
    "transactionReference": "JC20251213123456",
    "message": "OTP sent to customer",
    "isSuccess": true,
    "errorCode": null,
    "errorDetails": null,
    "traceId": "8f3a1c22d4b64e0fa1c9b7e5d2f30a41"
  }
}

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid mobile number format or CNIC digits"
}

{
  "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing API key"
}

{
  "type": "https://tools.ietf.org/html/rfc4918#section-11.2",
  "title": "Unprocessable Content",
  "status": 422,
  "detail": "Wallet provider not available or insufficient customer wallet balance"
}

Validation Rules

CNIC Format

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

Order Reference

Alphanumeric characters only
Pattern: ^[A-Za-z0-9]+$
Example: ORD123456

Description

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

Wallet Provider Codes

Provider	Code	Status	Description
JazzCash	1	Active	Pakistan’s leading mobile wallet service
Easypaisa	2	Active	Popular mobile wallet and financial service

The paymentMethod and walletProvider fields accept the same values. You can use either field to specify the payment method.

Payment Flow

Create Deposit Order - Call this endpoint with customer details
Customer Receives OTP - Mobile wallet provider sends OTP to customer’s phone
Customer Verification - Customer enters OTP in their wallet app to approve
Webhook Notification - You receive webhook when payment is confirmed
Transaction Complete - Funds are added to your merchant wallet

In test mode, use OTP 123456 to complete wallet verification for testing purposes.

Best Practices

Validate Before Submission: Always validate mobile number and CNIC format before making the request
Handle OTP Flow: Implement proper UI/UX for customers to complete OTP verification
Monitor Status: Poll the transaction status or use webhooks to get real-time updates
Error Handling: Implement retry logic for temporary failures
Store Payment Intent ID: Keep the paymentIntentId for reconciliation and support
Test Mode: Use test credentials (03123456789) in sandbox environment
Production Mode: Use real customer data when processing live transactions

Common Error Scenarios

Error	Cause	Solution
Wallet not available	Customer’s wallet account inactive	Ask customer to verify wallet account
Insufficient balance	Customer wallet has insufficient funds	Customer needs to top up wallet
Invalid mobile number	Number not registered with wallet	Verify mobile number with customer
OTP timeout	Customer didn’t complete verification	Retry the deposit request

Security Considerations

Never store customer CNIC or sensitive information in plain text
Use HTTPS for all API communications
Validate customer identity before processing deposits
Implement rate limiting to prevent abuse
Monitor for suspicious transaction patterns
Keep API keys secure and rotate regularly

Testing

Use these test credentials in sandbox mode:

Mobile Number: 03123456789
CNIC: 3520108345678
OTP: 123456
Wallet Provider: 1 (JazzCash) or 2 (Easypaisa)

Next Steps

Check Transaction Status

Monitor deposit status by transaction reference

Setup Webhooks

Receive real-time notifications for deposit events

Handle Refunds

Process refunds for completed deposits

Mobile Wallet Charging

Direct wallet charging with tokens

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

Order Reference

Description

Wallet Provider Codes

Payment Flow

Best Practices

Common Error Scenarios

Security Considerations

Testing

Next Steps

Check Transaction Status

Setup Webhooks

Handle Refunds

Mobile Wallet Charging

​Overview

​Path Parameters

​Request Body

​Response

​Validation Rules

​CNIC Format

​Order Reference

​Description

​Wallet Provider Codes

​Payment Flow

​Best Practices

​Common Error Scenarios

​Security Considerations

​Testing

​Next Steps

Check Transaction Status

Setup Webhooks

Handle Refunds

Mobile Wallet Charging

Overview

Path Parameters

Request Body

Response

Validation Rules

CNIC Format

Order Reference

Description

Wallet Provider Codes

Payment Flow

Best Practices

Common Error Scenarios

Security Considerations

Testing

Next Steps