The webhook notification serves to provide a notification that informs the Remote Host about actions that have been made or information that needs to be relayed to your own customers.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
For certain transactions, only a webhook request will be sent and not an authorization request as Visa requires us to approve the transaction no matter what. For example, a reversal to an original deduction request must be approved, therefore a webhook will be sent to notify you that a reversal has occurred and it is expected that money is adjusted accordingly based on the webhook, check the case by case #reversals for more information.
To confirm that the request is authentic, we will always send a header called X-COP-Signature-256. It will be prefixed sha256={hash of the request body with secret}. For example, X-COP-Signature-256: "sha256=7bfa3187cddb25ce4a31194db16738c1ef9aceb5117d86cc9c87faccface06b7"
Webhook Types are defined as follows:
- transaction: This webhook notifies you of the final outcome of a request. If you approved a transaction but the webhook indicates a failure, you should revert the transaction.
- Note: For transaction webhook which marked as
rejected, we'll also provide therejection_reasonas a indicator of the error classification, check transaction rejection reasons for more information.
- Note: For transaction webhook which marked as
- otp_notification: Triggered when your user requests a one-time password. You can choose the method to relay this information to your user.
- Note: for the
merchant,amount,currencyfields, omit empty.
- Note: for the
- card_spend_limit: Sent when a user reaches their card spending limit.
- reconciliation_manual_adjustment: Sent when there is a discrepancy between the Base 2 clearing file and the Base 1 live transaction records. You may need to adjust (either deduct or refund) based on the action recommended.
- reconciliation_success: We send you a list of transactions that have matched amounts between the transaction clearing file and the live transaction.
- pre_authorization_release: Sent when we automatically release a hold on a preauthorized amount.
- card_token_passcode: Provides a passcode needed for card token authentication.
- card_delivery: Sent to inform merchant of card delivery status.
- oob_notification: Triggered when your user requests an out-of-band authentication. You can choose the method to relay this information to your user.
- Note: for the
transaction_id,authentication_idare the identifiers for the 3DS transaction. For the 3DS transaction which is adding the card, theacquirer_amountwill be zero. - You can utilize the identifiers to obtain oob, check obtain out-of-band authentication for more information
- Note: for the
- card_token_provisioned: Triggered when your user successfully provisioned a token. You can choose the method to relay this information to your user
- For more information please refer to provisioning-notification.
- settlement_account_topup: Triggered when topup to StraitsX settlement account is sucessfuly performed. It will inform important information such as amount, currency and source of transfer.
- settlement_summary : Triggered after daily settlement processis done to inform settlement amount.
- settlement_offset : This will notify you whenever a settlement offset occurs, allowing you to track credits and debits more accurately.
- card_token_provisioning_failed: Triggered when card token provisioning is failed
- card_token_status_changed: Sent when a card token’s status transitions to a new state
- card_status_transition: Sent when a card's status changes (e.g. activated, suspended, blocked, closed). Requires the "Card Status Transition Webhook" feature to be enabled.
- card_pin_set: Sent when a customer successfully set their card PIN. Requires the "Card PIN Action Webhook" feature to be enabled.
- card_pin_changed: Sent when a customer successfully changed their card PIN. Requires the "Card PIN Action Webhook" feature to be enabled.
- card_pin_reset: Sent when a customer successfully reset their card PIN. Requires the "Card PIN Action Webhook" feature to be enabled.
- card_custom_per_transaction_limit_revoked: Sent when a custom per-transaction limit on a card is revoked.
- dispute_financial_advice: Sent when a transaction-level dispute financial record is received via the Visa clearing system.
Webhook retry and Timeout
Webhook is an important mechanism for us to communicate transaction status so that you are able to utilize the notification to make the right adjustment to the cardholder's account.
In the event of a failure when sending webhook for transaction (webhook event_type=transaction), we will be doing 11 retries with the below intended intervals:
| Retry Count | Delay |
|---|---|
| 1 | 1s |
| 2 | 2s |
| 3 | 4s |
| 4 | 8s |
| 5-7 | 10m |
| 8-10 | 1h |
| 11 | 3h |
Each attempt also has a 10-second timeout. If your server does not respond within 10 seconds, the attempt is considered failed and will move to the next retry.