Account API (beta)

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.


Authentication

The methods described use IdentityServer (OAuth2) authentication.


Demo environment

Base URL: https://uat-api.vivapayments.com/


API methods

The methods described below belong to the Viva Wallet Account API.

Our Account API is currently in beta and available for test purposes only.

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://uat-api.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://uat-api.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://uat-api.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 method 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://uat-api.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://uat-api.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 method 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://uat-api.vivapayments.com";

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

Balance transfer

Enables you to transfer money from any of your wallets to a client or merchant target wallet.

Request information

post    /api/wallets/{WalletId}/balancetransfer?TargetPersonId={TargetPersonId}

or

post    /api/wallets/{WalletId}/balancetransfer/{TargetWalletId}

ParameterDescriptionTypeImportance
walletIdThe WalletId the money originate fromLongRequired
targetPersonIdThe PersonId the money are targeted toGuidRequired
targetWalletId(Optionally instead of TargetPersonId) The WalletId the money are targeted toLongRequired
amountThe amount, in cents, to be transferredLongYes
descriptionA string denoting the reason of transfer. Appears on target person's wallet statementStringOptional
Sample response
{
  "DebitTransactionId": "eee0beff-7cd7-4b10-afae-e423712d52cb",
  "CreditTransactionId": "5f6da41c-5334-462c-877f-96d79a9b8d1e"
}

A valid BalanceTransfer API call will result in http status code 200, along with two TransactionIds, as shown above. Preliminary checks are carried out to ensure that both wallets are valid and active and that the source wallet has sufficient balance to perform the operation.

DebitTransactionId is the transaction that unloads your wallet. CreditTransactionId is the transaction that loads the target person’s wallet.