Transaction Failed

Notification that a customer payment has failed.


This webhook will be sent when a failed customer payment has been attempted to one of your wallets. The reason the payment failed is indicated by the ‘ResponseEventId’ code.

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.

A customer may retry a payment (e.g. by retrying to pay using a different payment method), so a Transaction Failed webhook may be then followed by a Transaction Payment Created webhook, indicating that the customer has actually managed to pay, despite the original failure.

Consequently, please do not treat a Transaction Failed webhook as ‘final’, as a Transaction Payment Created webhook may follow, indicating a successful payment.

You should confirm the payment result with the combination of OrderCode, TransactionId and the StatusId parameters. As an extra layer of confirmation, you have the option to use Retrieve Transaction Details API.

Webhook configuration

If you are setting up an ISV integration, please see our ISV Create webhook API call

To enable within the Viva Wallet banking app:

  1. Log in to Viva Wallet, demo or live , and select the required account.

  2. Visit Settings > API Access > Webhooks.

  3. Click on the Create Webhook link.
    The New Webhook dialog box is displayed.

  4. Enter your webhook URL in the URL field.

  5. Click on the Verify link.
    If verified successfully, a confirmation message is displayed.

  6. Choose Transaction Failed from the Event Type dropdown:

    Transaction Failed webhook

  7. Select the Active checkbox to activate notifications.

  8. Click on the Save button.

Response example

You may find below the sample response with EventTypeId 1798.

  "Url": "Your webhook url",
  "EventData": {
    "Moto": false,
    "Email": "",
    "Phone": "799999999999",
    "BankId": "NET_BNCT",
    "Systemic": false,
    "Switching": false,
    "ParentId": null,
    "Amount": 1000,
    "ChannelId": "245a790d-c98d-4d80-ad97-a9b1efb5771e",
    "TerminalId": 50000000,
    "MerchantId": "11ac9cd4-c9ea-48d3-b414-1f10ce664aad",
    "OrderCode": 3464811134270497,
    "ProductId": null,
    "StatusId": "E",
    "FullName": "John Doe",
    "ResellerId": null,
    "DualMessage": false,
    "InsDate": "2022-05-26T02:51:09.077",
    "TotalFee": 0,
    "CardUniqueReference": "347E552560C0FD1CB31D3123CB060BC763421803",
    "CardToken": "2BFCB1FD4F000DB41CB5BA76CAFB68D76AB87752",    
    "CardNumber": "606005XXXXXX0148",
    "TipAmount": 0,
    "SourceCode": "9999",
    "SourceName": "websource",
    "Latitude": null,
    "Longitude": null,
    "CompanyName": "Luxembourg Services",
    "TransactionId": "8d31eed6-bd43-4d93-b146-6e857d09c88d",
    "CompanyTitle": "Luxembourg Services",
    "PanEntryMode": "81",
    "ReferenceNumber": 66720,
    "ResponseCode": null,
    "CurrencyCode": "978",
    "OrderCulture": "en-GB",
    "MerchantTrns": null,
    "CustomerTrns": "Short description for customer",
    "IsManualRefund": false,
    "TargetPersonId": null,
    "TargetWalletId": null,
    "LoyaltyTriggered": false,
    "TransactionTypeId": 5,
    "TotalInstallments": 0,
    "CardCountryCode": null,
    "CardIssuingBank": null,
    "RedeemedAmount": 0,
    "ClearanceDate": null,
    "CurrentInstallment": 0,
    "Tags": [],
    "BillId": null,
    "ResellerSourceCode": null,
    "ResellerSourceName": null,
    "ResellerCompanyName": null,
    "ResellerSourceAddress": null,
    "CardExpirationDate": "2022-11-30T00:00:00",
    "RetrievalReferenceNumber": null,
    "AssignedMerchantUsers": [],
    "AssignedResellerUsers": [],
    "CardTypeId": 6,
    "ResponseEventId": 310,
    "ElectronicCommerceIndicator": null
  "Created": "2022-05-25T23:51:09.1255633Z",
  "CorrelationId": "22-145-E823540F",
  "EventTypeId": 1798,
  "Delay": null,
  "MessageId": "b2b46d3c-5bdb-4622-b281-d105616033bb",
  "RecipientId": "11ac9cd4-c9ea-48d3-b414-1f10ce664aad",
  "MessageTypeId": 512

Webhook body

You can find below the body parameters of this webhook

Parameter Description Example
Moto (boolean) True/False, Indicates if the card details were entered by a third person or by customers themselves false
Email (string) Customer email "customer email"
Phone (string) Phone number of the customer null
BankId (string) Schema "NET_VISA"
Systemic (boolean) If this is a transaction not initiated by the merchant or the customer but a system initiated trn (edge cases, e.g. Bancontact) false
Switching (boolean) If the transaction is a switching transaction false
ParentId (uuid) The parent TransactionId (if any) of the current transaction null
Amount (decimal) The signed amount of the transaction. Represents the total funds paid by the customer and includes TotalFee 99.05
ChannelId (uuid) Woocommerce, shopify, smart checkout, api, pos etc. "245a790d-c98d-4d80-ad97-a9b1efb5771e"
TerminalId (int) Id of the POS if it is a physical payment 90000000
MerchantId (uuid) The MerchantId of the Merchant "bdf4c6b3-c26d-4046-b5df-5c443ec39d09"
OrderCode (long) The OrderCode of the transaction 5039420255772601
ProductId (uuid) If not empty, wallet refill null
StatusId (string) The status of the transaction "E"
FullName (string) Customer Fullname "George Mitsiou"
ResellerId (uuid) The ResellerId of the Reseller (if any) that received the payment null
InsDate (datetime) The date and time the transaction took place "2021-11-04T17:06:02.153"
TotalFee (decimal) The signed fees that apply to the transaction (e.g. if paid through reseller network) 0
CardToken (string) The Token of the card "2BFCB1FD4F000DB41CB5BA76CAFB68D76AB87752"
CardUniqueReference (string) The Token of the card "2BFCB1FD4F000DB41CB5BA76CAFB68D76AB87752"
CardNumber (string) The card number used (applicable for card related transaction types) "414746XXXXXX0133"
TipAmount (decimal) The amount for the tip which is linked with the payment order 0
SourceCode (string) The SourceCode of the Merchant used for the transaction 8362
SourceName (string) The Merchant's source name "Test"
Latitude (decimal) If physical source, GPS coordinates null
Longitude (decimal) If physical source, GPS coordinates null
CompanyName (string) The company name of the Merchant "Greek Services"
TransactionId (uuid) The TransactionId of the transaction "92e0debb-fdf4-4392-a940-290b0c62ea6b"
CompanyTitle (string) Business Title "Greek Services"
PanEntryMode (int) How the card was used 01
ReferenceNumber (int) Used by card schemes to identify a transaction (created by us) 981049
ResponseCode (int) The response code of the transaction 05
CurrencyCode (string) The currency of the transaction in ISO 4217 numeric format (e.g. “978” for Euro) 978
OrderCulture (string) The language (culture) of the order "el-GR"
MerchantTrns (string) The MerchantTrns property as set during the creation of the Order "Short description of items/services purchased by customer with card installments"
CustomerTrns (string) The CustomerTrns property as set during the creation of the Order "Carpet Cleaning Services"
IsManualRefund (boolean) Internal process false
TargetPersonId (uuid) The target logged-in user of the transaction (e.g. for wallet payments, this is the wallet owner id) null
TargetWalletId (int64) The target wallet of the transaction null
LoyaltyTriggered (boolean) If the customer paid using loyalty points in addition to the charge false
TransactionTypeId (int) The type of transaction 5
TotalInstallments (byte) The total card installments of the transaction 0
CardCountryCode (string) The country the card was issued from "SG"
CardIssuingBank (string) The bank the card was issued from "CITIBANK"
RedeemedAmount (byte) This has to do with loyalty, it is the amount redeemed using points 0
ClearanceDate (datetime) The day of the clearence null
CurrentInstallment (byte) The current card installment ordinal (use in relation with TotalInstallments parameter) 0
Tags (arrayOfStrings) Information that Merchant inputs []
BillId (uuid) The id of the bill payment (if the transaction is a bill payment transaction) null
ResellerSourceCode (string) The SourceCode of the source of the Reseller (if any) that received the payment null
ResellerSourceName (string) The name of the Reseller (if any) that received the payment null
ResellerCompanyName (string) The name of the Reseller (if any) that received the payment null
ResellerSourceAddress (string) The address of the source of the Reseller (if any) that received the payment null
CardExpirationDate (datetime) The expiration date of the card used "2027-12-31T00:00:00"
RetrievalReferenceNumber (string) Used to retrieve the transaction from external systems 130815981049
AssignedMerchantUsers (arrayOfStrings) Merchants assigned to the source of the transaction []
AssignedResellerUsers (arrayOfStrings) Resellers assigned to the source of the transaction []
CardTypeId (byte) Possible values 0(Visa), 1(Mastercard), 2(Diners), 3(Amex), 4(Invalid), 5(Unknown), 6(Maestro), 7(Discover), 8(JCB) 0
ResponseEventId (int) the internal EventId of the transaction, used for INTERNAL OPERATIONS loyalty, ctap, bancontact advices 10005
ElectronicCommerceIndicator (int) A code appended to the Success/Failure URL as a query string parameter in addition to Event ID 7
Created (datetime) Transaction's creation timestamp "2021-09-02T07:39:28.8496795Z"

Get Support

If you would like to integrate with Viva Wallet, or if you have any queries about our products and solutions, please see our Contact & Support page to see how we can help!