3.45. /mapi/v1/sale

Введение

Приложение инициирует транзакцию, отправляя запрос HTTPS POST с использованием указанных ниже URL и параметров. Для аутентификации используйте HMAC-SHA1.

API URL

Примечание

Путь API URL не должен быть задан фиксированным значением, т.к. он может быть изменён позднее.

Интеграционная среда

Производственная среда

https://sandbox.sbctech.ru/paynet/mapi/v1/sale/ENDPOINTID

https://gate.sbctech.ru/paynet/mapi/v1/sale/ENDPOINTID

Параметры запроса

Примечание

* начальные и конечные пробелы в значениях параметров будут отброшены
В значениях параметров необходимо экранировать следующие символы: & + \.

Название параметра

Описание

Значение

client_orderid

Уникальный идентификатор заказа, присвоенный Присоединяющейся Стороной.
Необходимость: Обязательно
Тип: String
Длина: 128

order_desc

Краткое описание заказа
Необходимость: Обязательно
Тип: String
Длина: 64k

first_name

Имя Плательщика.
Необходимость: Опционально
Тип: String
Длина: 50

last_name

Фамилия Плательщика
Необходимость: Опционально
Тип: String
Длина: 50

ssn

Последние четыре цифры номера социального страхования Плательщика.
Необходимость: Опционально
Тип: Numeric
Длина: 32

birthday

Дата рождения Плательщика в формате YYYYMMDD.
Необходимость: Опционально
Тип: Numeric
Длина: 8

address1

Адрес Плательщика, строка 1. (Обратите внимание, что в некоторых случаях невозможно отправить адрес длиной более 50 символов. Для получения более подробной информации обратитесь к вашему менеджеру.)
Необходимость: Обязательно
Тип: String
Длина: 256

city

Город Плательщика.
Необходимость: Обязательно
Тип: String
Длина: 50

state

Штат Плательщика. Для списка действительных кодов штатов см. Обязательные коды штатов. Требуется для США, Канады и Австралии.
Необходимость: Опционально
Тип: String
Длина: 2

zip_code

Почтовый индекс Плательщика
Необходимость: Обязательно
Тип: String
Длина: 10

country

Страна Плательщика. Для списка действительных кодов см. Коды стран.
Необходимость: Обязательно
Тип: String
Длина: 2

phone

Полный международный номер телефона Плательщика, включая код страны.
Необходимость: Опционально
Тип: String
Длина: 15

cell_phone

Полный международный мобильный номер телефона Плательщика, включая код страны.
Необходимость: Опционально
Тип: String
Длина: 15

email

Адрес электронной почты Плательщика.
Необходимость: Обязательно
Тип: String
Длина: 50

purpose

Получатель платежа. Это полезно для Присоединяющихся сторон, позволяющих плательщикам пополнять свои счета банковской картой (счета мобильных телефонов, игровые счета и т. д.). Примеры значений: +9999999999; mail@example.com и т. д. Это значение может использоваться системой мониторинга мошенничества.
Необходимость: Опционально
Тип: String
Длина: 128

amount

Сумма к списанию. Сумма указывается в основных единицах с разделителем .. Например, 10.5 для USD означает 10 долларов США и 50 центов
Необходимость: Обязательно
Тип: Numeric
Длина: 10

currency

Валюта, в которой проводится транзакция (см. Коды валют). Примеры значений: USD для доллара США, EUR для европейского евро
Необходимость: Обязательно
Тип: String
Длина: 3

cvv2

Код CVV2 клиента. CVV2 (Card Verification Значение) — трёх- или четырёхзначное число, указанное ПОСЛЕ номера карты в области подписи карты. Используется, если эквайер предоставляет только E-Commerce соединение
Необходимость: Опционально
Тип: Numeric
Длина: 3-4

ipaddress

IP-адрес Плательщика, передаётся для целей мониторинга мошенничества.
Необходимость: Обязательно
Тип: String
Длина: 20

encrypted-type

Тип шифрования. Зависит от модели mPOS
Необходимость: Обязательно
Тип: String
Длина: 32

encrypted-data

Данные дорожек карты, зашифрованные с помощью алгоритма encrypted-type и закодированные в HEX. Подробности уточняйте в службе поддержки
Необходимость: Обязательно
Тип: String
Длина: -

server_callback_url
URL-адрес, по которому будет отправлен обратный вызов с результатом транзакции.
Присоединяющаяся Сторона может использовать URL обратного вызова сервера для собственной обработки завершения транзакции, например, для сбора платёжных данных в информационной системе Присоединяющейся Стороны. Список параметров, передаваемых вместе с обратным вызовом на:ex:server_callback_url, см. в:ref:Параметрах обратного вызова Присоединяющейся Стороны<merchant_callback_parameters>.
Необходимость: Опционально
Тип: String
Длина: 1024

Пример аутентификации запроса

Чтобы гарантировать, что запрос авторизован Присоединяющейся Стороной, все запросы должны быть подписаны. MAPI работает с подписью OAuth 1.0a HMAC-SHA1, так как это устоявшийся стандарт, поддерживаемый в клиентских библиотеках.
MAPI поддерживает только часть с подписью и не поддерживает полноценный OAuth. В качестве секретного ключа используется контрольный ключ Присоединяющейся Стороны.
Ниже приведён пример формирования подписанного запроса на Java с помощью библиотеки scribe:
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, Map<String, String>parameters) {
        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();
        }
    }
}

Параметры ответа

Название параметра

Описание

type

Тип ответа. Может быть async-form-response, validation-error, error. Если тип равен validation-error или error, параметры error-message и error-code содержат сведения об ошибке.

status

Подробности смотрите в:ref:status_list.

paynet-order-id

Идентификатор заказа, присвоенный сервером gate.sbctech.ru

merchant-order-id

Идентификатор заказа Присоединяющейся Стороны

serial-number

Уникальный номер, присваиваемый сервером gate.sbctech.ru конкретному запросу от присоединяющейся стороны.

error-message

Если статус declined или error, этот параметр содержит причину отклонения или сведения об ошибке

error-code

Код ошибки в случае статуса declined или error

Пример запроса Google Pay

После получения токена Google Pay он может выглядеть следующим образом:

{
  "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:

7B0A2020227369676E6174757265223A20224D4555434951434F48317557324C6151686561453462673037346D71643351704649782F424A78472F4F474D4568684471774967506236587A6C774477424D2B534C7A6B3248596E417930682F506B707338
6C38426E3133415663396851515C7530303364222C0A202022696E7465726D6564696174655369676E696E674B6579223A207B0A20202020227369676E65644B6579223A20227B5C226B657956616C75655C223A5C224D466B77457759484B6F5A497A6A
3043415159494B6F5A497A6A30444151634451674145695A6933492B3567307848336B4F584D78694E796F4F4D4D5277553773442B2F716B7331354164675355352B7848325054467765397943514C7A6E344453646A6F33514B4979632B633566554731
646B617342764B775C5C75303033645C5C75303033645C222C5C226B657945787069726174696F6E5C223A5C22313634393736363131393537395C227D222C0A20202020227369676E617475726573223A205B0A202020202020224D4559434951444C55
4B7763796639414171794A3657534C7254356A472B486434694B766F587861617976465565725838774968414D7A48714E317879414952687A6E6A4C6B6B55414F516762673763556C744B304648316876524C3743414E220A202020205D0A20207D2C0A
20202270726F746F636F6C56657273696F6E223A202245437632222C0A2020227369676E65644D657373616765223A20227B5C22656E637279707465644D6573736167655C223A5C22454F7047304E4E58394F7079597A6C523546456536434D4E663470
6B654A7645684F4F4F4739346342442B79317832324C64474535354C653267425249336D465243757351446151747943533550766F4C70302F757270574E7238785478572F4577786A6E716B596755425246474F6D624A51416365412F374D416C507539
7734677330434F5932616B6775726443624C516B4C617354536335652F693647576D646958715741574D384A724E42566B6C70596E46656B334643654B335732336D59486E746564434C79545450566D6255654D51346E387268677A6F2B386669574E6A
4B79774C6A565A6C4A326F2B6F434E78684D566668473734476457766F623254664531756F65584F43584F4830327538746F774F4F76523266716E416B4942445566706955536A7057374D6D44544A7959496577635734456F5747544536412B70457949
386A546241345930626F78333965784A624E746851735468715867354F4B4A4F4544634D4E594250672F6C62794E516659384E6A76424D413766422F2F51695A7149753857675A466653694D4A2B6A34755848644344664C54396269773470646537626B
5275482F556F6664314361626966685153753634536545456B6A307238377745593535734E72384B7A53434177774F6751503058596C742F743041354B54396B313732493834577469575159722F554E75495655526948387830386538496878394E766B
67782B477A2F5A79555651483952586A455844524E766D3633735369554D4231546C593950694D4B4F3034353155773279773330632F38537A794B42795059744E6448776D6436694168666F5153704A414B4D547768594D6D4B465A432B62384B484B62
783847652B4E564B76324770434C777930574C34777671574E506B32314A7A63306246636E7A7A74616664545062624542317066595C222C5C22657068656D6572616C5075626C69634B65795C223A5C224247566E30535A314A3570445A6C496E487665
356E6A3159626A2B43306F6C4663547967796E5371553859714B615A73385A6448516A566C49537252493130506D736B675A534D485958646B4D306B2B2F44382F6F306F5C5C75303033645C222C5C227461675C223A5C224949306468634F5A74596C32
36596C6E33474E5358544B3479616C52796C4B734B6A373152796A5A66464D5C5C75303033645C227D220A7D

Сформируйте запрос, установив encrypted-data равным HEX-токену и encrypted-type=googlepay:

POST paynet/mapi/v1/sale/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=
&currency=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

type=async-response
&serial-number=00000000-0000-0000-0000-0000000624e8
&merchant-order-id=59e1e3ca-5d44-11e1-b3d6-002522b853b4
&paynet-order-id=94935