Wallet API

Find out more about our Wallet API.

Authentication

The API calls below use basic auth.

Environments

The demo environment has a base URL of https://demo.vivapayments.com/ and for the live environment it’s https://www.vivapayments.com/.

API calls

Our Wallet API consists of the following API calls.

1. Balance transfer

Allows 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

    You need only do this for the source wallet.

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"
}'

Run in Postman

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"
}

Further information

Check out the related tutorials below for examples of this API call in action:

2. Retrieve wallet info

Retrieves merchant wallet information including the available and current balances.

Request information

get    /api/wallets

Example
curl -L -X GET 'https://demo.vivapayments.com/api/wallets' \
-H 'Authorization: Basic e01lcmNoYW50IElEfTp7QVBJIEtleX0='

Run in Postman

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"
  }
]

Further information

Check out the related tutorials below for more details about OAuth 2 authentication and setting webhooks: