💸 PayRails Merchant Payout Integration Guide

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

Follow this sequence for every payout.

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

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
}

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

Wallet balance is checked automatically before each payout creation.

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

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.

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

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

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.

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

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

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

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": "1234567890",
      "ifsc": "HDFC0001234",
      "account_type": "SAVINGS",
      "bank_name": "HDFC Bank",
      "mobile": "9876543210",
      "email": "payee@example.com"
    },
    "mode": "IMPS",
    "merchant_ref": "YOUR_REF_001"
  }'Copy

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

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 RETRY_PENDING REVERSED
• On FAILED: log the failure_reason. An admin can issue a retry if appropriate.
• 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.

This demo executes real payouts against the live API. To prevent exposing private banking information, the page enforces a strict two-model architecture.