Webhook notifications
A webhook notification is a way to call a script on one of your own web servers whenever a transaction or a subscription is processed.
Set up webhook requests
To receive a webhook request from the bePaid system, pass notification_url
in transaction request parameters.
{
....
"notification_url":"https://your-domain.com/notification",
....
}
Webhook request use HTTP Basic authentication with Shop ID and Secret Key.
Verify webhook requests
A webhook request contains the same parameters as a transaction or a subscription response.
The Content-Signature
header contains the RSA digital signature of the request, that is generated with the shop RSA private key known only to the bePaid.
If you need to verify the notifications, check the digital signature of the request on your side with your RSA public key and compare it with the one received in the request. If the signatures coincide, it confirms the authenticity and integrity of the notification.
Info
When verifying the signature, make sure that:
- The hash is calculated by the SHA256 function;
- A public key is a key obtained in your bePaid back office;
- The calculated value is transmitted in Base64 encoding.
Example of the PHP code to verify the digital signature
# shop_public_key - shop public key
# signature - Content-Signature header value
# rawBody - request body
$public_key = str_replace(array("\r\n", "\n"), '', $shop_public_key);
$public_key = chunk_split($public_key, 64);
$public_key = "-----BEGIN PUBLIC KEY-----\n$public_key-----END PUBLIC KEY-----";
$signature = base64_decode($signature);
$key = openssl_pkey_get_public($public_key);
$a = openssl_verify($rawBody, $signature, $key, OPENSSL_ALGO_SHA256);
var_dump($a);
Example of the Ruby code to verify the digital signature
require 'openssl'
require 'base64'
shop_public_key = "" # Shop public key
signature = "" # Content-Signature header value
request_raw_body = "" # Request body
public_key = OpenSSL::PKey::RSA.new(Base64.decode64(shop_public_key))
if public_key.verify(OpenSSL::Digest::SHA256.new, Base64.decode64(signature), request_raw_body)
true
else
false
end
Processing webhook notifications
Your web server should return 200
HTTP status code if a webhook notification is processed successfully. Otherwise, bePaid will re-post webhook data later.
Example of the webhook request for a payment transaction
{
"transaction": {
"uid": "dd6ee60c-d30a-4348-b84c-86a4ef1a137d",
"status": "successful",
"amount": 100,
"currency": "EUR",
"description": "Test transaction ütf",
"type": "payment",
"payment_method_type": "credit_card",
"tracking_id": "tracking_id_000",
"message": "Successfully processed",
"test": true,
"created_at": "2023-04-14T13:07:01.836Z",
"updated_at": "2023-04-14T13:07:05.530Z",
"paid_at": "2023-04-14T13:07:05.495Z",
"expired_at": null,
"recurring_type": null,
"closed_at": null,
"settled_at": null,
"manually_corrected_at": null,
"language": "en",
"credit_card": {
"holder": "John Doe",
"stamp": "d9a78f040a8427c65da2c5569e6411c3641a5537fcfd2d2bf9f866abf3611c7d",
"brand": "visa",
"last_4": "1006",
"first_1": "4",
"bin": "401200",
"issuer_country": null,
"issuer_name": null,
"product": null,
"exp_month": 10,
"exp_year": 2026,
"token_provider": null,
"token": null
},
"receipt_url": "https://merchant.bepaid.by/customer/transactions/dd6ee60c-d30a-4348-b84c-86a4ef1a137d/42fe9b2e3ed56e98b426e946882cd10d71cd8ee0593373b00196413e28338dd7?language=en",
"status_code": null,
"gateway": {
"iframe": true
},
"id": "dd6ee60c-d30a-4348-b84c-86a4ef1a137d",
"additional_data": {
"browser": {
"screen_width": 1920,
"screen_height": 1080,
"screen_color_depth": 24,
"language": "en",
"java_enabled": false,
"user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36",
"time_zone": -180,
"time_zone_name": "Europe",
"accept_header": "json",
"window_height": 667,
"window_width": 600
}
},
"redirect_url": "https://gateway.bepaid.by/process/dd6ee60c-d30a-4348-b84c-86a4ef1a137d",
"payment": {
"auth_code": "654321",
"bank_code": "05",
"rrn": "999",
"ref_id": "777888",
"message": "Payment was approved",
"amount": 100,
"currency": "EUR",
"billing_descriptor": "test descriptor",
"gateway_id": 645,
"status": "successful"
},
"customer": {
"ip": "127.0.0.1",
"email": "john@example.com",
"device_id": "12312312321fff67",
"birth_date": "1980-01-31"
},
"billing_address": {
"first_name": "John 1",
"last_name": "Doe",
"address": "1st Street",
"country": "US",
"city": "Denver",
"zip": "96002",
"state": "CO",
"phone": "4567898765467"
}
}
}
Example of the webhook request body for a trial subscription
{
"id": "sbs_962f994ca74420d3",
"state": "trial",
"tracking_id": null,
"device_id": null,
"created_at": "2023-04-13T06:39:36.593Z",
"renew_at": "2023-05-13T06:41:26.581Z",
"active_to": "2023-05-13T06:41:26.581Z",
"card": {
"holder": "JOHN DOE",
"stamp": null,
"brand": "visa",
"last_4": "1006",
"first_1": "4",
"bin": null,
"issuer_country": null,
"issuer_name": null,
"product": null,
"token": "606760b7-74da-44fb-a730-13a9ee28d620",
"token_provider": null,
"exp_month": 12,
"exp_year": 2026,
"sub_brand": null
},
"customer": {
"id": "cst_4a708bf13a483278"
},
"paid_billing_cycles": 1,
"number_failed_payment_attempts": 0,
"additional_data": {},
"plan": {
"id": "pln_7f2e3edfbca72afc",
"title": "Test plan",
"name": "Test plan",
"description": "Subscription. Main period: €9.99 each 1 month. Trial: €4.99 each 1 month.",
"amount": 499,
"currency": "EUR",
"language": "en",
"infinite": true,
"billing_cycles": null,
"created_at": "2023-04-13T06:38:58.604Z",
"updated_at": "2023-04-13T06:38:58.604Z",
"trial": {
"amount": 499,
"interval": 1,
"interval_unit": "month"
},
"plan": {
"amount": 999,
"interval": 1,
"interval_unit": "month",
"visible_fields": [
"last_name",
"first_name",
"email"
]
},
"number_payment_attempts": 3,
"prevent_payments_at_night": true,
"test": true,
"pay_url": "https://api.bepaid.by/plans/pln_7f2e3edfbca72afc/pay",
"payment_url": "https://api.bepaid.by/plans/pln_7f2e3edfbca72afc/pay",
"confirm_url": "https://checkout.bepaid.by/v2/confirm_order/pln_7f2e3edfbca72afc/160"
},
"last_transaction": {
"uid": "971c8eb0-f4db-4a04-ba64-840e3427656e",
"status": "successful",
"message": "Successfully processed",
"created_at": "2023-04-13T06:41:22.913Z"
},
"event": "created.subscription"
}
Example of the webhook request for an active or renewed subscription
{
"card": {
"token": "2ed0b389f63c9198160bd7b8e98f6b42eb4c56e3b659a8070248b28cd3376d9d",
"holder": "John Doe",
"stamp": "b3839d334ba40e89168d60cd9f9d1390aee3fe67dd4d5c41adbf3998043eaef8",
"brand": "visa",
"last_4": "0000",
"first_1": "4",
"bin": "420000",
"issuer_country": null,
"issuer_name": null,
"product": null,
"token_provider": null,
"exp_month": 1,
"exp_year": 2026
},
"created_at": "2015-06-18T12:02:42.521Z",
"customer": {
"id": "cst_ae00d2582d001228"
},
"device_id": "any device_id",
"id": "sbs_f140af88af4aaf88",
"last_transaction": {
"created_at": "2015-01-12T09:04:59.000Z",
"message": "Successfully processed",
"status": "successful",
"uid": "4107-310b0da80b"
},
"plan": {
"currency": "USD",
"id": "pln_05e0756ed24eec5c",
"plan": {
"amount": 20,
"interval": 7,
"interval_unit": "day"
},
"title": "Title 1",
"trial": {
"amount": 10,
"interval": 40,
"interval_unit": "hour"
}
},
"renew_at": "2015-06-24T12:02:42.499Z",
"state": "active",
"tracking_id": "any tracking_id"
}
Example of the webhook request for a canceled subscription
{
"card": {
"token": "9990edb8e6f2af5d93a6259b690c50a7410bf9f97235f2e051345e01b580f699",
"holder": "John Doe",
"stamp": "b3839d334ba40e89168d60cd9f9d1390aee3fe67dd4d5c41adbf3998043eaef8",
"brand": "visa",
"last_4": "0000",
"first_1": "4",
"bin": "420000",
"issuer_country": null,
"issuer_name": null,
"product": null,
"token_provider": null,
"exp_month": 1,
"exp_year": 2026
},
"created_at": "2015-06-18T12:02:42.731Z",
"customer": {
"id": "cst_2a46e8b7ff87df2d"
},
"device_id": "any device_id",
"id": "sbs_1cc338f74bc9bfb7",
"last_transaction": null,
"plan": {
"currency": "USD",
"id": "pln_0b4ba2f1ab0c1988",
"plan": {
"amount": 20,
"interval": 7,
"interval_unit": "day"
},
"title": "Title 1",
"trial": {
"amount": 10,
"interval": 40,
"interval_unit": "hour"
}
},
"renew_at": null,
"state": "canceled",
"tracking_id": "any tracking_id"
}
Example of the webhook request for an expired payment token
If a payment token wasn't paid in time, the notification is sent at expired_at
date or in 24 hours after the token was created, if the expired_at
date wasn't defined.
{
"token":"311300d08dc7f22ae37272fac6513921d4c99ca24dcaccf4392a2606fe8f1877",
"shop_id":1,
"transaction_type":"payment",
"gateway_response":null,
"order":{
"currency":"USD",
"amount":4299,
"description":"Order description",
"tracking_id":null,
"additional_data":{
},
"expired_at":"2017-06-01T13:01:06.123Z"
},
"settings":{
"success_url":"http://127.0.0.1:4567/success",
"fail_url":"http://127.0.0.1:4567/fail",
"decline_url":"http://127.0.0.1:4567/decline",
"notification_url":"http://your_shop.com/notification",
"cancel_url":"http://127.0.0.1:4567/cancel",
"language":"en",
"customer_fields":{
"hidden":[
"phone",
"address"
],
"read_only":[
"email"
]
}
},
"customer":{
"first_name":null,
"last_name":null,
"address":null,
"city":null,
"country":null,
"state":null,
"phone":null,
"zip":null,
"email":"jake@example.com"
},
"finished":false,
"expired":true,
"shop":{
"name":"Shop",
"url":"http://127.0.0.1:3009",
"contact_email":"qwfpg@gmail.com",
"contact_phone":"123456789",
"brands":[
"visa",
"master",
"maestro",
"belkart",
"erip"
]
},
"test":false,
"status":"error",
"message":"Token is expired.",
"payment_method":{
"id":9,
"checkout_data_id":9,
"types":[
"erip"
],
"data":{
"erip":{
"order_id":"order_id",
"account_number":"123",
"service_no":"99999999"
}
},
"created_at":"2017-06-01T13:00:14.506Z",
"updated_at":"2017-06-01T13:00:14.506Z"
}
}