> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Webhooks for Payment Callbacks

> Receive real-time payment status updates by configuring a callback URL. bluSwap POSTs a JSON payload to your URL when a transaction completes.

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.

> [!WARNING]
>
> Treat an initiated payment as pending. Fulfil the order only after receiving a `SUCCESS` status via webhook or the status endpoint.

## Webhook Payload

### Examples

> [tab] Successful Transaction
>
> ```json theme={"dark"}
> {
>     "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"
> }
> ```

> [tab] Failed Transaction
>
> ```json theme={"dark"}
> {
>     "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

**order\_id** `String`

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

**amount** `String`

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

**status** `String`

Terminal state of the transaction. Either `SUCCESS` or `FAILED`.

**RRN** `String`

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

**ref\_id** `String`

bluSwap's unique internal reference ID for this transaction.

**payment\_mode** `String`

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

**status\_description** `String`

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

**created\_at** `String`

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

**updated\_at** `String`

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

**account\_type** `String`

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

**card\_network** `String`

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

**currency** `String`

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.