1. Основные особенности оплаты токеном
Оплата токеном - это технология оплаты в магазинах и интернете с помощью некоторых мобильных устройств, основные производители которых предоставляют средства для проведения платежей через систему токенизации, например, Apple Pay, Samsung Pay или Google Pay.
Возможны 4 варианта проведения оплаты:
- Оплата через платёжный терминал, при этом мобильное устройство прикладывается к считывателю банковских карт аналогично прикладыванию карт с поддержкой бесконтактной оплаты. Такие платежи проводятся как POS транзакции.
- Оплата по кнопке, встроенной в мобильное приложение магазина (InApp схема). Такие платежи проводятся как ECOM транзакции.
- Оплата в браузере (Web схема), при этом получение шифрованного пакета с платёжными данными и токеном выполняется на стороне платёжных страниц АПК Ассист. Такие платежи проводятся как ECOM транзакции.
- Оплата в браузере (Web схема), при этом получение шифрованного пакета с платёжными данными и токеном выполняется на странице интернет-магазина. Такие платежи проводятся как ECOM транзакции.
Ассист предоставляет возможности организовать приём платежей токенами по всем 4 вариантам. Однако, отдельные провайдеры токенов поддерживают не все варианты проведения платежей. В таблице ниже представлены возможные варианты организации платежей токенами с использованием разных провайдеров.
Провайдер токена | POS оплата | Оплата по кнопке в мобильном приложении (InApp) | Оплата в браузере на стороне АПК Ассист (Web) | Оплата в браузере на стороне магазина (Web) |
Apple Pay | Через приложение Assist.mPOS + считыватель карт | С использованием Assist.SDK для iOS или Apple Pay SDK + сервис TokenPay | Будет реализовано в I квартале 2018 г. (только при платеже в браузере Safari на платформе MacOS) | Только в браузере Safari на платформе MacOS, используя примеры работы с ApplePay JS API с сайта разработчиков Apple Pay и сервис TokenPay |
Samsung Pay | Через приложение Assist.mPOS+ считыватель карт | В настоящий момент не поддерживается со стороны Samsung Pay | Через интеграцию с платежными страницами АПК Ассист или из мобильного приложения через WebView | Не поддерживается со стороны Samsung Pay |
Google Pay* | Через приложение Assist.mPOS+ считыватель карт | С использованием Google Pay API + сервис TokenPay | Платеж на мобильном устройстве, через браузер с поддержкой Payment Request API при переходе на платежную страницу Ассист с сайта магазина или из мобильного приложения магазина через WebView. | При платеже на мобильном устройстве, через браузер с поддержкой Payment Request API: используя примеры кода по работе с Payment Request API на сайте разработчиков Google и сервис TokenPay |
*В настоящий момент в рамках Google Pay поддерживается оплата только токенизированной картой (ранее такой метод оплаты имел название Android Pay). Оплата привязанными к аккаунту Google картами невозможна в связи с ограничениями банков.
Таким образом, для разработчиков мобильных приложений доступны следующие варианты проведения оплаты:
Для Apple Pay только вариант оплаты по кнопке в приложении:
- с использованием Assist.SDK для iOS;
- с использованием Apple Pay SDK + сервис TokenPay.
Для Google Pay:
с использованием Assist SDK для Android (через WebView) — для оплаты по кнопке на платежной странице АПК Ассист;
с использованием Google API + сервис TokenPay — для оплаты по кнопке в приложении.
6. Передача платежной информации TokenPay
Оплата по токену
Параметры запроса:
| Параметр | Обязательный? | Принимаемые значения | Значение по умолчанию | Описание |
|---|---|---|---|---|
| Merchant_ID | Да | Число | Идентификатор предприятия в системе АПК Ассист | |
| Login | Да | Строка | Логин учетной записи Assist | |
| Password | Да | Строка | Пароль учетной записи Assist | |
| OrderNumber | Нет | 128 символов | Номер заказа в системе расчетов предприятия | |
| OrderAmount | Да | Число, 15 цифр (разделители «.», «,») | Сумма платежа в оригинальной валюте (например, 10.34) | |
| OrderCurrency | Нет | 3 символа | Код валюты, в которой указана сумма платежа OrderAmount (RUB, USD, EUR) | |
| OrderComment | Нет | 256 символов | Комментарий | |
| Delay | Нет | 0 – одностадийный механизм работы, 1- двустадийный механизм | 0 | Признак авторизации при двустадийном механизме работы |
| Language | Нет | RU – русский EN - английский | Язык юр.лица или предприятия | Язык квитанции об оплате |
| ClientIP | Нет | IP адрес покупателя | ||
| TokenType | Нет | 1 - Apple Pay | 1 | Идентификатор типа платежного токена. |
| PaymentToken | Нет | JSON | платежный токен | |
| Lastname | Да | 70 символов без цифр | Фамилия покупателя | |
| Firstname | Да | 70 символов без цифр | Имя покупателя | |
| Middlename | Нет | 70 символов без цифр | Отчество покупателя | |
| Да | 128 символов | E-mail покупателя | ||
| Address | Нет | 256 символов | Адрес покупателя | |
| HomePhone | Нет | 64 символа | Домашний телефон покупателя | |
| WorkPhone | Нет | 20 символов | Рабочий телефон покупателя | |
| MobilePhone | Нет | 20 символов | Мобильный телефон покупателя | |
| Fax | Нет | 20 символов | Факс покупателя | |
| Country | Нет | 3 символа | Код страны покупателя | |
| State | Нет | 3 символа | Код региона покупателя | |
| City | Нет | 70 символов | Город покупателя | |
| Zip | Нет | 25 символов | Индекс предприятия связи покупателя | |
| isConvert | Нет | 0 - Не конвертировать в базовую валюту 1 - Не конвертировать при возможности 2 - Всегда конвертировать | 1 | Флаг конвертации валюты платежа в базовую валюту |
| Format | Нет | 4 – SOAP 5 – JSON | 5 | Формат выдачи результата |
| Signature | Нет | Cтрока | Формируется строка, сшитая из следующих параметров заказа: Merchant_ID;OrderNumber;OrderAmount;OrderCurrency, разделенных точкой с запятой. На базе этой строки алгоритмом MD5 формируется дайджест. Дайджест подписывается закрытым RSA ключом мерчанта. Длина ключа - 1024. Полученная байтовая последовательность является подписью магазина. Подпись передается нам в виде дополнительного параметра, закодированного в виде строки BASE64 | |
| RecurringIndicator | Нет | 1 –рекуррентный платеж 0 - обычный платеж | 0 | Признак рекуррентного платежа |
| RecurringMinAmount | Нет/Да | Число, 15 цифр (разделители «.», «,») | Минимальная сумма рекуррентных платежей. Параметр обязателен при RecurringIndicator = 1 | |
| RecurringMaxAmount | Нет/Да | Число, 15 цифр (разделители «.», «,») | Минимальная сумма рекуррентных платежей. Параметр обязателен при RecurringIndicator = 1 | |
| RecurringPeriod | Нет/Да | Число, 10 цифр | Минимальная сумма рекуррентных платежей. Параметр обязателен при RecurringIndicator = 1 | |
| RecurringMaxDate | Нет/Да | Строковое представление даты в формате DD.MM.YY | Минимальная сумма рекуррентных платежей. Параметр обязателен при RecurringIndicator = 1 |
Параметры ответа:
| Параметр | Значение |
|---|---|
| Параметры заказа | |
| ordernumber | Номер заказа |
| billnumber | Уникальный номер заказа в системе АПК Ассист |
| testmode | Тестовый режим |
| ordercomment | Комментарий |
| orderamount | Оригинальная сумма заказа |
| ordercurrency | Оригинальная валюта заказа |
| firstname | Имя плательщика |
| lastname | Фамилия плательщика |
| middlename | Отчество плательщика |
| Email | Email плательщика |
| orderdate | Дата заказа по Гринвичу (GMT) |
| orderstate | Статус заказа |
| packetdate | Дата формирования запроса по Гринвичу (GMT) |
| signature | 1) Для типа подписи MD5 - пусто 2) Для типа PGP – значение X, подписанное закрытым ключом АПК Ассист, закодированное в BASE64 |
| checkvalue | uppercase(md5(uppercase(md5(SALT) + md5(Х)))), где SALT – секретное слово; Х – результат строковой склейки параметров merchant_id, ordernumber, orderamount, ordercurrency, orderstate (без разделителей), + -строковая склейка |
| Параметры операции | |
| billnumber | Расширенный формат billnumber |
| operationtype | Тип операции |
| operationstate | Состояние операции |
| amount | Сумма операции |
| currency | Валюта операции |
| ipaddress | IP-адрес плательщика |
| clientip | IP-адрес совершившего операцию |
| meantype_id | Тип платежного средства |
| meansubtype | Подтип платежного средства |
| meannumber | Номер платежного средства |
| cardholder | Держатель платежного средства |
| issuebank | Название банка-эмитента |
| bankcountry | Страна банка-эмитента |
| responsecode | Код возврата |
| message | Сообщение о результате операции |
| customermessage | Сообщение о результате для покупателя |
| recommendation | Рекомендация |
| approvalcode | Код авторизации |
| protocoltypename | Протокол |
| processingname | Процессинг |
| operationdate | Дата и время операции (GMT) |
| authresult | Результат аворизации по 3DSecure (Y - успешно, N - неуспешно, A - Attempt, U – неизвестно) |
| authrequired | Результат аворизации по 3DSecure (Y - успешно, N - неуспешно, A - Attempt, U – неизвестно) |
| slipno | Номер финансовой транзакции, отправляемый в процессинг |
Описание веб-сервиса:
../pay/tokenpay.wsdl
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="http://www.paysecure.ru/ws/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" name="tokenpay" targetNamespace="http://www.paysecure.ru/ws/"> <wsdl:types> <xsd:schema targetNamespace="http://www.paysecure.ru/ws/"> <xsd:element name="TokenPayRequestParams"> <xsd:complexType> <xsd:all> <xsd:element minOccurs="1" name="merchant_id" type="xsd:string" /> <xsd:element minOccurs="1" name="login" type="xsd:string" /> <xsd:element minOccurs="1" name="password" type="xsd:string" /> <xsd:element minOccurs="1" name="lastname" type="xsd:string" /> <xsd:element minOccurs="1" name="firstname" type="xsd:string" /> <xsd:element minOccurs="1" name="orderamount" type="xsd:string" /> <xsd:element minOccurs="1" name="email" type="xsd:string" /> <xsd:element minOccurs="0" name="tokentype" type="xsd:string" /> <xsd:element minOccurs="0" name="tokennumber" type="xsd:string" /> <xsd:element minOccurs="0" name="cryptogram3ds" type="xsd:string" /> <xsd:element minOccurs="0" name="eci" type="xsd:string" /> <xsd:element minOccurs="0" name="paymenttoken" type="xsd:string" /> <xsd:element minOccurs="0" name="transactionid" type="xsd:string" /> <xsd:element minOccurs="0" name="cardholder" type="xsd:string" /> <xsd:element minOccurs="0" name="ExpireDate" type="xsd:string" /> <xsd:element minOccurs="0" name="ordercurrency" type="xsd:string" /> <xsd:element minOccurs="0" name="ordernumber" type="xsd:string" /> <xsd:element minOccurs="0" name="delay" type="xsd:string" /> <xsd:element minOccurs="0" name="testmode" type="xsd:string" /> <xsd:element minOccurs="0" name="language" type="xsd:string" /> <xsd:element minOccurs="0" name="isconvert" type="xsd:string" /> <xsd:element minOccurs="0" name="ordercomment" type="xsd:string" /> <xsd:element minOccurs="0" name="middlename" type="xsd:string" /> <xsd:element minOccurs="0" name="address" type="xsd:string" /> <xsd:element minOccurs="0" name="homephone" type="xsd:string" /> <xsd:element minOccurs="0" name="workphone" type="xsd:string" /> <xsd:element minOccurs="0" name="mobilephone" type="xsd:string" /> <xsd:element minOccurs="0" name="country" type="xsd:string" /> <xsd:element minOccurs="0" name="city" type="xsd:string" /> <xsd:element minOccurs="0" name="state" type="xsd:string" /> <xsd:element minOccurs="0" name="zip" type="xsd:string" /> <xsd:element minOccurs="0" name="clientip" type="xsd:string" /> <xsd:element minOccurs="0" name="cardtype" type="xsd:string" /> <xsd:element minOccurs="0" name="cvc2" type="xsd:string" /> <xsd:element minOccurs="0" name="recurringindicator" type="xsd:string" /> <xsd:element minOccurs="0" name="recurringminamount" type="xsd:string" /> <xsd:element minOccurs="0" name="recurringmaxamount" type="xsd:string" /> <xsd:element minOccurs="0" name="recurringperiod" type="xsd:string" /> <xsd:element minOccurs="0" name="recurringmaxdate" type="xsd:string" /> <xsd:element minOccurs="0" name="plan_mounth" type="xsd:string" /> <xsd:element minOccurs="0" name="invoice_number" type="xsd:string" /> <xsd:element minOccurs="0" name="charge_type" type="xsd:string" /> <xsd:element minOccurs="0" name="airline_name" type="xsd:string" /> <xsd:element minOccurs="0" name="passenger_name" type="xsd:string" /> <xsd:element minOccurs="0" name="ticket_number" type="xsd:string" /> <xsd:element minOccurs="0" name="ticket_issuer" type="xsd:string" /> <xsd:element minOccurs="0" name="ticket_issuer_address" type="xsd:string" /> <xsd:element minOccurs="0" name="departure_airport" type="xsd:string" /> <xsd:element minOccurs="0" name="arrival_airport_1" type="xsd:string" /> <xsd:element minOccurs="0" name="carrier_code_1" type="xsd:string" /> <xsd:element minOccurs="0" name="airline_class_1" type="xsd:string" /> <xsd:element minOccurs="0" name="stopover_code_1" type="xsd:string" /> <xsd:element minOccurs="0" name="arrival_airport_2" type="xsd:string" /> <xsd:element minOccurs="0" name="carrier_code_2" type="xsd:string" /> <xsd:element minOccurs="0" name="airline_class_2" type="xsd:string" /> <xsd:element minOccurs="0" name="stopover_code_2" type="xsd:string" /> <xsd:element minOccurs="0" name="arrival_airport_3" type="xsd:string" /> <xsd:element minOccurs="0" name="carrier_code_3" type="xsd:string" /> <xsd:element minOccurs="0" name="airline_class_3" type="xsd:string" /> <xsd:element minOccurs="0" name="stopover_code_3" type="xsd:string" /> <xsd:element minOccurs="0" name="arrival_airport_4" type="xsd:string" /> <xsd:element minOccurs="0" name="carrier_code_4" type="xsd:string" /> <xsd:element minOccurs="0" name="airline_class_4" type="xsd:string" /> <xsd:element minOccurs="0" name="stopover_code_4" type="xsd:string" /> <xsd:element minOccurs="0" name="charge_details" type="xsd:string" /> <xsd:element minOccurs="0" name="agent_code" type="xsd:string" /> <xsd:element minOccurs="0" name="restricted_ticked_ind" type="xsd:string" /> <xsd:element minOccurs="0" name="pnr" type="xsd:string" /> <xsd:element minOccurs="0" name="departure_date" type="xsd:string" /> <xsd:element minOccurs="0" name="header_http_user_agent" type="xsd:string" /> <xsd:element minOccurs="0" name="header_http_accept" type="xsd:string" /> <xsd:element minOccurs="0" name="header_http_accept_language" type="xsd:string" /> <xsd:element minOccurs="0" name="header_http_referer" type="xsd:string" /> <xsd:element minOccurs="0" name="header_remote_host" type="xsd:string" /> <xsd:element minOccurs="0" name="header_http_forwarded" type="xsd:string" /> <xsd:element minOccurs="0" name="header_http_x_forwarded_for" type="xsd:string" /> <xsd:element minOccurs="0" name="header_http_via" type="xsd:string" /> <xsd:element minOccurs="0" name="client_js_ver" type="xsd:string" /> <xsd:element minOccurs="0" name="client_local_time" type="xsd:string" /> <xsd:element minOccurs="0" name="client_screen_res" type="xsd:string" /> <xsd:element minOccurs="0" name="client_screen_colors" type="xsd:string" /> <xsd:element minOccurs="0" name="client_js_browser_name" type="xsd:string" /> <xsd:element minOccurs="0" name="client_time_zone" type="xsd:string" /> <xsd:element minOccurs="0" name="client_cookies" type="xsd:string" /> <xsd:element minOccurs="0" name="client_java" type="xsd:string" /> <xsd:element minOccurs="0" name="client_stylesheets" type="xsd:string" /> <xsd:element minOccurs="0" name="client_browser_platform" type="xsd:string" /> <xsd:element minOccurs="0" name="client_system_language" type="xsd:string" /> <xsd:element minOccurs="0" name="client_browser_language" type="xsd:string" /> <xsd:element minOccurs="0" name="client_user_language" type="xsd:string" /> <xsd:element minOccurs="0" name="client_processor" type="xsd:string" /> <xsd:element minOccurs="0" name="client_connection" type="xsd:string" /> <xsd:element minOccurs="0" name="client_hostaddress" type="xsd:string" /> <xsd:element minOccurs="0" name="client_hostname" type="xsd:string" /> <xsd:element minOccurs="0" name="signature" type="xsd:string" /> </xsd:all> </xsd:complexType> </xsd:element> <xsd:element name="TokenPayResponseParams"> <xsd:complexType> <xsd:sequence> <xsd:element name="order" type="tns:order" /> <xsd:element name="packetdate" type="xsd:string" /> <xsd:element name="signature" type="xsd:string" /> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:element name="WSException"> <xsd:complexType> <xsd:sequence> <xsd:element name="firstcode" type="xsd:string" /> <xsd:element name="secondcode" type="xsd:string" /> </xsd:sequence> </xsd:complexType> </xsd:element> <xsd:complexType name="order"> <xsd:sequence> <xsd:element minOccurs="0" name="billnumber" type="xsd:string" /> <xsd:element minOccurs="0" name="ordernumber" type="xsd:string" /> <xsd:element minOccurs="0" name="testmode" type="xsd:string" /> <xsd:element minOccurs="0" name="ordercomment" type="xsd:string" /> <xsd:element minOccurs="0" name="orderamount" type="xsd:string" /> <xsd:element minOccurs="0" name="ordercurrency" type="xsd:string" /> <xsd:element minOccurs="0" name="rate" type="xsd:string" /> <xsd:element minOccurs="0" name="orderdate" type="xsd:string" /> <xsd:element minOccurs="0" name="orderstate" type="xsd:string" /> <xsd:element minOccurs="0" name="customer" type="tns:customer" /> <xsd:element maxOccurs="unbounded" minOccurs="0" name="operation" type="tns:operation" /> </xsd:sequence> </xsd:complexType> <xsd:complexType name="customer"> <xsd:sequence> <xsd:element minOccurs="0" name="firstname" type="xsd:string" /> <xsd:element minOccurs="0" name="lastname" type="xsd:string" /> <xsd:element minOccurs="0" name="middlename" type="xsd:string" /> <xsd:element minOccurs="0" name="email" type="xsd:string" /> </xsd:sequence> </xsd:complexType> <xsd:complexType name="operation"> <xsd:sequence> <xsd:element minOccurs="0" name="billnumber" type="xsd:string" /> <xsd:element minOccurs="0" name="operationtype" type="xsd:string" /> <xsd:element minOccurs="0" name="operationstate" type="xsd:string" /> <xsd:element minOccurs="0" name="amount" type="xsd:string" /> <xsd:element minOccurs="0" name="currency" type="xsd:string" /> <xsd:element minOccurs="0" name="ipaddress" type="xsd:string" /> <xsd:element minOccurs="0" name="meantype_id" type="xsd:string" /> <xsd:element minOccurs="0" name="meansubtype" type="xsd:string" /> <xsd:element minOccurs="0" name="meannumber" type="xsd:string" /> <xsd:element minOccurs="0" name="cardholder" type="xsd:string" /> <xsd:element minOccurs="0" name="cardexpirationdate" type="xsd:string" /> <xsd:element minOccurs="0" name="issuebank" type="xsd:string" /> <xsd:element minOccurs="0" name="bankcountry" type="xsd:string" /> <xsd:element minOccurs="0" name="responsecode" type="xsd:string" /> <xsd:element minOccurs="0" name="message" type="xsd:string" /> <xsd:element minOccurs="0" name="customermessage" type="xsd:string" /> <xsd:element minOccurs="0" name="recommendation" type="xsd:string" /> <xsd:element minOccurs="0" name="approvalcode" type="xsd:string" /> <xsd:element minOccurs="0" name="protocoltypename" type="xsd:string" /> <xsd:element minOccurs="0" name="processingname" type="xsd:string" /> <xsd:element minOccurs="0" name="operationdate" type="xsd:string" /> <xsd:element minOccurs="0" name="slipno" type="xsd:string" /> </xsd:sequence> </xsd:complexType> <xsd:complexType name="chequeitem"> <xsd:sequence> <xsd:element name="id" type="xsd:string" /> <xsd:element name="product" minOccurs="0" type="xsd:string" /> <xsd:element name="name" minOccurs="0" type="xsd:string" /> <xsd:element name="price" type="xsd:string" /> <xsd:element name="quantity" type="xsd:string" /> <xsd:element name="tax" type="xsd:string" /> </xsd:sequence> </xsd:complexType> </xsd:schema> </wsdl:types> <wsdl:message name="TokenPayRequest"> <wsdl:part element="tns:TokenPayRequestParams" name="cancel"> </wsdl:part> </wsdl:message> <wsdl:message name="TokenPayException"> <wsdl:part element="tns:WSException" name="wsexception"> </wsdl:part> </wsdl:message> <wsdl:message name="TokenPayResponse"> <wsdl:part element="tns:TokenPayResponseParams" name="return"> </wsdl:part> </wsdl:message> <wsdl:portType name="TokenPayPortType"> <wsdl:operation name="Cancel"> <wsdl:input message="tns:TokenPayRequest"> </wsdl:input> <wsdl:output message="tns:TokenPayResponse"> </wsdl:output> <wsdl:fault message="tns:TokenPayException" name="WSException"> </wsdl:fault> </wsdl:operation> </wsdl:portType> <wsdl:binding name="TokenPayBinding" type="tns:TokenPayPortType"> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" /> <wsdl:operation name="Cancel"> <soap:operation soapAction="" style="document" /> <wsdl:input> <soap:body use="literal" /> </wsdl:input> <wsdl:output> <soap:body use="literal" /> </wsdl:output> <wsdl:fault name="WSException"> <soap:fault name="WSException" use="literal" /> </wsdl:fault> </wsdl:operation> </wsdl:binding> <wsdl:service name="TokenPayService"> <wsdl:port binding="tns:TokenPayBinding" name="tokenpay"> <soap:address location="" /> </wsdl:port> </wsdl:service> </wsdl:definitions>