Webhooks

Viva Wallet now supports webhooks, a simple and powerful solution that allows you to receive notifications each time a specific event takes place. The following two events are currently available (more to be added soon):

  • Create transaction
  • Cancel/refund transaction

You can now be programmatically notified each time a transaction is created or refunded, which is even more useful for offline payment methods (cash, DIAS payments etc).

To receive webhook notifications, all you need to do is create a publicly available URL resource that can receive (via POST) objects of type Message<TransactionEventData>.

Message has the following documented properties

  • EventData ( TransactionEventData ): the actual notification, described below
  • EventTypeId ( int ): the type of the event that triggered the notification. Possible values 1796(Transaction Created), 1797(Transaction cancelled)
  • Created ( datetime ): the date and time the notification was initially created

TransactionEventData has the following documented 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(Uknown), 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 (“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 ): the signed total commission of the transaction
  • 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 the transaction. Possible values explained below

Sample JSON objects

Create Transaction (EventTypeId: 1796)

{
  "EventData":{
	"Amount": 100.50,
	"CardNumber": "411111XXXXXX1111",
	"CardTypeId": 0,
	"ClientId": "90a7114f-3a7a-466b-8a45-000111222555",
	"CompanyName": "Viva Ηλεκτρονικές Υπηρεσίες",
	"CurrencyCode": 978,
	"CurrentInstallment": 0,
	"CustomerTrns": "Customer description",
	"Email": "customer@viva.gr",
	"FullName": "Customer FullName",
	"InsDate": "2014-06-18T14:20:30.45+03:00",
	"MerchantId": "90a7114f-3a7a-466b-8a45-000111222666",
	"MerchantTrns": "Merchant Reference",
	"OrderCode": 776027772607,
	"ParentId": "90a7114f-3a7a-466b-8a45-000111222777",
	"ResellerCompanyName": "Παπασωτηρίου",
	"ResellerId": "90a7114f-3a7a-466b-8a45-000111222888",
	"ResellerSourceAddress": "Πανεπιστημίου 37 και Κοραή, Αθήνα",
 	"ResellerSourceCode": "2233",
	"ResellerSourceName": "Πανεπιστημίου",
	"SourceCode": "Default",
	"StatusId": "F",
	"TotalCommission": 2.71,
	"TotalFee": 0.50,
	"TotalInstallments": 0,
	"TransactionId": "90a7114f-3a7a-466b-8a45-000111222888",
	"TransactionTypeId": 5
  },
  "EventTypeId": 1796,
  "Created": "2014-06-18T14:20:30.45+03:00"
}

Property TransactionTypeId can have one of the following values:

TypeId Description
0 Capture from Preauth
5 Charge Card
6 Charge Card w. Installments
9 Wallet Charge
15 Dias Payment
16 Cash Payment

E.g. For a transaction of type 6 (Charge Card w. Installments) you will only receive a notification for the initial charge, concerning the total amount. You will not receive any notification for the subsequent installments (type 5) at any time. 

Cancel/Refund Transaction (EventTypeId: 1797)

{
  "EventData":{
	"Amount": -100.50,
	"CardNumber": "411111XXXXXX1111",
	"CardTypeId": 0,
	"ClientId": "90a7114f-3a7a-466b-8a45-000111222555",
	"CompanyName": "Viva Ηλεκτρονικές Υπηρεσίες",
	"CurrencyCode": 978,
	"CurrentInstallment": 0,
	"CustomerTrns": "Customer description",
	"Email": "customer@viva.gr",
	"FullName": "Customer FullName",
	"InsDate": "2014-06-18T14:20:30.45+03:00",
	"MerchantId": "90a7114f-3a7a-466b-8a45-000111222666",
	"MerchantTrns": "Merchant Reference",
	"OrderCode": 776027772607,
	"ParentId": "90a7114f-3a7a-466b-8a45-000111222777",
	"ResellerCompanyName": "Παπασωτηρίου",
	"ResellerId": "90a7114f-3a7a-466b-8a45-000111222888",
	"ResellerSourceAddress": "Πανεπιστημίου 37 και Κοραή, Αθήνα",
 	"ResellerSourceCode": "2233",
	"ResellerSourceName": "Πανεπιστημίου",
	"SourceCode": "Default",
	"StatusId": "F",
	"TotalCommission": -2.71,
	"TotalFee": -0.50,
	"TotalInstallments": 0,
	"TransactionId": "90a7114f-3a7a-466b-8a45-000111222888",
	"TransactionTypeId": 7
  },
  "EventTypeId": 1797,
  "Created": "2014-06-18T14:20:30.45+03:00"
}

Property TransactionTypeId can have one of the following values:

TypeId Description
4 Refund Card Transaction
7 Void Card Transaction
11 Wallet Refund Transaction
13 Refund Card Transaction from Claim
17 Void Cash

Retry policy

Viva Payments will assume you have successfully received a webhook notification if you respond with http status 200 to the above POST calls. 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 max retries threshold is reached (72 retries / 3 days).  

Webhook URL verification

In order to use a new webhook URL, Viva Wallet needs to verify that the given URL is available for immediate use.

Each time you enter a new webhook URL via the banking app, you need to verify it (by clicking on the “verify” link next to URL input textbox). This action will start the process of a simple GET http call to your URL. Your page should print a JSON response of the following format:

{
  "Key":"B3248222FDCD1885AEAFE51CCC1B5607F00903F6"
}

To receive the webhook authorization code, all you need to do is call (via GET) the following API action

/api/messages/config/token

with standard API authentication headers). This call will give you the above requested key which you can print to the page as is. You can always disable a webhook (without deleting it), to temporarily stop receiving notifications.

In case you need to setup IP restriction, webhooks are sent from the following IPs:

Production:

  • 13.80.70.181
  • 13.80.71.223
  • 13.79.28.70

Demo:

  • 94.70.170.65
  • 94.70.174.36
  • 94.70.255.73
  • 94.70.248.18
  • 62.38.158.36
  • 194.219.230.78
  • 83.235.24.226

Detailed usage of webhooks is demonstrated in the code samples within our public GitHub pages.