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
  • Once the webhook is sent, our system expects a 200 response from your server. If we do not receive 200 response within 15 seconds, we will retry sending the webhooks 5 more times in the below mentioned intervals -
AttemptRetry time since last attemptRetry interval after first webhook is sent
Attempt 125 seconds25 seconds
Attempt 210 minutes10 minutes 25 seconds
Attempt 31 hour1 hour 10 minutes 25 seconds
Attempt 46 hours7 hours 10 minutes 25 seconds
Attempt 516 hours23 hours 10 minutes 25 seconds
IMPORTANT
  • Nimbbl supports only 1 webhook url to be configured for all the events, you cannot configure multiple webhook URL for each event.

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",
        "payment_mode": <Payment Mode>,
        "sub_payment_mode": { 
            // sub_payment_mode object will be different for each payment_mode

            // Payment Mode = "Netbanking"
            "bank_name": "<Bank Name>",

            // Payment Mode = "Wallet"
            "wallet_name": "<Wallet Name>",

            // Payment Mode = "UPI"
            "upi_id": "Vpa Id",
            "upi_holder": "Vpa Holder",
            "upi_app_name": "Vpa App Name",
            "upi_instrument": "Upi Instrument",
            "upi_flow": "<Intent, Collect, QR>",

            // Payment Mode = "<Credit Card, Debit Card, Prepaid Card>"
            "card_input_type": "<Card Input Type>", // merchant_network_token, nimbbl_token_id, card_pan
            "issuer": "<Issuer>",
            "card_type": "<Card Type>",
            "scheme": "<Card Network>",
            "masked_card": "<Masked Card>", // Only if card_input_type is "card_pan" and "merchant_network_token"  
            "expiry": "<Card Expiry>", // Only if card_input_type is "card_pan" and "merchant_network_token"  
            "card_holder": "<Card Holder Name>", // Only if card_input_type is "card_pan" and "merchant_network_token"  
            "network_token": "<Network Token>",  // Only if card_input_type is "merchant_network_token"  
            "nimbbl_token_id": "<Nimbbl Token Id>",  // Only if card_input_type is "nimbbl_token_id"
            

            // Payment Mode = "<Credit Card EMI, Debit Card EMI>"
            "emi": {
                "issuer_code": "<Issuer Code>",
                "card_network_code": "<Card Network Code>",
                "card_input_type": "<Card Input Type>", // merchant_network_token, nimbbl_token_id
                "masked_card": "<Masked Card>",
                "card_holder": "<Card Holder Name>",

                "subvention_type": "<Subvention Type>", 
                "installment_amount": "<Formatted Installment Amount>",
                "interest_discount": "<Formatted Interest Discount>",
                "cashback_amount": "<Formatted Cashback Amount>",
                "tenure": "<EMI Tenure>",
                "frequency": "<EMI Frequency>",

                "processing_fee_data": {
                    "fee": "<Formatted Processing Fee>",
                    "gst_exclusive": "<GST Exclusive>"
                },

                "interest_amount": "<Formatted Interest Amount>",
                "interest_rate": "<Formatted Interest Rate>",
                "subvented_interest_rate": "<Formatted Subvented Interest Rate>",
                "network_token" : "<Network Token>", // Only if card_input_type is merchant_network_token
                "nimbbl_token_id" : "<Nimbbl Token Id>", // Only if card_input_type is nimbbl_token_id
            }
        },
        "psp_transaction_id": "<Pay_ID>",
        "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.