Callbacks

Last changes: 04-12-2023

Notification Service

This section covers how webhooks are used to notify about events that happen in an E-wallet Program. Some events, like disputed charges or account status changes, 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 recive a JSON payload depending on the notification type. Based on your integration requirements the individual notifications have to be turned on. Please contact Customer Support or your administrator to check your individual integration use case.

Authentication Options

Any of the below authentication methods can be selected for the corresponding program:

Authentication Type	Behavior
No Authentication	No authentication information is sent in the requests to the "Notification Target URL". IP Whitelisting is mandatory in this case. Please contact Customer Support or your Administrator for the IP address which must be whitelisted.
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".
OAuth Authentication	The Authentication URL along with the Username and Password must be specified. They are used for OAuth authentication to get a token via Client Credentials Grant. This authentication token is then attached to every call to "Notification Target URL".

Notification Types

There are 2 distinct notification types

Program Specific Notifications - sending more detailed transaction information regarding the entire program, in addition to user management, compliance and others.
Merchant Specific Notifications - only sending transaction related information regarding a specific merchant. They can be configured for each individual merchant.

You can provide a different endpoint for the Program' Notifications and each Merchant's Notifications. Please coordinate with your Technical Rollout Manager.

Program Specific Notifications

Settlement

If a transaction is Settled, a notification is sent to the "Notifications Target URL" specified in the program to which the transaction belongs to, if the following are activated:

Notification Service for the corresponding program
The "Settlement" notification type is enabled

{
  "uniqueReference": "{unique reference of the transaction being settled}",
  "notificationType": "Settlement"
}

Refund

If a Refund is performed for a transaction, a notification is sent to the "Notifications Target URL" specified in the program to which the transaction belongs to, if the following are activated:

Notification service for the corresponding program
The "Refund" notification type is enabled

{
    "uniqueReference": "{unique reference of the transaction being refunded}",
    "refundedTransactionReferences": [ "{array of transaction references of dependent transactions being refunded}" ],
    "refundTransactionReference": "{unique reference of the refund transaction}",
    "refundingTransactionReferences": [ "{array of transaction references of the dependent refunding transactions}" ],
    "notificationType": "Refund"
}

Chargeback

If a transaction is Charged Back, a notification is sent to the "Notifications Target URL" specified in the program to which the transaction belongs to, if the following are activated:

Notification service for the corresponding program
The "Chargeback" notification type is enabled

{
    "uniqueReference": "{unique reference of the transaction being charged back}",
    "chargedBackTransactionReferences": [ "{array of transaction references of dependent transactions being charged back}" ],
    "chargebackTransactionReference": "{unique reference of the chargeback transaction}",
    "chargingBackTransactionReferences": [ "{array of transaction references of the dependent chargeback transactions}" ],
    "amount": 12.34,
    "chargebackReason": {
        "code": "123",
        "description": "Example Reason for Chargeback"
    },
    "notificationType": "Chargeback"
}

Merchant On-boarding Completed

When a Merchant completes the On-boarding, a notification is sent to the "Notifications Target URL" specified in the program owning the Merchant, if the following are activated:

Notification service for the corresponding program is enabled
The "Merchant On-boarding Completed" notification is enabled

{
"notificationType": "MerchantOnboardingCompleted",
"programName": "{Name of the Program owning the Merchant}",
"programCode": "{Code of the Program owning the Merchant}",
"merchantName": "{Name of the Merchant that is On-boarding}",
"merchantReference": "{Unique Reference of the Merchant}",
"merchantStatus": "Completed"
}

Account Status Change

If an e-wallet user account changes its status, a notification is sent to the "Notifications Target URL" specified in the program owning the account whose status has been changed, if the following are activated:

Notification service for the corresponding program
The "AccountStatusChange" notification is enabled

{
"notificationType": "AccountStatusChange",
"accno": "{account number of the affected account}",
"externalAccountReference": "{external account reference of the affected account}",
"newStatus": "{status code of the new account status}"
}

Debtor Invoice Callback

If the API method 1.103 Perform Debtor Invoice Callback is called, a notification is sent to the "Notifications Target URL" specified in the program owning the account whose status has been changed, if the following are activated:

Notification service for the corresponding program
The "DebtorInvoiceCallback" notification is enabled

{
"notificationType": "DebtorInvoiceCallback",
"invoiceData": "{body of the 'Perform Debtor Invoice Callback' request}"
}

Compliance Check

If the "Manual Review Result" is changed for a compliance check record, a notification is sent to the "Notifications Target URL" specified in the program owning the account to which the "archiveId" is specified in the compliance check record, if the following are activated:

Notification Service for the corresponding program
The "ComplianceCallback" notification is enabled

{
"notificationType": "ComplianceCallback",
"archiveId": "{'ArchiveId' specified in the compliance check record}",
"decision": "{'ManualReviewResult' specified in the compliance check record: 1 -> 'OK', 0 -> 'KO'}",
"comment": "{'ReviewComment' specified in the compliance check record}"
}

Payment Option Added

If a Stored Payment Option is Added, a notification is sent to the "Notifications Target URL" specified in the program to which the account belongs to, if the following are activated:

Notification service for the corresponding program
The "Payment Option Added" notification type is enabled

{
  "notificationType": "PaymentOptionAdded",
  "storedPaymentOptionReference": "{Unique Reference of the Stored Payment Option}",
  "validUntil": "{Validity Date of the Stored Payment Option, format 'YYYY-MM-DD'}",
  "accno": "{Account Number to which the above Stored Payment Option belongs to}",
  "externalAccountReference": "{External Account Reference of the above Account}"
}

Payment Option Expiration

A notification will be sent the aligned number of days before the payment option expires. This gives you the option to trigger internal processes prompting the user to register a new credit / debit card and delete the one that is about to expire. To align on this functionality and the number of days before a payment option's expiration you would like to receive this notification - please contact your rollout manager.

To change the expiration date of a card first call 1.55 Delete Stored Payment Option, then 1.53 Init Add Stored Payment Option, prompting the user to provide the same card in the payment form, and lastly 1.54 Complete Add Stored Payment Option to finish the process.

For more details on the above flows please visit the Payment Option Management section.

{
"notificationType": "PaymentOptionExpiration",
"storedPaymentOptions":
[
{
"storedPaymentOptionReference": "{reference of the stored payment option to be expired}",
"paymentOptionCode": "{payment option code of the stored payment option to be expired}",
"validUntil": "{validity date of the stored payment option to be expired as YYYY-MM-DD}",
"accno": "{account number to which the stored payment option above belongs}",
"externalAccountReference": "{external account reference of the account above}"
}
]
}

Reject Expired Stored Payment Option

If a Transaction is Declined because the used Stored Payment Option is Expired, a notification is sent to the "Notifications Target URL" specified in the program to which the transaction belongs to, if the following are activated:

Notification service for the corresponding program
The "Reject Expired Stored Payment Option" notification type is enabled

{
  "notificationType": "RejectExpiredStoredPaymentOption",
  "storedPaymentOptionReference": "{Unique Reference of the Expired Stored Payment Option}",
  "validUntil": "{Validity Date of the Expired Stored Payment Option, format 'YYYY-MM-DD'}",
  "accno": "{Account Number to which the Expired Stored Payment Option belongs to}",
  "externalAccountReference": "{External Account Reference of the above Account}"
}

PaymentsOS Callbacks

If you use a Payment Option provided by PaymentsOS, a notification is sent to the "Notifications Target URL" specified in the program to which the transaction belongs to, if the following are activated:

Notification Service for the corresponding program
The "Authorization Feedback" notification is enabled
The "Capture Feedback" notification is enabled
The "Cancellation Feedback" notification is enabled
The "Refund Feedback" notification is enabled

{
    "notificationType": "AuthorizationFeedback",
    "processingStatus": "Status of transaction processing: 'Success' or 'Failed'",
    "processingReason": "Description of the transaction processing status",
    "transactionStatus": "RECEIVED or AUTHORIZED",
    "uniqueReference": "Unique reference of the transaction",
    "relatedTransactionReferences": [ {Array of transaction references of dependent transactions which are updated} ]
}

Merchant Specific Notifications

Settlement

If a transaction is Settled, a notification is sent to the "Notifications Target URL" specified for the merchant receiving the transaction, if the following are activated:

Notification Service for the specified merchant
The "Settlement" notification type is enabled

{
  "uniqueReference": "{unique reference of the transaction being settled}",
  "notificationType": "Settlement"
}

Refund

If a Refund is performed for a transaction, a notification is sent to the "Notifications Target URL" specified for the merchant receiving the transaction, if the following are activated:

Notification Service for the specified merchant
The "Refund" notification type is enabled

{
    "uniqueReference": "{unique reference of the transaction being refunded}",
    "refundedTransactionReferences": [ "{array of transaction references of dependent transactions being refunded}" ],
    "notificationType": "Refund"
}

Chargeback

If a transaction is Charged Back, a notification is sent to the "Notifications Target URL" specified for the merchant receiving the transaction, if the following are activated:

Notification Service for the specified merchant
The "Chargeback" notification type is enabled

{
    "uniqueReference": "{unique reference of the transaction being charged back}",
    "chargedBackTransactionReferences": [ "{array of transaction references of dependent transactions being charged back}" ],
    "amount": 12.34,
    "chargebackReason": {
        "code": "123",
        "description": "Example Reason for Chargeback"
    },
    "notificationType": "Chargeback"
}

Previous

Next