Program Specific Notifications

Last changes: 10-19-2023

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

Sent when the Debtor Management Provider notifies of an Invoice for the related Transaction / Order, belonging to the Host Program, and the below are configured:

  • Debtor Management is Setup in the Host Program
  • The "Invoice Callback URL" Endpoint is Configured
{
  "notificationType": "DebtorInvoiceCallback",
  
  "id": "{Unique Invoice Identifier in the Debtor Management}",
  "customerId": "{Identifier of the Customer / Payer Account}",
  "created": "{Created Time, Format YYYY-MM-DD[T]HH:mm:ss[Z]}",
  "documentType": "{Type of Invoice, ex. Invoice, Memo, etc.}",
  "status": "{Status of the Invoice in the Debtor Management}",
  
  "items": // The "items" Array can contain Multiple Orders
  [{
    "itemId": "{Unique Identifier of the Order / Payment}",
    
    "applicationItems": // Can contain Multiple Order Items
    [{
      "number": "{Identifier of the Order Position Number / Item}",
      "totalAmountInclusiveVat": {Gross Price of the Order Item},
      "totalAmountExclusiveVat": {Net Price of the Order Item},
      "outstanding": {Amount Still Pending Payment for Item},
      "status": {Status of Order Item in Debtor Management}
    }]
  }],
  
  "totalAmountInclusiveVat": {Gross Amount of the Entire Invoice},
  "totalAmountExclusiveVat": {Net Amount of the Entire Invoice},
  "totalAmountVat": {The Full VAT Amount of the Entire Invoice},
  "totalOutstanding": {Full Amount Pending Payment of Invoice}
}

Note: The possible values of "documentType"  can be found under Document Type.

Debtor Error Callback

Sent when the Debtor Management Provider notifies of an Error with the User Data / Transaction / Order belonging to the Host Program, and the below are configured:

  • Debtor Management is Setup for Host Program
  • The "Error Callback URL" Endpoint is configured
{
  "notificationType": "DebtorErrorCallback",

  "error": "{Error Description forwarded from Debtor Management Provider}",

  "itemIdentifier": {
    "itemType": "{Designates the Entity Type of the Following 'itemId'}",
    "itemId": "{Unique ID of User / Transaction / Order having an Error}",
    "relatedOrderId": "{Optional, Only if Error is Related to an Order}",
    "clientId": "{Identifier of Client's Debtor Management Environment}",
    "division": "{Either 'USR' for B2C Booking or 'BIZ' for B2B Booking}"
  }
}

Note: The Possible Values of "error"  can be found in the Lookups.

Note: The "itemType"  can hold only one of the below values:

ValueDescription
MASTERDATAError with the User's Debtor Data
ORDERError with the Deposit / Payment
REFUNDError with Refund of the Deposit
PAYMENT_TRANSACTIONError with Order's related Deposit
PAYMENT_REFUNDError with Order's related Refund

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} ]
}