Issuing API

Find out more about our Issuing API. You can use API testing tools such as Postman or Insomnia to make test API calls.

The base URL is https://demo-api.vivapayments.com/

The API uses IdentityServer (OAuth2) authentication.

API methods

View API methods (three-column layout)

Authorization request

After receiving an authorization request, the Partner decides whether to approve or decline the transaction based on the account’s available funds and any applicable fraud rules in place and responds using one of the designated response codes.

If the authorization is approved, the Partner is required to reserve the corresponding amount of funds on the cardholder’s account.

Special cases of authorization include requests with reference to a previously approved transaction.

Authorization advice

Authorization advice represents a notification for an authorization that has already been decided upon (approved/declined), either by the acquirer or by the payment scheme.

Authorization advice is marked with advice = true and contains the response code provided.

In the case of an approval, the Partner must proceed to reserve the corresponding amount of funds on the cardholder’s account as per normal authorization requests.

Preauthorization

Preauthorizations are special cases of authorizations marked with preauthorization = true. Preauthorizations serve the purpose of reserving funds on behalf of a merchant for longer periods of time, examples include hotel reservations and car hiring.

Partners are required to handle preauthorizations as normal authorization requests, providing the appropriate response and reserving account funds when applicable.

Clearing is the process of sending transaction information in a file following an authorization, where applicable. The partner is responsible for applying funds (credit/debit) to the cardholder’s account.

Clearing file

On receipt of the clearing file the Partner is required to post the cardholder’s account; credit or debit the specified amount as indicated by each financial message row. For transaction types that require prior authorization, the corresponding authorizationId is provided to facilitate the release of funds, while for transactions that only appear in Clearing, the partner should only post the accounts.

Note that the clearing file may contain financial presentments for transactions that have not been matched to authorizations (authorizationId = null). As a result, for some debit transactions, cardholder’s may notice both an actual charge and a reserve of funds, for short time intervals.

See also Clearing file specification.

Funds release policy

The presentment of a transaction should appear in clearing within 13 days of the corresponding authorization, while for preauthorizations the period is adjusted to 31 days.

Partners are required to maintain the funds reserved for the above mentioned time frame. After this period, and given that the transaction has not appeared in Clearing, the authorizations are considered to have expired. The Partner should then release the corresponding reservations, making the funds available to the cardholder’s account.