💳 PayRails Merchant PayIn Integration Guide

Live API console — authenticate, test, and explore the PayRails PayIn 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_KEYCopy

⚡ Quick Start

Everything you need to accept your first UPI payment in under 5 minutes.

🔄 Integration Flow

Follow this sequence for every PayIn transaction.

📤 Create Transaction API

Initiates a UPI payment session. Returns a upi_intent_url that the merchant redirects the customer to.

Request Body

The live form below creates a real transaction using this exact endpoint.

🚀 Live Demo

Enter an amount below and click Create UPI Transaction to execute a real API call. All debug panels below will populate with live data.

📱 UPI Intent URL

The upi_intent_url field in the response is a deep link that opens the customer's UPI app directly. It follows the standard upi://pay?... URI scheme.

upi://pay?pa=...&pn=...&am=...&tr=...&tn=...Copy

♻️ Transaction Status Lifecycle

A PayIn transaction transitions through these states after creation.

🔔 Webhook

PayRails sends a webhook to your configured callback URL when a transaction reaches a terminal state (SUCCESS, FAILED, CANCELLED/EXPIRED). Configure your callback URL in the PayRails merchant settings.

{
  "transaction_id":  "internal-uuid",
  "merchant_txn_id": "YOUR-REF-001",
  "status":          "SUCCESS",
  "amount":          "100",
  "currency":        "INR",
  "provider":        "razorpay",
  "provider_txn_id": "pay_xxxxx",
  "bank_reference":  "HDFC123456",
  "failure_code":    null,
  "failure_reason":  null,
  "completed_at":    "2026-07-08T..."
}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 →

⚠️ Error Reference

All errors from the PayIn backend. Every entry is verified from the actual implementation.

💻 cURL Reference Example

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

Create UPI Transaction

curl -X POST \
  'https://api.payrails.in/api/v1/transactions' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "merchantTxnId": "ORDER-20261104112600",
    "amount": 100,
    "paymentMethod": "UPI",
    "customer": {
      "name": "Customer Name",
      "email": "customer@example.com",
      "mobile": "9876543210"
    },
    "s2s_client_ip": "1.2.3.4",
    "s2s_device_info": "Mozilla/5.0 ..."
  }'Copy

✅ Production Checklist

Verify each item before going live with PayRails PayIn API.

• Store your x-api-key securely on the server. Never expose it in frontend JavaScript or mobile apps.
• Generate a unique merchantTxnId for every transaction (e.g. your internal order ID).
• Persist the transaction_id returned by the Create Transaction response immediately.
• Redirect the customer to upi_intent_url — do not attempt to parse or modify it.
• On desktop, generate a QR code from upi_intent_url rather than showing the raw URL.
• Never confirm an order based on a browser redirect alone. Always wait for the webhook.
• Configure a publicly accessible webhook URL in your PayRails merchant settings.
• Your webhook handler must return HTTP 200 within the timeout window to prevent retries.
• Implement idempotency in your webhook handler using transaction_id to prevent double-fulfilment.
• Handle FAILED correctly: log failure_reason and prompt the customer to retry.
• Handle PENDING state: show a waiting indicator. Do not fulfil the order yet.
• Handle CANCELLED: the payment window expired. Allow the customer to initiate a new transaction.
• Use bank_reference from the SUCCESS webhook for payment reconciliation.
• Implement exponential backoff on HTTP 5xx responses before retrying a failed request.