Notifications
Last changes: 04-03-2024
Introduction
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.
Authentication Options
Any of the below authentication methods can be selected for the corresponding Merchant key:
| Authentication Type | Behavior |
No Authentication | No authentication information is sent in the requests to the "Notification Target URL". |
Basic Authentication | The authentication is done by specifying a Username and Password under the |
Notification Format
The "Notification Target URL" will receive a JSON payload respecting the below form
| Field | Type | Format | Description |
| id | String | string | Contains the payment transaction identifier |
| createdAt | String | yyyy-MM-dd'T'HH:mm:ss.SS'Z | Time of the creation of the event: Example: 2021-05-26T14:29:05.994Z |
| origin | String | Possible values: "api", "widget", "automated" | Origin triggering the event: an API call, an action performed on the Widget or an event triggered by SmartPay backend |
| eventType | String | Enum: "updated" | Description of the event type |
| objectId | String | UUID | In case of a payment status change, it contains SmartPay transactionId
|
| objectType | String | Enum: "payment" "refund" "prepayment" | Type of the event, mainly differentiating between "refund" and other transaction status changes under "payment". "prepayment" type provides prepayment specific status changes. |
| metadata | Dictionary | key, value pairs | Optional object (exists for specific use cases only e.g. pre-payment) "reconciliationId": 102957125651 } |
List of the available notifications
objectType | origin | Description |
| payment | "automated" | 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. Example: Payment notification: { "id": "c200b3fd-4960-4cd8-918c-5919013ce769", "createdAt": "2021-10-01T08:42:28.637Z", "origin": "automated", "eventType": "status.updated", "objectId": "c200b3fd-4960-4cd8-918c-5919013ce769", "objectType": "payment" } |
| refund | "automated" | 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. Example Refund notification: { Get Payment Status Api: [GET] <base_url>/payment/status/c200b3fd-4960-4cd8-918c-5919013ce769 { "status": "REFUNDED", |
| prepayment | "automated" | Triggered when certain actions hapened to prepayment transaction. Additional information is provided in "metadata" section of the notification body. To distinguish between prepayment notification types, read "notificationType" value in the "metadata" object. There are five types of notifications can be triggered for prepayment transactions:
Payment Recognized This type of notifications is sent when a prepayment transaction was payed by the consumer and settled amount is matched to the transaction amount. { Payment Reminder This type of notifications is sent to remind of the prepayment transaction is expiring soon. Expiration date is provided in the metadata section of the notification body. { Underpaid Transaction Expiration This type of notifications is sent when the invoice related to a transaction expires while not fully paid. Payed amount has been refunded to the consumer's acount. The 'refund' object type notification is provided as well, where the refunded amount can be identified (see 'refund' type explanation above). { Unpaid Transaction Expiration This type of notifications is sent when the invoice related to a prepayment transaction expires while not paid. { Overpayment Triggered when underlying payment was captured by the bank, but settled amount was greater than originally requested. Overpayed amount has been refunded to the consumer's acount. Once overpayed refund is completed, the 'refund' object type notification is provided as well, where the refunded amount can be identified (see 'refund' type explanation above). {
|
For the full list of SmartPay transaction statuses, please refer to this section.