Webhook notifications
To notify a merchant of an accepted payment or of a changed transaction status, bePaid sends POST
requests to the URL from notification_url
parameter.
bePaid sends notifications when a transaction status is changed to one of pending
, expired
, failed
or successful
.
POST requests (notification) include the shop credentials (Shop ID and Secret Key) and a JSON-serialized message with transaction parameters.
Warning
To avoid receiving of fake notifications, always check credentials received. Only successful verifying of these credentials can guarantee that a notification really came from bePaid.
Parameters of a webhook notification request about a transaction made by an alternative payment method
Parameter | Type | Description |
---|---|---|
transaction | object | |
uid * required |
string | A transaction UID. |
type * required |
string | A transaction type. |
status * required |
string | A transaction status. |
amount * required |
integer | A transaction amount in minimal currency units. |
currency * required |
string | A transaction currency in the ISO-4217 alpha-3 code format. For example, USD . |
description * required |
string | The description value from the transaction request. |
created_at * required |
string | Time and date when the transaction was created (refers to the expired_at description of the payment request). |
updated_at * required |
string | Time and date when transaction details were updated (refers to the expired_at description of the payment request). |
method_type * required |
string | A payment method type. |
payment | object | |
status * required |
string | A status from the payment method provider. |
gateway_id * required |
integer | An identifier of the gateway that processed the transaction. |
ref_id | string | A transaction identifier provided by the payment method provider. |
message | string | A message from the payment method provider. |
{method} | object | A name of the payment method which processed the transaction. Check the available payment methods and their parameters here. |
customer * conditionally required |
object | A section of the customer information. |
ip | string | The customer's IP address. |
string | The customer's email address. | |
message | string | A system message. |
tracking_id | string | The tracking_id value from the transaction request. |
test | boolean | true , if a transaction is processed in the test mode. |
language | string | The language value from the transaction request. |
paid_at | string | Time and date when the transaction was paid (refers to the expired_at description of a payment request). If a transaction is not completed, the parameter is missing. |
billing_address | object | A section with the customer information. |
first_name | string | The customer's first name. |
middle_name | string | The customer's middle name. |
last_name | string | The customer's last name. |
country | string | The customer's country. |
city | string | The customer's city. |
zip | string | The customer's postal or zip-code. |
address | string | The customer's address. |
phone | string | The customer's phone. |
birth_date | string | The customer's birth date in the format YYYY-MM-DD . |
additional_data | object | A section of additional transaction details. |
Example of a webhook notification about a payment
{
"transaction": {
"uid": "566fd40a-2379-46d6-aecd-67779afcf883",
"type": "payment",
"status": "pending",
"amount": 1234,
"currency": "EUR",
"description": "Description",
"created_at": "2018-08-08T13:30:54Z",
"updated_at": "2018-08-08T13:30:54Z",
"method_type": "method_name",
"payment": {
"status": "pending",
"gateway_id": 1,
"message": "Transaction has been initialized"
},
"method_name": {
"type": "method_name",
"account": "user",
},
"customer": {},
"message": "Transaction has been initialized",
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"country": "DE",
"birth_date": "1974-02-15"
},
"additional_data": {
"payment_method": {
"type": "alternative"
}
}
}
}