Account API

Find out more about the Viva Wallet Account API.

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 API calls below use basic auth.


API calls

Our Account API consists of the following 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

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

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),
});

Transferring money to a bank account

Use this API to transfer money from a wallet to a stored bank account. A typical transfer money flow consists of the following steps:

  1. Create a bank account or retrieve a stored one
  2. Retrieve the instructionTypes available to this account and display it to the user.
  3. Create a Fee Command with the instruction type selected by the user
  4. Request an otp code for the user
  5. Submit the bank transfer request with bankCommandId (fee command Id received from step 3) and Otpcode included.

Upon successful completion a commandId will be returned and can be used to track command’s progress (executed, cancelled etc.).

Note, that if the bank account stored is handled by Viva Wallet (meaning that it is essentially a wallet) then, a Wallet transfer will be created instead, transferring funds instantly to the receiver’s wallet. In that case, commandId will be null and a walletTransactionId will be provided instead. Bank accounts belonging to Viva Wallet are marked by the isVivaIban property. In addition to that, calls to retrieving the list of available instruction types must be omitted for all Viva Wallet accounts, as they will fail.

Roles allowed

Client Merchant MerchantChild (with role ManageAccount)

Bank accounts (beneficiaries)

Create bank account

HTTP Request

post    /transfers/v1/bankaccounts

Request body

Content-Type: application/json

{
    "beneficiaryName": "string",
    "iban": "string",
    "friendlyName": "string?"
}

Response

{
    "bankAccountId": "uuid",
    "iban": "string",
    "swiftCode": "string",
    "friendlyName": "string?",
    "beneficiaryName": "string",
    "bankId": "string",
    "isArchived": "bool",
    "isVivaIban": "bool"
}

Example

let access_token = '';
let data = {
    "beneficiaryName": "John Smith",
    "iban": "GR4601428763563796446211493"
};
let host = "https://uat-api.vivapayments.com";

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

Update bank account

Summary

Update a bank account’s details or mark it as archived(delete).

HTTP Request

patch    /transfers/v1/bankaccounts/{bankAccountId}

URI Parameters

Parameter Type Description
bankAccountId uuid The id of bank account

Request body

Content-Type: application/json

{
    "friendlyName": "string?",
    "beneficiaryName": "string?",
    "archive": "bool?"
}

Response

{
    "bankAccountId": "uuid",
    "iban": "string",
    "swiftCode": "string",
    "friendlyName": "string?",
    "beneficiaryName": "string",
    "bankId": "string",
    "isArchived": "bool",
    "isVivaIban": "bool"
}

Example

let access_token = '';
let data = {
    "beneficiaryName": "John Smith"
};
let host = "https://uat-api.vivapayments.com";

fetch(`${host}/transfers/v1/bankaccounts/f58eca83-8875-465e-a992-bba176154331`, {
    method: "PATCH",         
    headers: {
        "Authorization": `Bearer ${access_token}`,
        "Content-Type": "application/json; charset=utf-8"
    },
    body: JSON.stringify(data),
});

Retrieve bank accounts

HTTP Request

get    /transfers/v1/bankaccounts

Query Parameters

Parameter Type Required Default Description
skip number false 0 Skip number of bank accounts
limit number false 20 Number of rows to fetch
iban string false The iban of the bank account
beneficiaryName string false The beneficiary name of the bank account

Response

[
    {
        "bankAccountId": "uuid",
        "iban": "string",
        "swiftCode": "string",
        "friendlyName": "string?",
        "beneficiaryName": "string",
        "bankId": "string",
        "isArchived": "bool",
        "isVivaIban": "bool"
    }
]

Example

let access_token = '';
let host = "https://uat-api.vivapayments.com";

fetch(`${host}/transfers/v1/bankaccounts?skip=0&limit=10`, {
    method: "GET",         
    headers: {
        "Authorization": `Bearer ${access_token}`,
        "Content-Type": "application/json; charset=utf-8"
    },
});

Retrieve bank account by Id

HTTP Request

get    /transfers/v1/bankaccounts/{bankAccountId}

URI Parameters

Parameter Type Description
bankAccountId uuid The id of bank account

Response

{
    "bankAccountId": "uuid",
    "iban": "string",
    "swiftCode": "string",
    "friendlyName": "string?",
    "beneficiaryName": "string",
    "bankId": "string",
    "isArchived": "bool",
    "isVivaIban": "bool"
}

Example

let access_token = '';
let host = "https://uat-api.vivapayments.com";

fetch(`${host}/transfers/v1/bankaccounts/f58eca83-8875-465e-a992-bba176154331`, {
    method: "GET",         
    headers: {
        "Authorization": `Bearer ${access_token}`,
        "Content-Type": "application/json; charset=utf-8"
    },
});

Retrieve available bank transfer instruction types

Summary

Information about instruction types.

HTTP Request

get    /transfers/v2/bankaccounts/{bankAccountId}/instructiontypes

URI Parameters

Parameter Type Description
bankAccountId uuid The id of bank account

Query Parameters

Parameter Type Required Default Description
amount long true The amount of the transfer

Response

{
    "supportsInstant": true,
    "instructionTypes": [
        1,
        2
    ]
}

Example

let access_token = '';
let host = "https://uat-api.vivapayments.com";

fetch(`${host}/transfers/v2/bankaccounts/f58eca83-8875-465e-a992-bba176154331/instructiontypes`, {
    method: "GET",         
    headers: {
        "Authorization": `Bearer ${access_token}`,
        "Content-Type": "application/json; charset=utf-8"
    },
});

Create a bank transfer fee command

HTTP Request

post    /transfers/v1/bankaccounts/{bankAccountId}/fees

URI Parameters

Parameter Type Description
bankAccountId uuid The id of bank account

Request body

Content-Type: application/json

{
    "amount": "long",
    "walletId": "long",
    "isInstant": "bool",
    "instructionType": "int"
}

Response

{
    "fee": "decimal",
    "isInstant": "bool",
    "bankCommandId": "uuid",
    "instructionType": "int"
}

Example

let access_token = '';
let data = {
    "amount": 1022,
    "isInstant": true,
    "instructionType": 1,
    "walletId": 166374269593
};
let host = "https://uat-api.vivapayments.com";

fetch(`${host}/transfers/v1/bankaccounts/f58eca83-8875-465e-a992-bba176154331/fees`, {
    method: "POST",         
    headers: {
        "Authorization": `Bearer ${access_token}`,
        "Content-Type": "application/json; charset=utf-8"
    },
    body: JSON.stringify(data),
});

Send money to a bank account

HTTP Request

post    /transfers/v1/bankaccounts/{bankAccountId}:send

URI Parameters

Parameter Type Description
bankAccountId uuid The id of bank account

Request body

Content-Type: application/json

{
    "amount": "long",
    "walletId": "long",
    "description": "string",
    "bankCommandId": "uuid",
    "oneTimePassword": "string"
}

Response

{
    "walletTransactionId": "uuid?",
    "commandId": "uuid?"
}

Example

let access_token = '';
let data = {
    "amount": 1022,
    "walletId": 166374269593,
    "description": "Bank transfer",
    "oneTimePassword": "111111",
    "bankCommandId": "AFBB004E-6A15-4C6A-BA04-F1B48394183A"
};
let host = "https://uat-api.vivapayments.com";

fetch(`${host}/transfers/v1/bankaccounts/f58eca83-8875-465e-a992-bba176154331:send`, {
    method: "POST",         
    headers: {
        "Authorization": `Bearer ${access_token}`,
        "Content-Type": "application/json; charset=utf-8"
    },
    body: JSON.stringify(data),
});

Wallet to Wallet transfers

Retrieve personal account details

Summary

Use this method retrieve information about a Personal account. The properties firstName and lastName might be empty, depending on the security preferences of the user

HTTP Request

get    /transfers/v1/persons/clients

Query Parameters

Parameter Type Required Default Description
mobile string true The user’s mobile with or without the country’s mobile prefix code
countryCode string true The country of the location of the user

Authorization

Roles: Client Merchant

Response

{
    "walletId": "long",
    "lastName": "string?",
    "firstName": "string?"
}

Example

let access_token = '';
let host = "https://uat-api.vivapayments.com";

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

Transfer funds from wallet to wallet

Summary

Use this method to transfer funds from a wallet that belongs to the authenticated user to

HTTP Request

post    /transfers/v1/wallets/{sourceWalletId}:send

Events

Event Id Description
SecurityValidateOtpInvalid 3717 Indicates that the supplied oneTimePassword code does not match or has expired.
SecurityValidateOtpThresholdReached 3718 Indicates that the maximum attempts to validate OTP have been reached.

URI Parameters

Parameter Type Description
sourceWalletId uuid The id of the wallet to be charged

Authorization

Roles: Client Merchant

Request body

Content-Type: application/json

{
    "amount": "long",
    "description": "string",
    "targetWalletId": "long",
    "oneTimePassword": "string"
}

Response

{
    "DebitWalletTransactionId": "uuid",
    "CreditWalletTransactionId": "uuid"
}

Example

let access_token = '';
let data = {
    "amount": 1022,
    "oneTimePassword": "111111",
    "targetWalletId": 166374269593,
    "description": "Lunch break"
};
let host = "https://uat-api.vivapayments.com";

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

Account Transactions API

The Account Transactions API provides all the necessary tools in order to search for Account Transactions of Personal or Merchant Accounts.

Search for account transactions

Searches for account transactions of a specific Person

post    /dataservices/v1/accounttransactions/Search?PageSize={PageSize}&Page={Page}&OrderBy={Ascending/Descending}

URI Parameters

Name Type Required Description
Pagesize int required Number of results to return (max 500)
Page int required Page to return (based on Pagesize)
OrderBy string required Sort order of the result (on field Created). Allowed values Ascending/Descending

Headers

Name Type Required Description
Authorization Bearer token required The required access/identity token need to access the resource. Scope urn:viva:payments:biservices:publicapi is required for identity tokens (or urn:viva:payments:biservices:internalapi for access tokens)
PersonId UniqueIdentifier required for access tokens only Indicates the personId whose transactions will be returned

Request Body

Content-Type: application/json

Name Type Required Description
DateFrom DateTimeOffset optional DateRange Start
DateTo DateTimeOffset optional DateRange End
WalletId Long optional Specific person wallets
TypeIds byte[] optional Specific types only
SubTypeIds byte[] optional Specific subtypes only
ExcludedSubTypeIds byte[] optional Exclude these subtypes
IsExpired bool optional Includes or excludes expired transactions (eg Expired reserves)
AmountFrom decimal optional Minimum amount
AmountTo decimal optional Maximum amount

NOTE: AmountFrom/AmountTo are signed decimals (transactions which reduce balance have negative value)

Response Body

Content-Type: application/json

Name Type Required Description
currentPage Int required Current page of results
pageSize Int required Number of results per page
totalPages Int required Total Number of Pages
totalDataCount Int required Total Number of Results
data AccountTransaction required An array of AccountTransaction with the results
links Link required Related links for api navigation

Sample

post    /dataservices/v1/accounttransactions/Search?PageSize=3&Page=2&OrderBy=Descending
{
    "DateFrom": "2018-01-20 13:45:03.5200000 +02:00",
    "DateTo": "2019-04-27 13:45:03.5200000 +02:00",
    "WalletId": 932498539354,
    "SubTypeIds": [ 22, 25, 30 ],
    "AmountFrom": 0.00,
    "AmountTo": 2000.00
}
Response
{
    "currentPage": 2,
    "pageSize": 3,
    "totalPages": 4,
    "totalDataCount": 10,
    "data": [
        {
            "accountTransactionId": "8d8d268e-0de9-456c-ae57-efb80dc2e8df",
            "created": "2019-03-26T15:06:17.7333333+00:00",
            "personId": "2e325715-4fef-47fc-b235-66e6ee45c859",
            "walletId": 932498539354,
            "typeId": 20,
            "subTypeId": 30,
            "amount": -1,
            "currencyCode": 978,
            "isAuthorization": false,
            "targetAmount": 0,
            "targetAvailable": 0,
            "valueDate": null,
            "counterPart": "GR2201402670267002340002249"
        },
        {
            "accountTransactionId": "cab5653d-ab6c-4385-8342-f2d7f610289c",
            "created": "2019-03-26T15:06:17.5466667+00:00",
            "personId": "2e325715-4fef-47fc-b235-66e6ee45c859",
            "walletId": 932498539354,
            "typeId": 20,
            "subTypeId": 30,
            "amount": -1,
            "currencyCode": 978,
            "isAuthorization": false,
            "targetAmount": 0,
            "targetAvailable": 0,
            "valueDate": null,
            "counterPart": "GR2201402670267002340002249"
        },
        {
            "accountTransactionId": "12c88aea-8a16-4a1b-94ce-bb620d9581cc",
            "created": "2019-03-26T15:06:16.21+00:00",
            "personId": "2e325715-4fef-47fc-b235-66e6ee45c859",
            "walletId": 932498539354,
            "typeId": 20,
            "subTypeId": 30,
            "amount": -2,
            "currencyCode": 978,
            "isAuthorization": false,
            "targetAmount": 0,
            "targetAvailable": 0,
            "valueDate": null,
            "counterPart": "GR2201402670267002340002249"
        }
    ],
    "links": {
        "self": "/api/AccountTransaction/Search?PageSize=3&Page=2&OrderBy=Descending",
        "next": "/api/AccountTransaction/Search?PageSize=3&Page=3&OrderBy=Descending",
        "previous": "/api/AccountTransaction/Search?PageSize=3&Page=1&OrderBy=Descending"
    }
}

Retrieve account transaction details

Retrieves details for a specific Account Transaction

get    /dataservices/v1/accounttransactions/{AccountTransactionId}

URI Parameters

Name Type Required Description
AccountTransactionId UniqueIdentifier required The id of the transaction to retrieve

Headers

Name Type Required Description
Authorization Bearer token required The required access/identity token need to access the resource. Scope urn:viva:payments:biservices:publicapi is required for identity tokens (or urn:viva:payments:biservices:internalapi for access tokens)
PersonId UniqueIdentifier required for access tokens only Indicates the personId whose transactions will be returned

Response Body

Content-Type: application/json

Name Type Required Description
data AccountTransactionDetail required The account transaction requested

Sample

get    /dataservices/v1/accounttransactions/91c94191-c4eb-44a6-a3f8-b07b7937921d
Response
"data":
        "details": {
            "cardNumber": null,
            "iban": null,
            "orderCode": 1824111174272603,
            "resellerName": "VIVA ΗΛΕΚΤΡΟΝΙΚΕΣ ΥΠΗΡΕΣΙΕΣ",
            "counterPartCompanyTitle": null,
            "counterPartCompanyName": null,
            "counterPartFirstName": null,
            "counterPartLastName": null
        },
        "accountTransactionId": "91c94191-c4eb-44a6-a3f8-b07b7937921d",
        "created": "2019-03-01T10:39:21.7033333+00:00",
        "personId": "04a61c54-f26b-4026-b781-26f4684bbfec",
        "walletId": 991883512826,
        "typeId": 20,
        "subTypeId": 20,
        "amount": 100,
        "currencyCode": 978,
        "isAuthorization": false,
        "targetAmount": 0,
        "targetAvailable": 0,
        "valueDate": null,
        "counterPart": "VIVA ΗΛΕΚΤΡΟΝΙΚΕΣ ΥΠΗΡΕΣΙΕΣ"
}

Reference

AccountTransaction

Name Type Required Description
AccountTransactionId UniqueIdentifier required id of the transaction
Created DateTimeOffset required timestamp of the transaction
WalletId long required wallet code of the transaction
TypeId byte required Type of the transaction (20: ChangeBalance, 32: ChangeAvailable, 21: ChangeOverdraft)
SubTypeId byte required SubType of the transaction
Amount decimal required Amount of the transaction (signed)
CurrencyCode short required ISO Currency Code of the transaction
IsAuthorization bit optional Indicates if a type 32 transaction is an authorisation or not
TargetAmount decimal required Wallet Amount after the execution of this transaction
TargetAvailable decimal required Wallet Available Amount after the execution of this transaction
ValueDate date optional Value Date of the transaction
CounterPart string optional A string representing the other part of the transaction (eg the recipient IBAN of a payout)
Name Type Required Description
Self string required Current action url
Previous string optional Url of the previous page’s results (null for page 1)
Next string optional Url of the next page’s results (null for last page)

AccountTransactionDetail

Name Type Required Description
Detail Dictionary optional Details of the specific transaction
AccountTransactionId UniqueIdentifier required id of the transaction
Created DateTimeOffset required timestamp of the transaction
WalletId long required wallet code of the transaction
TypeId byte required Type of the transaction (20: ChangeBalance, 32: ChangeAvailable, 21: ChangeOverdraft)
SubTypeId byte required SubType of the transaction
Amount decimal required Amount of the transaction (signed)
CurrencyCode short required ISO Currency Code of the transaction
IsAuthorization bit optional Indicates if a type 32 transaction is an authorisation or not
TargetAmount decimal required Wallet Amount after the execution of this transaction
TargetAvailable decimal required Wallet Available Amount after the execution of this transaction
ValueDate date optional Value Date of the transaction
CounterPart string optional A string representing the other part of the transaction (eg the recipient IBAN of a payout)

Transaction

Name Type Required Description
TransactionId Guid required Unique TransactionId
TransactionTypeId int required Transacton Type (5: Card Charge, 4: Refund etc)
MerchantId Guid required The merchant of the transaction
OrderCode long required The Order Code of the transaction
Email string required Customer’s email
Phone string required Customer’s phone
ResellerId Guid? optional Id of Reseller
ResellerSourceCode string required SourceCode of Reseller
MerchantTrns string required Merchant Reference text
CustomerTrns string required Customer Reference text
ReferenceNumber int? required The Reference number of the transaction
CardCountryCode string required The two digit iso Country code of the Issuing Bank
CardIssuingBank string required The name of the Issuing Bank
InsDate DateTimeOffset required Transaction Execution Date
SourceCode string required SourceCode of the Transaction
FullName string required Customer’s Fullname
CardNumber string required Card Number (masked)
CardTypeId byte? required Card Type (0: Visa, 1:MasterCard etc)
CurrencyCode string required The iso currency code of the transaction (978: Euro etc)
Amount decimal required Amount of the transaction
CurrentInstallment byte required Current Installment # (if original transaction is CardChargeWithInstallments)
TotalInstallments byte required Total Installments # (if original transaction is CardChargeWithInstallments)
ChannelId Guid required Channel of the transaction
StatusId string required The status of the transaction (‘F’: Successful, ‘X’: Canceled etc)
OrderTags List<string> required The Order Tags of the transaction
ClearanceDate DateTimeOffset? optional The datetime transaction was cleared by Viva
InterchangeFee decimal required The interchange fee of the transaction
SchemeFee decimal required The scheme fee of the transaction
TotalCommission decimal required The commission charged on merchant for the transaction
SourceTerminalId long required The terminalId of the transaction
PanEntryMode string required The two-digit iso code indicated the Pan Entry Mode

TransactionStats

Name Type Required Description
MerchantId Guid required The merchant of the transaction
InsDate DateTimeOffset required Transaction Execution Date in closest distribution interval.
In monthly distribution, the 1st of each month is returned (e.g.
CurrencyCode string required The iso currency code of the transaction (978: Euro etc)
CP bool required Indicates CardPresent or CardNoPresent transactions
count long required Aggregate, indicates count of transactions in range and group
amount decimal required Aggregate, indicates sum of transaction amounts in range and group
totalCommission decimal required Aggregate, indicates sum of transaction Total Commisions in range and group
tipAmount decimal required Aggregate, indicates sum of transaction Tip amounts in range and group

SummaryStats

Name Type Required Description
Type string required Enum to identify the type of metric (Sale, Void, Refund, PreAuth)
CurrencyCode string required The iso currency code of the transaction (978: Euro etc)
count long required Aggregate, indicates count of transactions in range and group
amount decimal required Aggregate, indicates sum of transaction amounts in range and group
totalCommission decimal required Aggregate, indicates sum of transaction Total Commisions in range and group
tipAmount decimal required Aggregate, indicates sum of transaction Tip amounts in range and group

SummaryTotals

Name Type Required Description
CurrencyCode string required The iso currency code of the transaction (978: Euro etc)
amount decimal required Aggregate, indicates sum of transaction amounts in range and group
count long required Aggregate, indicates count of transactions in range and group
totalCommission decimal required Aggregate, indicates sum of transaction Total Commisions in range and group
tipAmount decimal required Aggregate, indicates sum of transaction Tip amounts in range and group