Skip to main content

Overview

Introduction​

Webhooks allow the Merchant to track events happening in Paysafe Embedded wallet. The following object changes can be tracked using webhooks.

It is the Merchant's responsibility to:

  • expose API endpoints for webhook handling
  • configure the webhook root URL with Paysafe
  • ensure the availability of the endpoints to receive the webhooks

Getting started​

In order to start receiving notifications the URL for each event type should be configured. As well as http statuses that need to trigger the retry mechanism described below.

All notifications can be signed before sending using HMAC. In order to turn on HMAC signing, the secret, used for signing, should be communicated and set. More about HMAC signing you can find in the section Webhook signature down bellow.

Supported events​

The Webhooks service supports multiple types of events related to various aspects of customer's activity:

  • Customer restrictions - Events related to any changes in restriction status of a customer. Contain information about restriction name, restriction reason and required actions.
  • Transactions - Events related to any changes in restriction status of a customer. Contain information about restriction name, restriction reason and required actions.
  • Accounts - This event is used to track IBAN assignments.
  • Payment Instruments - Events related to all changes in payment instruments of a customer.
  • Prepaid cards - Events related to prepaid card updates.
    • Card status updates - This webhook will be sent when the card status is updated
    • Card tokenization events - This webhook will be sent when the card is tokenized by Google, Apple or a merchant website.
    • Card token updates - This webhook will be sent when the card token is updated. A token update event occurs when the token associated with a card is updated due to changes in card details or security updates, ensuring seamless and secure transactions by automatically replacing the old token with a new one across platforms like Google Pay, Apple Pay, and merchant websites.
    • Card 3ds challenge events - This webhook will be sent when card 3ds authentication process is initiated.
    • Card bulk order events - This webhook will be sent upon the completion of the card bulk order process.
  • Kyc verifications - Know Your Customer verification status updates for customers.
  • PEP/Sanctions screening - Events that reflect customer's status after PEP and Sanctions screening.
  • Payment Handle - The webhook is sent when there's an update on the Payment Handle. The eventType signifies the change that occurred.

Retry mechanism​

In case event is not delivered the retry mechanism is involved. Webhooks service supports infinite retry mechanism with configurable timeout. Events are retried for multiple HTTP response statuses that can be configured as well. The retry is triggered on the event sending step.

Error scenarios​

In case of any error during the event processing, the event is stored in the system.

For any error during sending the event, the event is retried according to the retry mechanism. If retry is not configured the event is stored in the system.

Webhook Signature​

The webhook notification contains a signature header calculated using the following algorithm:

  • digest = HMAC_SHA256 (hmacKey, UTF 8 string containing the JSON webhook request body)
  • signature = base 64 encode (digest)

The code receiving the webhook needs to repeat this algorithm and compare the value generated with the value received in the header.

Example Header:

Signature: UMaQ4h635wUc4hp60Z5ASBC/5UtqKybAldOkLv6ngc0=

For more details on request signing please check the Request Signing documentation.

Notifications Resend API

In cases some issue in the merchant system prevented proper event processing, events can be replayed using Notification Resend API. In order to use this feature you need to specify searching criteria to filter events, then notifications will be sent to the URLs one more time. Pay attention that events are stored in the system for one month, so the older ones could not be available for resend.

When resend notification task is created it is stored and processed asynchronously. The task is processed in the background and the events are re-sent to the Merchant system after run of the Resend job.

Notification Resend API allows the Merchant to request the re-sending of events that have already been sent and delivered successfully to the Merchant.