💸 PayRails Merchant Payout Integration Guide

Live API console — authenticate, test, and explore the PayRails Payout API in real time.

🚀 Merchant Onboarding Journey

The complete path from zero to a production-ready PayRails integration — including webhook authentication, which is documented in full further down this page.

🔑 API Keys

API keys are managed from your PayRails merchant Dashboard under Developer Settings → API Keys. This section mirrors exactly what you will see there so you know what to expect before you go looking for it.

Generating a key

Click Generate API Key, choose an environment (sandbox, staging, or prod) and an optional label, then click Generate. The dashboard then shows:

Click Copy or Download, then I have saved this key to dismiss the dialog. The plaintext key is never displayable again after this point — if you lose it, generate a new one and revoke the old one.

Revoking a key

Click Revoke next to any active key. You will be asked to confirm:

Once generated, use the key exactly as shown in the Authentication section above — in the x-api-key header on every request.

🔐 Authentication

Content-Type: application/json
Accept: application/json
x-api-key: YOUR_API_KEY
X-Idempotency-Key: <uuid>  ← recommendedCopy

🔄 Integration Flow

Follow this sequence for every payout.

⚡ Quick Start

Everything you need to send your first payout in under 5 minutes.

🛡️ Submission Guarantees & Status Retrieval

Understanding what happens after you submit a payout request — especially when you do not receive a response.

GET /payouts/status?merchant_ref=ORDER12345Copy

HTTP 409
DUPLICATE_MERCHANT_REFERENCECopy

📬 Merchant Callback Behaviour

PayRails sends callbacks whenever a payout reaches a meaningful lifecycle event. Callbacks contain the latest payout status together with reconciliation information available at that moment.

{
  "platform_request_id":   "PRQ...",
  "platform_payout_id":    "PPX...",
  "merchant_ref":          "ORDER12345",
  "status":                "SUCCESS",
  "amount":                1000,
  "currency":              "INR",
  "fee_amount":            5,
  "mode":                  "IMPS",
  "provider_code":         "bank_provider",
  "provider_payout_id":    "TXN98765",
  "provider_reference":    "IMPS/1234567",
  "bank_reference_number": "123456789012",
  "provider_completed_at": "2026-07-10T14:32:00Z",
  "failure_reason":        null,
  "timestamp":             "2026-07-10T14:32:05Z"
}Copy

🔗 Configure Callback URLs

Callback URLs are managed from your PayRails merchant Dashboard under Developer Settings → Webhook Callback. PAYIN and PAYOUT each have their own, independently configured callback URL (selected via a PAYIN / PAYOUT tab in the dashboard).

In the dashboard: select the PAYIN or PAYOUT tab, click Edit callback URL (or Configure if none is set yet), enter your URL, and click Save. If the URL fails validation the dashboard shows the exact rejection reason inline (for example, a malformed URL or a blocked/private address) — fix the URL and save again.

Once saved, the dashboard displays your current callback URL together with its type and the date it was registered, and offers Edit callback URL and Refresh actions.

Testing with the Callback Lab

While integrating, you can temporarily point your callback URLs at this portal's built-in Callback Lab to inspect real deliveries — headers, raw body, parsed JSON, and HMAC verification result — before your own endpoint is ready:

Developer Settings walkthrough

After saving: perform a test transaction (PayIn or Payout), open this Integration Portal, find the delivery in the Callback Inspector, verify its HMAC signature, compare the payload against the HMAC guide, and then update your own production implementation to match — finally, switch the callback URL over to your real endpoint once it's ready.

For the exact delivery behaviour (HTTP method, retry policy, expected response code, payload shape), see the Webhook section further down this page — that content is unchanged and still applies.

🔐 Webhook Authentication

Managed from your PayRails merchant Dashboard under Developer Settings → Webhook Authentication (PAYIN / PAYOUT tabs, same as Callback URL). This section documents the metadata and actions available there, exactly as they behave in the dashboard.

Metadata shown

Rotate Secret

Click Rotate Secret. The dashboard asks you to confirm:

On confirmation, a new secret is generated immediately and shown exactly once:

Copy it, then click I have saved this secret. The previous secret (the one just replaced) remains valid for a 48-hour grace period — both the old and new secret will successfully verify signatures during that window, so you can redeploy your verifier with the new secret without dropping any in-flight callbacks.

Revoke Previous Secret

If you need to immediately invalidate the previous secret before its grace period naturally expires (for example, suspected compromise), click Revoke Previous Secret. This button is disabled with the tooltip "There is no previous secret to revoke." when there is nothing to revoke (i.e. you have never rotated, or the grace period already ended). Confirmation dialog:

The full HMAC signing scheme — headers, exact signing formula, and a PHP verification sample that supports both the current and previous secret — is documented in the HMAC Signature Verification section below.

🛡️ HMAC Signature Verification

Every signed callback includes an HMAC-SHA256 signature so you can verify it genuinely came from PayRails and was not tampered with in transit. This section is the authoritative reference for implementing that verification yourself. The PayIn and Payout Callback Labs (or the shared /callback-example.php) are working, runnable implementations of everything below.

Headers sent with a signed callback

Exact signing formula

signing_input = raw_request_body + "." + X-Payrails-Timestamp + "." + X-Payrails-Event-Id
signature     = hex( HMAC_SHA256( secret, signing_input ) )
header value  = "v1=" + signatureCopy

PHP verification sample

Supports both the current and previous secret (for the 48-hour rotation grace period described in Webhook Authentication above). Uses hash_equals() for a timing-safe comparison — never compare signatures with == or ===.

<?php
// 1. Read the RAW body — never $_POST.
$rawBody = file_get_contents('php://input');

// 2. Read the PayRails headers.
$headers   = getallheaders();
$signature = $headers['X-Payrails-Signature'] ?? '';   // "v1=<hex>"
$timestamp = $headers['X-Payrails-Timestamp'] ?? '';
$eventId   = $headers['X-Payrails-Event-Id']  ?? '';

if (!preg_match('/^v1=([0-9a-f]{64})$/', $signature, $m)) {
    http_response_code(400);
    exit('Missing or malformed signature');
}
$providedHex = $m[1];

// 3. Rebuild the exact signing input.
$signingInput = $rawBody . '.' . $timestamp . '.' . $eventId;

// 4. Try the current secret, then the previous secret (grace period).
$currentSecret  = getenv('PAYRAILS_WEBHOOK_SECRET_CURRENT');
$previousSecret = getenv('PAYRAILS_WEBHOOK_SECRET_PREVIOUS'); // may be empty

$verified = false;
foreach (array_filter([$currentSecret, $previousSecret]) as $secret) {
    $expectedHex = hash_hmac('sha256', $signingInput, $secret);
    if (hash_equals($expectedHex, $providedHex)) {
        $verified = true;
        break;
    }
}

if (!$verified) {
    http_response_code(401);
    exit('Signature verification failed');
}

// 5. Only now is it safe to decode and act on the payload.
$payload = json_decode($rawBody, true);

// ... process $payload, using transaction_id / platform_payout_id for idempotency ...

http_response_code(200);
echo json_encode(['received' => true]);Copy

Secret lifecycle

Troubleshooting

Security recommendations

🧪 Callback Lab — Live Reference Receiver

A working, runnable callback receiver you can point a real (or simulated) callback URL at to see the entire HMAC verification flow in action — not just described, but executed.

• Receives an inbound POST exactly the way your own server should — raw body via php://input, never $_POST.
• Verifies the X-Payrails-Signature using the exact formula documented above.
• Displays every received callback: Callback Type, headers, raw JSON, parsed JSON, verification status, algorithm, key version, and signature.
• Includes a Simulate Callback button so you can see a fully verified delivery even before your production callback URL is configured.

Prefer one shared endpoint for both types? Open the canonical Callback Lab →

💡 Status API Best Practices

💰 Wallet Balance API

Check your available balance before creating a payout. Attempting a payout with insufficient funds returns an error without creating any record.

{
  "currency":         "INR",
  "total_balance":    50000,
  "reserved_balance": 3000,
  "available_balance":47000,
  "payouts_enabled":  true,
  "is_frozen":        false
}Copy

The live card below calls this exact endpoint and displays your real-time balance.

Wallet balance is checked automatically before each payout creation.

📤 Create Payout API

Initiates a real-money bank transfer. The payout begins processing immediately after successful creation.

Request Body

👤 Fixed Test Beneficiary

All payouts from this console go to the beneficiary below. These values are hardcoded constants on the server and cannot be changed from the browser.

📡 Status Poll API

After creating a payout, use this endpoint to check its current status. Poll until the status reaches a terminal state.

{
  "platform_payout_id":    "PPX...",
  "platform_request_id":   "PRQ...",
  "merchant_reference":    "DEMO_...",
  "status":                "SUCCESS",
  "amount":                100,
  "currency":              "INR",
  "mode":                  "IMPS",
  "provider_reference":    "COLT12345",
  "bank_reference_number": "HDFC9876",
  "failure_reason":        null,
  "created_at":            "...",
  "updated_at":            "..."
}Copy

♻️ Payout Status Lifecycle

A payout transitions through these states. Poll the Status API until a terminal state is reached.

👤 Beneficiary Handling

In your production integration, include the beneficiary's bank details in every payout request as shown in the Create Payout API section above. The fields you need are: name, account_number, ifsc, account_type, and optionally bank_name, mobile, and email. All values are encrypted before storage and the account number is never returned in plaintext.

⚠️ Error Reference

All errors from the payout backend. Every field is from the actual implementation.

💻 cURL Reference Examples

Copy-paste ready examples. Replace YOUR_API_KEY with your actual key.

1. Check Wallet Balance

curl -X GET \\
  'https://api.payrails.in/api/v1/payouts/wallet' \\
  -H 'x-api-key: YOUR_API_KEY' \\
  -H 'Accept: application/json'Copy

2. Create Payout

curl -X POST \\
  'https://api.payrails.in/api/v1/payouts' \\
  -H 'Content-Type: application/json' \\
  -H 'Accept: application/json' \\
  -H 'x-api-key: YOUR_API_KEY' \\
  -H 'X-Idempotency-Key: unique-request-id-here' \\
  -d '{
    "amount": 100,
    "beneficiary": {
      "name": "Beneficiary Name",
      "account_number": "55550100320090",
      "ifsc": "HDFC0001234",
      "account_type": "SAVINGS",
      "bank_name": "HDFC Bank",
      "mobile": "9876543210",
      "email": "payee@example.com"
    },
    "mode": "IMPS",
    "merchant_ref": "YOUR_REF_001"
  }'Copy

3. Poll Payout Status

curl -X GET \\
  'https://api.payrails.in/api/v1/payouts/status?merchant_ref=ORDER100' \\
  -H 'x-api-key: YOUR_API_KEY' \\
  -H 'Accept: application/json'Copy

or

curl -X GET \\
  'https://api.payrails.in/api/v1/payouts/status?platform_payout_id=PPX...' \\
  -H 'x-api-key: YOUR_API_KEY' \\
  -H 'Accept: application/json'Copy

✅ Production Checklist

Verify each item before going live with PayRails Payout API.

• Store your x-api-key securely on the server. Never expose it in the browser or mobile app.
• Always call GET /payouts/wallet and verify available_balance ≥ amount before creating a payout.
• Generate a unique merchant_ref for every payout (e.g. your internal order ID).
• Generate a new cryptographically random X-Idempotency-Key for every new payout request.
• Never reuse an idempotency key from a previous payout to avoid unintended duplicates or errors.
• Persist the platform_payout_id returned by POST /payouts immediately after creation.
• Poll GET /payouts/{platform_payout_id} every 3–5 seconds until the status is terminal.
• Terminal states: SUCCESS FAILED CANCELLED EXPIRED REVERSED
• On FAILED: log the failure_reason. FAILED is a permanent terminal state — the original payout never changes. If a retry is needed, PayRails support issues a brand-new payout with a new platform_payout_id. Track the new payout independently.
• On EXPIRED: the wallet reservation is not automatically released. Contact PayRails support.
• On SUCCESS: confirm the bank_reference_number for reconciliation.
• Implement exponential backoff on HTTP 429 (rate limit: 10 payouts/60 s) and HTTP 503 responses.
• If your server has a fixed IP, configure the IP whitelist with PayRails to prevent unauthorized use of your API key.