Developer API Documentation

1

Overview & Authentication

The Zyx Pay API allows you to initiate automated customer checkouts, verify completed payments, and receive real-time webhook notifications. All requests must use HTTPS and include your Merchant API Key.

Authentication Header

Provide your API key either as a standard HTTP header or directly in the JSON POST payload:

X-API-KEY: zyx_live_your_secret_api_key_here

You can obtain your live API key from your Merchant Dashboard → API & Webhooks.

2

Create Payment Request

POST /api/payment/create

Initiate a payment request. The API responds with a secure, hosted checkout link (payment_url). Redirect your customer to this URL to complete payment via bKash, Nagad, Rocket, or Upay.

Request Parameters (JSON Body)

Field	Type	Requirement	Description
api_key	string	Required	Your Merchant API Key (or pass via `X-API-KEY` header).
amount	number	Required	The payable amount in BDT (e.g. `500.00`).
order_id	string	Required	Your store's unique internal order reference ID (e.g. `INV-84920`).
customer_email	string	Optional	Customer's email address for receipt delivery.
customer_phone	string	Optional	Customer's phone number (e.g. `017XXXXXXXX`).
success_url	string	Optional	Redirect URL when payment is verified successfully.
cancel_url	string	Optional	Redirect URL if the customer cancels the payment.

Sample Implementation

curl -X POST "https://zyxpay.cyou/api/payment/create" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "amount": 1500.00,
    "order_id": "ORD-1004",
    "customer_email": "customer@example.com",
    "customer_phone": "01700000000",
    "success_url": "https://yourwebsite.com/payment/success",
    "cancel_url": "https://yourwebsite.com/payment/cancel"
  }'

<?php
$payload = [
    'api_key' => 'YOUR_API_KEY',
    'amount' => 1500.00,
    'order_id' => 'ORD-1004',
    'customer_email' => 'customer@example.com',
    'customer_phone' => '01700000000',
    'success_url' => 'https://yourwebsite.com/payment/success',
    'cancel_url' => 'https://yourwebsite.com/payment/cancel'
];

$ch = curl_init('https://zyxpay.cyou/api/payment/create');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

if (!empty($response['payment_url'])) {
    header('Location: ' . $response['payment_url']);
    exit;
}
?>

const axios = require('axios');

async function initiatePayment() {
  const { data } = await axios.post('https://zyxpay.cyou/api/payment/create', {
    amount: 1500.00,
    order_id: 'ORD-1004',
    customer_email: 'customer@example.com',
    customer_phone: '01700000000',
    success_url: 'https://yourwebsite.com/payment/success',
    cancel_url: 'https://yourwebsite.com/payment/cancel'
  }, {
    headers: { 'X-API-KEY': 'YOUR_API_KEY' }
  });

  if (data.status === 1) {
    console.log('Redirect user to:', data.payment_url);
  }
}

import requests

url = "https://zyxpay.cyou/api/payment/create"
headers = {"X-API-KEY": "YOUR_API_KEY", "Content-Type": "application/json"}
payload = {
    "amount": 1500.00,
    "order_id": "ORD-1004",
    "customer_email": "customer@example.com",
    "customer_phone": "01700000000",
    "success_url": "https://yourwebsite.com/payment/success",
    "cancel_url": "https://yourwebsite.com/payment/cancel"
}

res = requests.post(url, json=payload, headers=headers).json()
if res.get("status") == 1:
    print("Redirect to checkout:", res["payment_url"])

Success Response (200 OK)

{
  "status": 1,
  "message": "Payment session initialized successfully",
  "transaction_id": "TRX_9A8B7C6D5E",
  "payment_url": "https://zyxpay.cyou/pay/TRX_9A8B7C6D5E",
  "amount": 1500.00
}

3

Verify Payment Request

POST /api/payment/verify

Verify the current status and settlement confirmation of any transaction before fulfilling digital orders or granting user access.

cURL Example

curl -X POST "https://zyxpay.cyou/api/payment/verify" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "transaction_id": "TRX_9A8B7C6D5E"
  }'

Verified Response (200 OK)

{
  "status": 1,
  "transaction_id": "TRX_9A8B7C6D5E",
  "order_id": "ORD-1004",
  "amount": 1500.00,
  "trx_id": "9H8B7F6D",
  "payment_method": "bkash",
  "sender_number": "017XXXXXXXX",
  "payment_status": "completed",
  "completed_at": "2026-10-13 00:25:10"
}

4

Payment Status Polling

GET /api/pay-status

Lightweight real-time check endpoint used by front-end clients to poll transaction status without exposing merchant API keys:

GET https://zyxpay.cyou/api/pay-status?id=TRX_9A8B7C6D5E

5

No-Code Hosted Payment Links & QR Codes

If you don't want to write API code, you can generate Payment Links directly from your merchant dashboard. Each link provides:

Shareable URL

Send directly on WhatsApp, Facebook, email, or invoice: https://zyxpay.cyou/pay-link/pl_...

Instant QR Code

Customers can scan using their phone camera to open the payment page immediately.

Single or Multi-Use

Choose between multi-use links for general products or single-use links that mark settled once paid.

Go to Payment Links Manager →

6

Instant Server Webhooks (IPN)

When an SMS arrives on your connected Android phone and matches a customer transaction, Zyx Pay instantly sends an HTTP POST request to your configured webhook_url.

Webhook POST Payload Format

{
  "event": "payment.completed",
  "transaction_id": "TRX_9A8B7C6D5E",
  "order_id": "ORD-1004",
  "amount": 1500.00,
  "payment_method": "bkash",
  "trx_id": "9H8B7F6D",
  "sender_number": "017XXXXXXXX",
  "status": "completed",
  "timestamp": "2026-10-13 00:25:10"
}

Recommended PHP Webhook Receiver

<?php
// webhook.php on your server
$raw = file_get_contents('php://input');
$data = json_decode($raw, true);

if (!empty($data) && $data['status'] === 'completed') {
    $orderId = $data['order_id'];
    $trxId = $data['trx_id'];
    $amount = (float)$data['amount'];

    // Update your database: Mark order paid
    // e.g., updateOrderStatus($orderId, 'paid', $trxId);

    // Respond with 200 OK
    http_response_code(200);
    echo json_encode(['status' => 'received']);
    exit;
}

http_response_code(400);
echo "Invalid payload";
?>

7

Handling Cancelled Payments (cancel_url)

When a customer clicks Cancel / বন্ধ করুন or closes the hosted bKash or Nagad checkout page, Zyx Pay cancels the session and automatically redirects the customer back to your configured cancel_url (e.g. https://yourstore.com/cancel or fallback https://zyxpay.cyou/cancel).

Cancel Redirect Query Parameters

The redirect URL appends complete context so your application can restore the customer's shopping cart or offer another payment option:

GET https://yourstore.com/cancel?transaction_id=TRX_9A8B7C6D5E&order_id=ORD-1004&amount=1500.00&status=cancelled

Parameter	Type	Description
transaction_id	string	Unique Zyx Pay transaction ID (e.g. `TRX_9A8B7C6D5E`)
order_id	string	Your internal order reference passed during payment creation
amount	numeric	The order amount in BDT
status	string	Always returns `cancelled`

Example PHP Cancel Handler

<?php
// cancel.php on your e-commerce store
$orderId = $_GET['order_id'] ?? null;
$trxId   = $_GET['transaction_id'] ?? null;
$status  = $_GET['status'] ?? null;

if ($status === 'cancelled') {
    // 1. Release reserved cart stock or mark order abandoned
    // 2. Show friendly message to customer with retry checkout button:
    echo "<h1>Payment was cancelled</h1>";
    echo "<p>Order #" . htmlspecialchars($orderId) . " has not been charged.</p>";
    echo "<a href='/checkout?order=" . urlencode($orderId) . "'>Try Again</a>";
}
?>

8

Mobile Android App Sync

The Zyx Pay Mobile Sync App installs on any Android phone (Android 5.0 through 14+) receiving bKash, Nagad, Rocket, or Upay payment notification SMS.

1. One-Click QR Connect

Open the app, tap Scan QR, and point the camera at your dashboard QR code. Your Device Key and API endpoint configure instantly.

2. Real-Time SMS Listener

When SMS arrives from 16247 (bKash) or 16167 (Nagad), the app parses the TrxID and posts it to /api/add-data within 300ms.

Download Verified Android App (.apk)

9

Drop-in PHP Client Class

Copy and paste this helper class into any PHP project to integrate payments in under two minutes:

<?php
class ZyxPay {
    private $apiKey;
    private $baseUrl = 'https://zyxpay.cyou/api';

    public function __construct($apiKey) {
        $this->apiKey = $apiKey;
    }

    public function createPayment($amount, $orderId, $successUrl, $cancelUrl, $email = '', $phone = '') {
        $data = [
            'amount' => $amount,
            'order_id' => $orderId,
            'customer_email' => $email,
            'customer_phone' => $phone,
            'success_url' => $successUrl,
            'cancel_url' => $cancelUrl
        ];
        return $this->request('/payment/create', $data);
    }

    public function verifyPayment($transactionId) {
        return $this->request('/payment/verify', ['transaction_id' => $transactionId]);
    }

    private function request($endpoint, $payload) {
        $ch = curl_init($this->baseUrl . $endpoint);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Content-Type: application/json',
            'X-API-KEY: ' . $this->apiKey
        ]);
        $res = curl_exec($ch);
        curl_close($ch);
        return json_decode($res, true);
    }
}
?>

Zyx Pay Integration Guide