Xpress Pay - Custom White-Label Payment Gateway

API Reference

1. Overview & Credentials

Gateway Pakistan provides a secure, RESTful v2 API for high-volume Pakistani payment routing. All API requests use JSON bodies over HTTPS.

Merchant Credentials

Credential	Description	Usage
appId	Your unique Merchant Application ID	Send as `"appId"` in every request body
appSecret	Your private Merchant Secret Key	Used exclusively to generate SHA-256 signatures. Never send in requests!

Integration Steps

Get Merchant Credentials

Copy your appId and appSecret from your Merchant Dashboard.

Generate SHA-256 Signature

Sort request parameters alphabetically, append &key=appSecret, and hash with SHA-256.

Receive Webhook Updates

Pass notifyUrl in request. Our system pushes instant webhook notifications upon transaction completion.

2. SHA-256 Signature Algorithm

Every request submitted to Gateway Pakistan requires a checksum signature parameter "sign" to guarantee request integrity.

Algorithm Steps:

Remove empty values and the "sign" field from your payload object.
Sort all remaining parameter keys in ASCII alphabetical order.
Format as query string: key1=value1&key2=value2&...
Append your merchant secret: ...&key=YOUR_APP_SECRET
Generate SHA-256 hex digest (or MD5) of the string.

PHP Signature Code Example

function generateSignature($params, $appSecret) {
    unset($params['sign']);
    ksort($params);
    $arr = [];
    foreach ($params as $k => $v) {
        if ($v !== "" && $v !== null) {
            $arr[] = "$k=$v";
        }
    }
    $strToSign = implode("&", $arr) . "&key=" . $appSecret;
    return hash("sha256", $strToSign);
}

POST/api/v2/payment/order/create

Create a new online pay-in deposit order. Generates a secure checkout payment link for Easypaisa or JazzCash collection.

Request Parameters

Field	Type	Required	Description
appId	String	Yes	Your unique Merchant App ID.
merOrderNo	String	Yes	Unique order ID generated by your system.
amount	String	Yes	Deposit amount in PKR (minimum PKR 100).
channel	String	Yes	Payment channel: `EASYPAISA` or `JAZZCASH`.
customerMobile	String	Optional	Customer's mobile wallet number (e.g. "03001234567").
customerName	String	Optional	Customer's full name.
notifyUrl	String	Yes	Your server's webhook callback endpoint URL.
returnUrl	String	Optional	URL to redirect customer after payment completion.
sign	String	Yes	Calculated SHA-256 signature checksum.

Request Code Samples

curl -X POST "https://xpresspay.cloud/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",
    "sign": "5f4dcc3b5aa765d61d8327deb882cf99"
  }'

Success Response Example (200 OK)

{
  "code": 0,
  "msg": "success",
  "payUrl": "https://xpresspay.cloud/pay/EP918203901",
  "gatewayOrderNo": "EP918203901",
  "merOrderNo": "PAYIN_ORDER_991823908",
  "sign": "a1b2c3d4e5f67890..."
}

POST/api/v2/payout/order/create

Trigger an automated B2C payout transfer from your available balance directly to a customer's Easypaisa or JazzCash account.

Request Parameters

Field	Type	Required	Description
appId	String	Yes	Your unique Merchant App ID.
merOrderNo	String	Yes	Your system's unique payout order identifier.
amount	String	Yes	Payout sum (must not exceed your available balance).
channel	String	Yes	Payout channel: `EASYPAISA` or `JAZZCASH`.
accountNumber	String	Yes	Recipient's mobile wallet account number (e.g. "03112233445").
accountTitle	String	Yes	Recipient's account title name.
notifyUrl	String	Yes	Webhook notification endpoint URL for payout results.
sign	String	Yes	Calculated SHA-256 signature checksum.

Request Code Samples

curl -X POST "https://xpresspay.cloud/api/v2/payout/order/create" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "c551c980b045d827f3d910fbdf8c1ddb",
    "merOrderNo": "PAYOUT_ORDER_1882",
    "amount": "1000.00",
    "channel": "EASYPAISA",
    "accountNumber": "03112233445",
    "accountTitle": "Receiver Name",
    "notifyUrl": "https://yourwebsite.com/api/payout-callback",
    "sign": "9b1deb4d3b7d1638e4088a8d1e2e99d8"
  }'

Payout Success Response Example

{
  "code": 0,
  "msg": "payout request submitted",
  "orderNo": "PO_1882_99120",
  "merOrderNo": "PAYOUT_ORDER_1882",
  "status": "pending",
  "sign": "a1b2c3d4e5f67890..."
}

POST/api/v2/payment/order/query

Query the real-time payment status of an incoming pay-in deposit order.

Request Code Samples

curl -X POST "https://xpresspay.cloud/api/v2/payment/order/query" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "c551c980b045d827f3d910fbdf8c1ddb",
    "merOrderNo": "PAYIN_ORDER_991823908",
    "sign": "7c2b3e4f5a6b7c8d9e0f1a2b3c4d5e6f"
  }'

Response Structure

{
  "code": 0,
  "msg": "success",
  "data": {
    "orderNo": "EP918203901",
    "merOrderNo": "PAYIN_ORDER_991823908",
    "amount": "1500.00",
    "currency": "PKR",
    "orderStatus": "2",
    "channel": "EASYPAISA",
    "createdAt": "2026-08-17T09:00:00.000Z"
  }
}

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

• orderStatus = "2": Success (Paid / Completed)

• orderStatus = "4": Failed (Cancelled / Expired)

POST/api/v2/payout/order/query

Query the execution status of an outgoing payout transfer.

Request Code Samples

curl -X POST "https://xpresspay.cloud/api/v2/payout/order/query" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "c551c980b045d827f3d910fbdf8c1ddb",
    "merOrderNo": "PAYOUT_ORDER_1882",
    "sign": "8d3c4e5f6a7b8c9d0e1f2a3b4c5d6e7f"
  }'

POST/api/v2/account/balance/query

Query your available, frozen, and total withdrawn balance.

Request Code Samples

curl -X POST "https://xpresspay.cloud/api/v2/account/balance/query" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "c551c980b045d827f3d910fbdf8c1ddb",
    "sign": "3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d"
  }'

Response Structure Example

{
  "code": 0,
  "msg": "success",
  "availableBalance": "150000.00",
  "frozenBalance": "0.00",
  "withdrawn": "50000.00"
}

8. Webhook Callback Specification

When a transaction is finalized (success or failed), Gateway Pakistan dispatches an asynchronous POST request to your specified notifyUrl.

Webhook JSON Body Sent to Your Server

{
  "appId": "c551c980b045d827f3d910fbdf8c1ddb",
  "merOrderNo": "PAYIN_ORDER_991823908",
  "orderNo": "EP918203901",
  "amount": "1500.00",
  "currency": "PKR",
  "channel": "EASYPAISA",
  "orderStatus": "2",
  "status": "success",
  "code": 0,
  "msg": "success",
  "timestamp": 1723888000,
  "sign": "a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890"
}

Merchant Response Requirement

Your server endpoint must return an HTTP Status Code 200 OK with the exact plaintext string "SUCCESS" or "OK" to acknowledge receipt. If any other status code or error is returned, Gateway Pakistan will automatically retry delivery up to 3 times with exponential backoff.

Webhook Server Implementation Samples

# Example callback request payload received by your server from Gateway Pakistan
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",
    "channel": "EASYPAISA",
    "orderStatus": "2",
    "status": "success",
    "code": 0,
    "msg": "success",
    "timestamp": 1723888000,
    "sign": "a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890"
  }'

9. Notice of Recall Notification

If a transaction recall or dispute is flagged by a banking provider, Gateway Pakistan sends a recall notification callback POST request to your server.

Recall Payload Format

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

Recall Handler 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"
  }'

10. E-Commerce Extensions

Plug-and-play integrations for popular shopping platforms to accept Easypaisa & JazzCash without writing code.

Available Soon

WooCommerce / WordPress

Official Gateway Plugin

Zero-code WordPress payment gateway extension with automatic callback synchronization and Easypaisa / JazzCash checkout overlay.

Available Soon

Shopify Web Widget

Seamless Payment Overlay

Embeddable payment checkout widget for Shopify stores with instant webhook notifications and automated settlement.

Gateway Pakistan API Documentation

API Reference

1. Overview & Credentials

Merchant Credentials

Integration Steps

2. SHA-256 Signature Algorithm

Algorithm Steps:

PHP Signature Code Example

Request Parameters

Request Code Samples

Success Response Example (200 OK)

Request Parameters

Request Code Samples

Payout Success Response Example

Request Code Samples

Response Structure

Request Code Samples

Request Code Samples

Response Structure Example

8. Webhook Callback Specification

Webhook JSON Body Sent to Your Server

Merchant Response Requirement

Webhook Server Implementation Samples

9. Notice of Recall Notification

Recall Payload Format

Recall Handler Samples

10. E-Commerce Extensions

WooCommerce / WordPress

Shopify Web Widget