При двустадийном механизме работы разделены процессы авторизации банковской карты (операция оплаты) и совершения финансовой транзакции (финансовое подтверждение).
Операция оплаты по банковской карте
На первой стадии происходит авторизация банковской карты, проверка ее платежеспособности и блокирование средств на счету клиента. Если предприятие использует двустадийный механизм работы, то, кроме необходимых и дополнительных параметров платежа (как описано в разделе Создание платежа), в авторизационном запросе должно быть передано значение параметра 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="KZT"> <INPUT TYPE="HIDDEN" NAME="Delay" VALUE="1"> <INPUT TYPE="HIDDEN" NAME="Language" VALUE="RU"> <INPUT TYPE="HIDDEN" NAME="Email" VALUE="test@test.kz"> <INPUT TYPE="HIDDEN" NAME="OrderComment" VALUE="Оплата заказа 28-A"> <INPUT TYPE="HIDDEN" NAME="URL_RETURN_OK" VALUE="http://www.URL.kz/yes"> <INPUT TYPE="HIDDEN" NAME="URL_RETURN_NO" VALUE="http://www.URL.kz/no"> <INPUT TYPE="HIDDEN" NAME="CardPayment" VALUE="1"> <INPUT TYPE="HIDDEN" NAME="WMPayment" VALUE="0"> <INPUT TYPE="HIDDEN" NAME="YMPayment" VALUE="0"> <INPUT TYPE="SUBMIT" NAME="Submit" VALUE="Купить"> </FORM>
После нажатия на такую кнопку покупатель перенаправляется на платежные страницы АПК Ассист, где вводит персональные данные и данные карты для совершения операции оплаты. Операция оплаты может быть как успешной, так и неуспешной. После успешного завершения операции оплаты при двустадийном механизме работы предприятия статус заказа в системе АПК Ассист принимает значение Delayed (Ожидает подтверждения оплаты), см. статусы заказа.
На второй стадии после успешной операции оплаты предприятие проводит операцию подтверждения оплаты. Только после подтверждения оплаты в процессинг отправляется финансовая транзакция.
Внимание!
При двустадийном механизме работы списание средств со счета покупателя происходит только после подтверждения оплаты со стороны предприятия.
Подтверждение оплаты
Финансовое подтверждение интернет-магазин может осуществить в течение 4 дней в Личном кабинете либо с помощью веб-сервиса.
Для подтверждения оплаты нужно отправить запрос на сервер АПК Ассист по адресу:
https://<SERVER-NAME>/charge/charge.cfm.
Параметры передаются методом POST в теле запроса в формате «ключ=значение», SOAP запросом, либо в формате JSON (swagger описание: https://docs.assist.kz/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 (поля с разделителями) | 1 | Формат выдачи результатов. Передается только для запроса в формате POST (по умолчанию ответ будет выдан в формате CSV). Для других форматов ответ выдается в том же формате, в котором был выполнен запрос. |
| AutoDeposit | Нет | 1 – флаг установлен 0 – флаг сброшен | Флаг онлайн депозита. Используется в тех случаях, когда необходимо сразу разблокировать неподтвержденную часть суммы заказа. |
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 | Оригинальная валюта операции |
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"> <INPUT TYPE="HIDDEN" NAME="Currency" VALUE="KZT"> <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: 01.01.2018 09:00:05 amount: 100.00 currency: RUB meantypename: VISA meannumber: 411111****1111 lastname: Testov firstname: Test middlename: Testovich issuebank: BANK email: test@testpost.kz 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: KZT packetdate: 01.01.2018 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?, 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 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> 01.01.2018 10:51:53</orderdate>
<amount> 100.00 </amount>
<currency> KZT </currency>
<meantypename> VISA</meantypename>
<meannumber> 411111****1111</meannumber>
<lastname> Testov </lastname>
<firstname> Test </firstname>
<middlename> Testovich</middlename>
<issuebank> BANK </issuebank>
<email> test@testpost.kz </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> KZT</ordercurrency>
<packetdate> 01.01.2018 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.
Если подтверждение оплаты не будет прислано (не был вызван сервис charge), то финансовая транзакция в процессинг не отправляется и будет отсутствовать в отчете процессинга предприятию.
Пример результата запроса в формате XML, вернувшего ошибку (неправильный пароль):
<?xml version="1.0" encoding="utf-8" standalone="yes"?> <!DOCTYPE result [...]> <result firstcode="7"secondcode="102" count="0"></result>
С описанием первого и второго кодов ошибок можно ознакомиться здесь.
Пример ответа в формате SOAP (может быть получен только при запросе в формате 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.kz/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'>01.01.2018 11:23:13</orderdate> <amount xsi:type='xsd:string'>100.00</amount> <currency xsi:type='xsd:string'>KZT</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.kz</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'>KZT</ordercurrency> <packetdate xsi:type='xsd:string'>01.01.2018 11:28:26</packetdate> <signature xsi:type='xsd:string'></signature> </return> </ASS-NS:MakeChargeResponse></SOAP-ENV:Body></SOAP-ENV:Envelope>
Внимание!
Для корректной работы с веб-сервисами по защищенному TLS-соединению необходимо иметь на своей стороне в хранилище доверенных корневых сертификатов следующие сертификаты:
- корневые сертификаты от GlobalSign (https://www.globalsign.com/repository/ca-certificates/):
- GlobalSign Root R3;
- GlobalSign ECC Root R5;
- GlobalSign Root R6;
- корневые сертификаты от Sectigo (https://www.sectigo.com/knowledge-base/detail/Sectigo-Root-Certificates/kA03l000000c4KV):
- USERTrust RSA Certification Authority;
- USERTrust ECC Certification Authority.
Перед началом работы следует проверить наличие этих сертификатов в хранилище и добавить их в случае необходимости.