Merchant API Documentation

This documentation is for your branded gateway only. Upstream provider behaviour is normalized into gateway statuses before it is returned to merchants.

Authentication

X-API-Key: MERCHANT_API_KEY
X-Timestamp: UNIX_EPOCH_SECONDS
X-Nonce: UNIQUE_REQUEST_NONCE
X-Signature: HMAC_SHA256(method + route + timestamp + nonce + sha256(body), API_SECRET)
Content-Type: application/json

HMAC is supported in off, optional, and required modes. Replay prevention uses a 5 minute timestamp window plus a one-time nonce lock per merchant and route.

Activation checklist

1. Merchant account must be active.
2. Admin must assign a marketplace code.
3. Merchant must register an API source IP.
4. Admin must approve at least one API IP.
5. Admin must enable API access.
6. Merchant must keep callback URL current.
7. For payout, wallet balance and payout limits must pass validation.

Create order

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

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

Signature example

base_string =
POST
api_create_order
1714723200
nonce_001
ecb70d326b13eabb89b986a89df22151af2dcebac3c44df54fca90a6597ebe8a

signature = hash_hmac("sha256", base_string, API_SECRET)

Order status

GET https://www.xpayout.org?route=api_order_status&merchant_order_id=MERCHANT_PAYIN_10001

Status lookup requires one non-empty identifier: order_id, gateway_order_id, merchant_order_id, or reference_id. Blank status checks are rejected to protect merchant order accuracy.

Balance

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

Report download

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

Gateway status mapping

success    final success
processing in progress / pending confirmation
failed     final failure
reversed   reversed after prior success

Merchant callback payload

{
  "order_id": "GW202604071234567890",
  "merchant_order_id": "MERCHANT_PAYOUT_10001",
  "reference_id": "PREF10001",
  "status": "failed",
  "amount": "100.00",
  "gross_amount": "100.00",
  "fee_amount": "10.00",
  "gst_amount": "1.80",
  "total_fee": "11.80",
  "total_debit": "111.80",
  "total_cost": "111.80",
  "net_amount": "100.00",
  "beneficiary_receives": "100.00",
  "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

The gateway sends X-Gateway-Signature, X-Timestamp, and X-Callback-Id. The signature is HMAC SHA256 of the JSON body using the merchant webhook secret when configured, with the API secret retained as a legacy fallback.

Signed payment links

Customer-facing payment URLs can point to a branded signed route first. The route expires and rejects tampering before forwarding to the upstream collection page.

Provider callback URL

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