Quickstart

Create your WayPay account

To use the WayPay Merchant APIs, first create an account:

Go to: https://portal.dev.waypay.live
Click Sign Up and complete the registration form (business name, contact, email, phone).
Verify your email address via the link sent to your inbox.
Provide required business details and documents for compliance (KYC/KYB).
Submit for review and wait for approval. You’ll be notified once your account is active.

Your API access becomes available only after your account is approved and active. Approval timelines vary based on compliance review completeness.

Get your API key

Once approved:

Sign in to the merchant portal.
Locate your API key in the dashboard.
Copy it securely. Never commit keys to source control.
Use separate keys per environment and rotate them periodically.

All API requests must include this header:

SWICH-API-Key: YOUR_API_KEY

Treat your API key like a password. Rotate it immediately if exposed.

Understanding Test Mode

Test Mode vs Production ModeWayPay provides two environments to help you develop and test your integration safely:

Test Mode (Sandbox)

When using API keys that start with pk_test_, you are in test mode:

✅ No real money is processed - All transactions are simulated
✅ Free unlimited testing - Test as many transactions as you need
✅ Instant processing - No waiting for real bank confirmations
✅ Same API behavior - Test mode mirrors production functionality
✅ Separate data - Test transactions never affect production data

Test Credentials

Always use these standardized test credentials in sandbox mode:

Test Phone Number

03123456789Use for all mobile wallet and customer phone fields

Test CNIC

Full: 3520108345678Last 6 digits: 345678

Test OTP

123456Use when completing mobile wallet verification

Test Bank Account

IBAN: PK36SCBL0000001123456702Bank: Standard Chartered BankAccount Title: Test User

Production Mode

When using API keys that start with pk_live_:

⚠️ Real money is processed - Actual charges and transfers occur
💳 Real customer data required - Use actual phone numbers, CNICs, bank accounts
🏦 Real banking delays - Transactions follow actual bank processing times
📊 Affects live balances - All transactions update production wallet balances

Never use test credentials (03123456789, 3520108345678) in production! Always use real customer information when processing live transactions.

Make your first test API call

Set your test API key in the terminal:

export SWICH_API_KEY="pk_test_xxxxxxxxxxxxx"

Example 1: Create a test checkout session

curl -X POST "https://gateway.dev.waypay.live/Gateway/v1/Payment/initiate-checkout" \
  -H "Content-Type: application/json" \
  -H "SWICH-API-Key: $SWICH_API_KEY" \
  -d '{
    "amount": 1000,
    "currency": "PKR",
    "description": "Test Order 12345",
    "customerRef": {
      "name": "Test User",
      "email": "test@example.com",
      "cnic": "3520108345678",
      "phone": "03123456789"
    },
    "orderRef": { 
      "orderRef": "TEST-ORD-12345" 
    },
    "callbackUrl": "https://merchant.example.com/webhook/payment",
    "signature": "a1b2c3d4e5f6789012345678abcdef12"
  }'

You should receive a response with paymentIntentId and checkoutUrl:

{
  "paymentIntentId": "550e8400-e29b-41d4-a716-446655440000",
  "checkoutUrl": "https://checkout.waypay.com/pay/abc123xyz",
  "expiresAt": "2025-12-12T12:00:00Z"
}

Redirect your customer to the checkoutUrl to complete the test payment.

Example 2: Test mobile wallet deposit

curl -X POST "https://gateway.dev.waypay.live/Gateway/v1/Payment/deposit" \
  -H "Content-Type: application/json" \
  -H "SWICH-API-Key: $SWICH_API_KEY" \
  -d '{
    "mobileNumber": "03123456789",
    "amount": 1500,
    "walletProvider": 1,
    "currency": "PKR",
    "description": "Test Deposit",
    "intentType": "deposit",
    "customerRef": {
      "name": "Test User",
      "email": "test@example.com",
      "cnic": "3520108345678",
      "phone": "03123456789"
    },
    "orderRef": {
      "orderRef": "TEST-DEP-456"
    },
    "signature": "b2c3d4e5f6789012345678abcdef123"
  }'

Expected Response:

{
  "paymentIntentId": "770e8400-e29b-41d4-a716-446655440000",
  "amount": 1500,
  "currency": "PKR",
  "merchantReference": "TEST-DEP-456",
  "walletChargeInfo": {
    "provider": "JazzCash",
    "status": "Pending",
    "transactionReference": "JC20251213123456",
    "message": "OTP sent to customer",
    "isSuccess": true
  }
}

In test mode, use OTP 123456 to complete the mobile wallet verification.

Example 3: Test bank withdrawal/payout

curl -X POST "https://gateway.dev.waypay.live/Gateway/v1/Payment/withdraw" \
  -H "Content-Type: application/json" \
  -H "SWICH-API-Key: $SWICH_API_KEY" \
  -d '{
    "amount": 5000,
    "currency": "PKR",
    "description": "Test Payout",
    "intentType": "withdrawal",
    "autoProcessPayout": true,
    "customerRef": {
      "name": "Test User",
      "email": "test@example.com",
      "cnic": "3520108345678",
      "phone": "03123456789",
      "bankAccountNumber": "PK36SCBL0000001123456702",
      "bankName": "Standard Chartered Bank",
      "accountTitle": "Test User"
    },
    "orderRef": {
      "orderRef": "TEST-WD-789"
    },
    "signature": "c3d4e5f6789012345678abcdef12345"
  }'

Expected Response:

{
  "paymentIntentId": "880e8400-e29b-41d4-a716-446655440000",
  "amount": 5000,
  "currency": "PKR",
  "merchantReference": "TEST-WD-789",
  "payoutInfo": {
    "status": "Processing",
    "provider": "Bank Transfer",
    "transactionReference": "WD20251213123456",
    "message": "Payout initiated successfully",
    "isSuccess": true,
    "errorDetails": null,
    "estimatedCompletionTime": "2025-12-14T10:00:00Z",
    "customerBankName": "Standard Chartered Bank",
    "customerAccountNumber": "PK36SCBL0000001123456702"
  }
}

Additional Test Examples

Check test wallet balance

curl -X POST "https://gateway.dev.waypay.live/Gateway/v1/Account/query-balance" \
  -H "SWICH-API-Key: $SWICH_API_KEY"

Get test transaction details

curl -X GET "https://gateway.dev.waypay.live/Gateway/v1/Transaction/by-ref/TEST-ORD-12345" \
  -H "SWICH-API-Key: $SWICH_API_KEY"

Issue a test refund

curl -X POST "https://gateway.dev.waypay.live/Gateway/v1/Refunds" \
  -H "Content-Type: application/json" \
  -H "SWICH-API-Key: $SWICH_API_KEY" \
  -d '{
    "trxnRef": "TXN20251212123456",
    "amount": 500,
    "reason": "Test refund - customer return",
    "signature": "d4e5f6789012345678abcdef1234567"
  }'

About Signatures in ExamplesThe signature field values shown in the examples above (e.g., a1b2c3d4e5f6789012345678abcdef12) are placeholders. In production, you must generate valid signatures using your secret key.See the Signature Generation Guide for step-by-step instructions on how to generate signatures in C#, Node.js, Python, PHP, and Java.

Going Live Checklist

Before switching to production mode:

✅ Test all payment flows thoroughly in sandbox
✅ Implement proper error handling for all endpoints
✅ Set up and test webhook endpoints
✅ Test transaction status polling/verification
✅ Implement idempotency for all payment requests
✅ Set up proper logging and monitoring
✅ Review and implement security best practices
✅ Validate all required field formats (CNIC, phone, bank account)
✅ Complete KYC/KYB verification
✅ Obtain production API key (pk_live_)
✅ Update environment variables with production key
✅ Switch to using real customer data (phone, CNIC, bank accounts)
✅ Test a small transaction in production
✅ Monitor first few production transactions closely

Critical Reminders for Production:

Real money will be processed
Use actual customer phone numbers (format: ^(\+92|0)?3\d{9}$)
Use valid CNICs (13 digits: ^\d{13}$)
Validate bank account details before withdrawals
Never use test credentials (03123456789, 3520108345678)
Keep production API keys secure

Troubleshooting

401 Unauthorized

Ensure the header is present and correct:

-H "SWICH-API-Key: $SWICH_API_KEY"

Common issues:

Missing SWICH-API-Key header
Incorrect API key
Using test key in production or vice versa
API key has been revoked

400 Bad Request

Check your payload fields and formats:

description must be 1-200 alphanumeric characters and spaces
amount must be greater than 10
currency must be exactly 3 characters (e.g., “PKR”)
Required fields are present (name, email, cnic, phone)
In test mode, use correct test credentials
Phone must match pattern: ^(\+92|0)?3\d{9}$
CNIC must be 13 digits: ^\d{13}$

422 Validation Error

Your request passed basic validation but failed business logic:

Insufficient balance
Invalid mobile number format (must be 03123456789 in test mode)
Transaction already refunded
CNIC format incorrect (must be 3520108345678 in test mode)
Bank account number length invalid (10-24 characters)
Email format invalid

See the full API reference and schema at the API Reference, and detailed endpoint examples under API Reference → Endpoints.

Next steps

API reference

Explore endpoints, payloads, and examples powered by OpenAPI.

Authentication

Learn about API key management and security best practices.

Payment Endpoints

Deep dive into payment processing options.

Deposit Orders

Collect payments from mobile wallets.

Withdrawal Orders

Process payouts to bank accounts.

Webhooks

Set up real-time event notifications.

Need help? Contact support@waypay.live or check our documentation.

Getting started

Core Business Processes

Create your WayPay account

Get your API key

Understanding Test Mode

Test Mode (Sandbox)

Test Credentials

Test Phone Number

Test CNIC

Test OTP

Test Bank Account

Production Mode

Make your first test API call

Example 1: Create a test checkout session

Example 2: Test mobile wallet deposit

Example 3: Test bank withdrawal/payout

Additional Test Examples

Check test wallet balance

Get test transaction details

Issue a test refund

Going Live Checklist

Troubleshooting

401 Unauthorized

400 Bad Request

422 Validation Error

Next steps

API reference

Authentication

Payment Endpoints

Deposit Orders

Withdrawal Orders

Webhooks

Getting started

Core Business Processes

​Create your WayPay account

​Get your API key

​Understanding Test Mode

​Test Mode (Sandbox)

​Test Credentials

Test Phone Number

Test CNIC

Test OTP

Test Bank Account

​Production Mode

​Make your first test API call

​Example 1: Create a test checkout session

​Example 2: Test mobile wallet deposit

​Example 3: Test bank withdrawal/payout

​Additional Test Examples

​Check test wallet balance

​Get test transaction details

​Issue a test refund

​Going Live Checklist

​Troubleshooting

​401 Unauthorized

​400 Bad Request

​422 Validation Error

​Next steps

API reference

Authentication

Payment Endpoints

Deposit Orders

Withdrawal Orders

Webhooks

Create your WayPay account

Get your API key

Understanding Test Mode

Test Mode (Sandbox)

Test Credentials

Production Mode

Make your first test API call

Example 1: Create a test checkout session

Example 2: Test mobile wallet deposit

Example 3: Test bank withdrawal/payout

Additional Test Examples

Check test wallet balance

Get test transaction details

Issue a test refund

Going Live Checklist

Troubleshooting

401 Unauthorized

400 Bad Request

422 Validation Error

Next steps