Skip to content

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.
email 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"
      }
    }
  }
}