Skip to main content

It is extremely important for you to keep the status of the payments and refunds updated on your server so you can reliably provide goods or services to your customers. There are two ways in which you can fetch the status of the transaction from Nimbbl. First, you can setup webhooks where Nimbbl can proactively inform your system when a status changes at the Nimbbl end. Second, you can call an API to fetch the latest status of a transaction.

We recommend using a combination both methods judiciously to keep your system updated reliably and efficiently.

Consuming Webhooks​

This is the easiest and the most efficient way of getting updated by Nimbbl. As soon as the status of a transaction is updated on Nimbbl, we will let your system know by way of hitting a webhook URL shared by you.

Webhook Retries, Idempotent Checks, Order of Events​

While webhooks work very well in keeping your system updated, you should be mindful of the following while building your logic to consume webhooks

  • You need to handle checks for idempotency i.e. if you receive the same webhook twice, you should be able to handle it in your code
  • Nimbbl doesn't guarantee the order in which you receive the webhooks
  • If a webhook cannot be delivered (non 200 response from your URL), we will attempt it 4 more times before

Subscribing to Webhook Events​

Webhook gets called on certain events which can be customized in the merchant dashboard. When any of the events get triggered, We send an HTTP POST payload in JSON format to the webhook URL which is configured by you.

The following events are supported

EventDescription
payment_successThis event is triggered when the payment status becomes suceeded
payment_failedThis event is triggered when the payment status becomes failed
payment_reversingThis event is triggered when the payment status becomes reversing
payment_reversedThis event is triggered when the payment status becomes reversed
refund_successThis event is triggered when the refund status becomes suceeded
refund_failedThis event is triggered when the refund status becomes failed
refund_pendingThis event is triggered when the refund status becomes pending

You can set up webhooks for test mode as well as live mode. Test webhooks will only receive events from your test transactions and live webhooks will only receive events from your live transactions.

You can set up different webhook URLs for different events. To setup webhooks, please send the webhook URL that needs to be configured to help@nimbbl.biz.

IMPORTANT
  • The URL should be https and must accept POST requests
  • The URL should return a 200 HTTP response on receiving the webhook
  • Ensure that the URL is publicly accessible and is not blocked by a firewall
  • If you need to whitelist our IP to hit this URL, please reach out to us and we will provide our IP address

Payload for Webhook Events​

{
    "event_type": "payment_success",
    "status": "success",
    "message": "Payment Successful",
    "nimbbl_order_id": "<Order_ID>",
    "nimbbl_transaction_id": "<Transaction_ID>",
    "transaction": {
        "transaction_id": "<Transaction_ID>",
        "payment_partner": "<Payment Partner>",
        "status": "succeeded",
        "sub_payment_mode": { // sub_payment_mode object will be different for each payment_mode
            "bank_name": "<Bank Name>"
        },
        "psp_transaction_id": "<Pay_ID>",
        "payment_mode": "Netbanking",
        "nimbbl_consumer_message": "",
        "nimbbl_merchant_message": "",
        "nimbbl_error_code": "",
    "transaction_currency": "<ISO_4217 Alpha-3 format currency>",
        "transaction_amount": <Transaction amount with upto 2 decimal>,
        "additional_charges": <Convenience Fee>,
        "offer_discount": <Offer discount>,
        "offer_id": "<Offer id from Nimbbl system>",
        "transaction_type": "payment",
        "signature": "<nimbbl_signature>",
        "signature_version": "v3"
    },
    "order": {
        "order_date": "<Date in yyyy-mm-dd hh:mm:ss format>",
        "amount_before_tax": <Amount before tax>,
        "tax": <Tax amount>,
        "total_amount": <Total Amount>,
        "referrer_platform": "<Integration Platform used>",
        "referrer_platform_version": "<Integration Platform version>",
        "invoice_id": "<Merchant invoice id>",
        "attempts": <#Transactions for the order>,
        "device_user_agent": "<User Agent>",
        "status": "completed",
        "currency": "<ISO_4217 Alpha-3 format currency>",
        "description": "",
        "cancellation_reason": "",
        "additional_charges": 0,
        "grand_total": <total_amount - offer_discount + additional_charges>,
        "offer_discount": 0,
        "refund_details": { // this field will only come when the order_status is `completed`. This object will have all the refund details for the order.
            "refundable_currency": "INR", 
            "available_refundable_amount": 5.0, 
            "refunded_amount": 0.0, 
            "total_refundable_amount": 5.0 
        },
        "currency_conversion": { // this object is sent only if the transaction currency was changed.
            "original_currency": "USD",
            "converted_currency": "INR", 
            "exchange_rate": 100.0, 
            "conversion_reason": "ALTERNATE_CURRENCY_CONFIG", 
            "original_amount_before_tax": 8.0,
            "original_tax": 2.0, 
            "original_total_amount": 10.0
        },
        "custom_attributes": [{
                "key_1": "val_1"
            },
            {
                "key_2": "val_2"
            }
        ],
        "device": {
            "browser_name": "Chrome",
            "device_name": "Other",
            "os_name": "Windows",
            "ip_address": "127.0.0.1"
        }
    },
    "nimbbl_signature": "<Nimbbl signature>",
    "psp_raw_response": { 
        // psp_raw_response object will be different for each payment_partner
    }, 
    "user": {
        "email": "test@gmail.com",
        "mobile": "9121212121",
        "name": "Shakthiman",
        "user_id": "<user_ID>"
    }
}

Performing Transaction Enquiry​

If you want to proactively fetch the status of a single transaction from Nimbbl then you can use the Enquiry API. If the transaction is pending at Nimbbl, we will attempt to fetch the latest status from the payment provider.

The following endpoint performs the enquiry:

MethodEnd Point
POST/v3/transaction-enquiry

To read in detail about the request, response, sample payloads and error scenarios for this API, please click here.