Web-Service interface

The use of the functions or functionality of the system described in the wsdl but not described in this document is not allowed.

Request for order registration (WS)

The Request for order registration is called registerOrder, it is described in the WSDL of the service (see the Connection coordinates section).
Request parameters::

Name Type Mandatory Description
merchantOrderNumber ANS..32 yes The order number (identifier) in the store's system is unique for each store within the system
description ANS..512 no Description of the order in any form
amount N..20 yes Payment amount in minimum currency units
currency N3 no The payment currency code is ISO 4217. If not specified, it is considered equal to 810 (Russian rubles).
language A2 no The language is encoded in ISO 639-1. If not specified, the default language specified in the store settings will be used.
pageView ANS..20 no

The value of this parameter determines which pages of the payment interface should be loaded for the client. Possible values are:

  • DESKTOP – for pages designed to be displayed on PC screens (pages with names payment_<locale>.html and errors_<locale>.html will be searched for in the archive of the payment interface pages);
  • MOBILE – for pages designed to be displayed on mobile devices (pages with names mobile_payment_<locale>.html and mobile_errors_<locale>.html will be searched for in the archive of the payment interface pages);

  • If the store has added arbitrary prefixes to their page file names, value of the desired prefix should be passed in the pageView parameter for the corresponding pages to be loaded. For example, if iphone is passed in the parameter, pages with names iphone_payment_<locale>.html и iphone_error_<locale>.html will be searched for in the archive of the payment interface pages.
    where:

    • locale – language of the page encoded in ISO 639-1. For example, ru for Russian or en for English.

If the parameter is missing or does not match the format, the default value is pageView=DESKTOP.

sessionTimeoutSecs N...9 no The order lifetime in seconds. If the parameter is not specified, the value specified in the merchant's settings or the default time (1200 seconds = 20 minutes) will be used. If the expirationDate parameter is present in the request, the value of the sessionTimeoutSecs parameter is ignored.
bindingId AN..255 no ID of the binding created earlier. It can only be used if the store has permission to work with bindings. If this parameter is passed in this request, it means: 1. This order can only be paid using a binding; 2. The payer will be redirected to the payment page, where only CVC input is required.
expirationDate ANS no Date and time of the order lifetime expiration. Format: yyyy-MM-dd'T'HH:mm:ss. If this parameter is not passed in the request, then sessionTimeoutSecs is used to determine the end-of-life time of the order.
returnUrl AN..512 yes The address to which the user must be redirected in case of successful payment. The address must be specified in full, including the protocol used (for example, https://test.ru instead of test.ru). Otherwise, the user will be redirected to the address of the following type: http://<payment_gateway_address>/<merchant_address>.
failUrl AN..512 no The address to which the user must be redirected in case of failed payment. The address must be specified in full, including the protocol used (for example, https://test.ru instead of test.ru). Otherwise, the user will be redirected to the address of the following type: http://<payment_gateway_address>/<merchant_address>.
params - no

Tag containing attributes to pass additional parameters of the merchant.

The fields for additional information and its subsequent storage. To pass N parameters, the request must contain N Params tags, where the name attribute contains the name, and the value attribute contains the value:

Name Type Mandatory Description
name AN..20 yes Name of the additional parameter
value AN..1024 yes Value of the additional parameter

These fields can be passed to the Bank processing system to be subsequently displayed in the registries. This functionality can be enabled upon additional agreement with the bank during the integration period.
If sending notifications to a buyer is set up for a seller, the email address of a buyer must be passed in this tag in the email parameter.
clientId AN..255 no

The client's number (ID) in the store's system. It is used to implement the functionality of bindings. It can be present if creating bindings is allowed for the store.

Specifying this parameter when processing payments with the use of bindings is mandatory. Otherwise, a payment will be failed.
merchantLogin AN..255 no To register an order on behalf of a child merchant, specify the merchant login in this parameter.
features ANS..255 no

A container for the feature parameter, where the following values can be passed:

  • AUTO_PAYMENT - if the request for order registration initiates auto-payments.

By default the following fields are passed to the bank processing system:

  • orderNumber – order number in the store system;
  • description – order description.

The fields transferred to the processing system must be no more than 99 characters; %, +, carriage return \r, and line feed \n cannot be used.
If an additional parameter named merchantOrderId is passed in the order, then its value will be passed to the processing system as the order number (instead of the value of the orderNumber field).

Response parameters:

Name Type Mandatory Description
orderId ANS36 no The order number in the payment system. It is unique within the system. It is missing if the order registration failed due to an error detailed in errorCode.
formUrl AN..512 no URL of the payment form to which the client's browser is to be redirected. It is not returned if the order registration failed due to an error detailed in errorCode.
errorCode N3 no Error code.
errorMessage AN..512 no Error description in the language passed in the language parameter in the request.

Error codes (errorCode field):

Meaning Description
0 Request processing took place without system errors
1 Invalid order nuber
1 Order with given order number is processed already
3 Currency is not defined
4 Empty amount
4 The order number cannot be empty
4 The return URL cannot be empty
5 A parameter value has been specified incorrectly
5 Access denied
5 The user must change password
7 System error
13 Using both values, Features FORCETDS/FORCESSL and AUTO_PAYMENT, is not allowed
13 The Merchant does not have the permission to process auto-payments
13 The Merchant does not have the permission to process verification payments
14 Features are specified incorrectly


Request example:

html 
        <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="https://ecom.alfabank.ru/api/soap/merchant-ws/"> 
  <soapenv:Header/> 
  	<soapenv:Body> 
      <mer:registerOrder> 
        <order merchantOrderNumber="78ds901234567890" description=" " amount="15000" currency=" " language=" " pageView="MOBILE" sessionTimeoutSecs=" " bindingId=" " expirationDate="2014-09-08T14:14:14"> 
          <returnUrl>https://tws.egopay.ru/ab/finish.html</returnUrl> 
          <params name="param1" value="valueParam1"/>
          <params name="param2" value="valueParam2"/> 
          <clientId>666</clientId> 
          <merchantLogin> </merchantLogin>
          <features>
            <feature>AUTO_PAYMENT</feature>
          </features>
        </order> 
      </mer:registerOrder> 
  	</soapenv:Body> 
</soapenv:Envelope>

Response example:

html 
        <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
  <soap:Body> 
    <ns1:registerOrderResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/"> 
      <return orderId="05fcbc62-7ee6-4f1a-b3d5-6ca41a982283" errorCode="0" errorMessage="Successful"> 
        <formUrl> https://tws.egopay.ru/ab/mobile_payment_ru.html?mdOrder=05fcbc62-7ee6-4f1a-b3d5-6ca41a982283 </formUrl> 
      </return> 
    </ns1:registerOrderResponse>

Request for order registration with pre-authorization (WS)

The order pre-authorization request is called registerOrderPreAuth (see the Connection coordinates section). It is used to register an order in the case of a two-phase payment pattern.

Request parameters:

Name Type Mandatory Description
merchantOrderNumber ANS..32 yes The order number (identifier) in the store's system is unique for each store within the system
description ANS..512 no Description of the order in any form
amount N..20 yes Payment amount in kopecks (or cents)
currency N3 no The payment currency code is ISO 4217. If not specified, it is considered equal to the default currency code.
language A2 no The language is encoded in ISO 639-1. If not specified, the default language specified in the store settings will be used.
pageView ANS..20 no

The value of this parameter determines which pages of the payment interface should be loaded for the client. Possible values are:

  • DESKTOP – for pages designed to be displayed on PC screens (pages with names payment_<locale>.html and errors_<locale>.html will be searched for in the archive of the payment interface pages);
  • MOBILE – for pages designed to be displayed on mobile devices (pages with names mobile_payment_<locale>.html and mobile_errors_<locale>.html will be searched for in the archive of the payment interface pages);

  • If the store has added arbitrary prefixes to their page file names, value of the desired prefix should be passed in the pageView parameter for the corresponding pages to be loaded. For example, if iphone is passed in the parameter, pages with names iphone_payment_<locale>.html и iphone_error_<locale>.html will be searched for in the archive of the payment interface pages.
    where:

    • locale – language of the page encoded in ISO 639-1. For example, ru for Russian or en for English.

If the parameter is missing or does not match the format, the default value is pageView=DESKTOP.

sessionTimeoutSecs N...9 no The order lifetime in seconds. If the parameter is not specified, the value specified in the merchant's settings or the default time (1200 seconds = 20 minutes) will be used. If the expirationDate parameter is present in the request, the value of the sessionTimeoutSecs parameter is ignored.
bindingId AN..255 no ID of the binding created earlier. It can only be used if the store has permission to work with bindings. If this parameter is passed in this request, it means: 1. This order can only be paid using a binding; 2. The payer will be redirected to the payment page, where only CVC input is required.
expirationDate ANS no Date and time of the order lifetime expiration. Format: yyyy-MM-dd'T'HH:mm:ss. If this parameter is not passed in the request, then sessionTimeoutSecs is used to determine the end-of-life time of the order.
returnUrl AN..512 yes The address to which the user must be redirected in case of successful payment. The address must be specified in full, including the protocol used (for example, https://test.ru instead of test.ru). Otherwise, the user will be redirected to the address of the following type: http://<payment_gateway_address>/<merchant_address>.
failUrl AN..512 no The address to which the user must be redirected in case of failed payment. The address must be specified in full, including the protocol used (for example, https://test.ru instead of test.ru). Otherwise, the user will be redirected to the address of the following type: http://<payment_gateway_address>/<merchant_address>.
params - no

Tag containing attributes to pass additional parameters of the merchant.

The fields for additional information and its subsequent storage. To pass N parameters, the request must contain N Params tags, where the name attribute contains the name, and the value attribute contains the value:

Name Type Mandatory Description
name AN..20 yes Name of the additional parameter
value AN..1024 yes Value of the additional parameter

These fields can be passed to the Bank processing system to be subsequently displayed in the registries. This functionality can be enabled upon additional agreement with the bank during the integration period.
If sending notifications to a buyer is set up for a seller, the email address of a buyer must be passed in this tag in the email parameter.
clientId AN..255 no

The client's number (ID) in the store's system. It is used to implement the functionality of bindings. It can be present if creating bindings is allowed for the store.

Specifying this parameter when processing payments with the use of bindings is mandatory. Otherwise, a payment will be failed.
merchantLogin AN..255 no To register an order on behalf of a child merchant, specify the merchant login in this parameter.
features ANS..255 no

A container for the feature parameter, where the following values can be passed:

  • AUTO_PAYMENT - if the request for order registration initiates auto-payments.

By default the following fields are passed to the bank processing system:

  • orderNumber – order number in the store system;
  • description – order description.

The fields transferred to the processing system must be no more than 99 characters; %, +, carriage return \r, and line feed \n cannot be used.
If an additional parameter named merchantOrderId is passed in the order, then its value will be passed to the processing system as the order number (instead of the value of the orderNumber field).

Response parameters:

Name Type Mandatory Description
orderId ANS36 no The order number in the payment system. It is unique within the system. It is missing if the order registration failed due to an error detailed in errorCode.
formUrl AN..512 no URL of the payment form to which the client's browser is to be redirected. It is not returned if the order registration failed due to an error detailed in errorCode.
errorCode N3 no Error code.
errorMessage AN..512 no Error description in the language passed in the language parameter in the request.

Error codes (errorCode field):

Meaning Description
0 Request processing took place without system errors
1 Invalid order nuber
1 Order with given order number is processed already
3 Currency is not defined
4 Empty amount
4 The order number cannot be empty
4 The return URL cannot be empty
5 Payments with pre-authorization are not allowed
5 The value of one of the parameters is incorrect
5 Access denied
5 The user must change password
7 System error
13 Using both values, Features FORCETDS/FORCESSL and AUTO_PAYMENT, is not allowed
13 The Merchant does not have the permission to process auto-payments
13 The Merchant does not have the permission to process verification payments
14 Features are specified incorrectly


Request example:


html 
            <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="https://ecom.alfabank.ru/api/soap/merchant-ws/"> 
    <soapenv:Header/> 
    <soapenv:Body> 
       <mer:registerOrderPreAuth> 
          <order merchantOrderNumber="asuaakdfadsfasdfasdd5" description=" " amount="10000" currency=" " language="ru" pageView="DESKTOP" bindingId=" " sessionTimeoutSecs=" "> 
             <returnUrl>https://tws.egopay.ru/ab/finish.html</returnUrl> 
             <params name="param1" value="paramValue1"/> 
             <params name="param2" value="paramValue2"/> 
             <clientId>7777</clientId> 
             <merchantLogin> </merchantLogin>
             <features>
                   <feature>AUTO_PAYMENT</feature>
             </features>
          </order> 
       </mer:registerOrderPreAuth> 
    </soapenv:Body>
    </soapenv:Envelope>

Response example:

html 
            <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
    <soap:Body> 
       <ns1:registerOrderPreAuthResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/"> 
          <return orderId="5e5dc6bd-dee3-4c96-849a-09f3f575f4b6" errorCode="0" errorMessage="Success"> 
             <formUrl> https://tws.egopay.ru/ab/payment_ru.html?mdOrder=5e5dc6bd-dee3-4c96-849a-09f3f575f4b6 </formUrl> 
          </return>

Request for Order Payment Completion (WS)

The depositOrder request is used to request the debiting of a previously pre-authorized order (see the Connection coordinates section). This operation can be performed if there are appropriate rights in the system.

Request parameters:

Name Type Mandatory Description
orderId ANS36 yes The order number in the payment system. It is unique within the system..
depositAmount N..5 yes The amount of the debit in the order currency. It may be less than or equal to the amount of pre-authorization. It cannot be less than 1 ruble.
language A2 no The language is encoded in ISO 639-1. If not specified, it is assumed that the language is Russian. The error message will be returned in this language.

Attention!!!
If you do not specify the "depositAmount" parameter, the completion will occur for the entire pre-authorized amount.

Response parameters:

Name Type Mandatory Description
errorCode N3 no Error code.
errorMessage AN..512 no Error description in the language passed in the Language parameter in the request.

Error Codes (ErrorCode field):

Meaning Description
0 Request processing took place without system errors
5 The deposit amount exceeds the reserved amount
5 The deposit amount must be greater than zero or at least one ruble
5 Access denied
5 The user must change password
6 Invalid order nuber
6 orderId not set
7 The payment must be in the correct state
7 System error

Request example:

html 
            <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="https://ecom.alfabank.ru/api/soap/merchant-ws/"> 
    <soapenv:Header/> 
    <soapenv:Body> 
       <mer:depositOrder> 
          <order language="ru" orderId="4302d369-a5e8-4432-a5e5-42acfab52c86" depositAmount="30000"> 
             <!- Zero or more repetitions: -> 
             <params name="?" value="?"/> 
          </order> 
       </mer:depositOrder> 
    </soapenv:Body> 
    </soapenv:Envelope>

Response example:

            <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
    <soap:Body> 
       <ns1:depositOrderResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/"> 
          <return errorCode="6" errorMessage="Invalid order nuber"/> 
       </ns1:depositOrderResponse> 
    </soap:Body>
    </soap:Envelope>

Order Status Request (WS)

The getOrderStatus request is used to request the status of a registered order. (see the Connection coordinates section).
The order status must be determined by the value of the OrderStatus parameter. The AuthCode field is deprecated.

Request parameters:

Name Type Mandatory Description
orderId ANS36 yes The order number in the payment system. It is unique within the system..
language A2 no The language is encoded in ISO 639-1. If not specified, it is assumed that the language is Russian. The error message will be returned in this language.

Response parameters:

Name Type Mandatory Description
orderStatus N2 no The value of this parameter determines the order status in the payment system. The list of possible values is given in the table below. It is missing if the order has not been found.
errorCode N3 no Error code.
errorMessage AN..512 no Error description in the language passed in the Language parameter in the request.
orderNumber AN..32 yes Order number (ID) in the store's system
pan N..19 no The masked number of the card that was used for payment. It is specified only after payment of the order.
expiration N6 no Card expiration date in the YYYYMM format. It is specified only after payment of the order.
cardholderName A..64 no Cardholder's name. It is specified only after payment of the order..
amount N..20 yes Payment amount in kopecks (or cents)
currency N3 no The payment currency code is ISO 4217. If not specified, it is considered equal to 810 (Russian rubles).
approvalCode AN6 no IPS authorization code. This field has a fixed length (6 characters) and can contain digits and Latin letters..
authCode N3 no This field is deprecated. Its value is always "2", regardless of the order status and the authorization code of the processing system.
ip NS..15 no The IP address of the user who paid for the order
date ANS yes Order registration date
orderDesctiption AN..512 yes Description of the order transmitted during its registration
actionCodeDesctiption AN..512 yes Decryption of the response code in the language transmitted in the language parameter in the request.
clientId AN..255 no The client's number (ID) in the store's system, transmitted during the order registration. Present only if the store is allowed to create bindings.
bindingId AN..255 no ID of the binding created when paying for the order or used for payment. Present only if the store is allowed to create bindings.

The orderStatus field can have the following values:

Status number Description
0 The order is registered, but not paid for
1 The pre-authorized amount is reserved (for two-phase payments)
2 Full authorization of the order amount has been carried out
3 Authorization canceled
4 A refund operation was performed on the transaction
5 Authorization has been initiated through the issuing bank's ACS;
6 Authorization denied

Error codes ( errorCode field):

Meaning Description
0 Request processing took place without system errors
2 Payment rejected
5 Access denied
5 The user must change password
5 orderId not specified
6 Unknown order number
7 System error

Request example:

html 
            <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="https://ecom.alfabank.ru/api/soap/merchant-ws/"> 
    <soapenv:Header/> 
    <soapenv:Body> 
       <mer:getOrderStatus> 
          <order orderId="b1221b79-5703-42c9-a4b1-ed0d0f36493e" language="ru"/> 
       </mer:getOrderStatus> 
    </soapenv:Body> 
    </soapenv:Envelope>

Response example:

html 
            <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
    <soap:Body> 
       <ns1:getOrderStatusResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/"> 
          <return orderStatus="2" errorCode="0" orderNumber="456789012345678" pan="411111**1111" expiration="201512" cardholderName="Ivan" amount="15000" currency="810" approvalCode="123456" uthCode="2" ip="212.5.125.194" date="2013-09-03T16:48:52.459+04:00" orderDescription=" " actionCodeDescription="Request successfully processed" clientId="666" bindingId="df0b1801-a754-4576-b174-c2485d98bc9b"/> 
       </ns1:getOrderStatusResponse> 
    </soap:Body> 
    </soap:Envelope>

Advanced Order Status Request (WS)

The getOrderStatusExtended request is used to request the status of a registered order (see the Connection coordinates section).

Request parameters:

Name Type Mandatory Description
orderId ANS36 yes* The order number in the payment system. It is unique within the system.
language A2 no The language is encoded in ISO 639-1. If not specified, it is assumed that the language is Russian. The error message will be returned in this language.
merchantOrderNumber ANS..32 yes* The order number (ID) in the store's system.

The request must pass either the orderId parameter or the merchantOrderNumber parameter. If both parameters are passed in the request, orderId has a higher priority.
There are several sets of response parameters. Exactly what kind of sets of parameters will be returned depends on the version of getOrderStatusExtended specified in the seller's settings.

Name Type Mandatory Description getOrderStatusExtended version
orderNumber AN..32 yes The order number (ID) in the store's system. All versions.
orderStatus N2 no

The value of this parameter determines the order status in the payment system. List of possible values::

  • '0' The order is registered, but not paid for;
  • '1' The pre-authorized amount is reserved (for two-phase payments);
  • '2' Full authorization of the order amount has been carried out;
  • '3' Authorization canceled;
  • '4' A refund operation was performed on the transaction;
  • '5' Authorization has been initiated through the issuing bank's ACS;
  • '6' Authorization denied.

It is missing if the order has not been found.

 All versions.
actionCode N3 yes Response code. All versions.
actionCodeDescription AN..512 yes Decryption of the response code in the language transmitted in the language parameter in the request. All versions.
errorCode N3 no

Error code. The following options are possible:

  • '0' Request processing took place without system errors;
  • '1' orderId or orderNumber expected;
  • '5' Access denied;
  • '5' The user must change password;
  • '6' Order not found;
  • '7' System error.
All versions.
errorMessage AN..512 no Error description in the language passed in the Language parameter in the request. All versions.
amount N..20 yes Payment amount in kopecks (or cents) All versions.
currency N3 no The payment currency code is ISO 4217. If not specified, it is considered equal to 810 (Russian rubles). All versions.
date ANS yes Order registration date. All versions.
orderDescription AN..512 no Description of the order transmitted during its registration All versions.
ip AN..20 yes The buyer's IP address. All versions.

The merchantOrderParams – element is present in the response if the order contains additional seller parameters. Each additional order parameter is presented in a separate merchantOrderParams element.

Name Type Mandatory Description getOrderStatusExtended version
name AN..20 no Name of the additional parameter All versions.
value AN..1024 no Value of the additional parameter All versions.

The cardAuthInfo element - the element contains a structure consisting of a list of the secureAuthInfo element and the following parameters:

Name Type Mandatory Description getOrderStatusExtended version
maskedPan N..19 no The masked number of the card that was used for payment. It is specified only after payment of the order. All versions.
expiration N6 no Card expiration date in the YYYYMM format. It is specified only after payment of the order. All versions.
cardholderName A..64 no Cardholder's name. It is specified only after payment of the order. All versions.
approvalCode AN6 no КPayment authorization code. This field has a fixed length (6 characters) and can contain digits and Latin letters. It is specified only after payment of the order. All versions.
chargeback A..5 no Whether the funds were forcibly returned to the buyer by the bank. The following values are possible: true, false. 06 and above.
paymentSystem N..10 yes Payment system name. The following options are available: VISA, MASTERCARD, AMEX, JCB, CUP, MIR. 08 and above.
product AN..255 yes Additional information about corporate cards. This information is filled in by the technical support in the management console. If there is no such information, an empty value is returned. 08 and above.
paymentWay AS..14 yes The method of making the payment (payment with the input of card data, payment by bindings, etc.). 09 and above.

The secureAuthInfo element (the element consists of an eci element and a threeDSInfo element, which is a list of the cavv and xid parameters):

Name Type Mandatory Description getOrderStatusExtended version
eci N..4 no Electronic commercial indicator. It is specified only after the order payment and in case of appropriate permission. All versions.
cavv ANS..200 no The value of checking the authentication of the cardholder. It is specified only after the order payment and in case of appropriate permission. All versions.
xid ANS..80 no Electronic commercial transaction ID. It is specified only after the order payment and in case of appropriate permission. All versions.

The bindingInfo element consists of the following parameters:

Name Type Mandatory Description getOrderStatusExtended version
clientId AN..255 no The client's number (ID) in the store's system, transmitted during the order registration. Present only if the store is allowed to create bindings. All versions.
bindingId AN..255 no ID of the binding created when paying for the order or used for payment. Present only if the store is allowed to create bindings. All versions.
authDateTime ANS no Date/time of authorization. 02 and above.
authRefNum AN..24 no Reference number. 02 and above.
terminalId AN..10 no Terminal ID. 02 and above.

The paymentAmountInfo element consists of the following parameters:

Name Type Mandatory Description getOrderStatusExtended version
approvedAmount N..20 no The amount reserved on the card (used only for two-phase payments). 03 and above.
depositedAmount N..20 no The amount confirmed for debiting from the card. 03 and above.
refundedAmount N..20 no Refund amount. 03 and above.
paymentState A..10 no Order status. 03 and above.
feeAmount N..20 no Fee amount. 11 and above.

The bankInfo element consists of the following parameters:

Name Type Mandatory Description getOrderStatusExtended version
bankName AN..200 no Name of the Issuing bank. 03 and above.
bankCountryCode AN..4 no Country code of the issuing bank. 03 and above.
bankCountryName AN..160 no Name of the issuing bank's country in the language passed in the language parameter in the request, or in the language of the user who called the method, if the language is not specified in the request. 03 and above.

Request example:

html 
            <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="https://ecom.alfabank.ru/api/soap/merchant-ws/"> 
    <soapenv:Header/> 
    <soapenv:Body> 
       <mer:getOrderStatusExtended> 
          <order orderId="942e8534-ac73-4e3c-96c6-f6cc448018f7" language="ru"> 
             <!--Optional:--> 
             <merchantOrderNumber> </merchantOrderNumber> 
            </order> 
       </mer:getOrderStatusExtended> 
    </soapenv:Body> 
    </soapenv:Envelope >

Response example:

html 
            <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
    <ns1:getOrderStatusExtendedResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/">
         <return orderNumber="00000123" orderStatus="2" actionCode="0" actionCodeDescription="" amount="10000" currency="810" date="2016-12-20T18:48:49.590+03:00" ip="10.7.5.21" errorCode="0" errorMessage="Success">
            <attributes name="mdOrder" value="08c87ec5-399d-49d0-85ed-85c94bb26675"/>
            <cardAuthInfo maskedPan="555555**5599" expiration="201912" cardholderName="asd asd" approvalCode="123456" paymentSystem="MASTERCARD" product="DEBIT">
               <secureAuthInfo>
                  <eci>1</eci>
               </secureAuthInfo>
            </cardAuthInfo>
            <authDateTime>2016-12-20T18:52:16.276+03:00</authDateTime>
            <terminalId>000001</terminalId>
            <authRefNum>111111111111</authRefNum>
            <paymentAmountInfo paymentState="DEPOSITED" approvedAmount="10000" depositedAmount="10000" refundedAmount="0"/>
            <bankInfo bankName="Unated State Bank of Atlanta" bankCountryCode="US" bankCountryName="United States of America"/>
            <chargeback>false</chargeback>
            <paymentWay>CARD</paymentWay>
         </return>
      </ns1:getOrderStatusExtendedResponse>
    </soap:Body>
    </soap:Envelope>

Request for order payment cancellation (WS)

The ReverseOrder request is used to request cancellation of an order (see the Connection coordinates section). The cancellation function is available within a limited time after payment, the exact terms must be specified in the Bank.
The payment cancellation operation can be performed only once. If it ends with an error, the repeated payment cancellation operation will fail.
This function is available to stores in agreement with the Bank. To perform the cancellation operation, the user must have the appropriate rights.

Request parameters:

Name Type Mandatory Description
orderId ANS36 yes The order number in the payment system. It is unique within the system.
language A2 no The language is encoded in ISO 639-1. If not specified, it is assumed that the language is Russian. The error message will be returned in this language.

Response parameters:

Name Type Mandatory Description
errorCode N3 no Error code.
errorMessage AN..512 no Error description in the language passed in the Language parameter in the request.

Error Codes (ErrorCode field):

Meaning Description
0 Request processing took place without system errors
5 Access denied
5 The user must change password
5 orderId not set
6 Invalid order nuber
7 Invalid operation for the current order status
7 System error

Request example:

html 
            <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="https://ecom.alfabank.ru/api/soap/merchant-ws/"> 
    <soapenv:Header/> 
    <soapenv:Body> 
       <mer:reverseOrder> 
          <order language="ru" orderId="f88a2bbf-2021-4ccc-8783-8a13068a89f9"> 
             <!- Zero or more repetitions: -> 
             <params name=" " value=" "/> 
          </order> 
       </mer:reverseOrder> 
    </soapenv:Body> 
    </soapenv:Envelope>

Response example:

html 
            <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
    <soap:Body> 
       <ns1:reverseOrderResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/"> 
          <return errorCode="7" errorMessage="Invalid operation for the current order status"/> 
       </ns1:reverseOrderResponse> 
    </soap:Body> 
    </soap:Envelope>

Request for a refund of the order payment (WS)

The refundOrder request is used for the refund (see the Connection coordinates section).
Upon this request, the funds for the specified order will be returned to the payer. The request will end with an error if the funds for this order have not been debited. The system enables to return funds more than once, but for a total amount not exceeding the initial debit amount.
To process the refund operation, one must have the appropriate rights in the system.

Request parameters:

Name Type Mandatory Description
orderId ANS36 yes The order number in the payment system. It is unique within the system.
refundAmount N..5 yes The refund amount in the order currency. May be less than or equal to the remnant in the order.
language A2 no The language is encoded in ISO 639-1. If not specified, it is assumed that the language is Russian. The error message will be returned in this language.

Response parameters:

Name Type Mandatory Description
errorCode N3 no Error code.
errorMessage AN..512 no Error description in the language passed in the Language parameter in the request.

Error Codes (ErrorCode field):

Meaning Description
0 Request processing took place without system errors
5 Access denied
5 The user must change password
5 orderId not set
5 Incorrect amount
6 Invalid order nuber
7 The payment must be in the correct state
7 The refund amount exceeds the amount debited
7 System error

Request example:

html 
            <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="https://ecom.alfabank.ru/api/soap/merchant-ws/">
    <soapenv:Header/>
    <soapenv:Body>
       <mer:refundOrder>
          <order language="ru" orderId="4302d369-a5e8-4432-a5e5-42acfab52c86" refundAmount="20000">
             <!--Zero or more repetitions:-->
             <params name=" " value=" "/>
          </order>
       </mer:refundOrder>
    </soapenv:Body>
    </soapenv:Envelope>

Response example:

html 
            <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
       <ns1:refundOrderResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/">
          <return errorCode="7" errorMessage="The refund amount exceeds the amount debited"/>
       </ns1:refundOrderResponse>
    </soap:Body>
    </soap:Envelope>

Request to verify the card's enrolment in 3DS (WS)

The verifyEnrollment request is used to verify the card's involvement in 3DS (see the Connection coordinates section).

Request parameters:

Name Type Mandatory Description
pan N12...19 yes Card number

Response parameters:

Name Type Mandatory Description
errorCode N3 no Error code.
errorMessage AN..512 no Error description.
isEnrolled A1 no A sign of the card's enrolment in 3DS. Possible values: Y, N, U.
emitterName AN..160 no Name of the Issuing bank.
emitterCountryCode AN..4 no Country code of the issuing bank.

Error Codes (ErrorCode field):

Meaning Description
0 Request processing took place without system errors
1 The card number is not specified
1 The card number must be a number containing from 13 to 19 digits
5 Access denied
5 The user must change password
6 No information was found for the specified card number
7 System error

Request example:

html 
            <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="https://ecom.alfabank.ru/api/soap/merchant-ws/"> 
    <soapenv:Header/> 
    <soapenv:Body> 
       <mer:verifyEnrollment> 
          <pan>4111111111111111</pan> 
       </mer:verifyEnrollment> 
    </soapenv:Body> 
    </soapenv:Envelope>

Response example:

html 
            <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
    <soap:Body> 
       <ns1:verifyEnrollmentResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/"> 
          <return isEnrolled="Y" emitterName="TEST CARD" emitterCountryCode="RU" errorCode="0"/> 
       </ns1:verifyEnrollmentResponse> 
    </soap:Body> 
    </soap:Envelope>

Request to add additional parameters to the order (WS)

The addParams method is used to add new additional parameters to the order (see the Connection coordinates section).
If an additional parameter already exists in the order, then when adding a parameter with the same name, the last transferred value will be saved in the order.

Request parameters:

Name Type Mandatory Description
orderId ANS36 yes The order number in the payment system. It is unique within the system.
params - yes Tag containing attributes to pass additional parameters of the merchant.

The params tag contains fields of additional information for subsequent storage. To pass N parameters, the request must contain N Params tags, where the name attribute contains the name, and the value attribute contains the value:

Name Type Mandatory Description
name AN..20 yes Name of the additional parameter
value AN..1024 yes Value of the additional parameter

Response parameters

Name Type Mandatory Description
errorCode N3 yes Error code.
errorMessage AN..512 no Error description. Not available if the request is successful.

Error Codes (ErrorCode field):

Meaning Description
0 Request processing took place without system errors
5 Access denied
5 The user must change password
6 orderId not specified
6 Invalid order number
7 System error

Request example:

html 
            <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="https://ecom.alfabank.ru/api/soap/merchant-ws/">
       <soapenv:Header/>
       <soapenv:Body>
    <mer:addParams>
         <request orderId="02988563-0cc4-4109-84ed-15781f0d718e">
            <!--Zero or more repetitions:-->
            <params name="Param1" value="Param1"/>
            <params name="Param2" value="Param2"/>
         </request>
      </mer:addParams>
    </soapenv:Body>
    </soapenv:Envelope>
```html

**Response example:**

```html
    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
    <ns1:addParamsResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/">
         <return errorCode="0"/>
      </ns1:addParamsResponse>
    </soap:Body>
    </soap:Envelope>

Request for statistics on payments for the period (WS)

The getLastOrdersForMerchants method is used to get statistics on payments for a certain period (see the Connection coordinates section).

Request parameters:

Name Type Mandatory Description
language A2 no The language is encoded in ISO 639-1. If not specified, it is assumed that the language is Russian. The error message will be returned in this language.
page N no When processing the request, a list will be generated, divided into pages (with the number of size records per page). The response returns a page with the number specified in the page parameter. Page numbering starts from 0. If the parameter is not specified, the page number 0 will be returned.
size N..3 yes The number of elements on the page (maximum value = 200).
from ANS yes Date and time of the start of the period for sampling orders in the YYYY-MM-DDTHH:mm:ss format.
to ANS yes Date and time of the end of the period for sampling orders in the YYYY-MM-DDTHH:mm:ss format.
transactionStates A..9 yes In this block, it is necessary to list the required order states. Only orders that are in one of the specified states will be included in the report. Possible values: CREATED, APPROVED, DEPOSITED, DECLINED, REVERSED, REFUNDED.
merchants ANS yes A list of logins of merchants whose transactions should be included in the report. Leave this block empty to get a list of reports on all available merchants (subsidiary merchants and merchants specified in the user settings).
searchByCreatedDate A..5 no Possible values: • true – search for orders whose creation date falls within the specified period. • false – search for orders whose payment date falls within the specified period (thus, orders with the CREATED and DECLINED status cannot be present in the report). The default value - false.

Response parameters:

Name Type Mandatory Description
errorCode N..2 yes Error code. The description of possible codes is given below in the "Error codes (ErrorCode field)" table
errorMessage AN..512 no Error description. It is present only if there is an error (errorCode is not equal to 0).
orderStatuses - - Blocks containing information about orders included in the report. See the "orderStatuses block parameters" table below.
totalCount N yes The total number of items in the report (on all pages).
page N yes The number of the current page (equal to the page number transferred in the request).
pageSize N..3 yes The maximum number of records per page (equal to the page size transferred in the request).

Parameters of the orderStatuses block:

Name Type Mandatory Description
orderNumber AN..32 yes The order number (ID) in the store's system.
orderStatus N..2 yes The order status in the payment system. Possible values are shown below in the "orderStatus field" table.
actionCode N..3 yes Response code.
actionCodeDescription AN..512 yes Decryption of the response code.
amount N..20 yes Payment amount in minimum currency units.
currency N3 yes The payment currency code is ISO 4217. If not specified, it is considered equal to the default currency.
date ANS yes Order registration date.
orderDescription AN..512 no Description of the order transmitted during its registration
ip AN..20 no The buyer's IP address. Specified only after payment.
errorCode N..2 yes Error code.
merchantOrderParams - no A tag with attributes that transfer additional merchant parameters. See the "Parameters of the merchantOrderParams block" table below.
attributes - yes Order attributes in the payment system (order number). See the "Attributes block parameters" table below.
cardAuthInfo - no A tag with payment attributes. See the "cardAuthInfo block parameters" table below.
bindingInfo - no A tag with information about the binding that was used to make the payment. See the "bindingInfo block parameters" table below.
authDateTime ANS no Date/time of authorization
terminalId AN..10 no Terminal Id
authRefNum AN..24 no Reference number
paymentAmountInfo - no A tag with information about the amounts of confirmation, debiting, and refund. See the "paymentAmountInfo block parameters" table below.
bankInfo - no A tag with information about the Issuing bank. See the "bankInfo block parameters" table below.

Parameters of the merchantOrderParams block:

Name Type Mandatory Description
name AN..20 yes Name of the merchant's additional parameter
value AN..1024 yes The value of the merchant's additional parameter

Attributes block parameters:

Name Type Mandatory Description
name A7 yes The attribute name - "mdOrder".
value ANS36 yes The attribute value is the order number in the payment system (unique within the system).

cardAuthInfo block parameters:

Name Type Mandatory Description
maskedPan N..19 no The masked number of the card that was used for payment.
expiration N6 no Card expiration date in the YYYYMM format.
cardholderName A..64 no Cardholder's name.
approvalCode AN6 no Payment authorization code. This field has a fixed length (6 characters) and can contain digits and Latin letters.

bindingInfo block parameters:

Name Type Mandatory Description
clientId AN..255 no The client's number (ID) in the store's system.
bindingId AN..255 no ID of the binding used for payment.

paymentAmountInfo block parameters:

Name Type Mandatory Description
paymentState N..9 no Payment status
approvedAmount N..20 no The amount confirmed for debiting.
depositedAmount N..20 no The amount debited from the card.
refundedAmount N..20 no Refund amount.

bankInfo block parameters:

Name Type Mandatory Description
bankName AN..200 no Name of the Issuing bank.
bankCountryCode AN..4 no Country code of the Issuing Bank
bankCountryName AN..160 no Name of the issuing bank's country in the language passed in the language parameter in the request, or in the language of the user who called the method, if the language is not specified in the request.

The OrderStatus field can have the following values:

Meaning Description
0 The order is registered, but not paid for
1 The pre-authorized amount is reserved (for two-phase payments)
2 Full authorization of the order amount has been carried out
3 Authorization canceled
4 A refund operation was performed on the transaction
5 Authorization initiated through the issuing bank's ACS
6 Authorization denied

Error codes (errorCode field):

Meaning Description
0 Request processing took place without system errors
5 One of the required fields is not filled in
5 Invalid format of the transactionStates parameter
7 System error
10 The value of the size parameter exceeds the maximum allowed
10 Insufficient rights to view transactions of the specified merchant

Request example:


html 
            <soapenv:Envelope
    xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
    xmlns:mer="https://ecom.alfabank.ru/api/soap/merchant-ws/"> 
    <soapenv:Header/> 
    <soapenv:Body> 
       <mer:getLastOrdersForMerchants> 
          <request language="ru"> 
             <page>0</page> 
             <size>200</size> 
             <from>2014-10-10T00:00:00</from> 
             <to>2014-11-11T00:00:00</to> 
             <transactionStates> 
                <transactionStates>DEPOSITED</transactionStates> 
                <transactionStates>REVERSED</transactionStates> 
             </transactionStates> 
             <merchants> 
                <merchants>SevenEightNine</merchants> 
             </merchants> 
           <searchByCreatedDate>false</searchByCreatedDate>
          </request> 
       </mer:getLastOrdersForMerchants> 
    </soapenv:Body> 
    </soapenv:Envelope>

Response example:

html 
            <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
    <soap:Body> 
       <ns1:getLastOrdersForMerchantsResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/"> 
          <return errorCode="0"> 
             <orderStatuses orderNumber="58drs0Pes459Hdsddd0567a0" orderStatus="2" actionCode="0" actionCodeDescription="Request successfully processed" amount="250000" currency="810" date="2014-10-28T12:40:49.233+04:00" orderDescription="Opisanie" ip="212.5.125.194" errorCode="0"> 
                <merchantOrderParams name="registr1" value="registr1"/> 
                <attributes name="mdOrder" value="f1a3365b-542c-4c8d-b34c-e9a7ee8dbc9c"/> 
                <cardAuthInfo maskedPan="411111**1111" expiration="201512" cardholderName="Ivan" approvalCode="123456"/> 
                <bindingInfo clientId="666" bindingId="1eabfb8e-b90e-4dc8-bef6-14bd392b1cec"/> 
                <authDateTime>2014-10-28T12:41:01.207+04:00</authDateTime> 
                <terminalId>111113</terminalId> 
                <authRefNum>111111111111</authRefNum> 
                <paymentAmountInfo paymentState="DEPOSITED" approvedAmount="250000" depositedAmount="250000" refundedAmount="0"/>
                <bankInfo bankName="TEST CARD" bankCountryCode="RU" bankCountryName="Russia"/> 
             </orderStatuses> 
             <orderStatuses orderNumber="57drs0Pes459Hdsddd0567a0" orderStatus="2" actionCode="0" actionCodeDescription="Request successfully processed" amount="250000" currency="810" date="2014-10-28T12:34:37.286+04:00" orderDescription="Opisanie" ip="212.5.125.194" errorCode="0"> 
                <merchantOrderParams name="registr1" value="registr1"/> 
                <attributes name="mdOrder" value="09489184-bc5e-44a7-b6c4-3ca1feb8ef69"/> 
                <cardAuthInfo maskedPan="411111**1111" expiration="201512" cardholderName="Ivan" approvalCode="123456"/> 
                <bindingInfo clientId="666" bindingId="1eabfb8e-b90e-4dc8-bef6-14bd392b1cec"/> 
                <authDateTime>2014-10-28T12:34:56.046+04:00</authDateTime> 
                <terminalId>111113</terminalId> 
                <authRefNum>111111111111</authRefNum> 
                <paymentAmountInfo paymentState="DEPOSITED" approvedAmount="250000" depositedAmount="250000" refundedAmount="0"/>
                <bankInfo bankName="TEST CARD" bankCountryCode="RU" bankCountryName="Russia"/> 
             </orderStatuses> 
             <totalCount>2</totalCount> 
             <page>0</page> 
             <pageSize>200</pageSize> 
          </return> 
       </ns1:getLastOrdersForMerchantsResponse> 
    </soap:Body> 
    </soap:Envelope>

Request for payment via an external payment system (WS)

The paymentOrderOtherWay request with special parameters is used to pay for an order via an external payment system (see the Connection coordinates section).
This operation is available if you have the appropriate rights in the system.

Request parameters:

Name Type Mandatory Description
orderId ANS36 yes Order number received during order registration
paymentWay ANS..* yes The payment method is passed in this parameter. Possible values: ALFA_ALFACLICK – for payment using Alfa-Clic" (via the PayByClik system); UPOP – for payment via the UPOP system, available for China UnionPay cardholders.
ip AS..15 no Payer's IP address
language A2 no The language is encoded in ISO 639-1. If not specified, the default language specified in the store settings will be used

Response parameters:

Name Type Mandatory Description
errorCode N1 yes Error code
errorMessage ANS..* (in case of error) Error message
redirect ANS..* no Return address after payment

Error Codes (ErrorCode field):

Meaning Description
0 Request processing took place without system errors
1 orderId not set
1 paymentWay is not set
2 Order not found
5 Session timeout
5 Access denied
5 The user must change password
5 paymentWay is incorrect
5 System error

Request example:

html 
            <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="https://ecom.alfabank.ru/api/soap/merchant-ws/"> 
    <soapenv:Header/> 
    <soapenv:Body> 
       <mer:paymentOrderOtherWay> 
          <order language="ru" orderId="8232a33f-c44f-48ec-b52f-0d63a88c50ae" paymentWay="ALFA_ALFACLICK" ip=" "/> 
       </mer:paymentOrderOtherWay> 
    </soapenv:Body> 
    </soapenv:Envelope>

Response example:

html 
            <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
    <ns1:paymentOrderOtherWayResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/">
         <return redirect="http://217.12.96.193/PayByClick/login.xhtml?orderId=4e6b383e-809d-4e7e-9477-956e9c828934&amp;backUrl=http%3A%2F%2Fya.ru%3ForderId%3D4e6b383e-809d-4e7e-9477-956e9c828934" errorCode="0"/>
      </ns1:paymentOrderOtherWayResponse>
    </soap:Body>
    </soap:Envelope>

Request to make a binding payment (WS)

The paymentOrderBinding request is used to make a payment by bindings (see the Connection coordinates section).

Request parameters:

Name Type Mandatory Description
mdOrder ANS36 yes The order number in the payment system. It is unique within the system..
bindingId ANS36 yes ID of the binding created when paying for the order or used for payment. Present only if the store is allowed to create bindings.
params - no An additional tag with attributes for transmitting additional merchant parameters *.
language A2 no The language is encoded in ISO 639-1. If not specified, the default language specified in the store settings will be used
ip NS..15 yes payer's ip address
cvc N4 no CVC code. This parameter is required if the merchant does not have the "Can make payment without CVC confirmation" permission selected.
email ANS..* no Payer's email address
loyaltyId ANS..* no Loyalty program identifier. The sbrf_spasibo value should be used.
pointsAmount N..20 no The number of bonus points to be deducted.

The fields for additional information and its subsequent storage. These fields can be passed to the Bank processing system to be subsequently displayed in the registries. This functionality can be enabled upon additional agreement with the bank during the integration period. To pass N parameters, the request must contain N Params tags, where the name attribute contains the name, and the value attribute contains the value:

Name Type Mandatory Description
name AN..20 yes Name of the additional parameter
value AN..1024 yes Value of the additional parameter

By default, the orderNumber and its description fields are transferred to the bank's processing system (no more than 99 characters; %, +, carriage return \r, and line feed \n cannot be used)
Response parameters:

Name Type Mandatory Description
redirect ANS..* no With a successful response. In the case of an SSL payment, the URL to which the redirection is made after the payment. In the case of a 3DS payment, the URL for the refund from ACS.
info ANS..* no

With a successful response. The result of the payment attempt. The possible values are shown below:

  • Your payment is proceeded, redirecting...
  • The operation was rejected. Check the entered data, the sufficiency of funds on the card and repeat the operation. Redirecting...
  • Sorry, the payment cannot be made. Redirecting...
  • The operation was rejected. Contact the store. Redirecting...
  • The operation was rejected. Contact the bank that issued the card. Redirecting...
  • The operation is impossible. Cardholder authentication failed. Redirecting...
  • No connection with the bank. Repeat later. Redirecting...
  • Data entry timeout. Redirecting...
  • No response was received from the bank. Repeat later. Redirecting...
errorCode N1 yes Completion code.
errorMessage ANS..* no When responding with an error. Error message.
acsUrl ANS..* no With a successful response in the case of a 3DS payment. URL of the transition to ACS
paReq ANS..* no With a successful response in the case of a 3DS payment. Payment Authentication Request.

Error Codes (ErrorCode field):

Meaning Description
0 Request processing took place without system errors
1 It is necessary to specify the CVC2/CVV2 code, since the merchant does not have permission to make a payment without CVC
1 Invalid CVC format
1 mdOrder not set
1 bindingId not set
1 The email address does not match the template
1 Wrong language
2 Order not found
2 The binding was not found
5 Access denied
5 The user must change password
5 Payment attempts have been exhausted or the session time has ended
7 System error

Request example:

html 
            <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="https://ecom.alfabank.ru/api/soap/merchant-ws/"> 
    <soapenv:Header/> 
    <soapenv:Body> 
       <mer:paymentOrderBinding> 
          <order mdOrder="9213bc5f-5d5b-43d6-a408-b6b93cdde992" bindingId="ca91a4ab-b6d4-495d-b606-8fb0114e679e" language="ru" ip="127.0.0.1" cvc="123" loyaltyId="sbrf_spasibo" pointsAmount="12000"> 
             <!-Zero or more repetitions:-> 
             <params name=" " value=" "/> 
          </order> 
       </mer:paymentOrderBinding> 
    </soapenv:Body> 
    </soapenv:Envelope>

Response example:

html 
            <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
    <soap:Body> 
       <ns1:paymentOrderBindingResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/"> 
          <return errorCode="0" info="Your payment has been processed, redirection is taking place..." redirect="http://example.ru?orderId=9213bc5f-5d5b-43d6-a408-b6b93cdde992"/"/> 
       </ns1:paymentOrderBindingResponse> 
    </soap:Body>
    </soap:Envelope>

Request to deactivate a binding (WS)

The unBindCard request is used to make an existing binding inactive (see the Connection coordinates section).

Request parameters:

Name Type Mandatory Description
bindingId ANS36 yes ID of the binding created when paying for the order or used for payment. Present only if the store is allowed to create bindings

Response parameters:

Name Type Mandatory Description
errorCode N1 yes Completion code
errorMessage ANS..* (in case of error) Error message

Error Codes (ErrorCode field):

Meaning Description
0 Request processing took place without system errors
2 Incorrect binding state (when trying to deactivate an inactive binding)
2 The binding was not found
5 Access denied
5 The user must change password
7 System error

Request example:

html 
            <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="https://ecom.alfabank.ru/api/soap/merchant-ws/"> 
    <soapenv:Header/> 
    <soapenv:Body> 
       <mer:unBindCard> 
          <bindingId>fd3afc57-c6d0-4e08-aaef-1b7cfeb093dc</bindingId> 
       </mer:unBindCard> 
    </soapenv:Body> 
    </soapenv:Envelope>

Response example:

html 
            <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
    <soap:Body> 
       <ns1:unBindCardResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/"> 
          <return errorCode="0" errorMessage="Successful"/> 
       </ns1:unBindCardResponse> 
    </soap:Body> 
    </soap:Envelope>

Request to activate a binding (WS)

The bindCard request is used to activate a previously deactivated binding (see the Connection coordinates section).

Request parameters:

Name Type Mandatory Description
bindingId ANS36 yes ID of the binding created when paying for the order or used for payment. Present only if the store is allowed to create bindings

Response parameters:

Name Type Mandatory Description
errorCode N1 yes Completion code
errorMessage ANS..* (in case of error) Error message

Error Codes (ErrorCode field):

Meaning Description
0 Request processing took place without system errors
2 Incorrect binding state (when trying to deactivate an inactive binding)
2 The binding was not found
5 Access denied
5 The user must change password
7 System error

Request example:

html 
        <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="https://ecom.alfabank.ru/api/soap/merchant-ws/"> 
  <soapenv:Header/> 
  <soapenv:Body> 
    <mer:bindCard> 
      <bindingId>fd3afc57-c6d0-4e08-aaef-1b7cfeb093dc</bindingId> 
    </mer:bindCard> 
  </soapenv:Body> 
</soapenv:Envelope>

Response example:

html 
        <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
  <soap:Body> 
    <ns1:bindCardResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/"> 
      <return errorCode="5" errorMessage="The user must change password"/> 
    </ns1:bindCardResponse> 
  </soap:Body> 
</soap:Envelope>

Request to change the validity period of a binding (WS)

To change the validity period of a binding, use the extendBinding method (see the Connection coordinates section).

Request parameters:

Name Type Mandatory Description
bindingId ANS36 yes ID of the binding created when paying for the order or used for payment. Present only if the store is allowed to create bindings.
newExpiry N6 yes New expiration date (year and month) in the YYYYMM format
language А2 no The language is encoded in ISO 639-1. If not specified, the default language specified in the store settings will be used.

Response parameters:

Name Type Mandatory Description
errorCode N1 yes Completion code
errorMessage ANS..* (in case of error) Error message

Error Codes (ErrorCode field):

Meaning Description
0 Request processing took place without system errors
1 One or more required parameters are not specified or incorrectly specified
2 The binding was not found
5 Access denied
5 The user must change password
7 System error

Request example:

html 
            <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="https://ecom.alfabank.ru/api/soap/merchant-ws/">
    <soapenv:Header/>
    <soapenv:Body>
    <mer:extendBinding>
         <request language=" " bindingId="1eabfb8e-b90e-4dc8-bef6-14bd392b1cec" newExpiry="201807"/>
      </mer:extendBinding>
    </soapenv:Body>
    </soapenv:Envelope>

Response example:

html 
            <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
    <ns1:extendBindingResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/">
         <return errorCode="0" errorMessage="Successful"/>
      </ns1:extendBindingResponse>
    </soap:Body>
    </soap:Envelope>

Request for a list of client bindings (WS)

The getBindings request is used to get a list of bindings by client ID (see the Connection coordinates section).

Request parameters:

Name Type Mandatory Description
clientId AN..255 yes The client's number (ID) in the store's system, transmitted during the order registration. Present only if the store is allowed to create bindings.

Response parameters:

Name Type Mandatory Description
errorCode N1 yes Completion code
errorMessage ANS..* (in case of error) Error message

Binding element (consists of bindingId, maskedPan and ExpiryDate):

Name Type Mandatory Description
bindingId AN..255 no ID of the binding created when paying for the order or used for payment. Present only if the store is allowed to create bindings.
maskedPan N..19 no The masked number of the card that was used for payment. It is specified only after payment of the order.
expiryDate N6 no Card expiration date in the YYYYMM format. It is specified only after payment of the order.

Error Codes (ErrorCode field):

Meaning Description
0 Request processing took place without system errors
1 clientId not set
2 Information not found
5 Access denied
5 The user must change password
7 System error

Request example:

html 
        <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="https://ecom.alfabank.ru/api/soap/merchant-ws/"> 
    <soapenv:Header/> 
    <soapenv:Body> 
       <mer:getBindings> 
          <request clientId="client"/> 
       </mer:getBindings> 
    </soapenv:Body> 
    </soapenv:Envelope>

Response example:

html 
            <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> 
    <soap:Body> 
       <ns1:getBindingsResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/"> 
          <return errorCode="0" errorMessage="Successful"> 
             <bindings> 
                <binding bindingId="fd3afc57-c6d0-4e08-aaef-1b7cfeb093dc" maskedPan="400000**0002" expiryDate="201512"/> 
             </bindings> 
          </return> 
       </ns1:getBindingsResponse> 
    </soap:Body>
    </soap:Envelope>

Request for a list of bank card bindings (WS)

The getBindingsByCardOrId method is used to get a list of bank card bindings (see the Connection coordinates section).
If the appropriate permissions are available, the store can request a list of all bindings related to a particular bank card. One can do this by card number or by a known binding identifier.
The response returns all bindings available to the merchant in accordance with its settings.

Request parameters:

Name Type Mandatory Description
pan N..19 no Card number. Required if bindingId is not specified. The search by the full card number is available to stores only if they have the appropriate permission.
bindingId AN..255 no Binding identifier. Required if pan is not specified. If pan is transferred in the request, the bindingId value is ignored.
showExpired boolean no This parameter determines whether to display bindings with expired cards. Possible values: true, false. By default, the parameter have the "false" value.
language A2 no The language is encoded in ISO 639-1. If not specified, the language specified in the user settings is considered to be used. The error message will be returned in this language.

Response parameters:

Name Type Mandatory Description
errorCode N1 yes Completion code.
errorMessage ANS..* yes Completion code description.

Bindings element (may consist of several "binding" elements)
Binding element (consists of bindingId, maskedPan, expiryDate and clientId):

bindingId AN..255 no Binding identifier.
maskedPan N..19 no The masked number of the card that was used for payment.
expiryDate N6 no Card expiration date in the YYYYMM format.
clientId AN..255 no The client's number (ID) in the merchant's system.

Error codes (errorCode field):

Meaning Description
0 Request processing took place without system errors.
1 Neither the card number nor the binding ID is specified.
2 No information found.
5 Access denied.
5 The user must change password.
7 System error.

Request example:

html 
            <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="https://ecom.alfabank.ru/api/soap/merchant-ws/">
    <soapenv:Header/>
    <soapenv:Body>
    <mer:getBindingsByCardOrId>
         <request pan="4111111111111111" bindingId=" " showExpired="true" language="ru"/>
      </mer:getBindingsByCardOrId>
    </soapenv:Body>
    </soapenv:Envelope>

Response parameters:

html 
            <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
    <ns1:getBindingsByCardOrIdResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/">
         <return errorCode="0" errorMessage="Successful">
            <bindings>
               <binding bindingId="9f43e86d-9744-42a5-8646-c4bb7cf8799a" maskedPan="411111**1111" expiryDate="201912" clientId="12345"/>
               <binding bindingId="51c0750b-1a23-424b-8989-5e8f669124b4" maskedPan="411111**1111" expiryDate="201512" clientId="123456"/>
               <binding bindingId="6a8c0738-cc88-4200-acf6-afc264d66cb0" maskedPan="411111**1111" expiryDate="201912" clientId="666"/>
               <binding bindingId="97a70989-c1fb-49f7-8a42-27c19dc160dw" maskedPan="411111**1111" expiryDate="201512" clientId="666"/>
            </bindings>
         </return>
      </ns1:getBindingsByCardOrIdResponse>
    </soap:Body>
    </soap:Envelope>

Request for payment via Apple Pay (WS)

The applePay request is used to pay via Apple Pay (see the Connection coordinates section).

An example of the request is presented below.

html 
            <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="https://ecom.alfabank.ru/api/soap/merchant-ws/">
    <soapenv:Header/>
    <soapenv:Body>
    <mer:applePay>
         <arg0>
            <merchant>OurBestMerchantLogin</merchant>
            <orderNumber>UAF-203974-DE</orderNumber>
            <description>Test description</description>
            <paymentToken>ew0KICB7DQoJICAidmVyc2lvbiI6ICJSU0FfdjEiLA0KCSAgInNpZ25hdHVyZSI6ICJabUZyWlNCemFXZHVZWFIxY21VPSIsDQoJICAiaGVhZGVyIjogew0KCQkiZXBoZW1lcmFsUHVibGljS2V5IjogIk1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRW14Q2hDcGpLemY5YVh6MjZXVDZaVE4yekUzaUdYUWpjWlJZWUFkUUlURFgyUmtBTmJ0N2s5cmFoRjFoempqbWVWVHhjZ0NvZkg4MXprMkdOVFozZHRnPT0iICAgICAgIA0KCQkid3JhcHBlZEtleSI6ICJYejI2V1Q2WlROMnpFM2lHWFFqYz0iDQoJCSJwdWJsaWNLZXlIYXNoIjogIk9yV2dqUkdrcUVXamRrUmRVclhmaUxHRDBoZS96cEV1NTEyRkpXckdZRm89IiwNCgkJInRyYW5zYWN0aW9uSWQiOiAiYXBwbGUtMTIzNDU2Nzg5MEFCQ0RFRiINCgkgIH0sDQoJICAiZGF0YSI6ICIxZFhFMTNrdnpUVlA2bldFTjhEMnBoclBsZlFjR3I4VzN5ajJTSFlZai9QeWNIV1RqbnBWN3ovRXI3OGJyaT09Ig0KICB9DQp9</paymentToken>
            <language>RU</language>
            <additionalParameters>
               <entry>
                  <key>firstParamName</key>
                  <value>firstParamValue</value>
               </entry>
            </additionalParameters>
            <preAuth>true</preAuth>
    		<ip>127.0.0.1</ip>
    	 </arg0>
      </mer:applePay>
    </soapenv:Body>
    </soapenv:Envelope>

The description of the request is presented in the table below.

Parameter Data type Compulsoriness Description
merchant AN..30 no Merchant's login name in the payment gateway system.
orderNumber AN..32 no A unique order number on the seller's side.
description ANS..512 no Order description.
paymentToken AN..8192 yes

The paymentToken дparameter must contain the Base64 encoded value of the paymentData property obtained from the PKPaymentToken Object from the Apple Pay system (for more information, see Apple Pay documentation).
Thus, in order to make a payment request to the payment gateway, the seller must:

  • 1. get the PKPaymentToken Object containing the paymentData property from the Apple Pay system;
  • 2. extract the value of the paymentData property and encode it in Base64;
  • 3. include the encoded value of the paymentData property as the value of the paymentToken parameter in the payment request that the seller will send to the payment gateway.
language A2 no The language is encoded in ISO 639-1. If not specified, the default language specified in the store settings will be used.
additionalParameters AN..1024 no

Additional order parameters that are saved for viewing from the merchant's personal area. For each additional parameter, the following nested entry parameter should be used, which, in turn, includes the following nested parameters:

  • key - parameter name;
  • value - parameter value.

Below is an example of a part of the request code with several nested parameters.

html 
        <entry>           
  <key>parameter_1</key>
  <value>value_1</value>    
</entry>    
<entry>           
  <key>parameter_2</key>           
  <value>value_2</value>    
</entry>

If the seller has fiscalization configured, when specifying email (the buyer's email address) and/or phone (the buyer's cell phone number) as additional parameters, these parameters are primarily used to send a fiscal receipt.
In the case of using an external MPI, the payment gateway expects that the "eci" parameter will be received in each request for order payment. If the "eci" value differs from those used for SSL authorizations, it is also necessary to pass the "xid" and "cavv" parameters. When paying with MIR cards with 3-D Secure support, if ECI=05 or ECI=06, the CAVV value must be transmitted on a mandatory basis.
preAuth A..5 yes Parameter that determines the need for pre-authorization (blocking funds on the client's account before they are debited). The following values are available: • true - the parameter is enabled, the payment is made with preauthorization (the client's funds are blocked before being debited); • false - the parameter is disabled (debiting is made immediately). If the parameter is not specified in the request, the debiting is made immediately.
clientId ANS..255 no The number of the client for whom one should create a binding for making regular payments. It should be indicated only if a technical payment is made for subsequent regular payments.
ip AN..20 no Payer's IP address.

An example of a PKPaymentToken Object received by a seller from Apple looks as follows: 

        {
  "paymentData": {
    "data": "vj5Uvux7Im8DD8YhSOsJvw5lWmfl2HMUnTNWJhVfTehvFffRhDo54mfpjxMt9vJdp6DwD7fgcNHDxBvnj56qYG4DpOxg1fTSdXgPFrezprZHCrRxPhN/aQQEThe2pQ0c7hgzzZlA6TpkIR/Xtk6CTcEbD1W6znFVdvMgX8G96Gg4OAGl8GaTXdSU3wlMQL5E63CLQzPi1xHVErWl1OOn6hYQuREUDGc7mAjmqMyLwXp6mOwJZ6ZFO/b9HkgFi428rqtOH08AfqkfaIWwIIAz2w3xEoZrDXbgFpNBnN7F2oretCU1/dFvQJjDYbMorKQ8GJbWtlsVbKsy0U91eoUetDcyMpB9zc139STYVoC8yp6Yk6Mn3icCLY0ZBujq7/404kMGpnHgkNVqFc/4SN0U2XQ5rrb14DM8M69w=",
    "signature": "MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID4jCCA4igAwIBAgIIJEPyqAad9XcwCgYIKoZIzj0EAwIwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE0MDkyNTIyMDYxMVoXDTE5MDkyNDIyMDYxMVowXzElMCMGA1UEAwwcZWNjLXNtcC1icm9rZXItc2lnbl9VQzQtUFJPRDEUMBIGA1UECwwLaU9TIFN5c3RlbXMxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwhV37evWx7Ihj2jdcJChIY3HsL1vLCg9hGCV2Ur0pUEbg0IO2BHzQH6DMx8cVMP36zIg1rrV1O/0komJPnwPE6OCAhEwggINMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDEwHQYDVR0OBBYEFJRX22\/VdIGGiYl2L35XhQfnm1gkMAwGA1UdEwEB/wQCMAAwHwYDVR0jBBgwFoAUI/JJxE+T5O8n5sT2KGw/orv9LkswggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMA4GA1UdDwEB/wQEAwIHgDAPBgkqhkiG92NkBh0EAgUAMAoGCCqGSM49BAMCA0gAMEUCIHKKnwSoyq5mXQr1V62c0BXKpaHodYu9TWXEPUWPpbpAiEAkTecfW6+W5l0r0ADfzTCPq2YtbS39w01XIayqBNy8bEwggLuMIICdaADAgECAghJbS+/OpjalzAKBggqhkjOPQQDAjBnMRswGQYDVQQDDBJBcHBsZSBSb290IENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0xNDA1MDYyMzQ2MzBaFw0yOTA1MDYyMzQ2MzBaMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABPAXEYQZ12SF1RpeJYEHduiAou\/ee65N4I38S5PhM1bVZls1riLQl3YNIk57ugj9dhfOiMt2u2ZwvsjoKYT/VEWjgfcwgfQwRgYIKwYBBQUHAQEEOjA4MDYGCCsGAQUFBzABhipodHRwOi8vb2NzcC5hcHBsZS5jb20vb2NzcDA0LWFwcGxlcm9vdGNhZzMwHQYDVR0OBBYEFCPyScRPk+TvJ+bE9ihsP6K7\/S5LMA8GA1UdEwEB/wQFMAMBAf8wHwYDVR0jBBgwFoAUu7DeoVgziJqkipnevr3rr9rLJKswNwYDVR0fBDAwLjAsoCqgKIYmaHR0cDovL2NybC5hcHBsZS5jb20vYXBwbGVyb290Y2FnMy5jcmwwDgYDVR0PAQH/BAQDAgEGMBAGCiqGSIb3Y2QGAg4EAgUAMAoGCCqGSM49BAMCA2cAMGQCMDrPcoNRFpmxhvs1w1bKYr/0F+3ZD3VNoo6+8ZyBXkK3ifiY95tZn5jVQQ2PnenC/gIwMi3VRCGwowV3bF3zODuQZ/0XfCwhbZZPxnJpghJvVPh6fRuZy5sJiSFhBpkPCZIdAAAxggGMMIIBiAIBATCBhjB6MS4wLAYDVQQDDCVBcHBsZSBBcHBsaWNhdGlvbiBJbnRlZ3JhdGlvbiBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMCCCRD8qgGnfV3MA0GCWCGSAFlAwQCAQUAoIGVMBgGCSqGSIb3DQEJAzELBgkqhkiG9w0BBwEwHAYJKoZIhvcNAQkFMQ8XDTE3MDMxNzEwMzgzOVowKgYJKoZIhvcNAQk0MR0wGzANBglghkgBZQMEAgEFAKEKBggqhkjOPQQDAjAvBgkqhkiG9w0BCQQxIgQgvL+q07/reM0N/5b0hwWT7TJReVTdS9QX5SPhiqeie+cwCgYIKoZIzj0EAwIERzBFAiEAttC68Xyzs6I0+tAKmg6x+0UrqmkQN/V5c8RMMIEJHooCIHIgUHbAt2p5WrFHQKrAVL4c7nohRplZWVbVu6wbBeCgAAAAAAAA",
    "header": {
      "publicKeyHash": "fpvAnSDwQFX4NX4pghdjpNwUFhoTH/DDGhew94uJaRA=",
      "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAErKZUfqvhlieGAOaCKeTB/oDEo29fS1jWSKemNDh3fIqmbfs86nL4BGtRsWRxWcMnHN6GFOQm1MEj4m7ZHxe78g==",
      "transactionId": "38e4c267ef1de62a343d0eccada3f7e19f6b22ffc7ede899c039865432ba6aa2"
    },
    "version": "EC_v1"
  },
  "transactionIdentifier": "38E4C267EF1DE62A343D0ECCADA3F7E19F6B22FFC7EDE899C039865432BA6AA2",
  "paymentMethod": {
    "network": "Visa",
    "type": "debit",
    "displayName": "Visa5223"
  }
}

The value of the paymentData property (from the example above), which needs to be encoded in Base64 and passed in a payment request to the payment gateway, looks as follows:

        {
	"data": "vj5Uvux7Im8DD8YhSOsJvw5lWmfl2HMUnTNWJhVfTehvFffRhDo54mfpjxMt9vJdp6DwD7fgcNHDxBvnj56qYG4DpOxg1fTSdXgPFrezprZHCrRxPhN\/aQQEThe2pQ0c7hgzzZlA6TpkIR\/Xtk6CTcEbD1W6znFVdvMgX8G96Gg4OAGl8GaTXdSU3wlMQL5E63CLQzPi1xHVErWl1OOn6hYQuREUDGc7mAjmqMyLwX+p6mOwJZ6ZFO\/b9HkgFi428rqtOH08AfqkfaIWwIIAz2w3xEoZrDXbgFpNBnN7F2oretCU1\/dFvQJjDYbMorKQ8+GJbWtlsVb+Ksy0U91eoUetDcyMpB9zc139STYVoC8yp6Yk6Mn3icCLY0ZBujq7\/404kMGpnHgkNVqFc\/4SN0U2XQ5rrb14DM8M69w=","signature":"MIAGCSqGSIb3DQEHAqCAMIACAQExDzANBglghkgBZQMEAgEFADCABgkqhkiG9w0BBwEAAKCAMIID4jCCA4igAwIBAgIIJEPyqAad9XcwCgYIKoZIzj0EAwIwejEuMCwGA1UEAwwlQXBwbGUgQXBwbGljYXRpb24gSW50ZWdyYXRpb24gQ0EgLSBHMzEmMCQGA1UECwwdQXBwbGUgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTE0MDkyNTIyMDYxMVoXDTE5MDkyNDIyMDYxMVowXzElMCMGA1UEAwwcZWNjLXNtcC1icm9rZXItc2lnbl9VQzQtUFJPRDEUMBIGA1UECwwLaU9TIFN5c3RlbXMxEzARBgNVBAoMCkFwcGxlIEluYy4xCzAJBgNVBAYTAlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwhV37evWx7Ihj2jdcJChIY3HsL1vLCg9hGCV2Ur0pUEbg0IO2BHzQH6DMx8cVMP36zIg1rrV1O\/0komJPnwPE6OCAhEwggINMEUGCCsGAQUFBwEBBDkwNzA1BggrBgEFBQcwAYYpaHR0cDovL29jc3AuYXBwbGUuY29tL29jc3AwNC1hcHBsZWFpY2EzMDEwHQYDVR0OBBYEFJRX22\/VdIGGiYl2L35XhQfnm1gkMAwGA1UdEwEB\/wQCMAAwHwYDVR0jBBgwFoAUI\/JJxE+T5O8n5sT2KGw\/orv9LkswggEdBgNVHSAEggEUMIIBEDCCAQwGCSqGSIb3Y2QFATCB\/jCBwwYIKwYBBQUHAgIwgbYMgbNSZWxpYW5jZSBvbiB0aGlzIGNlcnRpZmljYXRlIGJ5IGFueSBwYXJ0eSBhc3N1bWVzIGFjY2VwdGFuY2Ugb2YgdGhlIHRoZW4gYXBwbGljYWJsZSBzdGFuZGFyZCB0ZXJtcyBhbmQgY29uZGl0aW9ucyBvZiB1c2UsIGNlcnRpZmljYXRlIHBvbGljeSBhbmQgY2VydGlmaWNhdGlvbiBwcmFjdGljZSBzdGF0ZW1lbnRzLjA2BggrBgEFBQcCARYqaHR0cDovL3d3dy5hcHBsZS5jb20vY2VydGlmaWNhdGVhdXRob3JpdHkvMDQGA1UdHwQtMCswKaAnoCWGI2h0dHA6Ly9jcmwuYXBwbGUuY29tL2FwcGxlYWljYTMuY3JsMA4GA1UdDwEB\/wQEAwIHgDAPBgkqhkiG92NkBh0EAgUAMAoGCCqGSM49BAMCA0gAMEUCIHKKnw+Soyq5mXQr1V62c0BXKpaHodYu9TWXEPUWPpbpAiEAkTecfW6+W5l0r0ADfzTCPq2YtbS39w01XIayqBNy8bEwggLuMIICdaADAgECAghJbS+\/OpjalzAKBggqhkjOPQQDAjBnMRswGQYDVQQDDBJBcHBsZSBSb290IENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzAeFw0xNDA1MDYyMzQ2MzBaFw0yOTA1MDYyMzQ2MzBaMHoxLjAsBgNVBAMMJUFwcGxlIEFwcGxpY2F0aW9uIEludGVncmF0aW9uIENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9yaXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABPAXEYQZ12SF1RpeJYEHduiAou\/ee65N4I38S5PhM1bVZls1riLQl3YNIk57ugj9dhfOiMt2u2ZwvsjoKYT\/VEWjgfcwgfQwRgYIKwYBBQUHAQEEOjA4MDYGCCsGAQUFBzABhipodHRwOi8vb2NzcC5hcHBsZS5jb20vb2NzcDA0LWFwcGxlcm9vdGNhZzMwHQYDVR0OBBYEFCPyScRPk+TvJ+bE9ihsP6K7\/S5LMA8GA1UdEwEB\/wQFMAMBAf8wHwYDVR0jBBgwFoAUu7DeoVgziJqkipnevr3rr9rLJKswNwYDVR0fBDAwLjAsoCqgKIYmaHR0cDovL2NybC5hcHBsZS5jb20vYXBwbGVyb290Y2FnMy5jcmwwDgYDVR0PAQH\/BAQDAgEGMBAGCiqGSIb3Y2QGAg4EAgUAMAoGCCqGSM49BAMCA2cAMGQCMDrPcoNRFpmxhvs1w1bKYr\/0F+3ZD3VNoo6+8ZyBXkK3ifiY95tZn5jVQQ2PnenC\/gIwMi3VRCGwowV3bF3zODuQZ\/0XfCwhbZZPxnJpghJvVPh6fRuZy5sJiSFhBpkPCZIdAAAxggGMMIIBiAIBATCBhjB6MS4wLAYDVQQDDCVBcHBsZSBBcHBsaWNhdGlvbiBJbnRlZ3JhdGlvbiBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMCCCRD8qgGnfV3MA0GCWCGSAFlAwQCAQUAoIGVMBgGCSqGSIb3DQEJAzELBgkqhkiG9w0BBwEwHAYJKoZIhvcNAQkFMQ8XDTE3MDMxNzEwMzgzOVowKgYJKoZIhvcNAQk0MR0wGzANBglghkgBZQMEAgEFAKEKBggqhkjOPQQDAjAvBgkqhkiG9w0BCQQxIgQgvL+q07\/reM0N\/5b0hwWT7TJReVTdS9QX5SPhiqeie+cwCgYIKoZIzj0EAwIERzBFAiEAttC68Xyzs6I0+tAKmg6x+0UrqmkQN\/V5c8RMMIEJHooCIHIgUHbAt2p5WrFHQKrAVL4c7nohRplZWVbVu6wbBeCgAAAAAAAA",
	"header": {
		"publicKeyHash":"fpvAnSDwQFX4NX4pghdjpNwUFhoTH\/DDGhew94uJaRA=",
		"ephemeralPublicKey":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAErKZUfqvhlieGAOaCKeTB\/oDEo29fS1jWSKemNDh3fIqmbfs86nL4BGtRsWRxWcMnHN6GFOQm1MEj4m7ZHxe78g==",
		"transactionId":"38e4c267ef1de62a343d0eccada3f7e19f6b22ffc7ede899c039865432ba6aa2"
	},
	"version":"EC_v1"
}

Below is an example of a response after a successful payment.

html 
            <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
    <ns1:applePayResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/">
         <return>
            <success>true</success>
            <data>
               <orderId>12312312123</orderId>
            </data>
            <orderStatus errorCode="0"/>
         </return>
      </ns1:applePayResponse>
    </soap:Body>
    </soap:Envelope>

Below is an example of a response after a failed payment.

html 
            <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
    <ns1:applePayResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/">
         <return>
            <success>false</success>
            <error>
               <code>10</code>
               <description>No private key</description>
            </error>
            <orderStatus errorCode="0"/>
         </return>
      </ns1:applePayResponse>
    </soap:Body>
    </soap:Envelope>

The description of the response parameters is presented in the table below.

Parameter Netsed Parameter Data type Mandatory parameter Description
success Not relevant A..5 yes Indicates the success of the payment. The following values are available: true - the request was processed successfully; false - the request failed.
data (returned only if the payment was successful) orderId ANS36 yes The order number unique to the seller in the payment system.
error (returned only if the payment failed) code N..2 yes Error code.
description - ANS..512 yes Detailed technical explanation of the error - the contents of this parameter are not intended to be displayed to the user.

The error codes that can be returned as a result of an unsuccessful payment are shown in the table below. Information about the parameters used is also provided in the Apple documentation.

Error code Message
4 Invalid value of the paymentToken.signature parameter, verification failed
10 Invalid value of the merchant parameter
10 Invalid value of the orderNumber parameter
10 Invalid value of the paymentToken parameter
10 Invalid value of the paymentToken.version parameter
10 Invalid value of the paymentToken.header parameter
10 Invalid value of the paymentToken.signature parameter
10 Invalid value of the paymentToken.header.transactionId parameter
10 Invalid value of the paymentToken.header.wrappedKey parameter
10 Invalid value of the paymentToken.header.publicKeyHash parameter
10 Authorization failed

Request for recurring payments via Apple Pay (WS)

This functionality supports recurrent payments only with MasterCard cards

The recurrentPayment request is used to register an order (see the Connection coordinates section).
The parameters are described in the table below

Parameter Compulsoriness Description
orderNumber yes Order number.
bindingId yes Binding identifier.
amount yes Payment amount.
description no Order description.
additionalParameters no

Additional order parameters that are saved for viewing from the merchant's personal area. For each additional parameter, the following nested entry parameter should be used, which, in turn, includes the following nested parameters:

  • key - parameter name;
  • value - parameter value.

Below is an example of a part of the request code with several nested parameters.

html 
        <entry>           
  <key>parameter_1</key>
  <value>value_1</value>    
</entry>    
<entry>           
  <key>parameter_2</key>           
  <value>value_2</value>    
</entry>

If the seller has fiscalization configured, when specifying email (the buyer's email address) and/or phone (the buyer's cell phone number) as additional parameters, these parameters are primarily used to send a fiscal receipt.
In the case of using an external MPI, the payment gateway expects that the "eci" parameter will be received in each request for order payment. If the "eci" value differs from those used for SSL authorizations, it is also necessary to pass the "xid" and "cavv" parameters. When paying with MIR cards with 3-D Secure support, if ECI=05 or ECI=06, the CAVV value must be transmitted on a mandatory basis.

Below is an example of a successful response to a request.

html 
            <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
    <ns1:recurrentPaymentResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/">
         <return>
            <success>true</success>
            <data>
               <orderId>134561314642</orderId>
            </data>
            <orderStatus errorCode="0"/>
         </return>
      </ns1:recurrentPaymentResponse>
    </soap:Body>
    </soap:Envelope>

Below is an example of an unsuccessful response to a request.

html 
            <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
    <ns1:recurrentPaymentResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/">
         <return>
            <success>false</success>
            <error>
               <code>10</code>
               <description>An order with this number has already been registered</description>
            </error>
            <orderStatus errorCode="0"/>
         </return>
      </ns1:recurrentPaymentResponse>
    </soap:Body>
    </soap:Envelope>

The description of the response parameters is presented in the table below.

Parameter Nested parameter Mandatory parameter Description
success Not relevant yes Indicates the success of the payment. The following values are available: true - the request was processed successfully; false - the request failed.
data (returned only if the payment was successful) orderId yes The order number unique to the seller in the payment system.
error (returned only if the payment failed) code yes Error code.
description - yes Detailed technical explanation of the error - the contents of this parameter are not intended to be displayed to the user.


Request for payment via Google Pay (WS)

The parameters are described in the table below.

Parameter Mandatory Description
merchant Yes Merchant's login name in the payment gateway system.
orderNumber Yes A unique order number on the seller's side.
description no Order description.
language no The language is encoded in ISO 639-1. If not specified, the default language specified in the store settings will be used.
additionalParameters no

Additional order parameters that are saved for viewing from the merchant's personal area. For each additional parameter, the following nested entry parameter should be used, which, in turn, includes the following nested parameters: :

  • key - parameter name;
  • value - parameter value.


Below is an example of a part of the request code with several nested parameters.

        <entry>
	<key>parameter_1</key>
	<value>value_1</value>
</entry>
<entry>
	<key>parameter_2</key>
	<value>value_2</value>
</entry>

In the case of using an external MPI, the payment gateway expects that the eci parameter will be received in each request for order payment. If the "eci" value differs from those used for SSL authorizations, it is also necessary to pass the "xid" and "cavv" parameters.

                When paying with MIR cards with 3-D Secure support, if ECI=05 or ECI=06, the cavv value must be transmitted on a mandatory basis.
preAuth no Parameter that determines the need for pre-authorization (blocking funds on the client's account before they are debited). The following values are available: • true - the parameter is enabled, the payment is made with preauthorization (the client's funds are blocked before being debited); • false - the parameter is disabled (debiting is made immediately). If the parameter is not specified in the request, the debiting is made immediately.
clientId no The number of the client for whom one should create a binding for making regular payments. It should be indicated only if a technical payment is made for subsequent regular payments.
paymentToken Yes A token received from Google Pay and encoded in Base64.
ip Yes Payer's IP address.
amount Yes Payment amount in minimum units of currency (e.g., kopecks).
currencyCode no The payment currency digital code as per ISO 4217. If not specified, it is considered equal to 643 (Russian ruble).
email no (see description) Email address. Required if the online store has fiscalization configured and no phone number is specified.
phone no (see description) Phone number. Required if the online store has fiscalization configured and no email address is specified.
failUrl no to which the user must be redirected in case of failed payment. The address must be specified in full, including the protocol used (for example, https://test.ru instead of test.ru)). Otherwise, the user will be redirected to the address of the following type:http://<payment_gateway_address>/<merchant_address>. 
                See also the 3 DS-payment block - for one-phase and two-phase payments. 
failUrl is used in the same way as in step 11 in the specified patterns.
returnUrl Yes The address to which the user must be redirected in case of successful payment. The address must be specified in full, including the protocol used (for example, https://test.ru instead of test.ru). Otherwise, the user will be redirected to the address of the following type: http://<payment_gateway_address>/<merchant_address>. 
        See also the 3 DS-payment block - for one-phase and two-phase payments. 
returnUrl is used in the same way as in step 11 in the specified patterns.

Below is an example of a request for payment.

To process the request correctly, one needs to add a header with the definition of the content type - Content-Type: application/json..

        
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:mer="https://ecom.alfabank.ru/api/soap/merchant-ws/">
<soapenv:Header/>
<soapenv:Body>
<mer:googlePay>
<arg0>
<merchant>OurBestMerchantLogin</merchant>
<orderNumber>UAF-203974-DE</orderNumber>
<language>RU</language>
<preAuth>true</preAuth>
<paymentToken>ewogICJwcm90b2NvbFZlcnNpb24iOiAiRUN2MSIsCiAgInNpZ25hdHVyZSI6ICJUSlZBOTVPck03RTJjQmFiMzBSTUhySERjRWZ4am9ZWmdlRk9ORmg3SGdRIiwKICAic2lnbmVkTWVzc2FnZSI6ICJ7XCJlbmNyeXB0ZWRNZXNzYWdlXCI6CiAgXCJaVzVqY25sd2RHVmtUV1Z6YzJGblpRPT1cIixcImVwaGVtZXJhbFB1YmxpY0tleVwiOgogIFwiWlhCb1pXMWxjbUZzVUhWaWJHbGpTMlY1XCIsXCJ0YWdcIjogXCJjMmxuYm1GMGRYSmxcIn0iCn0=</paymentToken>
<ip>127.0.0.1</ip>
<amount>230000</amount>
<currencyCode>810</currencyCode>
<returnUrl>https://test.ru</returnUrl>
</arg0>
</mer:googlePay>
</soapenv:Body>
</soapenv:Envelope>


The description of the response parameters is given in the table below.

Parameter Nested parameter Mandatory parameter Description
success Not relevant Yes Indicates the success of the payment. The following values are available: true - the request was processed successfully and false - the request failed.
data orderId Yes The order number unique to the seller in the payment system.
data termUrl Only if additional authentication is used on the issuing bank's ACS With a successful response in the case of a payment in which the card was checked for belonging to 3-D Secure. The URL to return from the access control server.
data acsUrl Only if additional authentication is used on the issuing bank's ACS Upon successful response in case of payment using 3-D Secure. The URL to go to the access control server.
data paReq Only if additional authentication is used on the issuing bank's ACS Upon successful response in case of payment using 3-D Secure. Payment Authentication Request - request for payment authentication.
data bindingId Only when using bindings ID of the previously created binding. It can only be used if the seller has permission to work with bindings.
error code Yes Error code.
error description Yes Detailed technical explanation of the error – the contents of this parameter are not intended to be displayed to the user.
error message Yes Clear error description – designed to be displayed to the user.

data - returned only if the payment was successful
error - returned only if the payment failed
Examples and description of the response


Below is an example of a response after a successful payment.

        <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:googlePayResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/">
         <return>
            <success>true</success>
            <data>
               <orderId>12312312123</orderId>
            </data>
            <orderStatus errorCode="0"/>
         </return>
      </ns1:googlePayResponse>
   </soap:Body>
</soap:Envelope>


Example of a response after an unsuccessful payment

        <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns1:googlePayResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/">
         <return>
            <success>false</success>
            <error>
               <code>10</code>
               <description>Invalid value of the [OrderNumber] parameter</description>
            </error>
            <orderStatus errorCode="0"/>
         </return>
      </ns1:googlePayResponse>
   </soap:Body>
</soap:Envelope>


Possible error codes are described in the table below.

Error code Error message
0 Request processing took place without system errors
1 Insufficient funds on the card
5 Access denied
5 The user must change password
7 System error
10 Invalid value of the paymentToken parameter
10 Invalid value of the orderNumber parameter
10 Invalid value of the merchant parameter
10 Invalid ip parameter value
10 Decryption of the transferred data failed
10 No private key

Request for payment via Samsung Pay (WS)

The samsungPay request is used to pay via Samsung Pay (see the Connection coordinates section).
Below is an example of a request for payment.

html 
            <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mer="https://ecom.alfabank.ru/api/soap/merchant-ws/">
    <soapenv:Header/>
    <soapenv:Body>
    
    <mer:samsungPay>
         <arg0>
            <merchant>OurBestMerchantLogin</merchant>
            <orderNumber>UAF-203974-DE</orderNumber>
            <description>Test description</description>
            <paymentToken>ew0KICB7DQoJICAidmVyc2lvbiI6ICJSU0FfdjEiLA0KCSAgInNpZ25hdHVyZSI6ICJabUZyWlNCemFXZHVZWFIxY21VPSIsDQoJICAiaGVhZGVyIjogew0KCQkiZXBoZW1lcmFsUHVibGljS2V5IjogIk1Ga3dFd1lIS29aSXpqMENBUVlJS29aSXpqMERBUWNEUWdBRW14Q2hDcGpLemY5YVh6MjZXVDZaVE4yekUzaUdYUWpjWlJZWUFkUUlURFgyUmtBTmJ0N2s5cmFoRjFoempqbWVWVHhjZ0NvZkg4MXprMkdOVFozZHRnPT0iICAgICAgIA0KCQkid3JhcHBlZEtleSI6ICJYejI2V1Q2WlROMnpFM2lHWFFqYz0iDQoJCSJwdWJsaWNLZXlIYXNoIjogIk9yV2dqUkdrcUVXamRrUmRVclhmaUxHRDBoZS96cEV1NTEyRkpXckdZRm89IiwNCgkJInRyYW5zYWN0aW9uSWQiOiAiYXBwbGUtMTIzNDU2Nzg5MEFCQ0RFRiINCgkgIH0sDQoJICAiZGF0YSI6ICIxZFhFMTNrdnpUVlA2bldFTjhEMnBoclBsZlFjR3I4VzN5ajJTSFlZai9QeWNIV1RqbnBWN3ovRXI3OGJyaT09Ig0KICB9DQp9</paymentToken>
            <language>RU</language>
            <additionalParameters>
               <entry>
                  <key>firstParamName</key>
                  <value>firstParamValue</value>
               </entry>
            </additionalParameters>
            <preAuth>true</preAuth>
            <ip>127.0.0.1</ip>
         </arg0>
      </mer:samsungPay>
    </soapenv:Body>
    </soapenv:Envelope>

The request parameters are described in the table below.

Parameter Mandatory Description
merchant no Merchant's login name in the payment gateway system.
orderNumber yes A unique order number on the seller's side.
paymentToken yes The contents of the 3ds.data parameter from the response received from Samsung Pay.
ip yes Payer's IP address.
amount yes Payment amount in minimum units of currency (e.g., kopecks).
description no Order description.
language no The language is encoded in ISO 639-1. If not specified, the default language specified in the store settings will be used.
additionalParameters no

Additional order parameters that are saved for viewing from the merchant's personal area. For each additional parameter, the following nested entry parameter should be used, which, in turn, includes the following nested parameters:

  • key - parameter name;
  • value - parameter value.

Below is an example of a part of the request code with several nested parameters.

html 
        <entry>           
  <key>parameter_1</key>
  <value>value_1</value>    
</entry>    
<entry>           
  <key>parameter_2</key>           
  <value>value_2</value>    
</entry>

If the seller has fiscalization configured, when specifying email (the buyer's email address) and/or phone (the buyer's cell phone number) as additional parameters, these parameters are primarily used to send a fiscal receipt.
In the case of using an external MPI, the payment gateway expects that the "eci" parameter will be received in each request for order payment. If the "eci" value differs from those used for SSL authorizations, it is also necessary to pass the "xid" and "cavv" parameters. When paying with MIR cards with 3-D Secure support, if ECI=05 or ECI=06, the CAVV value must be transmitted on a mandatory basis.
preAuth no Parameter that determines the need for pre-authorization (blocking funds on the client's account before they are debited). The following values are available: • true - the parameter is enabled, the payment is made with preauthorization (the client's funds are blocked before being debited); • false - the parameter is disabled (debiting is made immediately). If the parameter is not specified in the request, the debiting is made immediately.
clientId no The number of the client for whom one should create a binding for making regular payments. It should be indicated only if a technical payment is made for subsequent regular payments.
currencyCode no The payment currency digital code as per ISO 4217. If not specified, it is considered equal to the default currency code.

Below is an example of a response after a successful payment.

html 
            <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
    <ns1:samsungPayResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/">
         <return>
            <success>true</success>
            <data>
               <orderId>12312312123</orderId>
            </data>
            <orderStatus errorCode="0"/>
         </return>
      </ns1:samsungPayResponse>
    </soap:Body>
    </soap:Envelope>

Below is an example of a response after a failed payment.

html 
            <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
    <ns1:samsungPayResponse xmlns:ns1="https://ecom.alfabank.ru/api/soap/merchant-ws/">
         <return>
            <success>false</success>
            <error>
               <code>1</code>
               <description>Insufficient funds on the card</description>
            </error>
            <orderStatus errorCode="0"/>
         </return>
      </ns1:samsungPayResponse>
    </soap:Body>
    </soap:Envelope>

The description of the response parameters is presented in the table below.

Parameter Nested parameter Mandatory Description
success Not relevant yes Indicates the success of the payment. The following values are available: true - the request was processed successfully; false - the request failed.
data (returned only if the payment was successful) orderId yes The order number unique to the seller in the payment system.
error (returned only if the payment failed) code yes Error code.
description - yes Detailed technical explanation of the error - the contents of this parameter are not intended to be displayed to the user.
message - yes Clear error description - designed to be displayed to the user.

Possible error codes are described in the table below.

Code Description
0 Request processing took place without system errors
1 Insufficient funds on the card
5 Access denied
5 The user must change password
7 System error
10 Invalid value of the paymentToken parameter
10 Invalid value of the orderNumber parameter
10 Invalid value of the merchant parameter
10 Invalid ip parameter value
10 Invalid value of the paymentToken.header.alg parameter
10 Invalid value of the paymentToken.header.enc parameter
10 Invalid value of the paymentToken.header.typ parameter
10 Invalid value of the paymentToken.header.channelSecurityContext parameter
10 Invalid value of the paymentToken.header.kid parameter
10 Decryption of the transferred data failed