Webhook notifications

To notify a merchant of an accepted payment or of a changed transaction status, Overpay sends POST requests to the URL from notification_url parameter.

Overpay 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 Overpay.

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