Webhooks for payments
Viva Wallet supports webhooks, a simple and powerful solution that allows you to receive notifications each time a specific event takes place.
The following events are available for which a notification can be sent:
- Obligation Created – a marketplace obligation (refund request) has been successfully sent to a marketplace seller.
- Obligation Captured – a marketplace obligation (refund request) has been successfully paid by a marketplace seller.
- Account Transaction Created – wallet account balance change.
- Transaction Payment Created – a customer’s payment has been successful.
- Transaction Price Calculated – a commission payment has been withdrawn from your account by Viva Wallet.
- Transaction Reversal Created – a customer refund has been successfully actioned.
- Transaction Failed – a customer payment has been declined by their issuing bank.
- Command Bank Transfer Created – 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 – a bank transfer to an external IBAN has been executed but not necessarily received yet (the money has been transferred from your wallet, but not necessarily received yet into the external IBAN).
To receive webhook notifications, you need to create a public URL resource that can receive (via POST) objects of type Message<TransactionEventData>.
Message has the following properties:
- EventData ( TransactionEventData ): the actual notification
- EventTypeId ( int ): the type of the event that triggered the notification
- Created ( datetime ): the date and time the notification was initially created
TransactionEventData has the following properties:
- Amount ( decimal ): the signed amount of the transaction. Represents the total funds paid by the customer and includes TotalFee
- CardNumber ( string ): the card number used (applicable for card related transaction types)
- CardTypeId ( byte ): Possible values 0(Visa), 1(Mastercard), 2(Diners), 3(Amex), 4(Invalid), 5(Unknown), 6(Maestro), 7(Discover), 8(JCB)
- CompanyName ( string ): the company name of the Merchant
- CurrencyCode ( string ): the currency of the transaction in ISO 4217 numeric format (e.g. “978” for Euro)
- CurrentInstallment ( byte ): the current installment ordinal (use in relation with TotalInstallments parameter)
- CustomerTrns ( string ): the CustomerTrns property as set during the creation of the Order
- Email ( string ): customer email
- FullName ( string ): customer Fullname
- InsDate ( datetime ): the date and time the transaction took place
- MerchantId ( uuid ): the MerchantId of the Merchant
- MerchantTrns ( string ): the MerchantTrns property as set during the creation of the Order
- OrderCode ( long ): the OrderCode of the transaction
- ParentId ( uuid ): the parent TransactionId (if any) of the current transaction
- ResellerCompanyName ( string ): the name of the Reseller (if any) that received the payment
- ResellerId ( uuid ): the ResellerId of the Reseller (if any) that received the payment
- ResellerSourceAddress ( string ): the address of the source of the Reseller (if any) that received the payment
- ResellerSourceCode ( string ): the SourceCode of the source of the Reseller (if any) that received the payment
- SourceCode ( string ): the SourceCode of the Merchant used for the transaction
- StatusId ( string ): the status of the transaction
- TargetPersonId ( uuid ): the target logged-in user of the transaction (e.g. for wallet payments, this is the wallet owner id)
- TotalCommission ( decimal ): interchange++ fee = customer bank fee + card scheme fee + Viva fee
- TotalFee ( decimal ): the signed fees that apply to the transaction (e.g. if paid through reseller network)
- TotalInstallments ( byte ): the total installments of the transaction
- TransactionId ( uuid ): the TransactionId of the transaction
- TransactionTypeId ( int ): the type of transaction
You may confirm the transactions status through the StatusId parameter.
Viva Wallet will assume you have successfully received a webhook notification if you respond with http status 200 to the POST calls received from us. In any other case (e.g. http status 404,401,500) a retry mechanism will start and run once per hour until a status 200 is received or the maximum retries threshold is reached (72 retries / 3 days).
Check out the related tutorial below for more details on this topic: