Webhooks
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 currently:
- Create transaction
- Cancel / refund transaction
- Transaction price calculated
- Bank transfer created
- Bank transfer executed
- Obligation captured (online marketplace access only)
- Obligation cancelled (online marketplace access only)
Note that we also have a Webhooks API, details further down this page.
Overview
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 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), 5633(obligation captured), 5634(obligation 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 (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 ): 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
Further details
Create transaction event
This is the same as the event type Transaction Payment Created in the Viva Wallet banking app:
To access this feature:
- Log in to Viva Wallet banking app.
- Visit Settings > API Access.
- Click on the Create Webhook link.
EventTypeId: 1796 (JSON object)
{
"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": "[4-digit code of your payment source]",
"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 event
This is the same as the event type Transaction Reversal Created in the Viva Wallet banking app:
To access this feature:
- Log in to Viva Wallet banking app.
- Visit Settings > API Access.
- Click on the Create Webhook link.
EventTypeId: 1797 (JSON object)
{
"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": "[4-digit code of your payment source]",
"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 |
Transaction price calculated event
This is the same as the event type Transaction Price Calculated in the Viva Wallet banking app:
To access this feature:
- Log in to Viva Wallet banking app.
- Visit Settings > API Access.
- Click on the Create Webhook link.
Bank transfer created event
This is the same as the event type Command Bank Transfer Created in the Viva Wallet banking app:
To access this feature:
- Log in to Viva Wallet banking app.
- Visit Settings > API Access.
- Click on the Create Webhook link.
Bank transfer executed event
This is the same as the event type Command Bank Transfer Executed in the Viva Wallet banking app:
To access this feature:
- Log in to Viva Wallet banking app.
- Visit Settings > API Access.
- Click on the Create Webhook link.
Webhooks API
List messages
HTTP request
/webhooks/v1/messages
Query parameters
Parameter | Type | Required | Description |
---|---|---|---|
eventTypeId | int | true | Filter all messages with the specified eventTypeId . |
before | datetime | false | Retrieve all messages before the specified date. |
responseStatus | int | false | 1 for success, 2 for fail. Omit for all statuses |
Response
[
{
"messageId": "uuid",
"eventTypeId": "int",
"created ": "datetime",
"responseStatus": "int",
"statusCode": "int?",
"delivered": "datetime?",
"nextRetry": "datetime?",
"url": "string"
}
]
Get message details by ID
HTTP request
/webhooks/v1/messages/{messageId}
URI parameters
Parameter | Type | Description |
---|---|---|
messageId | uuid | The ID of the message to retrieve details. |
Response
{
"messageId": "uuid",
"eventTypeId": "int",
"created ": "datetime",
"responseStatus": "int",
"statusCode": "int?",
"delivered": "datetime?",
"nextRetry": "datetime?",
"url": "string",
"string": "payload",
"deliveries": [
{
"deliveryId ": "uuid",
"created ": "datetime",
"responseStatus": "int",
"statusCode": "int?",
"delivered": "datetime?"
}
]
}
Attempt to redeliver a message
HTTP request
/webhooks/v1/messages/{messageId}:redeliver
URI parameters
Parameter | Type | Description |
---|---|---|
messageId | uuid | The ID of the message to redeliver. |
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 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:
- 51.138.37.238
- 20.54.89.16
- 13.80.70.181
- 13.80.71.223
- 13.79.28.70
Demo:
- 40.74.20.78
- 94.70.170.65
- 94.70.174.36
- 94.70.255.73
- 94.70.248.18
- 83.235.24.226
Detailed usage of webhooks is demonstrated in the code samples within our public GitHub pages.