3.16. /api/v2/preauth

Введение

Preauth инициируется запросом HTTPS POST с использованием указанных ниже URL и параметров. Для аутентификации используйте SHA-1. См. статусы.

API URL

Примечание

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

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

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

https://sandbox.sbctech.ru/paynet/api/v2/preauth/ENDPOINTID

https://gate.sbctech.ru/paynet/api/v2/preauth/ENDPOINTID

https://sandbox.sbctech.ru/paynet/api/v2/preauth/group/ENDPOINTGROUPID

https://gate.sbctech.ru/paynet/api/v2/preauth/group/ENDPOINTGROUPID

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

Примечание

Запрос должен иметь заголовок content-type=application/x-www-form-urlencoded.

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

Описание

Значение

client_orderid

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

order_desc

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

amount

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

currency

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

address1

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

city

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

zip_code

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

country

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

phone

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

email

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

ipaddress

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

control
Контрольная сумма, сгенерированная SHA-1. Строка для подписи представляет собой объединение следующих параметров:
1. <ENDPOINTID | ENDPOINTGROUPID> (См.: URL запроса).
2. Параметр запроса:client_orderid.
3. Параметр запроса: amount в минимальных денежных единицах,
4. Параметр запроса: email,
5. merchant_control (Контрольный ключ, назначенный для учетной записи Присоединяющейся стороны в SBC).
Необходимость: Обязательно
Тип: String
Длина: 40

cvv2

Код CVV2 плательщика. CVV2 (Card Verification Значение) — это трех - или четырехзначное число, напечатанное на обратной стороне карты в области подписи.
Необходимость: Обязательно
Тип: Numeric
Длина: 3-4

credit_card_number

Номер банковской карты плательщика (также известный как PAN — Primary Account Number).
Необходимость: Обязательно
Тип: Numeric
Длина: 20

card_recurring_payment_id

Идентификатор токенизированных данных держателя карты Плательщика. Отправьте либо card_recurring_payment_id, либо комбинацию credit_card_number, card_printed_name, expire_month и expire_year, но не все значения одновременно. Сведения о создании card_recurring_payment_id см. в /api/v2/create-card-ref.
Необходимость: Обязательно
Тип: Long
Длина: 20

card_printed_name

Имя владельца карты, напечатанное на банковской карте.
Необходимость: Обязательно
Тип: String
Длина: 64k

expire_month

Месяц окончания срока действия банковской карты.
Необходимость: Обязательно
Тип: Numeric
Длина: 2

expire_year

Год окончания срока действия банковской карты.
Необходимость: Обязательно
Тип: Numeric
Длина: 4

first_name

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

last_name

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

state

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

redirect_url
URL-адрес, на который будет перенаправлен Плательщик после завершения транзакции. Перенаправление выполняется в любом случае, независимо от того, получила ли транзакция статус successful, unsuccessful или любой другой конечный статус (см. Статусы транзакций).
Присоединяющаяся сторона должен не use parameters come along с redirect HTTP Запрос в treat статус транзакция. Instead Присоединяющаяся сторона может utilize server_callback_url или статус API command. Pass site.siteназвание if you have no need в return payer anywhere. Use either redirect_url или combination redirect_успех_url и redirect_fail_url, не both. https://doc.sbctech.ru/
Необходимость: Опционально
Тип: String
Длина: 1024

redirect_success_url
URL-адрес, на который будет перенаправлен Плательщик после получения успешного статуса транзакции (см. Статусы транзакций).
Присоединяющаяся сторона не должна использовать параметры, передаваемые вместе с перенаправленным HTTP-запросом, для определения статуса транзакции. Вместо этого Присоединяющаяся сторона может использовать server_callback_url или команду API статуса. В противном случае передайте https://doc.sbctech.ru/, если не требуется перенаправлять плательщика. Используйте комбинацию redirect_success_url и redirect_fail_url либо redirect_url, но не оба варианта.
Необходимость: Опционально
Тип: String
Длина: 1024

redirect_fail_url
URL-адрес, на который будет перенаправлен Плательщик после получения неуспешного статуса транзакции (см. Статусы транзакций).
Присоединяющаяся сторона не должна использовать параметры, переданные с HTTP-запросом перенаправления, для определения статуса транзакции. Вместо этого используйте server_callback_url или status API command. Передайте https://doc.sbctech.ru/, если плательщика не нужно никуда перенаправлять. Используйте либо сочетание redirect_fail_url и redirect_success_url, либо redirect_url, но не оба варианта.
Необходимость: Опционально
Тип: String
Длина: 1024

ssn

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

birthday

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

cell_phone

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

site_url

URL-адрес сайта электронной коммерции, откуда происходит платеж.
Необходимость: Опционально
Тип: String
Длина: 128

purpose

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

server_callback_url
URL-адрес, по которому будет отправлен обратный вызов с результатом транзакции.
Присоединяющаяся сторона may use server callback URL для custom processing транзакция completion, e.g. в collect платёж data in Присоединяющаяся сторона’s information system. For list parameters which come along с server callback в server_callback_url refer в Присоединяющаяся сторона callback parameters. Thявляется parameter может be sent instead notify_url. If server_callback_url является sent, Платёжный Шлюз sends callback notification only when original транзакция receives final статус. If notify_url является sent, Платёжный Шлюз sends callback notification once original транзакция receives final статус, и about every future upдата для thявляется original транзакция (reversal, chargeback, etc).
Необходимость: Опционально
Тип: String
Длина: 1024

notify_url
URL-адрес, по которому будет отправлен обратный вызов с результатом транзакции.
Присоединяющаяся сторона may use notify URL для custom processing транзакция completion, e.g. в collect платёж data in Присоединяющаяся сторона’s information system. For list parameters which come along с server callback в notify_url refer в Присоединяющаяся сторона callback parameters. Thявляется parameter может be sent instead server_callback_url. If notify_url является sent, Платёжный Шлюз sends callback notification once original транзакция receives final статус, и about every future upдата для thявляется original транзакция (reversal, chargeback, etc). If server_callback_url является sent, Платёжный Шлюз sends callback notification only when original транзакция receives final статус.
Необходимость: Опционально
Тип: String
Длина: 1024

order_desc
Дополнительные сведения о транзакции для Присоединяющейся Стороны, которые можно прикрепить к транзакции и получить обратно в ответе на:ref:запрос статуса</api/v2/status/>,:ref:обратном вызове Присоединяющейся Стороны<merchant_callback_parameters> или:ex:server_callback_url. Может содержать данные, которые будут полезны во внешней системе Присоединяющейся Стороны, например:ex:VIP клиент,:ex:телевизионная промо-кампания.
Информация возвращается в ответе на запрос статуса и в обратном вызове Присоединяющейся Стороны.
Необходимость: Опционально
Тип: String
Длина: 64k

minimum_transaction_amount

Этот параметр можно использовать для ограничения минимальной суммы транзакции, если сумма транзакции доступна для указания Плательщиком в форме. Свяжитесь с менеджером службы поддержки, чтобы включить эту функцию. Формат значения такой же, как и в параметре:ex:amount.
Необходимость: Опционально
Тип: Numeric
Длина: 10

maximum_transaction_amount

Этот параметр можно использовать для ограничения максимальной суммы транзакции, если сумма транзакции доступна для указания Плательщиком в форме. Свяжитесь с менеджером службы поддержки, чтобы включить эту функцию. Формат значения такой же, как и в параметре:ex:amount.
Необходимость: Опционально
Тип: Numeric
Длина: 10

customer_level

Уровень клиента в системе CMS.
Необходимость: Опционально
Тип: Varchar
Длина: 32

customer_id

Идентификатор клиента в системе CMS. Параметр становится обязательным, если включена система CMS в режиме определения клиента Платёжным шлюзом.
Необходимость: Опционально
Тип: Int
Длина: 10

merchant_customer_identifier

Идентификатор клиента-продавца в системе CMS. Параметр становится обязательным, если включена система CMS в режиме CRM.
Необходимость: Опционально
Тип: Varchar
Длина: 64

recurring-payment-id

Recurring Payment ID может быть передан вместо данных держателя карты. Для нативных транзакций CVV не требуется. Обновление данных клиента возможно через:ref:/api/v4/update-recurring-payment/<api_v4_update-recurring-payment>. Процесс создания Recurring Payment ID инициируется:code:HTTPS POST запросом с использованием указанных ниже:ref:URLs<api_v4_card-ref-id_request_url>. и:ref:параметров<v4_card-ref-id_request_parameters>, используйте:ref:RSA-SHA256 для аутентификация
Необходимость: Условно
Тип: Long

Дополнительные поля для транзакций Preauth

Для Присоединяющейся Стороны

Примечание

Данные браузера для 3DS 2.X собираются системой SBC на этапе 3DS-аутентификации. Однако для некоторых каналов обработки данные браузера и/или URL Присоединяющейся стороны для результатов 3DS challenge должны быть переданы в первоначальном запросе транзакции. Обратитесь к менеджеру поддержки, чтобы уточнить, следует ли включать эти параметры в параметры запроса.

Сайт Присоединяющейся Стороны должен точно заполнять информацию о браузере по каждой транзакции. Эти данные могут быть получены серверами Присоединяющейся Стороны. Убедитесь, что данные не изменены и не жестко запрограммированы, и что они уникальны для каждой транзакции.

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

Описание

Значение

ipaddress

IP-адрес браузера, возвращаемый HTTP-заголовками инициатору запроса 3DS.
Необходимость: Обязательно
Тип: String
Длина: 45

customer_browser_accept_header

Точное содержание заголовков HTTP Accept, отправленное инициатору запроса 3DS из браузера владельца карты.
Необходимость: Обязательно
Тип: String
Длина: 2048

customer_browser_javascript_enabled

Boolean, представляющий cпособность браузера владельца карты запускать JavaScript.
Необходимость: Обязательно
Тип: Boolean
Длина: -

customer_browser_accept_language

Значение, представляющее язык браузера, по определено IETF BCP47.
Необходимость: Обязательно
Тип: String
Длина: 8

customer_browser_user_agent

Точное содержание заголовка HTTP user-agent.
Необходимость: Обязательно
Тип: String
Длина: 2048

tds_areq_notification_url, псевдоним tds_cres_notification_url

Полный URL-адрес системы Присоединяющейся Стороны, которая получит сообщение CRes или сообщение об ошибке. Это сообщение CRes должно быть отправлено SBC. См. Загрузка результата CRes.
Необходимость: Опционально
Тип: String
Длина: 256

customer_browser_info

Если true, параметры, приведенные ниже, должны быть указаны.
Необходимость: Опционально
Тип: Boolean
Длина: -

customer_browser_color_depth

Значение, представляющее разрядность цветовой палитры для отображения изображений, в битах на пиксель. Становится обязательным, когда browser_javaScript_enabled = true».
Необходимость: Опционально
Тип: String
Длина: 2

customer_browser_java_enabled

Boolean, который представляет способность браузера владельца карты запускать Java. Становится обязательным, когда browser_javaScript_enabled = true.
Необходимость: Опционально
Тип: Boolean
Длина: -

customer_browser_screen_height

Общая высота экрана владельца карты в пикселях. Требуется, когда browser_javaScript_enabled = true.
Необходимость: Опционально
Тип: Numeric
Длина: 6

customer_browser_screen_width

Общая ширина экрана владельца карты в пикселях. Требуется, когда browser_javaScript_enabled = true.
Необходимость: Опционально
Тип: Numeric
Длина: 6

customer_browser_time_zone

Смещение часового пояса в минутах между UTC и местным временем браузера держателя карты. Обратите внимание, что смещение является положительным, если местный часовой пояс отстает от UTC, и отрицательным, если он опережает UTC. Становится обязательным, когда browser_javaScript_enabled = true.
Необходимость: Опционально
Тип: String
Длина: 5

Для платежных учреждений

PSP или эквайер могут заполнить результаты 3DS для каждой транзакции, если выполнение 3DS аутентификации происходит на их стороне.

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

Описание

Значение

tds_authentication_result_type
Тип результата. Возможное значение:
- SIMPLE
Тип: String
Длина: 6

tds_authentication_result_authentication_type
Тип Аутентификации. Показывает тип метода аутентификации, используемый Эмитентом, для отправки ARes сообщения или использованный ACS при отправке RReq сообщения. Возможные значения:
- 01 = Static
- 02 = Dynamic
- 03 = OOB
- 04 = Decoupled
- 05-79 = Reserved for EMVCo future use (values invalid until defined by EMVCo)
- 80-99 = Reserved for DS use
Тип: String
Длина: 2

tds_authentication_result_authentication_value

Значение Аутентификации. Зависищее от Платежной Системы значение, определяемое ACS или DS, используя алгоритмы, определенные Платежной Системой. Значение Аутентификации может быть использовано как подтверждение аутентификации. 20-байтное значение, закодированное Base64, выдающее 28-байтный результат
Тип: String
Длина: 19-28

tds_authentication_result_transaction_id

xid для 1.0.2 или dsTransID для 2.1.0/2.2.0
Тип: String
Длина: 19-36

tds_authentication_result_transaction_status
Статус транзакции. Показывает, транзакция аутентифицирована или верифицирована. Возможные значения:
- Y = Authentication Verification Successful
- N = Not Authenticated/Account Not Verified, Transaction denied
- U = Authentication/Account Verification Could Not Be Performed, Technical or other problem, as indicated in ARes or RReq
- A = Attempts Processing Performed, Not Authenticated/Verified, but a proof of attempted authentication/verification is provided
- C = Challenge Required, Additional authentication is required using the CReq/CRes
- D = Challenge Required, Decoupled Authentication confirmed
- R = Authentication/ Account Verification Rejected, Issuer is rejecting
Тип: String
Длина: 15

tds_authentication_result_message_version
Версия номера сообщения. Версия протокола идентификацтора. Это номер версии протокола, назначенного системой, посылающей сообщение. Версия номера сообщения назначается Сервером 3DS, который относит протокол к сообщению AReq. Версия номера сообщения не меняется во время процесса 3DS. Возможные значения:
- 1.0.2
- 2.1.0
- 2.2.0
Тип: String
Длина: 5

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

Примечание

Ответ имеет заголовок Content-Type: text/html;charset=utf-8. Все поля имеют кодировку x-www-form-urlencoded, с символом (0xA) в конце значения каждого параметра.

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

Описание

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

paynet-order-id

Идентификатор заказа, присвоенный SBC.

merchant-order-id

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

serial-number

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

error-message

Для транзакций в статусе error этот параметр будет содержать причину отклонения или сведения об ошибке.

error-code

Код ошибки для транзакций в статусе error.

end-point-id

Идентификатор терминала, используемый для транзакции.

Пример запроса с данными владельца карты

POST /paynet/api/v2/preauth/39549 HTTP/1.1
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 314
Content-Type: application/x-www-form-urlencoded
Connection: close

credit_card_number=4538977399606732
&card_printed_name=CARD HOLDER
&expire_month=12
&expire_year=2099
&cvv2=123
&client_orderid=902B4FF5
&order_desc=Test Order Описание
&first_name=John
&last_name=Smith
&ssn=1267
&birthday=19820115
&address1=100 Main st
&city=Seattle
&state=WA
&zip_code=98102
&country=US
&phone=%2B12063582043
&cell_phone=%2B19023384543
&email=john.smith@gmail.com
&currency=USD
&amount=10.42
&ipaddress=65.153.12.232
&site_url=https://doc.sbctech.ru/
&purpose=user_account1
&redirect_url=https://doc.sbctech.ru//doc/dummy.htm
&server_callback_url=https://httpstat.us/200
&merchant_data=VIP customer
&control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483

Пример запроса с идентификатором регулярного платежа по карте

POST /paynet/api/v2/preauth/39549 HTTP/1.1
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 314
Content-Type: application/x-www-form-urlencoded
Connection: close

card_recurring_payment_id=1491927
&cvv2=123
&client_orderid=34T43R77N
&order_desc=Test Order Описание
&amount=777
&currency=USD
&ipaddress=65.153.12.232
&redirect_url=https://doc.sbctech.ru//doc/dummy.htm
&server_callback_url=https://httpstat.us/200
&control=218d377897ce25c2ac69d99de42bc6902eb5bcd8

Пример успешного ответа

HTTP/1.1 200 OK
Server: server
Date: Mon, 05 Sep 2022 10:43:57 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 139

type=async-response
&serial-number=00000000-0000-0000-0000-000002ddb018
&merchant-order-id=123
&paynet-order-id=6863073
&end-point-id=39914

Пример неуспешного ответа

HTTP/1.1 200 OK
Server: server
Date: Mon, 05 Sep 2022 10:51:14 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 208

type=validation-error
&serial-number=00000000-0000-0000-0000-000002ddb019
&merchant-order-id=123
&error-message=Validate+card+number+failed.+Card+Number+length+must+be+between+16+and+19+digits..
&error-code=8

Коллекция Postman

Конструктор запросов

endpointid or groupid

input ENDPOINTID or ENDPOINTGROUPID

client_orderid

make it or use internal invoice ID

order_desc
first_name
last_name
ssn
birthday
address1
city
state
zip_code
country
phone
cell_phone
amount
email
currency
ipaddress
site_url
credit_card_number

card_printed_name
expire_month
expire_year
cvv2
purpose
merchant_control

input Control Key

redirect_url
redirect_success_url
redirect_fail_url
notify_url
server_callback_url
merchant_data
merchant_form_data

String to sign
Signature