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:

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:

TransactionEventData has the following documented properties:

Further details

Create transaction event

This is the same as the event type Transaction Payment Created in the Viva Wallet banking app:

Transaction Payment Created webhook

To access this feature:

  1. Log in to Viva Wallet banking app.
  2. Visit Settings > API Access.
  3. 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:

Transaction Reversal Created webhook

To access this feature:

  1. Log in to Viva Wallet banking app.
  2. Visit Settings > API Access.
  3. 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:

Transaction Price Calculated webhook

To access this feature:

  1. Log in to Viva Wallet banking app.
  2. Visit Settings > API Access.
  3. 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:

Bank Transfer Created webhook

To access this feature:

  1. Log in to Viva Wallet banking app.
  2. Visit Settings > API Access.
  3. 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:

Bank Transfer Executed webhook

To access this feature:

  1. Log in to Viva Wallet banking app.
  2. Visit Settings > API Access.
  3. Click on the Create Webhook link.

Webhooks API

List messages

HTTP request

get    /webhooks/v1/messages

Query parameters

ParameterTypeRequiredDescription
eventTypeIdinttrueFilter all messages with the specified eventTypeId.
beforedatetimefalseRetrieve all messages before the specified date.
responseStatusintfalse1 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

get    /webhooks/v1/messages/{messageId}

URI parameters

ParameterTypeDescription
messageIduuidThe 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

post    /webhooks/v1/messages/{messageId}:redeliver

URI parameters

ParameterTypeDescription
messageIduuidThe 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

get    /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.