BlueSnap webhook validation and event mapping for Real-Time Reconciliation
Learn how Zuora validates BlueSnap webhooks for Real-Time Reconciliation using IP allowlisting and how BlueSnap events, including ACH events, map to Zuora payment statuses and reconciliation outcomes
Zuora validates BlueSnap requests by checking the sender IP address. This approach follows the recommended validation method in the BlueSnap Real-Time Reconciliation design.
Zuora uses the sandbox allowlist when the test environment option is selected. If the test environment option is not selected, Zuora uses the production allowlist.
BlueSnap also supports signature-key validation, but the current BlueSnap Real-Time Reconciliation design uses IP-based validation instead of signature validation.
BlueSnap event mapping
BlueSnap events are mapped to Zuora payment or refund reconciliation outcomes.
| BlueSnap event | Zuora mapping |
|---|---|
| Successful Charge | Maps to TransactionSettled. |
| Declined Charge | Maps to TransactionRejected and updates the payment reconciliation reason. |
| Successful Refund | Maps to TransactionSettled on the refund record. |
| Chargeback and Chargeback_Status_Changed | Map to TransactionReversed and update the payment reconciliation status and reason. |
ACH event outcomes
For ACH payments, BlueSnap sends post-settlement events. Zuora processes these events through Real-Time Reconciliation and updates the corresponding records based on the gateway notifications that BlueSnap sends.
The following table describes how BlueSnap ACH events affect Zuora payment status and reconciliation actions.
| BlueSnap event | Zuora payment status | Zuora action |
|---|---|---|
| Sale + Approved (initial ACH submission) | Processed | Payment is marked as processed. |
| Sale + Pending (initial ACH, Immediate Approval off) | Pending | Payment awaits settlement. |
| Post-Approved → Returned or Failed, such as NSF or invalid account | Error or Failed | Invoice is reopened, balances are restored, and dunning or retry is triggered again. |
| Post-Approved → Refunded (settled, then refunded) | Payment stays Processed | A new refund record is created and linked to the payment. The invoice is updated according to standard refund logic. |
| Post-Approved → Canceled | Logged as anomaly | Requires Support review. The payment does not transition back to Processed. |