При двустадийном механизме работы разделены процессы авторизации банковской карты (операция оплаты) и совершения финансовой транзакции (финансовое подтверждение).
Операция оплаты по банковской карте
На первой стадии происходит авторизация банковской карты, проверка ее платежеспособности и блокирование средств на счету клиента. Если предприятие использует двустадийный механизм работы, то, кроме необходимых и дополнительных параметров платежа (как описано в разделе "Создание платежа"), в авторизационном запросе должно быть передано значение параметра Delay=1.
<FORM ACTION=" https://<SERVER-NAME>/pay/order.cfm" METHOD="POST"> <INPUT TYPE="HIDDEN" NAME="Merchant_ID" VALUE="Ваш Merchant_ID"> <INPUT TYPE="HIDDEN" NAME="OrderNumber" VALUE="A20042011_28"> <INPUT TYPE="HIDDEN" NAME="OrderAmount" VALUE="237.40"> <INPUT TYPE="HIDDEN" NAME="OrderCurrency" VALUE="USD"> <INPUT TYPE="HIDDEN" NAME="Delay" VALUE="1"> <INPUT TYPE="HIDDEN" NAME="Language" VALUE="RU"> <INPUT TYPE="HIDDEN" NAME="Email" VALUE="test@test.by"> <INPUT TYPE="HIDDEN" NAME="OrderComment" VALUE="Оплата заказа 28-A"> <INPUT TYPE="HIDDEN" NAME="URL_RETURN_OK" VALUE="http://www.URL.by/yes"> <INPUT TYPE="HIDDEN" NAME="URL_RETURN_NO" VALUE="http://www.URL.by/no"> <INPUT TYPE="HIDDEN" NAME="CardPayment" VALUE="1"> <INPUT TYPE="SUBMIT" NAME="Submit" VALUE="Купить"> </FORM>
После нажатия на такую кнопку покупатель перенаправляется на платежные страницы АПК Ассист, где вводит персональные данные и данные карты для совершения операции оплаты. Операция оплаты может быть как успешной, так и неуспешной. После успешного завершения операции оплаты при двустадийном механизме работы предприятия статус заказа в системе АПК Ассист принимает значение Delayed (Ожидает подтверждения оплаты), см. статусы заказа.
На второй стадии после успешной операции оплаты предприятие проводит операцию подтверждения оплаты. Только после подтверждения оплаты в процессинг отправляется финансовая транзакция.
Внимание! При двустадийном механизме работы списание средств со счета покупателя происходит только после подтверждения оплаты со стороны предприятия.
Подтверждение оплаты
Финансовое подтверждение интернет-магазин может осуществить в течение 2 дней в Личном кабинете либо с помощью веб-сервиса.
Для подтверждения оплаты нужно отправить запрос на сервер АПК Ассист по адресу:
https://<SERVER-NAME>/charge/charge.cfm.
Параметры передаются методом POST в теле запроса в формате «ключ=значение», SOAP запросом, либо в формате JSON (swagger описание: https://docs.belassist.by/swagger/).
Список параметров запроса подтверждения оплаты при двустадийном механизме работы предприятия представлен в таблице:
Название | Обязательное поле | Принимаемые значения | Значения по умолчанию | Описание |
Billnumber | Да | 15 или 16 цифр Расширенный формат | Номер платежа, соответствующий заказу в системе АПК Ассист, передача расширенного номера платежа допускается только в том случае, если в заказе не передается чек. | |
Merchant_ID | Да | Число | Идентификатор предприятия в АПК Ассист | |
Login | Да | 8 - 20 символов | Логин (лат. буквы и цифры, символ _) | |
Password | Да | 8 - 20 символов | Пароль (лат. буквы и цифры) | |
Amount | Нет1 | Число, 15 цифр (разделитель «.») | Сумма финансового подтверждения | |
Currency | Нет1 | 3 символа | Код валюты подтверждения. Может быть использован только код валюты операции оплаты | |
ClientIP | Нет | Максимум 15 цифр, 4 разделителя «.» | IP компьютера оператора, который производит подтверждение платежа | |
Language | Нет | RU – русский | RU | Язык выдачи результатов |
Format | Нет | 1 – CSV (поля с разделителями) | Формат входных данных | Формат выдачи результатов. Если запрос передан в формате JSON, то ответ также будет в JSON, в остальных случаях в соответствии с переданным значением формата. |
AutoDeposit | Нет | 1 – флаг установлен | Флаг онлайн депозита. Используется в тех случаях, когда необходимо сразу разблокировать неподтвержденную часть суммы заказа. |
1Параметры Amount , Currency могут присутствовать или отсутствовать в запросе только одновременно. В случае отсутствия параметров операция подтверждения оплаты будет проведена на полную сумму.
Все параметры, передаваемые в запросе, проходят автоматическую валидацию в АПК Ассист, см. Правила валидации входных параметров.
Подтверждение может быть проведено как на всю сумму оплаты, так и на часть суммы. Допускается совершение частичного подтверждения на сумму, не превышающую суммы оплаты, если операция оплаты по банковской карте была совершена через процессинг, имеющий соответствующие настройки.
Внимание! При проведении подтверждения оплаты (как в Личном кабинете, так и с помощью веб-сервиса) нужно указывать сумму подтверждения в валюте операции оплаты (обычно это рубли).
Для совершения операции подтверждения оплаты можно передать параметр billnumber как в обычном формате (если по заказу была одна успешная операция оплаты), так и в расширенном формате. При использовании расширенного формата обязательно должен быть указан номер успешной операции оплаты (в некоторых случаях это может быть не первая по счету операция, например, 500000000000001.2).
Внимание! Передача расширенного номера платежа допускается только в том случае, если в заказе не передается чек.
Операция подтверждения оплаты всегда успешная, кроме отказа по техническим причинам. В случае технического сбоя подтверждение оплаты нужно повторить. Повторное подтверждение оплаты не приводит к повторному списанию денег.
В случае успешного подтверждения оплаты статус заказа в системе АПК Ассист принимает значение Approved (Оплачен) или PartialDelayed (Подтвержден частично), код возврата responsecode AS000.
Описание веб-сервиса для формата SOAP можно увидеть на странице:
https://<SERVER-NAME>/charge/charge.wsdl
Список параметров ответа:
Название | Значение |
ordernumber | Номер заказа |
responsecode | Код возврата |
recommendation | Рекомендации |
message | Сообщение |
ordercomment | Комментарий |
orderdate | Дата заказа по Гринвичу (GMT) |
amount | Сумма операции |
currency | Валюта операции |
meantypename | Тип платежного средства |
meannumber | Номер платежного средства |
lastname | Фамилия плательщика |
firstname | Имя плательщика |
middlename | Отчество плательщика |
issuebank | Название банка-эмитента |
Email плательщика | |
bankcountry | Страна банка-эмитента |
rate | Курс валюты |
approvalcode | Код авторизации |
meansubtype | Подтип платежного средства |
cardholder | Держатель платежного средства |
cardexpirationdate | Срок действия карты |
ipaddress | IP-адрес плательщика |
protocoltypename | Протокол |
testmode | Тестовый режим |
customermessage | Сообщение о результате для покупателя |
orderstate | Cтатус заказа |
processingname | Процессинг |
operationtype | Тип операции |
billnumber | Расширенный формат billnumber |
orderamount | Оригинальная сумма операции |
ordercurrency | Оригинальная валюта операции |
slipno | Номер финансовой транзакции, отправляемый в процессинг (не используется) |
packetdate | Дата формирования запроса по Гринвичу (GMT) |
signature | Значение X без разделителей, подписанное закрытым ключом АПК Ассист, закодированное в BASE64, где X - billnumber,ordernumber,responsecode,orderamount,ordercurrency,meannumber,approvalcode,orderstate,packetdate |
Примеры
Пример запроса для формата HTTP POST:
<FORM ACTION="https://<SERVER-NAME>/charge/charge.cfm" METHOD="POST"> <INPUT TYPE="HIDDEN" NAME="BillNumber" VALUE="545000000000001"> <INPUT TYPE="HIDDEN" NAME="Merchant_ID" VALUE="Ваш Merchant_ID"> <INPUT TYPE="HIDDEN" NAME="Login" VALUE="Ваш логин"> <INPUT TYPE="HIDDEN" NAME="Password" VALUE="Ваш пароль"> <INPUT TYPE="HIDDEN" NAME="Amount" VALUE="100.00"> <INPUT TYPE="HIDDEN" NAME="Currency" VALUE="BYN"> <INPUT TYPE="HIDDEN" NAME="Language" VALUE="0"> <INPUT TYPE="HIDDEN" NAME="Format" VALUE="3"> <INPUT TYPE="SUBMIT" NAME="Submit" VALUE="Выполнить"> </FORM>
Пример результата запроса подтверждения оплаты в формате CSV:
ordernumber: 0001-01 responsecode: AS000 recommendation: message: Завершено успешно. ordercomment: тестовый платеж orderdate: 06.07.2016 09:00:05 amount: 100.00 currency: BYN meantypename: VISA meannumber: 411111****1111 lastname: Testov firstname: Test middlename: Testovich issuebank: BANK email: test@testpost.by bankcountry: Россия rate: 1 approvalcode: meansubtype: Corporate Purchasing Card cardholder: TEST cardexpirationdate:12/20 ipaddress: 111.23.11.23 protocoltypename: testmode: 1 customermessage: Завершено успешно. orderstate: Approved processingname: Name operationtype: 200 billnumber: 511111100000001.2 orderamount: 100.00 ordercurrency: BYN slipno: packetdate: 06.07.2016 09:01:47 signature:
В формате XML:
<?xml version='1.0' encoding='utf-8' standalone='yes'?> <!DOCTYPE result [ <!ATTLIST result firstcode CDATA #REQUIRED secondcode CDATA #REQUIRED count CDATA #REQUIRED> <!ELEMENT result (orders?)> <!ELEMENT orders (order)> <!ELEMENT order (ordernumber?, responsecode?, recommendation?, message?, ordercomment?, orderdate?, amount?, currency?, meantypename?, meannumber?, lastname?, firstname?, middlename?, issuebank?, email?, bankcountry?, rate?, approvalcode?, meansubtype?, cardholder?, cardexpirationdate?, ipaddress?, protocoltypename?, testmode?, customermessage?, orderstate?, processingname?, operationtype?, billnumber?, orderamount?, ordercurrency?, slipno?, packetdate?, signature?, pareq?, acsurl?)> <!ELEMENT ordernumber (#PCDATA)> <!ELEMENT responsecode (#PCDATA)> <!ELEMENT recommendation (#PCDATA)> <!ELEMENT message (#PCDATA)> <!ELEMENT ordercomment (#PCDATA)> <!ELEMENT orderdate (#PCDATA)> <!ELEMENT amount (#PCDATA)> <!ELEMENT currency (#PCDATA)> <!ELEMENT meantypename (#PCDATA)> <!ELEMENT meannumber (#PCDATA)> <!ELEMENT lastname (#PCDATA)> <!ELEMENT firstname (#PCDATA)> <!ELEMENT middlename (#PCDATA)> <!ELEMENT issuebank (#PCDATA)> <!ELEMENT email (#PCDATA)> <!ELEMENT bankcountry (#PCDATA)> <!ELEMENT rate (#PCDATA)> <!ELEMENT approvalcode (#PCDATA)> <!ELEMENT meansubtype (#PCDATA)> <!ELEMENT cardholder (#PCDATA)> <!ELEMENT cardexpirationdate (#PCDATA)> <!ELEMENT ipaddress (#PCDATA)> <!ELEMENT protocoltypename (#PCDATA)> <!ELEMENT testmode (#PCDATA)> <!ELEMENT customermessage (#PCDATA)> <!ELEMENT orderstate (#PCDATA)> <!ELEMENT processingname (#PCDATA)> <!ELEMENT operationtype (#PCDATA)> <!ELEMENT billnumber (#PCDATA)> <!ELEMENT orderamount (#PCDATA)> <!ELEMENT ordercurrency (#PCDATA)> <!ELEMENT slipno (#PCDATA)> <!ELEMENT packetdate (#PCDATA)> <!ELEMENT signature (#PCDATA)> <!ELEMENT pareq (#PCDATA)> <!ELEMENT acsurl (#PCDATA)>]> <result firstcode="0" secondcode="0" count="1"> <orders> <order> <ordernumber> 0001-01 </ordernumber> <responsecode> AS000 </responsecode> <recommendation> </recommendation> <message> Завершено успешно. </message> <ordercomment> тестовый платеж </ordercomment> <orderdate> 06.07.2016 10:51:53 </orderdate> <amount> 100.00 </amount> <currency> BYN </currency> <meantypename> VISA </meantypename> <meannumber> 411111****1111 </meannumber> <lastname> Testov </lastname> <firstname> Test </firstname> <middlename> Testovich </middlename> <issuebank> BANK </issuebank> <email> test@testpost.by </email> <bankcountry> Россия </bankcountry> <rate> 1 </rate> <approvalcode> </approvalcode> <meansubtype> Corporate Purchasing Card </meansubtype> <cardholder> TEST </cardholder> <cardexpirationdate> 12/20 </cardexpirationdate> <ipaddress> 10.23.10.23 </ipaddress> <protocoltypename> </protocoltypename> <testmode> 1 </testmode> <customermessage> Завершено успешно. </customermessage> <orderstate> Approved </orderstate> <processingname> Name </processingname> <operationtype> 200 </operationtype> <billnumber> 511111100000001.2 </billnumber> <orderamount> 100.00 </orderamount> <ordercurrency> BYN </ordercurrency> </slipno> <packetdate> 06.07.2016 10:53:45 </packetdate> <signature> </signature> </order> </orders> </result>
В качестве значения поля <meannumber> здесь и далее во всех веб-сервисах возвращаются 6 первых и 4 последних цифры номера карты, остальные цифры скрыты символом *.
В случае успешного подтверждения оплаты поле orderstate будет содержать значение Approved (Оплачен) или PartialDelayed (Подтвержден частично), код возврата операции подтверждения response_code AS000, значения первого и второго кода firstcode=0, secondcode=0. В случае неуспешного подтверждения оплаты код возврата response_code принимает значения AS100-AS998.
Если запрос на подтверждение оплаты не может быть обработан, в результате запроса вернутся ненулевые значения параметров firstcode, secondcode.
Пример результата запроса в формате XML, вернувшего ошибку (неправильный пароль):
<?xml version="1.0" encoding="utf-8" standalone="yes" ?> <!DOCTYPE result [...]> <result firstcode="7" secondcode="102" count="0"></result>
С описанием первого и второго кодов ошибок можно ознакомиться здесь.
Пример ответа в формате SOAP:
<?xml version='1.0' encoding='utf-8' standalone='no'?> <SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:xsd='http://www.w3.org/2001/XMLSchema'> <SOAP-ENV:Body SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> <ASS-NS:MakeChargeResponse xmlns:ASS-NS='http://www.paysecure.ru/message/'> <return xmlns:si='http://www.paysecure.ru/type/' xsi:type='si:SOAPStruct'> <ordernumber xsi:type='xsd:string'>0001-01</ordernumber> <responsecode xsi:type='xsd:string'>AS000</responsecode> <recommendation xsi:type='xsd:string'></recommendation> <message xsi:type='xsd:string'>Завершено успешно.</message> <ordercomment xsi:type='xsd:string'>тестовый платеж</ordercomment> <orderdate xsi:type='xsd:string'>06.07.2016 11:23:13</orderdate> <amount xsi:type='xsd:string'>100.00</amount> <currency xsi:type='xsd:string'>BYN</currency> <meantypename xsi:type='xsd:string'>VISA</meantypename> <meannumber xsi:type='xsd:string'>411111****1111</meannumber> <lastname xsi:type='xsd:string'>Testov</lastname> <firstname xsi:type='xsd:string'>Test</firstname> <middlename xsi:type='xsd:string'>Testovich</middlename> <issuebank xsi:type='xsd:string'>New Bank</issuebank> <email xsi:type='xsd:string'>test@testpost.by</email> <bankcountry xsi:type='xsd:string'>Россия</bankcountry> <rate xsi:type='xsd:string'>1</rate> <approvalcode xsi:type='xsd:string'></approvalcode> <meansubtype xsi:type='xsd:string'>Classic</meansubtype> <cardholder xsi:type='xsd:string'>TEST</cardholder> <cardexpirationdate xsi:type='xsd:string'>12/20</cardexpirationdate> <ipaddress xsi:type='xsd:string'>11.23.11.23</ipaddress> <protocoltypename xsi:type='xsd:string'></protocoltypename> <testmode xsi:type='xsd:string'>1</testmode> <customermessage xsi:type='xsd:string'>Завершено успешно.</customermessage> <orderstate xsi:type='xsd:string'>Approved</orderstate> <processingname xsi:type='xsd:string'>Name</processingname> <operationtype xsi:type='xsd:string'>200</operationtype> <billnumber xsi:type='xsd:string'>511111100000001.2</billnumber> <orderamount xsi:type='xsd:string'>100.00</orderamount> <ordercurrency xsi:type='xsd:string'>BYN</ordercurrency> <slipno xsi:type='xsd:string'></slipno> <packetdate xsi:type='xsd:string'>06.07.2016 11:28:26</packetdate> <signature xsi:type='xsd:string'></signature> </return> </ASS-NS:MakeChargeResponse></SOAP-ENV:Body></SOAP-ENV:Envelope>
Внимание! Для корректной работы с веб-сервисами по защищенному TLS-соединению необходимо иметь на своей стороне в хранилище доверенных корневых сертификатов следующие сертификаты:
- корневой сертификат от Comodo: COMODO RSA Certification Authority (https://support.comodo.com/index.php?/Default/Knowledgebase/Article/View/969/108/root-comodo-rsa-certification-authority-sha-2);
- корневой сертификат от GlobalSign: GlobalSign Root CA R1 (https://www.globalsign.com/repository/ca-certificates/).
Перед началом работы следует проверить наличие этих сертификатов в хранилище и добавить их в случае необходимости.