Webhooks overview

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 types

The trigger events that the Nium One platform sends fall into one of the following four sections, based on the scenario:

• Platform events
• Payout events
• Payin events
• Issuing and Cards events.

Platform events

• Client Setup
• Client KYB Status
• Client Refund Approval
• Customer Registration
• Customer Update
• Customer Compliance Status
• Wallet Encashment
• Balance Transfer Within Wallet
• Cashback Credit
• P2P Transfer Between Wallets
• Prefund Approval
• Virtual Account Assigned
• Virtual Account Assignment Failed

Payout events

• Remit Transaction Initiated
• Remit Transaction Expired
• Remit Transaction Returned
• Remit Transaction Paid
• Remit Transaction Sent to Bank

Payin events

• Direct Debit Funding Instrument Approved
• Direct Debit Funding Instrument Cancelled
• Direct Debit Funding Instrument Failed
• Direct Debit Micro-Deposit Successful
• Direct Debit Transaction Return
• Direct Debit Transaction Chargeback Settled
• Wallet Funding

Issuing and cards events

• Add Card
• Assign Card
• Add On Card
• Activate Card
• 3DS OTP
• VTS Token
• VTS Provisioning
• Set Pin
• Permanent Block
• Temporary Block
• Temporary Block Removal
• POS Approved
• ATM Approved
• Transaction Reversal
• Wrong PIN Decline
• Inactive Decline
• Block Decline
• Card System Down
• Expired Card
• Miscellaneous
• PIN Block Decline
• PIN Retry Exceed Decline
• PIN Retry Exceed Soft Block
• Insufficient Funds Declined
• Insufficient Funds Declined Client
• Wrong CVV2
• Transaction Limit Exceeds
• Restricted Transactions
• Wrong Expiry
• Transaction Not Supported
• Settlement Debit
• Settlement Credit
• Settlement Direct Debit
• Settlement Reversal

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.