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 two events are available as triggers currently:

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:

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

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:

  • 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.