What are webhooks?

Webhooks are how our platform keeps your system in the loop.

Whenever something important happens in the payment flow (like a successful charge, a refund, a failure, etc.), we send a notification to your configured webhook endpoint. This allows your backend to react instantly and stay in sync with the latest transaction events.

Webhooks are essential for automation. Think of it as our way of giving your system a heads-up — the moment it matters.

How to accept webhooks?

To verify the notification, you need to :

Transform the json body into string.
Concatenate : string-body+xxx-timestamp
Hash the string using HMAC-SHA256 and Secret Key (coding = UTF8)
Ensure that the encoded hash in base16 = xxx-signature

Find your Secret Key

You can find your Secret Key needed for the notifications in the Backoffice.

Log into your account.
Navigate to API & Notifications.
If you have more than one merchant account, select the one you are retrieving Secret Key for at the top.
Go to Security and retrieve your key from the Secret Key section.

Example

Headers

Parameter	Value
`xxx-timestamp`	1639569054
`xxx-signature`	5a938268e15a97a17f465a540ba0b7c05899b342b61e67aa1b3b1ba74d2f61a9

JSON notification body

{
  "request_id": "3456789876545678456789765",
  "order_id": "60509208505368000a3dfbd2",
  "transaction_id": "68HGVFT5RTGVU",
  "merchant_order_id": "9J3947DB29D",
  "merchant_contract_id": "489YGF68YGT545678YG",
  "status": "authorization_successful",
  "action_date": "2023-08-12T12:45:48+0000",
  "amount": 118.98,
  "payin_partner": "checkout",
  "payin_transaction_id": "pay_5689IHVFR43456789UYHGVGYU876545678UYG",
  "payin_transaction_description": "APPROVED",
  "authentication_partner": "checkout",
  "authentication_result": "success",
  "risk_assessment_partner": "checkout",
  "risk_assessment_result": "accepted",
  "payment_method": "VISA",
  "capture_total_amount": 0,
  "refund_total_amount": 0,
  "currency": "EUR",
  "is_capturable": true,
  "is_refundable": false,
  "is_cancellable": true,
  "link_interface": "",
  "card_6_digits": "424242",
  "card_4_digits": "4242",
  "card_validity_month": "02",
  "card_validity_year": "25",
  "card_issuer": "",
  "card_country": "GB",
  "merchant_account": "615f3066c67357000ad556e1",
  "token": "072bd9c0b63dde38e2d41e906273d1b59acfe6dea2c3d9a877c8ed7806c2b5eb",
  "is_order_last_transaction": true
}

Transforming JSON body intro string

{"request_id":"3456789876545678456789765","order_id":"60509208505368000a3dfbd2","transaction_id":"68HGVFT5RTGVU","merchant_order_id":"9J3947DB29D","merchant_contract_id":"489YGF68YGT545678YG","status":"authorization_successful","action_date":"2023-08-12T12:45:48+0000","amount":118.98,"payin_partner":"checkout","payin_transaction_id":"pay_5689IHVFR43456789UYHGVGYU876545678UYG","payin_transaction_description":"APPROVED","authentication_partner":"checkout","authentication_result":"success","risk_assessment_partner":"checkout","risk_assessment_result":"accepted","payment_method":"VISA","capture_total_amount":0,"refund_total_amount":0,"currency":"EUR","is_capturable":true,"is_refundable":false,"is_cancellable":true,"link_interface":"","card_6_digits":"424242","card_4_digits":"4242","card_validity_month":"02","card_validity_year":"25","card_issuer":"","card_country":"GB","merchant_account":"615f3066c67357000ad556e1","token":"072bd9c0b63dde38e2d41e906273d1b59acfe6dea2c3d9a877c8ed7806c2b5eb","is_order_last_transaction":true}

Concatenate string-body+xxx-timestamp

{"request_id":"3456789876545678456789765","order_id":"60509208505368000a3dfbd2","transaction_id":"68HGVFT5RTGVU","merchant_order_id":"9J3947DB29D","merchant_contract_id":"489YGF68YGT545678YG","status":"authorization_successful","action_date":"2023-08-12T12:45:48+0000","amount":118.98,"payin_partner":"checkout","payin_transaction_id":"pay_5689IHVFR43456789UYHGVGYU876545678UYG","payin_transaction_description":"APPROVED","authentication_partner":"checkout","authentication_result":"success","risk_assessment_partner":"checkout","risk_assessment_result":"accepted","payment_method":"VISA","capture_total_amount":0,"refund_total_amount":0,"currency":"EUR","is_capturable":true,"is_refundable":false,"is_cancellable":true,"link_interface":"","card_6_digits":"424242","card_4_digits":"4242","card_validity_month":"02","card_validity_year":"25","card_issuer":"","card_country":"GB","merchant_account":"615f3066c67357000ad556e1","token":"072bd9c0b63dde38e2d41e906273d1b59acfe6dea2c3d9a877c8ed7806c2b5eb","is_order_last_transaction":true}1639569054

Hash the previous string using HMAC-SHA256 with SecretKey

If secret-key=3456789876543235TGY8 , hash= 5a938268e15a97a17f465a540ba0b7c05899b342b61e67aa1b3b1ba74d2f61a9
Ensure that xxx-signature value equals the encoded hash in the last step

How to configure webhooks in your account?

You can create webhooks directly in your account as follows:

Log into your merchant account.
On the left-handed sidebar navigate to Integration section.
Select API & notifications
If you have more than one merchant account, select the one you are configuring notifications for at the top.
SelectNotifications.
Click on Add notification to open a configuration section of your webhook.
In this section you can configure your webhook with the following details:
- Name of your webhook. Useful if you want to create more than one webhook as it will help you to identify it.
- URL to receive your notification.
- Triggers. You can select as many triggers as you want within one webhook, although depending on your situation, it could be more useful to have more webhooks, categorized by trigger type.
- Notify last transaction only. Boolean.
- Status. Active or Inactive. In case you want to temporarily stop using your webhook(s), you can deactivate instead of removing.

Full list of available webhooks and recommendation

Webhook	Description	Recommended
Authorization successful	Payment authorization was approved by the issuer.	✅
Capture declined	The attempt to capture an authorized payment was declined.	✅
Refund declined	The request to refund a payment was declined.	✅
Route not found	The request failed because no routing path was found.	✅
Capture successful	Funds were successfully captured from a previously authorized transaction.	✅
Authentication attempted	An authentication process was initiated by the user.
Authentication declined	The user's authentication attempt was declined.
Authentication request expired	The authentication request expired without completion.
Authentication request failed	The authentication request could not be processed due to an error.
Authentication requested	An authentication request was generated and sent to the user.
Authentication successful	The user successfully completed authentication.
Authorization cancel declined	The attempt to cancel an authorization was declined.
Authorization cancel request failed	A technical failure occurred while trying to cancel an authorization.
Authorization cancel requested	A request to cancel an authorization was initiated.
Authorization cancel successful	The authorization was successfully canceled.
Authorization declined	The authorization attempt was declined by the issuer.
Authorization expired	The authorization expired before capture.
Authorization failed	The authorization process failed due to a system or network error.
Authorization renewed	An expired or expiring authorization was successfully renewed.
Authorization request expired	The authorization request expired before being completed.
Authorization request failed	A technical failure occurred during the authorization request.
Authorization requested	A payment authorization request was initiated.
Blocked by router	The transaction was blocked by internal routing or business logic.
Capture request failed	The request to capture funds failed due to a technical issue.
Capture requested	A request to capture previously authorized funds was initiated.
Charged back	The transaction was reversed due to a chargeback by the cardholder.
Created	A new transaction or object was successfully created.
Credit declined	The credit (payout) attempt was declined by the recipient’s bank.
Credit request failed	A technical issue occurred during the credit request.
Credit requested	A request to credit (send funds) was initiated.
Credit successful	Funds were successfully credited to the recipient.
Paid	The transaction was successfully paid and settled.
Refund request failed	A technical error prevented the refund request from being processed.
Refund requested	A refund was requested for a previously settled payment.
Refund successful	The refund was successfully processed and funds returned to the payer.
Risk assessment approved	The transaction passed the risk assessment and was approved.
Risk assessment declined	The transaction failed the risk assessment and was declined.
Risk assessment manual review	The transaction was flagged for manual review during risk assessment.
Risk assessment request failed	A technical issue occurred during the risk assessment request.
Risk assessment requested	A risk assessment was initiated for the transaction.

Examples

Below you will find some Webhooks samples for the following events: authorization_successful, capture_declined, refund_declined, route_not_found.

{
  "status": "authorization_successful",
  "amount": 35,
  "currency": "USD",
  "merchant_account": "615371bef73714000bc978c5",
  "authentication_partner": "partnername",
  "authentication_result": "accepted",
  "payin_partner": "partnername",
  "risk_assessment_partner": "partnername",
  "risk_assessment_result": null,
  "order_id": "687368f051cc140fa87ed132",
  "customer_zip_code": null,
  "token": "a54c0064c83d35d588a4dbdcd0db386bf86f83940f34b05501149f06bfd7ed2f",
  "is_order_last_transaction": true,
  "card_6_digits": "411111",
  "card_4_digits": "1111",
  "card_issuer": "CONOTOXIA SP. Z O.O",
  "card_country": "PL",
  "card_validity_month": "03",
  "card_validity_year": "29",
  "request_id": "687368f951cc140fa87ed162",
  "transaction_id": "687368f051cc140fa87ed133",
  "merchant_order_id": "b4912b7f-8223-4bdf-80fd-cd292857e8c8:",
  "merchant_contract_id": "662a3d2ec23528a64c1677fb",
  "action_date": "2025-07-13T08:06:17.972Z",
  "payin_transaction_id": "XZZ02e2c592882f594D3FTZFTITW5H63",
  "payin_transaction_description": "Approved or completed successfully",
  "payment_method": "visa",
  "capture_total_amount": 0,
  "refund_total_amount": 0,
  "is_capturable": true,
  "is_refundable": false,
  "is_cancellable": true,
  "link_interface": "https://merchant-sandbox.abcompany.com/brainpower/orders/687368f051cc140fa87ed132"
}

{
  "request_id": "672cc6fe149e8e04ad2baa8a",
  "order_id": "672cc6e1149e8e04ad2ba606",
  "transaction_id": "672cc6e1149e8e04ad2ba608",
  "merchant_order_id": "583b9ed0-c463-4d25-a5d2-c98f0ed3b57c",
  "merchant_contract_id": "66c8a0eafe3f34c573bfa7a4",
  "status": "capture_declined",
  "action_date": "2024-11-07T13:56:14.709Z",
  "amount": 100,
  "payin_partner": "partnername",
  "payin_transaction_id": "993C4FC90B6A4D22B1D4E6F9B8B82FA3",
  "payin_transaction_description": "Validation failure: No primary action specified. Please specify 1 primary action., No valid subscription found for service 'payconiq'.",
  "authentication_partner": null,
  "authentication_result": null,
  "risk_assessment_partner": "partnername",
  "risk_assessment_result": null,
  "payment_method": "payconiq",
  "capture_total_amount": 0,
  "refund_total_amount": 0,
  "currency": "EUR",
  "is_capturable": false,
  "is_refundable": false,
  "is_cancellable": false,
  "link_interface": "https://merchant-sandbox.abcompany.com/brainpower/orders/672cc6e1149e8e04ad2ba606",
  "card_6_digits": null,
  "card_4_digits": null,
  "card_validity_month": null,
  "card_validity_year": null,
  "card_issuer": null,
  "card_country": null,
  "merchant_account": "64abc8a3d2b7f2007e7c30bb",
  "token": null,
  "is_order_last_transaction": true
}

{
  "request_id": "662b74ed9087b43160e6606b",
  "order_id": "662b74d39087b43160e66005",
  "transaction_id": "662b74d39087b43160e66007",
  "merchant_order_id": "560027e8-5429-44bf-abd1-702113435370",
  "merchant_contract_id": "655624f3a89ee731f832ae3a",
  "status": "refund_declined",
  "action_date": "2024-04-26T09:33:34.822Z",
  "amount": 16,
  "payin_partner": "partnername",
  "payin_transaction_id": "pi_3P9l9UD1ZswKcVpZ041WiG4U",
  "payin_transaction_description": null,
  "authentication_partner": "partnername",
  "authentication_result": "attempted",
  "risk_assessment_partner": "partnername",
  "risk_assessment_result": "accepted",
  "payment_method": "cb",
  "capture_total_amount": 16,
  "refund_total_amount": 0,
  "currency": "EUR",
  "is_capturable": false,
  "is_refundable": true,
  "is_cancellable": false,
  "link_interface": "https://merchant-sandbox.abcompany.com/brainpower/orders/662b74d39087b43160e66005",
  "card_6_digits": "400000",
  "card_4_digits": "7726",
  "card_validity_month": "12",
  "card_validity_year": "25",
  "card_issuer": "issuername",
  "card_country": "US",
  "merchant_account": "64abc8a3d2b7f2007e7c30bb",
  "token": "4c341adb52ff58d87fc6f74a9677a83c3abbc2d94c44debaedc246c3a3d5f08a",
  "is_order_last_transaction": true
}

{
  "status": "route_not_found",
  "amount": 13.13,
  "currency": "EUR",
  "merchant_account": "65d700586d4a8d7e7f26d039",
  "authentication_partner": null,
  "authentication_result": null,
  "payin_partner": "partnername",
  "risk_assessment_partner": null,
  "risk_assessment_result": null,
  "order_id": "686689ecdb942acb6dc16b9c",
  "token": "1c75d1abb377c6e94e6ad75eb91b8c622cdb3d4ff1456375a7ea3411224ae189",
  "is_order_last_transaction": true,
  "card_6_digits": "406742",
  "card_4_digits": "9265",
  "card_issuer": "issuername",
  "card_country": "FI",
  "company_result_code": "404000",
  "company_result_description": "route does not exist",
  "card_validity_month": "12",
  "card_validity_year": "34",
  "transaction_id": "686689ecdb942acb6dc16b9d",
  "merchant_order_id": "72c6dccd-9f57-4c23-b23e-0beb0991d455",
  "merchant_contract_id": "65e86095ca5a2f03064b3c0d",
  "action_date": "2025-07-03T13:47:24.615Z",
  "payin_transaction_id": null,
  "payin_transaction_description": null,
  "payment_method": "visa",
  "capture_total_amount": 0,
  "refund_total_amount": 0,
  "is_capturable": false,
  "is_refundable": false,
  "is_cancellable": false,
  "link_interface": "https://merchant-sandbox.abcompany.com/brainpower/orders/686689ecdb942acb6dc16b9c"
}

The headers will contain the xxx-signature parameter and the xxx-timestamp.

Webhook workflow

On the flowchart below you can see the webhook subscription - receive notification workflow with both successful and unsuccessful scenario included.

Notification failure

Sometimes webhooks don’t reach your system. Network hiccups, downtime, or endpoint misconfigurations can all cause delivery failures. To ensure your system doesn’t miss a useful information, we automatically retry sending webhook notifications when delivery fails.

Retry Mechanism

When a notification failure happens, rest assured - we got you covered! After the first failure, the retry mechanism will make another 9 attempts over a period of 12 hours with a descending frequency.

Resending notifications

If all attempts are not successful, you will still be able to resend the notification manually. This will be possibly only after the last retry takes place. The notifications status will remain on Pending until the last retry is done. After that, when unsuccessful, it will reach Failure status and that is when you will be able to resend the notification.

To resend a notification, either right-click on it and select Resend or add a SEND AGAIN column to your view.

Additional information in the webhook

Above, you could see some example webhooks that you receive from us. Those examples present out default webhook setup - default fields that we send. If you need some additional fields being passed in the webhook(s), please reach out to Support.