#1. BASICS: Store system communicates with Payment gateway using web-services.

##1.1. Services: There are two web-services provided for access from Store system to Payment gateway:

1. order - managing payment orders
2. status - retrieving orders processing status

Payment gateway conforms to the following industry standards and protocols:

• Message Envelope: SOAP 1.1
• Message Transfer: HTTP 1.1
• Encryption: TLS 1.1 or TLS 1.2
• Web Service Description Language: WSDL 1.1
• Data Transfer: XML 1.0
• Encoding: UTF-8

Note: We require standard redundant HTTP client implementation requirements. To receive recommendations, ask Support Team to provide it in the separate document.

##1.2. Identification: Basic HTTP authorization is required for any request. The Store system will be provided with test and production access credentials - login and password or certificate. Access to Payment gateway services can be limited by the list of ip addresses on the basis of security factor. Store is also provided with shop_id - special unique Store identifier in Payment gateway system for request performance.

Note: shop_id is not equal to Acquirer terminals (MID/TID). Shop_id is used to perform operations with the order, while Acquirer terminals are used to complete authorization.

##1.3 Types and global rules: Float type parameters values must be separated with dot (“.”) symbol. This rule is especially relevant to amount parameter in which major monetary unit (e.g. rubles) and minor monetary unit (e.g. kopecks) must be separated by dot.

Datetime parameter values must be in UTC timezone format.

Blank space is also a symbol.

The general timeout for responses is 30 seconds. Average services method call response time equate 2-3 seconds.

In case of SOAP fault the faultstring field will contain an error code (p. 8.1). Store system will receive SOAP fault to incorrect by scheme or by values request.

Example:

    <?xml version="1.0" encoding="utf-8"?>
    <soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/">
    <soap-env:Body>
        <soap-env:Fault>
            <faultcode>registerFault</faultcode>
            <faultstring>SYSTEM_ERROR</faultstring>
            <detail />
        </soap-env:Fault>
    </soap-env:Body>
    </soap-env:Envelope>

##1.4 Schemes: There are 2 basic schemes of card data entry:

1. payment-gateway-side: all card PCI-DSS sensitive data entering on Payment gateway side, and can’t be provided in full form into Store system.
2. store-system-side: for PCI-DSS certified merchants have an option to enter card data on own side and privide it from Store system to Payment gateway.

For payment-gateway-side Payment gateway support only re-direct mechanic. On order registration request (in register method response) Store system will recieve re-direct url to perform Customer browser re-direct to this url. This url will land Customer to secure Payment gateway page and card data entry will be made on secured Payment gateway side.

For store-system-side Payment gateway support 2 mechanics:

1. browser-to-host: Store system on own payment page have to embed special Payment gateway code and call it to send card data from Customer web browser to Payment gateway host.
   
2. host-to-host: Store system collect card data from Customer browser to its own host itself and transfer from it to Payment gateway.

Possible to integrate host-to-host by 2 different ways:

1. one-call: Store system provide card data in order registration (in register method request).
2. two-calls: Store system have to provide card data in separate call after successfull order registration (details described in another document).

Note: In case of one-call scheme card , exp , cvv , holder , amount parameters (card parameter in order registration request) are all mandatory.

##1.5 Order and operations on it:

Order is Payment gateway primary entry, and represents settlement acts between Store and Customer in context of their deal.

Acts are:

1. When the Customer make a Payment to Store.
2. When the Store make a Refund to Customer.

The Payment may have the following stages:

1. Authorization - Customer’s bank holds amount of money on Customer’s account. After this Payment gateway mark order as payed.
2. Charge - Customer’s bank charges amount of money Customer’s account. This stage may be reached only in process of settlement between Store and Acquirer.

The Store system initiate operations on order by calling proper order service methods. Payment gateway supports:

1. register - to initiate the Payment;
2. cancel - to interrupt the Payment before authorization stage;
   
3. reject - to interrupt the Payment after authorization stage and before order confirmation (p. 1.6);
4. confirm - as described in p. 1.6;
5. refund - to make refund to Customer.

##1.6 Confirmation: Confirmation is the process of informing that Payment gateway have to start settlement initiation process between Store and Aquirer. Before the order is confirmed, Payment gateway system holds money authorization on Customer bank account without charging of it. After sending confirmation, capture process begins and Payment gateway schedules payment settlement process.

Payment gateway system supports 2 basic configuration of confirmation:

1. auto - Payment gateway system will schedule settlement process right after the order is payed, this is default configuration.
2. manual - Payment gateway system will schedule settlement process only after receiving confirm request from Store system.

Store has a 2 options for setup Payment gateway reaction on expiry time of confirmation awaiting:

1. confirm-on-expire - will force automatic scheduling confirmation for all unconfirmed orders.
2. cancel-on-expire - will cancel all all unconfirmed orders.

Note: Store may configure expiration period, ask Support Team for this.

##1.7 Order processing

A set of activites in order processing depends on

1. Card entry scheme (p. 1.4)
2. 3d-secure enable status
3. fraudcheck enable status

and consists of the:

1. (optional, only in payment-gateway-side scheme) Card data entry on Payment gateway secure page (avg 1-3 min)
2. (optional, only for 3d-secure enabled) Payment gateway request Customer’s bank for enrollment Customer’s card in 3d-secure program (avg 2-10 secs)
3. (optional, only for 3d-secure enabled) Customer passing 3d-secure authentication procedures, as usual Customer receive and enter secure code on Customer’s bank page (avg 1-2 min)
4. (optional, only for fraudcheck enabled) Fraud management procedures (avg 1-2 sec)
5. Payment gateway request Customer’s bank for authorization of Payment (avg 2-5 sec).

Note: Store system can set Customer browser re-direct pages settings, to assign web pages to which Payment gateway will initiate Customer browser re-direct after successful or unsuccessful order processing completion. If Store request has no re-direct pages settings, Customer will be re-directed to Store home page, registered in Payment gateway database.

Tip: If Store system want to use timelimit to limit total time of processing, it has to appreciate above information and total overhead from Payment gateway internal processes (avg 2-3 sec).

Tip: Store system can limit the list of cards for performing order payment by: - setting default payment document type; - using allowed cards filters (Ask Support team to create card profile(s)). Fraud control and marketing action are the main purposes for using this feature(s).

In case of payment-gateway-side card data entry scheme the following features are available:

1. standard interface Payment page. Standard pages are automatically adapted according to the browser or device window width: less then 800 pixels - mobile, more then 800 pixels - standard interface. Russian language of graphical user interface is set by default. Ask Support team to adjust others available translations (p 8.6).

2. standard iframe Payment page. Iframe page can be used only in case of SSL-certificate presence on Store web site. Default iframe page size - 700x500 pixels. Ask Support team to assign iframe page to Store shop_id.

3. Payment page(s) customization - ask our Support team to provide standard templates for changes performing. Blocks #footer, #header, css can be changed. Pictures can be added. All customized payment pages should be checked, approved, named, uploaded by Support team. To manage several customized pages opening Store system should use Showcase parameter. Order comment can be added on Payment page.

##1.8 Customer notification about complied authorization According to Payment Systems standards the Customer must be notified about complied payment. Notification responsibility can be divided among Store and Payment gateway, or laid on one the participants of this process.

Payment gateway supports the following methods of Customer notification:

1. via mail - letter will contain the mail information about successful authorization (date,merchant name, sum etc.) This method can be used only if Store system transfer description/customer/email parameter. Optionally, the format of mails and the name of mailing server can be changed according to Store business demands.
2. via browser page - successful/unsuccessful authorization data will be shown in Customer web page after payment completion. This method can be used only if card date input is performing on payment-gateway-side.

If Store decides to perform Customer notification by its own, Payment gateway can deactivate notification.

To set up one of the chosen variants Store must ask Support Team for it.

##1.9 Obtaining processing status and results Payment gateway supports the following types of Store system informing about order processing status and results:

1. push - Payment gateway call Store system service. It means that Store system must support proper notification contract, describen in separate document. Ask Support Team for it.
2. pull - Store system call Payment gateway service. It is described in this document (p. 3). Store system decides on its own the frequency and periodicity of order status requests.

Tips: Combined variant assumes that Store system will use both push notification and pull request types. This approach is the most preferable as in case of unavailability of Store system or Payment gateway notification service, Store system can request for order status via different methods of status service or vice versa.

##1.10 Liability levels

1. reliable - Store provide Payment gateway with data for access to goods/services management system. While processing the order payment, Payment gateway will request for availability of certain goods/services, and in case of positive response it will send request for receipt formation for future services or goods delivery.
2. not realiable - Store system independently controls order cart formation, payment status, goods/services delivery.

Note: Store system doesn’t obtain exclusive right to choose one or another Payment gateway liability level. It is approved by Store together with the Acquirer.

#2. ORDER REGISTRATION:

Service: order

Method: register

Request parameters:

Postdata value/name values:

Note: The main difference between ReturnURLOk/ReturnURLFault and ReceiptURL is that ReceiptURL parameter has no indicator of order processing status. This means that Store system should define order status itself (to display it to Customer) using Payment gateway services information.

Example:

    <?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:egop="http://egopay.ru">
    <soapenv:Header />
    <soapenv:Body>
        <egop:registerRequest>
            <egop:order>
                <egop:shop_id>22222</egop:shop_id>
                <egop:number>123-123</egop:number>
            </egop:order>
            <egop:cost>
                <egop:currency>RUB</egop:currency>
                <egop:amount>100</egop:amount>
            </egop:cost>
            <egop:description>
                <egop:timelimit>2025-01-23T10:42:00.000Z</egop:timelimit>
                <egop:shopref>75f76cf3-8e9e-452d-a912-e942992517d9</egop:shopref>
            </egop:description>
            <egop:cards>
                <egop:card>
                    <egop:cvv>222</egop:cvv>
                    <egop:amount>
                        <egop:currency>RUB</egop:currency>
                        <egop:amount>100</egop:amount>
                    </egop:amount>
                    <egop:three_d_secure>
                        <egop:verification_id>QUFBQkJFaDJpUUFBQUFBQUIzYUpBQUFBQUFB</egop:verification_id>
                        <egop:xid>b2sQUFBQkJFaDJpUUF=</egop:xid>
                        <egop:eci>5</egop:eci>
                    </egop:three_d_secure>
                    <egop:holder>Pupkin Vasya</egop:holder>
                    <egop:exp>
                        <egop:month>12</egop:month>
                        <egop:year>2025</egop:year>
                    </egop:exp>
                    <egop:number>5100000000000008</egop:number>
                </egop:card>
            </egop:cards>
            <egop:postdata>
                <egop:entry>
                    <egop:value>ReceiptURL</egop:value>
                    <egop:name>https://abc124.ru/order/</egop:name>
                </egop:entry>
            </egop:postdata>
        </egop:registerRequest>
    </soapenv:Body>
</soapenv:Envelope>

Response parameters:

In case of successful request processing by Payment gateway, Store system will receive the following parameters in response:

Example:

    <?xml version="1.0" encoding="utf-8"?>
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:egop="http://egopay.ru">
    <soapenv:Header />
    <soapenv:Body>
        <egop:registerResponse>
            <egop:event>
                <egop:error>
                    <egop:category>system</egop:category>
                    <egop:code>ok</egop:code>
                    <egop:id>0</egop:id>
                    <egop:tcode>OK</egop:tcode>
                </egop:error>
                <egop:code>change</egop:code>
                <egop:shopref>75f76cf3-8e9e-452d-a912-e942992517d9</egop:shopref>
                <egop:id>123423</egop:id>
            </egop:event>
        </egop:registerResponse>
    </soapenv:Body>
    </soapenv:Envelope>

In case if the response timeout is reached, the Store system can resend the register request or send one of the requests of status service, get status response and repeat register request.

Note: Incorrect request will lead to SOAP fault in response (p. 1.3).

Average time of initiated authorization process equate 5 seconds. 99% authorization responses will be provided in 90 seconds.

If the register request is completed successfuly, Payment gateway set order status to registered. When the order is registered, Payment gateway begins order processing and changes order status to in_progress. After, order status changes depens on authorization results:

1. decline - to not_authorized
2. accept - to authorized

Then authorized, Payment gateway changes order status depens on confirmation configuration (p. 1.6):

1. auto - order status changes to acknowledged, and no manual confirmation required.
2. manual - order status changes to not_acknowledged, and order is ready to manual confirmation.

In case of register request timeout and Store system use pull mechanics to receive processing status, Store system should should start to request status by get_by_order requests as described in p. 3.

#3. ORDER STATUS RETRIEVE At any time after the order was registered, Store system can retrieve order status using get_by_order request.

Service: status

Method: get_by_order

Request parameters:

Example:

    <?xml version="1.0" encoding="utf-8"?>
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:egop="http://egopay.ru">
    <soapenv:Header/>
    <soapenv:Body>
        <egop:get_by_orderRequest>
             <egop:shop_id>22222</egop:shop_id>
             <egop:number>123-123</egop:number>
        </egop:get_by_orderRequest>
    </soapenv:Body>
    </soapenv:Envelope>

Response parameters:

Example:

<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:egop="http://egopay.ru">
    <soapenv:Header/>
    <soapenv:Body>
        <egop:get_by_orderResponse
            xmlns="http://egopay.ru">
            <egop:payments>
                <egop:Payment>
                    <egop:date>2016-04-13T12:29:09</egop:date>
                    <egop:ptype>card</egop:ptype>
                    <egop:authorg>ucs</egop:authorg>
                    <egop:aref>100073124696</egop:aref>
                    <egop:id>610412255284</egop:id>
                    <egop:amount>
                        <egop:amount>100.0</egop:amount>
                        <egop:currency>RUB</egop:currency>
                    </egop:amount>
                    <egop:authcode>123456</egop:authcode>
                </egop:Payment>
            </egop:payments>
            <egop:attempts>
                <egop:Attempt>
                    <egop:date>2016-04-13T12:28:43</egop:date>
                    <egop:change>
                        <egop:reference>test attempt1</egop:reference>
                        <egop:event id="1169739" />
                    </egop:change>
                    <egop:secure>authenticated</egop:secure>
                    <egop:holder>Vasya Pupkin</egop:holder>
                    <egop:devid>163510</egop:devid>
                    <egop:id>100071124694</egop:id>
                    <egop:docid>17168</egop:docid>
                    <egop:error>
                        <egop:tcode>FM</egop:tcode>
                        <egop:category>bank</egop:category>
                        <egop:id>51</egop:id>
                        <egop:code>funds</egop:code>
                    </egop:error>
                </egop:Attempt>
                <egop:Attempt>
                    <egop:date>2016-04-13T12:29:05</egop:date>
                    <egop:change>
                        <egop:reference>test attempt2</egop:reference>
                        <egop:event id="1169745" />
                    </egop:change>
                    <egop:secure>authenticated</egop:secure>
                    <egop:holder>Vasya Pupkin</egop:holder>
                    <egop:devid>163512</egop:devid>
                    <egop:id>100073124696</egop:id>
                    <egop:docid>1401</egop:docid>
                    <egop:error>
                        <egop:tcode>OK</egop:tcode>
                        <egop:category>system</egop:category>
                        <egop:id>0</egop:id>
                        <egop:code>ok</egop:code>
                    </egop:error>
                </egop:Attempt>
            </egop:attempts>
            <egop:customer>
                <egop:phone>79112223344</egop:phone>
                <egop:email>vasya@gmail.com</egop:email>
                <egop:id>1</egop:id>
            </egop:customer>
            <egop:documents>
                <egop:Document>
                    <egop:id>17168</egop:id>
                    <egop:desc>
                        <egop:product>gold</egop:product>
                        <egop:bank>Sberbank</egop:bank>
                        <egop:country>RU</egop:country>
                    </egop:desc>
                    <egop:code>CA</egop:code>
                    <egop:number>510000*0032</egop:number>
                </egop:Document>
                <egop:Document>
                    <egop:id>1401</egop:id>
                    <egop:desc>
                        <egop:bank>Alfabank</egop:bank>
                        <egop:country>RU</egop:country>
                    </egop:desc>
                    <egop:code>CA</egop:code>
                    <egop:number>510000*0008</egop:number>
                </egop:Document>
            </egop:documents>
            <egop:devices>
                <egop:Device>
                    <egop:ip>188.225.12.161</egop:ip>
                    <egop:ver>44.0</egop:ver>
                    <egop:model>Samsung Galaxy 6</egop:model>
                    <egop:os>Android</egop:os>
                    <egop:id>163510</egop:id>
                    <egop:os_ver>5.1</egop:os_ver>
                    <egop:name>Chrome Mobile</egop:name>
                </egop:Device>
                <egop:Device>
                    <egop:ip>188.225.12.161</egop:ip>
                    <egop:ver>44.0</egop:ver>
                    <egop:model>Samsung Galaxy 6</egop:model>
                    <egop:os>Android</egop:os>
                    <egop:id>163512</egop:id>
                    <egop:os_ver>5.1</egop:os_ver>
                    <egop:name>Chrome Mobile</egop:name>
                </egop:Device>
            </egop:devices>
            <egop:status>acknowledged</egop:status>
            <egop:order>
                <egop:shop_id>123</egop:shop_id>
                <egop:number>12345</egop:number>
            </egop:order>
            <egop:events>
                <egop:Event>
                    <egop:id>1169738</egop:id>
                    <egop:shopref>test attempt1</egop:shopref>
                    <egop:code>registration</egop:code>
                    <egop:error>
                        <egop:code>OK
                        </egop:tcode>
                        <egop:category>system</egop:category>
                        <egop:id>0</egop:id>
                        <egop:code>ok</egop:code>
                    </egop:error>
                </egop:Event>
                <egop:Event>
                    <egop:id>1169739</egop:id>
                    <egop:shopref>test attempt1</egop:shopref>
                    <egop:code>change</egop:code>
                    <egop:error>
                        <egop:tcode>OK</egop:tcode>
                        <egop:category>system</egop:category>
                        <egop:id>0</egop:id>
                        <egop:code>ok</egop:code>
                    </egop:error>
                </egop:Event>
                <egop:Event>
                    <egop:id>1169740</egop:id>
                    <egop:shopref>test attempt1</egop:shopref>
                    <egop:code>check</egop:code>
                    <egop:error>
                        <egop:tcode>OK</egop:tcode>
                        <egop:category>system</egop:category>
                        <egop:id>0</egop:id>
                        <egop:code>ok</egop:code>
                    </egop:error>
                </egop:Event>
                <egop:Event>
                    <egop:id>1169741</egop:id>
                    <egop:shopref>test attempt1</egop:shopref>
                    <egop:code>attempt</egop:code>
                    <egop:error>
                        <egop:tcode>OK</egop:tcode>
                        <egop:category>system</egop:category>
                        <egop:id>0</egop:id>
                        <egop:code>ok</egop:code>
                    </egop:error>
                </egop:Event>
                <egop:Event>
                    <egop:id>1169745</egop:id>
                    <egop:shopref>test attempt2</egop:shopref>
                    <egop:code>change</egop:code>
                    <egop:error>
                        <egop:tcode>OK</egop:tcode>
                        <egop:category>system</egop:category>
                        <egop:id>0</egop:id>
                        <egop:code>ok</egop:code>
                    </egop:error>
                </egop:Event>
                <egop:Event>
                    <egop:id>1169746</egop:id>
                    <egop:shopref>test attempt2</egop:shopref>
                    <egop:code>check</egop:code>
                    <egop:error>
                        <egop:tcode>OK</egop:tcode>
                        <egop:category>system</egop:category>
                        <egop:id>0</egop:id>
                        <egop:code>ok</egop:code>
                    </egop:error>
                </egop:Event>
                <egop:Event>
                    <egop:id>1169747</egop:id>
                    <egop:shopref>test attempt2</egop:shopref>
                    <egop:code>accept</egop:code>
                    <egop:error>
                        <egop:tcode>OK</egop:tcode>
                        <egop:category>system</egop:category>
                        <egop:id>0</egop:id>
                        <egop:code>ok</egop:code>
                    </egop:error>
                </egop:Event>
                <egop:Event>
                    <egop:id>1169747</egop:id>
                    <egop:shopref>test attempt2</egop:shopref>
                    <egop:code>acknowledge</egop:code>
                    <egop:error>
                        <egop:tcode>OK</egop:tcode>
                        <egop:category>system</egop:category>
                        <egop:id>0</egop:id>
                        <egop:code>ok</egop:code>
                    </egop:error>
                </egop:Event>
            </egop:events>
        </egop:get_by_orderResponse>
    </soap-env:Body>
</soap-env:Envelope>

Note: Incorrect request will lead to SOAP fault in response (p. 1.3).

get_by_order_period / get_by_payment_period methods are used to get information about the orders registration or payments completion within requested timeframe respectively.

Service: status

Methods: get_by_order_period, get_by_payment_period

Request parameters:

Example:

    <?xml version="1.0" encoding="utf-8"?>
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:egop="http://egopay.ru">
    <soapenv:Header/>
    <soapenv:Body>
        <egop:get_by_order_periodRequest>
             <egop:shop_id>22222</egop:shop_id>
             <egop:start>2016-01-23T10:42:00.000Z</egop:start>
             <egop:stop>2016-01-23T11:42:00.000Z</egop:stop>
        </egop:get_by_order_periodRequest>
    </soapenv:Body>
    </soapenv:Envelope>

Max period value – 2 hours.

Response parameters: include the list of orders, each of that consists of items described above in get_by_order method (see response parameters for get_by_order request).

Note: Incorrect request will lead to SOAP fault in response (p. 1.3).

All described methods of status service are used in 2 cases:

1. to retrieve orderstatus;
2. to get error code in case if no response returned on confirm/refund/reject requests.

#4. ORDER CONFIRMATION: After successful order processing, order status changes to not_acknowledged.

Method usage rules and regulations:

1. amount always must be equal or less authorized amount, else Store system will receive wrong_amount failure (p. 8.1).
2. amount may be less then authorized amount only if Store opened partial confirmation feature. Ask Support Team for it.
3. Store system may send more than one confirm request for one order, and if amount in this requests will be equal then Store system will receive positive response for every request.
4. If Store system will send confirm requests where amount will not be equal then Payment gateway will save amount of the first processed request, and for all another confirm requests with another amount Store system will receive already_processed failure (p. 8.1).

Note: In scenario when Store system did not receive response it may resend it. Payment gateway use shopref parameter (is generated for each new request by Store system) to identify is Payment gateway process this request or not. If case when Payment gateway identify that request already processed, Store system will receive already_processed failure (p. 8.1).

Service: order

Method: confirm

Request parameters:

Example:

    <?xml version="1.0" encoding="utf-8"?>
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:egop="http://egopay.ru">
    <soapenv:Header />
    <soapenv:Body>
        <egop:confirmRequest>
            <egop:order>
                <egop:shop_id>22222</egop:shop_id>
                <egop:number>123-123</egop:number>
            </egop:order>
            <egop:cost>
                <egop:currency>RUB</egop:currency>
                <egop:amount>100</egop:amount>
            </egop:cost>
            <egop:shopref>90bcdcc5-d31d-401a-b9f8-35e86c31aefe</egop:shopref>
        </egop:confirmRequest>
    </soapenv:Body>
    </soapenv:Envelope>

Response parameters: Are the same as in p. 2 (order registration response).

Note: Incorrect request will lead to SOAP fault in response (p. 1.3).

If the confirm request is completed successfully, Payment gateway changes order status to acknowledged. In case of missed order confirmation request, Payment gateway changes order status to canceled.

When Store uses manual confirmation scheme, Payment gateway changes status of every successfully payed order to not_acknowledged. If the confirm request is completed successfully, Payment gateway changes order status to acknowledged. Depending on the chosen type of Payment gateway reaction on expiry time of confirmation awaiting, order status can be changed to:

• confirmed in case of confirm-on-expire scheme;
• cancel in case of cancel-on-expire.

#5. ORDER CANCELATION Cancel method is used to stop payment process of the order, which is already registered in Payment gateway, but isn’t paid for any reason.

Method usage rules and regulations:

1. Cancel method can be used only if order status is registered.
2. Store system may send more than one cancel request for one order. It will receive positive response for every request.
3. If Store system sends cancel requests while order status is not registered then Payment gateway will return already_processed failure (p. 8.1).

Service: order

Method: cancel

Request parameters:

Example:

    <?xml version="1.0" encoding="utf-8"?>
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:egop="http://egopay.ru">
    <soapenv:Header/>
    <soapenv:Body>
        <egop:cancelRequest>
            <egop:order>
                <egop:shop_id>22222</egop:shop_id>
                <egop:number>123-123</egop:number>
            </egop:order>
        </egop:cancelRequest>
    </soapenv:Body>
    </soapenv:Envelope>

Response parameters: Are the same as in p. 2 (order registration response).

Note: Incorrect request will lead to SOAP fault in response (p. 1.3).

If the cancel request is completed successfuly, Payment gateway changes order status to not_authorized.

#6. ORDER REJECT Reject method is used to reverse payment authorization of the order, which is already paid for in Payment gateway. Only authorized payment can be reversed.

Method usage rules and regulations:

1. Reject method can be used only if order status is not_acknowledged.
2. Store system may send more than one cancel request for one order. It will receive positive response for every request.
3. If Store system sends reject requests while order status is not not_acknowledged then Payment gateway will return already_processed failure (p. 8.1).

Service: order

Method: reject

Request parameters:

Example:

    <?xml version="1.0" encoding="utf-8"?>
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:egop="http://egopay.ru">
    <soapenv:Header />
    <soapenv:Body>
        <egop:rejectRequest>
            <egop:order>
                <egop:shop_id>22222</egop:shop_id>
                <egop:number>123-123</egop:number>
            </egop:order>
        </egop:rejectRequest>
    </soapenv:Body>
    </soapenv:Envelope>

Response parameters: Are the same as in p. 2 (order registration response).

Note: Incorrect request will lead to SOAP fault in response (p. 1.3).

If the reject request is completed successfuly, Payment gateway sets order status to canceled.

#7. PAYMENT REFUND The Store must use refund method to complete the payment refund (after the order was confirmed and transaction process is completed).

Method usage rules and regulations:

1. Method may be used only after order confirmation procedure complete successfully (after using confirm method with positive response or authorization in auto confirmation case).
2. amount must be equal or less then confirmed and not refunded amount, else Store system will receive wrong_amount failure (p. 8.1).
3. amount may be less then confirmed and not refunded amount only if Store opened partial refund feature. Ask Support Team for it.
4. Store system may send more than one refund request for one order, if Store opened multiple refunds feature. Ask Support Team for it.

Note: In scenario when Store system did not receive response it may resend it. Payment gateway use shopref parameter (is generated for each new request by Store system) to identify is Payment gateway process this request or not. If case when Payment gateway identify that request already processed, Store system will receive already_processed failure (p. 8.1).

Service: order

Method: refund

Request parameters:

Example: Total cost of the order is 100 RUB, 100 RUB must be refunded.

    <?xml version="1.0" encoding="utf-8"?>
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:egop="http://egopay.ru">
    <soapenv:Header />
    <soapenv:Body>
        <egop:refundRequest>
            <egop:order>
                <egop:shop_id>22222</egop:shop_id>
                <egop:number>123-123</egop:number>
            </egop:order>
            <egop:payment_id>222222111111</egop:payment_id>
            <egop:cost>
                <egop:currency>RUB</egop:currency>
                <egop:amount>100</egop:amount>
            </egop:cost>
            <egop:shopref>d7715995-85ce-4465-bb1b-64f7359e3681</egop:shopref>
        </egop:refundRequest>
    </soapenv:Body>
    </soapenv:Envelope>

Response parameters: Are the same as in p. 2 (order registration response).

Note: Incorrect request will lead to SOAP fault in response (p. 1.3).

If the refund request is completed successfuly, Payment gateway sets order status to refunded.

The Store must use refund method to complete the partial payment refund (after the order was confirmed and transaction process is completed). The Store system should correct refund/cost/amount parameter to perform partial refund.

Service: order

Method: refund

Request parameters: Are the same as for refund method.

Example: Total cost of the order is 100 RUB, 60 RUB must be refunded.

    <?xml version="1.0" encoding="utf-8"?>
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:egop="http://egopay.ru">
    <soapenv:Header />
    <soapenv:Body>
        <egop:refundRequest>
            <egop:order>
                <egop:shop_id>22222</egop:shop_id>
                <egop:number>123-123</egop:number>
            </egop:order>
            <egop:payment_id>222222111111</egop:payment_id>
            <egop:cost>
                <egop:currency>RUB</egop:currency>
                <egop:amount>60</egop:amount>
            </egop:cost>
            <egop:shopref>d7715995-85ce-4465-bb1b-64f7359e3681</egop:shopref>
        </egop:refundRequest>
    </soapenv:Body>
    </soapenv:Envelope>

Response parameters: Are the same as in p. 2 (order registration response).

Note: Incorrect request will lead to SOAP fault in response (p. 1.3).

If the refund request is completed successfuly, Payment gateway sets order status to refunded.

#8. REFERENCES ##8.1. REQUEST PROCESSING SOAP FAULT CODES | Error code | Description | Action expected | |:———–|:————|:—————-| | ALREADY_PROCESSED | order number is already registred in Payment gateway| Check and correct order number

Resend registration request with new order number. | | ACCESS_DENIED | unsuccessful Store authentication | Check credentials and shop_id;

Resend request. | | SYSTEM_ERROR | system malfunction | Resend request latet;

Contact Acquirer Support Team. | | SYSTEM_ERROR | incorrect request performance | Check request accuracy;

Resend request. | | ORDER_ERROR | order not found in service provider system | Check number or host parameters;

Resend request. | | INVALID_ORDER | such order number is not registred in Payment gateway | Check request

Resend request | | PRICING_ERROR | mismatched good/service price in Store sytem and in service provider system |Check relevant good/service price;

Resend request. | | BOOKING_ERROR | incorrect booking status in GDS system | Check booking status and items parameter;

Correct and resend request | | WRONG_AMOUNT | incorrect amount parameter | Check order cost, correct it;

Resend request. | | SESSION_ERROR | GDS session receipt fail | Resend request | | MAX_ATTEMPTS | number of allowed payment attempts is exceeded | Pay attention to Customer | | REPEAT_NEEDED | request processing fail | Resend request later |

##8.2. ORDER ROCESSING ERRORS CODES | ID | CATEGORY | CODE | TCODE | Cause | Solution | |:—|:———|:—–|:——–|:—-|:———| | 0 | system | ok | OK |Operation is completed successfully| | 501 | system | black-list | BL |Customer card is blacklisted | Contact Acquirer Support Team to recieve updated antifraud settings. | 998 | system | max_attempts | LE |number of payments attempts is exceeded| Recommend Customer to appeal to issue bank (of his card) support. | 999 | system | in_progress | IN |order is still processing | Check order status after a while and repeat the request if needed | | 102/103 | system | network | CE | | Repeat the request within the frames of established timelimit.

In case if the problem remains (for example 30% of orders registered within 30 minutes remain unpaid because of system/common error) contact Acquirer Support Team.

! Please, be able to provide us with the examples of such orders. | | 670 | system | fraud | FM |operation is declined by Payment gateway anti-fraud system | Store system support should pay attention to Customer, his order cart and card | | 776 | system | operator | RE |authorization process was interrupted by Backoffice operator | | 333 | system | common | SE | services malfunction | Repeat the request within the frames of established timelimit.

In case if the problem remains for example 30% of orders registered within 30 minutes – remain unpaid because of system/error error – contact Acquirer Support Team.

! Please, be able to provide us with the examples of such orders. | | 334 | system | timeout | TE |processing timeout| Check order status;

Resend request. | | 335 | system | session | SE |Payment gateway is unable to process the request| Resen reqest;

If the problem remains - contact Acquirer Support Team. | 336 | system | denied | SD | payment can’t be performed via this card| Check payment document. | 400 | system | already_processed | AP |the order is already processed | Check request | 681 | system | unavailable_method | SD |Incorrect service/method combination | Check request | 12/13/57/58 | bank | i-prohibition | TD | online payments are restricted for this card | Recommend Customer to appeal to issue bank (of his card) support. | | 4/7/41/43 | bank | fraud | FM |operation is declined by Bank anti-fraud system | Store system support should pay attention to Customer, his order cart and card. | | 666/5 | bank | common | CE |common/indeterminate error | Repeat the request within the frames of established timelimit.

In case if the problem remains for example 30% of orders registered within 30 minutes – remain unpaid because of bank/common error – contact Acquirer Support Team.

! Please, be able to provide us with the examples of such orders. | | 96/82/101 | bank | network | NE |Acquirer’s system is unavailable | Repeat the request within the frames of established timelimit.

In case if the problem remains for example 30% of orders registered within 30 minutes – remain unpaid because of bankerror – contact Acquirer Support Team.

! Please, be able to provide us with the examples of such orders. | | 51 | bank | funds | IF |insufficient funds for order processing | Recommend Customer to appeal to issue bank (of his card) support or check card balance via bank online resources.| | 54/678 | bank | account | IE | Customer entered incorrect card data | Check the accuracy of entered card data, notify Customer about the mistake.| | 61 | bank | limit | LE | operations limit over card is exceeded | Recommend Customer to appeal to issue bank (of his card) support.| | 674 | bank | timeout | TE |order processing timeout| Check order status;

Advice Customer to repeat payment attempt. | 667 | 3dsecure | reject | UE |Customer closed or refreshed secure bank page | | | 668 | 3dsecure | failed | AE |Customer entered incorrect secure bank code | | | 673/672 | 3dsecure | timeout | TE |3ds verification processing timeout | | | 6731/6721 | 3dsecure | network | NE |3ds verification processing timeout | | | 6690 | shop | common | OE | incorrect shop_id settings | Contact Acquirer Support Team.| | 6691 | shop | price | OE |incorrect order cost | Check total order cost and cost of every order item. | | 6692 | shop | status | OE | the order is already processed (paid or canceled) | Check order number and current order status. | | 6693 | shop | network | CE |order processing timeout| Check order status;

Resend request. | | 6694 | shop | commission | OE |incorrect order commission cost | Check and correct commission cost in request to GDS. | | 6695 | shop | invalid_fop | OE |incorrect form of payment | Contact Acquirer Support Team. | | 6696 | shop | wrong_amount | OE | incorrect value of amount parameter | Check “Amount” parameter in request. | | 6700/6701/6702/
6703/6704/6705/
6706/6707/6708/
6709/6710/6711 | shop | error | OE | | 6712 | shop | session | OE | Payment gateway and Store system communication failure | Contact Acquirer Support Team. | | 671 | shop | network | OE | Store system is unavailable | Check the availability of Store system. | | 886 | shop | common | FE | common/indeterminate error | Contact Acquirer Support Team.| | 777 | shop | cancel | RE | order processing was canceled by Store system | | | 675 | user | timeout | TE | Customer ran out of time to perform payment | Check order timelimit. We recommend to set timelimit no less than 5-7 min – according to our statistics it is average time the customer spend on making payment. | | 676 | user | cancel | UE |Customer clicked the button “Back” / “Cancel payment”

or

Customer ‘refreshed’ the payment page | We recommend to notify customer not to leave page while the payment is processing and not to refresh it. | | 677 | user | duplicate | UE | Store system sent several equal order registration request simultaneously | Check Online store settings. | | 679 | user | card_not_binded | IE | incorrect token/customer id | Check request;

Resend request. | | 680 | user | unsupported_card | IE |payment can’t be performed via this card| Check payment document. | | 682 | user | network | UN |network connaction fail | Customer connection failed during 3ds secure authentication process.|

##8.3.ORDER STATUS | Status | Description | Action expected | |:——-|:————|:—————-| | registered | order is registered in Payment gateway system | no action expected | | in_progress | order processing, authorization response is expected | no action expected | | authorized | successful authorization, good/service receipt formation | no action expected | | not_authorized | unsuccessful order processing | Store system can:

perform no request;

create new order;

initiate new payment session | | canceled | authorization is canceled | no action expected | | failed | unsuccessful good/service receipt formation | Store should check availability of good/service, then:

either confirm it manualy via Backoffice system

or

cancel it manualy via Backoffice system. | | not_acknowledged | unsuccessful order confirmation

or

unsuccessful good/service receipt formation| Send confirm or reject request.

In case of unsuccessful good/service receipt formation - no action expected. | | acknowledged | successful order processing, successful receipt formation and successful order confirmation | no action expected | | refunded | successful payment refund | no action expected |

##8.4 EVENT CODES | Code | Description | |:—–|:————| | register| order registration in PG system | | change | order content has changed | | accept | order processing | | reject | payment reject | | acknowledge | order acknowledgement | | refund | payment refund | | cancel | order cancelation | | partial_cancel | partial order cancelation | | attempt | unsuccessful authorization attempt | | check | order content check | | notify | PG services auto notification | | payment_cancel | payment cancelation | | payment_change | order cost has changed | | charge | payment write-off | | subscription_create | recurrent payments schedule creation | | subscription_activate | recurrent payments schedule activation | | subscription_cancel | recurrent payments schedule cancelation |

##8.5 3DS AUTHENTIFICATION STATUS | Status | Description | |:——-|:————| | attempted | 3ds secure code input attempt | | unavailable | 3ds check is unavailable | | started | 3ds check is in process - card is enrolled | | created | 3ds check is in process - re-direct to secure bank page| | unprovided | card doesn’t support 3ds check mechanism | | authenticated | successful authentication | | ready | 3ds check is in process | | not_used | 3ds check wasn’t used (in case of non-3ds scheme of work) | | not_determined | card’s bank hasn’t sent the enrollment response | | not_authenticated | unsuccessful authentication | | not_enrolled | card is not enrolled |

##8.6 User interface language
| Abbreviation | Description | |————–|————-| | ru | Russian | | en | English | | de | German | | cn | Chinese |

##8.7 Payment session types | Abbreviation | Description | |————–|————————————————————| | redirect | Re-direct to Payment gateway secure page | | iframe | iframe format adapted secure Payment gateway page opening | | mobile | mobile format adapted secure Payment gateway page opening | | rest | host-to-host scheme of card data transfer | | token | recurring payment performance |