💳 PayRails Merchant PayIn Integration Guide

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

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

Follow this sequence for every PayIn transaction.

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

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

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

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=...

A PayIn transaction transitions through these states after creation.

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..."
}

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

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

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-20260708121213",
    "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

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.