Integration API Reference

Automated high-throughput transactions for EasyPaisa and JazzCash payments in Pakistan. Use our simple, unified JSON payload system to integrate deposits (Pay-In) and payouts (Settlements) instantly.

Public Developer Credentials

AppID: c551c980b045d827f3d910fbdf8c1ddb
Mode: Public Sandbox

API Reference Menuv2 REST

How Authentication Works

Xpress Pay uses a simple App ID based authentication system. You only need to send your appId with every request — our backend automatically handles all signature generation, validation, and security internally.

Your Merchant Credentials

After your account is approved, you receive two credentials from the Admin dashboard:

Credential	Description	Usage
App ID	Your unique merchant identifier	Send as `appId` in every request
App Secret	Your private merchant key	Stored securely — never sent in requests

Quick Start

Submit your merchant application. Admin reviews and activates your account with a unique App ID.

Specify Callback / Notify URL

Pass your server's callback endpoint as the notifyUrl parameter directly inside the request payload. Our gateway will push updates to this URL.

Make Your First API Call

POST to /api/v2/payment/order/create with your appId and transaction details. That's it!

POST/api/v2/payment/order/create

Submit a server-to-server POST request to create an online deposit routing request. This will generate a secure checkout session URL.

Request Parameters

Field	Type	Required	Description
appId	String	Yes	Your unique Merchant App ID.
merOrderNo	String	Yes	Unique transaction order number generated by your system.
amount	String	Yes	Payment amount (e.g. "1500").
channel	String	Yes	Payment method channel: `EASYPAISA` or `JAZZCASH`.
customerMobile	String	No	Customer's mobile wallet number (e.g. "03001234567"). If omitted or empty, the checkout page will dynamically prompt the user to input their account number before routing.
customerName	String	Yes	Customer's full name.
customerEmail	String	No	Customer's email address.
notifyUrl	String	Yes	Webhook endpoint where our servers push successful payment notifications.
returnUrl	String	No	Optional redirection target URL. Customer will redirect here after success, failure, or cancellation.

Payload Body Example

{
  "appId": "c551c980b045d827f3d910fbdf8c1ddb",
  "merOrderNo": "PAYIN_ORDER_991823908",
  "amount": "1500",
  "channel": "EASYPAISA",
  "customerMobile": "03001234567",
  "customerName": "John Doe",
  "customerEmail": "buyer@gmail.com",
  "notifyUrl": "https://yourwebsite.com/api/payment-callback",
  "returnUrl": "https://yourwebsite.com/payment-result"
}

Request Code Samples

curl -X POST "https://gateway-pakistan.com/api/v2/payment/order/create" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "c551c980b045d827f3d910fbdf8c1ddb",
    "merOrderNo": "PAYIN_ORDER_991823908",
    "amount": "1500",
    "channel": "EASYPAISA",
    "customerMobile": "03001234567",
    "customerName": "John Doe",
    "customerEmail": "buyer@gmail.com",
    "notifyUrl": "https://yourwebsite.com/api/payment-callback",
    "returnUrl": "https://yourwebsite.com/payment-result"
  }'

Success Response Structure

{
  "code": 0,
  "msg": "success",
  "data": {
    "orderNo": "EP918203901",
    "params": {
      "paymentLink": "https://gateway-pakistan.com/checkout/sandbox-demo?merchantId=..."
    }
  }
}

Dynamic Checkout & Redirection Workflow

1. Mobile Collection Modes

With Account Number (Direct Route): If you pass a valid customerMobile in the payload, the checkout screen will skip manual input and automatically initiate the transaction.
Without Account Number (Input Mode): If customerMobile is skipped or empty, the checkout page dynamically renders a secure mobile number input form to collect the details from the user.

2. Custom Redirection

Pass the returnUrl parameter to redirect users back to your platform once they finish checkout.

Redirects automatically upon successful payment.
Redirects if the customer cancels the payment.
Falls back to the merchant's website domain if not provided.

POST/api/v2/payout/order/create

Triggers an outgoing B2C payout transfer from your available balance. Real transfers require sufficient balance and active configuration.

Request Parameters

Field	Type	Required	Description
appId	String	Yes	Your unique Merchant App ID.
merOrderNo	String	Yes	Your system's unique payout identifier.
amount	String	Yes	Payout sum (must not exceed available balance).
channel	String	Yes	Payout method channel: `EASYPAISA` or `JAZZCASH`.
recipientMobile	String	Yes	Recipient's mobile wallet account number.
recipientName	String	Yes	Recipient's account title name.
recipientEmail	String	No	Recipient's email address.
notifyUrl	String	Yes	Webhook notification endpoint for the payout result.

Payload Body Example

{
  "appId": "c551c980b045d827f3d910fbdf8c1ddb",
  "merOrderNo": "PAYOUT_ORDER_1882",
  "amount": "1000.00",
  "channel": "EASYPAISA",
  "recipientMobile": "03112233445",
  "recipientName": "Receiver Name",
  "recipientEmail": "recipient@gmail.com",
  "notifyUrl": "https://yourwebsite.com/api/payout-callback"
}

Request Code Samples

curl -X POST "https://gateway-pakistan.com/api/v2/payout/order/create" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "c551c980b045d827f3d910fbdf8c1ddb",
    "merOrderNo": "PAYOUT_ORDER_1882",
    "amount": "1000.00",
    "channel": "EASYPAISA",
    "recipientMobile": "03112233445",
    "recipientName": "Receiver Name",
    "recipientEmail": "recipient@gmail.com",
    "notifyUrl": "https://yourwebsite.com/api/payout-callback"
  }'

GET/api/v2/payment/order/query

Query the status of an incoming pay-in deposit order. Send a GET request containing query parameters: appId and merOrderNo.

Request Parameters

Field	Type	Required	Description
appId	String	Yes	Your unique Merchant App ID.
merOrderNo	String	Yes	Unique transaction order number generated by your system.

Pay-In Query Code Samples

curl -X GET "https://gateway-pakistan.com/api/v2/payment/order/query?appId=c551c980b045d827f3d910fbdf8c1ddb&merOrderNo=PAYIN_ORDER_991823908"

Response Status Codes

• orderStatus = "1": Unpaid / Processing (pending)

• orderStatus = "2": Success (paid / completed)

• orderStatus = "4": Failed (cancelled / expired)

GET/api/v2/payout/order/query

Query the status of an outgoing payout transfer. Send a GET request containing query parameters: appId and merOrderNo.

Request Parameters

Field	Type	Required	Description
appId	String	Yes	Your unique Merchant App ID.
merOrderNo	String	Yes	Unique transaction order number generated by your system.

Payout Query Code Samples

curl -X GET "https://gateway-pakistan.com/api/v2/payout/order/query?appId=c551c980b045d827f3d910fbdf8c1ddb&merOrderNo=PAYOUT_ORDER_1882"

Response Status Codes

• orderStatus = "1": Unpaid / Processing (pending)

• orderStatus = "2": Success (paid / completed)

• orderStatus = "4": Failed (cancelled / expired)

GET/api/v2/merchant/balance

Query the collection, settlement (payout), and frozen balance of your merchant account. Simply pass your appId as a query parameter.

Request Parameters

Field	Type	Required	Description
appId	String	Yes	Your unique Merchant App ID.

Request Code Samples

curl -X GET "https://gateway-pakistan.com/api/v2/merchant/balance?appId=c551c980b045d827f3d910fbdf8c1ddb"

Success Response Structure (200 OK)

{
  "code": 200,
  "data": {
    "currency": "PKR",
    "payinValue": 150000,
    "payoutValue": 130000,
    "disableValue": 10000
  },
  "msg": "success"
}

Asynchronous Webhook Callbacks

Once a transaction is finalized (success or failed), our gateway sends an asynchronous POST request containing the callback parameters to your configured notifyUrl.

{
  "appId": "c551c980b045d827f3d910fbdf8c1ddb",
  "merOrderNo": "PAYIN_ORDER_991823908",
  "orderNo": "EP918203901",
  "amount": "1500.00",
  "currency": "PKR",
  "orderStatus": "2"
}

Responding to Webhook

To prevent retries, your webhook endpoint must respond with the exact plaintext string "SUCCESS" with HTTP status code 200. Any other response will cause our system to retry the notification up to 5 times.

Integration / Server Code Samples

# Example callback request payload received by your server
curl -X POST https://yourdomain.com/payin/callback \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "c551c980b045d827f3d910fbdf8c1ddb",
    "merOrderNo": "PAYIN_ORDER_991823908",
    "orderNo": "EP918203901",
    "amount": "1500.00",
    "currency": "PKR",
    "orderStatus": "2"
  }'

Notice of Recall callback notification

If a transaction recall is initiated by a provider or bank dispute, our gateway sends an asynchronous callback POST request containing the recall details to your notification webhook URL.

{
  "appId": "c551c980b045d827f3d910fbdf8c1ddb",
  "merOrderNo": "PAYIN_ORDER_991823908",
  "orderNo": "EP918203901",
  "recallAmount": "1500.00",
  "currency": "PKR",
  "reason": "Customer dispute / account unauthorized charge"
}

Responding to Recall Webhook

Your server must respond with the exact plaintext string "SUCCESS" with HTTP status code 200 to acknowledge receipt of the recall event and prevent retry requests.

Recall Callback Code Samples

# Example recall notification payload received by your server
curl -X POST https://yourdomain.com/payin/recall \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "c551c980b045d827f3d910fbdf8c1ddb",
    "merOrderNo": "PAYIN_ORDER_991823908",
    "orderNo": "EP918203901",
    "recallAmount": "1500.00",
    "currency": "PKR",
    "reason": "Customer dispute / account unauthorized charge"
  }'

E-Commerce Plugins & Extensions

We are building official, audited plugins for the world's most popular shopping systems to let you accept payments without writing any code.

Coming Soon

WooCommerce / WordPress

Official Integration

A plug-and-play gateway extension for WordPress. Connects your WooCommerce checkout flow directly to the Xpress Pay API with support for secure authentication and automated callback status sync.

Coming Soon

Shopify Web Widget

Seamless Widget

Inject a responsive overlay checkout widget into your Shopify store template. Processes payment orders securely and updates transaction status using webhooks.