.. meta:: :description: Эндпоинт мобильного API /mapi/v1/preauth SBC: инициирование preauth по карте из мобильного приложения через интерфейс mAPI v1 с поддержкой 3DS. .. _mapi_v1_preauth: /mapi/v1/preauth ============================ .. role:: ex .. role:: code Введение ^^^^^^^^^^^^^^^^^^^^^^^^ Приложение инициирует транзакцию, отправляя :code:`HTTPS POST` запрос с использованием :ref:`URL` и :ref:`параметров`, указанных ниже. Для аутентификации используется :ref:`HMAC-SHA1`. .. _mapi/api/preauth: API URL ^^^^^^^^^^^^^^^^^^^^ .. note:: | Путь API URL не должен быть задан фиксированным значением, т.к. он может быть изменён позднее. .. list-table:: :widths: 50, 50 :header-rows: 1 :class: longtable * - Интеграционная среда - Производственная среда * - :ex:`https://sandbox.sbctech.ru/paynet/mapi/v1/preauth/ENDPOINTID` - :ex:`https://gate.sbctech.ru/paynet/mapi/v1/preauth/ENDPOINTID` .. _mapi/parameters/preauth: Параметры запроса ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: | \* начальные и конечные пробелы в значениях параметров будут отброшены | В значениях параметров необходимо экранировать следующие символы: :code:`&` :code:`+` :code:`\\`. .. list-table:: :widths: 30 50 20 :header-rows: 1 :class: longtable * - Название параметра - Описание - Значение * - :code:`client_orderid` - Уникальный идентификатор заказа, присвоенный Присоединяющейся Стороной. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 128 * - :code:`order_desc` - Краткое описание заказа - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 64k * - :code:`first_name` - Имя Плательщика. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 50 * - :code:`last_name` - Фамилия Плательщика - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 50 * - :code:`ssn` - Последние четыре цифры номера социального страхования Плательщика. - | ``Необходимость``: Опционально | ``Тип``: Numeric | ``Длина``: 32 * - :code:`birthday` - Дата рождения Плательщика в формате YYYYMMDD. - | ``Необходимость``: Опционально | ``Тип``: Numeric | ``Длина``: 8 * - :code:`address1` - Адрес Плательщика, строка 1. (Обратите внимание, что в некоторых случаях невозможно отправить адрес длиной более 50 символов. Для получения более подробной информации обратитесь к вашему менеджеру.) - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 256 * - :code:`city` - Город Плательщика. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 50 * - :code:`state` - Штат Плательщика. Для списка действительных кодов штатов см. :ref:`Обязательные коды штатов`. Требуется для США, Канады и Австралии. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 2 * - :code:`zip_code` - Почтовый индекс Плательщика - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 10 * - :code:`country` - Страна Плательщика. Для списка действительных кодов см. :ref:`Коды стран`. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 2 * - :code:`phone` - Полный международный номер телефона Плательщика, включая код страны. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 15 * - :code:`cell_phone` - Полный международный мобильный номер телефона Плательщика, включая код страны. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 15 * - :code:`email` - Адрес электронной почты Плательщика. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 50 * - :code:`purpose` - Назначение платежа. Полезно для Присоединяющейся Стороны, которая позволяет своим плательщикам пополнять счета с помощью банковской карты (счета мобильных телефонов, игровые счета и т. д.). Примеры значений: :ex:`+9999999999`; :ex:`mail@example.com` и т.п. Это значение может использоваться системой мониторинга мошенничества. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 128 * - :code:`amount` - Сумма к списанию. Сумма указывается в основных единицах с разделителем :ex:`.`. Например, :ex:`10.5` для USD означает 10 долларов США и 50 центов - | ``Необходимость``: Обязательно | ``Тип``: Numeric | ``Длина``: 10 * - :code:`currency` - Валюта, в которой проводится транзакция (см. :ref:`Коды валют`). Примеры значений: :ex:`USD` для доллара США, :ex:`EUR` для европейского евро - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 3 * - :code:`cvv2` - Код CVV2 клиента. CVV2 (Card Verification Значение) — трёх- или четырёхзначное число, указанное ПОСЛЕ номера карты в области подписи карты. Используется, если эквайер предоставляет только E-Commerce соединение - | ``Необходимость``: Опционально | ``Тип``: Numeric | ``Длина``: 3-4 * - :code:`ipaddress` - IP-адрес Плательщика, передаётся для целей мониторинга мошенничества. - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 20 * - :code:`encrypted-type` - Тип шифрования. Зависит от модели mPOS - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: 32 * - :code:`encrypted-data` - Данные дорожек карты, зашифрованные с помощью алгоритма :ex:`encrypted-type` и закодированные в HEX. Подробности уточняйте в службе поддержки - | ``Необходимость``: Обязательно | ``Тип``: String | ``Длина``: - * - :code:`server_callback_url` - | URL-адрес, по которому будет отправлен обратный вызов с результатом транзакции. | Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to :ex:`server_callback_url` refer to :ref:`Connecting Party callback parameters`. - | ``Необходимость``: Опционально | ``Тип``: String | ``Длина``: 1024 Пример аутентификации запроса ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | Чтобы гарантировать, что запрос авторизован Присоединяющейся Стороной, все запросы должны быть подписаны. MAPI работает с подписью OAuth 1.0a :ex:`HMAC-SHA1`, так как это устоявшийся стандарт, поддерживаемый в клиентских библиотеках. | MAPI поддерживает только часть с подписью и не поддерживает полноценный OAuth. В качестве секретного ключа используется контрольный ключ Присоединяющейся Стороны. | Ниже приведён пример формирования подписанного запроса на Java с помощью `библиотеки scribe `_: .. highlight:: java :: import org.scribe.builder.api.DefaultApi10a; import org.scribe.model.*; import org.scribe.oauth.OAuth10aServiceImpl; import org.scribe.oauth.OAuthService; import org.scribe.services.HMACSha1SignatureService; import org.scribe.services.SignatureService; import java.util.Map; public class App { public String doPost(String url, Mapparameters) { OAuthConfig config = new OAuthConfig(apiToken, merchantControlKey, OAuthConstants.OUT_OF_BAND, SignatureType.Header, null,null); OAuthService service = new OAuth10aServiceImpl(new HmacSha1Mapi(), config); OAuthRequest request = new OAuthRequest(Verb.POST,url); for (Map.Entry < String,String > entry :parameters.entrySet()){ request.addBodyParameter(entry.getKey(), entry.getЗначение()); } // empty token for 'two-legged' Token token = new Token("", ""); service.signRequest(token, request); Response response = request.send(); return response.getBody(); } private static class HmacSha1Mapi extends DefaultApi10a { @Override public String getRequestTokenEndpoint() { return null; // not used } @Override public String getAccessTokenEndpoint() { return null; //not used } @Override public String getAuthorizationUrl(Token requestToken) { return null; // not used } @Override public SignatureService getSignatureService() { return new HMACSha1SignatureService(); } } } .. _preauth-form_response_parameters: Параметры ответа ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 25, 75 :header-rows: 1 :class: longtable * - Название параметра - Описание * - :code:`type` - Тип ответа. Может быть :ex:`async-form-response`, :ex:`validation-error`, :ex:`error`. Если тип равен :ex:`validation-error` или :ex:`error`, параметры :ex:`error-message` и :ex:`error-code` содержат сведения об ошибке. * - :code:`status` - Подробности смотрите в:ref:`status_list`. * - :code:`paynet-order-id` - Идентификатор заказа, присвоенный сервером gate.sbctech.ru * - :code:`merchant-order-id` - Идентификатор заказа Присоединяющейся Стороны * - :code:`serial-number` - Уникальный номер, присваиваемый сервером gate.sbctech.ru конкретному запросу от присоединяющейся стороны. * - :code:`error-message` - Если статус :ex:`declined` или :ex:`error`, этот параметр содержит причину отклонения или сведения об ошибке * - :code:`error-code` - Код ошибки в случае статуса :ex:`declined` или :ex:`error` Пример запроса Google Pay ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ После получения токена Google Pay он может выглядеть следующим образом: .. code-block:: json { "signature": "MEUCIQCOH1uW2LaQheaE4bg074mqd3QpFIx/BJxG/OGMEhhDqwIgPb6XzlwDwBM+SLzk2HYnAy0h/Pkps8l8Bn13AVc9hQQ\u003d", "intermediateSigningKey": { "signedKey": "{"keyЗначение":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEiZi3I+5g0xH3kOXMxiNyoOMMRwU7sD+/qks15AdgSU5+xH2PTFwe9yCQLzn4DSdjo3QKIyc+c5fUG1dkasBvKw\\u003d\\u003d","keyExpiration":"1649766119579"}", "signatures": [ "MEYCIQDLUKwcyf9AAqyJ6WSLrT5jG+Hd4iKvoXxaayvFUerX8wIhAMzHqN1xyAIRhznjLkkUAOQgbg7cUltK0FH1hvRL7CAN" ] }, "protocolVersion": "ECv2", "signedMessage": "{"encryptedMessage":"EOpG0NNX9OpyYzlR5FEe6CMNf4pkeJvEhOOOG94cBD+y1x22LdGE55Le2gBRI3mFRCusQDaQtyCS5PvoLp0/urpWNr8xTxW/EwxjnqkYgUBRFGOmbJQAceA/7MAlPu9w4gs0COY2akgurdCbLQkLasTSc5e/ i6GWmdiXqWAWM8JrNBVklpYnFek3FCeK3W23mYHntedCLyTTPVmbUeMQ4n8rhgzo+8fiWNjKywLjVZlJ2o+oCNxhMVfhG74GdWvob2TfE1uoeXOCXOH02u8towOOvR2fqnAkIBDUfpiUSjpW7MmDTJyYIewc W4EoWGTE6A+pEyI8jTbA4Y0box39exJbNthQsThqXg5OKJOEDcMNYBPg/lbyNQfY8NjvBMA7fB//QiZqIu8WgZFfSiMJ+j4uXHdCDfLT9biw4pde7bkRuH/Uofd1CabifhQSu64SeEEkj0r87wEY55sNr8Kz SCAwwOgQP0XYlt/t0A5KT9k172I84WtiWQYr/UNuIVURiH8x08e8Ihx9Nvkgx+Gz/ZyUVQH9RXjEXDRNvm63sSiUMB1TlY9PiMKO0451Uw2yw30c/8SzyKByPYtNdHwmd6iAhfoQSpJAKMTwhYMmKFZC+b8K HKbx8Ge+NVKv2GpCLwy0WL4wvqWNPk21Jzc0bFcnzztafdTPbbEB1pfY","ephemeralPublicKey":"BGVn0SZ1J5pDZlInHve5nj1Ybj+C0olFcTygynSqU8YqKaZs8ZdHQjVlISrRI10PmskgZSMH YXdkM0k+/D8/o0o\\u003d","tag":"II0dhcOZtYl26Yln3GNSXTK4yalRylKsKj71RyjZfFM\\u003d"}" } Преобразуйте токен в HEX: .. code-block:: text 7B0A2020227369676E6174757265223A20224D4555434951434F48317557324C6151686561453462673037346D71643351704649782F424A78472F4F474D4568684471774967506236587A6C774477424D2B534C7A6B3248596E417930682F506B707338 6C38426E3133415663396851515C7530303364222C0A202022696E7465726D6564696174655369676E696E674B6579223A207B0A20202020227369676E65644B6579223A20227B5C226B657956616C75655C223A5C224D466B77457759484B6F5A497A6A 3043415159494B6F5A497A6A30444151634451674145695A6933492B3567307848336B4F584D78694E796F4F4D4D5277553773442B2F716B7331354164675355352B7848325054467765397943514C7A6E344453646A6F33514B4979632B633566554731 646B617342764B775C5C75303033645C5C75303033645C222C5C226B657945787069726174696F6E5C223A5C22313634393736363131393537395C227D222C0A20202020227369676E617475726573223A205B0A202020202020224D4559434951444C55 4B7763796639414171794A3657534C7254356A472B486434694B766F587861617976465565725838774968414D7A48714E317879414952687A6E6A4C6B6B55414F516762673763556C744B304648316876524C3743414E220A202020205D0A20207D2C0A 20202270726F746F636F6C56657273696F6E223A202245437632222C0A2020227369676E65644D657373616765223A20227B5C22656E637279707465644D6573736167655C223A5C22454F7047304E4E58394F7079597A6C523546456536434D4E663470 6B654A7645684F4F4F4739346342442B79317832324C64474535354C653267425249336D465243757351446151747943533550766F4C70302F757270574E7238785478572F4577786A6E716B596755425246474F6D624A51416365412F374D416C507539 7734677330434F5932616B6775726443624C516B4C617354536335652F693647576D646958715741574D384A724E42566B6C70596E46656B334643654B335732336D59486E746564434C79545450566D6255654D51346E387268677A6F2B386669574E6A 4B79774C6A565A6C4A326F2B6F434E78684D566668473734476457766F623254664531756F65584F43584F4830327538746F774F4F76523266716E416B4942445566706955536A7057374D6D44544A7959496577635734456F5747544536412B70457949 386A546241345930626F78333965784A624E746851735468715867354F4B4A4F4544634D4E594250672F6C62794E516659384E6A76424D413766422F2F51695A7149753857675A466653694D4A2B6A34755848644344664C54396269773470646537626B 5275482F556F6664314361626966685153753634536545456B6A307238377745593535734E72384B7A53434177774F6751503058596C742F743041354B54396B313732493834577469575159722F554E75495655526948387830386538496878394E766B 67782B477A2F5A79555651483952586A455844524E766D3633735369554D4231546C593950694D4B4F3034353155773279773330632F38537A794B42795059744E6448776D6436694168666F5153704A414B4D547768594D6D4B465A432B62384B484B62 783847652B4E564B76324770434C777930574C34777671574E506B32314A7A63306246636E7A7A74616664545062624542317066595C222C5C22657068656D6572616C5075626C69634B65795C223A5C224247566E30535A314A3570445A6C496E487665 356E6A3159626A2B43306F6C4663547967796E5371553859714B615A73385A6448516A566C49537252493130506D736B675A534D485958646B4D306B2B2F44382F6F306F5C5C75303033645C222C5C227461675C223A5C224949306468634F5A74596C32 36596C6E33474E5358544B3479616C52796C4B734B6A373152796A5A66464D5C5C75303033645C227D220A7D Сформируйте запрос, установив :ex:`encrypted-data` равным HEX-токену и :ex:`encrypted-type=googlepay`: .. code-block:: http POST paynet/mapi/v1/preauth/27764 HTTP/1.1 Host: sandbox.sbctech.ru User-Agent: curl/7.83.0 Accept: */* Authorization: OAuth realm="",oauth_version="1.0",oauth_consumer_key="test_merchant14",oauth_signature_method="HMAC-SHA1",oauth_signature="hSXMSUPP%2FIGYOOWpU4LVx0mu7SA%3D" Content-Length: 108 Content-Type: application/x-www-form-urlencoded Connection: close client_orderid=123098 &cvv2=XXX &amount=114.94 &ipaddress=115.135.52.242 &state= ¤cy=USD &phone=+6072344354 &zip_code=81200 &order_desc=Super product 1 &email=francislusaikun@yahoo.com &country=MY &city=Johor Bahru &address1=11 Jalan Lurah 6 Kg. Kempas Baru &redirect_url=http://MERCHANT_SITE/payment_update/123098/ &encrypted-type=googlepay &encrypted-data=7B0A2020227369676E6174757265223A20224D4555434951434F48317557324C6151686561453462673037346D71643351704649782F424A78472F4F474D4568684471774967506236587A6C774477424D2B534C7A6B3248596E4179 30682F506B7073386C38426E3133415663396851515C7530303364222C0A202022696E7465726D6564696174655369676E696E674B6579223A207B0A20202020227369676E65644B6579223A20227B5C226B657956616C75655C223A5C224D466B774577 59484B6F5A497A6A3043415159494B6F5A497A6A30444151634451674145695A6933492B3567307848336B4F584D78694E796F4F4D4D5277553773442B2F716B7331354164675355352B7848325054467765397943514C7A6E344453646A6F33514B4979 632B633566554731646B617342764B775C5C75303033645C5C75303033645C222C5C226B657945787069726174696F6E5C223A5C22313634393736363131393537395C227D222C0A20202020227369676E617475726573223A205B0A202020202020224D 4559434951444C554B7763796639414171794A3657534C7254356A472B486434694B766F587861617976465565725838774968414D7A48714E317879414952687A6E6A4C6B6B55414F516762673763556C744B304648316876524C3743414E220A202020 205D0A20207D2C0A20202270726F746F636F6C56657273696F6E223A202245437632222C0A2020227369676E65644D657373616765223A20227B5C22656E637279707465644D6573736167655C223A5C22454F7047304E4E58394F7079597A6C52354645 6536434D4E6634706B654A7645684F4F4F4739346342442B79317832324C64474535354C653267425249336D465243757351446151747943533550766F4C70302F757270574E7238785478572F4577786A6E716B596755425246474F6D624A5141636541 2F374D416C5075397734677330434F5932616B6775726443624C516B4C617354536335652F693647576D646958715741574D384A724E42566B6C70596E46656B334643654B335732336D59486E746564434C79545450566D6255654D51346E387268677A 6F2B386669574E6A4B79774C6A565A6C4A326F2B6F434E78684D566668473734476457766F623254664531756F65584F43584F4830327538746F774F4F76523266716E416B4942445566706955536A7057374D6D44544A7959496577635734456F574754 4536412B70457949386A546241345930626F78333965784A624E746851735468715867354F4B4A4F4544634D4E594250672F6C62794E516659384E6A76424D413766422F2F51695A7149753857675A466653694D4A2B6A34755848644344664C54396269 773470646537626B5275482F556F6664314361626966685153753634536545456B6A307238377745593535734E72384B7A53434177774F6751503058596C742F743041354B54396B313732493834577469575159722F554E754956555269483878303865 38496878394E766B67782B477A2F5A79555651483952586A455844524E766D3633735369554D4231546C593950694D4B4F3034353155773279773330632F38537A794B42795059744E6448776D6436694168666F5153704A414B4D547768594D6D4B465A 432B62384B484B62783847652B4E564B76324770434C777930574C34777671574E506B32314A7A63306246636E7A7A74616664545062624542317066595C222C5C22657068656D6572616C5075626C69634B65795C223A5C224247566E30535A314A3570 445A6C496E487665356E6A3159626A2B43306F6C4663547967796E5371553859714B615A73385A6448516A566C49537252493130506D736B675A534D485958646B4D306B2B2F44382F6F306F5C5C75303033645C222C5C227461675C223A5C2249493064 68634F5A74596C3236596C6E33474E5358544B3479616C52796C4B734B6A373152796A5A66464D5C5C75303033645C227D220A7D Пример ответа Google Pay ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: http type=async-response &serial-number=00000000-0000-0000-0000-0000000624e8 &merchant-order-id=59e1e3ca-5d44-11e1-b3d6-002522b853b4 &paynet-order-id=94935