ePayments Merchant Services Limited (henceforth - EMS) is a service allowing online stores and online services to accept payments made via bankcards and payment systems.
Before you can begin to accept payments, please, select your preferred method of integration with EMS:
If you require a full API integration with the EMS service, please complete the following steps:
Fill out an application.
Send an integration request and provide data on your online store (see the Getting Access). As a result, you will receive individual settings and data to access the EMS API.
Select a payment scenario.
EMS provides the following methods of creating invoices and accepting payments:
Create a payment.
To transfer the information the payment information use one of the following methods GET /paymentpage (for the Redirect, Iframe or Invoicing)
or the POST /payment method (for the Direct payments).
Get results.
After the invoice is paid, you will be sent a callback - notification regarding payment status.
You can create and send an invoice to the buyer without API integration. To do this, please complete the following steps:
Fill out an application.
Send a request to connect to EMS to get individual store settings (see the Getting Access).
Open web form.
Go to the https://ms.epayments.com/create-invoice and fill out the proposed fields, using the store settings provided by the EMS (see the Web-form usage).
Send an invoice to the buyer.
Copy the generated link and send it to the buyer. When clicking on the link, the buyer will be see the EMS payment page, using which they will be able to pay invoice.
Get results.
After the invoice is paid, you will be sent a email - notification regarding payment status.
To register an online store in EMS the merchant must contact their account manager or support service team (through the ticket system). The following attributes must be included in the request:
Attributes | Mandatory | Description |
---|---|---|
ShopSupport | Yes | Contact details of the online store’s support team. It is possible to enter the phone number or the email address of the support team as contact details |
DefaultCurrency Id | Yes | Currency for crediting payments to the online store’s account. This currency is required if the payment currency does not correspond to one of the currencies of the store in EMS (in this case conversion will occur at EMS) |
WebsiteUrl | Yes | Online store’s website. Only one site can be entered for an online store |
IpAddressTest | Yes | IP addresses from which access to the test environment must be provided |
IpAddressProd | Yes | IP addresses from which access to the live environment must be provided |
MerchantEmail | Yes | Merchant’s email to which invoice payment results will be sent. This consists of a copy of the notification sent to the buyer after carrying out the payment |
HoldExpDays | Yes | The period of time during which funds will remain frozen/blocked on the buyer’s and available for the debit. The value can vary from 1 to 28 days |
CallbackUrl | Yes | Page to which information about the result of the payment will be transmitted |
DefaultUrl | No | Page to which the buyer is returned after clicking on the “Back to store” button prior to receiving the result (i.e. the buyer declined to pay upon his/her own initiative) |
FailUrl | No | Page to which the buyer will be redirected if an error occurs when carrying out the payment |
SuccessUrl | No | Page to which the buyer will be redirected if the payment is successfully carried out |
OperationLife Time | No | Invoice validity period prior to its payment. Displayed in minutes. Values from 1 to 4320 accepted |
TimeToReject | No | The timeframe during which a buyer can pay the invoice. The countdown starts the moment the buyer opens the payment page. Only integer values, in minutes can be used. The maximum value is 240 |
“Mandatory” attribute - means that it can be transmitted only during online store registration. Subsequent changes to the submitted data will only possible via the EMS support team.
“Non-mandatory” attribute - means that it can be transmitted both during registration and when sending a request to create a payment page GET /paymentpage. Such a setting will allow the merchant to manage these attributes’ values themselves:
If the merchant wants to use success, fail, and default URLs which are different than a main store’s domain (webSiteUrl), then the merchant needs to contact EMS technical support and indicate the reason why these URLs should be different.
After providing details and registering the online store, the merchant will be provided with the following attributes:
With these attributes, the merchant gets access to the EMS stage and production environment, which are located at the following addresses:
Stage: https://sb-ms.epayments.com
Production: https://ms.epayments.com
Option | Description |
---|---|
Send an email with invoice for payment to the buyer | When using the Invoice method to create an invoice for payment, the merchant can send the buyer an email, in which the merchant can provide a link to pay the invoice. To do this, the merchant must pass the sendEmail = true parameter and specify the email address of the recipient in the customerEmail parameter |
Get a copy of email with the result of the operation | It is possible for the merchant to receive an email notifications with the final payment status. To do this, the merchant must first configure the online store settings on the EMS side. After the configuration is completed, a copy of the email notification will be sent to MerchantEmail (by default) or shopEmail (if the merchant explicitly choose to send this parameter in the request body) |
Display the Merchant Reference Code in card statement | For incoming payments, the merchant can pass the merchRefCode parameter, which will be displayed in the buyer’s card statement. To use this option, the merchant must configure the online store settings on the EMS side |
Hold funds on buyer’s card | The merchant may be able to temporarily lock/hold funds on the buyer’s bank card to charge them later. To use the option, the merchant needs to send the DMO = true parameter and indicate in HoldExpDays the number of days to hold funds. The option is available for all methods |
Recurring payments | To allow recurring card payments without the direct participation of the buyer during each payment, the merchant can use the option to save card data. First, the merchant will be required to configure the online store settings on the EMS side. After the configuration, the merchant will need to send the saveCard = 1 parameter to allow to automatically charge funds from the buyer’s card in the future |
One-click payments | The merchant can use the buyer’s bank card token to substitute card data on the payment page. This will allow the buyer to pay by only providing the card’s CVV. To use this option, the merchant must pass the cardToken parameter when creating the payment page |
Rebill | When working with the Invoice method, the merchant may provide the buyer with the opportunity to re-pay the invoice. The number of attempts available to the buyer is set by the merchant on the EMS side in the store settings. If the invoice status changed to the Rejected, then the “Retry” button will be displayed on the payment page to the buyer |
The merchant can create and send an invoice to the buyer without having to undergo API integration with EMS. This is possible via a special web-form. The web form can be accessed via the following link
https://ms.epayments.com/create-invoice
In the web form, the following fields are available to the merchant:
Field | Description |
---|---|
Shop ID | Online shop identifier |
Shop Secret | Online shop secret key |
Order Number | Order number, which is unique for this online shop |
Order Name | Order name (product name) |
Order Description | Short description of the order |
Order Amount | The amount, which will be paid for the order. Decimal separator – dot. No more than 2 characters can be entered after the dot |
Payment Currency | Currency, which will be used to pay for the order: - USD (default); - EUR; - RUB |
Payment Page Language | Payment Page Language: - EN (default); - ES; - RU |
Payer e-mail | Payer’s email. Can be filled out only if the Integration type = Invoicing |
After entering the correct data, a merchant must click Proceed button in order to see the following buttons:
The merchant needs to copy the link and sent it to the buyer. Upon clicking on the link the payment page for specific invoice will be opened.
Authorisation in EMS can be done one of two ways:
For working with the payment page, recurring payments and Direct payment method, a ShopId authorisation method is used. The auth signature is generated on the merchant side and then transferred to the EMS.
For the rest of API methods, authorisation by access_token is used. A token is obtained in response to the POST /token request.
EMS allows the merchant to issue invoices, which can be paid for by buyer using the following methods:
If required, the merchant can set restrictions for the availability of payment methods. This is done using the gateWayId parameter, which is sent alongside the request to create payment page GET /paymentpage.
Depending on the gateWayId value, the buyer will receive one of the following payment forms:
If gatewayId = 2, the buyer will first be redirected to the ePayments website to pay the invoice. This same site is opened when selecting the value “ePayments” on the payment method selection page.
If gatewayId = 3, the buyer will first be redirected to the WebMoney website to pay the invoice. This same site is opened when selecting the value “WebMoney” on the payment method selection page.
If gatewayId = 5, the buyer will first be redirected to the Yandex.Money website to pay the invoice. This same site is opened when selecting the value “YandexMoney” on the payment method selection page.
Store identifier. Issued to the merchant during registration
Unique invoice number in the online store.
If a payment with this number was already successfully carried out, then future payment attempts will be declined.
Any characters can be entered. Length from 1 to 64 characters
Payment amount. Separator - decimal point. Allowed number of characters after the decimal point depends on the payment currency (orderSumCurrency) and its digit capacity requirements (in accordance with ISO-4217).
For example, to create an invoice for 10 USD you need to transfer:
If an incorrect number of digits is transmitted for the selected currency, the error 2002019 will be returned in the response
Three-letter ISO code of the payment currency
Payment name
Result of completion of SHA512 hash function. String is generated by the online store via the following payment form attributes:
shopId;secretKey;orderNumber;orderSumAmount;orderSumCurrency
The attribute separator – semicolon. Spaces between attributes are not permitted
Order description
Payment method identifier:
If the parameter is not transmitted, the payment method selection page will open
Buyer’s email address for receiving payment notifications. If this parameter is transferred, the buyer will not be able to specify or change the email, to which notification with payment status will be sent.
This parameter is mandatory, then transmitting the sendEmail=true parameter.
The method of obtaining buyer’s email is determined by the merchant and is not regulated by EMS
An indicator of whether it is necessary to send an email to the buyer with a request to pay the invoice:
If sendEmail=true, then the following parameters will become mandatory:
The page to which the buyer will be redirected in case of successful payment.
The URL must be share the same domain as the shopFailUrl and shopDefaultUrl.
This parameter is optional, as it can be specified by the merchant earlier, during online store registration
The page to which the buyer will be redirected in case if error occurs during payment.
The URL must be share the same domain as the shopDefaultUrl and shopSuccessUrl.
This parameter is optional, as it can be specified by the merchant earlier, during online store registration
Page to which the buyer will be returned if they have clicked on the “Back to store” button prior to receiving the operation (i.e. the buyer decided not to complete payment).
The URL must be share the same domain as the shopFailUrl and shopSuccessUrl.
This parameter is optional, as it can be specified by the merchant earlier, during online store registration
Payment page language. Possible values:
A merchant’s copy of a notification email regarding the final payment status. If the shopEmail parameter was not sent, but the merchant has enabled the option to receive email notifications, then the payment status notification will be sent to MerchantEmail (specified when registering the store)
Invoice validity period prior to its payment. Displayed in minutes.
Values from 1 to 4320 accepted.
This parameter is not mandatory if it was provided earlier by the merchant when registering the online store
Invoice creation method. Possible values:
Indicates if the buyer’s card information should be saved for the future recurring payments, if the current invoice is paid successfully. The value is set as 1. Parameter is sent only for gateWayId = 1
Indicates if using the pre-authorization payment option to block funds on the buyer’s bank card and later debit them is available:
The parameter is sent only if integrationType = redirect
The exact number of days during which funds can be blocked on the buyer’s card. Parameter is sent only if DMO = true
Indicates if buyer will be redirected to the URL, specified by the shop, after the invoice is paid:
A dynamic payment descriptor that will appear in the buyer’s bank statement after the payment is completed.
The parameter is sent only if the invoice is paid for with a bankcard.
Only digits and Latin letters can be entered. Length varies up to 6 characters. This is a case-sensitive parameter
A card token. It is used later to fill out data on the payments page if payment is carried out via card. After the buyer follows the created link and is redirected to the payment form, they will need to fill out only CVC and email (if the latter wasn’t already provided by the merchant when creating a payment page). The field with card number will not be available for editing and will be masked.
Cardholder name. Transmitted only if gateWayId = 1 (payment by bank card). Field length varies from 2 to 100 characters. Only latin letters, spaces and special characters such as - . ' can be used
When transmitting this parameter in GET /paymentpage, the Name field will not be displayed on the payment page.
curl -X GET "https://ms.epayments.com/api/v1/public/paymentpage?shopId=98&orderNumber=111&orderSumAmount=10.00&orderSumCurrency=USD&orderName=Name&sha512=1DA5F09EC2DC11E1C7034DE50A93311F3C6DB762235F6866C94B45&orderDescription=Description&gatewayId=1&customerEmail=customer%40mail.com&sendEmail=true&shopSuccessUrl=https%3A%2F%2Fshop-name.com%2Fsuccess&shopFailUrl=https%3A%2F%2Fshop-name.com%2Ffailed&shopDefaultUrl=https%3A%2F%2Fshop-name.com%2Ffailed&language=En&shopEmail=shop-name%40mail.com&operationLifeTime=4320&integrationType=redirect&saveCard=1&DMO=true&holdExpDays=1&autoReturn=false&merchRefCode=code12&cardToken=544B0-74A544EAA0-4FA7AB37C9EFE05B7-0F8FF&cardHolderName=NAME%20SURNAME" -H "accept: application/json"
Result array parameters
{
"result": {
"urlToRedirect": "https://ms.epayments.com/p/859f2a8a8e5c4a3084ca6d2373405680"
}
}
After an invoice is paid for, notification with the operation result - a callback, is sent to a merchant, using a previously specified CallbackUrl.
Mandatory Callback parameters:
Parameter | Type | Description |
---|---|---|
CallbackDate | dateTime | Date and time the notification was created in EMS. Transmitted in the format yyyy-mm-ddThh:mm:ss.fffZ |
PaymentDate | dateTime | Date and time the order payment was confirmed by the buyer (I.e. operationState = done) |
Sha512 | string | Result of completing SHA512 hash function, which necessary to verify the notification. Created as SHA512 from the shopId;secretKey;orderNumber;orderSumAmount;orderSumCurrency string The attribute separator – a semicolon. Spaces between attributes are not permitted |
ShopId | integer | Online store identifier |
OperationId | integer | Operation identifier |
OrderNumber | string | Invoice number in the online store’s system |
OrderName | string | Order name |
OrderSum Amount | decimal | Order amount |
OrderSum Currency | string | Three-letter ISO code of the payment currency |
GatewaySum Amount | decimal | Amount debited from the buyer for the selected payment method |
GatewaySum Currency | string | Three-letter ISO code of the payment currency debited from the buyer |
ShopSum Amount | decimal | Amount to be credited to the merchant’s account in EMS. |
ShopSum Currency | string | Currency amount to be credited to the merchant’s account in EMS |
OperationState | string | Current operation status: - Rejected; - Canceled; - Done |
CustomerEmail | string | Buyer’s email address for receiving payment notifications |
Gateway | object | An object that contains information about the bankcard holder (who carries out the payment). Object parameters: -WalletIdentifier - Buyer’s e-wallet number. Only sent if Name = ePayments or WebMoney; - Name - payment provider name. Possible values are - Bank Card, ePayments or WebMoney; - CardHolder - cardholder name. Sent only if Name = Bank Card; - CardToken - a bankcard token, used to fill in blanks on the payment page if payment is carried out via bankcard; - PanCodeMasked - masked card number. Provided in format 123456******1234. Sent only if Name = Bank Card; - ShopGatewayId - online store payment method identifier |
OperationType | string | Operation type. Takes the value IncomingPayment - accepting payment |
InvoiceExp DateTime | datetime | Invoice expiration time, after which the invoice can no longer be successfully paid (correlating to the current time in UTC + 0) |
Not-Mandatory Callback parameters:
Parameter | Type | Description |
---|---|---|
Order Description | string | Order description |
Rate | string | Exchange rate to the currency to be credited. Transmitted in the format "1 currency_debiting = amount_receipt currency_receipt". For instance, “1 USD = 62.6743 RUB” In the receipt amount up to 4 decimal points are displayed after the decimal point |
Error | object | An object that contains information about the error. It is returned only for an unsuccessful callback. Object parameters: - Code - error code; - Message - text description |
MaxRebill Attempts | integer | The maximum number of attempts allowed for paying an invoice. Set in the settings of the online store |
UsedRebill Attempts | integer | The number of attempts that were used to pay for the same invoice |
Successful request example:
{
"ShopSumAmount":616.80,
"ShopSumCurrency":"RUB",
"Rate":"1 RUB = 0.0161 USD",
"PaymentDate":"2019-04-18T13:48:06.33Z",
"OperationId":21714,
"OrderName":"Order",
"OrderDescription":"Description",
"GatewaySumAmount":1.00,
"GatewaySumCurrency":"USD",
"CustomerEmail":"[email protected]",
"InvoiceExpDateTime":"2019-04-18T14:16:13.6865718Z",
"MaxRebillAttempts":17,
"UsedRebillAttempts":1,
"CallbackDate":"2019-04-18T13:48:15.9537261Z",
"Sha512":"b9a785648fcf2ecfe742d3affd805d208de5ec62",
"ShopId":1,
"OrderNumber":"ED-676-1",
"OrderSumAmount":10.00,
"OrderSumCurrency":"USD",
"OperationState":"Done",
"Gateway":{
"WalletIdentifier":"000-861964",
"Name":"ePayments",
"ShopGatewayId":85
},
"OperationType":"IncomingPayment"
}
If the payment is successfully processed, a message about the operation’s success will be displayed on the payment page.
The buyer will also receive a corresponding email notification. If in the request body GET /paymentpage the shopEmail parameter was transmitted, a copy of the email notification will be sent to the merchant.
Unsuccessful request example:
{
"Rate":"",
"PaymentDate":"2019-04-18T14:27:17.886Z",
"OperationId":21721,
"OrderName":"Order",
"OrderDescription":"Description",
"GatewaySumAmount":1.00,
"GatewaySumCurrency":"USD",
"CustomerEmail":"[email protected]",
"InvoiceExpDateTime":"2019-04-18T14:53:15.1797886Z",
"UsedRebillAttempts":1,
"CallbackDate":"2019-04-18T14:27:32.3005005Z",
"Sha512":"1d14a3f04dabac5fcf872b12e4add73a9847c",
"ShopId":261,
"OrderNumber":"ED-676-7",
"OrderSumAmount":1.00,
"OrderSumCurrency":"USD",
"OperationState":"Rejected",
"Gateway":{
"WalletIdentifier":"",
"Name":"WebMoney",
"ShopGatewayId":111
},
"Error":{
"Code":9003017,
"Message":"Invoice rejected by payer"
},
"OperationType":"IncomingPayment"
}
If the payment is not successfully processed, a message about the payment decline will be displayed on the payment page.
The buyer will also receive a corresponding email notification. If in the GET /paymentpage request body the shopEmail was transmitted, a copy of the email notification will be sent to the merchant.
Redirect integration type is suitable for merchants who do not need to add payment forms to their online stores. However, in that case it will be mandatory for their online store to have a payment button, which after clicking the buyer is redirected to the EMS page.
When working with Redirect:
As part of their integration with EMS, using Redirect integration also allows merchant to access the following operations:
For Redirect the workflow is organized in accordance with the following algorithm:
The time to carry out the operation must be clarified with the EMS support team.
Iframe integration type is suitable for merchants who do not want to redirect buyers to third-party websites and plan on carrying out payments within their online store.
To use this method a merchant must complete an additional integration.
When working with Iframe:
As part of Iframe integration with EMS a merchant will be able to access the following operations:
For Iframe the workflow is organized in accordance with the following algorithm:
The time to carry out the operation must be clarified with the EMS support team.
To use the iframe for working with invoices the merchant must embed JavaScript in their online store coding to initialise the payment page.
It is not required to pass <iframe> </iframe>
tag additionally, it will be added automatically when using a script.
The code may be placed in any part on the html-page:
live: <script src="https/ms.epayments.com/ems-paymentPage.js"></script>
test: <script src="https/sb-ms.epayments.com/ems-paymentPage.js"></script>
To support older browsers the merchant must additionally enable polyfills for Promise and Fetch API methods:
live: <script src="https/ms.epayments.com/ems-paymentPage.with-polyfill.js"></script>
test: <script src="https/sb-ms.epayments.com/ems-paymentPage.with-polyfill.js"></script>
To use their own polyfills the merchant must first enable them and after it upload the payment page integration script.
PaymentPage class
After the merchant runs the script the EMS
object will become available, as well as the EMS.PaymentPage
class. Below is an abstract description of the EMS.PaymentPage
class.
interface Options {
apiUrl?: string;
}
abstract class PaymentPage {
constructor(paymentInfo: PaymentInfo | string, options: Options = {});
async init(mountNode: Element | string, {
submitButton: Element | string,
styles: Theme,
mode: 0 | 1
}): Promise<any>;
async destroy(): Promise<any>;
addEventListener(eventName: string, fn);
removeEventListener(eventName: string, fn);
triggerEvent(eventName: string, data: any);
}
Class methods | Description |
---|---|
constructor | Constructor which takes the following arguments: - paymentInfo — payment parameters. If presented as a string, it is recognized as a ready url for the payment page request; - options — constructor options. For example, the options.apiUrl — is a basic url for requesting the payment page. This parameter can be ignored if paymentInfo is a string. |
init | Method for initialization and embedment of the payment page: - submitButton - an element or selector of an element that initiates the form sending on click; - styles - a stylization of payment form fields. The value set is equal to the Theme interface; - mode - iframe mode: 0 - standard mode (default); 1 - customization |
destroy | Method for dismantling the payment page |
addEvent Listener | Method for subscribing to payment page events. This is a non-mandatory method |
removeEvent Listener | Method for unsubscribing from payment page events |
PaymentInfo interface
The PaymentInfo interface contains the same parameters as the method for calling the payment page GET /paymentpage:
interface PaymentInfo {
shopId: number;
orderNumber: string;
orderSumAmount: string;
orderSumCurrency: string;
orderName: string;
sha512: string;
gatewayId?: number;
orderDescription?: string;
customerEmail?: string;
sendEmail?: boolean;
shopSuccessUrl?: string;
shopFailUrl?: string;
shopDefaultUrl?: string;
language?: string;
shopEmail?: string;
operationLifetime?: number;
integrationType?: string;
saveCard?: number;
DMO?: boolean;
holdExpDays?: number;
autoReturn?: boolean;
merchRefCode?: string;
cardToken?: string;
cardHolderName?: string;
}
init method
To initialise the payment the merchant must create a sample of EMS.PaymentPage
class and call the EMS.PaymentPage::init
method. As an argument the method accepts links to a html-element or its corresponding selector:
<div id="payment-page"></div>
If the payment page is initialised immediately when uploading the html-page the merchant must be certain that at the moment of initialization the element for embedding iframe was added to DOM.
addEventListener method
After successfully initialising, the merchant can subscribe to possible payment page events by using the EMS.PaymentPage::addEventListener
method. Subscription to these events is not mandatory.
Javascript code for ECMAScript 6+ versions:
(async function(){
// page –class example
const page = new EMS.PaymentPage( {
shopId:123,
orderNumber:'456',
orderSumAmount:'44.56',
orderSumCurrency:'USD',
gatewayId:1,
language:'en',
orderName:'Order name',
orderDescription:'Order description',
operationLifetime:30,
sha512:'280e4f7fef0c2dc1524cc7c5de4964eaf398fe'
});
try {
// page monitoring for element with id="payment-page"
const result = await page.init('#payment-page');
console.log(result);
// subscription to payment change status
page.addEventListener('status:change', console.log);
} catch(e) {
console.error(e);
}
})()
Javascript code for ECMAScript 5 version:
(function(){
var page = new EMS.PaymentPage({
shopId: 123,
orderNumber: 456,
orderSumAmount: 44.56,
orderSumCurrency: 'USD',
gatewayId: 1,
language: 'en',
orderName: 'Order name',
orderDescription: 'Order description',
operationLifetime: 30,
sha512: '280e4f7fef0c2dc1524cc7c5de4964eaf398fe'
});
page.init('#payment-page')
.then(function(result){
console.log(result);
page.addEventListener('status:change', function(val){
console.log(val.status);
});
})
.catch(function(e){
console.error(e);
})
})()
Available events
Events | Description | Type of information |
---|---|---|
status:change | Receive information on final payment status. The merchant may opted to remove the iframe display and show the client additional information. - DONE - payment was successful; - REJECT - payment was not successful; - AWAIT - awaiting before sending card data | status:DONE or REJECT or AWAIT |
api:error | Receive errors when sending card data | message: string, code: number |
redirect | Receive confirmation that the buyer was redirected to the confirmation code entry page when paying with the card | — |
form:render | Receive information on how long will it take for the form to render and be available for use | — |
app:ready | Receive information on then the application will be ready to interact with the SDK | — |
Below is an example of a code for iframe integration:
<!DOCTYPE html>
<html>
<head></head>
<body>
<script src="https://sb-ms.epayments.com/ems-paymentPage.js">
// The test environment is provided
</script>
<h3>Example of payment page</h3>
<div style="height: 100px; width:max; background-color: lightblue;">
<p>Some content goes here</p>
</div>
<div id="payment-page" style="display:block">
<!-- Here is a place where payment form will appear; -->
</div>
<div id="result" style=>
</div>
<div id="error">
</div>
<script type="text/javascript">
let page;
(async function(){
// page –class example
page = new EMS.PaymentPage( {
shopId:1,
orderNumber:'321326',
orderSumAmount:'10.00',
orderSumCurrency:'USD',
gatewayId:1,
language:'en',
orderName:'Order name',
orderDescription:'Order description',
operationLifetime:30,
// sha512 that is generated from the following string: shopId;secret;orderNumber;orderSumAmount;orderSumCurrency
sha512:'795af75f0c049dce046bb17df803fc26096bc7c1185d978823a7c953ffc1b0d7759f8a09e455df5d1c380be0ab49ed8ae98f475421d28583779e49b73980b772'
});
try {
// page monitoring for element with id="payment-page"
const result = await page.init('#payment-page');
// subscription to payment change status
page.addEventListener('status:change', handleStatus);
} catch(e) {
document.getElementById('error').style.display = 'block';
document.getElementById('error').innerHTML = e;
console.log(e);
}
})()
// a payment form became hidden as well as the operation is completed. After that the result message is displayed
function handleStatus(result, param1, param2) {
document.getElementById('payment-page').style.display = 'none';
resultBlock = document.getElementById('result');
resultBlock.style.display = 'block';
status = 'Operation statis is ';
if(result.status === 'DONE') {
resultBlock.innerHTML = status + result.status + '\n' + 'Operation is complete.';
page.destroy();
} else if(result.status === 'REJECTED') {
resultBlock.innerHTML = status + result.status + '\n' + 'Operation is complete.'
page.destroy();
} else {
resultBlock.innerHTML = status + result.status + '\n' + 'Operation is not complete.'
}
}
</script>
</body>
</html>
The result of the code implementation is the following html page:
The merchant can customize the iframe in accordance with the design of their online store (hereinafter - customization).
Customization is available only for invoices that will be paid for by bankcard. This means that a custom design can be applied to the following fields of the payment form:
To access customization features, the merchant needs to define the following parameters in the init method when creating the page:
Parameter | Set value | Description |
---|---|---|
mode | 1 | Iframe work mode. For customization accepts the value = 1 |
submitButton | html-element or selector of an element | The element initiates submission of a form on click. At the time of creation of the payment page, this element must be present in the DOM structure |
styles | Theme | Interface to make changes in the basic style of fields. |
Theme interface
While working with customization it is possible to change the basic style of fields through the Theme interface:
interface Theme {
errorColor: string;
blurColor: string;
focusColor: string;
textColor: string;
backgroundColor: string;
fontFamily: string;
template: string;
placeholderColor: string;
gap: string;
}
Attribute | Description | Default value |
---|---|---|
errorColor | Text color and color of the line located below the field (in case of an error) | #eb5557 |
blurColor | Color of the line located below the field (in inactive state) | #d7e0ea |
focusColor | Color of the line located below the field (when inputting a value in the field) | #286ef2 |
textColor | Color of the text that have been inputted in the field | #1a1b1f |
background Color | Iframe background color | #ffffff |
fontFamily | Iframe form font | “’PT Sans’, sans-serif” |
template | Fields layout template. Fields visually represented as a table where rows are separated from each other by the ' symbol. Each line should contain the same number of elements. For example, 4 lines of 2 elements or 3 lines of 3 elements, etc. To arrange for one field to be in one line, the field value must be duplicated in accordance with the number of elements. For example, in the default setting, the fields are arranged in 4 lines with 2 elements in each. In this case, in the first, third and fourth line contains one field each, and the second line - two fields | ‘card-number card-number’ ‘exp-date cvc’ ‘card-holder card-holder’ ‘email email’ |
placeholder Color | The color of the text that is used as an example of the inputted value (placeholder) | #76869a |
gap | The distance between the columns and the fields. The first value determines the vertical distance between the fields, the second value determines the horizontal distance between the columns | 0 15px |
Invoicing integration type is suitable for merchants whose buyers purchase goods or services without the online store participation (for example, via an operator).
In this instance, the online store does not need to have a cart section and payment button.
When working with Invoicing:
Invoicing integration also allows merchant to access the following operations:
For Invoicing the workflow is organised in accordance with the following algorithm:
The time to carry out the operation must be clarified with the EMS support team.
When working with Invoicing, the merchant can send an email notification about the invoice issued to the buyer. An email is sent after forming a link to the payment page (GET /paymentpage method) if the following parameters were passed in the URL request:
After the link is formed, an email with the request to proceed to the invoice payment page will be sent to the buyer.
The notification language depends on which language
parameter was sent during the link generation request. If no such parameter was sent, the notification will be sent in English, by default.
The payment button in the email notification is valid for the duration of the operationLifeTime
time. It is sent by the merchant during registration or when creating the payment page link.
Direct integration type is suitable for merchants who want to use their own payment form for interacting with buyers. In accordance with the PCI DSS regulations, merchants who want to use this integration type, must fill out the SAQ form and go through ASV-scanning first.
When working with Direct:
The Direct integration also allows merchant to access the following operations:
For Direct the workflow is organized in accordance with the following algorithm:
This method is intended for creating payments using the Direct payment scenario. After the payment request is sent, the merchant will receive:
If the merchant did not receive a response to the submitted request, they can manually check the current status of the request. In this case, the merchant needs to re-submit the POST/v1/payment request using the same secret, shopId and OrderNumber parameters. The response to this request, will return operation data.
Using any other parameters and/or combinations will result in error during payment creation.
application/json
Basic shopId:shopSecret
, here shopId:shopSecret - is a base64 encoded string
Payment method
Payment processing data
Unique order number assigned by the online store system. Max length - 64 characters
Payment amount in the online store currency
Three-letter payment currency ISO code
Order name
Order description
Buyer’s email address for receiving payment notifications
Email notification language. Possible values are EN, RU, or ES
Online store’s email address for receiving payment notifications
Payment details
Indicates if the buyer’s card information should be saved for the future recurring payments, if the current invoice is paid successfully. The value is set as 1. Parameter is sent only if paymentMethod = bankCard
Indicates if it is possible to use the pre-authorisation payment option to block funds on the buyer’s bank card and debit them later:
The exact number of days during which funds can remain locked on the buyer’s card. Parameter is sent only if DMO = true
A dynamic payment descriptor that will appear in the buyer’s bank statement after the payment is completed.
The parameter is sent only if the invoice is paid for with a bankcard.
Only numbers and Latin letters can be entered. Max length 6 - characters. This is a case-sensitive parameter
{
"paymentMethod": "bankCard",
"paymentInfo": {
"returnURL": "https://shop-return-url.com"
},
"orderNumber": "EDF-456-43",
"orderSumAmount": "50.32",
"orderSumCurrency": "USD",
"orderName": "Name",
"orderDescription": "Description",
"customerEmail": "[email protected]",
"language": "EN",
"shopEmail": "[email protected]",
"paymentMethodData": {
"cardToken": "3ba2c031-a8c0-4c9f-9025-7eacf8dd14e2",
"cvv": "533",
"cardHolderName": "Alex Titmus",
"cardNumber": "5413330000000019",
"expMonth": "01",
"expYear": "20"
},
"saveCard": "1",
"dmo": "true",
"holdExpDays": "10",
"merchRefCode": "code12"
}
Result object parameters
{
"result": {
"operationId": "46585",
"operationState": "Rejected",
"confirmationURL": "http://example.com",
"error": {
"code": "9002000",
"messages": "The transfer cannot be made. Please contact the support team or try again later"
}
}
}
Some API methods require the merchant to pass authorisation and receive a token. The authorisation mechanism is built on the base of OAuth 2.0 protocol (RFC-6749).
The lifetime of the token in the authorisation method is limited, therefore it is necessary to periodically update it or request a new one.
To refresh the token, you must use the refresh_token parameter received with the access_token.
The same method is used to receive and update token - POST /api/v1/oauth/token, but with different request parameters are submitted:
application/x-www-form-urlencoded
Login issued to the merchant after entering an agreement with EMS
Password issued to the merchant after entering an agreement with EMS
curl -X POST "https://ms.epayments.com/api/v1/oauth/token" -H "accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=password&username=ShopName&password=secretKey"
Token type. Value is always set as Bearer
A token which the EMS client can use to access API methods
Token validity period. Takes the value of 3600. Displayed in seconds
Value which can be used to update the access_token without transmitting the username and password in the authorisation method body. Obtained in the response body only is grant_type=password was passed
{
"token_type": "bearer",
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ3UPmvzVLKraT43Dm5EkPaYT",
"expires_in": "3600",
"refresh_token": "CfDJ8AyUslu18k5GgMgSqVSa8fGVfprnTckhalLW-PrbuidmBf_"
}
This method is used to obtain a list of operations carried out by the merchant’s clients. By default, the merchant receives a list of all clients’ operations for the past 7 days.
Prior to sending the request the merchant must login using his/her login and password via the authorisation method.
Start date from which the operations list will be received. By default, returns operations for the past 7 days. Provided in yyyy-mm-dd format
End date of the operations received in the list. By default, this is the date the request is being made. Provided in yyyy-mm-dd format
Operation identifier set by EMS
Operation identifier set by the payment provider
Operation type:
First 6 numbers of the bankcard used in the operation
Store name
Payment method name:
Amount sent. Separator- decimal point. Up to 2 digits can be entered after the decimal point
Amount received. Separator- decimal point. Up to 2 digits can be entered after the decimal point
Currency to be debited. Displayed in three-letter ISO format
Currency to be received. Displayed in three-letter ISO format
Operation status:
Store identifier. Issued to the merchant during registration
Unique online store invoice number
Last 4 digits of the bankcard used during the operation
Bearer access_token
, where the access_token is an access key, obtained in the request response during authorisation
application/json
curl -X GET "https://ms.epayments.com/api/v1/operation?fromDate=2018-09-25&toDate=2018-10-25&operationId=34356&externalId=56577&operationType=IncomingPayment&bin=412305&shopName=Shop%20Name&gatewayName=Bank%20card&fromAmount=3.86&toAmount=2.96&fromCurrency=eur&toCurrency=usd&operationState=Done&shopId=98&orderNumber=558965&lastDigits=6543" -H "accept: application/json"
Successful response parameters
{
"result": {
"operations": [
{
"creationDate": "2018-09-25T12:47:48.927",
"id": "9537",
"externalId": "payment_55",
"operationType": "Refund",
"shopName": "Shop Name",
"gatewayName": "Bank Card",
"fromAmount": "10.50",
"fromCurrency": "USD",
"toAmount": "09.50",
"toCurrency": "EUR",
"operationState": "Done",
"cardId": "541333******0019",
"shopId": "261",
"orderNumber": "261_25_09_2018_001"
}
]
}
}
This method is used for cancelling a created invoice. A cancellation request can only be sent for unpaid invoices in a operationState = New or Open. If the invoice has already been paid, the request for cancellation will be declined.
Before the request is sent the merchant must login using their username and password via the authorisation method. If the operation is successfully cancelled the merchant will receive Callback and/or an email notification.
Bearer access_token
, where the access_token is an access key, obtained in the request response during authorisation
application/json
Online store identifier
Unique invoice number in the online store for which the refund is to be made.
When the shopId
and orderNumber
parameters are transmitted, the operationId
parameter is not mandatory
{
"shopId": "1",
"orderNumber": "398314"
}
Successful response parameters
{
"result": {
"operationId": "8951",
"operationState": "Canceled"
}
}
This method allows to refund a payment which was carried out via bankcard or via payment systems wallets - WebMoney, Yandex.Money, QIWI.
Refund policy:
Refund can be carried out if the following conditions are met:
Partial Refund:
The refund amount may differ from the original payment amount, i.e. partial refund is possible.
If the merchant does not have a partial refund settings configured, then upon trying to send a POST/v1/refund request, where the refund amount differs from the original transaction amount, the merchant will receive the following error: Refund prohibited by shop settings.
The number of refunds allowed for a single operation is set on the EMS side in the store settings.
Refund status:
If the merchant has not received a response, then the merchant can send an additional request to check the status of the operation. To do this, the merchant needs to resend the POST/v1/refund request using the same refundOrderNumber and incomingPaymentOperationId parameters as before. In this case, the merchant will receive the details on the operation in response to the request.
Prior to sending the request the merchant must login via the authorisation method. Regardless of the operation processing status, after sending the request and receiving a response, the merchant will receive a callback.
Bearer access_token
, where the access_token is an access key, obtained in the request response during authorisation
application/json
Operation identifier for EMS for which the refund must be made. The identifier is received in Callback or in the GET /operation response
Unique invoice number in the online store for which the refund is to be made. Max field length - 64 characters
The refund amount in the original payment currency
Reason for refund
{
"incomingPaymentOperationId": 0,
"refundOrderNumber": "365",
"amountToRefund": "80",
"cause": "Incorrect payment details"
}
Successful response parameters
{
"result": {
"operationId": "1366",
"state": "Done"
}
}
To successfully charge the blocked (held) funds from the client’s card, the merchant must call the cardCharge method before the HoldExpDays time expires. Upon initiating an operation, the merchant must specify the charged amount. The said amount can:
Bearer access_token
, where the access_token is an access key, obtained in the request response during authorisation
application/x-www-form-urlencoded
Operation identifier for which the blocked funds must be debited from the buyer’s card. In case if the operationId parameter is sent, the parameters shopId and orderNumber will not be sent
Merchant’s store identifier. In case if the shopId parameter is sent the operationId parameter will not be sent
Unique order number assigned by the online store system. In case if the orderNumber parameter is sent, the operationId parameter will not be sent
Amount to be debited
{
"operationId": 0,
"shopId": "10",
"orderNumber": "5673",
"chargeAmount": "55.10"
}
Result object parameters
{
"result": {
"operationId": "6678"
}
}
During the HoldExpDays time, the merchant may choose to lift the hold on the client’s card funds. In such cases, the buyer will receive the full amount that was previously blocked.
After the hold is cancelled, an email notification will be sent to the buyer, and the merchant will receive an email and/or callback (depending on the store settings) as well.
The hold can also be cancelled automatically after the HoldExpDays period has expired, provided that merchant did not send a request for charge or cancellation during the specified period.
Bearer access_token
, where the access_token is an access key, obtained in the request response during authorisation
application/x-www-form-urlencoded
Operation identifier for which the blocked funds must be debited from the buyer’s card. In case if the operationId parameter is sent, the parameters shopId and orderNumber will not be sent
Merchant’s store identifier. In case if the shopId parameter is sent the operationId parameter will not be sent
Unique order number assigned by the online store system. In case if the orderNumber parameter is sent, the operationId parameter will not be sent
{
"operationId": 0,
"shopId": "10",
"orderNumber": "5673"
}
Result object parameters
{
"result": {
"operationId": "6678"
}
}
Recurring payments are regularly executed payments, which use data from saved cards. Payments are initiated on the merchant’s side, without direct participation of the buyer.
Payment conditions
Working with recurring payments is possible if the following conditions are met:
Payment scheme
Recurrent payments are executed in accordance with the following scheme:
Identifier of the online store, for which a recurring payment is required
Token of a previously saved bankcard, from which funds will be charged
Unique order number assigned by the online store system
Order name
Payment amount
Three-letter ISO code of the payment currency. Must be the same as in the original payment
Buyer’s email address for receiving payment notifications
Online store’s email address for receiving payment notifications
Order description
{
"shopId": "1",
"cardToken": "dfgtey56er6efdfg56464576",
"orderNumber": "56",
"orderName": "Name",
"orderSumAmount": "50.10",
"orderSumCurrency": "usd",
"customerEmail": "[email protected]",
"shopEmail": "[email protected]",
"orderDescription": "Purchasing of goods"
}
Result array parameters
{
"result": {
"operationId": "8965"
}
}
Callback – is an EMS service which sends a notification with the operation result to the CallbackUrl.
EMS sends a HTTP POST request to the online store’s CallbackUrl. If the online store returns 200 OK status, then EMS will receive callback and stop trying to call the handler.
In the absence of a successful response the EMS server will continue to send requests with the following intervals: 1 min, 5 min, 5 min, 10 min, 1 hour, 24 hours. If after 24 hours response was not received, EMS will cease sending requests. If the online store did not receive callback, it can manually send callback for each operation.
Below the Callback is described which sends a notification of the invoice cancellation results to the CallbackUrl.
Mandatory callback parameters:
Parameter | Type | Description |
---|---|---|
OperationId | integer | Operation identifier |
OrderName | string | Order name |
GatewaySum Amount | decima | Amount debited from the buyer for the selected payment method |
GatewaySum Currency | string | Three-letter currency code debited from the buyer |
CallbackDate | dateTime | Date and time notifications created in EMS. Transmitted in yyyy-mm-ddThh:mm:ss.fffZ format |
PaymentDate | dateTime | Date and time of operation cancellation (i.e. operationState = canceled) |
Sha512 | string | Result of completing SHA512 hash function, which necessary to verify the notification. Created as SHA512 from the shopId;secretKey;orderNumber;orderSumAmount;orderSumCurrency string |
ShopId | integer | Online store identifier |
OrderNumber | string | Invoice number in the online store system |
OrderSum Amoun | decimal | Order amount |
OrderSum Currency | string | Three-letter order currency ISO code |
OperationState | string | Current operation status = Canceled |
Gateway | object | An object that contains information about the bankcard holder (who carries out the payment). Object parameters: - Name - payment provider name. Possible values are - Bank Card, ePayments; - ShopGatewayId - online store payment method identifier |
Error | object | Response description. Object parameters: - Code - Response code. If invoice successfully cancelled the code 2002017 will be sent; - Message - text description |
Not-Mandatory Callback parameters:
Parameter | Type | Description |
---|---|---|
rate | string | Exchange rate for the currency to be credited (if available) |
Successful cancellation example:
{
"OperationId":9786,
"OrderName":"Name",
"Rate":"",
"CallbackDate":"2018-10-08T11:40:20.7255414Z",
"PaymentDate":"2018-10-08T11:40:13.447",
"Sha512":"8635401afd76380fd8f8d6dab064a4626cfe54c55857f2c405d9550",
"ShopId":261,
"OrderNumber":"141",
"OrderSumAmount":1000.00,
"OrderSumCurrency":"RUB",
"OperationState":"Canceled",
"Gateway":{
"Name":"Bank card",
"ShopGatewayId":38
},
"Error":{
"Code":2002017,
"Message":"Operation canceled"
},
"OperationType":"IncomingPayment"
}
Unsuccessful cancellation example:
{
"OperationId":9179,
"OrderName":"Name",
"GatewaySumAmount":100.00,
"GatewaySumCurrency":"USD",
"Rate":"",
"CallbackDate":"2018-09-13T09:24:42.5863503Z",
"PaymentDate":"2018-09-13T09:24:27.523",
"Sha512":"6218e2a6a1cf31cc63c6725becd1c9d8cde4a2839c2d1ef74",
"ShopId":139,
"OrderNumber":"3301",
"OrderSumAmount":100.00,
"OrderSumCurrency":"USD",
"OperationState":"Canceled",
"Gateway":{
"Name":"Bank card",
"ShopGatewayId":38
},
"Error":{
"Code":2002016,
"Message":"Invoice expired"
}
}
Below the Callback is described which sends a notification about the payment refund result to the CallbackUrl. This callback is initialized when the following conditions are met:
Mandatory callback parameters:
Parameter | Type | Description |
---|---|---|
CallbackDate | dateTime | Data and time the notification was created in EMS. Transmitted in yyyy-mm-ddThh:mm:ss.fffZ format |
PaymentDate | dateTime | Date and time the payment refund was confirmed by the purchaser (when operationState = done or rejected) |
Sha512 | string | Result of completing SHA512 hash function, which necessary to verify the notification. Created as SHA512 from the shopId;secretKey;orderNumber;orderSumAmount;orderSumCurrency string. The attribute separator – a semicolon ";". Spaces between attributes are not permitted |
ShopId | integer | Online store identifier |
IncomingPayment OperationId | integer | Payment receipt operation identifier for which the refund was initiated |
OrderNumber | string | Invoice number within the online store’s system |
OrderSumAmount | decimal | Order amount |
OrderSumCurrency | string | Three-letter order currency ISO code |
RefundOperationId | integer | Refund operation identifier |
RefundedGateway SumAmount | decimal | Amount which was refunded to the purchaser. Include fees. Transmitted only in case of successful refund |
RefundedGateway SumCurrency | string | Three-letter ISO currency code of the purchaser’s refund. Transmitted only in case of successful refund |
RefundedShop SumAmount | decimal | Amount which was refunded by the online store. Does not include fees. Transmitted only in case of successful refund |
RefundedShop SumCurrency | string | Three-letter order currency ISO code of the online store’s refund currency. Transmitted only in case of successful refund |
InitiatedBy | string | Refund operation initiator: - Merchant – refund initiated be the merchant; - Operator – refund initiated by the EMS operator |
RefundCause | string | User comments left in the refund request |
OperationState | string | Current refund operation status: - Rejected; - Done |
Gateway | object | An object that contains information about the bankcard holder (who carries out the payment). Object parameters: - Name - payment provider name. Possible values are - Bank Card, ePayments or PayMaster24; - CardHolder - cardholder name. Sent only if Name = Bank Card; - PanCodeMasked - masked card number. Provided in format 123456******1234. Sent only if Name = Bank Card; - CardToken - a bankcard token, used to fill in the blanks on the payment page if payment is carried out via bankcard. Passed only if saveCard = 0 or 1, and state = Done; - ShopGatewayId - online store payment method identifier |
OperationType | string | Operation type. Takes the value Refund |
Non-mandatory callback parameters:
Parameter | Type | Description |
---|---|---|
RefundRate | string | Exchange rate to the currency to be credited. Transmitted in the format "1 currency_debiting = amount_receipt currency_receipt". For instance, “1 USD = 62.6743 RUB” In the receipt amount up to 4 decimal points are displayed after the decimal point |
Error | object | An object that contains information about the error. It is returned only for an unsuccessful callback. Object parameters: - Code - error code; - Message - text description |
Example of a successful refund:
{
"CallbackDate":"2018-07-11T17:44:19.5457669Z",
"PaymentDate":"2018-07-11T16:23:03.618",
"Sha512":"2b57a72a2c07c7e2b04f258736dec937b89e",
"ShopId":266,
"IncomingPaymentOperationId":2785,
"OrderNumber":989818,
"OrderSumAmount":4400.57,
"OrderSumCurrency":"RUB",
"RefundOperationId":2793,
"RefundedGatewaySumAmount":4400.57,
"RefundedGatewaySumCurrency":"RUB",
"RefundedShopSumAmount":69.17,
"RefundedShopSumCurrency":"USD",
"RefundRate":"1 USD = 63.6237 RUB",
"InitiatedBy":"Merchant",
"RefundCause":"Asked for the manager",
"OperationState":"Done",
"Gateway":{
"Name":"Bank Card",
"CardHolder":"ANNA POSH",
"PanCodeMasked":"431422******0049",
"ShopGatewayId":68
},
"OperationType":"Refund"
}
Example of an unsuccessful refund:
{
"CallbackDate":"2018-07-11T14:58:59.4722328Z",
"PaymentDate":"2018-07-11T14:58:45.024",
"Sha512":"d3a3356e7c6b2fe0c181e343c69d648f62eed2cb85493fd",
"ShopId":139,
"IncomingPaymentOperationId":2780,
"OrderNumber":8934912131,
"OrderSumAmount":155.55,
"OrderSumCurrency":"USD",
"RefundOperationId":2793,
"InitiatedBy":"Merchant",
"RefundCause":"Asked for the manager",
"OperationState":"Rejected",
"Gateway":{
"Name":"Bank Card",
"CardHolder":"ANNA POSH",
"PanCodeMasked":"541333******0019",
"ShopGatewayId":38
},
"Error":{
"Code":9000000,
"Message":"Error on the payment system side"
},
"OperationType":"Refund"
}
Below is the description of the Callback which sends a notification of the invoice cancellation results to the CallbackUrl. Using this callback the merchant can determine the validity of saved card data.
Mandatory callback parameters:
Parameter | Type | Description |
---|---|---|
OperationId | integer | Operation identifier |
OrderName | integer | Order name |
GatewaySum Amount | decimal | Amount debited from the buyer for the selected payment method |
GatewaySum Currency | string | Three-letter ISO code of the payment currency debited from the buyer |
CustomerEmail | string | Buyer’s email address for receiving payment notifications |
InvoiceExp DateTime | datetime | Invoice expiration time, after which the invoice can no longer be successfully paid (correlating to the current time in UTC + 0) |
CallbackDate | datetime | Date and time when the notification was created in EMS. Transmitted in the yyyy-mm-ddThh:mm:ss.fffZ format |
Sha512 | string | Result of completing SHA512 hash function, which necessary to verify the notification. Created as SHA512 from the shopId;secretKey;orderNumber;orderSumAmount;orderSumCurrency string The attribute separator – a semicolon. Spaces between attributes are not permitted |
ShopId | integer | Online store identifier |
OrderNumber | integer | Invoice number in the online store’s system |
OrderSum Amount | decimal | Order amount |
OrderSum Currency | string | Three-letter ISO code of the payment currency |
OperationState | string | Current operation status: - Open; - Canceled; - Confirmed; - Accepted; - Approved; - Done; - WMA; - Waiting for Charge |
Gateway | object | An object that contains information about the bankcard holder who carries out the payment. Object parameters: - Name - payment provider name. The value is set as - Bank Card; - CardHolder - cardholder name; - CardToken - a bankcard token, used to fill in blanks on the payment page if payment is carried out via bankcard; - PanCodeMasked - masked card number. Provided in format 123456******1234; - ShopGatewayId - online store payment method identifier |
OperationType | string | Operation type. The value is set as DualMessageOperation - payment pre-authorisation |
HoldMadeDate | datetime | Date and time when funds were blocked. Transmitted in the yyyy-mm-ddThh:mm:ss.fffZ format |
HoldExpDate | datetime | Date and time when the block on funds will be canceled. Transmitted in the yyyy-mm-ddThh:mm:ss.fffZ format |
Not-Mandatory Callback parameters:
Parameter | Type | Description |
---|---|---|
Order Description | string | Order |
Error | object | An object that contains information about the error. Is returned only for an unsuccessful callback. Object parameters: - Code - error code; - Message - error description |
MaxRebill Attempts | integer | The maximum number of attempts allowed for paying an invoice. Set in the settings of the online store |
UsedRebill Attempts | integer | The number of attempts that were used to pay for the same invoice |
Successful request example:
{
"HoldMadeDate":"2019-03-28T15:05:48.038Z",
"HoldExpDate":"2019-04-06T23:59:00",
"OperationId":21006,
"OrderName":"Order name",
"OrderDescription":"Order description",
"GatewaySumAmount":100.00,
"GatewaySumCurrency":"USD",
"CustomerEmail":"[email protected]",
"InvoiceExpDateTime":"2019-03-28T15:14:40.9380748Z",
"MaxRebillAttempts":10,
"UsedRebillAttempts":2,
"CallbackDate":"2019-03-28T15:06:02.285279Z",
"Sha512":"c77e4b7602c307d2bc4c1c981766067739a83ef7",
"ShopId":251,
"OrderNumber":"28032019_27",
"OrderSumAmount":100.00,
"OrderSumCurrency":"USD",
"OperationState":"WaitingForCharge",
"Gateway":{
"Name":"Bank card",
"CardHolder":"NAME SURNAME",
"CardToken":"07E547D9-586F6A73-F73FBAC0-435ED769",
"PanCodeMasked":"4314 22** **** 0049",
"ShopGatewayId":121
},
"OperationType":"DualMessageOperation"
}
Unsuccessful request example:
{
"HoldMadeDate":"2019-03-28T15:05:48.038Z",
"HoldExpDate":"2019-04-06T23:59:00",
"OperationId":21006,
"OrderName":"Order name",
"OrderDescription":"Order description",
"GatewaySumAmount":100.00,
"GatewaySumCurrency":"USD",
"CustomerEmail":"[email protected]",
"InvoiceExpDateTime":"2019-03-28T15:14:40.9380748Z",
"MaxRebillAttempts":10,
"UsedRebillAttempts":2,
"CallbackDate":"2019-03-28T15:06:02.285279Z",
"Sha512":"c77e4b7602c307d2bc4c1c981766067739a83ef7",
"ShopId":251,
"OrderNumber":"28032019_27",
"OrderSumAmount":100.00,
"OrderSumCurrency":"USD",
"OperationState":"WaitingForCharge",
"Gateway":{
"Name":"Bank card",
"CardHolder":"NAME SURNAME",
"PanCodeMasked":"4314 22** **** 0049",
"ShopGatewayId":121
},
"Error":{
"Code":9003017,
"Message":"Invoice rejected by payer"
},
"OperationType":"DualMessageOperation"
}
EMS sends a HTTP POST request to the online store’s CallbackUrl. If the online store returns 200 OK status, then EMS will receive callback and stop trying to call the handler.
In the absence of a successful response the EMS server will continue to send requests with the following intervals: 1 min, 5 min, 5 min, 10 min, 1 hour, 24 hours. If after 24 hours response was not received, EMS will cease sending requests.
If the online store did not receive callback, it can manually send callback for each operation. The request can be sent an unlimited number of times at any time after completing an operation (receiving a payment or refund).
If callback request was sent manually, the automatic sending of callback for the given operation stops.
Operation identifier issued by EMS, for which a callback will be sent
Bearer access_token
, where the access_token is an access key, obtained in the request response during authorisation
application/x-www-form-urlencoded
curl -X POST "https://ms.epayments.com/api/v1/callback/operation/{id}?id=65" -H "accept: application/json"
Result array parameters
{
"result": {
"operationId": "6678",
"callbackResponseCode": "200",
"responseDate": "2018-08-02T13:12:30.3807367Z"
}
}
Term | Definitions |
---|---|
Buyer(Payer) | The person paying for the goods or services in the merchant’s online store |
Callback | An EMS service which sends information about payment receipts to the online store |
Card token | A bankcard token, which is returned via callback, when the savecard parameter is sent in the request to create payment page - get /paymentpage. Later a said card token can be used for recurrent payments |
Create invoice | Method of creating an invoice, whereby the payment page opens without the online store’s participation. All invoice details are provided in advance by the merchant |
Customisation | Manual adjustment of the payment page elements in accordance with the online store design |
EMS | EMS, or ePayments Merchant Services Limited, is the organization providing merchant services |
Iframe | Method of creating an invoice whereby the payment page opens at the online store |
Invoice | Payment invoice provided to the buyer. Contains the payment amount, currency, and information about the payment recipient |
Merchant | A client using the merchant service for receiving online payments for goods and services on his/her website |
Merchant service | Service for receiving online payments for goods or services |
Online store | The merchant’s website, which is integrated with the EMS API to receive payments |
Payment method | Payment method of the goods or services in the online store. Selection of the payment method is carried out by the online store buyer in the payment page or via an API request in line with the terms of agreement between the merchant and EMS |
Payment page | Web page on which the buyer confirms payment in the online store by using one of the methods provided |
Pre-authorisation | Temporary blocking funds on a client’s card in order to debit them later |
Redirect | Method of creating an invoice whereby the payment page opens at EMS. Redirection is carried out after clicking on the payment button in the online store |
Recurrent payment | A recurrent payment, which is made using previously, saved bankcard. Initiated on the merchant side without the buyer |
To test the capabilities of the EMS service, a merchant is given access to a test web form. You can work with the form even without having a registered online shop in EMS.
Using this form a merchant can set parameters required to generate their payment page.
Web form can be accessed via the following link:
https://sb-ms.epayments.com/create-invoice
After opening the test form, the following fields are available to the merchant:
Field | Description |
---|---|
Shop ID | Online shop identifier. Default value = 1 |
Shop Secret | Online shop secret key. Default value = secret |
Order Number | Order number, which is unique for this online shop. The value is generated automatically |
Order Name | Order/product name |
Order Description | Short description of the order |
Order Amount | The amount, which will be paid for the order. Decimal separator – dot. No more than 2 characters can be entered after the dot |
Payment Currency | Currency, which will be used to pay for the order. Currency type is selected from the list: - USD (default), - EUR, - RUB |
Gateway ID | Invoice payment method: - None; - 1 – pay with card (default); - 2 – pay via ePayments; - 3 – pay via WebMoney |
Payment Page Language | Payment page language. Language is selected from the list: - EN (default), - ES, - RU |
Integration Type | Invoice creation method. Creation method is selected from the list: - Redirect (default); - Invoicing; - Iframe |
Payer e-mail | Payer’s email. Can be field out only if the Integration type = Invoicing |
After entering the test data, a merchant must press the Proceed button in order to generate the link to the payment page. After pressing the button the following button will become available (depending on the Integration type):
To test payments with bankcard the merchant may use the following test details:
Test bank card | 3D Secure | Transfer status |
---|---|---|
Number: 5413330000000019 Expiry date: 01/20 CVC: 589 | Card supports 3D Secure | Successful |
Number: 4314220000000049 Expiry date: 01/22 CVC: 589 | Card does not support 3D Secure | Successful |
Number: 5142905574265797 Expiry date: 01/20 CVC: 221 | Card does not support 3D Secure | Declined by bank |
Number: 2200774546102058 Expiry date: 04/21 CVC: 986 | Card does not support 3D Secure | Declined by transfer provider |
To test payments with ePayments e-Wallet, you can contact your account manager directly or submit a request using the ticket system in your ePayments personal account. Test ePayments account details will be sent to you after it.
To test payments with payment with WebMoney wallet, you can use your own WebMoney wallet. Funds will not be written off from your wallet, since test account will be used as a transfer recipient.
Error code | Description |
---|---|
1001002 | Error in one or several parameters |
1001006 | Access denied |
1001007 | The domain of the address provided must be the same as the main domain |
2001002 | Error in shop settings |
2001003 | Error in shop settings |
2001004 | Error in shop settings |
2001005 | Error in shop settings |
2001006 | Error in shop settings |
2001008 | Error in shop settings |
2001009 | Error in shop settings |
2001010 | Error in shop settings |
2001011 | Error in shop settings |
2001012 | The store has an incorrect tariff position for the payment method |
2001014 | The store does not have a tariff position |
2001016 | Redirect page address missing |
2001018 | Recurrent payment is prohibited by the shop settings |
2001038 | Refund prohibited by shop settings |
2002000 | Unknown error related to incoming payment |
2002001 | Incoming payment not found |
2002002 | The incoming payment has not been found for the operation identifier |
2002004 | Incorrect format |
2002005 | Value must be positive |
2002006 | The order number provided already exists |
2002007 | Error when creating an object |
2002011 | Incoming payment for order number is not found |
2002013 | The incoming payment does not have a transaction identifier on the side of the payment method |
2002015 | OperationLifetime not provided or store has incorrect settings |
2002016 | Invoice expired |
2002017 | Operation cancelled |
2002019 | The value of the specified currency should not have CcyMnrUnts = N. A. |
2002020 | The number of characters after the point does not match the currency standard |
2002024 | Payment cannot be repeated |
2002025 | The original operation with the specified card token does not exist |
2003000 | Unknown error related to payment processing |
2005000 | Unknown error related to payment systems |
2005002 | Payment system does not exist |
2005003 | Error in payment system settings |
2005004 | Error in payment system settings |
2005005 | Unsupported payment system type |
2006000 | Unknown error related to limits |
2006001 | Value exceeds the one-time limit |
2006002 | Value exceeds the cumulative limit |
2006003 | Limit position provided incorrectly |
2007000 | Unknown error related to e-Wallets |
2007001 | e-Wallet not found |
2008001 | Incorrect operation status |
2008002 | Operation with the provided identifier does not exist |
2008003 | Action is not allowed for this operation type |
2008005 | Refund for the operation has already been carried out |
2008006 | Incorrect number of transactions for the operation |
2009000 | Unknown error related to currencies |
2009001 | The currency does not exist |
2009002 | The currency with this Id does not exist |
2010000 | Unknown error related to the payment page |
2011001 | No exchange rate found for the selected currency |
2011002 | Currency exchange rate has expired |
2011003 | No worsening conversion rate was found for a currency pair |
2013001 | Refund amount does not match the incoming payment amount |
2013002 | Incoming transaction is not found |
2013005 | Remaining payment amount after refund must be greater than 1.00 |
2014000 | Unknown error related to tariffs |
2017000 | Unknown error related to the account details of the payment method |
2017001 | Account details for the payment method do not exist |
2017002 | Account details of the payment method are of an incorrect format |
9000000 | Error on the side of the payment system |
9000001 | Payment system timed out |