Create Deposit Order - Waypay API Documentation

curl --request POST \
  --url https://gateway.dev.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"
  }'

{
  "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,
    "errorDetails": null
  }
}

POST

Gateway

{version}

Payment

deposit

curl --request POST \
  --url https://gateway.dev.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"
  }'

{
  "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,
    "errorDetails": null
  }
}

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

version

string

required

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

Request Body

mobileNumber

string

required

Customer’s mobile wallet number

amount

number

required

Deposit amount (must be greater than 10)

walletProvider

integer

Mobile wallet provider code:

1: JazzCash
2: Easypaisa

paymentMethod

integer

Payment method (same as walletProvider):

1: JazzCash
2: Easypaisa

currency

string

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

description

string

required

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

callbackUrl

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.

intentType

string

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

customerRef

object

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

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

shippingAddress

string

Optional shipping address

estimatedDays

string

Estimated delivery days

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

Deposit amount

currency

string

Payment currency

merchantReference

string

Your merchant reference for this transaction

walletChargeInfo

object

Information about the wallet charge attempt

Show properties

provider

string

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

status

string

Charge status (e.g., “Pending”, “Success”, “Failed”)

transactionReference

string

Provider’s transaction reference number

message

string

Status message from the wallet provider

isSuccess

boolean

Whether the charge initiation was successful

errorDetails

string

Detailed error information if charge failed

curl --request POST \
  --url https://gateway.dev.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"
  }'

{
  "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,
    "errorDetails": null
  }
}

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

Initiate Checkout Create Withdrawal Order

​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