Merchant API Documentation

This documentation is for your branded gateway only. It does not expose underlying provider names. Upstream responses are normalized into gateway statuses before they are returned to merchants.

Authentication

X-API-Key: MERCHANT_API_KEY

Every merchant receives an API key and API secret from the dashboard. The API key is used for create-order, status, and report APIs. The API secret is used to verify merchant callback signatures.

Activation checklist

1. Merchant account must be active.
2. Admin must assign a marketplace code.
3. Merchant must register an IP.
4. Admin must approve at least one API IP.
5. Admin must enable API access.
6. For payout, available balance must be sufficient.
7. Min and max payout limits must be satisfied.

Create order

POST https://www.xpayout.org?route=api_create_order

Headers:
X-API-Key: MERCHANT_API_KEY
Content-Type: application/json

Payin body:
{
  "service_type": "payin",
  "order_id": "MERCHANT_PAYIN_10001",
  "reference_id": "REF10001",
  "amount": 1200.50,
  "currency": "INR",
  "customer_name": "Test User",
  "customer_email": "user@example.com",
  "customer_mobile": "9876543210",
  "callback_url": "https://merchant.example/callback",
  "meta": {"note": "first payin"}
}

Payout body:
{
  "service_type": "payout",
  "order_id": "MERCHANT_PAYOUT_10001",
  "reference_id": "PREF10001",
  "amount": 100.00,
  "currency": "INR",
  "customer_name": "Beneficiary Name",
  "customer_email": "beneficiary@example.com",
  "customer_mobile": "9876543210",
  "callback_url": "https://merchant.example/callback",
  "meta": {
    "mode": "imps",
    "account_number": "1234567890",
    "ifsc": "SBIN0001808",
    "bank_name": "State Bank of India",
    "beneficiary_firstname": "Ajah",
    "beneficiary_lastname": "Syshus"
  }
}

Create order response example

{
  "ok": true,
  "message": "Order created",
  "data": {
    "gateway_order_id": "GW202604071234567890",
    "merchant_order_id": "MERCHANT_PAYOUT_10001",
    "reference_id": "PREF10001",
    "status": "processing",
    "amount": "100.00",
    "fee_amount": "10.00",
    "gst_amount": "1.80",
    "total_debit": "111.80",
    "provider_reference": "",
    "utr": ""
  }
}

Gateway status mapping

success    Final success
processing In progress / pending confirmation
failed     Final failure
reversed   Reversed after prior success

The gateway stores the upstream provider code in provider_status_code and the raw upstream message in provider_message, but merchants should rely on the normalized gateway status.

Common failed responses

{
  "ok": false,
  "message": "Source IP is not approved"
}

{
  "ok": false,
  "message": "Insufficient available balance"
}

{
  "ok": false,
  "message": "Amount above payout maximum"
}

{
  "ok": false,
  "message": "Duplicate merchant order ID or reference ID"
}

Check order status

GET https://www.xpayout.org?route=api_order_status&api_key=MERCHANT_API_KEY&merchant_order_id=MERCHANT_PAYOUT_10001

GET https://www.xpayout.org?route=api_order_status&api_key=MERCHANT_API_KEY&order_id=GW_ORDER_ID

Get balance

GET https://www.xpayout.org?route=api_balance&api_key=MERCHANT_API_KEY

Provider callback URL

https://www.xpayout.org?route=api_callback

Your upstream provider should notify this URL. The gateway then updates the order and forwards the final status to the correct merchant callback URL configured inside the merchant account.

Merchant callback payload

{
  "order_id": "GW202604071234567890",
  "merchant_order_id": "MERCHANT_PAYOUT_10001",
  "reference_id": "PREF10001",
  "status": "failed",
  "amount": "100.00",
  "fee_amount": "10.00",
  "gst_amount": "1.80",
  "total_debit": "111.80",
  "currency": "INR",
  "provider_reference": "ABC123",
  "provider_status_code": "RV200",
  "provider_message": "Transaction failed or successful message from gateway",
  "utr": "473102263110",
  "updated_at": "2026-04-07 11:30:00"
}

Merchant callback signature

Header: X-Gateway-Signature = HMAC SHA256 of the JSON body using the merchant API secret.

Download reconciliation report

GET https://www.xpayout.org?route=api_download_report&api_key=MERCHANT_API_KEY

The report includes gateway order ID, merchant order ID, marketplace code, provider reference, fee, GST, total debit, status, created time, and updated time.