Webhooks for payments
Set up webhooks to receive notifications for events within your Viva account.
Overview
Viva supports webhooks, a simple and powerful solution that allows you to receive notifications each time a specific event takes place. Webhooks are particularly useful for asynchronous events such as asynchronous payments, for example, when the funds of the customer are transferred from their bank account into your Viva account.
Retry policy: Viva will assume you have successfully received a webhook notification if you respond with HTTP status 2xx to the POST calls received from us. In any other case, including HTTP status codes 3xx, 4xx, or 5xx, a retry mechanism will apply 24 times - one initial attempt plus 23 retries. Retries will run once per hour until a 2xx status is received or the maximum retry threshold is reached.
A maximum of 10 webhook URLs can be registered per event type. Ensure these endpoints are managed carefully to avoid exceeding the limit.
Webhook Events
The following events are available for webhook notifications. The tables below lists the available webhooks and the unique IDs (EventTypeId) which can be used to identify these events.
Events for Merchants
| Webhook | EventTypeId | Description |
|---|---|---|
| Command Bank Transfer Created | 768 | A bank transfer to an external IBAN has been created but not executed yet. The money has not yet been transferred from your wallet. |
| Command Bank Transfer Executed | 769 | A bank transfer to an external IBAN has been executed. In case of an instant bank account transfer, money has been transferred immediately from your wallet - which is linked with your IBAN - to the external IBAN. In case of a non-instant bank account transfer, money has been transferred from your wallet - which is linked with your IBAN - but not necessarily received yet by the external IBAN. |
| Transaction Payment Created | 1796 | A customer's payment has been successful. |
| Transaction Reversal Created | 1797 | A customer refund has been successfully actioned. |
| Transaction Failed | 1798 | A customer’s payment failed. The customer may retry, and the payment may eventually be successful and trigger a Transaction Payment Created webhook. |
| Transaction Price Calculated | 1799 | A commission payment has been withdrawn from your account by Viva. |
| Transaction Pos Ecr Session Created | 1802 | ECR integration only: The session is processed and a transaction is successfully created. |
| Transaction Pos Ecr Session Failed | 1803 | ECR integration only: The session has failed, been cancelled, timed out, or aborted. |
| Account Transaction Created | 2054 | A wallet account balance change. |
| Order Updated | 4865 | This webhook will be sent when an order’s status has been cancelled, either via Smart Checkout’s cancel/back button or via API. |
| Sale Transactions | The requested sale transactions are available to download. |
Events for ISV Partners
| Webhook | EventTypeId | Description |
|---|---|---|
| Transaction Payment Created | 1796 | A customer's payment has been successful. |
| Transaction Reversal Created | 1797 | A customer refund has been successfully actioned. |
| Transaction Failed | 1798 | A customer’s payment failed. The customer may retry, and the payment may eventually be successful and trigger a Transaction Payment Created webhook. |
| Transaction Pos Ecr Session Created | 1802 | ECR integration only: The session is processed and a transaction is successfully created. |
| Transaction Pos Ecr Session Failed | 1803 | ECR integration only: The session has failed, been cancelled, timed out, or aborted. |
| Account Connected | 8193 | Tiggered when a business account is successfully connected to the ISV account. |
| Account Verification Status Changed | 8194 | Triggered when the verification status of a connected account changes. |
Events for Marketplaces
| Webhook | EventTypeId | Description |
|---|---|---|
| Transaction Payment Created | 1796 | A customer's payment has been successful. |
| Transaction Reversal Created | 1797 | A customer refund has been successfully actioned. |
| Transaction Failed | 1798 | A customer’s payment failed. The customer may retry, and the payment may eventually be successful and trigger a Transaction Payment Created webhook. |
| Transaction Price Calculated | 1799 | A commission payment has been withdrawn from your account by Viva. |
| Transaction Pos Ecr Session Created | 1802 | ECR integration only: The session is processed and a transaction is successfully created. |
| Transaction Pos Ecr Session Failed | 1803 | ECR integration only: The session has failed, been cancelled, timed out, or aborted. |
| Account Transaction Created | 2054 | A wallet account balance change. |
| Order Updated | 4865 | This webhook will be sent when an order’s status has been cancelled, either via Smart Checkout’s cancel/back button or via API. |
| Obligation Created [DEPRECATED] | 5632 | Marketplace only: an obligation, such as a refund request, has been successfully sent to a marketplace seller. |
| Obligation Captured [DEPRECATED] | 5633 | Marketplace only: an obligation, such as a refund request, has been successfully paid by a marketplace seller. |
| Account Connected | 8193 | Marketplace only: triggered when an account is successfully connected to the platform. |
| Account Verification Status Changed | 8194 | Marketplace only: triggered when the verification status of a connected account changes. |
| Transfer Created | 8448 | Marketplace only: triggered when a transfer is made. |
| Sale Transactions | The requested sale transactions are available to download. |
Webhook notifications will not be triggered for cancelled transactions, or for payments that failed 3DS user authentication. See our Event ID codes.
Additionally, no notification will be triggered upon expiration of a payment order, but any subsequent successful payments will still trigger a webhook notification.
If you wish to test a Transaction Failed webhook, please use our Trigger a decline simulating functionality.
transactionId in the payload and make a call to the Retrieve Transaction API. Validate the orderCode, statusId and amount you received in the Retrieve Transaction API response and update your system accordingly.
Whitelist the Viva addresses
To successfully receive webhook notifications, you should whitelist the below IP addresses/ranges in both your server and your network firewall. The webhooks’ IP source will be from the below IP addresses/ranges:
| Production accounts | ||
|---|---|---|
| 51.138.37.238 | 40.127.253.112/28 | 51.105.129.192/28 |
| 20.54.89.16 | 4.223.76.50 | 51.12.157.0/28 |
| Demo accounts | ||
|---|---|---|
| 20.50.240.57 | 40.74.20.78 | 195.167.87.181 |
| 195.167.87.180 | 20.13.195.185 | 135.225.16.50 |
- * .vivapayments.com
- * .vivawallet.com
Setting Up Webhooks
To learn how to set up webhooks, please visit this page: Setting Up Webhooks.
Retry policy
Viva will assume you have successfully received a webhook notification if you respond with HTTP status 2xx to the POST calls received from us.
In any other case, including HTTP status codes 3xx, 4xx, or 5xx, a retry mechanism will apply. Viva will retry 24 times - one initial attempt plus 23 retries. Retries will run once per hour until a 2xx status is received or the maximum retry threshold is reached.
Get Support
If you would like to integrate with Viva, or if you have any queries about our products and solutions, please see our Contact & Support page to see how we can help!