Last changes: 06-07-2022
This section covers how webhooks are used to notify about events that happen in SmartPay.
Some events, like transaction status change, are not the result of a direct API request. Webhooks solve these problem by letting you provide a URL to which we will send a notification anytime such an event happens.
The "Notification Target URL" will receive a JSON payload depending on the notification type. Based on your integration requirements the notification service has to be turned on.
Please contact Customer Support to check your setup configuration.
Any of the below authentication methods can be selected for the corresponding Merchant key:
No authentication information is sent in the requests to the "Notification Target URL".
The authentication is done by specifying a Username and Password under the
The "Notification Target URL" will receive a JSON payload respecting the below form
Contains the payment transaction identifier
|createdAt||String||yyyy-MM-dd'T'HH:mm:ss.SS'Z||Time of the creation of the event:|
"api", "widget", "automated"
|Origin triggering the event: an API call, an action performed on the Widget or an event triggered by SmartPay backend|
Description of the event type
In case of a payment status change, it contains SmartPay transactionId
|Type of the event, mainly differentiating between "refund" and other transaction status changes under "payment".|
|metadata||Dictionary||key, value pairs|
Additional Ids and details linked to the notification:
|payment||"automated"||"status.updated"||Created every time when SmartPay payment transaction status gets changed. Usefull for tracking the statuses of asynchronoiusly processed payments or payment modifications initiated not through the SmartPay API, e.g from Merchant Panel. For security reasons only transaction id is provided into the notification body. To get the actual payment status Get Payment Status api should be used. As a 'transactionId' value required by Get Payment Status api use 'id' value received in notification.|
Created every time when SmartPay refund status gets changed. Usefull for tracking the statuses of asynchronoiusly processed refunds or refunds initiated not through the SmartPay API, e.g from Merchant Panel. For security reasons actual refund status is not provided in the norification data, only refund and transaction identifiers are provided in 'objectId' 'id' fields respectively.
To get the actual refund status use Get Payment Status API to retrieve transaction status and all modifications made to it by passing 'id' value provided as 'transactionId'. To determine the refund which has triggered the notification get first modification element with 'modificationData'/'type' equal to 'REFUND' and 'modificationData'/'refundId' equal to 'objectId' value received in notification. Read 'status' value from the found modification element for actual refund status.
Get Payment Status Api:
For the full list of SmartPay transaction statuses, please refer to this section.