Configure Webhooks for Payment Callbacks

Configure your callback URL before processing live transactions. When a collection transaction reaches a terminal state, bluSwap sends a POST request with a JSON payload to that URL — so your system receives the final payment outcome in real time without polling the status endpoint.

How It Works

bluSwap sends a POST request to your registered callback URL with a Content-Type: application/json header. Your endpoint must return a 2xx response to acknowledge receipt. Configure your callback URL from your bluSwap merchant dashboard before going live.

Treat an initiated payment as pending. Fulfil the order only after receiving a SUCCESS status via webhook or the status endpoint.

Webhook Payload

Examples

Successful Transaction
Failed Transaction

{
    "RRN": "662273803542",
    "amount": "399.0",
    "ref_id": "xxxxxxxxxxx",
    "status": "SUCCESS",
    "currency": "INR",
    "order_id": "xxxxxxxxx",
    "created_at": "2026-02-27 01:02:53",
    "updated_at": "2026-02-27 01:03:08",
    "payment_mode": "INTENT",
    "account_type": "N/A",
    "card_network": "N/A",
    "status_description": "Transaction completed successfully"
}

{
    "RRN": null,
    "amount": "1799.0",
    "ref_id": "xxxxxxxxx",
    "status": "FAILED",
    "currency": "INR",
    "order_id": "xxxxxxxx",
    "created_at": "2026-02-26 23:48:52",
    "updated_at": "2026-02-26 23:53:54",
    "payment_mode": "INTENT",
    "account_type": "N/A",
    "card_network": "N/A",
    "status_description": "Transaction failed: TXN NOT COMPLETED"
}

Payload Fields

String

Your unique internal transaction ID, exactly as provided when the collection was initiated.

String

The transaction amount (e.g., "399.0").

String

Terminal state of the transaction. Either SUCCESS or FAILED.

String

Retrieval Reference Number — the bank’s unique identifier for this transaction. Populated on successful transactions only; null on failure.

String

bluSwap’s unique internal reference ID for this transaction.

String

The payment method used to complete the transaction (e.g., INTENT, QR, VPA).

String

Human-readable details about the success or failure of the transaction.

String

Timestamp (IST) when the transaction was first initiated (e.g., "2026-02-27 01:02:53").

String

Timestamp (IST) when the transaction reached its final status (e.g., "2026-02-27 01:03:08").

String

Source account type from which the payment was made (e.g., SAVINGS, DEBIT_CARD).

String

The card network provider (e.g., VISA, MASTERCARD). Returns N/A for UPI transactions.

String

ISO 4217 currency code for the transaction (e.g., INR).

Get Started

Collections

Payouts

Refunds

Configure Webhooks for Payment Callbacks

How It Works

Webhook Payload

Examples

Payload Fields

​How It Works

​Webhook Payload

​Examples

​Payload Fields

How It Works

Webhook Payload

Examples

Payload Fields