Notifications

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.

important

SmartPay requires all merchant's notification endpoints to use https:\\ protocol for security reasons; http:\\ URLs are not supported.

Authentication Options

Based on the security requirements of the merchant website, the following authentication options are available:

Authentication Type	Behavior
No Authentication	The webhook request is sent without any authentication information.
Basic Authentication	The webhook request includes a username and password encoded in the HTTP headers. Please provide your username and password to us.
OAuth	The webhook request uses OAuth tokens for authentication. Please provide the OAuth provider URL, ClientID, and ClientSecret to us.

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, example: "c200b3fd-4960-4cd8-918c-5919013ce769".
merchantKey	String	UUID	Merchant 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".
context	String	-	The request body for "api" and "widget" events.
data	String	-	Details for the objectType parameter listed below.
origin	String	Enumeration	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	Enumeration	Description of the event type, example: "status.updated".
objectId	String	UUID	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".
objectType	String	Enumeration	Possible values: "payment", "refund", or "prepayment". Type of the event, mainly differentiating between "refund" and other transaction status changes under "payment". Type "prepayment" provides prepayment specific status changes.
metadata	Array	key, value pairs	Optional object (exists for specific use cases only, e.g. prepayment). Additional Ids and details linked to the notification: "metadata": { "transactionId": 102957125650, "reconciliationId": 102957125651 }.
sourceSystem	String	string	Source system that is sending the notification, i.e. "smartpay".

List of the available notifications

objectType	origin	Description
payment	"automated"	Created every time when SmartPay payment transaction status gets changed. Useful for tracking the statuses of asynchronously 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": "b06bde06-9949-4a4a-b843-ea54c7821d85",
  "merchantKey": "d1aa7f35-2542-46ae-9f10-923b3c5379ba",
  "createdAt": "2024-11-28T10:34:25.279Z",
  "context": null,
  "data": null,
  "origin": "automated",
  "eventType": "status.updated",
  "objectId": "b06bde06-9949-4a4a-b843-ea54c7821d85",
  "objectType": "payment",
  "metadata": null,
  "sourceSystem": "smartpay"
}

objectType	origin	Description
refund	"automated"	Created every time when SmartPay refund status gets changed. Useful for tracking the statuses of asynchronously 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 notification data, only refund and transaction identifiers are provided in "objectId" "id" fields respectively. To get the actual refund status use Get Payment Status 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": "b06bde06-9949-4a4a-b843-ea54c7821d85",
  "merchantKey": "d1aa7f35-2542-46ae-9f10-923b3c5379ba",
  "createdAt": "2024-11-28T10:39:20.840Z",
  "context": null,
  "data": null,
  "origin": "automated",
  "eventType": "status.updated",
  "objectId": "3f412edb-4f07-4393-acce-e52226cf2aff",
  "objectType": "refund",
  "metadata": null,
  "sourceSystem": "smartpay"
}

Get payment status API:

GET {base_url}/payment/status/c200b3fd-4960-4cd8-918c-5919013ce769

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

{
    "reconciliationReferenceId": "CQm1sOcWIOO2tChSCbfQL",
    "description": "TEST*SMARTPAY*Zvx2v0l3Uk",
    "paymentStatus": "CAPTURED",
    "creationDate": "2021-10-01T08:36:30.794Z",
    "lastStatusDate": "2021-10-01T08:42:28.517Z",
    "transactionOverview": {
        "amount": 10.08,
        "currencyCode": "EUR",
        "mit": false,
        "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"
}

Prepayments

objectType	origin	Description
prepayment	"automated"	Triggered when certain actions happened 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
• Payment Reminder
• Underpaid Transaction Expiration
• Unpaid Transaction Expiration
• Overpayment

Prepayment - Payment Recognized

This type of notifications is sent when a prepayment transaction was paid by the consumer and settled amount is matched to the transaction amount.

{
  "id": "d86d3305-13cd-4187-9a5b-2375b4114ccd",
  "merchantKey": "bec422d6-b944-46f4-8cc1-a2896e340553",
  "createdAt": "2024-11-19T23:02:28.161Z",
  "context": null,
  "data": null,
  "origin": "automated",
  "eventType": "payment.info",
  "objectId": "d86d3305-13cd-4187-9a5b-2375b4114ccd",
  "objectType": "prepayment",
  "metadata": {
    "notificationType": "TransactionPaymentRecognized",
    "underpaidAmount": "10.80 EUR"
  },
  "sourceSystem": "smartpay"
}

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

{
  "id": "ca9a039d-047f-430b-86e5-7cb9bf5be77e",
  "merchantKey": "bec422d6-b944-46f4-8cc1-a2896e340553",
  "createdAt": "2024-11-19T23:02:41.985Z",
  "context": null,
  "data": null,
  "origin": "automated",
  "eventType": "payment.info",
  "objectId": "ca9a039d-047f-430b-86e5-7cb9bf5be77e",
  "objectType": "prepayment",
  "metadata": {
    "notificationType": "TransactionPaymentReminder",
    "underpaidAmount": "230.26",
    "expirationDate": "2024-11-20"
  },
  "sourceSystem": "smartpay"
}

Prepayment - 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 account. The "refund" object type notification is provided as well, where the refunded amount can be identified (see "refund" type explanation above).

{
  "id": "aa5574e0-5bd4-4ae0-9134-ba5374f48fca",
  "merchantKey": "bec422d6-b944-46f4-8cc1-a2896e340553",
  "createdAt": "2024-11-20T23:30:54.160Z",
  "context": null,
  "data": null,
  "origin": "automated",
  "eventType": "status.updated",
  "objectId": "aa5574e0-5bd4-4ae0-9134-ba5374f48fca",
  "objectType": "prepayment",
  "metadata": {
    "notificationType": "UnderpaidTransactionExpiration"
  },
  "sourceSystem": "smartpay"
}

Prepayment - Unpaid Transaction Expiration

This type of notifications is sent when the invoice related to a prepayment transaction expires while not paid.

{
  "id": "9c486cc6-06bd-4c7c-9446-db30a3154735",
  "merchantKey": "bec422d6-b944-46f4-8cc1-a2896e340553",
  "createdAt": "2024-11-20T23:29:53.680Z",
  "context": null,
  "data": null,
  "origin": "automated",
  "eventType": "status.updated",
  "objectId": "9c486cc6-06bd-4c7c-9446-db30a3154735",
  "objectType": "prepayment",
  "metadata": {
    "notificationType": "UnpaidTransactionExpiration"
  },
  "sourceSystem": "smartpay"
}

Prepayment - Overpayment

Triggered when underlying payment was captured by the bank, but settled amount was greater than originally requested. Overpaid amount has been refunded to the consumer's account. Once overpaid refund is completed, the "refund" object type notification is provided as well, where the refunded amount can be identified (see "refund" type explanation above).

{
  "id": "d86d3305-13cd-4187-9a5b-2375b4114ccd",
  "merchantKey": "bec422d6-b944-46f4-8cc1-a2896e340553",
  "createdAt": "2024-11-19T23:03:31.315Z",
  "context": null,
  "data": null,
  "origin": "automated",
  "eventType": "payment.info",
  "objectId": "d86d3305-13cd-4187-9a5b-2375b4114ccd",
  "objectType": "prepayment",
  "metadata": {
    "notificationType": "TransactionOverpayment"
  },
  "sourceSystem": "smartpay"
}

Payment Options

objectType	eventType	Description
stored-payment-option	"details.updated"	Triggered when a consumer's payment option gets changed, used to notify the merchants so that they are up-to date with the payment options stored by their customers.

{
  "id": "NOTIFICATION@5dbb6da6-ac81-4cf3-96dd-fa9346f2ff80",
  "merchantKey": "f1202c60-d5e0-4b6b-8f97-0476e4191148",
  "createdAt": "2024-06-18T08:07:00.402Z",
  "context": null,
  "data": null,
  "origin": "automated",
  "eventType": "details.updated",
  "objectId": "nMUghOhOC3GZq9HBfRk8k",
  "objectType": "stored-payment-option",
  "metadata": {
    "customerAccountId": "5435345934534"
  },
  "sourceSystem": "smartpay"
} 

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