EMS allows the merchant to issue invoices, which can be paid for by buyer using the following methods:

• Bankcard VISA, Maestro or MasterCard;
• WebMoney wallet;
• ePayments e-Wallet;
• YooMoney wallet
• QIWI wallet (available only for Direct integration type and payment creation method POST /payment).

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 was not transmitted in the request, by default the payment method selection page will open for the buyer:

• If gatewayId = 1, the payment requisites entry page will open for the client when paying by bank card. This same page is opened when selecting the value “Bankcard” on the payment method selection page:

• 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 YooMoney website to pay the invoice. This same site is opened when selecting the value “YooMoney” on the payment method selection page.

The method returns a link via which the online store or buyer can be redirected to the payment page. The method is used for the following payment scenarios Redirect, IFrame and Invoicing.

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:

Not-Mandatory Callback parameters:

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 the Redirect scenario:

• invoice payment parameters are created in the online store;
• payment is carried out by EMS;
• the buyer is automatically redirected from the online store to the EMS payment page.

As part of their integration with EMS, using Redirect integration also allows merchant to access the following operations:

• Creating a link to pay for an invoice - GET /paymentpage.
• Refunding an invoice if payment was made via card - POST /card/refund.
• Cancelling an invoice - POST /cancel.
• Setting a recurring payment - POST /recurrent.
• Receiving a callback for available operations.

For Redirect the workflow is organized in accordance with the following algorithm:

1. The buyer selects goods or services in the online store, goes to the cart and clicks the payment button.
2. The online store transmits the purchase parameters to EMS (price, currency, description etc).
3. A payment link is created in EMS.
4. The buyer follows the link.
5. A payment page opens in EMS where the buyer can pay for their purchase.

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:

• parameters for invoice payment are created in the online store;
• payment takes place in the online store;
• the buyer remains in the online store to pay the invoice.

As part of iFrame integration with EMS a merchant will be able to access the following operations:

• Personalisation and customization of a payment form (customization).
• Creating a link to pay for the invoice - GET /paymentpage.
• Refunding an invoice if payment was made via card - POST /card/refund.
• Cancelling a created invoice - POST /cancel.
• Setting a recurring payment - POST /recurrent.
• Receiving callback for available operations.

For iFrame the workflow is organised in accordance with the following algorithm:

1. The merchant creates the payment page for their online shop.
2. The buyer selects the goods or service in the online store, adds them to the basket and clicks on the pay button.
3. The online store transmits the purchase parameters to EMS (price, currency, description etc.).
4. A payment link is created in EMS.
5. The buyer follows the link.
6. In the online store a payment page opens where the buyer carries out payment.

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);
}

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

Below is an example of 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="display:none">
         </div>
         <div id="error" style="display:none">
         </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 status 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 following html page is the result of the code execution:

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:

• email – buyer (payer) email address;
• card number – card full number;
• expired date – card expiration date;
• cvc – CVC code;
• card holder – cardholder first and last name.

To access customization features, the merchant needs to define the following parameters in the init method when creating the page:

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;
}

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:

• parameters for invoice payment are created by the merchant;
• payment is carried out by EMS;
• the buyer is redirected to the EMS payments page using a link from the merchant.
  
  

Invoicing integration also allows merchant to access the following operations:

• Creating a link to pay for an invoice - GET /paymentpage.
• Refunding an invoice if payment was made via card - POST /card/refund.
• Cancelling an invoice - POST /cancel.
• Setting a recurring payment - POST /recurrent.
• Receiving a callback for available operations.

For Invoicing the workflow is organised in accordance with the following algorithm:

1. The buyer informs the merchant that he/she wishes to acquire goods or services.
2. The merchant prepares invoice parameters (price, currency, description etc.) and sends them to EMS.
3. In response a created link to pay the invoice is received, which the merchant sends to the buyer.
4. The buyer receives a link (directly from the merchant or via email-notification) and opens the payment page.
5. A payment page opens in EMS where the buyer can carry out the payment.

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:

• customerEmail - customer email address;
• sendEmail - an indicator of whether it is necessary to send a notification. Must be = true.

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:

• parameters for invoice payment are created in the online store;
• the buyer enters payment data;
• payment is carried out by EMS;
• EMS payment page is not used then paying the invoice.

The Direct integration also allows merchant to access the following operations:

• Creating payment - POST /v1/payment.
• Refund - POST /card/refund.
• Cancelling an invoice - POST /cancel.
• Charging a card - POST /card/charge.
• Cancelling a hold on temporarily locked funds - POST /card/cancel.
• Setting a recurring payment - POST /recurrent.
• Receiving a callback for available operations.

For Direct the workflow is organized in accordance with the following algorithm:

1. The buyer selects goods or services in the online store, creates a basket and clicks the payment button.
2. The buyer enters payment details.
3. The online store transmits the purchase parameters to EMS (price, currency, description etc).
4. EMS performs the authentication of the online store and carries out the payment.

This method is intended for creating payments using the Direct payment scenario. After the payment request is sent, the merchant will receive:

• link to which the merchant can redirect their buyers to confirm the payment. After clicking on the link, the buyer will be redirected to a page there they must enter a payment confirmation code (3-D Secure), or
  
• a page with the results of the operation (if the 3-D Secure code was not required).
  

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.

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:

• password - to receive token;
• refresh_token - to refresh token

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.

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.

This method allows to refund a payment which was carried out via bankcard or via payment systems wallets - WebMoney, YooMoney, QIWI.

Refund policy:
Refund can be carried out if the following conditions are met:

• the merchant configured the required settings on the EMS side;
• the state of the operations is operationState = done, i.e. the operation was successful;
• refund is made in the original transaction currency.

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 log in using the authorisation method. Regardless of the operation processing status, after sending the request and receiving a response, the merchant will receive a callback.

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:

• match the amount blocked;
• be less than the amount blocked;
• exceed the amount blocked, but no more than by 10%.

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.

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:

• The merchant has access to the operation (access is obtained via online store settings on the EMS side).
• The first payment via card was initiated by the buyer and it was successful.
• The currency of all subsequent payments is the same as the currency of the original payment (the value of the GatewaySumCurrency parameter) made via saved bankcard.

Payment scheme
Recurrent payments are executed in accordance with the following scheme:

1. The merchant calls the payment page via the GET /paymentpage method and pass the saveCard = 1 (saving a card) parameter in the request body.
2. The buyer goes to the payment page and successfully pays the invoice with a card.
3. The merchant receives a callback for a successful transaction. Callback contains the original operation id.
4. At the required frequency, the merchant sends the POST /recurrent request and pass the previously received operation id and the transaction currency in the request body. Transaction currency of subsequent transactions must be the same as the first, original, payment currency.
5. An amount specified in the transaction is automatically debited from the saved card.
6. The buyer and the merchant receive notifications regarding the transaction.

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.

<br>
**Mandatory callback parameters:**

|    Parameter           |    Type    |    Description                                                                                                                                                                                                                                                                      |
|------------------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| OperationId            | integer    | Operation identifier                                                                                                                                                                                                                                                                |
| OrderName              | string     | Order name                                                                                                                                                                                                                                                                          |
| GatewaySum<br>Amount   | decima     | Amount debited from the buyer for the selected payment method                                                                                                                                                                                                                       |
| GatewaySum<br>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<br>Amoun      | decimal    | Order amount                                                                                                                                                                                                                                                                        |
| OrderSum<br>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).<br><br> Object parameters: <br> - **Name** - payment provider name. Possible values are - Bank Card, ePayments; <br><br> - **ShopGatewayId** - online store payment method identifier          |
| Error                  | object     | Response description.<br> Object parameters: <br><br> - **Code** - Response code. If invoice successfully cancelled the code 2002017 will be sent; <br><br> - **Message** - text description                                                                                                |


<br><br>
**Not-Mandatory Callback parameters:**

|    Parameter    |    Type    |    Description                                               |
|-----------------|------------|--------------------------------------------------------------|
| Rate            | string     | Exchange rate for the currency to be credited (if available) |


<br><br>
**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":{

     },
     "Error":{
        "Code":2002017,
        "Message":"Operation canceled"
     },
     "OperationType":"IncomingPayment"
  }

<br><br>
**Unsuccessful cancellation example:**

  {
    "OperationId":9179,
    "OrderName":"Название заказа",
    "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:

• the payment’s final status = Done or Rejected;
• operation type = Refund.

Mandatory callback parameters:

Non-mandatory callback parameters:

Example of a successful refund:

  {
    "CallbackDate":"2018-07-11T17:44:19.5457669Z",
    "PaymentDate":"2018-07-11T16:23:03.618",
    "Sha512":"2b57a72a2c07c7e2b04f258736dec937b89e96e0fd8f9327210f3e39a26d5a34f541d0187dc0a5f9a833cc34e546b
f857963e2286a51a0dd1f7bd65d5032daa8",
    "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":"Покупатель вернул товар",
    "OperationState":"Done",
    "Gateway":{
      "Name":"Bank Card",
      "CardHolder":"ANNA POLYAKOVA",
      "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": "d3a3356e7c6b2fe0c181e343c69d648f62eed2cb85493fd2da21f170ab7eb8d6cd3e6a22614e48df70af4985f52883baa42af5916c010ebbcbd1c1f1e4a9686a",
   "ShopId": 139,
   "IncomingPaymentOperationId": 2780,
   "OrderNumber": 8934912131,
   "OrderSumAmount": 155.55,
   "OrderSumCurrency": "USD",
   "RefundOperationId": 2793,
   "InitiatedBy": "Merchant",
   "RefundCause": "Покупатель вернул товар",
   "OperationState": "Rejected",
   "Gateway": {
    "Name": "Bank Card",
    "CardHolder": "CARDHOLDER NAME",
    "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:

Not-Mandatory Callback parameters:

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.

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:

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

• Copy Link – copy the link to the payment page;
• Reload page – update data in the web form;
• Go to Payment Page – go to the payment page.

To test payments with bankcard the merchant may use the following test details:

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.

• A new parameter - OriginalOperationId was added to the POST /recurrent method. Also cardToken and ShopId parameters were removed.

• A support for the IntegrationType = iFrame invoicing method was added to the GET /paymentpage method. This value is now mandatory for working with iFrame.
• A new subscription events for the merchant were added to the iFrame integration.

• A check for the partial refund amount was added. Now the balance remaining after the refund, cannot be less than 1.00 in the transaction’s currency.
• A new error codes to the refund method - POST /v1/refund was added.

• An ability to send a success, fail and default URL with a domain other than the shop’s domain (webSiteUrl) was added. This option is available only upon sending an additional request to a technical support.
• The endpoint for the refund method was changed and a partial refund option is now available.

• A list of subscription events for merchants who work with iFrame was updated.
• A description of the authorization process for the POST /payment method was added.

• A new payment method for the Direct framework was added - via QIWI wallet.
• Examples of email notifications that are sent to the client after the funds are temporarily blocked on their card during pre-authorization payment were added.

• A new payment scenario - Direct was added. It is used to bill saved bank cards.
  • A new payment method - via YooMoney wallet was added.
  • A new parameter - cardHolderName was added to the GET /paymentpage method. It is used to generate a payment page without cardholder name field.
  • A few changes were made in the EMS payment form design. A button to clear the field was added, the method to switch languages has been changed, several buttons have been renamed.

• A new method for working with payments made via saved cards was added - "One click payment".
• The URLs required to access EMS staging environment were updated.

• Requirements for displaying the “Email” field on the payments page were changed.
• A new parameter - TimeToReject was added. This parameter can be transferred during online shop registration.
• The WalletIdentifier parameter with buyer wallet number was added to the payment status callback. Said parameter is transmitted is invoice is paid via WebMoney wallet or ePayments e-Wallet
• New non-mandatory parameters – AutoReturn for automatic redirecting and MerchRefCode for payer identification, were added to the get /paymentpage method.
• A display of website without protocol (http://www) was added to the email notification.

• A new method for accepting payments was added - pre-authorisation.

• A new method for working with card payments - recurrent payments was added.
• A new method for accepting payments was added. It is now possible to accept payments from WebMoney purses.
• New parameters - MaxRebillAttempts, UsedRebillAttempts, InvoiceExpDateTime have been added to the Callback for accepting payments.
• A list of fields that are displayed in an email notifications with payment results information was updated.
• A feature allowing to save the buyer’s card via the saveCard parameter if payment was successful was added. It is available to the merchants with the appropriate store settings.