Skip to main content

Webhooks and Transaction Enquiry

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
Best Practice

Return HTTP 200 immediately after validating the signature. Process the webhook payload (database updates, fulfillment, notifications) after sending the response. This ensures Nimbbl receives your acknowledgement well within the 15-second window and avoids unnecessary retries.

Webhook URL Configuration

A single webhook URL can receive multiple event types, but each event type can only be mapped to one URL. If you need different events routed to different endpoints, configure a separate URL per event.

Subscribing to Webhook Events​

Webhook gets called on certain events which can be customized in the merchant Command Center. 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 succeeded
payment_failedThis event is triggered when the payment status becomes failed
payment_reversingThis event is triggered when the payment status becomes reversing
payment_reversal_failedThis event is triggered when the payment status becomes reversal_failed
payment_reversedThis event is triggered when the payment status becomes reversed
refund_successThis event is triggered when the refund status becomes succeeded
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 [email protected].

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​

We support both encrypted and decrypted responses for webhook events.

Unencrypted Response​

{
	"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>,
		"psp_credential_label": <Cred Label>,
		"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>,
		"shipping_charges": 0.0,
		"cod_charges": 0.0,
		"offer_discount": <Offer discount>,
		"offer_id": "<Offer id from Nimbbl system>",
		"transaction_type": "payment",
		"signature": "<nimbbl_signature>",
  		"signature_version": "v3"
	},
	"order": {
		"order_id" : <Order_ID>,
		"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.0,
		"shipping_charges": 0.0,
		"cod_charges": 0.0,
		"shipping_address": {
			"first_name": "john",
			"last_name": "doe",
			"address_id": "address_81x7BgApPVVQ6v5N",
			"address_1": "1080 Beach Mansion",
			"street": "Magic Beach Drive",
			"landmark": "Opposite Magic Mountain",
			"area": "Elyria",
			"city": "Atlantis",
			"state": "Castalia",
			"pincode": "400069",
			"address_type": "Office",
			"label": "01",
			"source": "user"
		},
		"billing_address": {
			"first_name": "john",
			"last_name": "doe",
			"address_id": "address_81x7BgApPVVQ6v5N",
			"address_1": "1080 Beach Mansion",
			"street": "Magic Beach Drive",
			"landmark": "Opposite Magic Mountain",
			"area": "Elyria",
			"city": "Atlantis",
			"state": "Castalia",
			"pincode": "400069",
			"address_type": "Office",
			"label": "01",
			"source": "user"
		},
		"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": null, 
	"user": {
		"email": "[email protected]",
		"mobile": "9121212121",
		"name": "Shakthiman",
		"user_id": "<user_ID>"
	}
}

To comply with the DPDP Act, psp_raw_response will be shared as null in webhooks due to irregular PII data formats.

Encrypted Response​

Once you decrypt the following key encrypted_response, you will get the unencrypted response corresponding to the webhook event.

To learn more about encryption/decryption, please refer to this guide.

{
    "encrypted_response": "3164351ca6195e9871cca9de3117cb8f1e3cd01c984796dc79a252206cd4532994a6dd1dfcd1f3aac92ad834a49b2f1823b7092535bc6f92401223e2598b31781646339ecdd5d1f219bed267f69c5ef8c26f78fc6ef7fa2c47023f15a6343f75c7944ce1f8f26710effbbfda30fdc7385c1cd405fdbd1609d95411782fb6a62caf0104f0575ba4b68c7edb244bf60116b914e614f9c482c04172efcf0262cf7e547c25d7281d57513f76ce64069218a3a00894ee2c2be05286cfae5c0df94bb0550dfa66b743dd98885e2ae956ae93b159d6996cd3ef478480a2235e2f125ae58062bea75acdac580489a25236491a7027d1df1e38be092f49c07d402707d1b6375f0cc9a4f3e9c795912a3389d6ee45414c2ed34d0e61cc4667b6c50bc1e538b9a55e69ff1f90fd003040c54b70abc477cfa91f4f24c3503a1491b1b9076c5cbd8be47ab52e520b3c352e597f03568f61c36b475659081331371ce7b5e997fa916aee7c98969ee7e62453e44481170c723f1676ecc5bbc34ccccfc2ac4e5f111af3b09a5edaed242f3d11878dfa534c25841e4671c421d960ddec24b992b359c6b340073fb7961da47a39c10e01f51833852d13e4b5b2f0282277d6b3d165f4005778d92fff458a53aa48d5de948bf42ea7619277581a9cb921e43377ab5a1ac576fe0166652de79b4c4c05135926f6c96f86c2dcf28ebde91977b6cebc9a02c00dd15118f9bf47a63a355500f5303be025d3b12342a262115c105ae24f548a4cc25d879fdbb879f006cfd5f26a03ac38f3e820641124ce92864a669d1c0f24a80fb179c2c76404f6e4b5848a565f9219d9451e8a37e588cbc0502df49af523354631eaec855b79694d128d4624602b5755918a9debc46dc53fee1de166ad9fc70d6657ed969a0e56778f819da93f8286e92ed91671b2e1cd7ab7bc2065a8eec49556371d7b3df83a5246d4a45e9703730fe5a2df8bb2b0f4820bf9be5ed691acf2a0e10e842a74852c75a0cedf932a0b0c8e4ba813e02bdb1d54f1865618b4cfd4c0d9193a95c120b99fd0558bb26c258ca5ea2f58ed176e48e504dd9e9c121f67f132180f62552d0a24d3649d212c1a5ac87d44db9f94d01acfa21033d0ed4149e2a8a2ab32f401b7aaefd1f171c964f0616d556fdff82496f4cba1e552560da1e54b40afebc90b037847184c8817678af5fdbb229110b6124a0035f3f1902ff4f85c8a3c4710e674de1940758cf38727d7d7b80aa47f2fa1b5c1f7221a313a9e4d382529e27f26ef26837dcc0c3f5652988f94aa818526d79ab6192ef647db6edb878e3867445ac2381d7468ed523b87f0391f10011882435716a5c5d3c0fde6ecfbe2c0365696d8a529a09ee0954775a3c7e7f1945abc60ba05ab6537db9cdc42ae52fe0a82c05b39be924fa34b656f02c17d8f2cea7bf76d33982ba2dd3286a8cc019902b90861e9604571d6ff73a61e5e1ded40e80ff9df40a923b7cd338ec8fa0dd1a6fe7fe3991694f02379aa8e0cb523f9395946593a3c63ea0151d7ee973cfc34bcc74ea472e3ff5db678b9e3c668551ee6ea241a38666f77e520f9668863477be9699b3accaa940d1ef5ec8d206101677a1b402aa72a054245b271107f077a07d5fff171454cd3954530a0d580d69f046ac8a2ff192df8d1b6823a08012c4bd19ec52b04aeb4348c7e50eae63d36c4978a9b23ae347007502afae55394f3bceaada92398b50a95ee14a9ee13fae3b91612de40f58aa38ef4c4285833793f56d8c7e379064cbf51c0ff2ae3e90af7bd887b4d9ec488d32a8fb444c6bfa78dbc0a18467ee29c94b322367a1c70d4f23be905a8d122e16c278ab631c2cb7456e73966d71d797c3e41376a48bc0e4803ec8fb56bfae126ce5559c8e085830adab0f266ca0dcf25c2a8be9f863e5e51b735cd38e107cfdaa4a961bf1b1f4f0870372fa2a82ca0c52a3104266cdca32a77882aa11d0c77309e66671d7600951fa87c510f8643123d73cfb738f8ee5b35364921aa21c40d90cef96d4426d2d1ba7964f34282af6f51ba682ea10e4ff69f7c3e736531ebe8665ffed316f8d42d5536b3982e3261fa75b8426ab8965959a0e0ba14ceb95b9f32300888979d3c82aa7dda23fad7fa3d1108f1efa1c6f69876af973d92863b5f8e52359e52e329e105eb332906d95f8358a115772dd58d367bcfab9437544d535a60aba726aacd780c6f8c46b4e570a27ddab8118d9c1220d24163a9738b93189da7a1fb01147d80b21c0834b0b892ac68f3f6db1946c97b9e8d5734cfc1477f87dea1a1650a47904ef3658c42da4c0e1f4a1431d8a903145619dd373fb9fd301f2afb87bd941b601e550d6c295d9ef31ea53c2d1ed9eba488627bf19f24ae3d77b4272e040f867662d8bda6402750aae9b3a113160705482399ea3a402e3e50930ed05dfa9b3d13649ae3a0525ff035b739b14a50e12d77abac1585dd9bf1eb44fded8672609ccf10e8ffcc4c38b9df0f3660a81d498f25e04d095b8f95d40fa6b9da582e7a6ac429e34d3cab509ef6b62f08d49eb9f42a2b2d0a806536a348d0460ed0a3593f85ca6c436efa1c0753cd0c1037034664e07470c5ec5d98704f33827db4c37865d0a4c49e5900bc899dbd972da764a573b2c8531687d8beccdf33c7d9a358fa85b5ac405f621545b48fa62c83fcf0bd3e914ed6ac9427d5093dc621538aa3aae9e5dea7ab105bbd901de4d3de1935776b7f45e280b5a4ea14be31f037b513902d0c47ef02279611390037c00807d3fc6b5477aa5018de21a4514744f9cb9f366e2c9d639a4d6e446d16732044b3175476e90735a11196cebb86c4156197ecd018f837caa03f1f0ffda19d4c5850788770b61a9af3877d0a2130fca437621c32b6f2e428769371c5da14d1d3ae425679e6bda08c9c3df7246e955daf71f2c47927949d71ee5b7d884b334218e35122e2ed1f5108b08fdd45eb9434cc776f6cd4f50cc3f4d5af662feb6769a944f0df0ed282e1a5f1cbc53d22a419080439e21058092ff5591f70648890826eb0c68c80342b2563204eaa733bafb889bc346d273e3a1d1a4fd2ca03773ba15b9897c442e08f3c1db6188f19f0060605707a3b807430613793eb8806264c882e3ecca76bb978328327ca55b49dede37c173f5ff9e4594f1ea041eead4677da7087347d1d42431b74b00273252780833f9fa3ace8c28786e0ad0887c5fdc42257545405a4cbd4fbf0a24c6fa2ef3e2bab34d061a4417a17bfbf91d58b4e741ffe33032ed2fcad8f5a2b6142ad993f202f072947801ec6790dee924c86d64911bbb011e908ea930f5066c28c982cf931fb6fddcc07fef2088c2f41a48c19f84945fb20c2351db12874824aecc97affa41fc59ec75822cbacaef85f24faf959f61bad8a2af014b69f8b7ff8aa13510088add31d2784fe8f90e97af94d29d252aef5e3ef5663acdae23bc4558fd3e9e43b5810b8e037d9208f5be18a27dc28ffad08fb28501c2196c530193311429bb804f9cbdd7971e255dc1732e285c29373d5326b1548c3d274b9073a6e0160035f7c93723f7353d60b98ae140f00c97f701bb822728a412bfdd48160d552b23fb7b5e253096812b434b4819f88948d0c0d5e17b497e8b3b5993cebe53822a6fe7413c40070ea05a0b6d469e18b5922afa304e85255a109ce5ad79077e374a3b93aa9e3051bc9abaefb6fe558b7420cc5165a21e7681a33ff6ebff9666853a83cdd970a79984d3cedc7300b17db398790592b57156de4944b325c7d422d265ebb39f52b5c4a1e2f706b0a3509bf907b9739a9be52049d37de678550386d1af83df896f31dbdee78426168b6696b354c34ae9d4eff314069723be410dd0df6dd43a547a1b7829710773e344fe9525c9722bf790250448a47de6d974e40d2756007f39963596f51c8841d1185f9106d3bc748d723655dbf59b71c872e6e93d049f869d1a07c1b42328463c6fc106523b5c142f6b7deda8bf4600b7cb1462ebbcd1c28ef2d342ae279f61585a29ffdbda051fda444335dac496ab8b05654cd84",
    "sub_merchant_id": "123456"
}

Performing Transaction Enquiry​

While webhooks push updates to your server, the Transaction Enquiry API lets you pull the latest status of a transaction on demand. Use it to:

  • Reconcile — verify the final status of a transaction when your system and Nimbbl may be out of sync (for example, after a missed or delayed webhook)
  • Confirm before fulfillment — double-check the payment status on your server before releasing goods or services
  • Handle edge cases — resolve ambiguous states where a webhook was received but your processing failed partway through

Endpoint​

MethodEndpoint
POST/v3/transaction-enquiry

You need to pass the nimbbl_transaction_id in the request body. The API returns the current transaction status along with the full transaction and order details.

When to Use Transaction Enquiry

Use webhooks as your primary mechanism and Transaction Enquiry as a fallback. A common pattern is to run a periodic reconciliation job that queries any transactions still in a pending state on your side, confirming their final status via this API.

For detailed request and response schemas, sample payloads, and error scenarios, see the Transaction Enquiry API reference.

Standard Checkout Completing IntegrationComplete your checkout integration with webhooksCommand Center CredentialsView and manage your API credentialsSonic Product OverviewThe checkout experience powered by Sonic