Introduction - Waypay API Documentation

Welcome to Waypay API

The Waypay Gateway API allows you to accept payments, process payouts, manage refunds, and handle settlements programmatically. Built on REST principles with predictable resource-oriented URLs, JSON responses, and standard HTTP response codes.

All API requests require authentication using your API key. See the Authentication section for details.

Base URL

https://gateway.dev.waypay.live/Gateway/v1

Key Features

Payment Processing

Accept payments via hosted checkout or custom integrations with support for cards and mobile wallets

Mobile Wallet Charging

Directly charge JazzCash, Easypaisa mobile wallets

Deposits & Withdrawals

Create deposit orders to collect funds and withdrawal orders to disburse payments

Refund Management

Process full or partial refunds with automated tracking

Settlement Control

Manage fund withdrawals with manual or automatic scheduling

Real-time Webhooks

Receive instant notifications for transaction events

API Capabilities

Account Endpoints

Query Balance - Retrieve wallet balance, pending amounts, and transaction counts

Payment Endpoints

Initiate Checkout - Create hosted payment sessions
Create Deposit - Initiate mobile wallet charges for payment collection
Create Withdrawal - Process payouts to customer bank accounts
Charge Mobile Wallet - Direct mobile wallet charging with tokens
Get Token Info - Retrieve payment token details

Transaction Endpoints

Get by Reference - Retrieve transaction by reference number
Get by ID - Retrieve transaction by unique identifier

Refund Endpoints

Create Refund - Initiate full or partial refunds
Get Refund - Retrieve refund details
Cancel Refund - Cancel pending refunds

Settlement Endpoints

Create Settlement - Request fund withdrawal to bank or USDT
Get Settlement - Retrieve specific settlement details
Configure Schedule - Set up automatic settlements with customizable parameters
Get Schedule - Retrieve current settlement schedule configuration

Environments

Waypay provides separate environments for testing and production:

Environment	Base URL	API Key Prefix
Test	`https://gateway.dev.waypay.live/Gateway/v1`	`pk_test_`
Production	`https://gateway.dev.waypay.live/Gateway/v1`	`pk_live_`

Use test mode to integrate and test your application without processing real transactions.

Test Mode / Sandbox

Important: Test Mode InformationWhen using test API keys (those starting with pk_test_), you are in sandbox mode. No real money is processed in test mode.

Test Mode Features

✅ No real money charged - All transactions are simulated
✅ Free to test - Test as many transactions as you need
✅ Same API behavior - Test mode mirrors production functionality
✅ Separate data - Test data never affects production
✅ Instant processing - No waiting for bank confirmations

Test Credentials

Use these standardized test credentials when testing in sandbox mode:

Test Mobile Number

Phone Number: 03123456789Use this mobile number for:

Deposit orders
Mobile wallet charging
Customer phone field
Any mobile wallet transactions

Test CNIC

CNIC: 3520108345678Last 6 digits: 345678Use this CNIC for:

Customer CNIC field
Last 6 CNIC digits verification
Bank account validation
Withdrawal requests

Test OTP

OTP Code: 123456When testing mobile wallet transactions, use this OTP to complete verification.

Test Bank Account

Account Number: PK36SCBL0000001123456702Bank Name: Standard Chartered BankAccount Holder: Ahmed AliUse these for testing withdrawal/payout flows.

Example Test Request

curl --request POST \
  --url https://gateway.dev.waypay.live/Gateway/v1/Payment/deposit \
  --header 'SWICH-API-Key: pk_test_xxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "mobileNumber": "03123456789",
    "amount": 1500,
    "walletProvider": 1,
    "currency": "PKR",
    "description": "Test Payment",
    "intentType": "deposit",
    "customerRef": {},
    "orderRef": {
      "orderRef": "TEST123456"
    }
  }'

Switching to Production

When you’re ready to go live:

✅ Complete all testing in sandbox mode
✅ Implement proper error handling
✅ Set up webhook endpoints
✅ Test all payment flows end-to-end
🔄 Switch to production API key (starts with pk_live_)
🔄 Use real customer data instead of test credentials
🔄 Real money will be processed

Never use test credentials in production! Always use real customer phone numbers, CNICs, and bank details when processing live transactions.

Quick Start

Here’s how to create your first test payment:

curl --request POST \
  --url https://gateway.dev.waypay.live/Gateway/v1/Payment/initiate-checkout \
  --header 'SWICH-API-Key: pk_test_xxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 1000,
    "currency": "PKR",
    "description": "Product Purchase",
    "customerRef": {},
    "orderRef": {
      "orderRef": "ORD123456"
    },
    "callbackUrl": "https://yoursite.com/payment/callback"
  }'

Response

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

Authentication

All API requests must include your API key in the SWICH-API-Key header:

SWICH-API-Key: pk_live_your_api_key

Never share your API key or commit it to version control. Use environment variables to store your keys securely.

Versioning

The API version is specified in the URL path. The current version is v1:

/Gateway/v1/Payment/initiate-checkout

We maintain backwards compatibility within major versions. Breaking changes will result in a new version number.

Rate Limits

To ensure service stability, API requests are rate-limited:

Test Environment: 100 requests per minute
Production Environment: 1000 requests per minute

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1639564800

Error Handling

Waypay uses conventional HTTP response codes:

Status Code	Meaning
200-299	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key
404	Not Found - Resource doesn’t exist
422	Unprocessable Entity - Validation error
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Error Response Format

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid request parameters",
  "instance": "/Gateway/v1/Payment/initiate-checkout"
}

See Error Codes for detailed information.

Supported Mobile Wallets

Waypay supports integration with Pakistan’s leading mobile wallet providers:

Provider	Code	Status
JazzCash	1	Active
Easypaisa	2	Active

Payment Flows

1. Hosted Checkout Flow

The simplest integration - redirect customers to Waypay’s hosted checkout page:

Call /Payment/initiate-checkout
Redirect customer to returned checkoutUrl
Customer completes payment
Receive webhook notification
Customer redirected to your success/cancel URL

2. Deposit Flow (Direct Mobile Wallet)

Collect payments directly from mobile wallets:

Call /Payment/deposit with customer wallet details
Customer receives OTP on their mobile
Customer completes OTP verification
Receive webhook notification

3. Withdrawal Flow (Bank Payout)

Disburse funds to customer bank accounts:

Call /Payment/withdraw with bank details
System processes payout (auto or manual approval)
Funds transferred to customer bank
Receive webhook notification

Idempotency

To safely retry requests without performing the same operation twice, include an idempotency key:

Idempotency-Key: unique-key-123

Waypay stores the result of the first request and returns it for subsequent requests with the same key (valid for 24 hours).

Webhooks

Receive real-time notifications when events occur in your Waypay account:

Payment completed
Payment failed
Deposit confirmed
Withdrawal processed
Refund processed
Settlement completed

Configure webhook endpoints in your dashboard.

Support

Need help? We’re here for you:

📧 Email: support@waypay.live
💬 Live Chat: Available in your dashboard
📚 Documentation: https://docs.waypay.live
🐛 Report Issues: support@waypay.live

Next Steps

Authentication

Learn how to authenticate your API requests

Account Balance

Check your wallet balance and pending transactions

Payment Endpoints

Start accepting payments

Deposit Orders

Collect payments from mobile wallets

Withdrawal Orders

Process payouts to bank accounts

Webhooks

Set up real-time event notifications

Quickstart Guide

Build your first integration

API documentation

Authentication

Account Balance

Hosted Page Checkout

Deposit

Withdrawal

Order Status

Refund Endpoints

Settlement Endpoints

Errors

​Welcome to Waypay API

​Base URL

​Key Features

Payment Processing

Mobile Wallet Charging

Deposits & Withdrawals

Refund Management

Settlement Control

Real-time Webhooks

​API Capabilities

​Account Endpoints

​Payment Endpoints

​Transaction Endpoints

​Refund Endpoints

​Settlement Endpoints

​Environments

​Test Mode / Sandbox

​Test Mode Features

​Test Credentials

​Example Test Request

​Switching to Production

​Quick Start

​Response

​Authentication

​Versioning

​Rate Limits

​Error Handling

​Error Response Format

​Supported Mobile Wallets

​Payment Flows

​1. Hosted Checkout Flow

​2. Deposit Flow (Direct Mobile Wallet)

​3. Withdrawal Flow (Bank Payout)

​Idempotency

​Webhooks

​Support

​Next Steps

Authentication

Account Balance

Payment Endpoints

Deposit Orders

Withdrawal Orders

Webhooks

Quickstart Guide

Welcome to Waypay API

Base URL

Key Features

API Capabilities

Account Endpoints

Payment Endpoints

Transaction Endpoints

Refund Endpoints

Settlement Endpoints

Environments

Test Mode / Sandbox

Test Mode Features

Test Credentials

Example Test Request

Switching to Production

Quick Start

Response

Authentication

Versioning

Rate Limits

Error Handling

Error Response Format

Supported Mobile Wallets

Payment Flows

1. Hosted Checkout Flow

2. Deposit Flow (Direct Mobile Wallet)

3. Withdrawal Flow (Bank Payout)

Idempotency

Webhooks

Support

Next Steps