Payment API details

Following is reference information for you to find out more about the Viva Wallet Payment API. Alternatively, to view and ‘try out’ the endpoints in Swagger UI format, please visit our Payment API specification page. You can also view the Swagger source file in JSON format.

The majority of methods described below use basic auth on its own. Card tokenization requires a combination of basic auth and IdentityServer (OAuth2) authentication.

You can use API testing tools such as Postman or Insomnia to make test API calls.

Create order

Every payment on the Viva Wallet platform needs an associated payment order. A payment order is represented by a unique numeric orderCode.

Request information

POST /api/orders

Parameters

Amount (int64): The amount requested in cents (amount in euros x 100). E.g. If you want to create a payment for €100.37, you need to pass the value 10037. The amount must always be greater than 30 cents (which is the minimum amount you can charge with Viva Payments).

A number of optional parameters are supported.

Sample request

{
  "Tags": [
    "sample string 1",
    "sample string 2",
    "sample string 3"
  ],
  "Email": "customer@domain.com",
  "Phone": "2117604000",
  "FullName": "Customer Name",
  "PaymentTimeOut": 86400,
  "RequestLang": "en-US",
  "MaxInstallments": 12,
  "AllowRecurring": true,
  "IsPreAuth": true,
  "Amount": 1000,
  "MerchantTrns": "Your reference",
  "CustomerTrns": "Description that the customer sees"
}

Response information

OrderCode (int64): The OrderCode is your unique Payment Order ID. This is now all that is required by Viva in order for the payment to be completed.

ErrorCode (int32): If the call is not successful, an error code is generated. For successful calls the value 0 is returned.

ErrorText (string): If the ErrorCode is not 0, a descriptive error message is returned.

TimeStamp (datetime): The server date and time that the Payment Order creation was completed in ISO 8601 format.

Sample response

{
  "OrderCode": 175936509216,
  "ErrorCode": 0,
  "ErrorText": "",
  "TimeStamp": "2012-12-24T15:23:21.6871106+02:00"
}

Optional parameters

The following optional parameters can be passed and are supported when creating an order via the API.

View table

Retrieve order

To retrieve information about a specific order.

Request information

GET /api/orders/{OrderCode}

Parameters

  • OrderCode ( long ): The 16-digit OrderCode for which you wish to retrieve information

Sample request

GET /api/Orders/3958121726095215

Response information

Properties:

  • OrderCode ( long ): The 16-digit OrderCode for which you requested information
  • SourceCode ( string ): The Sourcecode that is related to this Order
  • Tags ( string[] ): An array containing all related tags
  • RequestLang ( string ): The ISO formatted Request language
  • MerchantTrns ( string ): The related MerchantTrns
  • CustomerTrns ( string ): The related CustomerTrns
  • RequestAmount ( decimal ): The Request Amount of the Order
  • ExpirationDate ( datetime ): The exact date and time the Order expires at
  • StateId ( byte ): The state of the order. Possible values are 0 (Pending), 1 (Expired), 2 (Canceled), 3 (Paid)

Sample response

{
  "OrderCode": 3958121726095215,
  "SourceCode": "Default",
  "Tags": [],
  "RequestLang": "el-GR",
  "MerchantTrns": null,
  "CustomerTrns": null,
  "RequestAmount": 100,
  "ExpirationDate": "2015-07-08T00:13:03.243",
  "StateId": 3
}

Cancel order

Cancelling a standing payment order is pretty straightforward. You will need your MerchantId, Password and a valid 16-digit payment order code.

If the order has been cancelled, a customer with a valid payment order code can still make a payment using the DIAS channels (e-banking, ATM, Bank branch).

Request information

DELETE /api/orders/{OrderCode}

Parameters

  • OrderCode ( long ): A valid 16-digit payment order code.

Sample request

DELETE /api/orders/1759365092162578

Response information

Sample response

{
  "OrderCode": 1759365092162578,
  "ErrorCode": 0,
  "ErrorText": "Error Message",
  "TimeStamp": "2012-12-24T15:22:23.085251+02:00"
}

Update order

Enables you to update certain information relating to a standing payment order.

Request information

PATCH /api/orders/{OrderCode}

OrderCode ( int64 ): A valid 16-digit Payment Order code.

Parameters

At least one of the following parameters should be present in the request body:

  • Amount ( int64 ): The new amount of the Order in cents
  • IsCanceled ( bool ): Changes the canceled state of the Order
  • DisablePaidState ( bool ): Allows the Order to accept multiple payments (true) or not (false)
  • ExpirationDate ( date ): Alters the Expiration Date of the Order

Sample request

PATCH /api/orders/1759365092166384

{
    "Amount": 3900,
    "IsCanceled": 0,
    "ExpirationDate": "2017-12-01 03:00:00+2:00"
}

Response information

A valid request will result in an empty response with http status code 200. All required validation checks are carried out and reflected in the status code of the response (e.g. status code 404 for non-existent OrderCode).

Retrieve transactions

Enables you to obtain:

  • Details for all transactions for a given payment order.
  • A list of all transactions that occurred on a given day.
  • A list of all transactions for a given Source Code for a specific day.

Request information

GET /api/transactions/{id}

Parameters

  • id ( guid ): The id of a specific transaction
  • date ( date ): A given day for which all transactions will be returned
  • clearancedate ( date ): If we want to get all transactions that were cleared on a specific date
  • ordercode ( int64 ): A valid 1216 digit Payment Order code
  • sourcecode ( string ): The Source Code for which the transaction has been setup

Note 1: The {id} segment is optional.
Note 2: SourceCode is case-sensitive.
Note 3: SourceCode needs also the date or the ordercode parameter.

Sample requests GET /api/transactions/b1a3067c-321b-4ec6-bc9d-1778aef2a19d

GET /api/transactions/?ordercode=175936509216

GET /api/transactions/?date=2018-08-27

GET /api/transactions/?clearancedate=2018-08-27

GET /api/transactions/?sourcecode=Default&date=2018-08-27

Response information

  • ErrorCode: If the call is not successful, an error code is generated. For successful calls the value 0 is returned.
  • ErrorText: If the ErrorCode is not 0, a descriptive error message is returned.
  • TimeStamp: The server date and time that the response to this method call was created in ISO 8601 format.

Sample response

{
  "Transactions": [
    {
      "TransactionId": "b1a3067c-321b-4ec6-bc9d-1778aef2a19d",
      "MerchantId": "21192b18-78cc-4643-b8ae-e796318dbb38",
      "ResellerId": null,
      "StatusId": "F",
      "ParentId": "ce5de8be-bed6-494c-8988-f07841221ba8",
      "Fee": 1.0,
      "Amount": 10.0,
      "Commission": 2.0,
      "MerchantTrns": "Your Ref",
      "CustomerTrns": "Description that the customer sees",
      "CreatedBy": "username",
      "SourceCode": "default",
      "ResellerSourceCode": null,
      "ClearanceDate": "2012-12-24T15:21:44.3243753+02:00",
      "InsDate": "2012-12-24T15:21:44.3243753+02:00",
      "Order": {
        "OrderCode": 175936509216,
        "ChannelId": "93b1a083-2594-4383-a0e2-7d391b746237",
        "ResellerId": null,
        "SourceCode": "default",
        "ResellerSourceCode": null,
        "RequestLang": "en-US",
        "Tags": [
          "sample string 1",
          "sample string 2",
          "sample string 3"
        ]
      },
      "Payment": {
        "ChannelId": "cdbc3eb0-7f51-49dc-b447-a6e38b68a438",
        "RecurringSupport": true,
        "Installments": 4,
        "Email": "customer@domain.com",
        "Phone": "2131234567"
        "FullName": "Customer Name",
      },
      "CreditCard": {
        "CardHolderName": "Cardholder Name",
        "Number": "123456XXXXXX1234",
        "Token": "sample string 3",
        "CountryCode" : "GR",
        "CardIssuingBank" : "EFG EUROBANK",
        "CardType": {
          "CardTypeId": 1,
          "Name": "VISA"
        }
      },
      "TransactionType": {
        "TransactionTypeId": 1,
        "Name": "Charge"
      }
    }
  ],
  "ErrorCode": 0,
  "ErrorText": "Error",
  "TimeStamp": "2012-12-24T15:21:44.3263755+02:00"
}

View full details of the transaction statuses and types that can be returned in the response.

Create recurring transaction

This API call allows you to make a new payment by either committing an already authorized transaction or by making a recurring payment. The latter is only permitted if the following two conditions are met:

  • The cardholder has already been charged successfully in the past
  • The cardholder has agreed on allowing recurring payments on their card

Request information

POST /api/transactions/{TransactionId}

Parameters

Amount ( int64 ): The amount requested in cents (amount in euros x 100). For capturing authorized transactions, it should not exceed the amount entered in the original PreAuth. Note: If you want to create a payment for 100,37 €, you need to pass the value 10037

Installments ( int32 ): This Optional parameter defines the number of installments for the payment. Note: Acceptable values 1 to 36

Sample request

POST /api/transactions/252b950e-27f2-4300-ada1-4dedd7c17904

This is the ID of the original payment. You should use the same ID for every subsequent recurring transaction.

{
  "Installments": 0,
  "Amount": 500,
  "MerchantTrns": "Your Reference",
  "CustomerTrns": "Description for the customer receipt",
  "ActionUser": "user that initiated the call"
}

Response information

Method Output: TransactionResult object with the following documented attributes:

TimeStamp ( datetime ): The server date and time that the Payment Order creation was completed in ISO 8601 format.

TransactionId ( uuid ): The unique id for the new transaction.

StatusId ( string ): The current status of this transaction. It can have one of the following values:

StatusIdDescription
EThe transaction was not completed because of an error
AThe transaction is in progress
MThe cardholder has disputed the transaction with the issuing Bank
UA disputed transaction has been refunded
XThe transaction was cancelled by the merchant
RThe transaction has been fully or partially refunded
FThe transaction has been completed successfully

ErrorCode ( int32 ): If the call is not successful, an error code is generated. For successful calls the value 0 is returned.

ErrorText ( string ): If the ErrorCode is not 0, a descriptive error message is returned.

Sample response

{
  "TransactionId": "bd5390a9-5870-4d8d-abea-7f5a94f9cecc",
  "StatusId": "F",
  "ErrorCode": 0,
  "ErrorText": "Error Message",
  "TimeStamp": "2012-12-24T15:23:38.5157933+02:00"
}

Cancel transaction

This method allows you to:

  • Cancel a card payment occurred within the same business day (till 22:00 GMT+2).
  • Make a partial or full refund of a successful payment that has already been cleared.

To avoid an error, ensure you have enabled refunds in your Viva Wallet Account.

Request information

DELETE /api/transactions/{TransactionId}

Parameters

  • Amount ( int64 ): The amount that will be refunded in cents (amount in euros x 100). It should not exceed the of the original payment. Note: If you want to create a payment for 100,37 €, you need to pass the value 10037

  • ActionUser ( string ): The username that initiated this action, used optionally for your own logging purposes.

Sample request

DELETE /api/transactions/101f4704-8464-42cc-ba9a-5399d142b9b8?amount=100

Response information

  • TimeStamp ( datetime ): The server date and time that the Payment Order creation was completed in ISO 8601 format.

  • TransactionId ( uuid ): The unique id for the new transaction.

  • StatusId ( string ): The current status of this transaction. It can have one of the following values:

StatusIdDescription
EThe transaction was not completed because of an error
AThe transaction is in progress
MThe cardholder has disputed the transaction with the issuing Bank
UA disputed transaction has been refunded
XThe transaction was cancelled by the merchant
RThe transaction has been fully or partially refunded
FThe transaction has been completed successfully
  • ErrorCode ( int32 ): If the call is not successful, an error code is generated. For successful calls the value 0 is returned.

  • ErrorText ( string ): If the ErrorCode is not 0, a descriptive error message is returned.

Sample response

{
  "TransactionId": "101f4704-8464-42cc-ba9a-5399d142b9b8",
  "StatusId": "F",
  "ErrorCode": 0,
  "ErrorText": "",
  "TimeStamp": "2012-12-24T16:29:00.2339259+02:00"
}

Installments check

Enables you to obtain information on the maximum number of installments a card bin supports.

Request information

GET /api/cards/installments

Parameters

  • Authorization. Passed via header. The basic authentication header consisting of your MerchantId and API Key.
  • CardNumber. Passed via header. The card number you want to check (minimum 6 digits or an error 400 is returned).

You don’t need to provide the full number of the card. Installments support are always bin based, so the first 6 to 8 digits of the card are enough.

Response information

A successful Installments Check call results in a response status 200 along with an object of the following type

{
	int MaxInstallments;
}

Sample response

{
	"MaxInstallments": 36
}

Add source

Payment Sources allow you to group your sales into meaningful groups. They can be managed through the web self-care environment by logging in with your merchant profile then navigating to Sales > Websites / Apps.

To add a source through the API you use the AddSource method.

Request information

POST /api/sources

Parameters

  • Name ( string ): A meaningful name that will help you identify the source in Web Self Care environment
  • SourceCode ( string ): A unique code that is exchanged between your application and the API
  • Domain ( string ): The primary domain of your site. You should NOT enter protocol information (http/https) or paths. For example www.domain.com is a valid value for this property. http://www.domain.gr or www.domain.com/site are not.
  • IsSecure ( boolean ): A value of true indicates that your site’s protocol is https.
  • PathFail ( string ): The relative path url your client will end up to, after a failed transaction
  • PathSuccess ( string ): The relative path url your client will end up to, after a successful transaction

Response information

Response http status, as usual, indicates the successful source creation or not (status 200 = OK).

Approval rules hold for this API call too. A source with a new domain will require approval (1-2 days). Any source that uses a domain already approved will be automatically approved.

Sample request

{
   "Name": "Site 1",
   "Domain": "www.domain.com",
   "IsSecure": true,
   "PathFail": "site/failure.aspx",
   "PathSuccess": "site/success.aspx",
   "SourceCode": "site1"
}

The above call will result in a a source with the following success/failure URLs:

  • https://www.domain.com/site/failure.aspx
  • https://www.domain.com/site/success.aspx

Original Credit Transaction

The Original Credit Transaction (OCT) API call enables you to directly pay an amount to a card. It is essentially a refund transaction which allows you to return money to the card irrespective of the original payment amount.

You need to specifically be granted access to this API call. Please request permission by raising an issue via our public GitHub account.

Request information

DELETE /api/transactions/{TransactionsId}?Amount={amount}&ServiceId=6

ParameterDescriptionTypeMandatory
TransactionIdThe TransactionId of the original payment transaction (type 5 or 6)GuidYes
AmountThe amount, in cents, to be returnedLongYes
ServiceIdYou need to pass the value 6 in order to perform an OCTByteYes
MerchantTrnsAn ID or a short description that helps you uniquely identify the transaction. For example, this can be your customer order reference numberStringNo
CustomerTrnsA friendly description that you want to display to the cardholder. This description appears on the receipt the cardholder receivesStringNo

Please refer also to Cancel transaction method call of the public API.

Sample request

DELETE https://demo.vivapayments.com/api/transactions/8b303338-2ab5-4b71-a077-3c0139cd6a8b?amount=150&ServiceId=6

Sample response

{
  "Amount": -1.5,
  "StatusId": "F",
  "TransactionId": "45b02deb-dbe6-487d-8882-1da4122ed466",
  "RemainingRefunds": null,
  "AuthorizationId": "612132",
  "ErrorCode": 0,
  "ErrorText": null,
  "TimeStamp": "2015-06-18T12:39:00.1139811+03:00"
}

A valid OCT API call will result in http status code 200 along with an object as shown above. All preliminary checks are carried out to ensure the Merchant has the rights and sufficient balance to perform the operation.

Card tokenization

Viva Wallet uses tokenization to collect sensitive card details directly from your customers in a secure manner. A token representing this information is returned to your server to use. This ensures that no sensitive card data touches your server, and allows your integration to operate in a PCI-compliant way.

Make sure you read about the Create recurring transaction API. Using a previous transaction is, in most cases, superior to saving a card due to the extra work involved.

Some calls involved in the above flows use IdentityServer (OAuth2) authentication, whereas others use basic authentication. For the former, when experimenting with card tokenization in the sandbox environment, use the following (demo) client credentials:

  • Client ID: generic_acquiring_client.apps.vivapayments.com
  • Client Secret: generic_acquiring_client

Now request an access token, accept and store the access token, then follow the steps below.

Step 1 – Get charge token using card details

You need to perform this call from the customer’s browser, in order to limit your PCI scope and avoid sensitive data passing through your servers.

Environment Endpoint
Demo https://demo-api.vivapayments.com/acquiring/v1/cards/chargetokens
Production https://api.vivapayments.com/acquiring/v1/cards/chargetokens
POST https://demo-api.vivapayments.com/acquiring/v1/cards/chargetokens

Request

{
  "cvc": "111",
  "expirationMonth": 1,
  "expirationYear": 2018,
  "holderName": "Card Holder",
  "number": "4111111111111111"
}

Response

{
  "chargeToken": "ctok_Zxng0anBhUGMRang_xrfUw2"
}
Property Description
chargeToken This is a random, unique string that can be used in place of card in order to initiate a transaction. It has a short expiration period and once it is used it is disposed. Disposed tokens are not reused.
HTTP Status Message Explanation
200 (OK) Successfully create a token that can be used to initiate a transaction
400 (Bad Request) Null or whitespace Cvc Null or whitespace Cvc
400 (Bad Request) Invalid length for Cvc Must be 3 or 4 characters
400 (Bad Request) Invalid ExpirationMonth Month [1 - 12]
400 (Bad Request) Invalid ExpirationYear Year [1 - 9999]
400 (Bad Request) Invalid card Expiration Date Past date
400 (Bad Request) Invalid CardNumber The card cardNumber field is not a valid card number or it is not supported

Step 2 – Get card token using the charge token

You should save the card token for future usage.

GET https://demo-api.vivapayments.com/acquiring/v1/cards/tokens?chargeToken={chargeToken}

Response

{
     "token": "05FB1A1EBF41440FDF88A359C46645B6D1EE3EF5"
}
Property Description
token This is a random, unique string that represents a card’s details. It is unique per card and can be traded for a chargeToken.

Step 3 – Get charge token using card token

GET https://demo-api.vivapayments.com/acquiring/v1/cards/chargetokens?token={cardtoken}

Response

{
  "chargeToken": "ctok_Zxng0anBhUGMRang_xrfUw2"
}

Step 4 – Create an order

See Create order for more information.

Step 5 – Execute the payment

You should have by now an OrderCode and a Charge Token for the your customer’s card. To complete the payment, call Viva Payments’ API to execute the transaction.

POST https://demo.vivapayments.com/api/transactions

Request

{
  "OrderCode" : OrderCode,
  "SourceCode": 'Default',
  "CreditCard" : {
     "Token": 'Token'
  }
}

Response

A successful Payment Execution call results in a response 200 along with an object of the following type

{
    string StatusId;
    Guid TransactionId;
    int RemainingRefunds;
    int ErrorCode;
    string ErrorText;
    DateTime TimeStamp;
}

If the call is not successful, you will receive a different status response (e.g. 400, 403) along with a full description of the error as a ReasonPhrase.

Response status 200 indicates only a successful call to Viva Wallet API. To check the actual outcome of the transaction (whether the customer’s card was charged or not) you need to check property ErrorCode.

Migrating your recurring payments

You can migrate your recurring payments implementation to Card Tokenization. Use our Retrieve transactions API endpoint to retrieve card tokens, which you can trade for charge tokens, and follow the above flows.

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.