Notifications and Webhooks

Nium uses webhooks to notify you, the clients, of your applications when any of the observable events occur.

You can provide Nium the URL of your host endpoint to receive the webhook events from the Nium One platform. The platform delivers the webhook events to your client-specified endpoint with a POST HTTP request method.

You need to provide the required URL in the following format: https://<customerHost:Port>/webhook

Nium sends different payloads depending on the trigger event. The trigger event can be identified based on the template field in the payload body.

Webhook event structure

• The body of the webhook event generally carries just enough details about the event. You're expected to use other APIs to fetch more details.
• The body of the webhook event includes a field template to indicate the webhook event type.
• Every webhook event includes the x-request-id data element in the header. The platform populates unique values in this data element for every unique webhook event, except when the platform attempts to redeliver a webhook event.
• You can also configure a static identifier, say x-partner-key, as part of the client setup, so the platform can include the client-specified identifier in the header of every webhook event.

The following is an example of a webhook event:

curl --location --request POST 'https://<customerHost:Port>/webhook' \
-H 'content-type: application/json' \
-H 'x-request-id: 123e4567-e89b-12d3-a456-426655440000' \
-d '{
        "name":"Samar",
        "customerHashId":"0de1e512-e0d7-4eca-ad41-dd39325facc2",
        "walletHashId":"696bad93-bda7-4e8d-8c31-318f8d6cbc5f",
        "cardHashId":"a344b0c8-d27d-4db5-8194-aacdefb558ca",
        "cardNumber":"4001-35xx-xxxx-1950",
        "transactionCurrency":"SGD",
        "transactionAmount":"10.00",
        "transactionDate":"2020-09-29 09:24:46",
        "balanceCurrency":"SGD",
        "authAmount":"10.0",
        "walletBalance":"102.00",
        "mcc":"5499",
        "merchantName":"Frankie Tibbs",
        "merchantCountry":"IN",
        "merchantCity":"MUMBAI",
        "authCode":"114733"
        "effectiveAuthAmount":"11",
        "rhaTransactionId":"55648c70-fa9a-4a4d-aaf6-618174c319d2",       
        "template":"CARD_POS_APPROVED_WEBHOOK"
}'

Event and notification types

Webhook events and notifications fall into the following categories:

• Callbacks: Manage compliance-related events, notifications, and customer redirection callbacks.
• Platform: Monitor core platform events, including client setup, virtual account assignments, and wallet transfers.
• Payouts: Receive updates on payout lifecycles, such as transaction statuses and beneficiary verification.
• Payins: Track events related to wallet funding, chargebacks, and funding instrument approvals.
• Issuing and Cards: Stay informed about card-related events, such as activation, transactions, declines, and settlements.

Delivery

Nium supports two forms of webhook events delivery:

• At most once, by default
• Retry delivery, which needs to be explicitly set up

At most once

The default delivery configuration that Nium supports is to deliver every webhook event at most once. An attempt is made to deliver a webhook event. If the delivery fails, due to a timeout or an HTTP response status code, other than 200, the platform does not retry delivering the webhook event.

Retry delivering webhook

You can work with Nium to configure the webhook events that you want the platform to retry delivering. It works in the following way:

1. We have configured a retry feature, for example, for the Card Wallet Funding webhook. This is an event that gets triggered whenever a customer's wallet receives funds.
2. As soon as funding is applied to a customer wallet, under your client setup in the platform, Nium triggers the Card Wallet Funding webhook event to your registered endpoint called Original-Attempt.
3. If that fails for some reason, the platform makes another attempt immediately called Retry-Attempt #1. In this retry, the platform includes the same x-request-id as it sent in the Original-Attempt.
4. If this Retry-Attempt #1 fails, then the platform waits for 2 hours before trying to redeliver the webhook event, called Retry-Attempt #2.
5. If this Retry-Attemp #2 fails, the platform waits for 2 hours and tries delivering again. This event is called Retry-Attempt #3.
6. In this manner, the platform continues retrying up to 20 times, Retry-Attempt #20, with a 2-hour time gap between each retry attempt.

🗒️ NOTE

This is not the default approach available for every webhook event for clients. Clients that want this feature enabled, for example, the platform retrying to deliver webhook events, can reach out to their Nium representative for support. This needs to be configured at the chosen webhook event level as part of the client configuration in the platform.

⚠️ CAUTION

Every redelivered webhook event has the same x-request-id header value to help you identify and ignore such duplicate webhook events.

Notifications

Nium supports three types of system-generated notifications, which are similar to trigger alerts that are sent in response to a specific user action or event.

• Email notifications
• SMS notifications
• Webhooks notifications

Email notifications

Nium can trigger different types of customer notifications through email. The notifications follow the default Nium template but can be customized or turned off based on the client's needs.

SMS notifications

Nium can send Short Message Service (SMS) notifications to customers only for the 3D Secure (3DS) One Time Password (OTP) protocol or the Visa Token Service (VTS) for Google Pay and Apple Pay.

Webhooks notifications

Nium provides webhooks to trigger email, SMS, or in-app notifications. Refer to the Webhooks overview guide.

The following table summarizes different scenarios and corresponding notifications triggered with SMS:

Scenario	Email template	Webhook	SMS
This template is triggered while adding a card to Google Pay. See note above.	CARD_GOOGLEPAY_EMAIL	VTS Token
3DS OTP during 3DS online transaction (Version 2 is currently in use).	CARD_SAMPLE_EMAIL	3DS OTP
3DS OTP during 3DS online transaction.	CARD_3DS_OTP_EMAIL	3DS OTP
VTS OTP during VTP provisioning.	CARD_VTS_PROVISION_EMAIL	VTS Token

The following table summarizes different scenarios and corresponding notifications triggered without SMS:

Scenario	Email template	Webhook
The cardholder makes a balance transfer from one currency wallet to another currency wallet. This is applicable to the multi-currency program.	CARD_BALANCE_TRF_BETWEEN_CURRENCIES_ WITHIN_SAME_WALLET_EMAIL	Balance Transfer within Wallet
This template is triggered when a customer is registered.	CARD_CUSTOMER_REGISTRATION_EMAIL	Customer Registration
This template is triggered during a client prefund-request notification.	CARD_PRE_FUND_APPROVAL_EMAIL	Prefund Approval
This template is triggered when the wallet is funded.	CARD_WALLET_FUNDING_EMAIL	Wallet Funding
This template is triggered in the event of wallet encashment.	CARD_WALLET_ENCASHMENT_EMAIL	Wallet Encashment
This template is triggered when a balance transfer happens within a customer's wallet.	CARD_BALANCE_TRF_BETWEEN_CURRENCIES_ WITHIN_SAME_WALLET_EMAIL	Balance Transfer Within Wallet
This template is triggered when a transfer between two customers occurs under the same client program.	CARD_P2P_TRANSFER_BETWEEN_WALLETS_EMAIL	P2P Transfer Between Wallets
This template is triggered when a physical card is assigned to a customer.	CARD_ASSIGN_CARD_EMAIL	No webhook
This template is triggered when an ADD-ON card is issued using the Add Card API.	CARD_ADD_ON_CARD_ISSUE_EMAIL	Add On Card
This template is triggered when the card's Personal Identification Number (PIN) is set.	CARD_SET_PIN_EMAIL	Set Pin
This template is triggered when the transaction is declined due to an incorrect PIN.	CARD_PIN_BLOCK_DECLINE_EMAIL	Pin Block Decline
This template is triggered when the card is replaced using the Issue Replacement Card API.	CARD_CARD_REPLACEMENT_EMAIL	No webhook
This template is triggered when the card is temporarily blocked.	CARD_TEMPORARY_BLOCK_EMAIL	Temporary Block
This template is triggered when a temporarily blocked card is removed.	CARD_TEMPORARY_BLOCK_REMOVAL_EMAIL	Temporary Block Removal
This template is triggered when the card is permanently blocked.	CARD_PERMANENT_BLOCK_EMAIL	Permanent Block
This template is triggered when the permanently blocked card is being replaced with a new card.	CARD_PERMANENT_BLOCK_REPLACEMENT_EMAIL	No webhook
This template is triggered when the POS transaction is approved.	CARD_POS_APPROVED_EMAIL	POS Approved
This template is triggered when the transaction is through an ATM.	CARD_ATM_APPROVED_EMAIL	ATM Approved
This template is triggered on successful VTS provisioning for Apple Pay.	CARD_ADD_CARD_CONFIRMATION_APPLEPAY_EMAIL	VTS Provisioning walletProvider = applePay
This template is triggered on successful VTS provisioning for Google Pay.	CARD_ADD_CARD_CONFIRMATION_GOOGLEPAY_EMAIL	VTS Provisioning walletProvider = googlePay
This template is triggered when the transaction is declined due to a blocked card.	CARD_BLOCK_CARD_DECLINE_EMAIL	Block Decline
This template is triggered when the transaction is declined due to an inactive card.	CARD_INACTIVE_CARD_DECLINE_EMAIL	Inactive Decline
This template is triggered when the transaction is declined due to insufficient funds.	CARD_INSUFFICIENT_FUNDS_DECLINED_EMAIL	Insufficient Funds Declined
This template is triggered when the transaction is declined because the card is expired.	CARD_EXPIRED_CARD_EMAIL	Expired Card
This template is triggered when the card restricts the transactions.	CARD_RESTRICTED_TRANSACTIONS_EMAIL	Restricted Transactions
This template is triggered when a transaction isn't supported.	CARD_TRANSACTION_NOT_SUPPORTED_EMAIL	Transaction Not Supported
This template is triggered when the card transaction limit is exceeded.	CARD_TRANSACTION_LIMIT_EXCEEDS_EMAIL	Transaction Limit Exceeds
This template is triggered when the card has the wrong Card Verification Value 2 (CVV2).	CARD_WRONG_CVV2_EMAIL	Wrong CVV2
This template is triggered when the card has the wrong expiration date.	CARD_WRONG_EXPIRY_EMAIL	Wrong Expiry
This template is triggered when the transaction is declined due to the wrong PIN entry.	CARD_WRONG_PIN_DECLINE_EMAIL	Wrong PIN Decline
This template is triggered when the transaction is declined due to the wrong PIN entry.	CARD_PIN_RETRY_EXCEED_DECLINE_EMAIL	Pin Retry Exceed Decline
This template is triggered manually by the Fraud and Risk team for specific customers.	CARD_RISK_AWARENESS_PIN_EMAIL	No webhook
This template is triggered manually by the Fraud and Risk team for specific customers.	CARD_SUSPECTED_COMPROMISE_EMAIL	No webhook
This template is triggered manually by the Fraud and Risk team for specific customers.	CARD_SUSPECTED_MISUSE_EMAIL	No webhook
3DS OTP during 3DS online transaction.	CARD_SAMPLE_EMAIL	3DS OTP
This template is triggered when the transaction is declined due to the Security and Risk policy set by Nium.	CARD_MISC_EMAIL	Miscellaneous
This template is triggered when the card system is down.	CARD_SYSTEM_DOWN_EMAIL	Card System Down
This template is triggered after adding a beneficiary with the payout method of the value BANK.	ADD_BENEFICIARY_BANK_EMAIL	No webhook
This template is triggered after adding a beneficiary with the payout method of the value WALLET.	ADD_BENEFICIARY_WALLET_EMAIL	No webhook
This template is triggered after adding a beneficiary with the payout method of the value CASH.	ADD_BENEFICIARY_CASH_EMAIL	No webhook
This template is triggered after adding a beneficiary with the payout method of the valueCARD.	ADD_BENEFICIARY_CARD_EMAIL	No webhook
This template is triggered after editing a beneficiary with the payout method of the value BANK.	EDIT_BENEFICIARY_BANK_EMAIL	No webhook
This template is triggered after editing a beneficiary with the payout method of the valueWALLET.	EDIT_BENEFICIARY_WALLET_EMAIL	No webhook
This template is triggered after editing a beneficiary with the payout method of the value CASH.	EDIT_BENEFICIARY_CASH_EMAIL	No webhook
This template is triggered after editing a beneficiary with the payout method of the value CARD.	EDIT_BENEFICIARY_CARD_EMAIL	No webhook
This template is triggered after deleting a beneficiary with the payout method of the value BANK.	DELETE_BENEFICIARY_BANK_EMAIL	No webhook
This template is triggered after deleting a beneficiary with the payout method of the value WALLET.	DELETE_BENEFICIARY_WALLET_EMAIL	No webhook
This template is triggered after deleting a beneficiary with the payout method of the value CASH.	DELETE_BENEFICIARY_CASH_EMAIL	No webhook
This template is triggered after deleting a beneficiary with the payout method of the value CARD.	DELETE_BENEFICIARY_CARD_EMAIL	No webhook
This template is triggered when a remittance transaction is initiated with the payout method of the value BANK.	REMIT_TRANSACTION_INITIATED_EMAIL	Remit Transaction Initiated
This template is triggered when a remittance transaction is initiated with the payout method of the value CASH.	REMIT_TRANSACTION_INITIATED_CASH_EMAIL	Remit Transaction Initiated
This template is triggered when a remittance transaction is initiated with the payout method of the valueWALLET.	REMIT_TRANSACTION_INITIATED_WALLET_EMAIL	Remit Transaction Initiated
This template is triggered when a remittance transaction is initiated with the payout method of the value CARD.	REMIT_TRANSACTION_INITIATED_CARD_EMAIL	Remit Transaction Initiated
This template is triggered when a payout is done of the value sent to Sender.	REMIT_TRANSACTION_SENT_TO_BANK_EMAIL	Remit Transaction Sent to Bank
This template is triggered when a payout is done of the value sent to Beneficiary.	REMIT_TRANSACTION_SENT_TO_BANK_CASH_BENI_EMAIL	Remit Transaction Sent to Bank
This template is triggered when a remittance transaction is made with the payout method of the value BANK is paid.	REMIT_TRANSACTION_PAID_EMAIL	Remit Transaction Paid
This template is triggered when a remittance transaction is made with the payout method of the value CASH is paid.	REMIT_TRANSACTION_PAID_CASH_EMAIL	Remit Transaction Paid
This template is triggered when a remittance transaction is made with the payout method of the value WALLET is paid.	REMIT_TRANSACTION_PAID_WALLET_EMAIL	Remit Transaction Paid
This template is triggered when a remittance transaction is made with the payout method of the value CARD is paid.	REMIT_TRANSACTION_PAID_CARD_EMAIL	Remit Transaction Paid
This template is triggered to a beneficiary when a remittance transaction is made with the payout method of the value BANK is paid.	REMIT_TRANSACTION_PAID_BANK_BENI_EMAIL	Remit Transaction Paid
This template is triggered to a beneficiary when a remittance transaction is made with the payout method of the value CASH is paid.	REMIT_TRANSACTION_PAID_CASH_BENI_EMAIL	Remit Transaction Paid
This template is triggered to a beneficiary when a remittance transaction is made with the payout method of the value WALLET is paid.	REMIT_TRANSACTION_PAID_WALLET_BENI_EMAIL	Remit Transaction Paid
This template is triggered to a beneficiary when a remittance transaction is made with the payout method of the value CARD is paid.	REMIT_TRANSACTION_PAID_CARD_BENI_EMAIL	Remit Transaction Paid
This template is triggered when a remittance transaction is made with the payout method of the value BANK is rejected.	REMIT_TRANSACTION_REJECTED_EMAIL	No webhook
This template is triggered when a remittance transaction is made with the payout method of the value CASH is rejected.	REMIT_TRANSACTION_REJECTED_CASH_EMAIL	No webhook
This template is triggered when a remittance transaction is made with the payout method of the value WALLET is rejected.	REMIT_TRANSACTION_REJECTED_WALLET_EMAIL	No webhook
This template is triggered when a remittance transaction is made with the payout method of the value BANK is returned.	REMIT_TRANSACTION_RETURNED_EMAIL	Remit Transaction Returned
This template is triggered when a remittance transaction is made with the payout method of the value CASH is returned.	REMIT_TRANSACTION_RETURNED_CASH_EMAIL	Remit Transaction Returned
This template is triggered when a remittance transaction is made with the payout method of the value WALLET is returned.	REMIT_TRANSACTION_RETURNED_WALLET_EMAIL	Remit Transaction Returned
This template is triggered when a remittance transaction is made with the payout method of the value CARD is returned.	REMIT_TRANSACTION_RETURNED_CARD_EMAIL	Remit Transaction Returned
This template is triggered when the compliance status, as a result of the Know Your Business (KYB) process, is anything other than complete for a client.	No email template	Client KYB Status
This template is triggered when an ADD_ON card is issued using the Add Card API.	CARD_ADD_ON_CARD_ISSUE_EMAIL	Add Card
This template is triggered when a card is activate.	CARD_ACTIVATION_CARD_EMAIL	Activate Card
This template is triggered when the transaction is declined due to an insufficient client-prefund balance.	CARD_INSUFFICIENT_FUNDS_DECLINED_EMAIL	Insufficient Funds Declined
This template is triggered after adding a beneficiary with a proxy payout method.	ADD_BENEFICIARY_PROXY_EMAIL	No webhook
This template is triggered after editing a beneficiary with a proxy payout method.	EDIT_BENEFICIARY_PROXY_EMAIL	No webhook
This template is triggered after deleting a beneficiary with a proxy payout method.	DELETE_BENEFICIARY_PROXY_EMAIL	No webhook
This template is triggered when a remittance transaction is initiated with a bank payout method.	REMIT_TRANSACTION_INITIATED_PROXY_EMAIL	Remit Transaction Initiated
This template is triggered when a remittance transaction is paid with a proxy payout method.	REMIT_TRANSACTION_PAID_PROXY_EMAIL	Remit Transaction Paid
This template is triggered when a remittance transaction is returned with a proxy payout method.	REMIT_TRANSACTION_RETURNED_PROXY_EMAIL	Remit Transaction Returned
This template is triggered to a beneficiary when a remittance transaction is paid with a proxy payout method.	REMIT_TRANSACTION_PAID_PROXY_BENT_EMAIL	Remit Transaction Paid