Getting started

Getting started

Glossary

This website contains integration formats for the API provided by the ePayments system.

TermDescription
client_idA unique identifier (string constant), issued by the support department via the ticket system during API enablement process. Used as a means to bind clients and their cards to an account
client_secretA secret key (string constant), issued by the support department via ticket system during API enablement process. The key is issued together with the identifier (client_id) and is used to bind customers and their cards to your account
partner_idA unique identifier (number), issued by the support department via the ticket system during API enablement process
partner_secretA secret key. String constant (partner_secret) issued during the API enablement process. A key is issued alongside with the partner_id identifier by the support department via the ticket system
AuthorisationAuthorisation via partner_id and partner_secret, required for token acquisition and further sending of API requests
ClientAn ePayments client, who is providing access to their data
ReferralA User who is registered with ePayments using the referral’s link
End-to-end authorization (OAuth 2.0)An authorization process required to obtain access to your client’s data
Token (token)A one-time key to access API methods. Valid for one authentication session and for 20 minutes only. After that, either current token must be renewed or a new one acquired

Access to API

In order to obtain access to the ePayments API you must:

  1. Register in the ePayments system.
  2. Complete full account verification procedure.
  3. Submit an application form for API access. This can be done by reaching out to your personal manager or via the ticket system.

A request must include the following information:

  • the list of API requests you are planning to use;
  • RedirectURI if you are planning to use the client authorisation and getUser request. The RedirectURI must start from https, since working with http is not supported.

If the request is approved a personal manager or support team operator will send you unique ID partner_id and secret key partner_secret to gain access to the production environment API ePayments.

Before sending API requests, specify the IP addresses from which you are planning to access the ePayments API in your ePayments personal area (Settings>IP restrictions). Otherwise, access to the API will not be granted.

Access to the stage environment
You can also access the ePayments stage environment before attempting integration in the production environment. To do this, register with ePayments and contact your personal manager or support team operator. In the application, specify the list of IP addresses which you are planning to use to access the ePayments stage environment. In response to the application, access to the test account will be provided.

API requests

The following elements can be used as string variables while forming a request for API functions:

  • Latin letters
  • digits
  • space
  • special characters . ( ) : -_ ,
  • decimal separator – dot

URL addresses for accessing the ePayments API functions:

Stage: https://api.sandbox.epayments.com
Production: https://api.epayments.com
Stage environment instabilities
The staging environment can experience performance instabilities because it is used by ePayments to conduct testing. This is why temporary disruptions in financial operations, server unavailability, or deletion of some data can occur.

Payment details for test transfers
In order to execute test transfers to third-party systems, you will need to request test payment details from the ePayments support team. Attempt to use real payment details in a staging environment may result in some transactions being unavailable.

ePayments API supports requests in a JSON format. After the authorization is completed all API requests must contain the following header:

Authorization: Bearer ACCESS_TOKEN
Content-type: application/json


Text description of API errors is returned in one of the following languages: English, Spanish, Portuguese and Russian. By default, text descriptions are in English. To receive error messages in a different language you must add an (ISO639) language code to your request. For example, request for the Russian language will look like this:

Accept-Language: ru-RU


If an error occurs while trying to send an API request (for example, a 400 error code), it is possible to contact ePayments technical support directly. When contacting customer service the following data regarding API request must be provided:

  • x-request-id - the identifier that came in the header of the Response Headers response;
  • Error receiving time and time zone.

Authorisation

Authorisation

Obtaining Token

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.

post
/token
Request parameters
Authorization
string
required
header

This parameter is transmitted only for end-to-end authorisation (grant_type = authorization_code) and when updating a token for end-to-end authorisation (grant_type = refresh_token).

It accepts the value Basic GENERATED_STRING, where GENERATED_STRING – is a string, in the client_id:client_secret type format with base64 encoding.

Content-Type
string
required
header

application/x-www-form-urlencoded

Request body
grant_type
string
required
Possible values
partner_id
string
required

ID. Issued by ePayments

Example: 7854
partner_secret
string
required

Secret key. Issued by ePayments

Example: partner123
Request example
curl -X POST "https://api.epayments.com/token" -H  "accept: application/json" -H  "Content-Type: application/x-www-form-urlencoded" -d "grant_type=partner&partner_id=7854&partner_secret=partner123"
Responses
access_token
string
required

Access token for ePayments API

Example: Q2xpZW50SWQxMjM6Q2lKTk04eTNEWEZPaGc=
token_type
string
required

Token type. Value is always set as = bearer

Example: bearer
expires_in
string
required

Validity period for access_token or refresh_token. Specified in seconds

Example: 1200
refresh_token
string
required

Value to update the current Token value (RFC-6748#1.5)

Example: T3KMDFSIYkIztXHuWmIVGj2rujt6xlbW=
Response example
{
  "access_token": "Q2xpZW50SWQxMjM6Q2lKTk04eTNEWEZPaGc=",
  "token_type": "bearer",
  "expires_in": "1200",
  "refresh_token": "T3KMDFSIYkIztXHuWmIVGj2rujt6xlbW="
}

End-to-end authorisation

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.

get
/account/authorize
Request parameters
response_type
string
required
query

Request type. Value is always set as code

client_id
string
required
query

Client’s ID. Generated by the ePayments system and provided by customer service operators upon request

scope
string
required
query

Data you can request from your client. Values are transmitted as a string, using a comma to separate between elements. Use of spaces is not allowed:

  • ewallet – list of e-Wallet currency sections;
  • ewallet_balance – current e-Wallet balance;
  • cards – list of active ePayments cards;
  • cards_balance – ePayments cards balance;
  • address – list of verified addresses;
  • mobilephone – mobile phone number;
  • email – email address;
  • fullname – first and last name;
  • verificationdate – account verification date;
  • country - nationality and country of residence;
  • date_of_birth – date of birth
  • company_name - company name (for a business client);
  • company_jurisdiction - company jurisdiction (for a business client);
  • company_regnumber - company registration number (for a business client)
redirect_uri
string
required
query

An address a client will be redirected to upon completing authorisation (the domain of the indicated address should match with the principal domain in the application settings). The redirect_uri must start from https://, since working with http:// is not supported

Request example
curl -X GET "https://api.epayments.com/account/authorize?response_type=code&client_id=client958&scope=fullname%2Cewallet%2Caddress&redirect_uri=https%3A%2F%2Fpartner-site.com" -H  "accept: application/json"
Responses
code
string
required

The Code value, which is transmitted to the landing page URL. This Code must be obtained from the client and exchanged for a token within 2 minutes.

In order to exchange the code for a token the POST /token request with the grant_type=authorization_code in it must be submitted.

Example: g56732saq2
Response example
{
  "code": "g56732saq2"
}

Clients

Clients

Client data

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.

get
/v1/getuser
Request parameters
Authorization
string
required
header

Basic access_token, where the access_token is an access key, obtained in the response during client’s authorization

Content-Type
string
required
header

application/json

Request example
curl -X GET "https://api.epayments.com/v1/getuser" -H  "accept: application/json"
Responses
id
string

The unique identifier of the client. It can be subsequently transmitted for sending a getUser via id request during the partner_id authorisation

Example: 8bc876ef-773c-44e5-813d-e4dc392f134d
firstName
string

Client’s first name

Example: Mike
lastName
string

Client’s last name

Example: Nikmus
isVerified
boolean

Indicates if the client passed the verification process

Example: true
userState
string

Client’s status

Possible values
mobilePhone
string

Client mobile phone number

Example: +33 5896 585 44
email
string

Client’s email address

countryOfResidence
string

Country of residence

Example: United Kingdom
citizenship
string

Country of citizenship

Example: United Kingdom
verificationDate
string $date-time

Account verification date

Example: null
dateOfBirth
string $date-time

Client’s birth date

Example: null
ewallets
array of object

Information on e-Wallet

Show parameters
cards
array of object

Card information

Show parameters
addresses
array of object

Addresses information

Show parameters
company
object

Business client company information

Show parameters
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "id": "8bc876ef-773c-44e5-813d-e4dc392f134d",
  "firstName": "Mike",
  "lastName": "Nikmus",
  "isVerified": "true",
  "userState": "Approved",
  "mobilePhone": "+33 5896 585 44",
  "email": "[email protected]",
  "countryOfResidence": "United Kingdom",
  "citizenship": "United Kingdom",
  "verificationDate": "null",
  "dateOfBirth": "null",
  "ewallets": [
    {
      "ePid": "000-123456",
      "balances": [
        {
          "isSuccessed": "true",
          "currentBalance": "100.55",
          "hold": "0",
          "currency": "USD",
          "accountNumber": "000-123456",
          "accountType": "Ewallet"
        }
      ],
      "inLimit": "null",
      "outLimit": "null"
    }
  ],
  "cards": [
    {
      "id": "1234xxxxxxxx5678",
      "balance": "158.54",
      "cardCurrency": "USD"
    }
  ],
  "addresses": [
    {
      "countryIsoCode": "643",
      "postalCode": "109012",
      "city": "Moscow",
      "addressLine1": "Red Square",
      "addressLine2": "null",
      "addressLine3": "null"
    }
  ],
  "company": {
    "companyName": "Company LTD",
    "jurisdiction": "UK LLP",
    "companyNo": "123PX12345"
  },
  "errorCode": "0",
  "errorMsgs": "[]"
}

Client’s ID data

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.

get
/v1/getuser/{userId}
Request parameters
userId
string
required
path

Client’s unique identifier

Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-Type
string
required
header

application/json

Request example
curl -X GET "https://api.epayments.com/v1/getuser/8cd00aaf-7268-4024-9313-b082b1c51a40" -H  "accept: application/json"
Responses
id
string

The unique identifier of the client. It can be subsequently transmitted for sending a getUser via id request during the partner_id authorisation

Example: 8bc876ef-773c-44e5-813d-e4dc392f134d
firstName
string

Client’s first name

Example: Mike
lastName
string

Client’s last name

Example: Nikmus
isVerified
boolean

Indicates if the client passed the verification process

Example: true
userState
string

Client’s status

Possible values
mobilePhone
string

Client mobile phone number

Example: +33 5896 585 44
email
string

Client’s email address

countryOfResidence
string

Country of residence

Example: United Kingdom
citizenship
string

Country of citizenship

Example: United Kingdom
verificationDate
string $date-time

Account verification date

Example: null
dateOfBirth
string $date-time

Client’s birth date

Example: null
ewallets
array of object

Information on e-Wallet

Show parameters
cards
array of object

Card information

Show parameters
addresses
array of object

Addresses information

Show parameters
company
object

Business client company information

Show parameters
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "id": "8bc876ef-773c-44e5-813d-e4dc392f134d",
  "firstName": "Mike",
  "lastName": "Nikmus",
  "isVerified": "true",
  "userState": "Approved",
  "mobilePhone": "+33 5896 585 44",
  "email": "[email protected]",
  "countryOfResidence": "United Kingdom",
  "citizenship": "United Kingdom",
  "verificationDate": "null",
  "dateOfBirth": "null",
  "ewallets": [
    {
      "ePid": "000-123456",
      "balances": [
        {
          "isSuccessed": "true",
          "currentBalance": "100.55",
          "hold": "0",
          "currency": "USD",
          "accountNumber": "000-123456",
          "accountType": "Ewallet"
        }
      ],
      "inLimit": "null",
      "outLimit": "null"
    }
  ],
  "cards": [
    {
      "id": "1234xxxxxxxx5678",
      "balance": "158.54",
      "cardCurrency": "USD"
    }
  ],
  "addresses": [
    {
      "countryIsoCode": "643",
      "postalCode": "109012",
      "city": "Moscow",
      "addressLine1": "Red Square",
      "addressLine2": "null",
      "addressLine3": "null"
    }
  ],
  "company": {
    "companyName": "Company LTD",
    "jurisdiction": "UK LLP",
    "companyNo": "123PX12345"
  },
  "errorCode": "0",
  "errorMsgs": "[]"
}

ePayments cards

ePayments cards

Card list

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.

get
/v1/card
Request parameters
Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request example
curl -X GET "https://api.epayments.com/v1/card" -H  "accept: application/json"
Responses
cards
array of object

Detailed information about cards

Show parameters
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "cards": [
    {
      "displayString": "1234****5678",
      "id": "1234xxxxxxxx5678",
      "cardIdentity": "d55bdc1c-0511-4d0d-b6b7-b9e173e9f357",
      "balance": "550.8",
      "canBeReissued": "false",
      "allowAdjusment": "false",
      "cardType": "Real",
      "prevCardId": "null",
      "cardCurrency": "USD",
      "state": "Active",
      "cardPaid": "Paid",
      "deliveryPaid": "Paid",
      "deliveryMethod": 0,
      "deliveryAddressId": "160991",
      "creationDate": "2018-03-30T10:11:42.447Z",
      "cardServiceExpireAt": "2018-05-30T10:14:07.86Z",
      "cardServicePaid": "Free",
      "prerequestCreationDate": "2018-03-30T10:11:16.993Z",
      "embossingName": "CARDHOLDER NAME",
      "invoiceId": "886196",
      "creationType": 0,
      "inLimit": [
        {
          "identity": "000-123456",
          "limitAmount": "3000",
          "limitSpentAmount": "584.47",
          "currency": "USD",
          "period": "364000"
        }
      ],
      "outLimit": [
        {
          "identity": "000-123456",
          "limitAmount": "5000",
          "limitSpentAmount": "1862.01",
          "currency": "USD",
          "period": "364000"
        }
      ],
      "paymentDate": "2018-03-30T10:11:39.32Z",
      "vat": "20",
      "vdeExist": "true",
      "allowedCardOperationTypes": [
        "Adjusment"
      ],
      "purchases": "2985.57",
      "threshold": "300",
      "cardServicePeriod": 0,
      "trackingCodeUrl": "null",
      "trackingCode": "null"
    }
  ],
  "errorCode": "0",
  "errorMsgs": "[]"
}

Card unload

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

put
/v1/cardunload
Request parameters
Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request body
amount
number $float
required

Transaction amount. Decimal separator – dot. No more than two characters can be entered after a dot

Example: 100.00
targetPurse
string
required

The full number of the recipient’s ePayments e-Wallet in xxx-xxxxxx format

Example: 000-703454
cardPanCode
string
required

Sender’s masked ePayments card number in 1234xxxxxxxx5678 format. Only first and last 4 characters are shown. The rest are hidden and instead “x” are shown

Example: 5283xxxxxxxx2710
validateOnly
boolean

Transfer availability check:

  • true – checking only, no transaction execution;
  • false – transaction execution (set as default)
Example: false
Request example
{
  "amount": "100.00",
  "targetPurse": "000-703454",
  "cardPanCode": "5283xxxxxxxx2710",
  "validateOnly": "false"
}
Responses
cardBalance
object

Information about ePayments card balance

Show parameters
purseBalance
object

Information about ePayments e-Wallet

Show parameters
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "cardBalance": {
    "isSuccessed": "true",
    "currentBalance": "918.55",
    "hold": "0",
    "currency": "USD",
    "accountNumber": "1234хххххххх5678",
    "accountType": "Card"
  },
  "purseBalance": {
    "isSuccessed": "true",
    "currentBalance": "100.55",
    "hold": "0",
    "currency": "USD",
    "accountNumber": "000-123456",
    "accountType": "Ewallet"
  },
  "errorCode": "0",
  "errorMsgs": "[]"
}

Card load

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.

put
/v1/cardload
Request parameters
Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request body
sourcePurse
string
required

The full number of the ePayments e-Wallet in xxx-xxxxxx format, from which funds will be debited

Example: 000-725187
panCode
string
required

Masked ePayments card number to which funds will be loaded. Specified in 1234xxxxxxxx5678 format

Example: 5283xxxxxxxx5185
validateOnly
boolean

Transfer availability check:

  • true – checking only, no transaction execution;
  • false – transaction execution (set as default)
Example: false
amount
number $float
required

Transaction amount. Decimal separator – dot. No more than two characters can be entered after a dot

Example: 10.54
currency
string
required

Currency

Example: USD
Possible values
Request example
{
  "sourcePurse": "000-725187",
  "panCode": "5283xxxxxxxx5185",
  "validateOnly": "false",
  "amount": "10.54",
  "currency": "USD"
}
Responses
operationGuid
string

Unique transaction identifier. Can be used to send in the request for obtaining information about funds transfer status

Example: ad7322dc-0e8c-425a-95c5-67af5082c3ef
commissionAmount
number $float

Transaction fee

Example: 0
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "operationGuid": "ad7322dc-0e8c-425a-95c5-67af5082c3ef",
  "commissionAmount": "0",
  "errorCode": "0",
  "errorMsgs": "[]"
}

Card load status

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.

get
/v1/cardload
Request parameters
operationGuid
string
required
query

A unique transaction identifier. Obtained in the response to the cardLoad request

Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request example
curl -X GET "https://api.epayments.com/v1/cardload?operationGuid=ad7322dc-0e8c-425a-95c5-67af5082c3ef" -H  "accept: application/json"
Responses
purseBalance
number $float

e-Wallet balance after transaction execution

Example: 1810.06
cardBalance
number $float

Card balance after transaction execution

Example: 621.8
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "purseBalance": "1810.06",
  "cardBalance": "621.8",
  "errorCode": "0",
  "errorMsgs": "[]"
}

ePayments e-Wallet

ePayments e-Wallet

List of e-Wallets

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

get
/v1/ewallet
Request parameters
Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request example
curl -X GET "https://api.epayments.com/v1/ewallet" -H  "accept: application/json"
Responses
ewallets
array of object

Information on each currency section of the ePayments e-Wallet

Show parameters
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "ewallets": [
    {
      "ePid": "000-123456",
      "balances": [
        {
          "isSuccessed": "true",
          "currentBalance": "100.55",
          "hold": "0",
          "currency": "USD",
          "accountNumber": "000-123456",
          "accountType": "Ewallet"
        }
      ],
      "inLimit": [
        {
          "identity": "000-123456",
          "limitAmount": "3000",
          "limitSpentAmount": "584.47",
          "currency": "USD",
          "period": "364000"
        }
      ],
      "outLimit": [
        {
          "identity": "000-123456",
          "limitAmount": "5000",
          "limitSpentAmount": "1862.01",
          "currency": "USD",
          "period": "364000"
        }
      ]
    }
  ],
  "errorCode": "0",
  "errorMsgs": "[]"
}

Currency exchange

Currency exchange

Currency exchange

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.

post
/v1/currencyexchange
Request parameters
Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request body
buyCurrency
string
required

The end currency of an exchange. The value must be different from the value of the sellCurrency field.

  • usd
  • eur
  • rub
Example: usd
sellCurrency
string
required

The start currency of an exchange. The value must be different from the value of the buyCurrency field.

  • usd
  • eur
  • rub
Example: eur
sellAmount
number $float
required

The amount of the sold currency. Decimal separator – dot. No more than two digits can be entered after a dot. The parameter is passed only if the buyAmount parameter was not specified in the request

Example: 100
buyAmount
number $float

The amount of the purchasable currency. Decimal separator – dot. No more than two digits can be entered after a dot. The parameter is transmitted only if the sellAmount parameter was not specified in the request

Example: null
onlyCalculateRates
boolean

Preliminary currency exchange rate calculations without transaction execution:

  • true – preliminary calculation;
  • false – transaction execution (set as default)
Example: true
selectedPurseId
string
required

The ePayments e-Wallet ID for which currency exchange will be carried out. Set in the XXX-XXXXXX format. If someone else’s e-Wallet number is entered the corresponding error will return in response

Example: 000-123456
quoteHash
string

Currency exchange quotes hash code, which is set for the currency conversion. If the hash is not used within 5 minutes after the transfer procedure is initiated, then during the actual transfer currency will be converted using the rate relevant course

Request example
{
  "buyCurrency": "usd",
  "sellCurrency": "eur",
  "sellAmount": "100",
  "buyAmount": "null",
  "onlyCalculateRates": "true",
  "selectedPurseId": "000-123456",
  "quoteHash": "string"
}
Responses
give
object

Outgoing amount information

Show parameters
received
object

Incoming amount information

Show parameters
purseBalance
array of object

Balance information

Show parameters
exchangeQuote
object

Hash-code quotes information. It is returned only if the OnlyCalculateRates = true parameter was sent in the request

Show parameters
fixCommision
object

Fixed fee amount. If no fee is imposed, the value will be set as Null

Show parameters
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "give": {
    "amount": "100",
    "currency": "usd"
  },
  "received": {
    "amount": "86.41",
    "currency": "eur"
  },
  "purseBalance": [
    {
      "isSuccessed": "true",
      "currentBalance": "100.55",
      "hold": "0",
      "currency": "USD",
      "accountNumber": "000-123456",
      "accountType": "Ewallet"
    }
  ],
  "exchangeQuote": {
    "hash": "JhFkAWIDz8V50ucmO/C1K5xd3l6UWK==",
    "exchangeRate": "0.8093"
  },
  "fixCommision": {
    "amount": "2",
    "currency": "usd"
  },
  "errorCode": "0",
  "errorMsgs": "[]"
}

From cryptocurrency

From cryptocurrency

Available currencies

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.

get
/v1/exchange/crypto/availableCurrencies
Request parameters
Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request example
curl -X GET "https://api.epayments.com/v1/exchange/crypto/availableCurrencies" -H  "accept: application/json"
Responses
currencies
array of object

List of supported fiat currencies and cryptocurrencies

Show parameters
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "currencies": [
    {
      "currencyName": "BTC",
      "currencyType": "Crypto"
    }
  ],
  "errorCode": "0",
  "errorMsgs": "[]"
}

Recommended fees

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.

get
/v1/exchange/crypto/fees
Request parameters
Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request example
curl -X GET "https://api.epayments.com/v1/exchange/crypto/fees" -H  "accept: application/json"
Responses
fees
array of object

Information about fees (currency type and fee amount)

Show parameters
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "fees": [
    {
      "currency": "BTC",
      "recommendedFee": "0.0005",
      "refundFee": "0.001"
    }
  ],
  "errorCode": "0",
  "errorMsgs": "[]"
}

Payment execution

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.

put
/v1/exchange/crypto/convertFrom
Request parameters
Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request body
mode
string
required

Load from cryptocurrency mode

Possible values
fromAmount
number $float
required

Outgoing cryptocurrency transfer amount. Decimal separator – dot. No more than 8 digits can be entered after a dot. If the transfer amount is specified in thetoAmount field, then the fromAmount field may be left empty

toAmount
number $float
required

Incoming transfer amount. Decimal separator – dot. No more than 2 digits can be entered after a dot. If the transfer amount is specified in the fromAmount field, then the toAmount field may be left empty

Example: 200
addressForRefund
string
required

Refund cryptocurrency e-Wallet address. Only numbers and Latin letters can be entered. Length varies from 25 to 45 characters

Example: mpnyk2wTLN7pQsxnWPZnpCV4ZjRKb1HcK6
toCurrency
string
required

Currency

Example: USD
Possible values
fromCurrency
string
required

Cryptocurrency type. This parameter is not case sensitive

Example: BTC
Possible values
Request example
{
  "mode": "ValidateOnly",
  "fromAmount": 0,
  "toAmount": "200",
  "addressForRefund": "mpnyk2wTLN7pQsxnWPZnpCV4ZjRKb1HcK6",
  "toCurrency": "USD",
  "fromCurrency": "BTC"
}
Responses
exchangeRate
object

Information about currency exchange rate set for converting cryptocurrency into fiat currency. For the mode = ValidateAndExecute the value is set as Null

Show parameters
exchangeRateHash
string

Hash quotes for converting cryptocurrency into fiat currency

Example: MoU3DeTp1aL1PBAWIDz8V50ucmO/C1K5xd3l6UWK==
transactionId
integer

Transaction ID in the ePayments system. For the mode = ValidateOnly the parameter value is set as Null

Example: null
invoiceId
integer

Transaction ID in the ePayments system. For the mode = ValidateOnly the parameter value is set as Null

Example: null
cryptoWallet
string

e-Wallet to which cryptocurrency must be transferred before it can be converted into fiat currency. For the mode = ValidateOnly the value is set as Null

Example: null
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "exchangeRate": {
    "rateLifetime": "300",
    "fromCurrency": "BTC",
    "fromAmount": "0.03754",
    "toCurrency": "USD",
    "toAmount": "210"
  },
  "exchangeRateHash": "MoU3DeTp1aL1PBAWIDz8V50ucmO/C1K5xd3l6UWK==",
  "transactionId": "null",
  "invoiceId": "null",
  "cryptoWallet": "null",
  "errorCode": "0",
  "errorMsgs": "[]"
}

Payment status

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.

get
/v1/exchange/crypto/checkTransfer
Request parameters
invoiceId
integer
required
query

Transaction ID as set by the ePayments system. The value is obtained from the invoiceId parameter which is sent in the convertFrom method response

Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request example
curl -X GET "https://api.epayments.com/v1/exchange/crypto/checkTransfer?invoiceId=454767" -H  "accept: application/json"
Responses
transaction
object

Information on transfer status

Show parameters
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "transaction": {
    "status": "Completed",
    "errorCode": "0",
    "errorText": "null",
    "processDate": "2016-06-02T12:31:00.03Z"
  },
  "errorCode": "0",
  "errorMsgs": "[]"
}

To cryptocurrency

To cryptocurrency

Address validation

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.

post
/v1/FromPurseToCryptocurrency/checkAddress
Request parameters
Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request body
address
string
required

Cryptocurrency e-Wallet address. Only number and Latin letters can be entered. Length varies from 25 up to 45 characters

Example: mV9HWBVs8gy2ssFqQe3XNj5k4nn3AM6xF
currency
string
required

Cryptocurrency type. This parameter is not case sensitive

Example: BTC
Possible values
Request example
{
  "address": "mV9HWBVs8gy2ssFqQe3XNj5k4nn3AM6xF",
  "currency": "BTC"
}
Responses
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "errorCode": "0",
  "errorMsgs": "[]"
}

Conversion rate

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.

get
/v1/FromPurseToCryptocurrency
Request parameters
fromCurrency
string
required
query

Name of fiat currency which will be converted to cryptocurrency

Possible values
toCurrency
string
required
query

Name of cryptocurrency to which fiat will be converted

Possible values
fromAmount
number $float
query

Transfer amount in fiat currency. Decimal separator – dot. No more than two digits can be entered after a dot

toAmount
number $float
query

Transfer amount in cryptocurrency. Decimal separator – dot. No more than 8 digits can be entered after a dot

Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request example
curl -X GET "https://api.epayments.com/v1/FromPurseToCryptocurrency?fromCurrency=USD&toCurrency=BTC&fromAmount=100.00" -H  "accept: application/json"
Responses
exchangeRateId
integer

ID of conversion rate request made for transferring from fiat to cryptocurrency

Example: 24126196
fromAmount
number $float

The original transfer amount. Set in fiat currency

Example: 100
toAmount
number $float

The final transfer amount. Set in cryptocurrency

Example: 0.01213
fromCurrency
string

Currency

Example: USD
Possible values
toCurrency
string

Cryptocurrency type. This parameter is not case sensitive

Example: BTC
Possible values
networkFee
number $float

Network fee for transferring to cryptocurrency

Example: 0.001
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "exchangeRateId": "24126196",
  "fromAmount": "100",
  "toAmount": "0.01213",
  "fromCurrency": "USD",
  "toCurrency": "BTC",
  "networkFee": "0.001",
  "errorCode": "0",
  "errorMsgs": "[]"
}

Payment execution

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.
put
/v1/FromPurseToCryptocurrency
Request parameters
Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request body
purse
string
required

Sender’s ePayments e-wallet number in xxx-xxxxxx format

Example: 000-631703
cryptoAddress
string
required

Cryptocurrency e-Wallet address. Only numbers and Latin letters can be entered. Length varies from 25 up to 45 characters

Example: mmV9HWBVs8gy2ssFqQe3XNj5k4nn3AM6xF
fromAmount
number $float
required

Outgoing amount in fiat currency.

Corresponds with the fromAmount parameter from the cryptoExchange method response

Example: 100
toAmount
number $float
required

Incoming amount in cryptocurrency. Decimal separator – dot. No more than 8 digits can be entered after a dot

Corresponds with the toAmount parameter from the cryptoExchange method response

Example: 0.0391
networkFee
number $float
required

Network fee. Decimal separator – dot. No more than 8 digits can be entered after a dot

Corresponds with the networkFee parameter from the cryptoExchange method response

Example: 0.002
requestId
integer
required

Cross-rate request ID. This rate will be used during the transfer. It is not required if IsCalcOnly = true.

Corresponds with the exchangeRateId parameter from the cryptoExchange method response

Example: 5153449
fromCurrency
string
required

Currency

Example: USD
Possible values
toCurrency
string
required

Cryptocurrency type. This parameter is not case sensitive

Example: BTC
Possible values
isCalcOnly
boolean

Transaction execution mode:

  • true - preliminary calculation of transaction;
  • false - transaction execution
Example: false
confirmation
object

The “session - confirmation code” pair. It is sent only if confirmationSessionId and confirmationMessage, received after the first transfer request is submitted, are present

Show parameters
paymentTemplateId
integer

Transaction template ID. Used if a transaction is executed using template

Example: 462
Request example
{
  "purse": "000-631703",
  "cryptoAddress": "mmV9HWBVs8gy2ssFqQe3XNj5k4nn3AM6xF",
  "fromAmount": "100",
  "toAmount": "0.0391",
  "networkFee": "0.002",
  "requestId": "5153449",
  "fromCurrency": "USD",
  "toCurrency": "BTC",
  "isCalcOnly": "false",
  "confirmation": {
    "code": "180",
    "sessionId": "69b7039a-7c14-49da-881a-1016b9c62554"
  },
  "paymentTemplateId": "462"
}
Responses
invoiceId
integer

Invoice ID for requesting status of a transaction in case if the result of transfer to cryptocurrency is unknown

Example: 140038
guaranteedSuccess
boolean

Transaction processing status:

  • true – transaction processing was initiated;
  • false – transaction status is unknown. In such cases, you will need to request transaction status additionally
Example: true
confirmationSessionId
string

Confirmation session ID. The value is set as Null

Example: null
confirmationMessage
string

Message for the client with a reminder to enter the transaction confirmation code. The value is set as Null

Example: null
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "invoiceId": "140038",
  "guaranteedSuccess": "true",
  "confirmationSessionId": "null",
  "confirmationMessage": "null",
  "errorCode": "0",
  "errorMsgs": "[]"
}

Payment status

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

get
/v1/FromPurseToCryptocurrency/getTransaction
Request parameters
invoiceId
integer
required
query

ID of transfer to cryptocurrency. It is received in the response of the FromPurseToCryptocurrency method.

Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request example
curl -X GET "https://api.epayments.com/v1/FromPurseToCryptocurrency/getTransaction?invoiceId=454767" -H  "accept: application/json"
Responses
transaction
object

Information on transfer status

Show parameters
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "transaction": {
    "status": "Completed",
    "errorCode": "0",
    "errorText": "null",
    "processDate": "2016-06-02T12:31:00.03Z"
  },
  "errorCode": "0",
  "errorMsgs": "[]"
}

Mass payments

Mass payments

Available transactions

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
Mass payment to WebMoney
Mass payments to WebMoney are only available after an additional request is submitted to WebMoney and approved on their side. To obtain such an approval, open “Payments and Transfers > Mass Payments > To WebMoney e-Wallet” in your e-Payment personal area. There fill and submit the application form.

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

Transfer amount
For the transfer request, the sender can specify transfer amount only in one field:
- in the From field - meaning the amount that will be debited from the sender's e-Wallet, or;
- in the To field - meaning the amount that will be credited to the recipient's account.


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.

Preliminary calculation

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.

Fee calculation
The transfer fee is not included and not shown in the initial transaction amount (it is paid by the sender in addition to the transaction amount).
Currency conversion
If currency conversion is required, then the currency field should be filled for both parameters – from and to. The selected currency types must be different (for example, RUB in “from” and EUR in "to"). If only one currency field is filled or currency types are the same, then the currency conversion will not be performed. If currency conversion is not performed, the values of the Quote and Rate fields will be set as Null.
post
/v2/payments/preflight
Request parameters
Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request body
payments
array of object
required

Information about all transfers occurring within one mass payment. One mass payment can include from 1 to 500 transactions

Show parameters
Request example
{
  "payments": [
    {
      "from": {
        "provider": "eWallet",
        "currency": "USD",
        "amount": "20.00",
        "identity": "000-123123"
      },
      "to": {
        "provider": "qiwi",
        "amount": "20.00",
        "identity": "+79000123456",
        "currency": "USD"
      },
      "details": "details for payment",
      "externalId": "transfer_to_client",
      "quote": "ldxbasjqwewr4423hfcsdv23g24rfd9ew45tgfs==",
      "metadata": {}
    }
  ]
}
Responses
dateStarted
string $date-time
nullable

Mass payments start time. Value set as Null

Example: null
dateFinished
string $date-time
nullable

Mass payments completion time. Value set as Null

Example: null
state
string
required

Overall transaction status for selected mass payment. Value set as New

Possible values
id
string
nullable

Mass payment identifier within the ePayments system. Value set as Null

Example: null
self
string
nullable

Link to the information about the mass payment. Value set as Null

Example: null
payments
array of object

Information about all transfers occurring within one mass payment. One mass payment can include from 1 to 500 transactions

Show parameters
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "dateStarted": "null",
  "dateFinished": "null",
  "state": "New",
  "id": "null",
  "self": "null",
  "payments": [
    {
      "id": "null",
      "from": {
        "provider": "eWallet",
        "currency": "USD",
        "amount": "20.00",
        "identity": "000-123123"
      },
      "to": {
        "provider": "qiwi",
        "amount": "20.00",
        "identity": "+79000123456",
        "currency": "USD"
      },
      "details": "details for payment",
      "externalId": "transfer_to_client",
      "quote": "ldxbasjqwewr4423hfcsdv23g24rfd9ew45tgfs==",
      "metadata": {},
      "rate": "1.48",
      "quoteExpireIn": "8556",
      "dateStarted": "null",
      "dateFinished": "null",
      "state": "New",
      "errorCode": 0,
      "errorData": [
        "string"
      ],
      "errorMsgs": [
        "string"
      ]
    }
  ],
  "errorCode": "0",
  "errorMsgs": "[]"
}

Calculation of fees

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.

post
/v2/payments/fees
Request parameters
Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request body
payments
array of object
required

Information about all transfers occurring within one mass payment. One mass payment can include from 1 to 500 transactions

Show parameters
Request example
{
  "payments": [
    {
      "from": {
        "provider": "eWallet",
        "currency": "USD",
        "amount": "20.00",
        "identity": "000-123123"
      },
      "to": {
        "provider": "qiwi",
        "amount": "20.00",
        "identity": "+79000123456",
        "currency": "USD"
      },
      "details": "details for payment",
      "externalId": "transfer_to_client",
      "quote": "ldxbasjqwewr4423hfcsdv23g24rfd9ew45tgfs==",
      "metadata": {}
    }
  ]
}
Responses
dateStarted
string $date-time
nullable

Mass payments start time. Value set as Null

Example: null
dateFinished
string $date-time
nullable

Mass payments completion time. Value set as Null

Example: null
state
string
required

Overall transaction status for selected mass payment. Value set as New

Possible values
id
string
nullable

Mass payment identifier within the ePayments system. Value set as Null

Example: null
self
string
nullable

Link to the information about the mass payment. Value set as Null

Example: null
payments
array of object

Information about all transfers occurring within one mass payment. One mass payment can include from 1 to 500 transactions

Show parameters
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "dateStarted": "null",
  "dateFinished": "null",
  "state": "New",
  "id": "null",
  "self": "null",
  "payments": [
    {
      "id": "null",
      "from": {
        "provider": "eWallet",
        "currency": "USD",
        "amount": "20.00",
        "identity": "000-123123"
      },
      "to": {
        "provider": "qiwi",
        "amount": "20.00",
        "identity": "+79000123456",
        "currency": "USD"
      },
      "details": "details for payment",
      "externalId": "transfer_to_client",
      "quote": "ldxbasjqwewr4423hfcsdv23g24rfd9ew45tgfs==",
      "metadata": {},
      "rate": "1.48",
      "quoteExpireIn": "8556",
      "dateStarted": "null",
      "dateFinished": "null",
      "state": "New",
      "errorCode": 0,
      "errorData": [
        "string"
      ],
      "errorMsgs": [
        "string"
      ]
    }
  ],
  "errorCode": "0",
  "errorMsgs": "[]"
}

Payment execution

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.

Authorisation specific
If the the partner_id/partner_secret authorisation was used, then the response message to the POST v2/payments request will automatically contain transfer results, since usage of the confirmation method is not required for said authorisation type.
post
/v2/payments
Request parameters
Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request body
payments
array of object
required

Information about all transfers occurring within one mass payment. One mass payment can include from 1 to 500 transactions

Show parameters
Request example
{
  "payments": [
    {
      "from": {
        "provider": "eWallet",
        "currency": "USD",
        "amount": "20.00",
        "identity": "000-123123"
      },
      "to": {
        "provider": "qiwi",
        "amount": "20.00",
        "identity": "+79000123456",
        "currency": "USD"
      },
      "details": "details for payment",
      "externalId": "transfer_to_client",
      "quote": "ldxbasjqwewr4423hfcsdv23g24rfd9ew45tgfs==",
      "metadata": {}
    }
  ]
}
Responses
dateStarted
string $date-time

Mass payments start time

Example: 2018-04-09T12:22:41.8123172Z
dateFinished
string $date-time

Mass payments completion time. Its value is set only after all transactions in this mass payment have been processed

Example: 2018-04-09T12:22:41.9735298Z
state
string
required

Overall transaction status for selected mass payment

Example: Completed
Possible values
id
string

Mass payment identifier within the ePayments system

Example: 8f78fed1-ee85-45dd-86c8-c6d76aa1b562
self
string

Link to the information about mass payment; is the same as one in the response to the paymentsId request

Example: /v2/payments/8f78fed1-ee85-45dd-86c8-c6d76aa1b562
payments
array of object

Information about all transfers occurring within one mass payment. One mass payment can include from 1 to 500 transactions

Show parameters
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "dateStarted": "2018-04-09T12:22:41.8123172Z",
  "dateFinished": "2018-04-09T12:22:41.9735298Z",
  "state": "Completed",
  "id": "8f78fed1-ee85-45dd-86c8-c6d76aa1b562",
  "self": "/v2/payments/8f78fed1-ee85-45dd-86c8-c6d76aa1b562",
  "payments": [
    {
      "id": "e0f51e44-dde6-430b-b1f1-96af2b6d2e45",
      "from": {
        "provider": "eWallet",
        "currency": "USD",
        "amount": "20.00",
        "identity": "000-123123"
      },
      "to": {
        "provider": "qiwi",
        "amount": "20.00",
        "identity": "+79000123456",
        "currency": "USD"
      },
      "details": "details for payment",
      "externalId": "transfer_to_client",
      "quote": "ldxbasjqwewr4423hfcsdv23g24rfd9ew45tgfs==",
      "metadata": {},
      "rate": "1.48",
      "quoteExpireIn": "8556",
      "dateStarted": "2018-04-09T12:22:41.8123172Z",
      "dateFinished": "2018-04-09T12:22:41.9735298Z",
      "state": "Completed",
      "errorCode": 0,
      "errorData": [
        "string"
      ],
      "errorMsgs": [
        "string"
      ]
    }
  ],
  "errorCode": "0",
  "errorMsgs": "[]"
}

Payment status (externalId)

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.

get
/v2/payments
Request parameters
externalId
string
required
query

The unique payment ID. Specified in the request body payments. Requirements:

  • length - no more than 60 characters;
  • no spaces between characters;
  • only Latin letters, numbers and special characters such as / . -_ can be used.
Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request example
curl -X GET "https://api.epayments.com/v2/payments?externalId=external_client" -H  "accept: application/json"
Responses
dateStarted
string $date-time

Mass payments start time

Example: 2018-04-09T12:22:41.8123172Z
dateFinished
string $date-time

Mass payments completion time. Its value is set only after all transactions in this mass payment have been processed

Example: 2018-04-09T12:22:41.9735298Z
state
string
required

Overall transaction status for selected mass payment

Example: Completed
Possible values
id
string

Mass payment identifier within the ePayments system

Example: 8f78fed1-ee85-45dd-86c8-c6d76aa1b562
self
string

Link to the information about mass payment; is the same as one in the response to the paymentsId request

Example: /v2/payments/8f78fed1-ee85-45dd-86c8-c6d76aa1b562
payments
array of object

Information about all transfers occurring within one mass payment. One mass payment can include from 1 to 500 transactions

Show parameters
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "dateStarted": "2018-04-09T12:22:41.8123172Z",
  "dateFinished": "2018-04-09T12:22:41.9735298Z",
  "state": "Completed",
  "id": "8f78fed1-ee85-45dd-86c8-c6d76aa1b562",
  "self": "/v2/payments/8f78fed1-ee85-45dd-86c8-c6d76aa1b562",
  "payments": [
    {
      "id": "e0f51e44-dde6-430b-b1f1-96af2b6d2e45",
      "from": {
        "provider": "eWallet",
        "currency": "USD",
        "amount": "20.00",
        "identity": "000-123123"
      },
      "to": {
        "provider": "qiwi",
        "amount": "20.00",
        "identity": "+79000123456",
        "currency": "USD"
      },
      "details": "details for payment",
      "externalId": "transfer_to_client",
      "quote": "ldxbasjqwewr4423hfcsdv23g24rfd9ew45tgfs==",
      "metadata": {},
      "rate": "1.48",
      "quoteExpireIn": "8556",
      "dateStarted": "2018-04-09T12:22:41.8123172Z",
      "dateFinished": "2018-04-09T12:22:41.9735298Z",
      "state": "Completed",
      "errorCode": 0,
      "errorData": [
        "string"
      ],
      "errorMsgs": [
        "string"
      ]
    }
  ],
  "errorCode": "0",
  "errorMsgs": "[]"
}

Payment status (id)

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.

Payment final status
This API method is needed to obtain the final status of a mass payment sent to a third-party system using payment's identifier. Any further actions regarding mass payment handling should be made based on the method response.
get
/v2/payments/{id}
Request parameters
id
string
required
path

Mass Payment identifier

Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request example
curl -X GET "https://api.epayments.com/v2/payments/8cd00aaf-7268-4024-9313-b082b1c51a40" -H  "accept: application/json"
Responses
dateStarted
string $date-time

Mass payments start time

Example: 2018-04-09T12:22:41.8123172Z
dateFinished
string $date-time

Mass payments completion time. Its value is set only after all transactions in this mass payment have been processed

Example: 2018-04-09T12:22:41.9735298Z
state
string
required

Overall transaction status for selected mass payment

Example: Completed
Possible values
id
string

Mass payment identifier within the ePayments system

Example: 8f78fed1-ee85-45dd-86c8-c6d76aa1b562
self
string

Link to the information about mass payment; is the same as one in the response to the paymentsId request

Example: /v2/payments/8f78fed1-ee85-45dd-86c8-c6d76aa1b562
payments
array of object

Information about all transfers occurring within one mass payment. One mass payment can include from 1 to 500 transactions

Show parameters
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "dateStarted": "2018-04-09T12:22:41.8123172Z",
  "dateFinished": "2018-04-09T12:22:41.9735298Z",
  "state": "Completed",
  "id": "8f78fed1-ee85-45dd-86c8-c6d76aa1b562",
  "self": "/v2/payments/8f78fed1-ee85-45dd-86c8-c6d76aa1b562",
  "payments": [
    {
      "id": "e0f51e44-dde6-430b-b1f1-96af2b6d2e45",
      "from": {
        "provider": "eWallet",
        "currency": "USD",
        "amount": "20.00",
        "identity": "000-123123"
      },
      "to": {
        "provider": "qiwi",
        "amount": "20.00",
        "identity": "+79000123456",
        "currency": "USD"
      },
      "details": "details for payment",
      "externalId": "transfer_to_client",
      "quote": "ldxbasjqwewr4423hfcsdv23g24rfd9ew45tgfs==",
      "metadata": {},
      "rate": "1.48",
      "quoteExpireIn": "8556",
      "dateStarted": "2018-04-09T12:22:41.8123172Z",
      "dateFinished": "2018-04-09T12:22:41.9735298Z",
      "state": "Completed",
      "errorCode": 0,
      "errorData": [
        "string"
      ],
      "errorMsgs": [
        "string"
      ]
    }
  ],
  "errorCode": "0",
  "errorMsgs": "[]"
}

Payment confirmation

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.

put
/v2/payments/{id}/confirmation
Request parameters
id
string
required
path

Mass Payment identifier

Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request body
confirmation
string
required

Transaction confirmation code. Instructions on how to obtain the code are transmitted in the message parameter, which comes in the response to the payments request.

Example: 184
Request example
{
  "confirmation": "184"
}
Responses
dateStarted
string $date-time

Mass payments start time

Example: 2018-04-09T12:22:41.8123172Z
dateFinished
string $date-time

Mass payments completion time. Its value is set only after all transactions in this mass payment have been processed

Example: 2018-04-09T12:22:41.9735298Z
state
string
required

Overall transaction status for selected mass payment

Example: Completed
Possible values
id
string

Mass payment identifier within the ePayments system

Example: 8f78fed1-ee85-45dd-86c8-c6d76aa1b562
self
string

Link to the information about mass payment; is the same as one in the response to the paymentsId request

Example: /v2/payments/8f78fed1-ee85-45dd-86c8-c6d76aa1b562
payments
array of object

Information about all transfers occurring within one mass payment. One mass payment can include from 1 to 500 transactions

Show parameters
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "dateStarted": "2018-04-09T12:22:41.8123172Z",
  "dateFinished": "2018-04-09T12:22:41.9735298Z",
  "state": "Completed",
  "id": "8f78fed1-ee85-45dd-86c8-c6d76aa1b562",
  "self": "/v2/payments/8f78fed1-ee85-45dd-86c8-c6d76aa1b562",
  "payments": [
    {
      "id": "e0f51e44-dde6-430b-b1f1-96af2b6d2e45",
      "from": {
        "provider": "eWallet",
        "currency": "USD",
        "amount": "20.00",
        "identity": "000-123123"
      },
      "to": {
        "provider": "qiwi",
        "amount": "20.00",
        "identity": "+79000123456",
        "currency": "USD"
      },
      "details": "details for payment",
      "externalId": "transfer_to_client",
      "quote": "ldxbasjqwewr4423hfcsdv23g24rfd9ew45tgfs==",
      "metadata": {},
      "rate": "1.48",
      "quoteExpireIn": "8556",
      "dateStarted": "2018-04-09T12:22:41.8123172Z",
      "dateFinished": "2018-04-09T12:22:41.9735298Z",
      "state": "Completed",
      "errorCode": 0,
      "errorData": [
        "string"
      ],
      "errorMsgs": [
        "string"
      ]
    }
  ],
  "errorCode": "0",
  "errorMsgs": "[]"
}

Bank cards

Bank cards

Payment execution

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.

Tokenization set up

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>
ParameterDescription
div id=" "The identifier or class that is responsible for the location of the bank card data entry form on within the web page. The id value is set arbitrarily. There are no restrictions regarding which characters can be entered on the ePayments side. The value for this id must match the value of the root parameter from the var option variable (see the Javascript example below)
button id=" "The identifier that collects data from the recipient’s bank card. After clicking on the submit button, on the ePayments side, the data is processed and sent as a token



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 &lt;script&gt; tag. The link format depends on in which environment it is used:


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

ParameterDescription
var styleVariable for the stylisation of a bank card data entry form. By default the standard style is used. It is also possible to change the appearance of the form in accordance with the design of the site
var optionVariable to create a data entry form. As a value, it uses a list of input fields, form language, styles, etc
var widgetA variable consisted of a form object (with parameters passed to the var option) and methods for interacting with the bank card data entry form (for example, addEventListener)
widget.addEventListenerAn event for processing a request to receive a token, which will later be transferred to a bank card. Accepts events:
- tokenCreateSuccess - an event that is triggered when the request to receive a token is successfully processed;
- tokenCreateError - an event that is triggered when the request for a token is not processed successfully. After successful processing of the request, function (data) is called, which accepts the token object



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

ParameterDescription
widgetA set of CSS-styles for the bank data entry form (for example, color, font-size, etc.)
fieldAny form string. One line can consist of several fields intended for input. For example, by default, the first line of the form contains two input elements - the card number and the card’s expiration date
fieldInputElements input field. For example card number, expiration date, and cardholder name
fieldInputPlaceholderHint text inside the field that disappears when a value is entered (for example, for the expireDate field it can be “DD/YY”)
fieldInputControlField filling style
fieldSubmitConfirm button style
fieldSubmitErrorError panel style



Var option parameters

ParameterDescription
rootThe name of the parameter that is responsible for the location of the data entry form for a bank card. The parameter value is the same as the id value from the div tag. Required parameter
submitButtonThe name of the parameter that is responsible for the location of the button to confirm the sending of data by credit card
fieldsParameters that will be specified by the client in the input form:
- number - card number (required field);
- expireDate - expiration date (optional);
- embossingName - the name of the cardholder (required field)
sidRandom id. Used in the formation of a signature to the request. Any alphanumeric character set is allowed for input (no restrictions on the ePayments side)
partnerIdUnique identifier. Issued during integration. Numeric field
signSignature request. Formed as an MD5 hash string (PartnerId;PartnerSecret;sid). PartnerSecret - a unique key issued during integration
langThe language of the data entry form: ru - Russian, en - English. If the language is not explicitly specified, it is determined by the browser. If the browser failed to determine the language, then the default is “en”
styleConnecting personalized styling input form. The style value is the name of the variable that is responsible for styling the form (for the example above, the value is style). If the default styling is used, the style attribute is not passed



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.

ParameterDescription
Card numberCard masked number. Only the first 6 and last 4 digits are shown (regardless of the card’s full number length). The rest of the digits will be masked. For example, for the card with 19 digits in its full number the display will be as following: 1234 56** **** ***7 890
Card expiration dateCard validity period in the MM / YY format. Validity period cannot be less than the current month and year
Card holderCardholder’s Name. It consists of Latin letters, without special characters. Field length from 2 to 100 characters


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": []
}

Token data

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

get
/v2/payments/cards/token/{token_id}
Request parameters
token_id
string
required
path

Unique token identifier

Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request example
curl -X GET "https://api.epayments.com/v2/payments/cards/token/8cd00aaf-7268-4024-9313-b082b1c51a40" -H  "accept: application/json"
Responses
token
object

Information about card token

Show parameters
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "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": "20",
    "name": "Alex Mackitney",
    "fingerprint": "F1BE4A4450EEE42F64CC62C8BB1C0C8938FCBBDB2782F891CDF7F09505910F5F"
  },
  "errorCode": "0",
  "errorMsgs": "[]"
}

Token removal

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

delete
/v2/payments/cards/token/{token_id}
Request parameters
token_id
string
required
path

Unique token identifier

Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request example
curl -X DELETE "https://api.epayments.com/v2/payments/cards/token/8cd00aaf-7268-4024-9313-b082b1c51a40" -H  "accept: application/json"
Responses
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with error description

Example: card with tokenid = xxx has been successfully deleted
Response example
{
  "errorCode": "0",
  "errorMsgs": "card with tokenid = xxx has been successfully deleted"
}

Currencies

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.

Note
ePayments does not have any information regarding the currency of the recipient's card. Therefore, if the type of currency transferred does not match the type of currency expected by the receiving bank, the payment funds will be converted to different currency or declined altogether.
get
/v2/payments/externalcard/currencies/{bin}
Request parameters
bin
string
required
path

Card BIN number - the first 6 digits of its full number. This number is required to determine the card’s country of issue

Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request example
curl -X GET "https://api.epayments.com/v2/payments/externalcard/currencies/448315" -H  "accept: application/json"
Responses
cardCurrencies
array of string

The list of currencies in which transfer to bank card can be conducted. Currencies are transmitted as ISO three-character codes

cardCountry
string

Issuing bank country. Value is transmitted as ISO two-character codes

Example: RU
bankName
string

Name of the recipient bank. If bank name was not found, the return value will be set as Null

Example: null
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "cardCurrencies": [
    "USD"
  ],
  "cardCountry": "RU",
  "bankName": "null",
  "errorCode": "0",
  "errorMsgs": "[]"
}

Bank accounts

Bank accounts

Payment execution

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.

Transfer conditions

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.

get
/v2/payments/wireout/countryTerms
Request parameters
countryIsoCode
string
required
query

Digital ISO country code of a recipient bank for which a list of additional parameters is requested. Consists of 3 digits

currency
string
query

Transfer currency ISO code. Consist of 3 symbols

requestCurrencyPairs
boolean
query

Obtaining of information on transfer currencies available for the specified country:

  • true (set as default) - display currencies;
  • false - do not display currencies
beneficiaryType
string
query

Beneficiary type. Values are set either as characters or as numerical combination. Parameter is case sensitive:

  • Business - 1 (legal entity);
  • Individual - 2 (individual);
  • SelfEmployment - 3 (individual entrepreneur)
Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request example
curl -X GET "https://api.epayments.com/v2/payments/wireout/countryTerms?countryIsoCode=840&currency=EUR&requestCurrencyPairs=true&beneficiaryType=1" -H  "accept: application/json"
Responses
currencies
array of object

Currency pairs which can be used for wire transfer to the beneficiary bank in a specified country

Show parameters
additionalFields
array of object

Additional fields that must be filled for the beneficiary bank in a specified country (in addition to the general fields). If additional fields are not provided for the specified country, then additionalFields=null

Show parameters
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "currencies": [
    {
      "fromCurrency": "EUR",
      "toCurrency": "USD"
    }
  ],
  "additionalFields": [
    {
      "field": "purposeOfPayment",
      "isRequired": "true",
      "isForPaymentOnly": "false",
      "regex": "null",
      "placeholder": "null",
      "maxLength": "null",
      "values": [
        {
          "label": "Payroll Deposit PAY/PAY",
          "value": "200"
        }
      ]
    }
  ],
  "errorCode": "0",
  "errorMsgs": "[]"
}

Countries

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

get
/v2/payments/wireout/countries
Request parameters
Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request example
curl -X GET "https://api.epayments.com/v2/payments/wireout/countries" -H  "accept: application/json"
Responses
countryIsoCodes
array of string

The list of countries available for a bank transfer. Returned as a list of ISO three-digit codes

Example: [008, 012, 016]
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "countryIsoCodes": "[008, 012, 016]",
  "errorCode": "0",
  "errorMsgs": "[]"
}

Currencies

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.

get
/v2/catalog/currencies/{currency}
Request parameters
currency
string
required
path

The value of the currency for which additional information regarding transfer is required. Transmitted as ISO three-character code. If the currency value is not specified in the request, then the response will return information on all supported currencies

Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request example
curl -X GET "https://api.epayments.com/v2/catalog/currencies/vnd" -H  "accept: application/json"
Responses
currencies
array of object

Information on currencies

Show parameters
Response example
{
  "currencies": [
    {
      "title": "VND",
      "integral": "true"
    }
  ]
}

Bank templates

Bank templates

List of templates

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.

get
/v2/payments/wireout/templates
Request parameters
Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request example
curl -X GET "https://api.epayments.com/v2/payments/wireout/templates" -H  "accept: application/json"
Responses
templates
array of object

Get a list of templates

Show parameters
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "templates": [
    {
      "templateId": "45800",
      "bankName": "Sberbank",
      "templateName": "New transfer",
      "bankIdentity": "BKENGB2L",
      "beneficiaryName": "Alina Titomyr",
      "beneficiaryAccount": "60-16-13 31926819",
      "currencyCode": "usd"
    }
  ],
  "errorCode": "0",
  "errorMsgs": "[]"
}

Template information

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.

get
/v2/payments/wireout/templates/{templateId}
Request parameters
templateId
integer
required
path

A unique identifier saved template identifier. It is passed in the response of the get templates list request

Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request example
curl -X GET "https://api.epayments.com/v2/payments/wireout/templates/225591" -H  "accept: application/json"
Responses
template
object

In this object, all possible parameters of a bank wire are transmitted. This also includes additional parameters specific to the beneficiary country name, bank name and beneficiary type. If the country name, currency type and beneficiary type listed in the transfer template are not required, in the template objects their value will be passed as Null

Show parameters
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "template": {
    "templateName": "My regular bank transfer",
    "beneficiaryCountryCode": "076",
    "beneficiaryCity": "San Paolo",
    "beneficiaryAddress": "Av. Paulista, 1450",
    "beneficiaryType": "Individual",
    "beneficiaryRegistrationNumber": "null",
    "beneficiaryCnaps": "null",
    "beneficiaryAccount": {
      "account": "652457652125",
      "bankName": "The Central Bank of the Russian Federation",
      "bankIdentity": "FRDTEY98",
      "bicRussia": "123456789",
      "bankCountryCode": "643"
    },
    "currencyCode": "usd",
    "beneficiaryName": "Nikolaus Hilton",
    "beneficiaryFirstName": "Nikolaus",
    "beneficiaryLastName": "Hilton",
    "beneficiaryPatronymic": "null",
    "beneficiaryINN": "null",
    "beneficiaryKPP": "null",
    "beneficiaryPostCode": "null",
    "beneficiaryStateOrProvince": "null",
    "beneficiaryAba": "null",
    "beneficiarySortCode": "null",
    "beneficiaryBankCode": "076",
    "beneficiaryBranchCode": "6985",
    "beneficiaryAccountType": "SA",
    "beneficiaryAccountNumberSuffix": "null",
    "beneficiaryCPF": "2345678901",
    "beneficiaryCNPJ": "null",
    "purposeOfPayment": 200,
    "intermediaryAccount": {
      "account": "652457652125",
      "bankName": "The Central Bank of the Russian Federation",
      "bankIdentity": "FRDTEY98",
      "bicRussia": "123456789",
      "bankCountryCode": "643"
    }
  },
  "errorCode": "0",
  "errorMsgs": "[]"
}

Template creation

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

  • it 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.

put
/v3/payments/wireout/templates
Request parameters
Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request body
templateName
string

Template name. Any number of characters can be entered. Numbers, space, characters in any language and special characters {}?!.,;:’`&"/± can be used. If this parameter is not sent or sent empty, the template name will be saved in the bankName + ", " + beneficiaryName format

Example: New name for transfer to Mike
currencyCode
string
required

Currency

Possible values
beneficiaryType
string
required

Beneficiary type

Possible values
beneficiaryRegistrationNumber
string
required

Beneficiary registration number

Example: null
beneficiaryCountryCode
string
required

ISO country number of the beneficiary bank. Length - 3 digits

Example: 840
beneficiaryCity
string
required

Beneficiary city

Example: Michigan
beneficiaryAddress
string
required

Beneficiary address

Example: 611 West Ottawa
beneficiaryAccount
object
required

Information about the recipient’s account

Show parameters
beneficiaryName
string

Bank transfer beneficiary name. For the beneficiaryType = Individual the value is set as Null

Example: Nikolaus Hilton
beneficiaryFirstName
string

Bank transfer beneficiary name. For the beneficiaryType = Business the value is set as Null

Example: Nikolaus
beneficiaryLastName
string

Bank transfer beneficiary last name. For the beneficiaryType = Business the value is set as Null

Example: Hilton
beneficiaryPatronymic
string

Beneficiary patronymic

Example: null
beneficiaryINN
string

Beneficiary TIN

Example: null
beneficiaryKPP
string

Beneficiary KPP - Tax Registration Reason Code

Example: null
beneficiaryPostCode
string

Beneficiary postcode

Example: null
beneficiaryStateOrProvince
string

Beneficiary State

Example: null
beneficiaryAba
string

Beneficiary bank’s ABA-number. Additional parameter

Example: null
beneficiarySortCode
string

Beneficiary bank code. Used only for specific countries

Example: null
beneficiaryBankCode
string

Beneficiary bank code. Issued by the central bank of the country

Example: 076
beneficiaryBranchCode
string

Beneficiary bank branch code

Example: 6985
beneficiaryAccountType
string

Beneficiary account type

Possible values
beneficiaryAccountNumberSuffix
string

Beneficiary account number suffix

Example: null
beneficiaryCPF
string

TIN number for individuals in Brazil (Cadastro de Pessoas Físicas)

Example: 2345678901
beneficiaryCNPJ
string

TIN number for legal entities in Brazil (Cadastro Nacional da Pessoa Jurídica)

Example: null
purposeOfPayment
string

Bank transfer purpose.

Send if:

  • beneficiaryCountryCode = 050 (Bangladesh); currencyCode = BDT; length - 6 characters;
  • beneficiaryCountryCode = 076 (Brazil); currencyCode = BRL; length - 6 characters;
  • beneficiaryCountryCode = 356 (India); currencyCode = INR; length - 6 characters
  • beneficiaryCountryCode = 124 (Canada); currencyCode = CAD; length - 3 characters;
  • beneficiaryCountryCode = 840 (USA); currencyCode = USD; length- 3 characters;
  • beneficiaryCountryCode = 608 (Philippines); currencyCode = PHP; length- 3 characters
Possible values
intermediaryAccount
object

Information about the recipient’s account

Show parameters
Request example
{
  "templateName": "New name for transfer to Mike",
  "currencyCode": "usd",
  "beneficiaryType": "Individual",
  "beneficiaryRegistrationNumber": "null",
  "beneficiaryCountryCode": "840",
  "beneficiaryCity": "Michigan",
  "beneficiaryAddress": "611 West Ottawa",
  "beneficiaryAccount": {
    "account": "652457652125",
    "bankName": "The Central Bank of the Russian Federation",
    "bankIdentity": "FRDTEY98",
    "bicRussia": "123456789",
    "bankCountryCode": "643"
  },
  "beneficiaryName": "Nikolaus Hilton",
  "beneficiaryFirstName": "Nikolaus",
  "beneficiaryLastName": "Hilton",
  "beneficiaryPatronymic": "null",
  "beneficiaryINN": "null",
  "beneficiaryKPP": "null",
  "beneficiaryPostCode": "null",
  "beneficiaryStateOrProvince": "null",
  "beneficiaryAba": "null",
  "beneficiarySortCode": "null",
  "beneficiaryBankCode": "076",
  "beneficiaryBranchCode": "6985",
  "beneficiaryAccountType": "SA",
  "beneficiaryAccountNumberSuffix": "null",
  "beneficiaryCPF": "2345678901",
  "beneficiaryCNPJ": "null",
  "purposeOfPayment": 200,
  "intermediaryAccount": {
    "account": "652457652125",
    "bankName": "The Central Bank of the Russian Federation",
    "bankIdentity": "FRDTEY98",
    "bicRussia": "123456789",
    "bankCountryCode": "643"
  }
}
Responses
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
errorData
string
nullable

The list of incorrectly filled fields. Is only necessary for outgoing bank transfers if when carrying out the operation the errorCode=53003 was returned. In all other cases the errorData value set as Null

Example: null
Response example
{
  "errorCode": "0",
  "errorMsgs": "[]",
  "errorData": "null"
}

Template editing

This method (hereinafter referred to as – bankTemplateEdit) is used to edit parameters of already existing bank transfer templates. All mandatory template parameters must be sent in the request body. New values of all parameters that are subject to the change must be sent as well. Except for the templateId parameter, all others parameters can be changed.

post
/v3/payments/wireout/templates
Request parameters
Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request body
templateId
integer
required

A unique saved template identifier. It is transmitted in the response of the bankTemplateList method

Example: 57425
templateName
string

Template name. Any number of characters can be entered. Numbers, space, characters in any language and special characters {}?!.,;:’`&"/± can be used. If this parameter is not sent or sent empty, the template name will be saved in the bankName + ", " + beneficiaryName format

Example: New name for transfer to Mike
currencyCode
string
required

Currency

Possible values
beneficiaryType
string
required

Beneficiary type

Possible values
beneficiaryRegistrationNumber
string
required

Beneficiary registration number

Example: null
beneficiaryCountryCode
string
required

ISO country number of the beneficiary bank. Length - 3 digits

Example: 840
beneficiaryCity
string
required

Beneficiary city

Example: Michigan
beneficiaryAddress
string
required

Beneficiary address

Example: 611 West Ottawa
beneficiaryAccount
object
required

Information about the recipient’s account

Show parameters
beneficiaryName
string

Bank transfer beneficiary name. For the beneficiaryType = Individual the value is set as Null

Example: Nikolaus Hilton
beneficiaryFirstName
string

Bank transfer beneficiary name. For the beneficiaryType = Business the value is set as Null

Example: Nikolaus
beneficiaryLastName
string

Bank transfer beneficiary last name. For the beneficiaryType = Business the value is set as Null

Example: Hilton
beneficiaryPatronymic
string

Beneficiary patronymic

Example: null
beneficiaryINN
string

Beneficiary TIN

Example: null
beneficiaryKPP
string

Beneficiary KPP - Tax Registration Reason Code

Example: null
beneficiaryPostCode
string

Beneficiary postcode

Example: null
beneficiaryStateOrProvince
string

Beneficiary State

Example: null
beneficiaryAba
string

Beneficiary bank’s ABA-number. Additional parameter

Example: null
beneficiarySortCode
string

Beneficiary bank code. Used only for specific countries

Example: null
beneficiaryBankCode
string

Beneficiary bank code. Issued by the central bank of the country

Example: 076
beneficiaryBranchCode
string

Beneficiary bank branch code

Example: 6985
beneficiaryAccountType
string

Beneficiary account type

Possible values
beneficiaryAccountNumberSuffix
string

Beneficiary account number suffix

Example: null
beneficiaryCPF
string

TIN number for individuals in Brazil (Cadastro de Pessoas Físicas)

Example: 2345678901
beneficiaryCNPJ
string

TIN number for legal entities in Brazil (Cadastro Nacional da Pessoa Jurídica)

Example: null
purposeOfPayment
string

Bank transfer purpose.

Send if:

  • beneficiaryCountryCode = 050 (Bangladesh); currencyCode = BDT; length - 6 characters;
  • beneficiaryCountryCode = 076 (Brazil); currencyCode = BRL; length - 6 characters;
  • beneficiaryCountryCode = 356 (India); currencyCode = INR; length - 6 characters
  • beneficiaryCountryCode = 124 (Canada); currencyCode = CAD; length - 3 characters;
  • beneficiaryCountryCode = 840 (USA); currencyCode = USD; length- 3 characters;
  • beneficiaryCountryCode = 608 (Philippines); currencyCode = PHP; length- 3 characters
Possible values
intermediaryAccount
object

Information about the recipient’s account

Show parameters
Request example
{
  "templateId": "57425",
  "templateName": "New name for transfer to Mike",
  "currencyCode": "usd",
  "beneficiaryType": "Individual",
  "beneficiaryRegistrationNumber": "null",
  "beneficiaryCountryCode": "840",
  "beneficiaryCity": "Michigan",
  "beneficiaryAddress": "611 West Ottawa",
  "beneficiaryAccount": {
    "account": "652457652125",
    "bankName": "The Central Bank of the Russian Federation",
    "bankIdentity": "FRDTEY98",
    "bicRussia": "123456789",
    "bankCountryCode": "643"
  },
  "beneficiaryName": "Nikolaus Hilton",
  "beneficiaryFirstName": "Nikolaus",
  "beneficiaryLastName": "Hilton",
  "beneficiaryPatronymic": "null",
  "beneficiaryINN": "null",
  "beneficiaryKPP": "null",
  "beneficiaryPostCode": "null",
  "beneficiaryStateOrProvince": "null",
  "beneficiaryAba": "null",
  "beneficiarySortCode": "null",
  "beneficiaryBankCode": "076",
  "beneficiaryBranchCode": "6985",
  "beneficiaryAccountType": "SA",
  "beneficiaryAccountNumberSuffix": "null",
  "beneficiaryCPF": "2345678901",
  "beneficiaryCNPJ": "null",
  "purposeOfPayment": 200,
  "intermediaryAccount": {
    "account": "652457652125",
    "bankName": "The Central Bank of the Russian Federation",
    "bankIdentity": "FRDTEY98",
    "bicRussia": "123456789",
    "bankCountryCode": "643"
  }
}
Responses
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
errorData
string
nullable

The list of incorrectly filled fields. Is only necessary for outgoing bank transfers if when carrying out the operation the errorCode=53003 was returned. In all other cases the errorData value set as Null

Example: null
Response example
{
  "errorCode": "0",
  "errorMsgs": "[]",
  "errorData": "null"
}

Affiliate program

Affiliate program

About the program

The ePayments Affiliate Program is a service which allows ePayments clients to receive rewards or remunerations for financial transactions made by their referrals.

Referrals are clients who have registered in the ePayments system using a special referral link and who will also have the opportunity to join the affiliate program.

Stages of working with the affiliate program

In order to participate in the affiliate program and to receive remuneration you will need to:

  1. Create a referral link or use an automatically generated link.
  2. Send the referral link to your clients/contractors/employees.
  3. Wait for them to register using the link and to become your referrals.
  4. Receive remuneration from transactions made by referrals. Specifically, those transactions for which remuneration may be credited.
  5. Transfer rewards to your ePayments e-Wallet.

Remuneration

Remuneration is monetary funds in one of three currencies: USD, RUB and EUR. They are paid to you from the fee income of ePayments. The client can transfer their remuneration to their ePayments e-Wallet at any time in a 1:1 ratio.

Remuneration amount and the list of eligible transactions are listed in the client’s personal area of the ePayments system in the “Affiliate Program” section. For more information about the affiliate program please visit the Help Center.

Referrals and their levels

Remuneration can be charged from level 1 and level 2 referrals. Clients who are registered via your referral link are Level 1 referrals. By creating and using their own referral links, they can bring new clients. These clients will become your Level 2 referrals.

Link creation

This method (hereinafter referred to as - linkCreate) is used to create a referral link. A referral link is a unique link which, when used as a registration invite for new clients, linking them to the owner of the link. Linking clients to provides the link owner profile with remunerations for the operations conducted by the clients.

When you join the affiliate program, the first referral link will be created automatically. After that, you will be able to create any number of referral links manually using a personal account or API methods.

put
/v2/bonus/link
Request parameters
Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request body
partnerLink
string

Referral link name. If the parameter is not sent in the request body, then the name will be generated automatically and returned in the request response.

Field length varies from 1 up to 100 characters. Numbers, letters of the Latin alphabet, as well as the special characters "-" and “_” can be entered

redirectUrl
string
required

URL to which client will be redirected after clicking on a referral link. URL must contain the domain epayments.com. Use of any other domains is forbidden

Example: https://www.epayments.com/ru/ewallet_tariffs.html
Request example
{
  "partnerLink": "string",
  "redirectUrl": "https://www.epayments.com/ru/ewallet_tariffs.html"
}
Responses
id
integer

Referral link ID

Example: 225591
createdAt
string $date-time

Referral link creation time

Example: 2018-04-30T12:03:39.852Z
updatedAt
string $date-time

Time referral link was last edited

Example: 2018-04-30T12:03:39.852Z
partnerLink
string

Referral link name. If the parameter is not sent in the request body, then the name will be generated automatically and returned in the request response

Example: ldlklx1289
redirectUrl
string

URL to which client will be redirected after clicking on a referral link

Example: https://www.epayments.com/ru/ewallet_tariffs.html
state
integer

Link activity status

Possible values
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "id": "225591",
  "createdAt": "2018-04-30T12:03:39.852Z",
  "updatedAt": "2018-04-30T12:03:39.852Z",
  "partnerLink": "ldlklx1289",
  "redirectUrl": "https://www.epayments.com/ru/ewallet_tariffs.html",
  "state": 0,
  "errorCode": "0",
  "errorMsgs": "[]"
}

Link editing

This method (hereinafter referred to as - linkEdit) is used to edit the name of an existing referral link. If the specified link does not belong to the client, then editing will not be possible and the corresponding error will be returned in the method response (errorCode=54018).

The name of the referral link must be unique within ePayments. When you change the name of the link, the old name will remain in the system and becomes available for use by other clients. This means that if any potential clients will use the link with the old name, they will not become your referrals.

post
/v2/bonus/link/{linkId}
Request parameters
linkId
integer
required
path

Referral link ID. It is transmitted in the response to the link creation request

Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request body
partnerLink
string
required

New referral link name. Field length varies from 3 up to 100 characters. Numbers, letters of the Latin alphabet, as well as the special characters "-" and “_” can be entered

Example: new_partnerlink_name
Request example
{
  "partnerLink": "new_partnerlink_name"
}
Responses
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "errorCode": "0",
  "errorMsgs": "[]"
}

Link removal

This method (hereinafter referred to as - linkDelete) is used to delete/remove a referral link. If the specified link does not belong to the client, then removal will be prohibited and the corresponding error will be returned in the method response (errorCode=54018).

A deleted link can be restored within 30 days after its removal. To restore the link you will need to send a request linkRestore. After 30 days, the link and all statistics on it will be permanently deleted.

delete
/v2/bonus/link/{linkId}
Request parameters
linkId
integer
required
path

Referral link ID. It is transmitted in the response to the link creation request

Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request example
curl -X DELETE "https://api.epayments.com/v2/bonus/link/225591" -H  "accept: application/json"
Responses
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "errorCode": "0",
  "errorMsgs": "[]"
}

Link recovering

This method (hereinafter referred to as - linkRestore) is used to restore deleted referral link. Links can be restored within 30 days after their removal.

If the specified link does not belong to the client, then the corresponding error will be returned in the method response (errorCode=54018).

post
/v2/bonus/link/{linkId}/restore
Request parameters
linkId
integer
required
path

Referral link ID. It is transmitted in the response to the link creation request

Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request example
curl -X POST "https://api.epayments.com/v2/bonus/link/225591/restore" -H  "accept: application/json"
Responses
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "errorCode": "0",
  "errorMsgs": "[]"
}

Reward payout

This method (hereinafter referred to as - linkPayout) is used when transferring the remuneration to your own ePayments e-Wallet. If someone else’s ePayments e-Wallet number is used, remuneration transfer will be canceled.

Remuneration amount is always paid in full, with no option to enter any specific transfer amount.

Remuneration is transferred to the corresponding e-Wallet currency section (conversion into a single currency type is not possible). For example, a client is eligible for the remunerations in the amount of 15 USD and 500 RUB. After sending the remuneration payment request, monetary funds will be transferred to the client’s e-Wallet, accordingly – 15 USD to the USD section of the e-wallet, and 500 RUB to the RUB section. The EUR section balance will not be changed.

post
/v2/bonus/payout
Request parameters
Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request body
provider
string
required

Remuneration recipient. Value is always set as = ewallet

Example: eWallet
identity
string
required

Recipient’s ID, i.e. ePayments e-Wallet number in the xxx-xxxxxx format. The e-Wallet indicated must belong to the owner of the referral link, according to which the remuneration is paid

Example: 012-345678
Request example
{
  "provider": "eWallet",
  "identity": "012-345678"
}
Responses
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "errorCode": "0",
  "errorMsgs": "[]"
}

Clicks statistics

This method (hereinafter referred to as - linkClicksStat) is used to obtain information on clicks and registrations for each referral link. The method returns information on all referral links (active and temporarily removed).

get
/v2/bonus/statistics
Request parameters
from
string $date
required
query

Clicks and registrations statistic display start date. Transmitted in one of the following formats:

  • YYYY-DD-MM
  • YYYY/MM/DD
  • YYYY.MM.DD
  • DD-MM-YYYY
  • DD/MM/YYYY
  • DD.MM.YYYY
to
string $date
required
query

Clicks and registrations statistic display end date. Transmitted in one of the following formats:

  • YYYY-DD-MM
  • YYYY/MM/DD
  • YYYY.MM.DD
  • DD-MM-YYYY
  • DD/MM/YYYY
  • DD.MM.YYYY
Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request example
curl -X GET "https://api.epayments.com/v2/bonus/statistics?from=04-01-2017&to=10-01-2017" -H  "accept: application/json"
Responses
statistics
object

Information regarding clicks on links and registrations carried out. This object also displays overall statistics for each day, if at least one click or one registration took place

Show parameters
links
array of object

Referral links data, including separate statistics for each link on how many times the link was clicked on and how many people registered afterward

Show parameters
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "statistics": {
    "total": {
      "clicks": "5",
      "registrations": "1"
    },
    "days": {
      "2017- 10-11": {
        "clicks": "5",
        "registrations": "1"
      },
      "2017- 10-19": {
        "clicks": "5",
        "registrations": "1"
      }
    }
  },
  "links": [
    {
      "id": "89196",
      "info": {
        "id": "89196",
        "createdAt": "2017-09-26T15:57:16.184Z",
        "updatedAt": "2017-09-26T15:57:16.184Z",
        "code": "1111234",
        "url": "https://www.epayments.com",
        "state": "InTrash",
        "userId": "131d1d4f-80f6-4967-a609-a1c0aac792dc"
      },
      "statistics": {
        "total": {
          "clicks": "5",
          "registrations": "1"
        },
        "days": {
          "2017- 10-11": {
            "clicks": "5",
            "registrations": "1"
          },
          "2017- 10-19": {
            "clicks": "5",
            "registrations": "1"
          }
        }
      }
    }
  ],
  "errorCode": "0",
  "errorMsgs": "[]"
}

Reward statistics

This method (hereinafter - linkFinanceStat) is used to obtain information on remunerations paid to the client as part of the affiliate program.

get
/v2/bonus/statistics/finance
Request parameters
from
string $date
required
query

Clicks and registrations statistic display start date. Transmitted in one of the following formats:

  • YYYY-DD-MM
  • YYYY/MM/DD
  • YYYY.MM.DD
  • DD-MM-YYYY
  • DD/MM/YYYY
  • DD.MM.YYYY
to
string $date
required
query

Clicks and registrations statistic display end date. Transmitted in one of the following formats:

  • YYYY-DD-MM
  • YYYY/MM/DD
  • YYYY.MM.DD
  • DD-MM-YYYY
  • DD/MM/YYYY
  • DD.MM.YYYY
Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request example
curl -X GET "https://api.epayments.com/v2/bonus/statistics/finance?from=04-01-2017&to=10-01-2017" -H  "accept: application/json"
Responses
balances
object

Information about remunerations: current balance, the balance on the date of remuneration accrual and the total balance - all displayed in a single currency

Show parameters
links
array of object

Information about all transfers occurring within one mass payment. One mass payment can include from 1 to 500 transactions

Show parameters
excahgeRates
object

Information about the internal currency exchange rate for each currency type

Show parameters
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "balances": {
    "total": {
      "eur": {
        "hold": "0",
        "balance": "0",
        "cancelled": "0",
        "paidOut": "150"
      },
      "rub": {
        "hold": "20",
        "balance": "0",
        "cancelled": "0",
        "paidOut": "513.23"
      },
      "usd": {
        "hold": "0",
        "balance": "0",
        "cancelled": "350.6",
        "paidOut": "872.36"
      }
    },
    "days": {
      "2017- 06-26": {
        "usd": {
          "holdDelta": "0",
          "balanceDelta": "0",
          "canceledDelta": "0",
          "paidOutDelta": "0"
        }
      }
    },
    "aggregated": {
      "eur": {
        "hold": "0.26",
        "balance": "0",
        "cancelled": "283.74",
        "paidOut": "862.57"
      },
      "rub": {
        "hold": "20",
        "balance": "0",
        "cancelled": "21625.04",
        "paidOut": "65455.19"
      },
      "usd": {
        "hold": "0.31",
        "balance": "0",
        "cancelled": "350.6",
        "paidOut": "1056.09"
      }
    }
  },
  "links": [
    {
      "id": "201256",
      "balances": {
        "total": {
          "first": {
            "eur": {
              "holdDelta": "0",
              "balanceDelta": "30",
              "canceledDelta": "0"
            },
            "rub": {
              "holdDelta": "20",
              "balanceDelta": "147.2",
              "canceledDelta": "0"
            },
            "usd": {
              "holdDelta": "153.84",
              "balanceDelta": "86.16",
              "canceledDelta": "0"
            }
          },
          "all": {
            "eur": {
              "holdDelta": "0",
              "balanceDelta": "30",
              "canceledDelta": "0"
            },
            "rub": {
              "holdDelta": "20",
              "balanceDelta": "147.2",
              "canceledDelta": "0"
            },
            "usd": {
              "holdDelta": "153.84",
              "balanceDelta": "86.16",
              "canceledDelta": "0"
            }
          }
        },
        "days": {
          "2018- 03-14": {
            "first": {
              "rub": {
                "holdDelta": "20",
                "balanceDelta": "147.2",
                "canceledDelta": "0"
              }
            },
            "all": {
              "rub": {
                "holdDelta": "20",
                "balanceDelta": "147.2",
                "canceledDelta": "0"
              }
            }
          }
        }
      },
      "invoices": {
        "total": {
          "first": {
            "eur": {
              "holdDelta": "0",
              "balanceDelta": "30",
              "canceledDelta": "0"
            },
            "rub": {
              "holdDelta": "20",
              "balanceDelta": "147.2",
              "canceledDelta": "0"
            },
            "usd": {
              "holdDelta": "153.84",
              "balanceDelta": "86.16",
              "canceledDelta": "0"
            }
          },
          "all": {
            "eur": {
              "holdDelta": "0",
              "balanceDelta": "30",
              "canceledDelta": "0"
            },
            "rub": {
              "holdDelta": "20",
              "balanceDelta": "147.2",
              "canceledDelta": "0"
            },
            "usd": {
              "holdDelta": "153.84",
              "balanceDelta": "86.16",
              "canceledDelta": "0"
            }
          }
        },
        "days": {
          "2018- 03-14": {
            "first": {
              "rub": {
                "holdDelta": "20",
                "balanceDelta": "147.2",
                "canceledDelta": "0"
              }
            },
            "all": {
              "rub": {
                "holdDelta": "20",
                "balanceDelta": "147.2",
                "canceledDelta": "0"
              }
            }
          }
        },
        "aggregated": {
          "eur": {
            "hold": "0.26",
            "balance": "0",
            "cancelled": "283.74",
            "paidOut": "862.57"
          },
          "rub": {
            "hold": "20",
            "balance": "0",
            "cancelled": "21625.04",
            "paidOut": "65455.19"
          },
          "usd": {
            "hold": "0.31",
            "balance": "0",
            "cancelled": "350.6",
            "paidOut": "1056.09"
          }
        }
      }
    }
  ],
  "excahgeRates": {
    "eur": {
      "rub": "74.2314",
      "usd": "1.1722"
    },
    "rub": {
      "eur": "0.0128",
      "usd": "0.0154"
    },
    "usd": {
      "eur": "0.8093",
      "rub": "61.6801"
    }
  },
  "errorCode": "0",
  "errorMsgs": "[]"
}

Transactions

Transactions

Transactions list

This method (hereinafter referred to as - transactions) is used for returning a transactions list with specified parameters. If JSON in the request body parameters was left empty, then the response will include information regarding all transaction for the past 7 days (including current date).

Selection dates
If selection dates were not specified in the request body (using from and till parameters) then, the response will contain information about transactions from the last week, as by default. If no transactions were conducted during this week, then regardless of the value of the other request parameters, the response will be empty.
post
/v2/transactions
Request parameters
Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request body
direction
string

Transaction direction

Possible values
from
string $date-time

Date and time values starting from which transactions will be displayed. Specified in the UnixTimeStamp format

Example: 1541961595
till
string $date-time

Date and time values indicating the end of a selection. Specified in the UnixTimeStamp format

Example: 1541961539
take
integer

Number of transactions returned. Default value is 10 transactions. Maximum value is 20

Example: 2
skip
integer

Number of elements which should be skipped in the primary sample selection. Default value is =0

Example: 0
operationId
integer

Transaction (invoice) ID

Example: 896547
transactionId
integer

Transaction ID

Example: 6905108
receiverIdentity
string

Recipient’s ID (for example, their ePayments e-Wallet number). Maximum length – 100 characters

Example: 001-333665
externalId
string

The external ID of the transaction

Example: uniqueId
typeIdentity
string

ePayments e-Wallet number

Example: 000-123321
currency
string

Currency

Possible values
destinations
integer

Transaction purpose

Example: 1
Request example
{
  "direction": "In",
  "from": "1541961595",
  "till": "1541961539",
  "take": "2",
  "skip": "0",
  "operationId": "896547",
  "transactionId": "6905108",
  "receiverIdentity": "001-333665",
  "externalId": "uniqueId",
  "typeIdentity": "000-123321",
  "currency": "USD",
  "destinations": "1"
}
Responses
transactions
array of object

Detailed information on transactions

Show parameters
from
string $date-time

Selection start date. If no time period was specified in the request body parameters, then in the response, the value of the from parameter will be changed to a default – last week. For example, if the current date is 10.05.2018, then “from” value will be set as = 2018-05-03T00:00:00Z

Example: 2018-05-03T00:00:00Z
till
string $date-time

Selection end date. If no time period was specified in the request body parameters, then in the response, the value of the till parameter will be changed to a default – the end of the current day. For example, if the current date is 10.05.2018, then “till” = 2018-05-10T23:59:59Z

Example: 2018-05-10T23:59:59Z
count
integer

The number of entries in the selected period

Example: 1
in
object

Transaction amount for each currency section

Show parameters
out
object

Transaction amount for each currency section

Show parameters
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "transactions": [
    {
      "operationId": "896547",
      "receiverIdentity": "001-333665",
      "externalId": "uniqueId",
      "transactionId": "6905108",
      "direction": "In",
      "operation": {
        "date": "2018-11-06T15:10:13.155622Z",
        "type": "0",
        "typeCode": "Other",
        "displayName": "Transfer between the e-Wallet sections"
      },
      "source": {
        "type": "ewallet",
        "identity": "000-123321"
      },
      "destination": {
        "type": "ewallet",
        "identity": "000-123321"
      },
      "details": "Currency exchange from RUB to USD. Rate = 0.0169",
      "currency": "USD",
      "fee": "0",
      "total": "1.69",
      "amount": "1.69",
      "unRead": "true",
      "txnAmount": "0",
      "txnCurrency": "null",
      "startBalance": "0",
      "endBalance": "375.12",
      "refunded": "null",
      "billConvRate": "0",
      "state": "null",
      "massPaymentId": "null"
    }
  ],
  "from": "2018-05-03T00:00:00Z",
  "till": "2018-05-10T23:59:59Z",
  "count": "1",
  "in": {
    "usd": "1.0",
    "eur": "2.0",
    "rub": "3.0"
  },
  "out": {
    "usd": "1.0",
    "eur": "2.0",
    "rub": "3.0"
  },
  "errorCode": "0",
  "errorMsgs": "[]"
}

Last transactions

This method (hereinafter referred to as - transactionsLast) is used for obtaining detailed information on recent transactions.

get
/v1/transactions/last
Request parameters
take
integer
required
query

Number of most recent transactions. Value can range from 5 to 20

Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request example
curl -X GET "https://api.epayments.com/v1/transactions/last?take=10" -H  "accept: application/json"
Responses
transactions
array of object

Transaction details

Show parameters
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "transactions": [
    {
      "transactionId": "6905108",
      "direction": "In",
      "operation": {
        "date": "2018-11-06T15:10:13.155622Z",
        "type": "0",
        "typeCode": "Other",
        "displayName": "Transfer between the e-Wallet sections"
      },
      "source": {
        "type": "ewallet",
        "identity": "000-123321"
      },
      "destination": {
        "type": "ewallet",
        "identity": "000-123321"
      },
      "details": "Currency exchange from RUB to USD. Rate = 0.0169",
      "currency": "USD",
      "fee": "0",
      "total": "1.69",
      "amount": "1.69",
      "unRead": "true",
      "txnAmount": "0",
      "txnCurrency": "null",
      "startBalance": "0",
      "endBalance": "375.12",
      "refunded": "null",
      "billConvRate": "0",
      "state": "null",
      "massPaymentId": "null"
    }
  ],
  "errorCode": "0",
  "errorMsgs": "[]"
}

Transaction details

This method (hereinafter referred to as - transactionsId) is used to obtain detailed information about a specific transaction. The request can be sent only if a transaction was made using ePayments e-Wallet.

get
/v1/transactions/{id}
Request parameters
id
integer
required
path

Transaction number

Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request example
curl -X GET "https://api.epayments.com/v1/transactions/6905109" -H  "accept: application/json"
Responses
purseId
integer

ePayments e-Wallet ID

Example: 725187
transactions
array of object

Transaction details

Show parameters
from
string $date-time

Selection start date. If no time period was specified in the request body parameters, then in the response, the value of the from parameter will be changed to a default – last week. For example, if the current date is 10.05.2018, then from = 2018-05-03T00:00:00Z

Example: 2018-05-03T00:00:00Z
till
string $date-time

Selection end date. If no time period was specified in the request body parameters, then in the response, the value of the till parameter will be changed to a default – the end of the current day. For example, if the current date is 10.05.2018, then till = 2018-05-10T23:59:59Z

Example: 2018-05-10T23:59:59Z
count
integer

The number of entries in the selected period

Example: 1
in
object

Transaction amount for each currency section

Show parameters
out
object

Transaction amount for each currency section

Show parameters
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "purseId": "725187",
  "transactions": [
    {
      "transactionId": "6905108",
      "direction": "In",
      "operation": {
        "date": "2018-11-06T15:10:13.155622Z",
        "type": "0",
        "typeCode": "Other",
        "displayName": "Transfer between the e-Wallet sections"
      },
      "source": {
        "type": "ewallet",
        "identity": "000-123321"
      },
      "destination": {
        "type": "ewallet",
        "identity": "000-123321"
      },
      "details": "Currency exchange from RUB to USD. Rate = 0.0169",
      "currency": "USD",
      "fee": "0",
      "total": "1.69",
      "amount": "1.69",
      "unRead": "true",
      "txnAmount": "0",
      "txnCurrency": "null",
      "startBalance": "0",
      "endBalance": "375.12",
      "refunded": "null",
      "billConvRate": "0",
      "state": "null",
      "massPaymentId": "null"
    }
  ],
  "from": "2018-05-03T00:00:00Z",
  "till": "2018-05-10T23:59:59Z",
  "count": "1",
  "in": {
    "usd": "1.0",
    "eur": "2.0",
    "rub": "3.0"
  },
  "out": {
    "usd": "1.0",
    "eur": "2.0",
    "rub": "3.0"
  },
  "errorCode": "0",
  "errorMsgs": "[]"
}

Guidebooks

Guidebooks

Currencies list

This method (hereinafter referred to as – currencies) is used for obtaining a complete list of currencies defined in the ePayments system. However, each outgoing or incoming transaction will have its own list of defined currencies. This means that not all available currencies can or will participate in a specific transaction.

get
/v1/catalog/currencies
Request parameters
Authorization
string
required
header

Bearer access_token, where the access_token – an access key, obtained in the response during authorisation

Content-type
string
required
header

application/json

Request example
curl -X GET "https://api.epayments.com/v1/catalog/currencies" -H  "accept: application/json"
Responses
currencies
array of string

List of currencies defined in the ePayments system. Values are passed as ISO three-letter currency code

Example: USD, EUR, RUB, AED, AUD, ZAR
errorCode
integer

Error code

Example: 0
errorMsgs
array of string

Message with detailed error description

Example: []
Response example
{
  "currencies": "USD, EUR, RUB, AED, AUD, ZAR",
  "errorCode": "0",
  "errorMsgs": "[]"
}

Changelog

Changelog

v2.14.2 (2019-07-29)

  • A support for the RUB currency transfers from an ePayments e-Wallet to WebMoney purses was added.
  • The validation for the field beneficiaryName when transferring to bank accounts was changed. The maximum field length has been increased from 34 characters to 55.

v2.14.1 (2019-02-28)

v2.14 (2019-02-06)

  • A description of mass payments to VKontakte was added. The method is used when paying for VKontakte advertising and replenishing vote balances.
  • New values for the Scope parameter used for obtaining information about business clients’ company’s name, jurisdiction and registration number have been added to the end-to-end authorization method.
  • The requirements for the Details field used in the v2/ payments mass payments method has been changed. Use of a line break (or newline) in the Detail field is now forbidden for mass payments.
  • New countries- Gibraltar, Isle of Man, Jersey and Guernsey, for which local wire transfers in GBP currency is available, were added. When transferring to these countries, an additional field - beneficiarySortCode needs to be filled.

v2.13.2 (2018-11-08)

  • The list of parameters required for transferring to bank accounts (AccountData object) has been updated.
  • The requirements for errors’ language has been updated.
  • The PurposeOfPayments manual has been updated with payment value codes for the country = Philippines.

v2.13.1 (2018-10-19)

  • A note about the available currencies for crediting when transferring to third-party bank cards has been added.
  • A requirements to gain access to bank cards in the live environment has been added.