Skip to main content

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 TypeBehavior
No AuthenticationNo authentication information is sent in the requests to the "Notification Target URL".
Basic AuthenticationThe 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
idStringstringID of the Subscription Module event triggering the notification:
Example: "event-f81c4016-9c74-4046-9079-c00dbe4a5ce2"
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
eventTypeStringEnum:
"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.
objectIdStringUUIDUnique identifier of the object linked to the created event & notification (e.g subscription ID, transaction ID)
Example: "subscription-f81c4016-9c74-4046-9079-c00dbe4a5ce2"
objectTypeStringEnum:
"subscription",
"plan",
"billing-cycle",
"payment-series",
"transactions"
"manual-retry"
"payment"
"refund"
Name of the object linked to the created event & notification.
Example:"subscription"
metadataDictionarykey, value pairsOptional object. Additional Ids and details linked to the notification:
"metadata": { "reconciliationId": 102957125651 }

List of the available notifications

objectTypeorigineventTypeDescription
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