Webhook

A webhook lets you subscribe to certain events, which, when triggered, send a webhook event payload in a POST message to the configured URL in real time. Webhook events are triggered when there is a change in status for a single transfer, a refund, a standing order, a variable recurring payment, or a variable recurring payment consent — TRANSFER_STATUS_CHANGED, REFUND_STATUS_CHANGED, STANDING_ORDER_STATUS_CHANGED, VRP_STATUS_CHANGED, and VRP_CONSENT_STATUS_CHANGED, respectively.

Here's the practical application of a BNP Paribas webhook.

When a payment is initiated, you determine if/when the payment requested is successful in order to notify the user of the transfer's status and take appropriate next steps, such as sending the user a receipt for payment or, if the transfer did not succeed, advising the customer with respect to a payment collection alternative before cancelling the purchase altogether. Why is this important?

In some cases, completion of a payment initiation response from the bank takes longer than expected for reasons beyond the control of either the e-merchant or BNP Paribas, resulting in a delay in receiving the transfer status from the bank, whether successful or rejected. While awaiting the transfer status in the bank's response to the original transfer request, the e-merchant could either continuously poll the bank for an update on status, involving multiple calls made periodically, or it can rely on a BNP Paribas webhook.

The webhook avoids protracted polling calls by the e-merchant for updates. Instead, upon any change in transfer status (the trigger), your Webhook URL immediately receives an HTTP POST message from the bank containing the transfer status payload. During the interim, the bank is polled for updates on the current status of the transfer so you don't have to. Here's the basic flow (click to enlarge):

Note: The webhook is sent only when the transfer status returned by the bank is transitional; i.e., processing. When the status is conclusively final — either success or failure — the webhook is not sent. See Payment Initiation Status for the complete list of transfer states.

The message Headers received by your Webhook URL comprise the following:

Special Webhook Headers
Headers Description
BNPP-Event Name of the event type that triggered the delivery (e.g., Transfer)
BNPP-Signature Authenticates BNP Paribas as the sender of the message and ensures that particular headers have not been modified in transit

To configure and test your Webhook:

  1. Expand Settings in the navigator and click Configuration.
  2. Enter the Webhook URL that will receive the updated status; e.g., https://yourWebServer.yourCompany.com.
  3. Select the Events that will trigger an update (you may select more than one) — e.g., select Transfers.
  4. Click Save to store your entries/changes.
  5. Click Test to validate the Webhook URL.
  6. Click Okay to acknowledge the Event generated message. It confirms the URL to which the Webhook event has been sent and advises receipt within 1 to 3 minutes.
  7. Finally, check that your Webhook URL received the event message (HTTP POST).

The notification will contain a transactionId (optional, depending on bank support), transferId, refId, and the current transfer status. At the bank's option, it may include the original payment status in bankPaymentStatus or bankStandingOrderStatus, respectively. For a list of possible transfer states, see Payment initiation status.