Account API details

Following is reference information for you to find out more about the Viva Wallet Payment API.

The methods described below use IdentityServer (OAuth2) authentication.

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

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

Roles: 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

POST /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

Sample request

GET /api/Wallets

Response information

Response is an array of Wallets, with the following properties

  • WalletId ( long ): The WalletId assigned to the wallet
  • IsPrimary ( bool ): Indicates whether the wallet is the primary one
  • Amount ( decimal ): The balance of the wallet
  • Available ( decimal ): The available balance of the wallet
  • FriendlyName ( string ): The friendly name assigned
  • CurrencyCode ( int ): The 3 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 Required Default Description
skip int false 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 false 50 The total number of transactions to return in the response, it is applied after skip. Range: [1, 50].

Authorization Roles: 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

Roles: 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

Roles: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}

ParameterDescriptionTypeMandatory
WalletIdThe WalletId the money originate fromLongYes
TargetPersonIdThe PersonId the money are targeted toGuidYes
TargetWalletId(Optionally instead of TargetPersonId) The WalletId the money are targeted toLongYes
AmountThe amount, in cents, to be transferredLongYes
DescriptionA string denoting the reason of transfer. Appears on target person's wallet statementStringNo

Sample request

POST https://demo.vivapayments.com/api/wallets/110357172603/balancetransfer?targetPersonId=792C3376-2C29-4FA2-9952-04202C5CE303
{
   "Amount": 1000,
   "Description": "Description text here"
}

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.