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:

• Create transaction
• Cancel / refund transaction
• List messages
• Get message details by ID
• Attempt to redeliver a message

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)
• 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:

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:

List messages

HTTP request

Query parameters

Response

[
    {
        "messageId": "uuid",
        "eventTypeId": "int",
        "created ": "datetime",
        "responseStatus": "int",
        "statusCode": "int?",
        "delivered": "datetime?",
        "nextRetry": "datetime?",
        "url": "string"
    }
]

Get message details by ID

HTTP request

URI parameters

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

URI parameters

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