Account API

Find out more about the Viva Wallet Account API. You can use API testing tools such as Postman or Insomnia to make test API calls. The demo environment has a base URL of https://demo.vivapayments.com/ and for the live environment it’s https://www.vivapayments.com/.


Authentication

The Balance transfer API call, below, uses basic authentication, while the remaining calls use IdentityServer (OAuth 2) authentication.


API calls

The Viva Wallet Account API consists of the following API calls.

Balance transfer

Enables you to transfer money from any of your wallets to the wallet of another merchant. For a successful transfer to take place:

Before you can use this API call you need to enable transfers between accounts in the Viva Wallet banking app:

  1. Log in to Viva Wallet, demo or live , and select the required account.

  2. Go to Settings > API Access.

  3. Select the Allow transfers between accounts checkbox as shown below:

    Allow Transfers

Request information

post    /api/wallets/{walletId}/balancetransfer/{targetWalletId}

ParameterDescriptionTypeImportance
walletIdSource ID of the wallet from which you wish to make the transfer. Displayed as Account ID under Accounts in the Viva Wallet banking app.longRequired
targetWalletIdDestination ID of the wallet to which you wish to make the transfer. Displayed as Account ID under Accounts in the Viva Wallet banking app.longRequired
amountTransfer amount in the smallest denomination of your account currency.longRequired
descriptionSome text to summarize the transfer reason. Appears on target account statement.stringOptional
SaleTransactionIdThe Viva Wallet transaction ID generated during checkout (as a reference only). GUIDOptional
Example
curl -L -X POST 'https://demo.vivapayments.com/api/wallets/91883585/balancetransfer/38995427' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Basic OTZjYjVhMDctNDhjZS00ZDgxLTg3NmQtYTZjM2RmOGRiZDE2OkFEMmUqKA==' \
--data-raw '{
  "amount": "100",
  "description": "Optional text to show on account statement",
  "SaleTransactionId": "Optional text referencing the related sales transaction"
}'

Response information

A valid balance transfer API call will result in HTTP status code 200, along with two transaction IDs.

DebitTransactionId is a unique identifier for the debit taken from the source wallet. CreditTransactionId is a unique identifier for the credit sent to the target wallet.

Example
{
  "DebitTransactionId": "eee0beff-7cd7-4b10-afae-e423712d52cb",
  "CreditTransactionId": "5f6da41c-5334-462c-877f-96d79a9b8d1e"
}

List wallets

Lists all wallets.

HTTP request

get    /walletaccounts/v1/wallets

Authorization

Role: Client merchant reseller.

Response

[
    {
        "iban": "string",
        "walletId": "int",
        "amount": "number",
        "isPrimary": "bool",
        "created": "datetime",
        "swiftCode": "string",
        "available": "number",
        "branchCode": "string",
        "hasIssuedCard": "bool",
        "currencyCode": "string",
        "friendlyName": "string?"
    }
]

Example

let access_token = '';
let host = "https://demo.vivapayments.com";

fetch(`${host}/walletaccounts/v1/wallets`, {
    method: "GET",
    headers: {
        "Authorization": `Bearer ${access_token}`,
        "Content-Type": "application/json; charset=utf-8"
    },
});

Update a wallet

Change the friendly name of a wallet.

HTTP request

patch    /walletaccounts/v1/wallets/{walletId}

URI parameters
Parameter Type Description
walletId long Wallet ID of wallet to update friendly name

Authorization

Role: Merchant.

Request body

Content-Type: application/json

{
    "friendlyName": "string"
}
Example
let access_token = '';
let data = {
    "friendlyName": "New wallet name!"
};
let host = "https://demo.vivapayments.com";

fetch(`${host}/walletaccounts/v1/wallets/687864856050`, {
    method: "PATCH",
    headers: {
        "Authorization": `Bearer ${access_token}`,
        "Content-Type": "application/json; charset=utf-8"
    },
    body: JSON.stringify(data),
});

Create a new wallet

Creates a new wallet with the provided friendly name. The currency selected for the wallet is based on the incorporation country of the merchant account.

HTTP request

get    /walletaccounts/v1/wallets

Authorization

Role: Merchant.

Request body

Content-Type: application/json

{
    "friendlyName": "string"
}

Response

{
    "iban": "string",
    "walletId": "int",
    "amount": "number",
    "isPrimary": "bool",
    "created": "datetime",
    "swiftCode": "string",
    "available": "number",
    "branchCode": "string",
    "hasIssuedCard": "bool",
    "currencyCode": "string",
    "friendlyName": "string?"
}

Example

let access_token = '';
let data = {
    "friendlyName": "Expenses - 2018"
};
let host = "https://demo.vivapayments.com";

fetch(`${host}/walletaccounts/v1/wallets`, {
    method: "POST",
    headers: {
        "Authorization": `Bearer ${access_token}`,
        "Content-Type": "application/json; charset=utf-8"
    },
    body: JSON.stringify(data),
});

Retrieve wallet info

Retrieves merchant wallet information including the available and current balances.

Request information

get    /api/Wallets

Response information

Response is an array of wallets, with the following properties:

parameterTypeDescription
walletIdlongWalletId assigned to the wallet
isPrimaryboolIndicates whether the wallet is the primary one
amountdecimalWallet balance
availabledecimalAvailable balance of wallet
friendlyNamestringFriendly name assigned
currencyCodeint3-digit ISO formatted currency code corresponding to the wallet’s currency

Sample response
[
  {
    "walletId": 285944672607,
    "isPrimary": true,
    "amount": 249590.2,
    "available": 200100.0,
    "friendlyName": "Primary",
    "currencyCode": "978"
  },
  {
    "walletId": 839786772604,
    "isPrimary": false,
    "amount": 153700.5,
    "available": 109180.0,
    "friendlyName": "Misthodosies",
    "currencyCode": "978"
  }
]

Search for transactions

This API call can be used to search transaction that affect the balance of a specified wallet, namely wallet transactions. Wallet transactions can be debit or credit, furthermore these transactions are classified by sub types. Sub types are categorized in groups.

HTTP request

post    /walletaccounts/v1/wallets/{walletId}/transactions:search

URI parameters
Parameter Type Description
walletId long The Id of a wallet that belongs to the authorized user. Transactions returned will be about this wallet

Query parameters

Parameter Type Importance Default Description
skip int Optional 0 The number of transactions to skip from the top of the response. It is applied after calculating the result and sorting it by created date descending. Range: [0, ∞).
limit int Optional 50 The total number of transactions to return in the response. It is applied after skip. Range: [1, 50].

Authorization

Role: Client merchant reseller.

Request body

Content-Type: application/json

{
    "isCredit": "bool?",
    "amountTo": "decimal?",
    "amountFrom": "decimal?",
    "dateTo": "date?",
    "dateFrom": "date?",
    "walletTransactionId": "uuid?",
    "subTypeGroups": [
        "int"
    ]
}

Response

[
    {
        "amount": "decimal",
        "description": "string",
        "currencyCode": "string",
        "walletAmount": "decimal?",
        "created": "date",
        "walletTransactionId": "uuid?",
        "valueDate": "date?",
        "walletAvailableAmount": "decimal?",
        "subTypeId": "int"
    }
]

Example

let access_token = '';
let host = "https://demo.vivapayments.com";

fetch(`${host}/walletaccounts/v1/wallets/687864856050/transactions:search?skip=0&limit=50`, {
    method: "POST",
    headers: {
        "Authorization": `Bearer ${access_token}`,
        "Content-Type": "application/json; charset=utf-8"
    },
});

Retrieve the extrait report

Retrieve the wallet extrait report for a specific month.

HTTP request

get    /walletaccounts/v1/wallets/{walletId}/extrait/{year}/{month}

URI parameters
Parameter Type Description
walletId int The ID of a wallet that belongs to the authorized user
year int The year part of the date for the report
month int The month part of the date for the report

Authorization

Role: Client merchant reseller.

Response

[
    {
        "walletId": "int",
        "currencyCode": "string",
        "personPhone": "string",
        "dateTo": "datetime",
        "dateFrom": "datetime",
        "issueDate": "datetime",
        "personDisplayName": "string",
        "personFullAddress": "string",
        "balanceBroughtForward": "number",
        "balanceCarriedForward": "number",
        "transactions": [
            {
                "amount": "integer",
                "description": "string?",
                "currencyCode": "string",
                "walletAmount": "number",
                "created": "datetime",
                "valueDate": "datetime?"
            }
        ]
    }
]

Example

let access_token = '';
let host = "https://demo.vivapayments.com";

fetch(`${host}/walletaccounts/v1/wallets/481178623650/extrait/2018/07`, {
    method: "GET",
    headers: {
        "Authorization": `Bearer ${access_token}`,
        "Content-Type": "application/json; charset=utf-8"
    },
});

Export transactions

This API call filters the transactions of the wallet provided, based on the criteria entered and outputs the result in excel form (Open XML).

The file type is .xlsx and the content type of the response is application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.

HTTP request

post    /walletaccounts/v1/wallets/{walletId}/transactions:export

URI parameters
Parameter Type Description
walletId long The ID of a wallet that belongs to the authorized user. Transactions exported will be about this wallet

Authorization

Role: Client merchant reseller.

Request body

Content-Type: application/json

{
    "isCredit": "bool?",
    "amountTo": "decimal?",
    "amountFrom": "decimal?",
    "dateTo": "date?",
    "dateFrom": "date?",
    "walletTransactionId": "uuid?",
    "subTypeGroups": [
        "int"
    ]
}

Example

let access_token = '';
let host = "https://demo.vivapayments.com";

fetch(`${host}/walletaccounts/v1/wallets/687864856050/transactions:export`, {
    method: "POST",
    headers: {
        "Authorization": `Bearer ${access_token}`,
        "Content-Type": "application/json; charset=utf-8"
    },
});