Notifications

Last changes: 06-07-2022

Webhook Notification

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 TypeBehavior

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 Service Settings". These fields are used for basic authentication
for every call made to the "Notifications Target URL".

Notification Format

 

The "Notification Target URL" will receive a JSON payload respecting the below form

FieldTypeFormatDescription
idStringstring

Contains the payment transaction identifier

Example: "c200b3fd-4960-4cd8-918c-5919013ce769"

createdAtStringyyyy-MM-dd'T'HH:mm:ss.SS'ZTime of the creation of the event:
Example: 2021-05-26T14:29:05.994Z
originString

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

objectIdStringUUID

In case of a payment status change, it contains SmartPay transactionId
In case of a refund status change, it contains SmartPay refundId
Example: "4f6e528d-1438-43ee-9835-a17c05c34429"

 

objectTypeString

 Enum:

"payment"

"refund"

Type of the event, mainly differentiating between "refund" and other transaction status changes under "payment".
 
metadataDictionarykey, value pairs

Additional Ids and details linked to the notification:
"metadata": {

      "reconciliationId": 102957125651

}

List of the available notifications

objectType

origin

eventType

Description

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.

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""status.updated"

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:

{
  "id": "c200b3fd-4960-4cd8-918c-5919013ce769",
  "createdAt": "2021-10-01T08:42:28.637Z",
  "origin": "automated",
  "eventType": "status.updated",
  "objectId": "4f6e528d-1438-43ee-9835-a17c05c34429",
  "objectType": "refund"
}

Get Payment Status Api:

[GET] <base_url>/payment/status/c200b3fd-4960-4cd8-918c-5919013ce769

{
    "reconciliationReferenceId": "CQm1sOcWIOO2tChSCbfQL",
    "description": "VWFS*SMARTPAY*Zvx2v0l3Uk",
    "paymentStatus": "CAPTURED",
    "creationDate": "2021-10-01T08:36:30.794Z",
    "lastStatusDate": "2021-10-01T08:42:28.517Z",
    "transactionOverview": {
        "amount": 10.08,
        "currencyCode": "EUR",
        "transactionId": "c200b3fd-4960-4cd8-918c-5919013ce769",
        "paymentMethod": "CARDS"
    },
    "modifications": [
        {
            "modificationData": {
                "type": "CAPTURE",
                "modificationId": "CPT-USnqEheOjT",
                "reconciliationReferenceId": "CQm1sOcWIOO2tChSCbfQL"
            }
            "status": "CAPTURED",
            ...
        },
        {
            "modificationData": {
                "type": "REFUND",
                "modificationId": "da4c3ddc-5279-45a1-b60f-8d0802591fff",
                "refundId": "4f6e528d-1438-43ee-9835-a17c05c34429",
                "reconciliationReferenceId": "FLg5GWlukm0rUq5SwJfs3"
            },

            "status": "REFUNDED",
            ...
        }
    ],
    "statusHistory": [
        ...
    ],
    "carrierNumber": "someapmail@email.com"
}

 

For the full list of SmartPay transaction statuses, please refer to this section.