To access the ePayments API and pass account identification, a token must be acquired before each API request.

The following authorisation methods are available when working with the ePayments API:

• Authorisation via partner_id;
• End-to-end authorisation via OAuth 2.0 (RFC-6749).

Authorisation via partner_id is an authorisation method meant for clients who have integrated with the ePayments via API. The authorisation is carried out using unique identifiers - partner_id and partner_secret, which are issued by the customer service or an account manager during API integration.

End-to-end authorisation via OAuth 2.0 is authorisation carried out via authorization_code, which is used to gain access to your clients’ data (e-Wallet number, verification date, etc.). This authorisation can only be used if your client has an ePayments account and only after you received the authorization_code from them.

As part of the end-to-end authorisation method, the token is valid for 20 minutes. To extend the session length, it is recommended to refresh the token via the refresh_token parameter, which is sent in the body of the POST /token request.

After a successful authorisation, the access_token key is issued. It is used when sending your request to ePayments API.

A token can only be obtained using the IP addresses that were specified in your API access application. A token cannot be acquired if your account does not have whitelisted IP addresses or if IP addresses checks were disabled.

From the client’s point of view the authorisation process and token acquisition consists of the following steps:

1. Authorisation in the browser window.
2. Providing access to their data.
3. Sending the access_token key to access the getUser method.

This type of authorisation is only possible if the client already has an ePayments account (verification is optional).

The URL, which will be used to redirect your clients, must be presented in accordance with the below format. If the client has not been authorised in the ePayments system, they will be asked to enter their ePayments account login and password to complete authorisation.

After successful authorisation, the client will be asked to provide access to the data that were requested via the Scope parameter. If access to such data has already been granted, then this step will be skipped.

This method (hereinafter referred to as - getUser) is used to obtain detailed information about a client who provided access to their data. This method is used in end-to-end authorisation.

In the absence of access to some of those data, the fields in the response may be left empty. If the client’s status is not Approved, then the method will return an error with code 15002 and the response will contain values only for the id and userState parameters.

This method (hereinafter referred to as – getUserId) is used to obtain detailed information about a client who provided access to their data. This method is used in partner_id authorisation and if client’s userID is present.

In the absence of access to some of those data, the fields in the response may be left empty. If the client’s status is not - Approved, then the method will return an error with code 15002 and the response will contain values only for the id and userState parameters.

This method (hereinafter referred to as – cardList) is used for obtaining information on all personal and active ePayments cards. For the cards that are not currently in the Active state balance value will be always set as zero.

This method (hereinafter referred to as – cardUnload) is used for transferring funds from your ePayments card to your ePayments e-Wallet.

This method (hereinafter referred to as – cardLoad) is used for loading your ePayments card from your ePayments e-Wallet. The result of the transaction can be checked using the cardLoadInfo method.

This method (hereinafter referred to as – cardLoadInfo) is used to obtain information on a transfer made from the ePayments e-Wallet to your ePayments card.

This method (hereinafter referred to as - ewalletList) is used to obtain detailed information on each currency section of the ePayments e-Wallet.

This method (hereinafter referred to as - currencyExchange) is used for currency exchange when a transfer occurs between different sections of the same ePayments e-Wallet. Currency exchange is carried out using an internal rate set by ePayments. An exchange rate is set for 5 minutes. If during this time the request for a currency exchange was not sent, the rate will be automatically updated.

This method (hereinafter referred to as - availableCurrencies) is used for obtaining a list of all currencies available for cryptocurrency-related transactions. The list will include fiat as well as cryptocurrencies.

This method (hereinafter referred to as - cryptoFees) is used to obtain information about the amount of fees charged when loading cryptocurrency funds to an e-Wallet. Recommended fees are set separately for each cryptocurrency type.

This method (hereinafter referred to as - convertFrom) is used for loading cryptocurrency funds to an e-Wallet. The e-Wallet is loaded with fiat currency. Load amount is determined by the exchange rate and cryptocurrency type.

This method (hereinafter referred to as - checkTransfer) is used to check on the status of a transfer from a cryptocurrency into a fiat currency, using the transaction number set by the ePayments system. The transaction number is returned in the invoiceId parameter from the convertFrom method.

This method (hereinafter referred to as - checkAddress) is used for verifying the correctness of a cryptocurrency e-Wallet address. If entered IP address is correct, then in the reply will contain the errorCode=0 value.

This method (hereinafter referred to as - cryptoExchange) is used for obtaining a conversion rate between cryptocurrency and fiat currencies (USD and EUR). The method is used during fund transfer from an ePayments wallet to a cryptocurrency.

This method (hereinafter referred to as - FromPurseToCryptocurrency) is used for transferring funds from an ePayments wallet to cryptocurrency.

Working with the method is carried out through the following stages:

1. Acquire a token via the authentication method.
2. Submit the cryptoExchange request to obtain data on the exchange quote and network fee.
3. Submit the fromPurseToCryptocurrency transfer request. Its response will contain the 422 error code and instructions for entering the confirmation code (confirmationSessionId and confirmationMessage).
4. Re-submit the fromPurseToCryptocurrency transfer request and include the Confirmation object with previously received confirmation code (the code parameter) and the session Id (thesessionId parameter) in the request body.

This method (hereinafter referred to as - getTransaction) is used for checking on the status of transferring funds from an ePayments wallet to cryptocurrency.

Mass payments is a mass transfers service offered by ePayments. It allows for funds transfer from the ePayments e-Wallet to the following systems:

• Yandex.Money
• QIWI
• WebMoney
• Bank Cards (VISA, Mastercard, Maestro, MIR)
• Bank accounts
• Mobile phone accounts (MTS, Beeline, Megafon, Tele2)
• Other ePayments clients or people who are not yet registered with the system (using email, phone number or e-Wallet number)
• VKontakte payments for advertising and replenishing vote balance

Transfer participants

Mass payments process includes two kinds of participants:

• Sender – the one who is initiating the transfer from their ePayments e-Wallet;
• Recipient – the owner of an account which will receive the transferred funds.

A fee is debited from the sender’s e-Wallet after each mass payment. The exact amount depends on to which system the transfer was sent.

Available currencies

Mass payments can be carried out using one of three currencies available for an ePayments e-Wallet:

• USD – American dollar;
• EUR – Euro;
• RUB – Russian ruble.

If the type of currency sent is different from one to be received, the ePayments system will perform a currency conversion at the rate set by ePayments. The exchange rate is set for 5 minutes and changes after it. This means that if at the time of the transfer confirmation said time limit was not exceeded then the currency conversion will be carried out using the previously specified rate. Otherwise, the exchange rate changes and the final amount, which is supposed to be received, will be re-calculated using the new rate.

API methods for payment execution

When conducting mass payments, it is recommended to use API-methods in the following order:

• Preflight - preliminary calculation and parameters verification method;
• Fees - fees calculation method;
• Payments - mass payment execution method;
• Confirmation - transaction confirmation method. Only for the clients who is NOT authorized via partner_id/partner_secret;
• Search payment by Id - obtaining the mass payment status method;
• Search payment by ExternalId - obtaining the status of a single transfer within the mass payment.

This method (hereinafter referred to as - preflight) is used to:

• predict the possible result of a transaction before undertaking it;
• check for possible errors in the request;
• calculate the commission fee and conversion rate (if the currency sent is different from one to be received).

This method can be used for mass payment, but it is optional.

This method (hereinafter referred to as - fees) is required for calculating operation rates and fees. It uses the same checks as for the preliminary calculation method Preflight, excluding the identity parameter checks (recipient or sender identification). Submission of this parameter is optional. In addition, this method also performs checks for minimum and maximum operation limits.

This method supports calculating fees for funds transfer from and to the ePayments e-Wallet. It can be used for mass payments as well, but this is optional.

This method (hereinafter referred to as - payments) is used for the execution of funds transfer from the ePayments e-Wallet to any outside system. The response message for this method includes transfer confirmation instructions.

This method (hereinafter referred to as - paymentsExternalId) is used to obtain information regarding a specific transaction within a mass payment utilizing the external identifier ExternalId. This identifier is specified in the payment execution request body payments.

The ExternalId is unique for each payment made by the client. This means different payments will be not assigned the same ExternalId value. The identity check is not case sensitive, meaning aBCdeF = abcdef.

This method (hereinafter referred to as - paymentsId) is used to obtain information regarding all transactions made within a single mass payment. The id parameter from the payments array is selected as a request parameter. A response message will contain mass payment results including errors description, commission fee amounts, and quotations.

This method (hereinafter referred to as - confirmation) is used for confirming transfer operations. Confirmation is executed by transmitting the confirmation parameter with the confirmation code in the request body.

This method is not suited for clients who are authorized via partner_id/ partner_secret. Such clients will receive transfer results immediately upon calling the payments method.

Transfers to bank cards are made using the mass payments methods framework. For this type of transfer, one of the following parameters is specified as the recipient in the identity object:

• card – for transfers using a full card number;
• card_token – for transfers using a card token.

Before obtaining access to transfers to bank cards in a production environment, you must fill out an SAQ form, namely:

• for a transfer via full card number, you must provide the completed SAQ-A form;
• for a transfer via card token, you must provide the completed SAQ-D form with ASV report or a PCI DSS Attestation of Compliance (AOC) certificate.

These forms are requested in accordance with the PCI DSS rules. ePayments works under a PCI DSS certificate. The completed SAQ form can be uploaded using “Add Document” feature from the “Settings” tab in the personal area.

Pending status processing

After the transfer to the card has been executed, the sender can check the status of the transfer using the mass transfer identifier - id or the single transfer identifier - externalId. Transfer processing and how soon the final status can be achieved depends on the payment provider. In most cases, the final status of the transfer will be achieved within a few minutes. However it could take from 1 to 5 calendar days to achieve the final status.

Below are few cases for which, the final status of a transfer cannot be obtained earlier than the next day:

Case 1:

• The sender is an individual ePayments client, not a business;
• Recipient card is issued in the Russian Federation;
• The currency received is the Russian ruble.

Case 2:

• Recipient card issued outside of the Russian Federation;
• Payment provider of the recipient’s card - VISA;
• Currency received - US dollar or Euro.

For the aforementioned cases, the final status of a transfer is obtained within 1 to 5 calendar days. This means that when checking the status of a transfer, the status = pending response can be returned. In this case, it is recommended to repeatedly request the payment status according to the following schedule: every 30 seconds, 1 minute, 15 minutes, 30 minutes, 1 hour, 6 hours, and then every 6 hours until the final status is achieved.

To transfer to a third-party issued card using a token and not the card full number, you must use the tokenisation method. Tokenisation is the encryption of data of a third-party issued card in a token format. In this context, the token is a unique string that uniquely identifies the card. The token is generated on the ePayments side.

This payment method improves the security of data transmission and reduces requirements for integration (the only requirement is to sign the PCI DSS SAQ A form).

The tokenisation process consists of the following steps:

1. Implementing JavaScript code for receiving recipient’s card data on your website.
2. Inputting recipient’s card data and sending a request to api.epayments.com.
3. Obtaining the generated token for the recipient card.
4. Call the v2/payments payments method and indicate the received card token.

Implementing code on the website

The following code should be embedded on all web pages where the data entry form for a bank card will be provided (the location of the code inside the web page does not matter):

<div id="root-widget"></div>
<button id="submit-button">submit</button>

On the same page you will need to implement the following JavaScript code (regardless of the position of the previous code block):

<script src="https://static.epayments.com/card-token-widget/cardDataWidget.js">
</script>
<script>
(function () {
document.addEventListener('DOMContentLoaded', function () {
var style = {
widget: {},
field: {},
fieldInput: {},
fieldInputPlaceholder: {},
fieldInputControl: {},
fieldSubmit: {},
fieldSubmitError: {},
fieldSubmitButton: {
'background': '#000',
'hover' : {
'background': '#ff546c'
}
}
};
var option = {
root: '#root-widget',
submitButton: 'submit-button',
fields: [['number', 'expireDate'], ['embossingName']],
sid: '123',
partnerId: '58',
sign: 'f82a381d1f4ab94d8feb33bd161b6638',
lang: 'en',
style: style
};
var widget = cardDataWidget.init(option);
widget.addEventListener('tokenCreateSuccess', function (data)
{

});
})
})()
</script>;

JS Link

It is necessary to transmit the link to the widget form in the <script> tag. The link format depends on in which environment it is used:

• Stage environment: https://static.sandbox.epayments.com/card-token-widget/cardDataWidget.js
• Production environment: https://static.epayments.com/card-token-widget/cardDataWidget.js

In the aforementioned JavaScript code, the following variables are used:

Var Style parameters

For each field of the var style variable, you can apply CSS styling a specific element state (hover, active, focus) or specify additional CSS settings (for example, background).

Var option parameters

Bank card Parameters

Below is a description of the parameters that are available to the sender when filling out the data entry form. The input form can be modified in accordance with the design of your site.

After filling out the form and clicking on the submit button, ePayments receives and processes data on the bank card. If the request is processed successfully, ePayments sends the token object below in the function(data) attributes.

Token object

{
"token": {
"id": "57a729e8-c760-4e49-a206-e4a41539e2ab",
"brand": "Visa",
"country": "LV",
"number": "431422****0056",
"created": "2017-06-30T07:03:36Z",
"lastUsed": null,
"exp_month": "01",
"exp_year": "19",
"name": "Alex Mackitney",
"fingerprint": "F1BE4A4450EEE42F64CC62C8BB1C0C8938FCBBDB2782F891CDF7F09505910F5F"
},
"errorCode": 0,
"errorMsgs": []
}

This method (hereinafter referred to as - cardToken) returns bank card token data.

This method (hereinafter referred to as - cardTokenDelete) is used to delete token of a third-party bank.

This method (hereinafter referred to as - cardCurrencies) is required to obtain information about the issuing bank’s country of origin and the list of currencies available for transferring to third-party issued cards through the v2/payments mass payment method.

The list of currencies from the response can be used in the currency parameter during transfer to the specified card.

The bank transfer feature in the ePayments system is a wire transfer, which can be executed one of the following ways:

• using manual payment details;
• using templates, i.e. previously saved information.

Wire transfers are made via v2/payments mass transfer method. For all outgoing bank transfers, countries’ values are transmitted in ISO 3166 numeric format, currencies - in ISO 4217 symbolic format. Below is a list of beneficiary bank countries for which the additional fields must be filled:

• Australia (ISO = 036);
• Bangladesh (ISO = 050);
• Brazil (ISO = 076);
• Canada (ISO = 124);
• Gibraltar (ISO = 292);
• Guernsey (ISO = 831);
• Hong Kong (ISO = 344);
• India (ISO = 356);
• Indonesia (ISO = 360);
• Isle of Man (ISO = 833);
• Japan (ISO = 392);
• Jersey (ISO = 832);
• Philippines (ISO = 608);
• Russia (ISO = 643);
• Sweden (ISO = 752);
• Thailand (ISO = 764);
• United Kingdom (ISO = 826);
• United States (ISO = 840);
• Vietnam (ISO = 704);

Pending status processing

After the transfer to the card is executed, the sender can check the status of the transfer using the mass transfer identifier – id or the single transfer identifier - externalId. Transfer processing and the speed of achievement of the final status depends on the payment provider.

In most cases, the final status of the transfer will be obtained within 1 to 5 calendar days. However, if a wire transfer is sent to the beneficiary bank in Russia and the receiving currency is the Russian ruble, it could take as long as 30 consecutive days before the final status is achieved.

If the transfer was not processed by the provider, then status = pending will be returned in the payment status request response. In such cases, it is recommended to repeatedly request the payment status according to the following schedule: every 30 seconds, 1 minute, 15 minutes, 30 minutes, 1 hour, and then every hour for the duration of 5 days. If after 5 days final status is not achieved it is recommended to request the payment status according to once a day for each day of designated period until the final status is achieved.

This method (hereinafter referred to as - countryTerms) is used to obtain conditions of transfer to a bank account depending on the receiving bank country of origin, transfer currency and beneficiary type.

This method (hereinafter referred to as - countries) is used to obtain a list of countries available for outgoing bank transfers.

When transferring to bank accounts, only currencies that are defined by whole numbers can be used (for example, VND - Vietnamese dong). To identify such currencies, this method – currencies is used to obtain information about available values: decimal or integer.

This method (hereinafter referred to as - bankTemplateList) is used to get a brief overview of all existing templates which were added for outgoing bank transfers.