Skip to main content

Refund Webhooks

This page covers the three webhook events triggered as a refund progresses. For payment lifecycle events, see Payment Webhooks. For payment link events, see Payment Link Webhooks.

Each event below shows its v3 and v4 payload. v3 sends the full payload as-is; v4 encodes and signs the same payload before sending it — open Decoded payload in the v4 tab to see what's inside it. The v4 signature field is named signature, not nimbbl_signature (the name used on the payment and checkout callbacks). See Webhook Payloads for how retries, idempotency, and payload versions work, and Validating Payment Response with Signature for signature validation logic.

Refund Events​

Refund Success Webhook​

Your endpoint receives this over HTTPS POST:

{
    "payload": "<base64>",
    "signature": "<hmac-sha256-hex>",
    "sub_merchant_id": "<sub_merchant_id>",
    "version": "v4"
}

Base64-decode payload to get the JSON below — the full payment details for this event, verified by the accompanying signature.

Decoded payload
{
	"event_type": "refund_success",
	"status": "success",
	"message": "Refund Successful",
	"nimbbl_order_id": "<Order_ID>",
	"refund_transaction_id": "<Refund Transaction ID>",
	"transaction": {
		"transaction_id": "<Transaction_ID>",
		"payment_partner": "<Payment Partner>",
		"refund_status": "succeeded",
		"payment_mode": <Payment Mode>,
		"psp_credential_label": <Cred Label>,
		"sub_payment_mode": {},
		"psp_transaction_id": "<Pay_ID>",
		"refund_currency": "INR",
		"nimbbl_consumer_message": "",
		"nimbbl_merchant_message": "",
		"nimbbl_error_code": "",
		"original_payment_transaction_id": "<Payment Transaction ID>",
		"refund_request_id": "",
		"refund_arn": "",
		"refund_amount": <Refund amount with upto 2 decimal>,
		"payment_transaction_amount": <Transaction amount with upto 2 decimal>,
		"notes": "<Refund reason, if provided>",
		"transaction_type": "full-refund"
	},
	"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>,
		"status": "completed",
		"currency": "<ISO_4217 Alpha-3 format currency>",
		"cancellation_reason": "payment success",
		"grand_total": <total_amount - offer_discount + additional_charges>,
		"refund_details": {
			"refundable_currency": "INR",
			"available_refundable_amount": 0.0,
			"refunded_amount": 5.0,
			"total_refundable_amount": 5.0
		},
		"custom_attributes": [],
		"device": {
			"browser_name": "Chrome",
			"device_name": "Other",
			"os_name": "Windows",
			"ip_address": "127.0.0.1"
		}
	},
	"psp_raw_response": null,
	"user": {
		"email": "[email protected]",
		"mobile": "9121212121",
		"name": "Shakthiman",
		"user_id": "<user_ID>"
	}
}

Refund Failed Webhook​

Your endpoint receives this over HTTPS POST:

{
    "payload": "<base64>",
    "signature": "<hmac-sha256-hex>",
    "sub_merchant_id": "<sub_merchant_id>",
    "version": "v4"
}

Base64-decode payload to get the JSON below — the full payment details for this event, verified by the accompanying signature.

Decoded payload
{
	"event_type": "refund_failed",
	"status": "failed",
	"message": "Refund Failed",
	"nimbbl_order_id": "<Order_ID>",
	"refund_transaction_id": "<Refund Transaction ID>",
	"transaction": {
		"transaction_id": "<Transaction_ID>",
		"payment_partner": "<Payment Partner>",
		"refund_status": "failed",
		"payment_mode": <Payment Mode>,
		"psp_credential_label": <Cred Label>,
		"sub_payment_mode": {},
		"psp_transaction_id": "<Pay_ID>",
		"refund_currency": "INR",
		"nimbbl_consumer_message": "",
		"nimbbl_merchant_message": "",
		"nimbbl_error_code": "",
		"original_payment_transaction_id": "<Payment Transaction ID>",
		"refund_request_id": "",
		"refund_arn": "",
		"refund_amount": <Refund amount with upto 2 decimal>,
		"payment_transaction_amount": <Transaction amount with upto 2 decimal>,
		"notes": "<Refund reason, if provided>",
		"transaction_type": "full-refund"
	},
	"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>,
		"status": "completed",
		"currency": "<ISO_4217 Alpha-3 format currency>",
		"cancellation_reason": "payment success",
		"grand_total": <total_amount - offer_discount + additional_charges>,
		"refund_details": {
			"refundable_currency": "INR",
			"available_refundable_amount": 0.0,
			"refunded_amount": 5.0,
			"total_refundable_amount": 5.0
		},
		"custom_attributes": [],
		"device": {
			"browser_name": "Chrome",
			"device_name": "Other",
			"os_name": "Windows",
			"ip_address": "127.0.0.1"
		}
	},
	"psp_raw_response": null,
	"user": {
		"email": "[email protected]",
		"mobile": "9121212121",
		"name": "Shakthiman",
		"user_id": "<user_ID>"
	}
}

Refund Pending Webhook​

Your endpoint receives this over HTTPS POST:

{
    "payload": "<base64>",
    "signature": "<hmac-sha256-hex>",
    "sub_merchant_id": "<sub_merchant_id>",
    "version": "v4"
}

Base64-decode payload to get the JSON below — the full payment details for this event, verified by the accompanying signature.

Decoded payload
{
	"event_type": "refund_pending",
	"status": "pending",
	"message": "Refund Pending",
	"nimbbl_order_id": "<Order_ID>",
	"refund_transaction_id": "<Refund Transaction ID>",
	"transaction": {
		"transaction_id": "<Transaction_ID>",
		"payment_partner": "<Payment Partner>",
		"refund_status": "pending",
		"payment_mode": <Payment Mode>,
		"psp_credential_label": <Cred Label>,
		"sub_payment_mode": {},
		"psp_transaction_id": "<Pay_ID>",
		"refund_currency": "INR",
		"nimbbl_consumer_message": "",
		"nimbbl_merchant_message": "",
		"nimbbl_error_code": "",
		"original_payment_transaction_id": "<Payment Transaction ID>",
		"refund_request_id": "",
		"refund_arn": "",
		"refund_amount": <Refund amount with upto 2 decimal>,
		"payment_transaction_amount": <Transaction amount with upto 2 decimal>,
		"notes": "<Refund reason, if provided>",
		"transaction_type": "full-refund"
	},
	"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>,
		"status": "completed",
		"currency": "<ISO_4217 Alpha-3 format currency>",
		"cancellation_reason": "payment success",
		"grand_total": <total_amount - offer_discount + additional_charges>,
		"refund_details": {
			"refundable_currency": "INR",
			"available_refundable_amount": 0.0,
			"refunded_amount": 5.0,
			"total_refundable_amount": 5.0
		},
		"custom_attributes": [],
		"device": {
			"browser_name": "Chrome",
			"device_name": "Other",
			"os_name": "Windows",
			"ip_address": "127.0.0.1"
		}
	},
	"psp_raw_response": null,
	"user": {
		"email": "[email protected]",
		"mobile": "9121212121",
		"name": "Shakthiman",
		"user_id": "<user_ID>"
	}
}
RefundsThe refund concept, lifecycle, and processing full, partial, and SKU-based refundsTransaction EnquiryThe pull-based alternative for polling status on demandValidating Payment Response with SignatureFull HMAC SHA256 signature validation code in Java, C#, PHP, and Python