Authorisation via a Private Key is an authorisation using a unique identifier, which can only be generated in your ePayments account.

To authorise using a Private Key, you must:

1. Go to your ePayments account > Settings > API keys and credentials.
2. Generate an API key to download your Private Key in the form of a PEM certificate.
3. Make sure to save and store a downloaded Private Key. ePayments doesn’t store Private Keys, and you will not be able to re-display the already downloaded key in the ePayments account.
4. Encrypt each API request using your Private Key and the algorithm below to receive the X-Signature.
5. Include the received X-Signature in the header of each sent API request.

Header format for Private Key authorisation:

Content-type: application/json
X-Signature: encrypted request’s signature
X-Key-Id: a key from your ePayments account

Before an API request can be sent, you must prepare its unique signature - X-Signature. This signature should be included in the request’s header each time the request is sent. A single X-Signature can only be used within a single API request.

Generation of X-Signature depends on an API request format:

• if a request has a body, then a signature is generated using parameters of the request body;
• if a request has no body, then a signature is generated using the request’s URI.

If an API request has a body, then to generate an X-Signature you need:

1. Take the original request body in the JSON format {"name": "value"}.
2. Remove all spaces from the JSON.
3. Take the bytes in the Encoding.UTF8.GetBytes format from the resulting file.
4. Encrypt the resulting array using the RSA SHA-512 algorithm and the Private Key.
5. Convert the resulting array to a base64 string.
6. Send the received value in the request header in the X-Signature parameter.

For example, you received the following PEM certificate in your personal area: ePayments_5ec658fbe20a0d739086c860.pem. The name of this certificate included the X-Key-Id that should be passed in the request’s Header. In this example, X-Key-Id = 5ec658fbe20a0d739086c860.

In addition, you need to generate an X-Signature signature, which also needs to be passed in your request’s Header for successful authorisation. We will use POST /v2/payments API method as an example. The following parameters are passed in the request body:

{
    "Take": 10,
    "From": 1
}

To encrypt an X-Signature signature, you must convert the JSON to a string without spaces. For the example from above, it will be the following string {"Take":10,"From": 1}. Next, this line must be signed using the algorithm, and a PEM certificate (see below an example on how to generating the signature for C # and PHP ). For the pem certificate and the API method from the example above, the X-Signature signature will look like this:

LC9SPiMSWlxhr7FT/UG3GGBRX5lhIiaEcroxZ3Bk0dUP+KZR4u0hANVCe75pWk1G7s5ZmvC9KA/MeOkXVrynnv9r9Md+MpMOuNWR6zWsI5HeX1mzJQLKLX6QLgac+WgcIv+ECwr3FAyirubIQxDMCEgEj96d2daKK5Z+jqf0pzw=

If the API request does not have a body, then to generate an X-Signature you need:

1. Get the full query string. For example: https://api.sandbox.epayments.com/v1/ewallet
2. Take bytes in the Encoding.UTF8.GetBytes format from the resulting string.
3. Encrypt the array using the RSA SHA-512 algorithm and the Private Key.
4. Convert the resulting array to a base64 string.
5. Send the received value in the request header in the X-Signature parameter.

For example, you received the following PEM certificate in your personal area: ePayments_5ec658fbe20a0d739086c860.pem. The name of this certificate includes the X-Key-Id that should be passed in the request’s Header. In this example, X-Key-Id = 5ec658fbe20a0d739086c860.

In addition, you need to generate an X-Signature, which also needs to be passed in your request’s Header. We will use the GET /v1/user API method as an example. This method doesn’t have a request body, so in order to receive X-Signature we need to use the request’s URL.

This example requires using stage environment for signing the https://api.sandbox.epayments.com/v1/user string using this algorithm and a PEM certificate (see below for examples on how to generate the signature for C # and PHP). For the PEM certificate and the API method from the example above, the X-Signature will look like this:

SgmS1wx/j52Pn51F6OSZrvU5LzmYNiHMlERDnm6DeGcEEMYWSu1LH6bHAEg3T1kedag9/ThETkg9nVTtLovCsTjHJoaPxUyi1daXWrdL8zdZFJLL8FJ/RUVb+oOzcVjBeARIx+nMCvw8WnpfQl/S4utEjEatQBgRnImXdl7TT60=

The following are signature generating methods for C# and PHP. The following queries are used as an example:

• POST /v3/transactions, which has a request body;
• GET /v1/user, which does not have a request body (URI is used for generation).

Download files with examples using the links below:

• Example for C#
• Example for PHP

Authorisation via partner_id and partner_secret is the authorisation using unique identifiers - partner_id and partner_secret, which are generated on the ePayments side.

Obtaining access_token:

Thepartner_id and partner_secret identifiers are sent in the body of the POST /token request, and the access_token access key is received in the response. This key must be included in the header of each API request. The access_token lifetime is 5 minutes. After token lifetime is expired, you must re-send POST /token and include grant_type = refresh_token.

Header’s format for authorisation via Partner Id and Partner Secret:

Content-type: application / json
Authorization: Bearer access_token

Here, access_token is the access key received in the POST /token response when sending grant_type = partner.

Obtaining token is necessary in the following cases:

• for authorisation via partner_id and partner_secret;
• for authorisation via client_id and client_secret;
• when updating the previous token for OAuth authorisation.

The token retrieval method is only available from the IP addresses that were specified in the API access application. If the account does not have whitelisted IP addresses or IP address checking was disabled, then it is not possible to receive a token.

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

• YooMoney
• QIWI
• WebMoney
• Bank Cards (VISA, Mastercard, Maestro, MIR)
• Bank accounts
• Mobile phone accounts (MTS, Beeline, Megafon, Tele2)
• To other ePayments clients or people who are not yet registered with the system (using email, phone number or e-Wallet number)

Please, note: payments to WebMoney are processed by ePayments within 30 minutes.

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 retracted from the sender’s e-Wallet after each mass payment. The exact amount depends on to which system the transfer was sent.

Currency and amount of transfer

Mass payment 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, then the ePayments system will perform a currency conversion using the rate set by ePayments. The exchange rate lifetime is 5 minutes. After the initial 5 minutes the exchange rate changes. This means that the transfer confirmation must be obtained within the said time limit. Otherwise, the payment amount will be calculated using the exchange rate that was relevant by the time the transfer was sent.

API methods for making a payment

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;
• 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 transferring funds from 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 2 different payments made by the same client will have different 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 operation. Confirmation is carried out by sending the confirmation parameter with the confirmation code in the request body.

This method is not suited for clients who are authorised via partner_id/ partner_secret. Such clients will receive transfer’s results immediately after using the payments method.

OAuth 2.0 authorisation is an authorisation via client_id and client_secret identifiers. This authorisation is necessary to gain access to your client’s data (e-Wallet number, verification date, etc.). These identifiers are generated on the ePayments side and are issued after an API integrator sends a separated request to the support team or personal manager.

Obtaining client’s data:

1. The API integrator needs to generate a link using the GET /account/authorize.
2. The resulting link must be sent to a client who has a verified account in ePayments.
3. After receiving the link, the client needs to follow the link, authorise in their account and provide access to the requested data.
4. After the client provides access to the data he/she will be redirected to the landing page which is presented in the following format: {{redirect_uri}}?code={{auth_code}}, here auth_code is the access key that is required for further authorisation.
5. The client needs to send auth_code from the landing page URL to the API integrator. The code lifetime is 2 minutes.
6. The API integrator must pass the received auth_code in the code parameter of the body of the POST /token request. The access_token will be sent in the response.
7. The API integrator must pass the received access_token in the request header GET /v1/getuser in order to gain access to clients’ data.

Re-receiving data:

Further data retrieval is possible without OAuth 2.0 authorisation. To do this, the API integrator must save the UserId from the first GET /v1/getuser request and then pass this UserId in the URL according to the following format: GET /v1/getuser/{userId}.

Header format for OAuth authorisation:

Content-type: application / json
Authorization: Bearer access_token

Here, access_token is the access key received in the POST /token response when passing grant_type = authorization_code.

The following is a request to generate a link that you will need to send to your verified client in order to pass OAuth 2.0 authorisation.

After opening the link, a client must:

1. Enter login and password for authorisation in ePayments (if this client has not been authorised).
2. Agree to provide access to his/her data (a list of data is sent in the scope parameter). If access to the data was granted previously, then this step will be skipped.

After gaining access to client’s data, it is necessary to pass the received auth_code using the POST /token method.

This method (hereinafter referred to as - getUser) is used to obtain detailed information about a client who provided access to his/her data. It is used only for OAuth authorisation.

This method allows to automatically fill in the client’s data that is already in the ePayments system.

If access to some data was not previously granted by a customer then the response will contain empty fields. If the client’s status is not Approved, then the method will return the 15002 error code and the response will contain values only for the id and userState parameters.

This method (hereinafter referred to as - getUser) is used to obtain detailed information about a client who provided access to his/her data. This method is used for partner_id authorisation if userId of the client’s is present.

In the absence of access to some client’s data, the fields in the response may be left empty. If the client’s status is not Approved, then the method will return the 15002 error 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 - 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.

Transfers to bank cards are carried out using the mass payment methods. To send a transfer to bank cards, one of the following parameters is specified as the recipient in the identity object:

• card - if you are using full card number;
• card_token - if you are using card’s token.

Before you can access transfers to bank cards on a live environment, you must fill out the SAQ forms:

• A completed SAQ-D form with an ASV report or Attestation of Compliance (AOC) PCI DSS certificate - if you want to send transfers using the full card number;
• A completed SAQ-A form - if you want to send transfer using the cards’ tokens.

These forms are requested in accordance with the PCI DSS rules under which ePayments operates. The completed form should be uploaded using the Add document menu in the Settings section of your personal account. Official guidelines on how to fill out forms can be found on the PCI DSS website.

Processing pending status

After the transfer to the card, the sender can check the status of the transfer by the identifier of the mass transfer - id or by the identifier of a single transfer - externalId. The processing of the transfer and the speed of obtaining the final status depends on the payment provider. In most cases, the transfer reaches its final status within a few minutes. But for some transfers to third-party bank cards, it can take 1 to 5 calendar days to get the final status.

For the cases presented below, the final status of the transfer can be obtained not earlier than the next day:

Case 1:

• The sender has an individual account in ePayments;
• The recipient’s card was issued on the territory of the Russian Federation;
• Received currency - Russian ruble.

Case 2:

• The recipient’s card was issued outside the Russian Federation;
• Payment system of the recipient’s card - VISA;
• Received currency - US dollar or Euro.

For the aforementioned case, the final status is obtained within 1 to 5 calendar days. This means that when checking the status of the transfer, the response may return status = pending. In this case, it is recommended to request the payment status according to the following frequency: every 30 seconds, 1 minute, 15 minutes, 30 minutes, 1 hour, 6 hours and then every 6 hours until the final status is received.

To transfer to a third-party issued card using token and not the card full number, you must use the tokenization method. Tokenization 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).

The tokenization 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.

Posting 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'
       }
   },
   fieldDropdownMenuList: {},
   fieldDropdownMenuItem: {},
   fieldDropdownMenuItemFocused: {}
};
var option = {
   root: '#root-widget',
   submitButton: 'submit-button',
   fields: [['number', 'expireDate'], ['embossingName'], ['countryOfResidence']],
   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. 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 to 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) attribute.

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 bankcard.

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 bank account 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 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.

This method (hereinafter referred to as - bankTemplateId) is used to obtain detailed template information. The unique identifier of the template is - templateId, transmitted as the request parameter. This parameter can be obtained by sending a request to get a list of all existing templates - bankTemplateList.

An outgoing bank transfer can be saved as a template if:

• outgoing bank transfer was executed successfully;
• the account linking feature is used.

This method (hereinafter referred to as – bankTemplateCreate) is used to create templates for outgoing bank transfers. Number and types of fields, which will be sent in the request, varies, depending on a bank transfer recipient country and type of currency used. After all required fields are filled and a payment form is completed a template will be saved.