Notifications
Webhook Notification
Introduction
This section covers how webhooks are used to notify about events that happen in SmartPay. Some events, like expiry of a card or the automated MIT transactions, are not the result of a direct API request. Webhooks solve these problems 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 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
| Field | Type | Format | Description |
|---|---|---|---|
| id | String | string | ID of the Subscription Module event triggering the notification: Example: "event-f81c4016-9c74-4046-9079-c00dbe4a5ce2" |
| 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", "created", "deleted", "status.updated", "billing.expires", "billing.updated", "billing.scheduled" | Description of the event type: created: object creation (e.g subscription, plan) updated: object amendment(e.g subscription, plan) deleted: object deletion/cancellation(e.g subscription, plan) status.updated: subscription, billing-cycle, subscription transaction status change billing.expires: card used as a payment option and about to expire billing.updated: this event is triggered whenever the billingAgreement of a subscription is updated billing.scheduled: this event is created when the merchant configuration is setup to notify the merchant X days before the billing. |
| objectId | String | UUID | Unique identifier of the object linked to the created event & notification (e.g subscription ID, transaction ID) Example: "subscription-f81c4016-9c74-4046-9079-c00dbe4a5ce2" |
| objectType | String | Enum: "subscription", "plan", "billing-cycle", "payment-series", "transactions" "manual-retry" "payment" "refund" | Name of the object linked to the created event & notification. Example:"subscription" |
| metadata | Dictionary | key, value pairs | Optional object. Additional Ids and details linked to the notification: "metadata": { "reconciliationId": 102957125651 } |
List of the available notifications
| objectType | origin | eventType | Description |
|---|---|---|---|
| subscription | "api" | "created" | Triggered when Create subscription API is requested |
| subscription | "api" | "updated" | Each PATCH request on the subscription creates an event. |
| subscription | "widget" | "billing.updated" | Each time a billing-agreement is updated on the widget, a new event is created. |
| subscription | "automated" | "status.updated" | An event is created every time the subscription changes its status. |
| subscription | "automated" | "billing.scheduled" | The event is created when the merchant configuration is setup to notify the merchant X days before the billing. |
| subscription | "automated" | "billing.expires" | Available for Cards only. Event created when the card is about to expire (current month). |
| subscription | "automated" | "billing.updated" | Every time the nextBillingDate is updated, an event is created. |
| subscription | "api" | "deleted" | Event created when a subscription is canceled immediately |
| billing-cycle | "automated" | "created" | Event created when a billing cycle is created. |
| billing-cycle | "automated" | "status.updated" | Event created every time the billing cycle changes statuses. |
| billing-cycle | "automated" | "billing.updated" | Event created based on updating the billingAgreement within a transaction |
| subscription-plan | "api" | "created" | Based on the creation of a subscription plan. |
| subscription-plan | "api" | "updated" | Based on the amendment of a subscription plan. |
| subscription-plan | "api" | "deleted" | Based on the deletion/cancellation of a subscription plan. |
| payment-series | "api" | "created" | Based on the creation of a payment-series. |
| payment-series | "api" | "updated" | Based on the amendment of a paymentSerie. |
| payment-series | "automated" | "billing.expires" | Available for Cards only. Event created when the card is about to expire (current month). |
| payment-series | "widget" | "billing.updated" | Each time a billing-agreement is updated on the widget, a new event is created. |
| payment-series | "api" | "deleted" | Based on the deletion of a paymentSerie |
| transaction | "automated" | "created" | When a transaction is created via automated processing of billing cycle. |
| transaction | "api" | "created" | When a transaction is created via manual-retry |
| transaction | "automated" | "status.updated" | Created when the transaction changes statuses. |
| manual-retry | "api" | "created" | Created when a manual retry is performed |