Webhook notification

The webhook notification is an HTTP POST request sent to the business partner endpoint provided in the initiate payment request, as soon as the payment status changes.

If the payment is captured by PaysafeCash, a PAYMENT_CAPTURED webhook is sent,
if the payment expires or is actively cancelled by the customer, a PAYMENT_EXPIRED webhoook is sent.

Additionally, when a barcode payment is declined due to risk screening of the KYC/KYB Reliance data submitted via API, a PAYMENT_DECLINED webhook is emitted.

The business partner payment server must respond with HTTP 200 and the authenticity of the webhook notification must be verified, as well as process the payment matching the details in the body of the message.

During the onboarding, the PaysafeCash team will provide a public key to the business partner which can be used to verifiy the authenticity of the webhook notification.

In case of technical errors (e.g. socket timeout) or application errors, the webhook notification is resubmitted at a regular interval of 1 minute until one of the following criteria is fulfilled:

The notification is successfully delivered (i.e. HTTP 200 response from payment server).
The maximum number of retry attempts has been reached (currently configured at 5 retries).
The webhook notification will be sent from either of the below IP addresses:

Source IP Addresses

Payment notifications are sent exclusively from the IP addresses listed below. These addresses must be allow-listed in your firewall configuration.

IP addresses
`18.197.120.90`
`18.158.237.76`
`3.64.155.76`
`3.76.4.148`
`3.127.123.143`
`176.34.172.250`
`54.228.173.185`
`52.48.213.182`
`18.200.202.144`

How to verify the webhook notification

The webhook notification is signed with "rsa-sha256" and the signature can be found in the HTTP "Authorization" header.

HTTP headers

Content-Type: application/json
Authorization: keyId="2",algorithm="rsa-sha256",signature="OFPVO1uqac0U18LlEedwfdYaIPuuCIsvSxuDRV+nsU33F2TVYapR/JHR0mvJSAZUJWUTJk60PZXPhGF9eQLeIidxX1yJg8JA0pC0/CAt7JbiF39KsjMYMkCPp51q84s1RqAa23D2sljJuvPQYiDJLPlZ7PRSxYaIfmJ6MWzRq4Ku4XVi6OpqgAkO5V205UsDBmp8mxc00w1Eu5yAPoUjelZfxqHl/G2D0e5hWPuggtx/3hx2szFQDJzfHdRBhrlSqcU2WGzByXhy6A6FzeOQVysQNAR1/i+ztlhfCotY11Usb+Uh4yUVwi/I0pbKL+UJZ2VZlI6++SAO7CoQVkBAiw=="

Parameter	Description
`keyId`	The signature key version id. It currently has the value "2" except if communicated otherwise by the PaysafeCash integration team.
`algorithm`	The algorithm used for the signature. A PaysafeCash webhook notification will always be signed with "rsa-sha256".
`signature`	The signature of the webhook notification.

The signature is created as follows:

signature = base64encode(rsa_encrypt(sha256(body), merchantPrivateKey))

And it is verified as follows:

rsa_decrypt(base64decode(signature), merchantPublicKey) == sha256(body)

Using the openssl dgst function to verify the signature

The digest functions can be used to verify digital signatures using message digests. The three steps below ilustrate how this can be done:

Extract the public key from the rsa key file sent with the data package

openssl rsa -RSAPublicKey_in -in webhook_signer_MANXXXXXXXXXX_1.rsa -out webhook_signer_MANXXXXXXXXXX_1_extracted.pem

Decode the signature of the webhook notification with base64

Linux: base64 --decode signature.txt > signature_debase64.txt

Windows: certutil.exe -decode signature.txt signature_debase64.txt

Verify the signature using the openssl dgst function

The generic name, dgst, may be used with an option specifying the algorithm to be used. The default digest is sha256.

openssl dgst -sha256 -verify webhook_signer_MANXXXXXXXXXX_1_extracted.pem -signature signature_debase64.txt plaintext_payload.txt

Parameter	Description
`-verify webhook_signer_MANXXXXXXXXXX_1_extracted.pem.pem`	Verifies the signature using the public key extracted in step 1. The output is either `Verification OK` or `Verification Failure`.
`-signature signature_debase64.txt`	The actual signature to verify in plain text, obtained in step 2.
`plaintext_payload.txt`	The body of the request in plain text.

PAYMENT_CAPTURED Webhook

This webhook is triggered after the payment has been successfully captured. Its purpose is to notify you that the transaction has been completed and no further payment actions are required, allowing you to proceed with order fulfillment.

HTTP body

{
    "timestamp":1539920400647,
    "eventType":"PAYMENT_CAPTURED",
    "version":"2",
    "data": {
        "mid":"1000000312",
        "mtid":"pay_1000000312_kvQwaSARVDlZm2yxRVNaCYZObI5Xcd40_EUR"
        "cashtie_reference":"2918727923"
    }
}

Parameter	Description
`timestamp`	The Unix timestamp of the payment.
`eventType`	The event that triggered the webhook notification. There are only two event types: "PAYMENT_CAPTURED" or "PAYMENT_EXPIRED"
`version`	The signature key version.
`mid`	The Merchant ID and/or Sub-merchant ID provided for the allocation of the payment.
`mtid`	The payment ID.
`cashtie_reference`	A settlement ID sent by our processing partner InComm.^1^

Needs to be enabled by Paysafe on request of the business partner and only available for INC processing.

Point of Sale details

We can include Point of Sale (POS) information for the location where the barcode payment was completed in the PAYMENT_CAPTURED webhook payload. This information is available only if it has been enabled on our side. If you want to receive POS information, please contact our Integration team to request enablement.

See below an example of such webhook. Under point_of_sale array, you can see the provided POS information.

HTTP body

{
"timestamp":1768908000326,
"eventType":"PAYMENT_CAPTURED",
"version":"1",
"data":{
    "mid":"1020015105",
    "mtid":"pay_1020015105_PSk1-bmHY5JS0Kb_GBP",
    "point_of_sale":{
        "countrycode":"GB",
        "store_number":"7009550_000000000051649",
        "title":"cheam village news",
        "street_and_no":"35 station way",
        "zipcode":"SM3 8SD",
        "city":"Sutton Surrey",
        "lat":51.35677,
        "lng":-0.21603
        }
    }
}

Parameter	Description
`point_of_sale`	Array of the parameters below
`store_number`	Distributor ID & external Shop ID
`title`	Store name
`street_and_no`	Address
`zipcode`	ZIP code
`city`	City
`countrycode`	Country Code (ISO2)
`lat`	Coordinate X
`lng`	Coordinate Y

PAYMENT_EXPIRED Webhook

This webhook notification is sent when the end customer cancels the payment via the barcode panel, or when the allowed timeframe for completing the barcode payment has expired.

{
"timestamp":1770216970736,
"eventType":"PAYMENT_EXPIRED",
"version":"1",
"data":
    {
    "mid":"1020015105",
    "mtid":"pay_1020015105_PSkhui-Z0YQS5JF_GBP"
    }
}

PAYMENT_DECLINED Webhook

When a barcode payment is declined as a result of risk checks, a dedicated webhook notification is sent to the partner.

HTTP body

{
"timestamp":1768855677806,
"eventType":"PAYMENT_DECLINED",
"version":"1",
"data":{
"mid":"1020015105",
"mtid":"pay_1020015105_PSrU0cChm1zdcTK_GBP",
"decline_reason":{
"reason_code":"Screening decline"
      }
   }
}

MONEY_HANDOVER Webhook

If requested, Paysafe can activate an additional webhook notification which is sent as soon as the customer paid at the store.

This webhook notification uses the eventType "MONEY_HANDOVER".

Important: this is not yet a confirmation that the transaction was successful, but you can update the transaction status to "processing" or "pending" on your end.

We expect you to credit the customer only when you receive the webhook notification with the event type "PAYMENT_CAPTURED".

This notification uses the same IP addresses as the normal webhook notification.
It uses the same type of verification - see the chapter below.
This notification needs to be enabled on our side, so you need to request it from PaysafeCash.
The notification will be sent between 0-30 seconds after the customer paid.
It will be sent to the same URL as the normal webhook notification - the one specified in the payment request.
The transaction status will NOT be updated, so you cannot confirm this with a retrievePayment request.
In case the notification fails to get delivered, we attempt up to 5 retries.
- This means you could receive a "MONEY_HANDOVER" notification after the transaction was already successful. In these cases, please confirm the transaction status with a retrievePayment.

HTTP body

    {
      "timestamp": 1686560013991,
      "eventType": "MONEY_HANDOVER",
      "version": "2",
      "data": {
        "mid": "1000000433",
        "mtid": "mdirectload_1686560012113_hq13zzbV7z_EUR"
      }
    }

MONEY_RETURNED Webhook

If requested, Paysafe can also activate one more additional webhook notification which is sent as soon as a successful payment is cancelled at the point of sale and the funds are returned.

This webhook notification uses the eventType "MONEY_RETURNED".

Important: this is a confirmation that the funds have been returned to the customer at the point of sale and any credit you have done on your side needs to be reversed. The transaction status should be updated after you have received a different webhook event or preferably after checked with a GET call.

This notification uses the same IP addresses as the normal webhook notification.
It uses the same type of verification - see the chapter below.
This notification needs to be enabled on our side, so you need to request it from PaysafeCash.
The notification will be sent between 0-360 seconds after the customer received the funds back.
It will be sent to the same URL as the normal webhook notification - the one specified in the payment request.
The transaction status will NOT be updated, so you cannot confirm this with a retrievePayment request.
In case the notification fails to get delivered, we attempt up to 5 retries. This means you could receive a "MONEY_RETURNED" notification after receiving a "MONEY_HANDOVER" one or a "PAYMENT_CAPTURED" one. This will indicate an incomplete payment and the partner will need to recheck the payment status via GET call or wait for other webhook events.

HTTP body

    {
      "timestamp": 1706199208146,
      "eventType": "MONEY_RETURNED",
      "version": "2",
      "data": {
        "mid": "1000000545",
        "mtid": "pay_1000000545_iSL7n3nsLl8t396SJQTAvcjD3rKoIti9_EUR"
      }
    }

Source IP Addresses​

How to verify the webhook notification​

Using the openssl dgst function to verify the signature​

PAYMENT_CAPTURED Webhook​

Point of Sale details​

PAYMENT_EXPIRED Webhook​

PAYMENT_DECLINED Webhook​

MONEY_HANDOVER Webhook​

MONEY_RETURNED Webhook​

Source IP Addresses

How to verify the webhook notification

Using the openssl dgst function to verify the signature

PAYMENT_CAPTURED Webhook

Point of Sale details

PAYMENT_EXPIRED Webhook

PAYMENT_DECLINED Webhook

MONEY_HANDOVER Webhook

MONEY_RETURNED Webhook