Skip to main content
Optimization Protection

Notification types

Notifications are generated and sent to you when an event that you are subscribed to occurs.

  • You can subscribe to notifications by providing the event type, subtype, and subscription channel (webhook, email).
    • For webhooks, you must provide the callbackURL.
    • For emails, you must provide the recipientDetails.preferredLanguage and recipientDetails.emailAddress.
    • You can subscribe to either one channel type or both depending on the event type.
    • If you want both webhook and email notifications, you must create a subscription for each channel type individually.
  • Webhooks are sent to the callbackURL and emails are sent to the recipientDetails.emailAddress you provide during the onboarding process. 
  • You can also choose which events you want to enable during the onboarding process.

To learn more about the process of subscribing using the Notifications API, refer to how to subscribe to notifications.

Attention
A few things to keep in mind when you are subscribing to a notification:
  • If the callbackURL has query parameters, it must be encoded.
  • The callbackURL will be active after a buffer of 60 mins.
  • Webhooks may arrive out of order, so use the webhook’s messageCreateTimestamp field to determine the correct sequence.

Notifications API supports the following event types and subtypes.

Payment transaction events

Payment transaction events (paymentUpdateNotification) notify you of the status of asynchronous transactions in the Online Payments API.

Supported subscription channel: Webhook

When subscribing to this event, you can choose one, some, or all of the following subtype notifications:

Payment transaction event subtypes
Subtype Description Channel
All Notifies you of all transactions regardless of status. Webhook
PaymentApproved Notifies you when a transaction is successfully approved. Webhook
PaymentDeclined Notifies you when a transaction is declined. Webhook
PaymentErrored Notifies you when a transaction fails with an error code. Webhook
PaymentVoid Notifies you when a transaction is voided by the merchant. Webhook
PaymentClosed Notifies you when a transaction is closed at the payment gateway. Webhook

Token events

Token events (tokenLifecycleNotification) notify you when a token or tokenized data event occurs. The information related to the token is sent by the token service provider.

Supported subscription channel: Webhook

When subscribing to this event, you can choose all, some, or one of the following subtype notifications:

Token event subtypes
Subtype Description Channel
All  Notifies you of all token-related events. Webhook
CardDetailsUpdate  Notifies you of any metadata changes that occurred for the tokenized card product. Webhook
TokenStateChange  Notifies you about potential changes in the token and its state. Webhook
TokenProvisionUpdate  Notifies you about the asynchronously provisioned token information for future processing. Webhook
BulkTokenUpdate  Notifies you about the status information of bulk tokenization files. Webhook

For additional information regarding tokenization and token lifecycle management, refer to Tokenization API.  

Pay by Bank events

Pay by Bank (PBB) events notify you when there is a change impacting the Pay by Bank account.

Account update events

PBB account update events  (accountUpdateNotification) notify you when linking a Pay by Bank account succeeds or fails, or there is a change in the account.

Supported subscription channel: Webhook

When subscribing to this event, you can choose all, or one of the following subtype notifications:

PBB account update event subtypes
Subtype Description Channel
AccountLinkSuccess Notifies you when an account link is successful. Webhook
AccountLinkException Notifies you when an account link fails. Webhook
MicroDepositInitiated Notifies you when a micro-deposit has been initiated from the sender's account. Micro-deposits verify the legitimacy and ownership of a bank account, with an amount less than 1 dollar. Webhook
MicroDepositSent Notifies you when a micro-deposit has been successfully sent to the receiver's account. Webhook
MicroDepositVerificationFailed Notifies you when a micro-deposit could not be completed. Webhook
MicroDepositVerified Notifies you when a micro-deposit has been verified. Webhook
MicroDepositReadyToValidate Notifies you when a micro-deposit is ready to validate. Webhook
Note

In the initial callback notification for account link success, the account holder’s Personal Identifiable Information (PII) details like firstName, middleName, lastName, and address details are masked. To unmask an account holder’s PII, you must send a GET request to the /notifications endpoint using the notificationId provided in the initial notification to retrieve the complete PII details. 

Account information service events

PBB account information service events (accountInformationServiceNotification) notify you when consent for account linking is granted or denied.

PBB account information service events
Subtype Description Channel
ConsentFixSuccessful Notifies you when the consent for account linking is granted. Webhook
ConsentFixFailed Notifies you when the consent for account linking is not granted. Webhook

For additional information regarding Pay by Bank, refer to Pay by Bank API.

Account updater events

Account updater events (accountUpdateNotification) notify you of the details of an updated card account.

Supported subscription channel: Webhook

When subscribing to this event, you can choose the following subtype notification:

Account update event subtypes
Subtype Description Channel
AccountUpdaterStatus Notifies you when an update is made to the account information. Webhook

For additional information regarding account updater, refer to Account updater API.

Consumer profile events

Consumer profile events (consumerProfileNotification) notify you when a consumer profile is created, payment method is modified, or the status of a bulk consumer profile file changes.

Supported subscription channel: Webhook

When subscribing to this event, you can choose all, some, or one of the following subtype notifications:

Consumer profile event subtypes
Subtype Description Channel
All Notifies you of all events related to a consumer profile. Webhook
Created Notifies you when a consumer profile is created. Webhook
PaymentMethodCreated Notifies you when a payment method is added to a consumer profile. Webhook
PaymentMethodDeleted Notifies you when a payment method is deleted from a consumer profile. Webhook
BulkConsumerProfileUpdateNotification Notifies you when the status of a bulk consumer profile file changes. Webhook

For additional information regarding consumer profiles, refer to Consumer Profile API.

Digital onboarding events

Digital onboarding events help notify you of any changes during the screening and onboarding process.

Supported subscription channel: Webhook, Email

Entity events

Entity events (entityOnboardingNotification) notify you when the status of an entity changes during the screening and onboarding process. When subscribing to this event, you can choose all, some, or one of the following subtype notifications:

Entity event subtypes
Subtype Description Channel   
EntityScreening Notifies you when the status of an entity changes during the merchant screening process. Webhook
EntityOnboarding Notifies you when the status of an entity changes during the onboarding process. Webhook
EntityOnboardingReviewInProgress  Notifies you when the entity review is in progress during the onboarding process. You can enable this by default by providing your email address in your onboarding request. Email
EntityOnboardingInformationRequested                                                                                       Notifies you when the entity review requires additional information to be processed during the onboarding process. You can enable this by default by providing your email address in your onboarding request. Email
EntityOnboardingV2  Notifies you when the status of an entity changes during the onboarding process. Webhook

For additional information regarding digital onboarding and merchant screening, refer to Digital Onboarding API. 

Merchant status events

 Merchant status events (merchantStatusNotification) notify you when the following happens:

  • Status of the onboarding process changes
  • Status of the merchant account changes

Supported subscription channel: Webhook, Email

When subscribing to this event, you can choose all, some, or one of the following subtype notifications:

Merchant status events
Subtype Description Channel
All Notifies you of all events related to digital onboarding. Webhook, Email
MerchantOnboardingInProgress Notifies you when the merchant onboarding process is in progress. Webhook, Email
MerchantOnboardingDeclined Notifies you when the merchant onboarding process declines. Webhook, Email
MerchantOnboardingCompleted Notifies you when the merchant onboarding process is completed. Webhook, Email
MerchantSuspendedAutoblock Notifies you when the merchant account is suspended with autoblock. Webhook, Email
MerchantSuspendedWithFundHold Notifies you when the merchant account is suspended with the funds on hold. Webhook, Email
MerchantSuspendedWithoutFundHold Notifies you when the merchant account is suspended without the funds on hold. Webhook, Email
MopActivationCompleted Notifies you when the method of payment is activated for use. Webhook, Email
MopActivationDeclined Notifies you when the method of payment activation is declined. Webhook, Email
MerchantAccountPendingForClosure Notifies you when the merchant account is pending closure. Webhook, Email
MerchantReactivationCompleted Notifies you when the merchant account reactivation process is completed. Webhook, Email
MerchantReactivationInProgress Notifies you when the merchant account reactivation process is in progress. Webhook, Email
MerchantReactivationDeclined  Notifies you when the merchant account reactivation process is declined. Webhook, Email

Payout events

Payout events (payoutNotification) notify you when the status of a payout changes after it is posted for processing.

Supported subscription channel: Webhook, Email

When subscribing to this event, you can choose all, some, or one of the following subtype notifications:

Payout event subtypes
Subtype Description Channel
All Notifies you of all events related to payout. Webhook, Email
PayoutFailure Notifies you when a payout fails during processing. Webhook, Email
PayoutUnderReview Notifies you when a payout is put under review during processing. Webhook, Email
PayoutCreated Notifies you when a payout is created. Webhook, Email
PayoutDenied Notifies you when a payout is denied. Webhook, Email
PayoutCompleted Notifies you when a payout processing is completed. Webhook, Email
PayoutRejected Notifies you when a payout is rejected. Webhook, Email
PayoutFailureResolved Notifies you when a payout which had an issue is resolved and released for deposit. Webhook, Email
PayoutUnderReviewReleased Notifies you when a payout which was held is released. Webhook, Email
PayoutRejectedResolved Notifies you when a rejected payout which was resubmitted and released for deposit. Webhook, Email
FinancialAdjustmentInitiated  Notifies you when a financial adjustment impacting your payout is initiated. Email

Report status events

Report status events (reportStatusNotification) notify you when the status of a report changes.

Supported subscription channel: Webhook

When subscribing to this event, you can choose all, some, or one of the following subtype notifications:

Report status event subtypes
Subtype Description Channel
All Notifies you of all events related to reporting. Webhook
DailyCompleted Notifies you when a daily report generation process completes successfully. Webhook
WeeklyCompleted Notifies you when a weekly report generation process completes successfully. Webhook
MonthlyCompleted Notifies you when a monthly report generation process completes successfully. Webhook
AdhocRunCompleted Notifies you when an ad hoc report generation process completes successfully. Webhook
DailyErrored Notifies you when a daily report generation process fails due to an error. Webhook
WeeklyErrored Notifies you when a weekly report generation process fails due to an error. Webhook
MonthlyErrored Notifies you when a monthly report generation process fails due to an error. Webhook
AdhocRunErrored Notifies you when an ad hoc report generation process fails due to an error. Webhook

For additional information regarding reporting, refer to Reporting API.

3-D secure events

3DS events (authenticationUpdateNotification) notify you when the authentication process completes.

Supported subscription channel: Webhook

When subscribing to this event, you can choose all, some, or one of the following subtype notifications:

3DS event subtypes
Subtype Description Channel
All Notifies you of all events related to 3DS. Webhook
AuthenticationComplete Notifies you when the authentication process completes for 3DS authentication. Webhook

For additional information regarding 3-D secure, refer to 3DS API.

Recommendation events

Recommendation events (recommendationNotification) notify you when a soft decline occurs on a transaction.

Supported subscription channel: Webhook

When subscribing to this event, you can choose all, some, or one of the following subtype notifications:

Recommendation event subtypes
Subtype Description Channel
All Notifies you of all events related to recommendations. Webhook
PaymentRetry Notifies you when a transaction is soft declined and payment retry is recommended. Webhook

Dispute events

Dispute events (disputeNotification) notify you when the status of a dispute case changes. The payment network sends the dispute information via the Disputes Management platform.

Supported subscription channel: Webhook

When subscribing to this event, you can choose all, some, or one of the following subtype notifications:

Dispute event subtypes
Subtype Description Channel
All Notifies you of all events related to dispute notifications. Webhook
DisputeClosed Notifies you when the dispute case is closed on the payment network. Webhook
DisputeReceived Notifies you when the dispute case is received on the payment network. Webhook
DisputeMerchantResponseRequested Notifies you when the dispute case requires a response from the merchant.
 Webhook

Refund events

Refund events (refundUpdateNotification) notify you when there is a change in the status of a refund.

Supported subscription channel: Webhook

When subscribing to this event, you can choose all, some, or one of the following subtype notifications:

Refund event subtypes
Subtype Description Channel
All Notifies you of all events related to refund notifications. Webhook
RefundApproved Notifies you when the refund is approved. Webhook
RefundDeclined Notifies you when the refund is declined. Webhook
RefundErrored Notifies you when the refund fails due to an error. Webhook

QR code events

QR code events (qrCodeStatusNotification) notify you when the status of a QR code changes in the payment life cycle.

Supported subscription channel: Webhook

When subscribing to this event, you can choose all, some, or one of the following subtype notifications:

QR code event subtypes
Subtype Description Channel
All Notifies you of all events related to QR code notifications. Webhook
QRCodeCreated Notifies you when a QR code is created. Webhook
QRCodeExpired Notifies you when a QR code expires. Webhook
QRCodePaid Notifies you when a payment is made using the QR code. Webhook
QRCodeSettlementProcessing Notifies you when a payment that was made using the QR code is under processing for settlement. Webhook
QRCodeCancelled Notifies you when a QR code is cancelled. Webhook

For additional information regarding QR code, refer to Pay via QR code.

ACH status events

Automated Clearing House (ACH) status events (achStatusNotification) notify you when the status of an ACH transaction changes in the payment life cycle.

Supported subscription channel: Webhook

When subscribing to this event, you can choose all, some, or one of the following subtype notifications:

ACH status event subtypes
Subtype Description Channel
All Notifies you of all events related to ACH status notifications. Webhook
AchReturnReceived Notifies you when the ACH transactions are returned by the financial institution. Webhook

Direct Debit Account update events

Direct Debit Account (DDA) update events (directDebitAccountNotification) notify you when the status of a direct debit account is updated.

Supported subscription channel: Webhook, Email

When subscribing to this event, you can choose all, some, or one of the following subtype notifications:

DDA update event subtypes
Subtype Description Channel
All Notifies you of all events related to DDA account update notifications. Webhook, Email
DirectDebitAccountUpdateSuccess Notifies you when the update to a DDA is successful. Webhook, Email
DirectDebitAccountUpdateFailure Notifies you when the update to a DDA fails. Webhook, Email
DirectDebitAccountUpdatePending Notifies you when the update to a DDA is still pending processing. Webhook, Email

Embedded payment events

Embedded payment events notify you when there is a change in the account or the payment transaction.

Account update events

Account update events (accountUpdateNotification) notify you when there is a change in the status of an account.

Supported subscription channel: Webhook

When subscribing to this event, you can choose all, some, or one of the following subtype notifications:

Account update event subtypes
Subtype Description Channel
All Notifies you of all events related to account update notifications. Webhook
AccountCreated Notifies you when an account is created. Webhook
AccountOverdrawn Notifies you when an account is overdrawn. Webhook
AccountClosed Notifies you when an account is closed. Webhook
RecipientAccountValidation Notifies you when a micro-deposit is received and the deposit is ready to validate.  Webhook

Allocation order instruction events

Allocation order instruction events (allocationOrderInstructionNotification) notify you when there is a change in the status of an order.

Supported subscription channel: Webhook

When subscribing to this event, you can choose all, some, or one of the following subtype notifications:

Allocation order instruction event subtypes
Subtype Description Channel
All Notifies you of all events related to allocation order instruction notifications. Webhook
AllocationOrderInstructionUpdate Notifies you when the order is validated and the status of the order changes based on the validation result. Webhook

Allocation order settlement events

Allocation order settlement events (allocationOrderSettlementNotification) notify you when there is a change in the allocation order

Supported subscription channel: Webhook

When subscribing to this event, you can choose all, some, or one of the following subtype notifications:

Allocation order settlement event subtypes
Subtype Description Channel
All Notifies you of all events related to allocation order settlement notifications. Webhook
PspSettlementTransferUpdate Notifies you when the settlement payment is done and the Payment Service Provider (PSP) settlement transfer is complete. Webhook
DistributionTransferUpdate

Notifies you when:

  • A distribution transfer is scheduled.
  • A distribution transfer reaches a terminal state (rejected or complete).
 Webhook
PlatformSettlementTransferUpdate

Notifies you when:

  • A platform settlement transfer is scheduled.
  • A platform settlement transfer reaches a terminal state (rejected or complete).
  • A completed transfer is returned.
 Webhook

Processing threshold events

Processing threshold events (processingThresholdNotification) notify you when there is an adverse change in the status of the account.

Supported subscription channel: Webhook

When subscribing to this event, you can choose all, some, or one of the following subtype notifications:

Processing threshold event subtypes
Subtype Description Channel
All Notifies you of all events related to processing threshold notifications. Webhook
ProcessingThresholdStatus Notifies you when the account is in an adverse status. For example, overdrawn or non-sufficient funds. Webhook

For additional information regarding embedded payments, refer to Embedded payments API.

Tax events

Tax events (taxNotification) notify you when a backup withholding notice is issued. These notifications are sent automatically and don't require you to subscribe.

Supported subscription channel: Email

The following table lists the subtypes of tax events:

Tax event subtypes
Subtype Description Channel
All Notifies you of all events related to backup withholding. Email
BackupWithholdingPending Notifies you when a backup withholding notice is issued. Email
BackupWithholdingPendingTwo Notifies you when a backup withholding notice is issued again within two years after the first notification. Email
BackupWithholdingPrevented Notifies you when the updated tax form is submitted before the backup withholding effective date. Email
BackupWithholdingPreventedTwo Notifies you when the updated tax form is submitted again within two years after the first notification. Email
BackupWithholdingStarted Notifies you when you are placed on backup withholding. Email
BackupWithholdingStartedTwo Notifies you when you are placed on backup withholding again within two years after the first notification. Email
BackupWithholdingStopped Notifies you when you are removed from backup withholding. Email
BackupWithholdingStoppedTwo Notifies you when you are removed from backup withholding again within two years after the first notification. Email

Balance monitoring events

Balance monitoring events (balanceMonitoringNotification) notify you when we need to recover a negative balance from you.

Supported subscription channel: Webhook, Email

Balance monitoring events
Subtype Description Channel
All Notifies you of all events related to balance monitoring. Webhook, Email
DirectDebitInitiated Notifies you when a direct debit to return the merchant’s account to a non‑negative balance is initiated. This also indicates that an email has been sent for the same. Webhook, Email
DirectDebitRetry Notifies you when the direct debit attempt has returned with error code R03 (insufficient funds in the linked account) and a retry is going to be initiated. This also indicates that an email has been sent for the same. Webhook, Email
DirectDebitReturn Notifies you when the first direct debit attempt returns an error code other than R03 or if the second direct debit attempt fails for any reason, resulting in your account being sent to collections. This also indicates that an email has been sent for the same. Webhook, Email

Security alert events

Security alert events (securityAlert) notify you when there is a change in the status of your biometrics login.

Supported subscription channel: Email

Security alert events
Subtype Description Channel
All Notifies you of all events related to security alerts. Email
LoginLocked Notifies you when your biometrics login is locked. Email
PasswordReset Notifies you when your biometrics password reset request has been raised. Email
LoginFailed Notifies you when there is a failed login attempt. Email

Subscribe to notifications