Viva Documentation

Explore our guides and examples to integrate with Viva.

Open Demo Account

Get started with Viva by creating for free an account in the demo environment.

Your account in demo allows you to:

Request and send money
See your account details (Account ID, IBAN)
Get your account credentials for the integration
Check your balance
See the Sales transactions

Authentication

To submit payments with Viva, you will be making API requests that are authenticated using your account credentials.

If you don’t include them when making an API request, or use incorrect credentials, you will get an error.

Your account credentials are always available in the Self Card Dashboard.

Find your account credentials for Basic Auth.
Find your account credentials for OAuth2.

Viva use the below authentication methods for user authentication:

You may find below a Postman example for OAuth2 user authentication method.

🔐 You may find in every API Call the required authentication method

OAuth2

Security Scheme Type	OAuth2
clientCredentials OAuth Flow	Token URL: https://demo-accounts.vivapayments.com/connect/token Scopes: `urn:viva:payments:[xxx]` - (credentials-dependent)

BasicAuth

Security Scheme Type	HTTP
HTTP Authorization Scheme	basic

SandBox

The sandbox can be used for all your development / demo requirements. No actual payments can be made within this environment (you cannot use a real card).

To simulate a successful payment in the demo environment, use one of our test cards to mimic a payment of 30¢/30p or more.

Live environment

Actual transactions are executed in the live environment. The minimum transaction amount is the same as for the demo environment.

Glossary

Term	Description
Customer	The customer is the user who wants to pay for the product(s) and service(s).
Merchant	The merchant is the company that wants to receive payments product(s) and service(s) from the customer(s).
Payment	A payment request from the merchant.

Get Support

If you would like to integrate with Viva, or if you have any queries about our products and solutions, please see our Contact & Support page to see how we can help!

Payments

Create payment order

Every payment on the Viva platform needs an associated payment order. A payment order is represented by a unique numeric orderCode.

Note: For Marketplace orders, please see our Marketplace Create Payment Order API call which contains additional parameters.

As well as the below detailed information about this API call, we have a PHP code sample available.

This API call uses OAuth2 authentication.

Each payment orderCode is used for one payment only.

Authorizations:

OAuth2 (urn:viva:payments:core:api:redirectcheckout)

header Parameters

Content-Type

required

string

Default: application/json

Request Body schema: application/json

amount required	integer <int64> >= 30 The amount associated with this payment order. Must be a positive, non-zero number. The amount will be in the currency of the merchant account using the currency's smallest unit of measurement (e.g. cents of a euro). For example, if you want to create a payment for €100.37, you need to pass the value `10037`.
customerTrns	string [ 1 .. 2048 ] Default: null This optional parameter adds a friendly description to the payment order that you want to display to the customer on the payment form. It should be a short description of the items/services being purchased. Although optional, it is highly recommended to provide a description for the customer, so that the customer knows what he is being asked to pay for; this affects significantly the conversion rate of your online store.
customer	object Information about the customer
dynamicDescriptor	string <= 13 A descriptor tailored to the transaction, ensuring clarity and recognition for the buyer on their bank statement and 3DS verification page. This parameter generates a dynamic descriptor for bank statements when processing a payment through smart checkout. The descriptor is limited to no more than 13 characters, can contain only `Latin characters`, `numbers`, and `space`. Special characters are replaced by spaces to meet banking standards. When specified, the buyer will see the first 8 characters of the merchant's trade name, followed by a space, and up to 13 characters of the dynamic descriptor. For example: `MerchantX Descriptor`. If not specified, the merchant's trade name will be shown up to 22 charachters. The `dynamicDescriptor` is included in the following webhooks with the `Descriptor` parameter. - Transaction Payment Created - Transaction Failed - Transaction Reversal Created
paymentTimeout	integer Default: 1800 The time given to the customer to complete the payment. If the customer does not complete the payment within this time frame, the Payment Order is automatically cancelled. By using this parameter, you can define a different life span for the Payment Order. Value is in seconds and can be either smaller or greater than 1800 secs. Use value 65535 if you want the Payment Order to never expire.
currencyCode	string <int32> Default: "Gets the merchant currency" The numeric code of the order's currency as defined in ISO 4712. Merchants can create order codes in different currencies than the currency of the country to which they are registered. The currency code specified in this parameter indicates the currency in which the customer's payment will be made. Please see this page for more details and restrictions about multicurrency functionality.
preauth	boolean Default: false This will hold the selected amount as unavailable (without the customer being charged) for a period of time. No email receipt is sent out from us in this case as it is not a charge. To cancel a pre-auth, use the Cancel transaction API call in the same way that you would to reverse a payment. To capture a pre-auth, use the Create transaction API call in the same way that you would to create a payment. For further details, see our Handle pre-authorizations tutorial. The payment method needs to have support for pre-auth transactions. If set to `true`, a pre-auth transaction will be performed. Pre-authorizations are not available with recurring payments or instalments. Additionally, when creating a payment order for a pre-authorization (with `preauth` = `true`), tipAmount should only be set when capturing the pre-authorization, and not when creating the initial payment order
allowRecurring	boolean Default: false If this parameter is set to `true`, recurring payments are enabled so that the initial transaction ID can be used for subsequent payments. For details of how to create a recurring payment, view our Create a recurring payment tutorial. For an example of recurring payments in action, see our PHP code sample. The payment method needs to have support for recurring payments. Keep in mind it is your responsibility to have the customer's consent to perform recurring payments (using this parameter constitutes your confirmation that you have such consent)! Recurring payments are not available with pre-authorizations or instalments.
maxInstallments	integer <int32> [ 1 .. 36 ] Default: 0 The maximum number of installments that the customer can choose for this transaction. If this parameter is omitted, the customer will not see an option for paying with installments. The payment method needs to have support for installments. Installments are available only to merchants set up in Greece and are not available with recurring payments or pre-authorizations. Please note: If offering installments, the value provided by the merchant is not the number of installments the customer will select, and it is not mandatory for the customer to select installments at all. The process is as follows: 1. The merchant indicates the maximum number of installments they wish to offer to the customer 2. It is then up to the customer whether they pay with or without installments 3. If the customer decides to pay with installments, they are able to select the number of installments (up to the maximum specified by the merchant)
forceMaxInstallments	boolean Default: false If this parameter is set to `true`, the customer will be forced to pay with installments and with the specific number indicated in `maxInstallments` parameter. For details of how to create a payment with installments, view our Handle payments with card installments tutorial. Please note: 1. Only cards supporting installments can be used for the payment 2. The `maxInstallments` value indicates the number of installments that will be forced to the customer. It should be >`0`, otherwise the call will return an error
paymentNotification	boolean Default: false If you wish to create a payment order, and then send out an email to the customer to request payment, rather than immediately redirect the customer to the payment page to pay now, set the value to `true`, and the system will automatically send the customer an email notification. This is equivalent to sending a payment notification from the viva banking app.
tipAmount	integer <int64> Default: 0 The tip value (if applicable for the customer's purchase) which is already included in the `amount` of the payment order and marked as tip. It is in the currency of the merchant account using the currency's smallest unit of measurement (e.g. cents of a euro). When creating a payment order for a pre-authorization (with `preauth` = `true`), tipAmount should only be set when capturing the pre-authorization, and not when creating the initial payment order
disableExactAmount	boolean Default: false If this parameter is set to `true`, then any amount specified in the payment order is ignored (although still mandatory), and the customer is asked to indicate the amount they will pay. Note that if set to true, there will not be the option to pay with certain payment methods.
disableCash	boolean Default: false If this parameter is set to `true`, the customer will not have the option to pay in cash at a Viva Spot, and the checkout page will not display the Cash (Viva Spot) and e-banking (ΔΙΑΣ) options. Available only to merchants set up in Greece.
disableWallet	boolean Default: false If this parameter is set to `true`, the customer will not have the option to pay using their Viva personal account (wallet), and the checkout page will not display the Viva Wallet option. Available only to merchants set up in Greece, Malta and Cyprus.
sourceCode	string This is the code of the payment source associated with the merchant. If the merchant has defined multiple payment sources in their account, you need to define the `sourceCode` parameter when creating the payment order, so that the system selects the appropriate payment source. sourceCode is case-sensitive. If left unspecified, `Default` source code is used.
merchantTrns	string [ 1 .. 2048 ] Default: null This can be either an ID or a short description that helps you uniquely identify the transaction in the viva banking app. For example, this can be the customer order reference number. After logging in, go to Sales > Sales Transactions and find the transaction. Click on the Info button against the item to display the Transaction Details dialog box. The contents of the `merchantTrns` field will be displayed on the line below the timestamp information.
tags	Array of strings Default: null You can add several tags to a transaction that will help in grouping and filtering in the viva banking app. After logging in, go to Sales > Sales Transactions and expand the Advanced search feature. In the Tags field, enter the tag(s) you want to search with, then click on the Search button.
cardTokens	Array of strings Default: null You can provide the card tokens you have saved on your backend for this customer. The card tokens will then be presented to the customer on Smart Checkout to pay with. For details, view our Handle Card Tokens tutorial. The API call returns an error if a) you provide more than 10 card tokens, or b) if you provide invalid card tokens. You cannot send card tokens if the payment order is for an open amount, i.e. if `disableExactAmount` is true
paymentMethodFees	Array of objects Default: null Applies an additional 'Service fee' to be added on top of the order amount if the customer chooses to pay with specific payment methods. The amount will be in the currency of the merchant account using the currency's smallest unit of measurement (e.g. cents of a euro). Currently only applicable for payment method ‘Pay on Delivery’. Example of usage for Pay On Delivery: `"paymentMethodFees": [{"paymentMethodId":"35", "fee": 250}]`
isCardVerification	boolean Default: false This parameter should be set to `true` to trigger a verification using Card Verification functionality (and the `amount` parameter should be set to '0'). Please note: This is currently only available for card payments via Visa, Mastercard, Maestro, Diners Club & Discover (digital wallets are not supported) Recurring payments are supported This is not available with the ISV schema The following parameters are also not compatible with Card Verification: `preauth`, `maxInstallments`/`forceMaxInstallments`, `disableExactAmount`, `tipAmount`, `cardTokens`
nbgLoanOrderOptions	object Information about the NBG Loan.
klarnaOrderOptions	object <array of objects> These parameters are required when Klarna is being offered as a payment method.

Responses

200

Success - Return an HTTP 200 status to indicate that the data was received successfully

400

Bad Request

401

Unauthorized

403

Fail

5xx

Internal Server Error

post /checkout/v2/orders

Sandbox environment

https://demo-api.vivapayments.com/checkout/v2/orders

Live environment

https://api.vivapayments.com/checkout/v2/orders

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"amount": 10,
"customerTrns": "string",
"customer": 
{"email": "string",
"fullName": "string",
"phone": "string",
"countryCode": "string",
"requestLang": "string"
},
"dynamicDescriptor": "Descriptor",
"currencyCode": 978,
"paymentTimeout": 0,
"preauth": false,
"allowRecurring": false,
"maxInstallments": 0,
"forceMaxInstallments": false,
"paymentNotification": true,
"tipAmount": 1,
"disableExactAmount": false,
"disableCash": false,
"disableWallet": false,
"sourceCode": "Default",
"merchantTrns": "string",
"tags": 
["tag 1",
"tag 2"
],
"paymentMethodFees": 
{"paymentMethodId": "35",
"fee": 250
},
"cardTokens": 
["ct_5d0a4e3a7e04469f82da228ca98fd661"
],
"isCardVerification": false,
"nbgLoanOrderOptions": 
{"Code": "NBG Loan for the Order Id",
"ReceiptType": 1
},
"klarnaOrderOptions": 
{"attachment": 
{"body": "string",
"contentType": "string"
},
"billingAddress": 
{"city": "London",
"email": "johndoe@viva.com",
"phone": "++442037347770",
"title": "Mr",
"region": "Greater London",
"country": "GB",
"givenName": "John",
"familyName": "Doe",
"postalCode": "SW19 9QZ",
"streetAddress": "Bredowstr. 41",
"streetAddress2": ""
},
"shippingAddress": 
{"city": "London",
"email": "johndoe@viva.com",
"region": "Greater London",
"phone": "+4917665632531",
"country": "GB",
"givenName": "John",
"familyName": "Doe",
"postalCode": "SW19 9QZ",
"streetAddress": "Bredowstr. 41",
"streetAddress2": ""
},
"orderLines": 
[
{"name": "TestProductName",
"type": "physical",
"taxRate": 0,
"quantity": 1,
"unitPrice": 1,
"imageUrl": "string",
"reference": "string",
"totalAmount": 1,
"productUrl": "string",
"merchantData": "string",
"quantityUnit": "pcs",
"totalTaxAmount": 0,
"totalDiscountAmount": 0,
"subscription": 
{"name": "Sub 1",
"interval": "DAY",
"intervalCount": 1
},
"productIdentifiers": 
{"size": "small",
"brand": "shoe-brand",
"color": "white",
"categoryPath": "Shoes > Running",
"globalTradeItemNumber": "",
"manufacturerPartNumber": ""
}
},
{"name": "TEST PRODUCT",
"quantity": "1",
"unit_price": 1,
"tax_rate": 0,
"total_amount": 1,
"total_discount_amount": 0,
"total_tax_amount": 0,
"product_url": "https://.../AD6654412.html",
"image_url": "https://....com/product.png"
}
]
}
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"orderCode": 7568594363572609
}

Retrieve order

To retrieve information about a specific order.

This API call uses Basic authentication.

Authorizations:

BasicAuth (See BasicAuth)

path Parameters

orderCode

required

integer <int64>

The 16-digit orderCode for which you wish to retrieve information.

Responses

200

Success

401

Unauthorized

404

Fail - Specified order code does not exist or is invalid

5xx

Internal Server Error

get /api/orders/{orderCode}

Sandbox environment

https://demo.vivapayments.com/api/orders/{orderCode}

Live environment

https://www.vivapayments.com/api/orders/{orderCode}

Request samples

cURL
PHP
NodeJs
Java

Copy

curl --location -g 'https://demo.vivapayments.com/api/orders/{orderCode}?orderCode=null' \
--header 'Authorization: Basic TWVyY2hhbnRfSUQ6QVBJX0tleQ=='

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"OrderCode": 3958121726095215,
"SourceCode": "Default",
"Tags": [ ],
"TipAmount": 0,
"RequestLang": "en-GB",
"MerchantTrns": "Your merchant reference",
"CustomerTrns": "Short description of items/services purchased to display to your customer",
"MaxInstallments": 12,
"RequestAmount": 100,
"ExpirationDate": "2015-07-08T00:13:03.243",
"StateId": 3
}

Cancel payment order

Cancelling a standing payment order is pretty straightforward. You will need your Merchant ID, password and a valid 16-digit payment order code.

This API call uses Basic authentication.

Authorizations:

BasicAuth (See BasicAuth)

path Parameters

orderCode

required

integer <int64>

The 16-digit orderCode for which you requested information.

Responses

200

Success

401

Unauthorized

404

Fail - Specified order code does not exist or is invalid

5xx

Internal Server Error

delete /api/orders/{orderCode}

Sandbox environment

https://demo.vivapayments.com/api/orders/{orderCode}

Live environment

https://www.vivapayments.com/api/orders/{orderCode}

Request samples

cURL
PHP
NodeJs
Java

Copy

curl --location -g --request DELETE 'https://demo.vivapayments.com/api/orders/{orderCode}?orderCode=null' \
--header 'Authorization: Basic TWVyY2hhbnRfSUQ6QVBJX0tleQ=='

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"OrderCode": 1759365092162578,
"ErrorCode": 0,
"ErrorText": "Error Message",
"TimeStamp": "2012-12-24T15:22:23.085251+02:00",
"CorrelationId": "null,",
"EventId": 0,
"Success": true
}

Update an order

Enables you to update certain information relating to a standing payment order.

This API call uses Basic authentication.

Authorizations:

BasicAuth (See BasicAuth)

path Parameters

orderCode

required

integer <int64>

The 16-digit orderCode for which you requested information.

Request Body schema: application/json

amount	integer <int64> The new amount of the order (in the currency's smallest unit of measurement). Note: If this parameter is used, it cannot have a value of `0`.
disablePaidState	boolean Allows the order to accept multiple payments (`true`) or not (`false`).
expirationDate	string <date-time> The expiration date of the order.
isCanceled	boolean Changes the cancelled status of the order.

Responses

200

Success

401

Unauthorized

404

Fail - Specified order code does not exist or is invalid

5xx

Internal Server Error

patch /api/orders/{orderCode}

Sandbox environment

https://demo.vivapayments.com/api/orders/{orderCode}

Live environment

https://www.vivapayments.com/api/orders/{orderCode}

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"amount": 0,
"disablePaidState": true,
"expirationDate": "2025-04-16T07:41:14Z",
"isCanceled": true
}

Response samples

Content type

application/json

Copy

Expand all Collapse all

null

Transactions

Retrieve transaction

Enables you to obtain detailed information about a past payment from its transaction ID, e.g.

GET /checkout/v2/transactions/b1a3067c-321b-4ec6-bc9d-1778aef2a19d

Find out about the possible transaction feedback parameters.

As well as the below detailed information about this API call, we have a PHP code sample available.

This API call uses OAuth2 authentication.

Authorizations:

OAuth2 (urn:viva:payments:core:api:redirectcheckout)

path Parameters

transactionId

required

string <uuid>

The unique ID of the initial transaction.

Responses

200

Success

401

Unauthorized

404

Fail - Transaction Id does not exist

5xx

Internal Server Error

get /checkout/v2/transactions/{transactionId}

Sandbox environment

https://demo-api.vivapayments.com/checkout/v2/transactions/{transactionId}

Live environment

https://api.vivapayments.com/checkout/v2/transactions/{transactionId}

Request samples

cURL
PHP
NodeJs
Java

Copy

curl --location -g 'https://demo-api.vivapayments.com/checkout/v2/transactions/{transactionId}' \
--header 'Authorization: Bearer {Bearer_Token}' \
--data ''

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"email": "someone@vivawallet.com",
"bankId": "NET_VISA",
"amount": 21.1,
"conversionRate": 1.2,
"originalAmount": 10.55,
"originalCurrencyCode": "978",
"sourceCode": "3891",
"switching": false,
"orderCode": 6810910170372602,
"statusId": "F",
"fullName": "George Seferis",
"insDate": "2025-04-16T07:41:14.507Z",
"cardNumber": "523929XXXXXX0168",
"currencyCode": "978",
"customerTrns": "This is a description displayed to the customer",
"merchantTrns": "This is a short description that helps you uniquely identify the transaction",
"transactionTypeId": 5,
"recurringSupport": false,
"totalInstallments": 0,
"cardCountryCode": "GR",
"cardUniqueReference": "9521B4209B611B11E080964E09640F4EB3C3AA18",
"cardIssuingBank": null,
"EventId": null,
"currentInstallment": 0,
"cardTypeId": 1,
"cardExpirationDate": "2025-04-16T07:41:14.507Z",
"digitalWalletId": 2,
"loyaltyTransactions": 
[
{"pointsEarned": 1333,
"referenceNumber": 488425,
"pointsRedeemed": 300,
"amountEarned": null,
"amountRedeemed": 1,
"ProgramId": 3,
"externalReferenceNumber": "276683791032330",
"retrievalReferenceNumber": "427711014586",
"loyaltyTransactionTypeId": 0
},
{"pointsEarned": 1333,
"referenceNumber": 488425,
"pointsRedeemed": 300,
"amountEarned": 0,
"amountRedeemed": 1,
"ProgramId": 3,
"externalReferenceNumber": "276683791032330",
"retrievalReferenceNumber": "427711488425",
"loyaltyTransactionTypeId": 1
}
]
}

Create card token

Obtain the card token associated with the card used for the specific transaction. The API call returns an error if a) the customer paid with a payment method other than a card, or b) the customer paid with a digital wallet (Apple Pay, Google Pay, Samsung Pay).

Keep in mind it is your responsibility to have the customer's consent to store the card token on your backend (using this API constitutes your confirmation that you have such consent)!

Kindly note that different transactions that were paid with the same card will return different card tokens, so before saving a card token on your backend for a specific customer you first need to make sure that the 'card unique reference' of the transaction is different than the ones already saved for past transactions. For details, view our Handle Card Tokens tutorial.

This feature is available only upon request. Please contact your sales representative or use our Live Chat to request this feature.

Authorizations:

OAuth2 (urn:viva:payments:core:api:acquiring, urn:viva:payments:core:api:acquiring:cardtokenization)

header Parameters

Content-Type

required

string

Default: application/json

Request Body schema: application/json

transactionId	string <string> The unique ID of the initial transaction.
groupId	string <string or null> The Group ID (for merchant group functionality). This parameter should be specified if a group of merchants with shared tokens take place.
cardTokenType	string <integer> The cardTokenType specifies if the requested token is for Oracle OPI or not. You may find below the possible values: 0 = Default 1 = Oracle OPI

Responses

200

Success - Return an HTTP 200 status to indicate that the data was received successfully

401

Unauthorized

5xx

Internal Server Error

post /acquiring/v1/cards/tokens

Sandbox environment

https://demo-api.vivapayments.com/acquiring/v1/cards/tokens

Live environment

https://api.vivapayments.com/acquiring/v1/cards/tokens

Request samples

Payload
cURL
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"transactionId": "string",
"groupId": "string",
"cardTokenType": 0
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"token": "ct_5d0a4e3a7e04469f82da228ca98fd661"
}

Create transaction

This API call covers the following use cases:

Use Case 1: Make a recurring payment

Recurring payments are permitted only if the following conditions are met:

The payment method has support for recurring payments.
The customer has already been charged successfully in the past
The customer has agreed to allow recurring payments using the initial payment method.

You should use the same ID for every subsequent recurring transaction. For each recurring payment, the following parameters are re-used from the initial transaction:

Please note that you need to set the sourceCode to be the same with the initial transaction, if you want to charge the payments in the same source. Otherwise, if you do not set this parameter, the recurring payment will be charged on the default source.

fullName
email
phone
sourceCode
tags

A situation where you would need to set up recurring payments is if you're a merchant offering a subscription-based product to customers.

For details of how to create a recurring payment, view our Create a recurring payment tutorial.

We also have a recurring payment PHP code sample available.

Use Case 2: Make a new payment by committing an already authorized transaction

Keep in mind that you need to have previously completed successfully a payment whose payment order had isPreAuth = true.

Please note: when creating a payment order for a pre-authorization (with isPreAuth = true), tipAmount should only be set when capturing the pre-authorization, and not when creating the initial payment order.

For Marketplace integrations, please note: capturing a pre-authorization must be done using the Merchant ID & API Key of your Platform account.

For each captured payment, the following three parameters are re-used from the initial pre-auth:

fullName
email
requestLang

If you do not set the following parameters when capturing the transaction, customerTrns and merchantTrns will be null and the captured payment will be transferred to the default source.

customerTrns
merchantTrns
sourceCode

For further details, see our Handle pre-authorizations tutorial.

This API call uses Basic authentication.

Authorizations:

BasicAuth (See BasicAuth)

path Parameters

required

string

The unique ID of the initial transaction.

header Parameters

Content-Type

required

string

Default: application/json

Request Body schema: application/json

amount required	integer <int64> The amount requested in the currency's smallest unit of measurement. For capturing authorized transactions, this amount should not exceed the amount entered in the initial transaction. For example. if you want to create a payment for €100.37, you need to pass the value 10037.
installments	integer <int32> [ 1 .. 36 ] The maximum number of installments that the customer can choose for this transaction. If this parameter is omitted, the customer will not see an option for paying with installments. Available only to merchants set up in Greece.
customerTrns	string A friendly description that you want to display to the customer. This description appears on the receipt the customer receives.
merchantTrns	string An ID or a short description that helps you uniquely identify the transaction. For example, this can be your customer order reference number.
sourceCode	string A unique code that is exchanged between your application and the API. Note that if you leave this parameter empty, it would take the Default value.
tipAmount	integer <int64> Default: 0 The tip value (if applicable for the customer's purchase) which is already included in the `amount` of the payment order and marked as tip. It is in the currency of the merchant account using the currency's smallest unit of measurement (e.g. cents of a euro). Please note: when creating a payment order for a pre-authorization (with `isPreAuth` = `true`), `tipAmount` should only be set when capturing the pre-authorization, and not when creating the initial payment order.
currencyCode	string The numeric code of the transaction's currency as defined in ISO 4712. Merchants can create a transaction in different currencies than the currency of the country to which they are registered. The currency code specified in this parameter indicates the currency in which the customer's payment will be made. Please see this page for more details and restrictions about multicurrency functionality.

Responses

200

Success

400

Amount could not be validated -or- tipAmount is <= 0 -or- Request is invalid

401

Unauthorized

403

SourceCode could not be validated -or- serviceId not valid for merchant -or- Transaction does not allow recurring payments -or- Installment number is not valid

500

customerTrns or merchantTrns > 2048 chars -or- amount > 1 quintillion (18 zeroes)

5xx

Internal Server Error

post /api/transactions/{transaction_id}

Sandbox environment

https://demo.vivapayments.com/api/transactions/{transaction_id}

Live environment

https://www.vivapayments.com/api/transactions/{transaction_id}

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"amount": 100,
"installments": 1,
"customerTrns": "A description of products / services that is displayed to the customer",
"merchantTrns": "Your merchant reference",
"sourceCode": 6054,
"tipAmount": 0,
"currencyCode": 978
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"Emv": null,
"Amount": 90,
"StatusId": "F",
"CurrencyCode": 978,
"TransactionId": "bd5390a9-5870-4d8d-abea-7f5a94f9cecc",
"ReferenceNumber": 933351,
"AuthorizationId": 933351,
"RetrievalReferenceNumber": 122411933351,
"ThreeDSecureStatusId": 2,
"ErrorCode": 0,
"ErrorText": "Error description",
"TimeStamp": "2012-12-24T15:23:38.5157933+02:00",
"CorrelationId": null,
"EventId": 0,
"Success": true
}

Cancel transaction

This method enables you to:

Cancel / Reverse a payment - either partially or fully - which occurred within the same calendar day
Refund / Void a successful payment - either partially or fully - which occurred on a previous calendar day

The payment method used needs to have support for refunds.
To avoid an error, ensure you have enabled refunds in your Viva account.

This API call uses Basic authentication.

Example: DELETE /api/transactions/5f2a02b0-e4d9-4ec8-99b5-a67c1dc57ac0/?amount=200&sourceCode=xxxx&currencyCode=978

Authorizations:

BasicAuth (See BasicAuth)

path Parameters

required

string

The unique ID of the initial transaction.

query Parameters

amount required	integer The amount that will be refunded in the currency's smallest denomination (e.g amount in pounds / euros x 100). It cannot exceed the amount of the original payment unless it is an OCT. For example, if you want to refund a payment of £100.37, you need to pass the value `10037`.
sourceCode	string The source which the refund should be applied to. For example, to refund to the Source with the code "HQ", add '&sourceCode=HQ'.
merchantTrns	string An ID or a short description that helps you uniquely identify the transaction. For example, this can be your customer order reference number.
customerTrns	string A friendly description that you want to display to the customer. This description appears on the receipt the customer receives.
currencyCode	string <int32> The numeric code of the refund's currency as defined in ISO 4712. Merchants can refund in different currencies than the originally captured. The currency code specified in this parameter indicates the currency in which the customer's refund will be made, add `&currencyCode=XXX`. Please see this page for more details and restrictions about multicurrency functionality.

Responses

200

Success

400

Request is invalid -or- Payment amount not valid for cancellation

401

Unauthorized

403

Transaction already cancelled -or- Refund amount exceeds total amount

5xx

Internal Server Error

delete /api/transactions/{transaction_id}

Sandbox environment

https://demo.vivapayments.com/api/transactions/{transaction_id}

Live environment

https://www.vivapayments.com/api/transactions/{transaction_id}

Request samples

cURL
PHP
NodeJs
Java

Copy

curl --location -g --request DELETE 'https://demo.vivapayments.com/api/transactions/{id}?amount={amount}' \
--header 'Authorization: Basic TWVyY2hhbnRfSUQ6QVBJX0tleQ=='

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"Emv": null,
"Amount": 2,
"StatusId": "F",
"CurrencyCode": 826,
"TransactionId": "bd5390a9-5870-4d8d-abea-7f5a94f9cecc",
"ReferenceNumber": 909196,
"AuthorizationId": null,
"RetrievalReferenceNumber": 122409743701,
"ThreeDSecureStatusId": 2,
"ErrorCode": 0,
"ErrorText": null,
"TimeStamp": "2025-04-16T07:41:14.511Z",
"CorrelationId": null,
"EventId": 0,
"Success": true
}

Cancel Partial Authorization

This API call is used to cancel a Partial Authorization (Partial Approval) transaction.

Partial Approvals refer to transactions in which the customer has not covered the cost of the entire purchase, with some of the purchase amount therefore remaining to be taken (potentially via a different payment method).

Please note: Partial Approvals are only utilised in specific cases, and are not currently available to all merchants.

Authorizations:

OAuth2 (See OAuth2)

path Parameters

transactionId

required

string

Example: 082886d5-6021-4ebe-bbe2-1a50e6bcc5b6

Transaction Id of transaction to cancel

query Parameters

amount required	integer Example: amount=123 Amount to cancel
sourceCode	string Example: sourceCode=1234 Source to use for transaction cancellation. Defaults to source code of parent transaction
merchantTrns	string Example: merchantTrns=1a2b3c4d An ID or a short description that helps you uniquely identify the transaction
idempotencyKey	string Example: idempotencyKey=567890567890 Specify a key in order for the call have idempotent behaviour for all calls with the same key

Responses

200

Success

401

Unauthorized

5xx

Internal Server Error

delete /acquiring/v1/transactions/{transactionId}

Live environment

https://api.vivapayments.com/acquiring/v1/transactions/{transactionId}

Sandbox environment

https://demo-api.vivapayments.com/acquiring/v1/transactions/{transactionId}

Request samples

cURL
PHP
NodeJs
Java

Copy

curl --location -g --request DELETE 'https://demo-api.vivapayments.com/acquiring/v1/transactions/{transactionId}?amount={amount}' \
--header 'Authorization: Bearer Bearer_Token'

Response samples

Content type

application/json

Copy

Expand all Collapse all

"Success"

OCT & Pay Out

Original Credit Transaction (OCT):

Pays directly an amount to a card. It is a refund transaction which allows you to return money to a card, irrespective of the original payment amount.

Example: DELETE /api/transactions/a93da583-2959-491f-94ce-645e1e673ddc/?amount=200&ServiceId=6&sourceCode=4855&merchantTrns=Merchantdescription&customerTrns=Customerdescription

Please Note:

OCT is available only within the 'Betting' trading category (7995). If your business is eligible, please request access by emailing support@vivapayments.com
OCT transactions will fail (PaymentsInsufficientFundsForReversal) if the transaction is for an amount higher than the available wallet balance
OCT is only supported by the Visa & Mastercard schemes
OCT can only be used for Card-not-Present (e-commerce) payments made via cards and Digital Wallets (such as Apple Pay, Google Pay, etc.) - it cannot be used for Card-Present (POS) payments or other Alternative Payment Methods

Pay Out [DEPRECATED]:

Please Note: Pay Out is now deprecated. Please contact your Sales representative for more information

Pays directly an amount to a card. It is a refund transaction which allows you to return money to a card, irrespectively of the original payment amount.

Example: DELETE /api/transactions/a93da583-2959-491f-94ce-645e1e673ddc/?amount=200&ServiceId=14&sourceCode=4855&merchantTrns=Merchantdescription&customerTrns=Customerdescription

Authorizations:

BasicAuth (See BasicAuth)

path Parameters

required

string

The unique ID of the initial transaction.

query Parameters

amount required	integer The amount that will be refunded in the currency's smallest denomination (e.g amount in pounds / euros x 100). For example, if you want to refund a payment of £100.37, you need to pass the value `10037`. *Please note:* OCT and Pay Out transactions will fail (`PaymentsInsufficientFundsForReversal`) if the transaction is for an amount higher than the available wallet balance.
serviceId required	number The value `6` is necessary in order to perform an OCT, the value `14` is necessary in order to perform a Pay Out
idempotencyKey required	string Specify a key in order for the call have idempotent behaviour for all calls with the same key
sourceCode	number The source from which the funds will be withdrawn. Each source is linked to a wallet. If no `sourceCode` parameter is set then the funds will be withdrawn from the primary wallet.
merchantTrns	string An ID or a short description that helps you uniquely identify the transaction. For example, this can be your customer order reference number.
customerTrns	string A friendly description that you want to display to the customer. This description appears on the receipt the customer receives.
currencyCode	string The numeric code of the transaction's currency as defined in ISO 4712. Merchants can create a transaction in different currencies than the currency of the country to which they are registered. The currency code specified in this parameter indicates the currency in which the customer's payment will be made. Please see this page for more details and restrictions about multicurrency functionality.

Responses

200

Success

400

Request is invalid -or- Payment amount not valid for cancellation

401

Unauthorized

403

Transaction already cancelled -or- Refund amount exceeds total amount

5xx

Internal Server Error

delete /api/transactions/{transaction_Id}

Sandbox environment

https://demo.vivapayments.com/api/transactions/{transaction_Id}

Live environment

https://www.vivapayments.com/api/transactions/{transaction_Id}

Request samples

cURL
PHP
NodeJs
Java

Copy

curl --location -g --request DELETE 'https://demo.vivapayments.com/api/transactions/{id}?amount={amount}&serviceId={serviceId}' \
--header 'Authorization: Basic TWVyY2hhbnRfSUQ6QVBJX0tleQ=='

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"Emv": null,
"Amount": 2,
"StatusId": "F",
"CurrencyCode": 826,
"TransactionId": "bd5390a9-5870-4d8d-abea-7f5a94f9cecc",
"ReferenceNumber": 909196,
"AuthorizationId": null,
"RetrievalReferenceNumber": 122409743701,
"ThreeDSecureStatusId": 2,
"ErrorCode": 0,
"ErrorText": null,
"TimeStamp": "2025-04-16T07:41:14.511Z",
"CorrelationId": null,
"EventId": 0,
"Success": true
}

Rebate

This call allows merchants to perform 'rebates', tied to an initial transactionId. This is most commonly related to cardholder rewards or loyalty.

A Rebate can be cancelled using the Cancel Rebate / Fast Refund API call.

Please Note:

Rebates are not available for betting merchants
Only Visa and Mastercard support this functionality. Therefore, only a transactionId made with Visa or Mastercard (including Maestro) can be used (where supported by the customer’s bank)
The Rebate API call can only be used for Card-not-Present (e-commerce) payments made via cards and Digital Wallets (such as Apple Pay, Google Pay, etc.) - it cannot be used for Card-Present (POS) payments or other Alternative Payment Methods
For Rebates, the Transaction Reversal Created webhook is triggered with ServiceId = 18
Rebate functionality is not enabled by default, and is subject to approval. Please contact your sales representative or reach out via our Live Chat feature to enquire

Authorizations:

OAuth2 (urn:viva:payments:core:api:acquiring, urn:viva:payments:core:api:acquiring:transactions)

path Parameters

transactionId

required

string <uuid>

The unique ID of the initial (parent) transaction

Request Body schema: application/json

amount required	integer <int64> The amount the merchant wishes to give to the client
sourceCode	string If not provided, "Default" will be used
merchantTrns	string An ID or a short description that helps you uniquely identify the transaction
idempotencyKey	string Specify a key in order for the call have idempotent behaviour for all calls with the same key

Responses

200

Success

400

Bad Request (issue with request data)

403

Forbidden (issue with merchant account or source or unsupported card scheme)

404

Not Found (transaction does not exist)

422

Unprocessable Entity (BIN not valid)

423

Locked (transaction is already in progress)

452

Unknown (insufficient funds)

5xx

Internal Server Error

post /acquiring/v1/transactions/{transactionId}:rebate

Sandbox environment

https://demo-api.vivapayments.com/acquiring/v1/transactions/{transactionId}:rebate

Live environment

https://api.vivapayments.com/acquiring/v1/transactions/{transactionId}:rebate

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"amount": 100,
"sourceCode": "Default",
"merchantTrns": "The text the merchant sees",
"idempotencyKey": "string"
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"transactionId": "1234abcd-9876-1aa1-b22b-654321a1b2c3"
}

Fast Refund

This call allows merchants to perform 'fast refunds', tied to an initial transactionId. These refunds happen in near-real-time (a matter of minutes).

A Fast Refund can be cancelled using the Cancel Rebate / Fast Refund API call.

Please Note:

Fast Refunds are not available for betting merchants
Only Visa and Mastercard support this functionality. Therefore, only a transactionId made with Visa or Mastercard (including Maestro) can be used (where supported by the customer’s bank)
The Fast Refund API call can only be used for Card-not-Present (e-commerce) payments made via cards and Digital Wallets (such as Apple Pay, Google Pay, etc.) - it cannot be used for Card-Present (POS) payments or other Alternative Payment Methods
For Fast Refunds, the Transaction Reversal Created webhook is triggered with ServiceId = 19
Fast Refund functionality is not enabled by default, and is subject to approval. Please contact your sales representative or reach out via our Live Chat feature to enquire

Authorizations:

OAuth2 (urn:viva:payments:core:api:acquiring, urn:viva:payments:core:api:acquiring:transactions)

path Parameters

transactionId

required

string <uuid>

The unique ID of the initial (parent) transaction

Request Body schema: application/json

amount required	integer <int64> The amount the merchant wishes to give to the client
sourceCode	string If not provided, "Default" will be used
merchantTrns	string An ID or a short description that helps you uniquely identify the transaction
idempotencyKey	string Specify a key in order for the call have idempotent behaviour for all calls with the same key

Responses

200

Success

400

Bad Request (issue with request data)

403

Forbidden (issue with merchant account or source or unsupported card scheme)

404

Not Found (transaction does not exist)

422

Unprocessable Entity (BIN not valid)

423

Locked (transaction is already in progress)

452

Unknown (insufficient funds)

5xx

Internal Server Error

post /acquiring/v1/transactions/{transactionId}:fastrefund

Sandbox environment

https://demo-api.vivapayments.com/acquiring/v1/transactions/{transactionId}:fastrefund

Live environment

https://api.vivapayments.com/acquiring/v1/transactions/{transactionId}:fastrefund

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"amount": 100,
"sourceCode": "Default",
"merchantTrns": "The text the merchant sees",
"idempotencyKey": "string"
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"transactionId": "1234abcd-9876-1aa1-b22b-654321a1b2c3"
}

Cancel Rebate / Fast Refund

This API call is used to cancel a Rebate or Fast Refund transaction.

Please note:

Cancellation is only supported for Mastercard/Maestro transactions
Cancellation should be done on the same day that the Rebate / Fast Refund transaction was created

Authorizations:

OAuth2 (See OAuth2)

path Parameters

transaction_Id

required

string

Example: 082886d5-6021-4ebe-bbe2-1a50e6bcc5b6

Transaction Id of transaction to cancel

query Parameters

amount required	integer Example: amount=123 Amount to cancel. This should be a positive amount, equal to the original rebate/refund amount (partial cancellations are not supported)
sourceCode	string Example: sourceCode=1234 Source to use for transaction cancellation. Defaults to source code of parent transaction
merchantTrns	string Example: merchantTrns=1a2b3c4d An ID or a short description that helps you uniquely identify the transaction
currencyCode	string Example: currencyCode=978 The numeric code of the transaction's currency as defined in ISO 4712. Merchants can create a transaction in different currencies than the currency of the country to which they are registered. The currency code specified in this parameter indicates the currency in which the customer's payment will be made. Please see this page for more details and restrictions about multicurrency functionality.
idempotencyKey	string Example: idempotencyKey=567890567890 Specify a key in order for the call have idempotent behaviour for all calls with the same key

Responses

200

Success

401

Unauthorized

415

Unsupported Media Type (VISA does not support cancellation)

5xx

Internal Server Error

delete /acquiring/v1/transactions/{transaction_Id}

Live environment

https://api.vivapayments.com/acquiring/v1/transactions/{transaction_Id}

Sandbox environment

https://demo-api.vivapayments.com/acquiring/v1/transactions/{transaction_Id}

Request samples

cURL
PHP
NodeJs
Java

Copy

curl --location --globoff --request DELETE 'https://demo-api.vivapayments.com/acquiring/v1/transactions/{transactionId}?amount={amount}' \
--header 'Authorization: Bearer Bearer_Token'

Response samples

Content type

application/json

Copy

Expand all Collapse all

"Success"

RF Code Payments

Generare RF Codes

This API allows you to generate RF Codes in order to get paid.

Please note: The RF Code generation API Call does not require any authentication.

The RF codes are applicable only in Greece for Greek merchants.

Request Body schema: application/json

orderCode

required

string

The 16-digit orderCode for which you wish to retrieve information.

Responses

200

Success

400

Bad Request

404

Not found

5xx

Error (incorrect/missing ReportDate or incorrect authorisation token)

post /web2/checkout/v2/paymentsessions

Sandbox environment

https://demo.vivapayments.com/web2/checkout/v2/paymentsessions

Live environment

https://www.vivapayments.com/web2/checkout/v2/paymentsessions

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"orderCode": 3097103021072605
}

Response samples

Content type

application/json

Copy

Expand all Collapse all

"200 No Content"

Balance Transfer

Allows you to transfer money:

from any of your Viva accounts to any Viva account of another merchant.
between your Vivas accounts.

This API call uses Basic authentication.

Authorizations:

BasicAuth (See BasicAuth)

path Parameters

walletId required	integer <int64> Example: 657297971060 Source ID of the wallet from which you wish to make the transfer. Displayed as Account ID under Accounts in the viva banking app.
targetWalletId required	integer <int64> Example: 454808702785 Destination ID of the wallet to which you wish to make the transfer. Displayed as Account ID under Accounts in the viva banking app.

header Parameters

Content-Type

required

string

Default: application/json

Request Body schema: application/json

amount required	integer <int64> >= 30 Must be a positive, non-zero number. The amount will be in the currency of the merchant account using the currency's smallest unit of measurement (e.g. cents of a euro). For example, if you want to make a transfer for €100.37, you need to pass the value `10037`.
description	string Default: null Some text to summarize the transfer reason. Appears on target account statement.
saleTransactionId	GUID Default: null The Viva transaction ID generated during checkout (as a reference only).
customerTrns	string Short description.

Responses

200

Success

400

Bad Request

401

Unauthorized

403

The amount is zero or is null or is missing

404

Not Found

415

Unsupported media type

452

Insufficient Funds

5xx

Internal Server Error

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

Sandbox environment

https://demo.vivapayments.com/api/wallets/{walletId}/balancetransfer/{targetWalletId}

Live environment

https://www.vivapayments.com/api/wallets/{walletId}/balancetransfer/{targetWalletId}

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"amount": 100,
"description": "Optional text to show on account statement",
"saleTransactionId": "Optional text referencing the related sales transaction",
"customerTrns": "Short description"
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


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

Retrieve Wallets and Transactions

Retrieve Merchant Wallets

Retrieve all wallets set up under your Viva profile.

This API call uses OAuth2 authentication.

Authorizations:

OAuth2 (urn:viva:payments:core:api:merchants, urn:viva:payments:core:api:merchants:wallets)

header Parameters

Content-Type

required

string

Default: application/json

Responses

200

Success

404

Not Found

5xx

Internal Server Error

get /merchants/v1/wallets

Sandbox environment

https://demo-api.vivapayments.com/merchants/v1/wallets

Live environment

https://api.vivapayments.com/merchants/v1/wallets

Request samples

cURL
PHP
NodeJs
Java

Copy

curl --location 'https://demo-api.vivapayments.com/merchants/v1/wallets' \
--header 'Authorization: Bearer {Bearer_Token}'

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"iban": "GB73VPAY04002491883585",
"walletId": 91883585,
"amount": 2.16,
"isPrimary": true,
"available": -0.29,
"overdraft": 0,
"currencyCode": 826,
"friendlyName": "Primary Account"
}

Account Transactions

Retrieve all transactions for a given timeframe.

For the SubTypeIds parameter, please see our documentation for a list of possible values.

This API call uses OAuth2 authentication.

Please note: The Account Transactions API requires specific access credentials. To request access, please speak to your sales representative

Authorizations:

OAuth2 (urn:viva:payments:biservices:datafileapi)

query Parameters

PageSize	string Example: PageSize=500 Maximum value = 500
Page	string Example: Page=1 Should be set to `1` and increased by one until a "204 (No content)" message is received
OrderBy	string Example: OrderBy=Descending Order the results by either ascending or descending

header Parameters

Content-Type

required

string

Default: application/json

Request Body schema: application/json

DateFrom required	string <datetime> Start date of search.
DateTo required	string <datetime> End date of search.
WalletId	integer The ID of the wallet.
SubTypeIds	array of strings The 'subtype' of the transaction.
AmountFrom	integer Minimum amount to search.
AmountTo	integer Maximum amount to search.

Responses

200

Success

204

No Content

404

Not Found

5xx

Internal Server Error

post /dataservices/v2/accounttransactions/Search

Sandbox environment

https://demo-api.vivapayments.com/dataservices/v2/accounttransactions/Search

Live environment

https://api.vivapayments.com/dataservices/v2/accounttransactions/Search

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"DateFrom": "2018-01-20 13:45:03.5200000 +02:00",
"DateTo": "2024-04-27 13:45:03.5200000 +02:00",
"WalletId": 932498539354,
"SubTypeIds": 
[22,
25,
30
],
"AmountFrom": 0,
"AmountTo": 2000
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"accountTransactionId": "2353af54-b897-4ac3-93b0-f374ab643572",
"created": "2023-06-06T14:21:09.487+03:00",
"personId": "201ae961-9515-4ea4-93e4-5faf7c6a1211",
"walletId": 211878332234,
"typeId": 20,
"subTypeId": 13,
"amount": 5.2,
"currencyCode": 978,
"targetAmount": 14.8,
"targetAvailable": 14.8,
"valueDate": null,
"isAuthorization": false,
"counterPart": null,
"userDescription": null,
"tag": null
}

Bank Account

Link bank account

Use this API Call to link a bank account. There is no need to use a separate API to confirm the IBAN is valid, as this API will also validate the IBAN account.

The IBAN should belong to a bank account set up in the same currency as your Viva merchant account.

This API call uses OAuth2 authentication. Please use your 'Account Transactions Credentials' for this functionality.

You may find below test IBANs for your tests in demo environment.

IBAN	Country
BE22679200300047	Belgium
AT483200000012345864	Austria
BG18RZBB91550123456789	Bulgaria
HR1723600001101234565	Croatia
CY21002001950000357001234567	Cyprus
CZ5508000000001234567899	Czech Republic
DK9520000123456789	Denmark
FI1410093000123458	Finland
FR7630006000011234567890189	France
DE75512108001245126199	Germany
HU93116000060000000012345676	Hungary
IE64IRCE92050112345678	Ireland
IT60X0542811101000000123456	Italy
LU120010001234567891	Luxembourg
MT31MALT01100000000000000000123	Malta
NL02ABNA0123456789	Netherlands
PL10105000997603123456789123	Poland
ES7921000813610123456789	Spain
SE7280000810340009783242	Sweden
GR9608100010000001234567890	Greece
GB94BARC10201530093459	Greece
GR1601101250000000012300695	Greece
GR0901747473523851736771797	Greece
GR4101137398743417343263193	Greece
GB78BARC20037839364893	United Kingdom
GB93BARC20040487725456	United Kingdom

Authorizations:

OAuth2 (urn:viva:payments:core:api:banktransfers)

Request Body schema: applications/json

iban required	string <uuid> The IBAN of the bank account to link to.
friendlyName	string <uuid> A friendly name of your choosing.
beneficiaryName	string <uuid> A beneficiary name of your choosing.

Responses

200

401

Unauthorized

409

Conflict - The bank account already exists.

5xx

Internal Server Error

post /banktransfers/v1/bankaccounts

Sandbox environment

https://demo-api.vivapayments.com/banktransfers/v1/bankaccounts

Live environment

https://api.vivapayments.com/banktransfers/v1/bankaccounts

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

applications/json

Copy

Expand all Collapse all


{"iban": "GB94BARC10201530093459",
"friendlyName": "This is the IBAN of the Greek partner.",
"beneficiaryName": "Greek IBAN."
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"bankAccountId": "fa176a3b-a7e8-4f3d-abe6-5e65626f5994",
"isVivaIban": true
}

Retrieve bank accounts

Use this API Call to retrieve all the details for the linked bank accounts which are set up under your Viva profile.

It is optional to set one of the filters described in Query parameters below.

This API call uses OAuth2 authentication. Please use your 'Account Transactions Credentials' for this functionality.

Authorizations:

OAuth2 (urn:viva:payments:core:api:banktransfers)

query Parameters

skip	integer <int32> Example: skip=1 Skip number of bank accounts.
maxResults	integer <int32> Example: maxResults=20 Number of rows to fetch.
iban	string Example: iban=GB94BARC10201530093459 The iban of the bank account.
isArchived	boolean Example: isArchived=false Option to get archived bank accounts.
bankAccountId	string <uuid> Example: bankAccountId=eb6a54e5-283d-4c0c-8c60-64f66dad2d8f The id of the linked bank account.

Responses

200

401

Unauthorized

5xx

Internal Server Error

get /banktransfers/v1/bankaccounts

Sandbox environment

https://demo-api.vivapayments.com/banktransfers/v1/bankaccounts

Live environment

https://api.vivapayments.com/banktransfers/v1/bankaccounts

Request samples

cURL
PHP
NodeJs
Java

Copy

curl --location 'https://demo-api.vivapayments.com/banktransfers/v1/bankaccounts?skip=1&maxResults=20&iban=GB94BARC10201530093459&isArchived=false&bankAccountId=eb6a54e5-283d-4c0c-8c60-64f66dad2d8f' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {Bearer_Token}' \
--data ''

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"iban": "string",
"bankId": "string",
"isArchived": true,
"swiftCode": "string",
"bankAccountId": "857cad57-f84d-4640-96ab-56e428c16016",
"friendlyName": "string",
"beneficiaryName": "string",
"isVivaIban": true
}

Retrieve bank account by id

Use this API Call to retrieve all the details for a specific linked bank account set up under your Viva profile.

This API call uses OAuth2 authentication. Please use your 'Account Transactions Credentials' for this functionality.

Authorizations:

OAuth2 (urn:viva:payments:core:api:banktransfers)

path Parameters

bankAccountId

required

string <uuid>

Example: 94535158-514b-41df-9bc7-34c6791044d2

The id of the linked bank account.

Responses

200

401

Unauthorized

5xx

Internal Server Error

get /banktransfers/v1/bankaccounts/{bankAccountId}

Sandbox environment

https://demo-api.vivapayments.com/banktransfers/v1/bankaccounts/{bankAccountId}

Live environment

https://api.vivapayments.com/banktransfers/v1/bankaccounts/{bankAccountId}

Request samples

cURL
PHP
NodeJs
Java

Copy

curl --location 'https://demo-api.vivapayments.com/banktransfers/v1/bankaccounts/:bankAccountId' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {Bearer_Token}' \
--data ''

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"iban": "string",
"bankId": "string",
"isArchived": true,
"swiftCode": "string",
"bankAccountId": "857cad57-f84d-4640-96ab-56e428c16016",
"friendlyName": "string",
"beneficiaryName": "string",
"isVivaIban": true
}

Update bank account

Use this API Call to update the status of a specific bank account id.

This API call uses OAuth2 authentication. Please use your 'Account Transactions Credentials' for this functionality.

Authorizations:

OAuth2 (urn:viva:payments:core:api:banktransfers)

path Parameters

bankAccountId

required

string <uuid>

Example: eb6a54e5-283d-4c0c-8c60-64f66dad2d8f

The id of the linked bank account.

Request Body schema: application/json

archive required	boolean The desired bank account status.
friendlyName	string A desired friendly name of your choosing.
beneficiaryName	string A desired beneficiary name of your choosing.

Responses

200

401

Unauthorized

5xx

Internal Server Error

patch /banktransfers/v1/bankaccounts/{bankAccountId}

Sandbox environment

https://demo-api.vivapayments.com/banktransfers/v1/bankaccounts/{bankAccountId}

Live environment

https://api.vivapayments.com/banktransfers/v1/bankaccounts/{bankAccountId}

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"archive": true,
"friendlyName": "My favourite Greek Bank Account",
"beneficiaryName": "George Seferis"
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"archive": true,
"friendlyName": "My favourite Greek Bank Account",
"beneficiaryName": "George Seferis"
}

Retrieve bank transfer options

Before making any outgoing bank transfer, you should use this API Call:

- to retrieve the cost options available, i.e. shared or ours.
- to identify if the targeted linked bank account supports instant transfer(s).

👉 OUR (ours) instruction means you pay all transfer charges. SHA (shared) means you only pay your bank’s outgoing transfer charge. 👈

Please note: this API call is intended for external IBANs only.

It should therefore not be used if referring to a linked IBAN that is in fact an IBAN within Viva (meaning that it is essentially a wallet).

This API call uses OAuth2 authentication. Please use your 'Account Transactions Credentials' for this functionality.

Authorizations:

OAuth2 (urn:viva:payments:core:api:banktransfers)

path Parameters

bankAccountId

required

string <uuid>

Example: 532a2b8a-a74e-472a-af2d-a578f2b6bf6c

The id of the linked bank account.

query Parameters

amount

required

integer <int64>

The amount of the requested outgoing bank transfer.

Responses

200

401

Unauthorized

5xx

Internal Server Error

get /banktransfers/v1/bankaccounts/{bankAccountId}/instructiontypes

Sandbox environment

https://demo-api.vivapayments.com/banktransfers/v1/bankaccounts/{bankAccountId}/instructiontypes

Live environment

https://api.vivapayments.com/banktransfers/v1/bankaccounts/{bankAccountId}/instructiontypes

Request samples

cURL
PHP
NodeJs
Java

Copy

curl --location 'https://demo-api.vivapayments.com/banktransfers/v1/bankaccounts/:bankAccountId/instructiontypes?amount=xxxx' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {Bearer_Token}' \
--data ''

Response samples

Content type

application/json

Copy

Expand all Collapse all


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

Create bank transfer fee command

Use this API Call to specify the transfer options and/or be informed of the fee associated with the bank transfer.

This API call uses OAuth2 authentication. Please use your 'Account Transactions Credentials' for this functionality.

Authorizations:

OAuth2 (urn:viva:payments:core:api:banktransfers)

path Parameters

bankAccountId

required

string <uuid>

Example: 532a2b8a-a74e-472a-af2d-a578f2b6bf6c

The id of the linked bank account.

Request Body schema: applications/json

amount required	integer <int64> The amount of the requested outgoing bank transfer.
walletId required	integer <int64> The wallet id from which the amount will be transferred.
isInstant	boolean Default: false Indicates if the outgoing bank transfer will be instant or not.
instructionType required	Array of integers (bankTransferInstructionTypeId) Indicates the instruction type for this bank transfer. You may find below all the possible values. Enum: `"1"` `"2"` 1 = Shared 2 = Ours The OUR instruction means you pay all transfer charges. SHA (shared) means you only pay your bank's outgoing transfer charge.

Responses

200

401

Unauthorized

5xx

Internal Server Error

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

Sandbox environment

https://demo-api.vivapayments.com/banktransfers/v1/bankaccounts/{bankAccountId}/fees

Live environment

https://api.vivapayments.com/banktransfers/v1/bankaccounts/{bankAccountId}/fees

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

applications/json

Copy

Expand all Collapse all


{"amount": 0,
"walletId": 0,
"isInstant": false,
"instructionType": 1
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"fee": 0.1,
"isInstant": true,
"bankCommandId": "bd7e9099-6431-414f-800d-0f583aa556ba",
"instructionType": 1
}

Execute bank transfer

Use this API Call to execute a bank transfer.

This API call uses OAuth2 authentication. Please use your 'Account Transactions Credentials' for this functionality.

Authorizations:

OAuth2 (urn:viva:payments:core:api:banktransfers)

path Parameters

bankAccountId

required

string <uuid>

Example: 532a2b8a-a74e-472a-af2d-a578f2b6bf6c

The id of the linked bank account.

Request Body schema: applications/json

amount required	integer <int64> The amount of the requested outgoing bank transfer.
walletId required	integer <int64> The wallet id from which the amount will be transferred.
description	string Specify a description for this outgoing bank transfer.
bankCommandId	string <uuid> Specify the id of the bank transfer fee command, which is associated with specific: fee, instruction type, and instant flag. If you don't specify the `bankCommandId` parameter value, then a new `bankCommandId` will be created internally with `instructionType = 1` (Shared) and `isInstant = false`.

Responses

200

401

Unauthorized

452

Insufficient funds

5xx

Internal Server Error

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

Sandbox environment

https://demo-api.vivapayments.com/banktransfers/v1/bankaccounts/{bankAccountId}:send

Live environment

https://api.vivapayments.com/banktransfers/v1/bankaccounts/{bankAccountId}:send

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

applications/json

Copy

Expand all Collapse all


{"amount": 0,
"walletId": 0,
"description": "Bank transfer to George Seferis",
"bankCommandId": "39e6208c-a53d-4b7b-b085-2444178c0887"
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"fee": 0.8,
"commandId": "9e2dd63c-3478-489f-86d3-8c292a65a0aa",
"isInstant": true,
"walletTransactionId": "1e1fa555-eb0d-4fa3-a623-57d49e0eb53b"
}

Sources

Add a new source

This API call enables you to add a new payment source to your Viva account. Payment sources allow you to group your sales into meaningful groups. You can manage them through the Viva Banking app. Sign in and navigate to Sales > Online Payments > Websites/Apps for e-commerce transaction sources or Sales > Physical Payments > Stores for card-present (in-person) transaction sources.

This API call uses Basic authentication.

This API call can generate source codes for both e-commerce and in-person payments. Each source type can be created separately by providing the relevant parameters for either e-commerce or in-person payments.

Authorizations:

BasicAuth (See BasicAuth)

header Parameters

Content-Type

required

string

Default: application/json

Request Body schema: application/json

domain	string The primary domain of your site. You should not enter protocol information (http/https) or paths. Note: This parameter is mandatory only if the source is for `e-commerce`.
isSecure	boolean `True` indicates that your site's protocol is HTTPS. Note: This parameter is mandatory only if the source is for `e-commerce`.
name required	string A meaningful name that will help you identify the source in the Web Self Care environment.
pathFail	string The relative URL path that your client will end up at after a failed transaction. Note: This parameter is mandatory only if the source is for `e-commerce`.
pathSuccess	string The relative URL path that your client will end up at after a successful transaction. Note: This parameter is mandatory only if the source is for `e-commerce`.
sourceCode required	string A unique code that is exchanged between your application and the API.
phone	string <= 30 A phone contact number. Used only for card-present transactions. Note: This parameter is mandatory only if the source is for `card-present transactions`.
address	string <= 512 The address where the softPOS/card terminal will be located. Used only for card-present transactions. Note: This parameter is mandatory only if the source is for `card-present transactions`.
walletId	integer The wallet ID with which the source will be linked. Used only for card-present transactions. Note: This parameter is mandatory only if the source is for `card-present transactions`.
isPhysical	boolean If the source is associated with in-person payments, this value should always be `true`. Used only for card-present transactions. Note: This parameter is mandatory only if the source is for `card-present transactions`.
latitude	decimal The latitude of the softPOS/card terminal location. Used only for card-present transactions. Note: This parameter is mandatory only if the source is for `card-present transactions`.
longitude	decimal The longitude of the softPOS/card terminal location. Used only for card-present transactions. Note: This parameter is mandatory only if the source is for `card-present transactions`.
transactionDescriptor	string <= 22 A description displayed on the cardholder's bank statement. Used only for card-present transactions. For more information, please see the Dynamic Descriptor feature . Note: This parameter is mandatory only if the source is for `card-present transactions`.

Responses

200

Success

400

Fail - Bad syntax; domain may be formatted incorrectly

401

Unauthorized

409

Fail - Source already exists with this source code

5xx

Internal Server Error

post /api/sources

Sandbox environment

https://demo.vivapayments.com/api/sources

Live environment

https://www.vivapayments.com/api/sources

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"domain": "www.example.com",
"isSecure": true,
"name": "API test",
"pathFail": "fail",
"pathSuccess": "success",
"sourceCode": "1234",
"phone": "2102312111",
"address": "Amarousiou Chalandriou 18-20",
"walletId": 100000000000,
"isPhysical": true,
"latitude": 38.0425,
"longitude": 23.8086,
"transactionDescriptor": "my store coffee"
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"Message": "Success - There is no response body. Only the response status denotes successful completion of the request."
}

Marketplace Sellers

Create a connected account

Create a connected account.

By providing at least the email of the seller, the URL that the seller will be redirected to upon completing the onboarding process and the partner name & logo URL of the marketplace, you generate the account id of the seller along with the invitation url to send to the seller to initiate the onboarding process.

Optionally, you may provide additional details of the seller, such as business information of the seller (e.g. legal name), branding information to be displayed during the onboarding process of the seller (e.g. the color), and payout information (e.g. the bank account where the seller wishes to receive their payouts)

Note: During the onboarding process, the seller has the ability to change the following details: mobile, legalName, tradeName, taxNumber & address. Therefore, they could potentially override the values provided during the creation of the invitation by the marketplace owner This API call uses OAuth2 authentication.

Authorizations:

OAuth2 (

urn:viva:payments:core:api:acquiring urn:viva:payments:core:api:acquiring:cardtokenization urn:viva:payments:core:api:acquiring:transactions urn:viva:payments:core:api:platform urn:viva:payments:core:api:redirectcheckout

)

Request Body schema: application/json

email required	string Email address. The same email address can be used to create multiple connected accounts.
mobile	string Mobile number
legalName	string Company's legal name
tradeName	string Company's trade name
taxNumber	string Company's tax number
returnUrl required	string The URL that the seller will be redirected to upon completing the onboarding process
address	object Company's address
branding required	object Branding information of the marketplace
payouts	object To be used for sellers that wish to automatically receive their payouts to a 3rd party bank account outside Viva according to a defined interval (leave empty for manual handling of payouts)

Responses

200

Success

401

Unauthorized

412

Precondition Failed

5xx

Internal Server Error

post /platforms/v1/accounts

Sandbox environment

https://demo-api.vivapayments.com/platforms/v1/accounts

Live environment

https://api.vivapayments.com/platforms/v1/accounts

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"email": "user@example.com",
"mobile": 6948740000,
"legalName": "Consulting Detective",
"tradeName": "Sherlock Holmes",
"taxNumber": null,
"returnUrl": "https://example.com/connected",
"address": 
{"street": "Baker Street",
"number": "221B",
"city": "London",
"postCode": "NW1",
"countryCode": "GB",
"secondLine": null
},
"branding": 
{"partnerName": "Header/title summary",
"primaryColor": null,
"logoUrl": "https://example.com/company-logo"
},
"payouts": 
{"statementDescriptor": "Weekly payouts",
"dayOfWeek": 1,
"dayOfMonth": null,
"interval": 2,
"amountThreshold": 1000,
"disable": false,
"bankAccount": 
{"iban": "NL04RABO6360804956",
"friendlyName": "External account",
"beneficiaryName": "Sherlock Holmes",
"branchCode": null,
"accountNumber": null,
"countryCode": null
}
}
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"accountId": "fa176a3b-a7e8-4f3d-abe6-5e65626f5994",
"invitation": 
{"email": "user@example.com",
"redirectUrl": "https://example.com/onboardingflow",
"created": "2025-04-16T07:41:14.506Z"
}
}

Retrieve information about a connected account

Retrieve information about a connected account.

By providing the account id of the seller, you retrieve information about the seller, such as email of the seller, payout information (e.g. the bank account where the seller wishes to receive their payouts), the invitation details (e.g. the invitation url to send to the seller to initiate the onboarding process), as well as whether the seller is verified and whether they can accept payments.

Note: the verified and acquiringEnabled parameters refer to the Viva account (normally the connected account of the seller). It is possible for verified to equal true whilst acquiringEnabled equals false. As such, the marketplace owner must confirm that both flags are true in order to ensure the seller is active on the marketplace

This API call uses OAuth2 authentication.

Authorizations:

OAuth2 (

urn:viva:payments:core:api:acquiring urn:viva:payments:core:api:acquiring:cardtokenization urn:viva:payments:core:api:acquiring:transactions urn:viva:payments:core:api:platform urn:viva:payments:core:api:redirectcheckout

)

path Parameters

accountId

required

string

Example: 93fddb89-a9de-4328-a06e-d99dc9719c01

The id of the connected account

Responses

200

Success

401

Unauthorized

5xx

Internal Server Error

get /platforms/v1/accounts/{accountId}

Sandbox environment

https://demo-api.vivapayments.com/platforms/v1/accounts/{accountId}

Live environment

https://api.vivapayments.com/platforms/v1/accounts/{accountId}

Request samples

cURL
PHP
NodeJs
Java

Copy

curl --location -g 'https://demo-api.vivapayments.com/platforms/v1/accounts/{accountId}'

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"accountId": "3d07c219-0a88-45be-9cfc-91e9d095a1e9",
"email": "user@example.com",
"payouts": 
{"statementDescriptor": "Weekly payouts '#MP12385'",
"dayOfWeek": 1,
"dayOfMonth": null,
"interval": 2,
"amountThreshold": 1000,
"disable": false,
"bankAccount": 
{"iban": "NL04RABO6360804956",
"friendlyName": "External account",
"beneficiaryName": "Sherlock Holmes",
"branchCode": null,
"accountNumber": null,
"countryCode": null
}
},
"verified": true,
"acquiringEnabled": true,
"created": "2025-04-16T07:41:14.506Z",
"invitation": 
{"email": "user@example.com",
"redirectUrl": "https://example.com/onboardingflow",
"created": "2025-04-16T07:41:14.506Z"
}
}

Update connected account attributes

Update the payouts information of a connected account. Change the statement descriptor, schedule or target external account.

This API call uses OAuth2 authentication.

Authorizations:

OAuth2 (

urn:viva:payments:core:api:acquiring urn:viva:payments:core:api:acquiring:cardtokenization urn:viva:payments:core:api:acquiring:transactions urn:viva:payments:core:api:platform urn:viva:payments:core:api:redirectcheckout

)

path Parameters

accountId

required

string

Example: 93fddb89-a9de-4328-a06e-d99dc9719c01

The id of the connected account

Request Body schema: application/json

payouts

object

To be used for sellers with full Viva accounts (leave empty for manual handling of payouts)

Responses

204

Success

401

Unauthorized

5xx

Internal Server Error

patch /platforms/v1/accounts/{accountId}

Sandbox environment

https://demo-api.vivapayments.com/platforms/v1/accounts/{accountId}

Live environment

https://api.vivapayments.com/platforms/v1/accounts/{accountId}

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"payouts": 
{"statementDescriptor": "Weekly payouts",
"dayOfWeek": 1,
"dayOfMonth": null,
"interval": 2,
"amountThreshold": 1000,
"disable": false,
"bankAccount": 
{"iban": "NL04RABO6360804956",
"friendlyName": "External account",
"beneficiaryName": "Sherlock Holmes",
"branchCode": null,
"accountNumber": null,
"countryCode": null
}
}
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"Message": "Success."
}

Marketplace Payments

Create payment order

Create a payment order to accept a payment from an end customer.

Important note: if you are using the transfer parameter, this call will fail in the following circumstances:

The connected account is not verified (you can use the Retrieve information about a connected account API call to check that the verified flag of the seller is true)

The order is a Preauth (preauth = true)

The order utilises Installments (maxInstallments =/= 0)

The order is Recurring (allowRecurring = true)

The order has an open amount (enacted via the disableExactAmount parameter)

The order has a disabled paid state (enacted via the disablePaidState parameter of the Update an order API call)

The order is a card verification (isCardVerification = true)

Note: for non-Marketplace orders, please see our standard Create Payment Order API call

This API call uses OAuth2 authentication.

Authorizations:

OAuth2 (

urn:viva:payments:core:api:acquiring urn:viva:payments:core:api:acquiring:cardtokenization urn:viva:payments:core:api:acquiring:transactions urn:viva:payments:core:api:platform urn:viva:payments:core:api:redirectcheckout

)

Request Body schema: application/json

amount required	integer Default: 0 The exact amount to be paid. Must be a positive, non-zero number. The amount will be in the currency of the merchant account using the currency's smallest unit of measurement (e.g. cents of a euro).
preauth	boolean Default: false Specify if the card sale will be a preauthorization. Applies only to payments with card
tipAmount	integer Default: null Specify how much of the `amount` is to be marked as a tip. This value is not added to the `amount`
dynamicDescriptor	string <= 13 A descriptor tailored to the transaction, ensuring clarity and recognition for the buyer on their bank statement and 3DS verification page. This parameter generates a dynamic descriptor for bank statements when processing a payment through smart checkout. The descriptor is limited to no more than 13 characters, can contain only `Latin characters`, `numbers`, and `space`. Special characters are replaced by spaces to meet banking standards. When specified, the buyer will see the first 8 characters of the merchant's trade name, followed by a space, and up to 13 characters of the dynamic descriptor. For example: `MerchantX Descriptor`. If not specified, the merchant's trade name will be shown up to 22 charachters. The `dynamicDescriptor` is included in the following webhooks with the `Descriptor` parameter. - Transaction Payment Created - Transaction Failed - Transaction Reversal Created
disableCash	boolean Default: false Disable cash payment for this order
tags	array of string Default: null Tags to be added, if desired
sourceCode	string Default: null The payment source to be linked with the transaction on successful payment. If left unspecified then the Default payment source is used
disableWallet	boolean Default: false Disable payment with wallet for this order
paymentTimeout	integer Default: 1800 Defines the timespan in seconds that the created order can be fulfilled before it expires. The default value is 1800 seconds (30 minutes)
customerTrns	string Default: null This custom value will be displayed in the customer's platform
merchantTrns	string Default: null This custom value can be used by the merchant as a reference
allowRecurring	boolean Default: false Specify if the transaction created can be further used to initiate new transactions. Applies mainly to orders fulfilled with cards
maxInstallments	integer Default: 0 Maximum number of installments to be allowed
disableExactAmount	boolean Default: false Specify if the amount to be paid can be changed (true) or remains fixed (default value)
paymentNotification	boolean Default: false Dictates whether a payment notification should be sent
customer	object Information about the customer
cardTokens	array of strings Default: null You can provide the card tokens you have saved on your backend for this customer. The card tokens will then be presented to the customer on Smart Checkout to pay with
isCardVerification	boolean Default: false This parameter should be set to `true` to trigger a verification using Card Verification functionality (and the `amount` parameter should be set to '0'). Please note: This is currently only available for card payments via Visa, Mastercard, Maestro, Diners Club & Discover (digital wallets are not supported) Recurring payments are supported This is not available with the ISV schema The following parameters are also not compatible with Card Verification: `preauth`, `maxInstallments`/`forceMaxInstallments`, `disableExactAmount`, `tipAmount`, `cardTokens`
transfer	object Denotes whether an automatic transfer will be performed upon settlement of the payment. If `amount` is used, the process will be as follows: 1. Transaction funds (the amount of the payment order) settled to platform account 2. Funds transferred to seller account (the amount of the `amount` parameter) 3. Viva acquiring commission applied for the transaction and deducted from the platform account 4. Funds can be transferred to marketplace owner account as needed (manually via Send funds to a connected account API) If `platformFee` is used, the process will be as follows: 1. Transaction funds (the amount of the payment order) settled to platform account 2. Funds transferred to seller account (the amount of the payment order) 3. Fees transferred from seller account back to platform account (the amount of the `platformFee` parameter) 4. Viva acquiring commission applied for the transaction and deducted from the platform account 5. Funds can be transferred to marketplace owner account as needed (manually via Send funds to a connected account API) If both `amount` and `platformFee` are used (for cases in which the marketplace is both a marketplace and a seller), the process will be as follows: 1. Transaction funds (the amount of the payment order) settled to platform account 2. Funds transferred to seller 1 account (the amount of the payment order minus the Marketplace Owner's cut as specified by the `amount` parameter) 3. Fees transferred from seller 1 account back to platform account (the amount of the `platformFee` parameter) 4. Viva acquiring commission applied for the transaction and deducted from the platform account 5. Remaining funds transferred to seller 2 (Marketplace Owner) account
nbgLoanOrderOptions	object Information about the NBG Loan.
klarnaOrderOptions	object <array of objects> These parameters are required when Klarna is being offered as a payment method.

Responses

200

Success

400

Bad Request

401

Unauthorized

5xx

Internal Server Error

post /checkout/v2/orders/

Sandbox environment

https://demo-api.vivapayments.com/checkout/v2/orders/

Live environment

https://api.vivapayments.com/checkout/v2/orders/

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"amount": 0,
"preauth": false,
"tipAmount": null,
"dynamicDescriptor": "Descriptor",
"disableCash": false,
"tags": null,
"sourceCode": null,
"disableWallet": false,
"paymentTimeout": 1800,
"customerTrns": null,
"merchantTrns": null,
"allowRecurring": false,
"maxInstallments": 0,
"disableExactAmount": false,
"paymentNotification": false,
"customer": 
{"email": "example@example.com",
"phone": "01234567890",
"fullName": "John Doe",
"countryCode": "GB",
"requestLang": null
},
"cardTokens": 
["ct_5d0a4e3a7e04469f82da228ca98fd661"
],
"isCardVerification": false,
"transfer": 
{"amount": 1000,
"platformFee": null,
"connectedAccountId": "ac03972a-5ca5-43c5-b96f-c519ac843b7a"
},
"nbgLoanOrderOptions": 
{"Code": null,
"ReceiptType": null
},
"klarnaOrderOptions": 
{"attachment": 
{"body": "string",
"contentType": "string"
},
"billingAddress": 
{"city": "string",
"email": "string",
"phone": "string",
"title": "string",
"region": "string",
"country": "string",
"attention": "string",
"givenName": "string",
"familyName": "string",
"postalCode": "string",
"streetAddress": "string",
"streetAddress2": "string",
"organizationName": "string"
},
"shippingAddress": 
{"city": "string",
"email": "string",
"phone": "string",
"title": "string",
"region": "string",
"country": "string",
"attention": "string",
"givenName": "string",
"familyName": "string",
"postalCode": "string",
"streetAddress": "string",
"streetAddress2": "string",
"organizationName": "string"
},
"orderLines": 
{"name": "string",
"type": "string",
"taxRate": 0,
"quantity": 0,
"unitPrice": 0,
"imageUrl": "string",
"reference": "string",
"totalAmount": 0,
"productUrl": "string",
"merchantData": "string",
"quantityUnit": "string",
"totalTaxAmount": 0,
"totalDiscountAmount": 0,
"subscription": 
{"name": "string",
"interval": "string",
"intervalCount": 0
},
"productIdentifiers": 
{"size": "string",
"brand": "string",
"color": "string",
"categoryPath": "string",
"globalTradeItemNumber": "string",
"manufacturerPartNumber": "string"
}
}
}
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"orderCode": 1234567890123456
}

Marketplace Transfers

Send funds to a connected account

Send funds to a connected account, with or without linking the transfer to an existing transactionId. If transferring to the marketplace owner, transactionId should be left empty.

Note: this call will fail in the following circumstances:

The connected account is not verified (you can use the Retrieve information about a connected account API call to check that the verified flag of the seller is true)

The referenced transaction is a Preauth (preauth = true) - although Preauth Capture transactions are supported

The referenced transaction utilises Installments (maxInstallments =/= 0)

The referenced transaction is marked as 'switching' (you can use our Transaction Payment Created webhook to check if the Switching parameter is true - if so, you could send funds without referencing the transaction)

The referenced transaction is a refund

The referenced transaction has been partially refunded (i.e. its TransactionStatus is 'R')

This API call uses OAuth2 authentication.

Authorizations:

OAuth2 (

urn:viva:payments:core:api:acquiring urn:viva:payments:core:api:acquiring:cardtokenization urn:viva:payments:core:api:acquiring:transactions urn:viva:payments:core:api:platform urn:viva:payments:core:api:redirectcheckout

)

Request Body schema: application/json

amount required	integer Amount to be sent. Must be a positive, non-zero number. The amount will be in the currency of the merchant account using the currency's smallest unit of measurement (e.g. cents of a euro).
connectedAccountId required	string ID of the connected account
description	string <= 1024 Default: "Amount Settlement from Platform" A decription that can be set, as identification key, by the platform marketplace during sending funds to a connected account id.
transactionId	string Default: null Denotes the transaction (i.e. customer payment) associated with this transfer. If left empty or if the transaction is already settled, an instant balance transfer will be made and the `executed` parameter in the response will have a value (the account must have enough balance to complete the transfer). If the transaction is not yet settled, the transfer will be handled during settlement and the `executed` parameter in the response will not have a value.

Responses

200

Success

401

Unauthorized

403

Invalid Transfer Amount

452

Insufficient Funds

5xx

Internal Server Error

post /platforms/v1/transfers

Sandbox environment

https://demo-api.vivapayments.com/platforms/v1/transfers

Live environment

https://api.vivapayments.com/platforms/v1/transfers

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"amount": null,
"connectedAccountId": "ac03972a-5ca5-43c5-b96f-c519ac843b7a",
"description": "This is a description for sending funds to a connected account",
"transactionId": null
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"transferId": "fa176a3b-a7e8-4f3d-abe6-5e65626f5994",
"executed": "2025-04-16T07:41:14.506Z"
}

Create a transfer reversal

Reverse a transfer made to a connected account.

Note: if the referenced transfer has not yet been executed, the reversal will wait for this to be executed first. Otherwise, the reversal will be instant

Note: if the referenced transfer has already been executed, and the seller has insufficient funds to complete the reversal, the reversal will fail instantly with Status Code 452

This API call uses OAuth2 authentication.

Authorizations:

OAuth2 (

urn:viva:payments:core:api:acquiring urn:viva:payments:core:api:acquiring:cardtokenization urn:viva:payments:core:api:acquiring:transactions urn:viva:payments:core:api:platform urn:viva:payments:core:api:redirectcheckout

)

path Parameters

transferId

required

string

Example: 93fddb89-a9de-4328-a06e-d99dc9719c01

The id of the transfer that will be reversed. If the transfer has not yet been executed, this will be handled during settlement.

Request Body schema: application/json

amount

integer

Default: null

Amount to be reversed. Set as null to reverse the full amount.
Must be a positive, non-zero number.
The amount will be in the currency of the merchant account using the currency's smallest unit of measurement (e.g. cents of a euro).

Responses

200

Success

401

Unauthorized

452

Insufficient Funds

5xx

Internal Server Error

post /platforms/v1/transfers/{transferId}:reverse

Sandbox environment

https://demo-api.vivapayments.com/platforms/v1/transfers/{transferId}:reverse

Live environment

https://api.vivapayments.com/platforms/v1/transfers/{transferId}:reverse

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"amount": null
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"transferId": "fa176a3b-a7e8-4f3d-abe6-5e65626f5994",
"executed": "2025-04-16T07:41:14.506Z"
}

Marketplace Transactions

Cancel transaction

Cancel a transaction. Perform a refund towards an end customer.

Note: if you refund the platform fee (using refundPlatformFee), you must also reverse the transfer (with reverseTransfers)

Note: if a transfer triggered by the use of reverseTransfers and/or refundPlatformFee fails, then the entire call will fail

This API call uses OAuth2 authentication.

Authorizations:

OAuth2 (

urn:viva:payments:core:api:acquiring urn:viva:payments:core:api:acquiring:cardtokenization urn:viva:payments:core:api:acquiring:transactions urn:viva:payments:core:api:platform urn:viva:payments:core:api:redirectcheckout

)

path Parameters

transactionID

required

string

Example: 082886d5-6021-4ebe-bbe2-1a50e6bcc5b6

The Transaction Id of the transaction to cancel

query Parameters

amount required	integer Example: amount=0 The amount to cancel
sourceCode	string Example: sourceCode=1234 Source to use for transaction cancellation. Defaults to source code of parent transaction
merchantTrns	string Example: merchantTrns=1a2b3c4d An ID or a short description that helps you uniquely identify the transaction
idempotencyKey	string Example: idempotencyKey=ABC123DEF456 Specify a key in order for the call have idempotent behaviour for all calls with the same key
reverseTransfers	boolean Default: false Example: reverseTransfers=true Use this property to automatically return the funds back from the connected account to the platform account in order to cover the refund. When `reverseTransfers`=`true` for partial refunds, a proportional amount will be returned.
refundPlatformFee	boolean Default: false Example: refundPlatformFee=true Use this property to automatically return the platform fee to the connected account from the platform account. When `refundPlatformFee`=`true` for partial refunds, a proportional amount of the platfom fee wil be returned.

Responses

200

Success

401

Unauthorized

5xx

Internal Server Error

delete /acquiring/v1/transactions/{transactionID}

Sandbox environment

https://demo-api.vivapayments.com/acquiring/v1/transactions/{transactionID}

Live environment

https://api.vivapayments.com/acquiring/v1/transactions/{transactionID}

Request samples

cURL
PHP
NodeJs
Java

Copy

curl --location -g --request DELETE 'https://demo-api.vivapayments.com/acquiring/v1/transactions/{transactionID}?amount=null' \
--header 'Authorization: Bearer Bearer Token'

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"transactionId": "47398b8d-7933-4ed4-ba46-65171366e3df"
}

MOTO Card Charge

Make a MOTO card charge

Viva offers MOTO (Mail Order / Telephone Order) functionality, which gives merchants the ability to make charges without card presentment and without 3DS validation.

Note: MOTO functionality is not available for all merchants, and is offered on a case-by-case basis. Please speak to your sales representative or account manager (or reach out via our Live Chat functionality) if you are interested.

To make such a charge, the following three API Calls must be made:

1. Generate an OAuth2.0 Token
2. Create a Payment Order
3. Make the Card Charge (using this call)

This API call uses Basic authentication.

Authorizations:

BasicAuth (See BasicAuth)

Request Body schema: application/json

moto required	boolean This should always be `true`
merchantTrns	string Optional - an ID or a short description that helps you uniquely identify the transaction in the viva banking app
fullName	string The customer's full name
email	string The customer's email address (this is where the customer will receive their invoice)
phone	string The customer's phone number
creditcard required	object Information about the card to be charged
orderCode required	long The code of the payment order which is being charged
sourceCode	integer The code of the payment source to be used

Responses

200

Success

401

Unauthorized

404

Not Found

5xx

Internal Server Error

post /api/transactions

Sandbox environment

https://demo.vivapayments.com/api/transactions

Live environment

https://www.vivapayments.com/api/transactions

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"moto": true,
"merchantTrns": "Info for merchant",
"fullName": "John Doe",
"email": "john@example.com",
"phone": "306900000000",
"creditcard": 
{"cvc": "444",
"number": "5199816266546408",
"expirationDate": "2023-01"
},
"orderCode": 7909823376998902,
"sourceCode": 1234
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"Emv": null,
"Amount": 17.5,
"StatusId": "F",
"RedirectUrl": null,
"CurrencyCode": "826",
"TransactionId": "ef7786f9-b705-462b-9cd2-0fea4434aea4",
"ReferenceNumber": 337776,
"IssuerMessage": null,
"AuthorizationId": "399886",
"TransactionTypeId": 5,
"IssuerMessageControl": null,
"Ctap": null,
"ServiceId": null,
"RetrievalReferenceNumber": "322009088586",
"ApplePosInfo": 
{"PinToken": null
},
"Loyalty": null,
"CartesBancaires": null,
"ThreeDSecureStatusId": 2,
"ErrorCode": 0,
"ErrorText": null,
"TimeStamp": "2023-08-08T14:47:24.4493544+03:00",
"CorrelationId": null,
"EventId": 0,
"Success": true
}

MT940 API

Retrieve MT940 Data

This API allows you to retrieve MT940 report data for a given past date (MT940 data cannot be generated for the current date, as it only applies to cleared transactions).

Please note: The Data Services API requires specific access credentials. To request access, please speak to your sales representative

Authorizations:

OAuth2 (urn:viva:payments:biservices:datafileapi)

query Parameters

ReportDate

required

string <date>

Example: ReportDate=2023-04-30

Date for which MT940 data should be retrieved.

header Parameters

Authorization

required

string

The required identity Bearer token needed to access the resource.

Responses

200

Success

204

No Content (content was not found for the specified date)

500

Error (cannot generate data for the current date)

5xx

Error (incorrect/missing ReportDate or incorrect authorisation token)

get /dataservices/v2/merchants/mt940

Live environment

https://api.vivapayments.com/dataservices/v2/merchants/mt940

Request samples

cURL
PHP
NodeJs
Java

Copy

curl --location 'https://api.vivapayments.com/dataservices/v2/merchants/mt940?ReportDate=2023-04-30' \
--header 'Authorization: Bearer {Bearer_Token}'

Response samples

Content type

application/json

Copy

Expand all Collapse all

"{1:F01VPAYGRAA9272641}{2:O9499821VPAYGRAA0989N741}{4: :20:276657 :25:FR7624933233327453370009887 :28C:74/1 :60F:C345315EUR5,99 :62F:C345315EUR5,99 -}"

Webhooks API

Add subscription

The Webhooks API provides all the necessary tools to register on the webhooks service using event filters.

Register to webhooks by adding a new subscription. Limitations apply (one subscription per URL and event, limited total subscriptions).

Please note:
Webhook Subscriptions can currently only be made for the 'SaleTransactionsFileGenerated' event - see the Sale transactions File Request API

The Data Services API requires specific access credentials. To request access, please speak to your sales representative

Authorizations:

OAuth2 (urn:viva:payments:biservices:datafileapi)

header Parameters

Content-Type required	string Default: application/json
Authorization required	string The required identity Bearer token needed to access the resource.

Request Body schema: application/json

url required	string URL that will receive the webhook POST requests.
secret required	string This is a merchant-defined parameter, used to generate SHA-1 and SHA-256 signatures provided to webhook POST requests. The signatures (found within the header parameters of the resultant webhook) verify the sender (Viva) so webhook messages can be trusted.
events required	List<string> WebHook subscription events (i.e. SaleTransactionsFileGenerated).

Responses

200

Success

401

Unauthorized

5xx

Internal Server Error

post /dataservices/v1/webhooks/subscriptions

Live environment

https://api.vivapayments.com/dataservices/v1/webhooks/subscriptions

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"url": "https://www.myapi.com/webhooks/receive",
"secret": "N$45g@e6urE%367pP39*3b3Vh7$bZ122fmY4R_8tS%",
"events": 
["SaleTransactionsFileGenerated"
]
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"subscriptionId": "b17c1d56-d701-4b84-8c83-c67a5e5b187f"
}

Update subscription

Update webhooks subscription.

Authorizations:

OAuth2 (urn:viva:payments:biservices:datafileapi)

path Parameters

SubscriptionId

required

string

Example: b17c1d56-d701-4b84-8c83-c67a5e5b187f

The ID of the subscription.

header Parameters

Content-Type required	string Default: application/json
Authorization required	string The required identity Bearer token needed to access the resource.

Request Body schema: application/json

url required	string URL that will receive the webhook POST requests.
secret required	string This is a merchant-defined parameter, used to generate SHA-1 and SHA-256 signatures provided to webhook POST requests. The signatures (found within the header parameters of the resultant webhook) verify the sender (Viva) so webhook messages can be trusted.
events required	List<string> WebHook subscription events (i.e. SaleTransactionsFileGenerated).

Responses

200

Success

401

Unauthorized

5xx

Internal Server Error

put /dataservices/v1/webhooks/subscriptions/{SubscriptionId}

Live environment

https://api.vivapayments.com/dataservices/v1/webhooks/subscriptions/{SubscriptionId}

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"url": "https://www.myapi.com/webhooks/receive",
"secret": "N$45g@e6urE%367pP39*3b3Vh7$bZ122fmY4R_8tS%",
"events": 
["SaleTransactionsFileGenerated"
]
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"subscriptionId": "b17c1d56-d701-4b84-8c83-c67a5e5b187f"
}

Delete subscription

Delete webhooks subscription.

Authorizations:

OAuth2 (urn:viva:payments:biservices:datafileapi)

path Parameters

SubscriptionId

required

string

Example: b17c1d56-d701-4b84-8c83-c67a5e5b187f

The ID of the subscription.

header Parameters

Authorization

required

string

The required identity Bearer token needed to access the resource.

Responses

200

Success

401

Unauthorized

5xx

Internal Server Error

delete /dataservices/v1/webhooks/subscriptions/{SubscriptionID}

Live environment

https://api.vivapayments.com/dataservices/v1/webhooks/subscriptions/{SubscriptionID}

Request samples

cURL
PHP
NodeJs
Java

Copy

curl --location --request DELETE 'https://api.vivapayments.com/dataservices/v1/webhooks/subscriptions/53c6fd61-d885-4e07-afcc-e2c5814e673d' \
--header 'Authorization: Bearer {Bearer_Token}'

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"message": "Subscription deleted"
}

List subscriptions

List webhooks subscriptions.

Authorizations:

OAuth2 (urn:viva:payments:biservices:datafileapi)

header Parameters

Authorization

required

string

The required identity Bearer token needed to access the resource.

Responses

200

Success

401

Unauthorized

5xx

Internal Server Error

get /dataservices/v1/webhooks/subscriptions/

Live environment

https://api.vivapayments.com/dataservices/v1/webhooks/subscriptions/

Request samples

cURL
PHP
NodeJs
Java

Copy

curl --location 'https://api.vivapayments.com/dataservices/v1/webhooks/subscriptions' \
--header 'Authorization: Bearer {Bearer_Token}'

Response samples

Content type

application/json

Copy

Expand all Collapse all


[
{"subscriptionId": "930a9be8-6f2c-40e8-a351-2cf7770597d4",
"url": "http://merchant.url/path",
"events": 
["SaleTransactionsFileGenerated"
]
},
{"subscriptionId": "75fb06ba-fdee-4031-b3aa-704f3ec6cbd9",
"url": "http://merchant.url/path",
"events": 
["SaleTransactionsFileGenerated"
]
}
]

File Request API

Sale transactions

The File Requests API provides all the necessary tools in order to request a file generation.

Request the generation of a Sale Transactions file for a specific date. The data included in the resulting CSV file are from 00:00 - 23:59 of the date specified in the body of the request, based on the timezone of the country in which the merchant is registered.

Authorizations:

OAuth2 (urn:viva:payments:biservices:datafileapi)

header Parameters

Authorization required	string The required identity Bearer token needed to access the resource.
Content-Type required	string Default: application/json

Request Body schema: application/json

Id	string <uuid> Request identifier. If not provided, a new identifier will be generated.
Date required	date Date of sale transaction records.
FileType	string File extension of requested file (currently only csv is supported). If not provided, file will be generated in default file type (csv).

Responses

200

Success

401

Unauthorized

5xx

Internal Server Error

post /dataservices/v1/transactions/exports

Live environment

https://api.vivapayments.com/dataservices/v1/transactions/exports

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"Id": "dac40e4b-0369-407e-b52b-a2172f408ffa",
"Date": "2021-10-20",
"FileType": "csv"
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"requestId": "dac40e4b-0369-407e-b52b-a2172f408ffa"
}

WebHook SaleTransactions

Once a file generation request is received and the file is ready, a webhook is sent sent via POST request to the provided URL of the subscription.

header Parameters

User-Agent	string Default: “Viva-Hookshot/1.0” Constant value
Viva-Signature	string Contains the HMAC hex digest of the request body, and is generated using the SHA-1 hash function and the secret (provided when adding or updating a subscription) as the HMAC key.
Viva-Signature-256	string Contains the HMAC hex digest of the request body, and is generated using the SHA-256 hash function and the secret (provided when adding or updating a subscription) as the HMAC key.
Viva-Delivery-Id	string <uuid> A webhook unique value to identify the delivery. On sale transactions file requests, this is equal to the request identifier.
Viva-Event	string Name of the event that triggered the delivery (i.e. SaleTransactionsFileGenerated).

Responses

200

Success

post /webhooks/receive (your endpoint for webhooks)

Sandbox environment

https://demo.yourapi.com/webhooks/receive (your endpoint for webhooks)

Live environment

https://www.yourapi.com/webhooks/receive (your endpoint for webhooks)

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"requestId": "1aff7ab0-0f25-4f17-889b-da8d5d97c946",
"Text": "Download file from: https://api.vivapayments.com/dataservices/v1/FileRequests/File/1aff7ab0-0f25-4f17-889b-da8d5d97c946/22facb2a-3a28-4d81-ae5a-630e691817db",
"Link": "https://api.vivapayments.com/dataservices/v1/FileRequests/File/1aff7ab0-0f25-4f17-889b-da8d5d97c946/22facb2a-3a28-4d81-ae5a-630e691817db",
"Authorized": true,
"ExpirationDate": "2021-10-20T15:52:56.498 +03:00",
"FileType": ".csv"
}

Transactions via Data Service

Transactions from Data Service

This API call provides comprehensive access to detailed information regarding historical transactions. It offers extensive filtering capabilities based on various criteria such as date, transaction type, amount, status, and more. By utilizing this endpoint, you can retrieve specific transaction details that meet your specified criteria.

GET /dataservices/v2/transactions/Search?PageSize={PageSize}&Page={PageNumber}&OrderBy={Descending}

Note: MerchantIsvFeeAmount and TotalCommission in the response will have values only if the transaction is cleared. To determine whether the clearance has taken place, you can check the ClearanceDate parameter.

Find out about the possible transaction feedback parameters.

The Data Services APIs requires specific access credentials. To request access, please speak to your sales representative

Authorizations:

OAuth2 (urn:viva:payments:biservices:publicapi urn:viva:payments:core:api:isv urn:viva:payments:core:api:redirectcheckout)

query Parameters

PageSize	integer Example: PageSize=100 Specifies the number of items (records) to be included per page in the API response. It controls the amount of data returned per request, helping manage response size and optimize performance. If not specified, the default value is 10
Page	integer Example: Page=1 Determines which page of data to retrieve from the paginated API results. It indicates the specific subset of data within the overall dataset, based on the given pageSize. If not specified, the default value is 1.
OrderBy	string Example: OrderBy=Descending Specifies the order in which the results should be sorted. Use OrderBy=Descending to sort the results in descending order based on the date creteria. Conversely, for ascending order, use OrderBy=Ascending.

Request Body schema: application/json

insDateFrom	string <date-time> The start date and time for retrieving data, based on the transaction creation time. Data will be returned from this date and time onward. This parameter includes the following components, Date (YYYY-MM-DD) Time (HH:MM:SS.SS) Time zone offset(±HH:MM e.g., +00:00 for UTC)
insDateTo	string <date-time> The end date and time for retrieving data, based on the transaction creation time. Data will be returned up to this date and time. This parameter includes the following components, Date (YYYY-MM-DD) Time (HH:MM:SS.SS) Time zone offset(±HH:MM e.g., +00:00 for UTC)
ClearanceDateFrom	string <date-time> The start date and time for retrieving data, based on the transaction clerance time. Data will be returned from this date and time onward. This parameter includes the following components, Date (YYYY-MM-DD) Time (HH:MM:SS.SS) Time zone offset(±HH:MM e.g., +00:00 for UTC)
ClearanceDateTo	string <date-time> The end date and time for retrieving data, based on the transaction clerance time. Data will be returned up to this date and time. This parameter includes the following components, Date (YYYY-MM-DD) Time (HH:MM:SS.SS) Time zone offset(±HH:MM e.g., +00:00 for UTC)
TransactionTypeIds	Array of integers The transaction type to be filtered. If empty, all transaction types will be returned in the response. Please see this page for more details about transaction types.
StatusIds	Array of strings The statuses of transactions to filter. If left empty, transactions with all statuses will be included in the response. Example: `"F"` `"A"` `"C"` `"E"` `"M"` `"R"` `"X"` `"MA"` `"MI"` `"ML"` `"MS"` `"MW"` F = Finished A = Active C = Captured E = Error R = Refunded X = Cancelled M = Claimed MA = Claim Awaiting Response MI = Claim In Progress ML = Claim Lost MS = Suspected Claimed MW = Claim Won
TransactionIds	Array of guid The transaction ids to be filtered. If empty, all transactions will be returned in the response.
SourceTerminalId	string <long> The terminal ID used to filter the transactions.
OrderCode	string <long> The order code used to filter the transaction.
ResellerSourceCode	string <string> The StoreCode of the reseller
AmountFrom	decimal <decimal> The minimum transaction amount to filter the results. Only transactions with an amount above this value will be included in the response.
AmountTo	decimal The maximum transaction amount to filter the results. Only transactions with an amount below this value will be included in the response.
CurrencyCode	string The numeric code of the order's currency as defined in ISO 4712. Only transactions with the specified currency will be included in the response.
MerchantTrns	string The merchant reference number used during transaction creation.

Responses

200

Success

401

You were not authorized to execute this operation

post /dataservices/v2/transactions/Search?PageSize={PageSize}&Page={PageNumber}&OrderBy={Descending}

Sandbox environment

https://demo-api.vivapayments.com/dataservices/v2/transactions/Search?PageSize={PageSize}&Page={PageNumber}&OrderBy={Descending}

Live environment

https://api.vivapayments.com/dataservices/v2/transactions/Search?PageSize={PageSize}&Page={PageNumber}&OrderBy={Descending}

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"insDateFrom": "2024-06-20T12:57:25.463+03:00",
"insDateTo": "2024-06-21T12:57:25.463+03:00",
"ClearanceDateFrom": "2024-06-22T12:57:25.463+03:00",
"ClearanceDateTo": "2024-06-23T12:57:25.463+03:00",
"TransactionTypeIds": 
[5,
7
],
"StatusIds": 
["f",
"x",
"a"
],
"TransactionIds": 
["fa248e3b-7fdb-43bb-9441-d88812f8fce5",
"7bc23b6e-5207-48ed-8eb8-bd87a7fe5843",
"1dca89ed-f436-4068-bb77-6d4aa7185628"
],
"SourceTerminalId": "1412555643",
"OrderCode": "4054144410382502",
"ResellerSourceCode": "4054144410382502",
"AmountFrom": 120.34,
"AmountTo": 300.26,
"CurrencyCode": "978",
"MerchantTrns": "123456"
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"currentPage": 1,
"pageSize": 10,
"totalPages": 0,
"totalDataCount": -1,
"data": 
[
{"TransactionId": "e4c37c00-76ad-4730-93c2-004091ae9de1",
"TransactionTypeId": 5,
"MerchantId": "21859cf1-d7af-47b7-bfad-86b4b3bcc867",
"OrderCode": 4173124907236419,
"Email": null,
"Phone": null,
"ResellerId": null,
"ResellerSourceCode": null,
"MerchantTrns": null,
"CustomerTrns": null,
"ReferenceNumber": 635297,
"InsDate": "2024-06-21T12:37:35.577+03:00",
"SourceCode": "Default",
"FullName": null,
"CardNumber": "454793XXXXXX3518",
"AcquirerApproved": false,
"CardTypeId": 0,
"CardCountryCode": "GR",
"CardIssuingBank": "REVOLUT LIMITED",
"EventId": null,
"CurrencyCode": 978,
"Amount": 0.27,
"OriginalAmount": 0,
"ConversionRate": 0,
"OriginalCurrencyCode": "string",
"CurrentInstallment": 0,
"TotalInstallments": 0,
"ChannelId": "09913a34-c7d2-4e99-a3a7-550f2063d3b1",
"StatusId": "F",
"OrderTags": [ ],
"ClearanceDate": null,
"InterchangeFee": 0,
"SchemeFee": 0,
"TotalCommission": 0.02,
"SourceTerminalId": 16236419,
"PanEntryMode": 1,
"ParentId": null,
"TipAmount": 0,
"BankId": "NET_VISA",
"AuthorizationId": null,
"RetrievalReferenceNumber": 417309634081,
"OrderServiceId": 0,
"ApplicationIdentifierTerminal": "A0000000031010",
"MerchantIsvFeeAmount": 0.009728
}
],
"link": 
[
{"self": "/api/Transaction/Search?PageSize=1&Page=4&OrderBy=Descending",
"next": "/api/Transaction/Search?PageSize=1&Page=5&OrderBy=Descending",
"previous": "/api/Transaction/Search?PageSize=1&Page=3&OrderBy=Descending"
}
]
}

Resellers

Check eligibility for cash payments

Use this endpoint to check whether the customer is eligible to pay.

Cash deposit for merchant payment
Viva customers can use the service without an amount limit. An OTP will be send to the mobile phone of the customer. Non-customers can use the service only for payments < 1.000€ in this case eventId '109101' will be in the response and '/resellers/v1/transactions/cashPayments' must be called with the the appropriate tags in the request body.

Cash deposit to customer account
Only Viva customers can use the service. An OTP will be send to the mobile phone of the customer. otherwise he can only pay the Code via card.

Events

Event	ID	Description
Resellers Payment Not Allowed	109100	This will be exposed in the header (HTTP 400 error code). Payment not allowed
Resellers Additional Fields Required For Non Viva Customer	109101	This will be exposed in the header (HTTP 200 error code). The appropriate tags must be used in the request body of the payment call
Resellers Non Viva Customer Wallet Top Up Only Via Card	109104	This will be exposed in the header (HTTP 400 error code). Non Viva customer cash payment not allowed

For Resellers API calls, please use your Reseller API credentials

Authorizations:

OAuth2 (urn:viva:payments:core:api:resellers)

Request Body schema: application/json

phone	string The customer's phone number
amount	long or null Payment amount
orderCode	long or null The order's unique code
rfPaymentCode	string A unique 20-digit code that allows you to make a payment by bank deposit without knowing the IBAN of the account holder
countryCode	string The country code of the customer

Responses

204

Success

5xx

Internal Server Error

post /resellers/v1/transactions/cashPayments:validate

Sandbox environment

https://demo-api.vivapayments.com/resellers/v1/transactions/cashPayments:validate

Live environment

https://api.vivapayments.com/resellers/v1/transactions/cashPayments:validate

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"phone": "string",
"amount": null,
"orderCode": null,
"rfPaymentCode": "string",
"countryCode": "string"
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"No message": "[Success response]."
}

Check eligibility for bill payments

Use this endpoint to check wether the customer is eligible to pay. Viva customers can use the service without an amount limit. An OTP will be send to the mobile phone of the customer. Non-customers can use the service only for payments < 1.000€ in this case enventId '109101' will be in the response and '/resellers/v1/transactions/cashPayments' must be called with the the appropriate tags in the request body. Events

Event	ID	Description
Resellers Payment Not Allowed	109100	This will be exposed in the header (HTTP 400 error code). Payment not allowed
Resellers Additional Fields Required For Non Viva Customer	109101	This will be exposed in the header (HTTP 200 error code). The appropriate tags must be used in the request body of the payment call

For Resellers API calls, please use your Reseller API credentials

Authorizations:

OAuth2 (urn:viva:payments:core:api:resellers)

Request Body schema: application/json

phone	string The customer's phone number
amount	long or null Payment amount
countryCode	string The country code of the customer

Responses

204

Success

5xx

Internal Server Error

post /resellers/v1/transactions/billPayments:validate

Sandbox environment

https://demo-api.vivapayments.com/resellers/v1/transactions/billPayments:validate

Live environment

https://api.vivapayments.com/resellers/v1/transactions/billPayments:validate

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"phone": "string",
"amount": null,
"countryCode": "string"
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"No message": "[Success response]."
}

Resend OTP for cash payment

Use this endpoint to resend another OTP to customer only if OTP created by '/resellers/v1/transactions/cashPayments:validate' has been expired

For Resellers API calls, please use your Reseller API credentials

Authorizations:

OAuth2 (urn:viva:payments:core:api:resellers)

query Parameters

phone required	string The customer's phone number
countryCode	string The country code of the customer

Responses

204

Success

5xx

Internal Server Error

post /resellers/v1/transactions/cashPayments:sendotp

Sandbox environment

https://demo-api.vivapayments.com/resellers/v1/transactions/cashPayments:sendotp

Live environment

https://api.vivapayments.com/resellers/v1/transactions/cashPayments:sendotp

Request samples

cURL
PHP
NodeJs
Java

Copy

curl --location --globoff --request POST 'https://api.vivapayments.com/resellers/v1/transactions/cashPayments:sendotp?phone={phone}' \
--header 'Authorization: Bearer {Bearer_Token}'

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"No message": "[Success response]."
}

Resend OTP for bill payment

Use this endpoint to resend another OTP to customer only if OTP created by '/resellers/v1/transactions/billPayments:validate' has been expired

For Resellers API calls, please use your Reseller API credentials

Authorizations:

OAuth2 (urn:viva:payments:core:api:resellers)

query Parameters

phone required	string The customer's phone number
countryCode	string The country code of the customer

Responses

204

Success

5xx

Internal Server Error

post /resellers/v1/transactions/billPayments:sendotp

Sandbox environment

https://demo-api.vivapayments.com/resellers/v1/transactions/billPayments:sendotp

Live environment

https://api.vivapayments.com/resellers/v1/transactions/billPayments:sendotp

Request samples

cURL
PHP
NodeJs
Java

Copy

curl --location --globoff --request POST 'https://api.vivapayments.com/resellers/v1/transactions/billPayments:sendotp?phone={phone}' \
--header 'Authorization: Bearer {Bearer_Token}'

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"No message": "[Success response]."
}

Cash payment

Events

Event	ID	Description
Resellers Payment Not Allowed	109100	This will be exposed in the header (HTTP 400 error code). Payment not allowed
Resellers Additional Fields Required For Non Viva Customer	109101	This will be exposed in the header (HTTP 200 error code). The appropriate tags must be used in the request body of the payment call
Resellers Non Viva Customer Wallet Top Up Only Via Card	109104	This will be exposed in the header (HTTP 400 error code). Non Viva customer cash payment not allowed

For Resellers API calls, please use your Reseller API credentials

Authorizations:

OAuth2 (urn:viva:payments:core:api:resellers)

Request Body schema: application/json

phone	string The customer's phone number
amount	long or null Payment amount
orderCode	long or null The order's unique code
merchantId	uuid The merchant's unique ID
rfPaymentCode	string A unique 20-digit code that allows you to make a payment by bank deposit without knowing the IBAN of the account holder
countryCode	string The country code of the customer
oneTimePassword	string OTP - One-Time Password
resellerSourceCode	string The Reseller's Source Code
tags	array of strings Mandatory only when eligibility check responds with eventId 109101

Responses

200

Success

403

OTP (One Time Password) is invalid

404

OTP (One Time Password) has expired

5xx

Internal Server Error

post /resellers/v1/transactions/cashPayments

Sandbox environment

https://demo-api.vivapayments.com/resellers/v1/transactions/cashPayments

Live environment

https://api.vivapayments.com/resellers/v1/transactions/cashPayments

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"phone": "string",
"amount": null,
"orderCode": null,
"merchantId": null,
"rfPaymentCode": "string",
"countryCode": "string",
"oneTimePassword": "string",
"resellerSourceCode": "string",
"tags": null
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"email": "string",
"amount": null,
"merchantId": null,
"orderCode": null,
"onTopFee": null,
"totalFee": null,
"tags": null,
"companyName": "string",
"transactionId": null,
"serviceFee": null,
"channelName": "string",
"currencyCode": "string",
"currencyName": "string",
"resellerFee": null,
"collectionFee": null,
"clearanceDate": null,
"amountWithoutFee": null,
"resellerSourceName": "string",
"merchantReceiptUrl": "string",
"totalConversionFee": null,
"resellerSourceAddress": "string"
}

Bill payment

Use this endpoint to pay bills

For Resellers API calls, please use your Reseller API credentials

Authorizations:

OAuth2 (urn:viva:payments:core:api:resellers)

Request Body schema: application/json

vat	string VAT
amount	long Payment amount
phone	string The customer's phone number
date	date-time Date
lastName	string The customer's last name
orderCode	long or null The order's unique code
firstName	string The customer's last name
tags	array of strings Mandatory only when eligibility check responds with eventId 109101
countryCode	string The country code of the customer
merchantTrns	string An ID or a short description that helps you uniquely identify the transaction
oneTimePassword	string OTP - One-Time Password
billId	integer The Bill ID
resellerSourceCode	string The reseller's Source Code

Responses

200

Success

403

OTP (One Time Password) is invalid

404

OTP (One Time Password) has expired

5xx

Internal Server Error

post /resellers/v1/transactions/billPayments

Sandbox environment

https://demo-api.vivapayments.com/resellers/v1/transactions/billPayments

Live environment

https://api.vivapayments.com/resellers/v1/transactions/billPayments

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"vat": "string",
"amount": null,
"phone": "string",
"date": null,
"lastName": "string",
"orderCode": null,
"firstName": "string",
"tags": null,
"countryCode": "string",
"merchantTrns": "string",
"oneTimePassword": "string",
"billId": 0,
"resellerSourceCode": "string"
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"email": "string",
"amount": null,
"orderCode": null,
"billFee": null,
"onTopFee": null,
"totalFee": null,
"tags": null,
"sourceCode": "string",
"serviceFee": null,
"companyName": "string",
"channelName": "string",
"transactionId": null,
"currencyCode": "string",
"currencyName": "string",
"resellerFee": null,
"collectionFee": null,
"clearanceDate": null,
"amountWithoutFee": null,
"resellerSourceName": "string",
"merchantReceiptUrl": "string",
"totalConversionFee": null,
"resellerSourceAddress": "string"
}

Create order

Use this endpoint to create an order. In the successful response you will get OrderCode and RfPaymentCode which can be used to make a cash payment. Only one of the two codes can be used; we suggest to use the RfPaymentCode.

For Resellers API calls, please use your Reseller API credentials

Authorizations:

OAuth2 (urn:viva:payments:core:api:resellers)

Request Body schema: application/json

amount	decimal Payment amount
email	string The customer's email address
phone	string The customer's phone number
productId	uuid or null Used only when you want to create an order for wallet top-up - "4690241B-C159-479F-8309-F167874ADC4A"
fullName	string The customer's full name
merchantId	uuid or null The Merchant's unique ID
countryCode	string The country code of the customer
requestLang	string The language in which the payment form is displayed. Consists of two-letter ISO 639-1 language code combined with two-letter ISO 3166-1 alpha-2 country code
currencyCode	string The numeric code of the currency as defined in ISO 4712
merchantTrns	string Used to help the Merchant identify the order
customerTrns	string Friendly description displayed to the customer
targetWalletId	long or null Destination ID of the wallet to which you wish to make the transfer
disableExactAmount	boolean Specify if the amount to be paid can be changed (true) or remains fixed (default value)
resellerSourceCode	string The reseller's Source Code

Responses

200

Success

5xx

Internal Server Error

post /resellers/v1/orders

Sandbox environment

https://demo-api.vivapayments.com/resellers/v1/orders

Live environment

https://api.vivapayments.com/resellers/v1/orders

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"amount": null,
"email": "string",
"phone": "string",
"productId": null,
"fullName": "string",
"merchantId": null,
"countryCode": "string",
"requestLang": "string",
"currencyCode": "string",
"merchantTrns": "string",
"customerTrns": "string",
"targetWalletId": null,
"disableExactAmount": true,
"resellerSourceCode": "string"
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"orderCode": null,
"rfPaymentCode": "string"
}

Bank Account (Deprecated)

Link bank account (OLD) Deprecated

Use this API Call to link a bank account (create a new beneficiary using an external IBAN).

It is strongly recommended to first make sure that the IBAN is valid by using the Validate IBAN API call.

Note that the outgoing bank transfers are not fully functional in demo environment due to another bank involvement to the process.

This API call uses Basic authentication.

You may find below test IBANs for your tests in demo environment.

IBAN	Country
BE22679200300047	Belgium
AT483200000012345864	Austria
BG18RZBB91550123456789	Bulgaria
HR1723600001101234565	Croatia
CY21002001950000357001234567	Cyprus
CZ5508000000001234567899	Czech Republic
DK9520000123456789	Denmark
FI1410093000123458	Finland
FR7630006000011234567890189	France
DE75512108001245126199	Germany
HU93116000060000000012345676	Hungary
IE64IRCE92050112345678	Ireland
IT60X0542811101000000123456	Italy
LU120010001234567891	Luxembourg
MT31MALT01100000000000000000123	Malta
NL02ABNA0123456789	Netherlands
PL10105000997603123456789123	Poland
ES7921000813610123456789	Spain
SE7280000810340009783242	Sweden
GR9608100010000001234567890	Greece
GB94BARC10201530093459	Greece
GR1601101250000000012300695	Greece
GR0901747473523851736771797	Greece
GR4101137398743417343263193	Greece
GB78BARC20037839364893	United Kingdom
GB93BARC20040487725456	United Kingdom

Authorizations:

BasicAuth (See BasicAuth)

header Parameters

Content-Type

required

string

Default: application/json

Request Body schema: application/json

iban required	string <uuid> The desired IBAN.
friendlyName	string <uuid> A friendly name of your choosing.
beneficiaryName	string <uuid> A beneficiary name of your choosing.

Responses

200

Success

401

Unauthorized

409

You have already add this IBAN as beneficiary

5xx

Internal Server Error

post /api/bankaccounts

Sandbox environment

https://demo.vivapayments.com/api/bankaccounts

Live environment

https://www.vivapayments.com/api/bankaccounts

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


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

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"Iban": "GB74VPAY04136031593641",
"BankId": "NET_VIVAGB",
"IsArchived": false,
"BankAccountId": "176d131e-7271-4961-babe-cf6d0461a5ed",
"FriendlyName": "A friendly name of your choosing",
"CurrencyCode": 826,
"BeneficiaryName": "A beneficiary name of your choosing",
"VerificationRetries": 0,
"IdentificationState": 0
}

Retrieve bank accounts (OLD) Deprecated

Use this API Call to retrieve all the linked bank accounts (beneficiaries using external IBANs) set up under your Viva profile.

This API call uses Basic authentication.

Authorizations:

BasicAuth (See BasicAuth)

Responses

200

Success

400

Wrong Body Parameters

401

Unauthorized

403

No Role for Merchant

404

Wallet Not Found

405

Bank Account is Viva IBAN

452

Insufficient Funds

5xx

Internal Server Error

get /api/bankaccounts

Sandbox environment

https://demo.vivapayments.com/api/bankaccounts

Live environment

https://www.vivapayments.com/api/bankaccounts

Request samples

cURL
PHP
NodeJs
Java

Copy

curl --location 'https://demo.vivapayments.com/api/bankaccounts' \
--header 'Authorization: Basic e1lvdXIgTWVyY2hhbnQgSUR9OntZb3VyIEFQSSBLZXl9'

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"Iban": "GB74VPAY04136031593641",
"BankId": "NET_VIVAGB",
"IsArchived": false,
"BankAccountId": "176d131e-7271-4961-babe-cf6d0461a5ed",
"FriendlyName": "A friendly name of your choosing",
"CurrencyCode": 826,
"BeneficiaryName": "A beneficiary name of your choosing",
"VerificationRetries": 0,
"IdentificationState": 0
}

Οutgoing bank transfer (OLD) Deprecated

Use this API Call to make a successful outgoing bank transfer to a bank account.

This API call uses Basic authentication.

Authorizations:

BasicAuth (See BasicAuth)

path Parameters

walletId required	integer <int64> Example: 197697272601 The ID of the source wallet, funds will be transferred out of it.
bankAccountId required	string Example: 6e8a43bb-3407-4047-a5e8-ae03c9b8260f The ID of the linked bank account (beneficiary using an external IBAN), funds will be transferred into it.

header Parameters

Content-Type

required

string

Default: application/json

Request Body schema: application/json

amount required	integer <int32> The amount for the bank transfer.
description	string <uuid> <= 255 A short description for the bank transfer.
trySendInstant	boolean (true/false) Default: false Indicates the intent to try the transfer as instant. If this parameter is set to `true` and the recipient bank supports the instant transfer, the transfer will be attempted as instant. Otherwise, the transfer will be a normal bank transfer.
instructionTypeId	integer <int32> Default: 1 Indicates the instruction type for this bank transfer. You may find below all the possible values. Enum: `"1"` `"2"` 1 = Shared 2 = Ours The OUR instruction means you pay all transfer charges. SHA (shared) means you only pay your bank's outgoing transfer charge. If OUR is specified but not supported, the transfers will be executed as SHA

Responses

200

Success

400

Fail - Target bank account ID not valid

401

Unauthorized

452

Insufficient funds

5xx

Internal Server Error

post /api/wallets/{walletId}/commands/banktransfer/{bankAccountId}

Sandbox environment

https://demo.vivapayments.com/api/wallets/{walletId}/commands/banktransfer/{bankAccountId}

Live environment

https://www.vivapayments.com/api/wallets/{walletId}/commands/banktransfer/{bankAccountId}

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"amount": 100,
"description": "A short description about the bank transfer",
"trySendInstant": true,
"instructionTypeId": 1
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"commandId": "uuid",
"IsInstant": true
}

Retrieve bank account by Id (OLD) Deprecated

Use this API Call to retrieve a linked bank account (beneficiary using an external IBAN) by its ID.

This API call uses Basic authentication.

Authorizations:

BasicAuth (See BasicAuth)

path Parameters

required

string

Example: 76d131e-7271-4961-babe-cf6d0461a5ed

The assigned Id of the linked bank account.

Responses

200

Success

401

Unauthorized

5xx

Internal Server Error

get /api/bankaccounts/{id}

Sandbox environment

https://demo.vivapayments.com/api/bankaccounts/{id}

Live environment

https://www.vivapayments.com/api/bankaccounts/{id}

Request samples

cURL
PHP
NodeJs
Java

Copy

curl --location -g 'https://demo.vivapayments.com/api/bankaccounts/{id}' \
--header 'Authorization: Basic e1lvdXIgTWVyY2hhbnQgSUR9OntZb3VyIEFQSSBrZXl9'

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"Iban": "GB74VPAY04136031593641",
"BankId": "NET_VIVAGB",
"IsArchived": false,
"BankAccountId": "176d131e-7271-4961-babe-cf6d0461a5ed",
"FriendlyName": "A friendly name of your choosing",
"CurrencyCode": 826,
"BeneficiaryName": "A beneficiary name of your choosing",
"VerificationRetries": 0,
"IdentificationState": 0
}

Unlink bank account (OLD) Deprecated

Use this API Call to unlink a linked bank account (beneficiary using an external IBAN) by ID.

This API call uses Basic authentication.

Authorizations:

BasicAuth (See BasicAuth)

path Parameters

required

string

Example: 725ba43e-87a6-4c3f-a544-f250a26e8068d

The desired bank account Id for unlink.

Responses

200

Success

401

Unauthorized

5xx

Internal Server Error

delete /api/bankaccounts/{id}

Sandbox environment

https://demo.vivapayments.com/api/bankaccounts/{id}

Live environment

https://www.vivapayments.com/api/bankaccounts/{id}

Request samples

cURL
PHP
NodeJs
Java

Copy

curl --location -g --request DELETE 'https://demo.vivapayments.com/api/bankaccounts/{id}' \
--header 'Authorization: Basic e1lvdXIgTWVyY2hhbnQgSUR9OntZb3VyIEFQSSBLZXl9'

Response samples

Content type

application/json

Copy

Expand all Collapse all

"You receive HTTP 200 status code for successful requests."

Payments (Deprecated)

Create payment order (OLD) Deprecated

Every payment on the Viva platform needs an associated payment order. A payment order is represented by a unique numeric orderCode. As well as the below detailed information about this API call, we have a PHP code sample available.

This API call uses Basic authentication.

Typically, each payment orderCode is used for one payment only. If you want to accept multiple payments using the same order code, you should create the payment order, and then update it using the Update an order API call and set the disablePaidState request parameter value to true.

Authorizations:

BasicAuth (See BasicAuth)

header Parameters

Content-Type

required

string

Default: application/json

Request Body schema: application/json

amount required	integer <int64> >= 30 The amount associated with this payment order. The amount will be in the currency of your merchant account using the currency's smallest unit of measurement (e.g. cents of a euro). It must always be greater than 30 (which is the minimum amount you can charge with Viva). For example, if you want to create a payment for €100.37, you need to pass the value `10037`.
email	string [ 1 .. 50 ] The customer's e-mail address, used on the payment form. Although optional, it is highly recommended to provide the email of the customer, as the customer will be asked to provide it if not specified by you during the generation of the payment order; asking the customer to provide their email, which they may have provided earlier, may cause them to abandon the checkout; this affects significantly the conversion rate of your online store. This is a required parameter if combined with the `serviceId` parameter below set to a value of `4` (i.e. when creating a payment notification).
fullName	string [ 1 .. 100 ] The customer's full name, used on the payment form. Although optional, it is highly recommended to provide the full name of the customer, as the customer will be asked to provide it if not specified by you during the generation of the payment order; asking the customer to provide their full name, which they may have provided earlier, may cause them to abandon the checkout; this affects significantly the conversion rate of your online store.
customerTrns	string [ 1 .. 2048 ] This optional parameter adds a friendly description to the payment order that you want to display to the customer on the payment form. It should be a short description of the items/services being purchased. Although optional, it is highly recommended to provide a description for the customer, so that the customer knows what he is being asked to pay for; this affects significantly the conversion rate of your online store.
phone	string [ 1 .. 30 ] The customer's telephone number for inclusion in the sales transaction details in the viva banking app. After logging in, go to Sales > Sales Transactions and find the transaction. Click on the Info button against the item to display the Transaction Details dialog box. Click on the Customer tab. The contents of the `phone` field will be displayed on the line below the customer's name.
requestLang	string Default: "en-GB" For all possible values, please see the 'Allowed Values' list below The language in which the payment form is displayed. Consists of two-letter ISO 639-1 language code combined with two-letter ISO 3166-1 alpha-2 country code. Allowed Values: Bulgarian > `bg-BG` Croatian > `hr-HR` Czech (Czechia) > `cs-CZ` Danish > `da-DK` Dutch (Netherlands) > `nl-NL` Dutch (Belgium)> `nl-BE` English (United Kingdom) > `en-GB` English (United States) > `en-US` Finnish > `fi-FI` French (Belgium)> `fr-BE` French (France) > `fr-FR` German > `de-DE` Greek > `el-GR` Hungarian > `hu-HU` Italian > `it-IT` Polish > `pl-PL` Portuguese > `pt-PT` Romanian > `ro-RO` Russian > `ru-RU` Spanish > `es-ES` Swedish > `sv-SE`
sourceCode	string This is the code of the payment source you created to link with your online store. If you have defined multiple payment sources in your account, you need to define the `sourceCode` parameter when creating the payment order, so that the system selects the appropriate payment source. sourceCode is case-sensitive. If left blank, `Default` is used.
disableExactAmount	boolean Default: false If this parameter is set to true, then any amount specified in the payment order is ignored (although still mandatory), and the customer is asked to indicate the amount they will pay. Note that if set to true, there will not be the option to pay with certain payment methods.
disableCash	boolean Default: false If this parameter is set to `true`, the customer will not have the option to pay in cash at a Viva Spot, and the checkout page will not display the Cash and E-Banking/Phone banking options. Available only to merchants set up in Greece.
disableWallet	boolean Default: false If this parameter is set to `true`, the customer will not have the option to pay using their Viva personal account (wallet), and the checkout page will not display the Viva Wallet option. Available only to merchants set up in Greece, Malta and Cyprus.
allowRecurring	boolean Default: false If this parameter is set to `true`, recurring payments are enabled so that the initial transaction ID can be used for subsequent payments. For details of how to create a recurring payment, view our Create a recurring payment tutorial. For an example of recurring payments in action, see our PHP code sample. The payment method needs to have support for recurring payments. Keep in mind it is your responsibility to have the customer's consent to perform recurring payments (using this parameter constitutes your confirmation that you have such consent)! Recurring payments are not available with pre-authorizations or instalments.
isPreAuth	boolean Default: false If set to `true`, a pre-auth transaction will be performed. This will hold the selected amount as unavailable (without the customer being charged) for a period of time. No email receipt is sent out from us in this case as it is not a charge. To cancel a pre-auth, use the Cancel transaction API call in the same way that you would to reverse a payment. To capture a pre-auth, use the Create transaction API call in the same way that you would to create a payment. For further details, see our Handle pre-authorizations tutorial. The payment method needs to have support for pre-auth transactions. Pre-authorizations are not available with recurring payments or instalments. Additionally, When creating a payment order for a pre-authorization (with `isPreAuth` = `true`), tipAmount should only be set when capturing the pre-authorization, and not when creating the initial payment order
maxInstallments	integer <int32> [ 1 .. 36 ] The maximum number of installments that the customer can choose for this transaction. If this parameter is omitted, the customer will not see an option for paying with installments. The payment method needs to have support for installments. Installments are available only to merchants set up in Greece and are not available with recurring payments or pre-authorizations. Please note: If offering installments, the value provided by the merchant is not the number of installments the customer will select, and it is not mandatory for the customer to select installments at all. The process is as follows: 1. The merchant indicates the maximum number of installments they wish to offer to the customer 2. It is then up to the customer whether they pay with or without installments 3. If the customer decides to pay with installments, they are able to select the number of installments (up to the maximum specified by the merchant)
tipAmount	integer <int64> Default: 0 The tip value, if applicable for the customer's purchase, which is already included in the `amount` of the payment order. Should be in the currency of your merchant account using the currency's smallest unit of measurement (e.g. cents of a euro). When creating a payment order for a pre-authorization (with `isPreAuth` = `true`), tipAmount should only be set when capturing the pre-authorization, and not when creating the initial payment order
paymentTimeout	integer <int32> Default: 1800 By default, the time given to the customer to complete an online payment is 1800 seconds (30 minutes). If the customer does not complete the payment within this time frame, the Payment Order is automatically cancelled. By using this parameter, you can define a different life span for your Payment Order. Note that if the ExpirationDate parameter is given a value, then the ExpirationDate overrides the paymentTimeout option. Value is in seconds and can be either smaller or greater than 1800 secs. Use value 65535 if you want your Payment Order to never expire.
expirationDate	string <date-time> Same as paymentTimeout but expressed in absolute datetime in ISO 8601 format. Note that if the ExpirationDate parameter is given a value, then the ExpirationDate overrides the paymentTimeout option. Example: `2021-12-01T08:00:00+00:00`. This denotes the year (2021), month (December), date (1st), time (8.00am and zero seconds) and time zone (+00:00, which is Greenwich Mean Time).
serviceId	integer <int32> Default: 0 If you wish to create a payment order, and then send out an email to the customer to request payment, rather than immediately redirect the customer to the payment page to pay now, use the value `4` (EmailCheckoutOut), and the system will automatically send your customer an email notification. This is equivalent to sending a payment notification from the viva banking app. The default value is `0` (WebCheckOut) and does not send an email notification to request payment.
merchantTrns	string [ 1 .. 2048 ] This can be either an ID or a short description that helps you uniquely identify the transaction in the viva banking app. For example, this can be your customer order reference number. After logging in, go to Sales > Sales Transactions and find the transaction. Click on the Info button against the item to display the Transaction Details dialog box. The contents of the `merchantTrns` field will be displayed on the line below the timestamp information.
isCardVerification	boolean Default: false This parameter should be set to `true` to trigger a verification using Card Verification functionality (and the `amount` parameter should be set to '0'). Please note: This is currently only available for card payments via Visa, Mastercard, Maestro, Diners Club & Discover (digital wallets are not supported) Recurring payments are supported This is not available with the ISV schema The following parameters are also not compatible with Card Verification: `preauth`, `maxInstallments`/`forceMaxInstallments`, `disableExactAmount`, `tipAmount`, `cardTokens`
tags	Array of strings You can add several tags to a transaction that will help in grouping and filtering in the viva banking app. After logging in, go to Sales > Sales Transactions and expand the Advanced search feature. In the Tags field, enter the tag(s) you want to search with, then click on the Search button.

Responses

200

Success

400

Bad Request

401

Unauthorized

5xx

Internal Server Error

post /api/orders

Sandbox environment

https://demo.vivapayments.com/api/orders

Live environment

https://www.vivapayments.com/api/orders

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"amount": 200,
"email": "customer@example.com",
"fullName": "Customer full name",
"customerTrns": "Short description of items/services purchased to display to your customer",
"phone": "7967813180",
"requestLang": "en-GB",
"sourceCode": "3891",
"disableExactAmount": "false",
"disableCash": "false",
"disableWallet": "false",
"allowRecurring": "false",
"isPreAuth": "false",
"maxInstallments": 1,
"tipAmount": 0,
"paymentTimeout": 1800,
"expirationDate": "2021-12-01T08:00:00+00:00",
"serviceId": 0,
"merchantTrns": "Short description of items/services purchased by customer",
"isCardVerification": false,
"tags": 
["sample string 1",
"sample string 2",
"sample string 3"
]
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"OrderCode": 0,
"ErrorCode": 0,
"ErrorText": "string",
"TimeStamp": "2025-04-16T07:41:15Z",
"CorrelationId": "string",
"EventId": 0,
"Success": true
}

Transactions (Deprecated)

Retrieve transactions (OLD) Deprecated

Enables you to obtain detailed information about a past payment from its transaction ID, e.g.
GET /api/transactions/b1a3067c-321b-4ec6-bc9d-1778aef2a19d

By appending alternative parameters to the endpoint you can also find out a list of transactions with further details for a given:

date, e.g. GET /api/transactions/?date=2018-08-27
clearance date, e.g. GET /api/transactions/?clearancedate=2018-08-27
order code, e.g. GET /api/transactions/?ordercode=175936509216
source code for a specific date, e.g. GET /api/transactions/?sourceCode=Default&date=2018-08-27

Find out about the possible transaction feedback parameters. As well as the below detailed information about this API call, we have a PHP code sample available.

This API call uses Basic authentication.

Authorizations:

BasicAuth (See BasicAuth)

path Parameters

required

string

The unique ID of the initial transaction.

query Parameters

date	string <date-time> Example: date=2016-12-24 A given day for which all transactions will be returned.
clearanceDate	string <date-time> Example: clearanceDate=2016-11-24 If we want to get all transactions that were cleared on a specific date.
orderCode	integer Example: orderCode=175936509216 A valid 16-digit payment order code.
sourceCode	string The 4-digit code of the payment source you created to link with your online store.

Responses

200

Success

400

Invalid query parameters/values -or- Request is invalid

401

Unauthorized

5xx

Internal Server Error

get /api/transactions/{transaction_id}

Sandbox environment

https://demo.vivapayments.com/api/transactions/{transaction_id}

Live environment

https://www.vivapayments.com/api/transactions/{transaction_id}

Request samples

cURL
PHP
NodeJs
Java

Copy

curl --location -g 'https://demo.vivapayments.com/api/transactions/{transaction_id}' \
--header 'Authorization: Basic TWVyY2hhbnRfSUQ6QVBJX0tleQ=='

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"Transactions": 
[
{"Fee": 1,
"BankId": "NET_VISA",
"ParentId": "ce5de8be-bed6-494c-8988-f07841221ba8",
"Switching": false,
"Amount": 21.1,
"StatusId": "F",
"ChannelId": "93b1a083-2594-4383-a0e2-7d391b746237",
"MerchantId": "21192b18-78cc-4643-b8ae-e796318dbb38",
"ResellerId": null,
"InsDate": "2012-12-24T15:21:44.3243753+02:00",
"CreatedBy": null,
"TipAmount": 0,
"SourceCode": 2267,
"TransactionId": "b1a3067c-321b-4ec6-bc9d-1778aef2a19d",
"Commission": 0.3,
"PanEntryMode": 1,
"MerchantTrns": "Your merchant reference",
"CurrencyCode": "826",
"CustomerTrns": "Short description of items/services purchased to display to your customer",
"IsManualRefund": false,
"TargetPersonId": null,
"AcquirerApproved": false,
"SourceTerminalId": 90000000,
"RedeemedAmount": 0,
"AuthorizationId": 5428,
"TotalInstallments": 0,
"CurrentInstallment": 0,
"ClearanceDate": "2012-12-24T15:21:44.3243753+02:00",
"ConversionRate": 1.2,
"OriginalAmount": 10.55,
"OriginalCurrencyCode": "978",
"ResellerSourceCode": null,
"RetrievalReferenceNumber": 122409743701,
"Order": 
{"OrderCode": 8736775275262658,
"ChannelId": "95d02b56-bace-4608-ad1b-c1a8da705e52",
"ResellerId": null,
"SourceCode": 2267,
"Tags": 
["sample string 1",
"sample string 2",
"sample string 3"
],
"RequestLang": "en-GB",
"ResellerSourceCode": null
},
"Payment": 
{"Email": "example@example.com",
"Phone": "2131234567",
"ChannelId": "245a790d-c98d-4d80-ad97-a9b1efb5771e",
"FullName": "Joe Blogs",
"Installments": 4,
"RecurringSupport": true
},
"TransactionType": 
{"Name": "CardCharge",
"TransactionTypeId": 5
},
"CreditCard": 
{"Token": "Unique 40-character alphanumeric token",
"Number": "123456XXXXXX1234",
"CountryCode": "GB",
"IssuingBank": "Bank of Scotland PLC",
"CardHolderName": "Joe Blogs",
"ExpirationDate": "yyyy-mm-ddT00:00:00,",
"CardType": 
{"Name": "VISA",
"CardTypeId": 1
}
},
"LoyaltyTransactions": 
[
{"PointsEarned": 1333,
"ReferenceNumber": 488425,
"PointsRedeemed": 300,
"AmountEarned": null,
"AmountRedeemed": 1,
"ProgramId": 3,
"ExternalReferenceNumber": "276683791032330",
"RetrievalReferenceNumber": "427711014586",
"LoyaltyTransactionTypeId": 0
},
{"PointsEarned": 1333,
"ReferenceNumber": 488425,
"PointsRedeemed": 300,
"AmountEarned": 0,
"AmountRedeemed": 1,
"ProgramId": 3,
"ExternalReferenceNumber": "276683791032330",
"RetrievalReferenceNumber": "427711488425",
"LoyaltyTransactionTypeId": 1
}
]
}
],
"ErrorCode": 0,
"ErrorText": null,
"TimeStamp": "2012-12-24T15:21:44.3263755+02:00",
"CorrelationId": null,
"EventId": 0,
"Success": true
}

Retrieve Wallet (Deprecated)

Retrieve Wallet (OLD) Deprecated

Retrieve all wallets set up under your Viva profile.

This API call uses Basic authentication.

Authorizations:

BasicAuth (See BasicAuth)

header Parameters

Content-Type

required

string

Default: application/json

Responses

200

Success

401

Unauthorized

5xx

Internal Server Error

get /api/wallets

Sandbox environment

https://demo.vivapayments.com/api/wallets

Live environment

https://www.vivapayments.com/api/wallets

Request samples

cURL
PHP
NodeJs
Java

Copy

curl --location --request GET 'https://demo.vivapayments.com/api/wallets' \
--header 'Authorization: Basic e01lcmNoYW50X0lEfTp7QVBJX0tleX0=' \
--header 'Content-Type: application/json' \
--data '{
  "Iban": "GB73VPAY04002491881234",
  "WalletId": 91883585,
  "IsPrimary": true,
  "Amount": 2.16,
  "Available": -0.29,
  "Overdraft": 0,
  "FriendlyName": "Primary Account",
  "CurrencyCode": 826
}'

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"Iban": "GB73VPAY04002491883585",
"WalletId": 91883585,
"IsPrimary": true,
"Amount": 2.16,
"Available": -0.29,
"Overdraft": 0,
"FriendlyName": "Primary Account",
"CurrencyCode": 826
}

Obligation (Deprecated)

Obligation (OLD) Deprecated

Enables marketplace owner to place an obligation to a seller for payback. When the obligation is captured, Viva will transfer money from the seller account to the platform account.

This API call uses OAuth2 authentication.

Authorizations:

OAuth2 (urn:viva:payments:core:api:obligations)

Request Body schema: application/json

amount required	decimal In decimals rather than the smallest denomination of the currency (£0.6 instead of 60p).
personId required	long Seller merchant ID from which the refund payback is being requested.
walletId	integer <int64> Use 'null' unless there is a wallet other than the default primary one that’s being used by the seller for their transactions.
description	string <uuid> A string with extra information you want to show in the transaction once the obligation is captured.
currencyCode required	integer <int32> The 3-digit currency code of the transaction. Should be set to the same currency as the Viva accounts involved in the obligation call.

Responses

200

Success

401

Unauthorized

5xx

Internal Server Error

post /obligations/v1/obligations

Sandbox environment

https://demo-api.vivapayments.com/obligations/v1/obligations

Live environment

https://api.vivapayments.com/obligations/v1/obligations

Request samples

Payload
cURL
PHP
NodeJs
Java

Content type

application/json

Copy

Expand all Collapse all


{"amount": 0.6,
"personId": "Seller merchant ID",
"walletId": "Seller wallet ID",
"description": "This is a short description",
"currencyCode": 826
}

Response samples

Content type

application/json

Copy

Expand all Collapse all


{"CaptureId": null,
"StatusId": "A",
"ObligationId": "d1539512-95dd-44d6-b5d5-78c8b4f53839",
"CancellationId": null,
"Created": "2020-11-25T17:26:13.681595+02:00",
"Completed": null,
"WalletTransactionSubTypeId": 159
}