3.7. /api/v2/sale

Введение

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

API URL

Интеграционная среда	Производственная среда
https://sandbox.connpay.com/paynet/api/v2/sale/ENDPOINTID	https://gate.connpay.com/paynet/api/v2/sale/ENDPOINTID
https://sandbox.connpay.com/paynet/api/v2/sale/group/ENDPOINTGROUPID	https://gate.connpay.com/paynet/api/v2/sale/group/ENDPOINTGROUPID

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

Note

Запрос должен иметь заголовок content-type=application/x-www-form-urlencoded.
Банк может переопределить необходимость некоторых полей, сделав их обязательными.
Пробелы в начале и в конце значений параметров будут отсечены.

Warning

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

Название параметра	Описание	Значение
client_orderid	Уникальный идентификатор заказа, присвоенный Присоединяющейся Стороной.	`Необходимость`: Обязательно `Тип`: String `Длина`: 128
order_desc	Описание заказа.	`Необходимость`: Обязательно `Тип`: String `Длина`: 64k
amount	Сумма к оплате. Сумма должна быть указана в минимальных единицах с “.” разделителем. Например, 100.5 в RUB означает 100 российских рублей и 50 копеек.	`Необходимость`: Обязательно `Тип`: Numeric `Длина`: 10
currency	Валюта, в которой проводится операция (см. Коды валют). Примеры значений: USD для доллара США, EUR для европейского евро, RUB для российского рубля.	`Необходимость`: Обязательно `Тип`: String `Длина`: 3
address1	Адрес Плательщика, строка 1.	`Необходимость`: Обязательно `Тип`: String `Длина`: 50
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> (см: Request URL) 2. Параметр запроса: client_orderid 3. Параметр запроса: amount в минимальных денежных единицах 4. Параметр запроса: email 5. merchant_control (Контрольный ключ, назначенный для учетной записи Присоединяющейся Cтороны в ConnPay).	`Необходимость`: Обязательно `Тип`: String `Длина`: 40
cvv2	CVV2-код Плательщика. CVV2 (Card Verification Значение) — это трех- или четырех-значное число ПОСЛЕ номера кредитной карты в области подписи карты.	`Необходимость`: Обязательно `Тип`: Numeric `Длина`: 3-4
credit_card_number	Номер банковской карты Плательщика. Нужно отправлять или комбинацию из credit_card_number, card_printed_name, expire_month и expire_year или параметр card_recurring_payment_id, но не все в одном запросе.	`Необходимость`: Условно `Тип`: 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-v4-card-ref-id.	`Необходимость`: Условно `Тип`: Long `Длина`: 20
card_printed_name	Имя владельца карты, напечатанное на банковской карте.	`Необходимость`: Условно `Тип`: String `Длина`: 128
expire_month	Месяц окончания срока действия банковской карты.	`Необходимость`: Условно `Тип`: Numeric `Длина`: 2
expire_year	Год окончания срока действия банковской карты.	`Необходимость`: Условно `Тип`: Numeric `Длина`: 4
first_name	Имя Плательщика. Необходимость параметра можно уточнить у отдела поддержки. Зависит от канала эквайринга.	`Необходимость`: Обязательно `Тип`: String `Длина`: 50
last_name	Фамилия Плательщика. Необходимость параметра можно уточнить у отдела поддержки. Зависит от канала эквайринга.	`Необходимость`: Обязательно `Тип`: String `Длина`: 50
state	Штат Плательщика. Для списка действительных кодов штатов см. Обязательные коды штатов. Требуется для США, Канады и Австралии.	`Необходимость`: Условно `Тип`: String `Длина`: 2-3
redirect_url	URL-адрес, на который будет перенаправлен Плательщик после завершения транзакции. Перенаправление выполняется в любом случае, независимо от того, получила ли транзакция успешный, неуспешный или любой другой конечный статус (см. Статусы транзакций). Не следует использовать параметры, отправленные вместе с HTTP-запросом перенаправления, для обработки статуса транзакции. Вместо этого необходимо использовать server_callback_url или запрос статуса. Если транзакция не предполагает возврата “плательщика, параметр может быть использован со значением https://doc.connpay.com/. Допускается использование либо параметра redirect_url, либо комбинации параметров redirect_success_url и redirect_success_url, но не и того, и другого одновременно.	`Необходимость`: Опционально `Тип`: String `Длина`: 1024
redirect_success_url	URL-адрес, на который будет перенаправлен Плательщик после получения успешного статуса транзакции.(cм. Статусы транзакций). Не следует использовать параметры, отправленные вместе с HTTP-запросом перенаправления, для обработки статуса транзакции. Вместо этого необходимо использовать server_callback_url или запрос статуса. Если транзакция не предполагает возврата плательщика, параметр может быть использован со значением http://https://doc.connpay.com/. Допускается использование либо параметра redirect_url, либо комбинации параметров redirect_success_url и redirect_success_url, но не и того, и другого одновременно.	`Необходимость`: Опционально `Тип`: String `Длина`: 1024
redirect_fail_url	URL-адрес, на который будет перенаправлен Плательщик после получения неуспешного статуса транзакции.(cм. Статусы транзакций). Не следует использовать параметры, отправленные вместе с HTTP-запросом перенаправления, для обработки статуса транзакции.Вместо этого необходимо использовать server_callback_url или запрос статуса. Если транзакция не предполагает возврата плательщика, параметр может быть использован со значением http://https://doc.connpay.com/. Допускается использование либо параметра redirect_url, либо комбинации параметров redirect_success_url и redirect_success_url, но не и того, и другого одновременно.	`Необходимость`: Опционально `Тип`: String `Длина`: 1024
ssn	Последние четыре цифры номера социального страхования Плательщика.	`Необходимость`: Опционально `Тип`: Numeric `Длина`: 32
birthday	Дата рождения Плательщика в формате ГГГГММДД.	`Необходимость`: Опционально `Тип`: Numeric `Длина`: 8
cell_phone	Полный номер мобильного телефона Плательщика, включая код страны.	`Необходимость`: Опционально `Тип`: String `Длина`: 15
site_url	URL-адрес сайта электронной коммерции, откуда происходит платеж.	`Необходимость`: Опционально `Тип`: String `Длина`: 128
purpose	Назначение платежа. Параметр может использоваться для указания пополняемого счёта (счета мобильных телефонов, игровые учётные записи и т. д.). Примеры значений: +7123456789; gamer0001@ereality.com и т. д. Это значение может проверяться системой защиты от мошенничества.	`Необходимость`: Опционально `Тип`: String `Длина`: 128
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 server_callback_url refer to Connecting Party callback parameters.	`Необходимость`: Опционально `Тип`: String `Длина`: 1024
merchant_data	Дополнительные сведения о транзакции для Присоединяющейся Стороны, которые можно прикрепить к транзакции и получить обратно в ответе на запрос статуса или обратном вызове. Может содержать данные, которые будут полезны во внешней системе Присоединяющейся Стороны, например VIP клиент, телевизионная промо-кампания. Информация возвращается в ответе на запрос статуса и в обратном вызове Присоединяющейся Стороны.	`Необходимость`: Опционально `Тип`: String `Длина`: 64k
dapi_imei	Уникальный идентификатор устройства.	`Необходимость`: Опционально `Тип`: String `Длина`: 32
minimum_transaction_amount	Этот параметр можно использовать для ограничения минимальной суммы транзакции, если сумма транзакции доступна для указания Плательщиком в форме. Свяжитесь с менеджером службы поддержки, чтобы включить эту функцию. Формат значения такой же, как и в параметре amount.	`Необходимость`: Опционально `Тип`: Numeric `Длина`: 10
maximum_transaction_amount	Этот параметр можно использовать для ограничения максимальной суммы транзакции, если сумма транзакции доступна для указания Плательщиком в форме. Свяжитесь с менеджером службы поддержки, чтобы включить эту функцию. Формат значения такой же, как и в параметре amount.	`Необходимость`: Опционально `Тип`: Numeric `Длина`: 10
customer_level	Уровень клиента в системе CMS.	`Необходимость`: Опционально `Тип`: Varchar `Длина`: 32
customer_id	Идентификатор клиента в системе CMS. Параметр становится обязательным, если включена система CMS в режиме Payment Gateway.	`Необходимость`: Опционально `Тип`: Int `Длина`: 10
merchant_customer_identifier	Идентификатор клиента в системе CMS, назначенный Присоединяющейся Стороной. Параметр становится обязательным, если включена система CMS в режиме CRM.	`Необходимость`: Опционально `Тип`: Varchar `Длина`: 64

Данные браузера для 3DS 2.X собираются системой Присоединяющейся Стороны на этапе 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, alias tds_cres_notification_url	Полный URL-адрес системы Присоединяющейся Стороны, которая получит сообщение CRes или сообщение об ошибке. Это сообщение CRes должно быть отправлено ConnPay. См.:ref:Загрузка результата CRes :ref:`CRes</api/3ds/v1/upload-cres-result/>.	`Необходимость`: Опционально `Тип`: 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 аутентификации происходит на их стороне.

Parameter Name	Description	Value
tds_authentication_result_type	Type of result. Possible values are: - SIMPLE	`Type`: String `Length`: 6
tds_authentication_result_authentication_type	Authentication Type. Indicates the type of authentication method the Issuer will use to challenge the Cardholder, whether in the ARes message or what was used by the ACS when in the RReq message. Possible values are: - 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	`Type`: String `Length`: 2
tds_authentication_result_authentication_value	Authentication Value. Payment System-specific value provided by the ACS or the DS using an algorithm defined by Payment System. Authentication Value may be used to provide proof of authentication. A 20-byte value that has been Base64 encoded, giving a 28-byte result	`Type`: String `Length`: 19-28
tds_authentication_result_transaction_id	xid for 1.0.2 or dsTransID for 2.1.0/2.2.0	`Type`: String `Length`: 19-36
tds_authentication_result_transaction_status	Transaction Status. Indicates whether a transaction qualifies as an authenticated transaction or account verification. Possible values are: - 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	`Type`: String `Length`: 1
tds_authentication_result_message_version	Message Version Number. Protocol version identifier This shall be the Protocol Version Number of the specification utilised by the system creating this message. The Message Version Number is set by the 3DS Server which originates the protocol with the AReq message. The Message Version Number does not change during a 3DS transaction. Possible values are: - 1.0.2 - 2.1.0 - 2.2.0	`Type`: String `Length`: 5

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

Note

Ответ имеет заголовок 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	Номер заказа в системе gate.connpay.com.
merchant-order-id	Номер заказа в системе Присоединяющейся Стороны.
serial-number	Уникальный номер, присвоенный сервером ConnPay конкретному запросу от Присоединяющейся Стороны.
error-message	Для транзакций в статусе declined или error, этот параметр будет содержать причину отклонения или сведения об ошибке.
error-code	Код ошибки для транзакций в статусе declined или error.
end-point-id	Идентификатор терминала, используемый для транзакции.

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

POST /paynet/api/v2/sale/39529 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=John
&expire_month=01
&expire_year=2042
&cvv2=123
&client_orderid=34T43R77N
&order_desc=Test Order Описание
&first_name=John
&last_name=Smith
&ssn=1267
&birthday=19820115
&address1=100%20Main%20st
&city=Seattle
&state=WA
&zip_code=98102
&country=US
&phone=+12063582043
&cell_phone=+19023384543
&amount=156
&email=john.smith@gmail.com
&currency=RUB
&ipaddress=65.153.12.232
&site_url=https://doc.connpay.com/
&purpose=user_account1
&redirect_url=http%3A%2F%2Fhttps://doc.connpay.com/%2Fdoc%2Fdummy.htm
&server_callback_url=https%3A%2F%2Fhttpstat.us%2F200
&merchant_data=VIP customer
&dapi_imei=123
&control=c821e33bd22773c05c23725d0b1d2dbd9f191399

Request for SBP Example

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

&client_orderid=34T43R77N
&order_desc=Test Order Описание
&first_name=John
&last_name=Smith
&ssn=1267
&birthday=19820115
&address1=100%20Main%20st
&city=Seattle
&state=WA
&zip_code=98102
&country=US
&phone=+12063582043
&cell_phone=+19023384543
&amount=156
&email=john.smith@gmail.com
&currency=RUB
&ipaddress=65.153.12.232
&site_url=https://doc.connpay.com/
&purpose=user_account1
&redirect_url=http%3A%2F%2Fhttps://doc.connpay.com/%2Fdoc%2Fdummy.htm
&server_callback_url=https%3A%2F%2Fhttpstat.us%2F200
&merchant_data=VIP customer
&dapi_imei=123
&control=c821e33bd22773c05c23725d0b1d2dbd9f191399

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

POST /paynet/api/v2/sale/39915 HTTP/1.1
Host: sandbox.connpay.com
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 317
Content-Type: application/x-www-form-urlencoded
Connection: close

card_recurring_payment_id=1491954
&cvv2=123
&client_orderid=34T43R77N
&order_desc=Test Order Описание
&amount=777
&currency=USD
&ipaddress=65.153.12.232
&redirect_url=http://doc2.doc2.com/doc/dummy.htm
&server_callback_url=https://httpstat.us/200
&control=80761544c64373d1624240add048d36d42fe528a

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

HTTP/1.1 200
Server: server
Date: Wed, 17 Nov 2021 11:03:17 GMT
Content-Type: text/html;charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Keep-Alive: timeout=60
Vary: Accept-Encoding
X-XSS-Protection: 1
Strict-Transport-Security: max-age=31536000
Content-Language: ru-RU
P3P: CP="NOI ADM DEV COM NAV OUR STP"
Content-Encoding: gzip

type=async-response
&serial-number=00000000-0000-0000-0000-000002d9b22a
&merchant-order-id=inv4097763
&paynet-order-id=6768788
&end-point-id=22903

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

HTTP/1.1 200
Server: server
Date: Wed, 17 Nov 2021 13:14:40 GMT
Content-Type: text/html;charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Keep-Alive: timeout=60
Vary: Accept-Encoding
X-XSS-Protection: 1
Strict-Transport-Security: max-age=31536000
Content-Language: ru-RU
P3P: CP="NOI ADM DEV COM NAV OUR STP"
Content-Encoding: gzip

type=validation-error
&serial-number=00000000-0000-0000-0000-000002b36f64
&merchant-order-id=inv4097763
&error-message=End+point+with+id+22903+not+found
&error-code=3

Коллекция 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
card_recurring_payment_id	use either RPI or card number, not both
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
server_callback_url
merchant_data
dapi_imei

String to sign

Signature