Skip to main content
POST
/
Gateway
/
v
{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)
​
orderRef
object
required
Order information
​
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
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

ProviderCodeStatusDescription
JazzCash1ActivePakistan’s leading mobile wallet service
Easypaisa2ActivePopular 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

  1. Create Deposit Order - Call this endpoint with customer details
  2. Customer Receives OTP - Mobile wallet provider sends OTP to customer’s phone
  3. Customer Verification - Customer enters OTP in their wallet app to approve
  4. Webhook Notification - You receive webhook when payment is confirmed
  5. 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

ErrorCauseSolution
Wallet not availableCustomer’s wallet account inactiveAsk customer to verify wallet account
Insufficient balanceCustomer wallet has insufficient fundsCustomer needs to top up wallet
Invalid mobile numberNumber not registered with walletVerify mobile number with customer
OTP timeoutCustomer didn’t complete verificationRetry 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