AFT транзакции
Общая информация об AFT
AFT (Account Funding Transaction) - oсобый вид P2P транзакции по списанию средств с целью пополнения внутреннего счета клиента в системе мерчанта или банковского счета в системе банка (часто используется как альтернатива операции покупки).
AFT транзакции используют сервис P2P. Это сервис, доступный для настройки и интеграции со сторонними веб-сайтами, мобильными приложениями, а также интернет- и мобильными банками.
Пользователям доступен полный перечень операций, отправка/получение переводов, регистрация/авторизация в сервисе, управление сохраненными картами.
Сценарий операции AFT
Существует несколько сценариев реализации AFT-транзакций:
- Данные держателя карты вводятся на стороне шлюза
- Данные держателя карты вводятся на стороне Интернет-магазина
Особенности сценария операции AFT
У сценария операции AFT есть следующие особенности:
- При выполнении AFT-транзакции в запросе регистрации заказа необходимо передать параметр
features
со значениемWITHOUT_TO_CARD
. - В AFT-транзакции в запросе оплаты или в запросе оплаты по связке указываются только данные карты списания, т.е.
fromCard
(блокtoCard
отсутствует, кроме случая трансграничных переводов, см. ниже). - В случае трансграничных переводов, при которых списание с карты и зачисление на транзитный счет вызывается через платежный шлюз, а зачисление вызывается из другой внешней системы, в запросе оплаты в блоке
toCard
необходимо указать блокreplacementData
, который содержит номер карты и номер транзитного счета. См. описание здесь.
Сценарий операции AFT с вводом платежных данных на стороне платежного шлюза
- На сайте продавца (например, в интернет-магазине) держатель карты запрашивает выполнение денежного перевода P2P.
- Система интернет-магазина регистрирует заказ в Платежном шлюзе через registerP2P.do с параметром
features=WITHOUT_TO_CARD
. Используемые параметры регистрации включают сумму перевода, валюту, номер заказа в системе продавца и URL возврата для клиента.
- Платежный шлюз в ответ на запрос регистрации возвращает уникальный идентификатор заказа в платежной системе и URL для перенаправления клиента на форму сбора карточных данных.
- Система интернет-магазина передает URL-адрес перенаправления, полученный на Шаге 3, браузеру клиента.
- Браузер клиента открывает URL-адрес.
- По указанному URL браузер клиента получает форму для сбора карточных данных.
- Клиент заполняет форму, и данные отправляются на сервер платежного шлюза.
- Система проверяет принадлежность карты к 3-D Secure (SecureCode).
- Шлюз отправляет ссылку перенаправления на страницу сервера управления доступом (ACS) банка-эмитента в веб-браузер клиента (этот шаг необходим для реализации 3DS).
- Веб-браузер клиента запрашивает форму авторизации пользователя из ACS.
- ACS отправляет форму авторизации в веб-браузер клиента.
- Клиент заполняет форму, и данные отправляются на сервер платежного шлюза.
- ACS обрабатывает форму и, независимо от результата, отправляет URL-адрес перенаправления страниц платежного шлюза в веб-браузер клиента. Вместе с этим URL отправляются зашифрованные параметры результата авторизации.
- Веб-браузер клиента запрашивает страницу платежного шлюза при передаче зашифрованных параметров результата авторизации.
- Платежный шлюз переводит деньги.
- Когда деньги переведены, платежный шлюз отправляет обратный URL-адрес в веб-браузер клиента (URL-адрес был указан при регистрации заказа интернет-магазином на Шаге 2).
- Веб-браузер клиента запрашивает результаты перевода денег из интернет-магазина.
- Система интернет-магазина запрашивает информацию о статусе заказа у платежного шлюза – getP2PStatus.do.
- Платежный шлюз возвращает статус заказа.
- Система интернет-магазина показывает клиенту результат оплаты.
Сценарий операции AFT с вводом платежных данных на стороне интернет-магазина
- Держатель карты (клиент) взаимодействует с интернет-магазином для создания заказа.
- Система интернет-магазина регистрирует заказ в Платежном шлюзе через registerP2P.do с параметром
features=WITHOUT_TO_CARD
. Используемые параметры регистрации включают сумму перевода, валюту, номер заказа в системе продавца и URL возврата для клиента.
- Платежный шлюз в ответ на запрос регистрации возвращает уникальный идентификатор заказа в платежной системе и URL для перенаправления клиента на форму сбора карточных данных.
- Система интернет-магазина передает URL-адрес перенаправления, полученный на Шаге 3, браузеру клиента.
- Клиент заполняет форму и отправляет данные.
-
Необязательно. Если интернет-магазин работает с комиссией, интернет-магазин отправляет платежному шлюзу запрос на сумму комиссии через verifyP2P.do / verifyP2PByBinding.do.
- Необязательно. Платежный шлюз отправляет в ответ сумму комиссии.
- Интернет-магазин отправляет запрос на перевод средств в Платежный шлюз через performP2P.do / performP2PByBinding.do, указывая данные карты списания в блоке
fromCard
.
На этом этапе инициируется работа 3DS 2.0.
- Платежный шлюз проверяет на сервере 3DS, может ли клиент аутентифицироваться с использованием протокола 2.0.
- Платежный шлюз отправляет ответ на запрос, сделанный на Шаге 6. Ответ также возвращает следующие параметры:
-
is3DSVer2
- флаг возможности аутентификации 3DSv2 (true/false) -
threeDSServerTransId
- идентификатор транзакции, присвоенный сервером 3DS -
threeDSMethodURLServer
- адрес сервера 3DS для сбора данных браузера -
threeDSMethodURL
- (необязательно) адрес сервера ACS для сбора данных браузера -
threeDSMethodDataPacked
- (необязательно) данные для сбора данных браузера на ACS
(См. также описание запроса). -
- Интернет-магазин вызывает
threeDSMethodURLServer
в отдельном iframe с помощью методаPOST
, используя значение, полученное из ответа на запрос на перевод средств. Это позволяет серверу 3DS собирать данные о браузере клиента. -
Необязательно. Если в ответе на запрос о переводе средств были получены параметры
threeDSMethodURL
иthreeDSMethodDataPacked
, интернет-магазин вызывает в отдельном iframe методом POSTthreeDSMethodURL
.
- Перевод средств - этап 2. Интернет-магазин повторно отправляет запрос на выполнение перевода через performP2P.do / performP2PByBinding.do.
Необъодимо передать параметрthreeDSServerTransId
- идентификатор транзакции, который был создан сервером 3DS и возвращен на Шаге 10.
- Платежный шлюз отправляет запрос на аутентификацию на сервер 3DS.
- Сервер 3DS отправляет запрос аутентификации (AReq) на сервер ACS.
- Сервер ACS отправляет ответ на запрос аутентификации (ARes) на сервер 3DS.
- Сервер 3DS отправляет полученные данные в платежный шлюз.
-
- Если клиенту не нужно проходить аутентификацию в ACS, платежный шлюз возвращает ответ на запрос о переводе средств. В этом случае сценарий продолжается с Шага 27.
- Если клиенту необходимо пройти аутентификацию в ACS, Платежный шлюз отправит ответ на платежную страницу с данными перенаправления на ACS.
- Страница оплаты перенаправляется на
acsUrl
с параметромcreq=packedCReq
. - ACS отображает страницу аутентификации для клиента (страница challenge).
- Клиент аутентифицирован.
- Сервер ACS проверяет подлинность данных аутентификации.
- Происходит обмен данными между серверами ACS и 3DS и подтверждается результат обработки.
- Сервер ACS перенаправляет клиента на страницу магазина.
- Интернет-магазин отправляет запрос /p2p/finishThreeDsVer2.do платежному шлюзу.
- Платежный шлюз отправляет интернет-магазину ответ на сделанный запрос.
- Интернет-магазин отправляет getP2PStatus.do в платежный шлюз, чтобы узнать статус заказа.
- Платежный шлюз отправляет ответ на сделанный запрос.
- Интернет-магазин отображает страницу результата клиенту.
API-вызовы
Запросы по P2P-транзакциям (в том числе AFT) должны быть подписаны. Информация о подписях запросов доступна в нашем Руководстве по API.
Регистрация заказа P2P
Для оформления заказа на перевод денег с карты на карту используйте запрос https://3dsec.berekebank.kz/payment/rest/api/p2p/registerP2P.do
.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/json
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | username |
String [1..100] | Логин учетной записи API продавца. |
Обязательно | password |
String [1..200] | Пароль учетной записи API продавца. |
Обязательно | orderNumber |
String [1..36] | Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа. |
Обязательно | amount |
Integer [0..12] | Сумма платежа в минимальных единицах валюты (например, в копейках). |
Обязательно | currency |
Integer [3] | Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию. |
Обязательно | returnUrl |
String [1..512] | Адрес, на который требуется перенаправить пользователя в случае успешной оплаты. Адрес должен быть указан полностью, включая используемый протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com ). В противном случае пользователь будет перенаправлен по адресу следующего вида: https://3dsec.berekebank.kz/payment/<merchant_address> . |
Необязательно | failUrl |
String [1..512] | Адрес, на который требуется перенаправить пользователя в случае неуспешной оплаты. Адрес должен быть указан полностью, включая используемый протокол (например, https://mybestmerchantreturnurl.com вместо mybestmerchantreturnurl.com ). В противном случае пользователь будет перенаправлен по адресу следующего вида: https://3dsec.berekebank.kz/payment/<merchant_address> . |
Необязательно | orderDescription |
String [1..600] | Описание заказа передаваемое платежному шлюзу при регистрации. В этом поле недопустимо передавать персональные данные или платежные данные (номера карт т.п.). Данное требование связано с тем, что описание заказа нигде не маскируется. |
Необязательно | language |
String [2] | Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: ru, en. |
Необязательно | clientId |
String [0..255] | Номер клиента (ID) в системе мерчанта — до 255 символов. Используется для реализации функциональности связок. Может возвращаться в ответе, если мерчанту разрешено создавать связки. Указание этого параметра при обработке платежей по связке обязательно. В противном случае платеж будет невозможен. |
Необязательно | sessionTimeoutSecs |
Integer [1..9] | Продолжительность жизни заказа в секундах. В случае если параметр не задан, будет использовано значение, указанное в настройках мерчанта, или время по умолчанию (1200 секунд = 20 минут). Если в запросе присутствует параметр expirationDate , то значение параметра sessionTimeoutSecs не учитывается. |
Необязательно | sessionExpiredDate |
String | Дата и время истечения срока действия заказа. Формат: yyyy-MM-ddTHH:mm:ss .Если этот параметр не передается в запросе, то для определения времени истечения срока действия заказа используется параметр sessionTimeoutSecs . |
Необязательно | bindingId |
String [1..255] | Идентификатор уже существующей связки (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что:
|
Необязательно | creditBindingId |
String [0..255] | Идентификатор связки карты для зачисления. Используется при переводах с карты на карту, когда заранее известна карта получателя. Этот параметр нужно сначала передать в запросе на регистрацию платежа (registerP2P.do - здесь же должен быть передан параметр clientId ), затем в запросе на перевод средств по cвязке (performP2PByBinding.do - значение параметра creditBindingId , переданного в registerP2P.do , должно быть передано в параметре bindingId в блоке toCard ). |
Необязательно | features |
String | Поле для параметра feature , который будет передан, если имеет место операция AFT или OCT.
|
Необязательно | params |
Object | Поля дополнительной информации для последующего хранения, передаются в следующем виде: {"param":"value","param2":"value2"} .Данные поля могут быть переданы в процессинг банка для последующего отображения в реестрах банка. По умолчанию передаются orderNumber (номер заказа) и orderDescription (описание заказа).orderDescription не должно превышать 99 символов, не используйте следующие символы: % , + , возврат каретки \r и перевод строки \n ).Чтобы включить эту функциональность, обратитесь в банк. |
Необязательно | feeInput |
String | Размер комиссии в минимальных единицах валюты. Функциональность должна быть включена на уровне продавца в шлюзе. Если для мерчанта выставлено соответствующее разрешение, и он осуществляет операции AFT, комиссия мерчанта поступает в запросе на регистрацию и отправляется в сообщении в процессинг.
|
Необязательно | shippingPayerData |
Object | Объект, содержащий данные о доставке клиенту. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | preOrderPayerData |
Object | Объект, содержащий данные предварительного заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | orderPayerData |
Object | Объект, содержащий данные о плательщике заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | billingAndShippingAddressMatchIndicator |
String [1] | Индикатор соответствия платежного адреса владельца карты и адреса доставки. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. Возможные значения:
|
Необязательно | billingPayerData |
Object | Блок с регистрационными данными клиента (адрес, почтовый индекс), необходимый для прохождения проверки адреса в рамках сервисов AVS/AVV. Обязателен, если функция включена для продавца на стороне Платежного шлюза. См. вложенные параметры. |
Необязательно | billingRecipientData |
Object | Блок данных о получателе. Обязателен, если функция включена для продавца на стороне Платежного шлюза. См. вложенные параметры. |
Описание параметров объекта shippingPayerData
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | shippingCity |
String [1..50] | Город заказчика (из адреса доставки) |
Необязательно | shippingCountry |
String [1..50] | Страна заказчика |
Необязательно | shippingAddressLine1 |
String [1..50] | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingAddressLine2 |
String [1..50] | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingAddressLine3 |
String [1..50] | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingPostalCode |
String [1..16] | Почтовый индекс клиента для доставки |
Необязательно | shippingState |
String [1..50] | Штат/регион покупателя (из адреса доставки) |
Необязательно | shippingMethodIndicator |
Integer [2] | Индикатор способа доставки. Возможные значения:
|
Необязательно | deliveryTimeframe |
Integer [2] | Срок поставки товара. Возможные значения:
|
Необязательно | deliveryEmail |
String [1..254] | Целевой адрес электронной почты для доставки цифрового распространения. Предпочтительно передавать электронную почту в самостоятельном параметре запроса email (но если вы передадите его в этом блоке, к нему применятся те же правила). |
Описание параметров объекта preOrderPayerData
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | preOrderDate |
String [10] | Ожидаемая дата доставки (для предзаказанных покупок) в формате ГГГГММДД. |
Необязательно | preOrderPurchaseInd |
Integer [2] | Индикатор размещения клиентом заказа на доступную или будущую доставку. Возможные значения:
|
Необязательно | reorderItemsInd |
Integer [2] | Индикатор того, что клиент перебронирует ранее оплаченную доставку в составе нового заказа. Возможные значения:
|
Описание параметров объекта orderPayerData
.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | homePhone |
String [7..15] | Домашний телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | workPhone |
String [7..15] | Рабочий телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | mobilePhone |
String [7..15] | Номер мобильного телефона владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
Для платежей по VISA с 3DS авторизацией необходимо указать либо электронную почту, либо номер телефона владельца карты. Если у вас настроено отображение номера телефона на платежной странице и вы указали неверный номер телефона, клиент сможет исправить его на платежной странице. |
Ниже приведены параметры блока billingPayerData
(данные об адресе регистрации клиента).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | billingCity |
String [0..50] | Город, зарегистрированный по конкретной карте у Банка Эмитента. |
Необязательно | billingCountry |
String [0..50] | Страна, зарегистрированная по конкретной карте банка-эмитента. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или наименование страны. Рекомендуем передавать двух/трехбуквенный ISO код страны. |
Необязательно | billingAddressLine1 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 1. Обязательно к передаче для AVS-проверки. |
Необязательно | billingAddressLine2 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 2. |
Необязательно | billingAddressLine3 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 3. |
Необязательно | billingPostalCode |
String [0..9] | Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно к передаче для AVS-проверки. |
Необязательно | billingState |
String [0..50] | Штат, зарегистрированный по конкретной карте у Банка Эмитента. Формат: полное значение кода ISO 3166-2, его часть или наименование штата/региона. Может содержать буквы только латинского алфавита. Рекомендуем передавать двухбуквенный ISO код штата/региона. |
Optional | payerAccount |
String [1..32] | Номер счета отправителя. |
Необязательно | payerLastName |
String [1..64] | Фамилия отправителя. |
Необязательно | payerFirstName |
String [1..35] | Имя отправителя. |
Необязательно | payerMiddleName |
String [1..35] | Отчество отправителя. |
Необязательно | payerCombinedName |
String [1..99] | Полное имя отправителя. |
Необязательно | payerIdType |
String [1..8] | Тип предоставленного идентифицирующего документа отправителя. Возможные значения:
|
Необязательно | payerIdNumber |
String [1..99] | Номер предоставленного идентифицирующего документа отправителя. |
Необязательно | payerBirthday |
String [1..20] | Дата рождения отправителя в формате YYYYMMDD. |
Ниже приведены параметры блока billingRecipientData
(данные о получателе).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | recipientCity |
String [0..40] | Код города получателя. Формат ISO 3166-1 alpha-3. Может содержать буквы только латинского алфавита. |
Необязательно | recipientCountry |
String [0..50] | Код страны получателя. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или название страны. Рекомендуем передавать двух/трехбуквенный ISO код страны. |
Необязательно | recipientAddressLine1 |
String [0..50] | Адрес получателя. Может содержать буквы только латинского алфавита. |
Необязательно | recipientPostalCode |
String [0..9] | Почтовый индекс получателя. |
Необязательно | recipientState |
String [0..50] | Код штата получателя. Формат: полное значение кода ISO 3166-2, его часть или наименование штата/региона. Может содержать буквы только латинского алфавита. Рекомендуем передавать двухбуквенный ISO код штата/региона. |
Необязательно | recipientAccount |
String [0..32] | Номер счета получателя. |
Необязательно | recipientLastName |
String [0..64] | Фамилия получателя. |
Необязательно | recipientFirstName |
String [0..35] | Имя получателя. |
Необязательно | recipientMiddleName |
String [0..35] | Отчество получателя. |
Необязательно | recipientCombinedName |
String [0..99] | Полное имя получателя. |
Необязательно | recipientIdType |
String [1..8] | Тип предоставленного идентифицирующего документа получателя. Возможные значения:
|
Необязательно | recipientIdNumber |
String [1..99] | Номер предоставленного идентифицирующего документа получателя. |
Необязательно | recipientBirthday |
String [1..20] | Дата дня рождения получателя в формате YYYYMMDD. |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | errorCode |
Integer [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Обязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Необязательно | formUrl |
String [1..512] | URL платежной формы, на которую будет перенаправлен покупатель. URL не возвращается, если регистрация заказа не прошла из-за ошибки, указанной в errorCode . |
Необязательно | orderId |
String [1..36] | Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. |
Необязательно | orderNumber |
String [1..36] | Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа. |
Примеры
Пример запроса
curl -X POST 'https://3dsec.berekebank.kz/payment/rest/api/p2p/registerP2P.do'
-H 'Content-Type: application/json'
--data-raw '{
"username":"test_user",
"password":"test_user_password",
"amount" : 50000,
"currency" : "398",
"returnUrl" : "https://mybestmerchantreturnurl.com",
"orderNumber": "1"
}'
Пример запроса с указанием данных отправителя и получателя
curl -X POST 'https://3dsec.berekebank.kz/payment/rest/api/p2p/registerP2P.do' \
--header 'Content-Type: application/json' \
--data-raw '{
"username": "test_user",
"password": "test_user_password",
"amount" : 1500,
"currency" : "398",
"returnUrl" : "https://mybestmerchantreturnurl.com",
"failUrl" : "https://failUrl.com",
"orderNumber": "01rthtbkuysgr",
"email" : "test@test.com",
"billingPayerData": {
"payerAccount": "DE89370400440532013000",
"payerLastName": "CHINA",
"payerFirstName": "Mieville",
"payerMiddleName": "Tom",
"payerCombinedName": "CHINA Mieville",
"payerIdType": "IDTP1",
"payerIdNumber": "792209292",
"billingCity": "BUD",
"billingCountry": "348",
"billingAddressLine1": "Terez krt",
"billingAddressLine2": "Terez krt",
"billingAddressLine3": "Terez krt",
"billingPostalCode": "1067",
"billingState": "VI",
"payerBirthday": "19900101"
},
"billingRecipientData": {
"recipientAccount": "DE89370400440532013000",
"recipientLastName": "CHINA",
"recipientFirstName": "Mieville",
"recipientMiddleName": "Tom",
"recipientCombinedName": "CHINA Mieville",
"recipientIdType": "IDTP1",
"recipientIdNumber": "792209292",
"recipientCity": "BUD",
"recipientCountry": "348",
"recipientAddressLine1": "Terez krt",
"recipientPostalCode": "1067",
"recipientState": "VI",
"recipientBirthday": "19900101"
}
}'
Пример ответа
{
"errorCode": 0,
"errorMessage": "Successful",
"orderId": "0a4eaae8-653a-71a9-8259-46fc00a8ea58",
"formUrl": "https://3dsec.berekebank.kz/payment/merchants/ecom/payment.html?mdOrder=0a4eaae8-653a-71a9-8259-46fc00a8ea58&language=en",
"orderNumber": "2009"
}
Сумма комиссии
Для получения суммы комиссии за денежный перевод используйте запрос https://3dsec.berekebank.kz/payment/rest/api/p2p/verifyP2P.do
.
Структура запроса предполагает наличие блока fromCard
для передачи атрибутов карты для списания и блока toCard
для передачи атрибутов карты для зачисления.
В зависимости от бизнес-процессов, при проведение перевода с карты на карту могут быть возможны следующие варианты:
- В платежный шлюз передаются данные карты списания и данные карты зачисления денежных средств. В этом случае в запросе должны присутствовать оба блока параметров —
fromCard
иtoCard
. - Если зачисление на карту производится сторонней системой, то в платежный шлюз передаются только данные карты списания. В этом случае должен быть заполнен только один блок параметров –
fromCard
- Если списание с карты производится сторонней системой, то в платежный шлюз передаются только данные карты зачисления. В этом случае должен быть заполнен только один блок параметров –
toCard
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/json
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | username |
String [1..100] | Логин учетной записи API продавца. |
Обязательно | password |
String [1..200] | Пароль учетной записи API продавца. |
Обязательно | orderId |
String [1..36] | Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. |
Необязательно | language |
String [2] | Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: ru, en. |
Необязательно | amount |
String [0..12] | Сумма перевода в минимальных единицах валюты (например, в копейках). Этот параметр передается, если плательщик решит изменить сумму перевода при осуществлении денежного перевода. |
Условие | fromCard |
Object | Блок с атрибутами карты списания. Если списание производится сторонней системой, этот блок должен отсутствовать. В иных случаях он обязателен. См. вложенные параметры. |
Условие | toCard |
Object | Блок с атриубутами карты начисления. Если начисление производится сторонней системой, этот блок должен отсутствовать. В иных случаях он обязателен. См. вложенные параметры. |
Необязательно | billingPayerData |
Object | Блок с регистрационными данными клиента (адрес, почтовый индекс), необходимый для прохождения проверки адреса в рамках сервисов AVS/AVV. Обязателен, если функция включена для продавца на стороне Платежного шлюза. См. вложенные параметры. |
Необязательно | billingRecipientData |
Object | Блок данных о получателе. Обязателен, если функция включена для продавца на стороне Платежного шлюза. См. вложенные параметры. |
Блок fromCard
(если списание производится сторонней системой, то этот блок должен отсутствовать) включает в себя следующие параметры:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | pan |
String [1..19] | Номер карты списания денежных средств. Необходимо передать один из следующих наборов параметров: |
Необязательно | cvc |
Integer [3] | Код CVC/CVV2 на обратной стороне карты списания. Обязателен, если оплата не проводится по связке и/или у продавца нет разрешения на оплату без CVC. |
Обязательно | expirationYear |
Integer [4] | Год истечения действия карты списания. Принимаются значения от 2000 до 2200. Необходимо передать один из следующих наборов параметров: |
Обязательно | expirationMonth |
Integer [2] | Месяц истечения действия карты списания. Доступные значения: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12. Необходимо передать один из следующих наборов параметров: |
Обязательно | cardholderName |
String [1..26] | Имя держателя карты списания. |
Условие | seToken |
String | Зашифрованные данные карты. Обязательно, если используется вместо данных карты. Обязательные параметры для строки seToken: timestamp , UUID , PAN , EXPDATE , MDORDER . Подробнее о генерации seToken см. здесь.Необходимо передать один из следующих наборов параметров: |
Блок toCard
(если зачисление производится сторонней системой, то этот блок должен отсутствовать) включает в себя следующие параметры:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | pan |
String [1..19] | Номер карты для зачисления денежных средств. Необходимо передать один из следующих параметров: |
Необязательно | cvc |
Integer [3] | Код CVC/CVV2 на обратной стороне карты зачисления. |
Необязательно | expirationYear |
Integer [4] | Год истечения действия карты зачисления. Принимаются значения от 2000 до 2200. |
Необязательно | expirationMonth |
Integer [2] | Месяц истечения действия карты зачисления. Доступные значения: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12. |
Необязательно | cardholderName |
String [1..26] | Имя держателя карты зачисления. |
Условие | seToken |
String | Зашифрованные данные карты. Обязательно, если используется вместо данных карты. Обязательные параметры для строки seToken: timestamp , UUID , PAN , EXPDATE , MDORDER . Подробнее о генерации seToken см. здесь.Необходимо передать один из следующих наборов параметров: |
Ниже приведены параметры блока billingPayerData
(данные об адресе регистрации клиента).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | billingCity |
String [0..50] | Город, зарегистрированный по конкретной карте у Банка Эмитента. |
Необязательно | billingCountry |
String [0..50] | Страна, зарегистрированная по конкретной карте банка-эмитента. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или наименование страны. Рекомендуем передавать двух/трехбуквенный ISO код страны. |
Необязательно | billingAddressLine1 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 1. Обязательно к передаче для AVS-проверки. |
Необязательно | billingAddressLine2 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 2. |
Необязательно | billingAddressLine3 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 3. |
Необязательно | billingPostalCode |
String [0..9] | Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно к передаче для AVS-проверки. |
Необязательно | billingState |
String [0..50] | Штат, зарегистрированный по конкретной карте у Банка Эмитента. Формат: полное значение кода ISO 3166-2, его часть или наименование штата/региона. Может содержать буквы только латинского алфавита. Рекомендуем передавать двухбуквенный ISO код штата/региона. |
Optional | payerAccount |
String [1..32] | Номер счета отправителя. |
Необязательно | payerLastName |
String [1..64] | Фамилия отправителя. |
Необязательно | payerFirstName |
String [1..35] | Имя отправителя. |
Необязательно | payerMiddleName |
String [1..35] | Отчество отправителя. |
Необязательно | payerCombinedName |
String [1..99] | Полное имя отправителя. |
Необязательно | payerIdType |
String [1..8] | Тип предоставленного идентифицирующего документа отправителя. Возможные значения:
|
Необязательно | payerIdNumber |
String [1..99] | Номер предоставленного идентифицирующего документа отправителя. |
Необязательно | payerBirthday |
String [1..20] | Дата рождения отправителя в формате YYYYMMDD. |
Ниже приведены параметры блока billingRecipientData
(данные о получателе).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | recipientCity |
String [0..40] | Код города получателя. Формат ISO 3166-1 alpha-3. Может содержать буквы только латинского алфавита. |
Необязательно | recipientCountry |
String [0..50] | Код страны получателя. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или название страны. Рекомендуем передавать двух/трехбуквенный ISO код страны. |
Необязательно | recipientAddressLine1 |
String [0..50] | Адрес получателя. Может содержать буквы только латинского алфавита. |
Необязательно | recipientPostalCode |
String [0..9] | Почтовый индекс получателя. |
Необязательно | recipientState |
String [0..50] | Код штата получателя. Формат: полное значение кода ISO 3166-2, его часть или наименование штата/региона. Может содержать буквы только латинского алфавита. Рекомендуем передавать двухбуквенный ISO код штата/региона. |
Необязательно | recipientAccount |
String [0..32] | Номер счета получателя. |
Необязательно | recipientLastName |
String [0..64] | Фамилия получателя. |
Необязательно | recipientFirstName |
String [0..35] | Имя получателя. |
Необязательно | recipientMiddleName |
String [0..35] | Отчество получателя. |
Необязательно | recipientCombinedName |
String [0..99] | Полное имя получателя. |
Необязательно | recipientIdType |
String [1..8] | Тип предоставленного идентифицирующего документа получателя. Возможные значения:
|
Необязательно | recipientIdNumber |
String [1..99] | Номер предоставленного идентифицирующего документа получателя. |
Необязательно | recipientBirthday |
String [1..20] | Дата дня рождения получателя в формате YYYYMMDD. |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | errorCode |
Integer [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Обязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Блок feeDescriptionList
включает в себя следующие параметры:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | feeAmount |
Integer [1..12] | Сумма комиссии. |
Необязательно | feeCurrency |
String [3] | Код валюты платежа ISO 4217. |
Необязательно | feeDescription |
String [1..512] | Описание комиссии. |
Примеры
Пример запроса
curl -X POST 'https://3dsec.berekebank.kz/payment/rest/api/p2p/verifyP2P.do'
-H 'Content-Type: application/json'
--data-raw '{
"username":"test_user",
"password":"test_user_password",
"orderId": "0a4eaae8-653a-71a9-8259-46fc00a8ea58",
"fromCard": {
"cardholderName": "TEST CARDHOLDER",
"cvc": "123",
"expirationMonth": 12,
"expirationYear": 2030,
"pan": "5000001111111115"
},
"toCard": {
"pan": "4000001111111118"
},
"amount" : 50000
}'
Пример ответа
{
"errorCode": 0,
"errorMessage": "Successful",
"feeDescriptionList: [ {
"feeAmount": 500,
"feeCurrency": "398",
"feeDescription": "Acquirer fee"
} ]
}
Комиссия за P2P перевод по связке
Для получения суммы комиссии при переводе средств по связке используйте запрос https://3dsec.berekebank.kz/payment/rest/api/p2p/verifyP2PByBinding.do
.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/json
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | username |
String [1..100] | Логин учетной записи API продавца. |
Обязательно | password |
String [1..200] | Пароль учетной записи API продавца. |
Необязательно | language |
String [2] | Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: ru, en. |
Обязательно | orderId |
String [1..36] | Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. |
Условие | fromCard |
Object | Блок с атрибутами карты списания. Если списание производится сторонней системой, этот блок должен отсутствовать. В иных случаях он обязателен. См. вложенные параметры. |
Условие | toCard |
Object | Блок с атриубутами карты начисления. Если начисление производится сторонней системой, этот блок должен отсутствовать. В иных случаях он обязателен. См. вложенные параметры. |
Блок fromCard
(если списание производится сторонней системой, то этот блок должен отсутствовать) включает в себя следующие параметры:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | bindingId |
String [1..255] | Идентификатор связки, созданной при оплате заказа или использованной для оплаты. Доступно, только если продавцу разрешено создавать связки. Необходимо передать один из следующих наборов параметров: |
Обязательно | pan |
String [1..19] | Номер карты списания денежных средств. Необходимо передать один из следующих наборов параметров: |
Необязательно | cvc |
Integer [3] | Код CVC/CVV2 на обратной стороне карты списания. Обязателен, если оплата не проводится по связке и/или у продавца нет разрешения на оплату без CVC. |
Обязательно | expirationYear |
Integer [4] | Год истечения действия карты списания. Принимаются значения от 2000 до 2200. Необходимо передать один из следующих наборов параметров: |
Обязательно | expirationMonth |
Integer [2] | Месяц истечения действия карты списания. Доступные значения: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12. Необходимо передать один из следующих наборов параметров: |
Обязательно | cardholderName |
String [1..26] | Имя держателя карты списания. |
Необязательно | seToken |
String [1..8192] | Зашифрованные данные карты. Обязательно, если используется вместо данных карты. Обязательные параметры для строки seToken: timestamp , UUID , bindingId , MDORDER . Подробнее о генерации seToken см. здесь.Необходимо передать один из следующих наборов параметров: |
Блок toCard
(если зачисление производится сторонней системой, то этот блок должен отсутствовать) включает в себя следующие параметры:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | bindingId |
String [1..255] | Идентификатор связки, созданной при оплате заказа или использованной для оплаты. Доступно, только если продавцу разрешено создавать связки. Необходимо передать один из следующих наборов параметров: |
Обязательно | pan |
String [1..19] | Номер карты для зачисления денежных средств. Необходимо передать один из следующих параметров: |
Необязательно | cvc |
Integer [3] | Код CVC/CVV2 на обратной стороне карты зачисления. |
Необязательно | expirationYear |
Integer [4] | Год истечения действия карты зачисления. Принимаются значения от 2000 до 2200. |
Необязательно | expirationMonth |
Integer [2] | Месяц истечения действия карты зачисления. Доступные значения: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12. |
Необязательно | cardholderName |
String [1..26] | Имя держателя карты зачисления. |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | errorCode |
Integer [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Обязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Необязательно | feeAmount |
Integer [1..12] | Сумма комиссии. |
Необязательно | feeCurrency |
String [3] | Код валюты платежа ISO 4217. |
Необязательно | feeDescription |
String [1..512] | Описание комиссии. |
Примеры
Пример запроса
curl --location --request POST 'https://3dsec.berekebank.kz/payment/rest/api/p2p/verifyP2PByBinding.do' \
--header 'Content-Type: application/json' \
--data-raw '{
"username": "test_user",
"password": "test_user_password",
"orderId": "fa71bf70-7c81-484e-a6fc-7db7e4283b2a",
"bindingId": "4d792471-cee0-742c-922d-a265072e6148",
"fromCard": {
"seToken": "ofVx1r3aIJ3Mlx3nkfeOIJgFOnwfsgFK+V6Yzm+KxJgsq19l74GChhX0We/LEFq78Rhn9uFAEZGdeyDhnIc/KfuvObf0EzoDA65Uj1Z8FjwWyjnEwTBHZL4KmdFBCSk8jLxHt70mXwyjiHYyCVH1fT/UVOnsrkZVGrqmEG4MTi5dX9Znzf24DwRg4iezvdT8vf0dUW5lJdvY1tgOsOnBulwy6kH/YbHVsnR6yxO6d6IsdnT5f8PxaB+7ZyUqgrd6VA88FGJKJgdoxk4721pqKSG5dYroLJG96s23EDJ2Hpi4e9wU2rP7E6dlFw+qzATqX/eaJbaQ9eakkdMWnkj7aQ=="
},
"toCard": {
"cardholderName": "IVAN IVANOV",
"cvc": "123",
"expirationMonth": 12,
"expirationYear": 2024,
"pan": "5555555555555599"
},
"amount": 1000,
"currency": "398",
"clientId": "123",
"fromCard": {
"bindingId": "fd3afc57-c6d0-4e08-aaef-1b7cfeb093dc"
},
"toCard": {
"pan": "4000001111111118"
}
}'
Пример ответа
{
"errorCode" : 0,
"errorMessage" : "Successful",
"feeDescriptionList" : [ {
"feeAmount" : 10,
"feeCurrency" : "398",
"feeDescription" : "Acquirer fee"
} ]
}
P2P перевод
Для осуществления денежного перевода с карты на карту используйте запрос https://3dsec.berekebank.kz/payment/rest/api/p2p/performP2P.do
.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/json
Структура запроса performP2P.do
предполагает наличие блока fromCard
для передачи атрибутов карты для списания и блока toCard
для передачи атрибутов карты для зачисления. В зависимости от бизнес-процессов, определённых для банка и магазина, при проведение перевода с карты на карту могут быть возможны следующие варианты.
- Магазин передаёт в шлюз данные карты списания и данные карты зачисления денежных средств. В этом случае в запросе должны присутствовать оба блока параметров —
fromCard
иtoCard
. - Если зачисление на карту производится сторонней системой, то магазин передаёт в шлюз только данные карты списания. В этом случае должен быть только один блок параметров –
fromCard
- Если списание с карты производится сторонней системой, то магазин передаёт в шлюз только данные карты зачисления. В этом случае должен быть только один блок параметров –
toCard
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | username |
String [1..100] | Логин учетной записи API продавца. |
Обязательно | password |
String [1..200] | Пароль учетной записи API продавца. |
Необязательно | language |
String [2] | Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: ru, en. |
Обязательно | orderId |
String [1..36] | Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. |
Необязательно | ip |
String [1..39] | IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов). |
Необязательно | email |
String [1..40] | Электронная почта плательщика. |
Необязательно | amount |
String [0..12] | Сумма перевода в минимальных единицах валюты (например, в копейках). Этот параметр передается, если плательщик решит изменить сумму перевода при осуществлении денежного перевода. |
Необязательно | agent_info.type |
Integer | Тип агента, доступные значения:
|
Необязательно | amountInput |
Integer [0..12] | Сумма перевода в минимальных единицах валюты (например, в копейках). Если в этом параметре указана сумма, перевод будет осуществлен на эту сумму (независимо от суммы, переданной в запросе на оформление заказа). |
Обязательно | params |
Object | Поля дополнительной информации для последующего хранения, передаются в следующем виде: {"param":"value","param2":"value2"} .Данные поля могут быть переданы в процессинг банка для последующего отображения в реестрах банка. По умолчанию передаются orderNumber (номер заказа) и orderDescription (описание заказа).orderDescription не должно превышать 99 символов, не используйте следующие символы: % , + , возврат каретки \r и перевод строки \n ).Чтобы включить эту функциональность, обратитесь в банк. В объекте params запроса на перевод денег с карты на карту могут быть переданы следующие данные клиента (формат значений зависит от используемого метода обработки данных):
params следующую информацию (формат значений определяется используемым методом обработки данных):
При необходимости обратитесь в команду поддержки для указания постоянных значений параметров payer* и recipientName , чтобы не передавать их каждый раз во всех запросах. |
Необязательно | shippingPayerData |
Object | Объект, содержащий данные о доставке клиенту. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | preOrderPayerData |
Object | Объект, содержащий данные предварительного заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | orderPayerData |
Object | Объект, содержащий данные о плательщике заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Условие | fromCard |
Object | Блок с атрибутами карты списания. Если списание производится сторонней системой, этот блок должен отсутствовать. В иных случаях он обязателен. См. вложенные параметры. |
Условие | toCard |
Object | Блок с атриубутами карты начисления. Если начисление производится сторонней системой, этот блок должен отсутствовать. В иных случаях он обязателен. См. вложенные параметры. |
Необязательно | billingPayerData |
Object | Блок с регистрационными данными клиента (адрес, почтовый индекс), необходимый для прохождения проверки адреса в рамках сервисов AVS/AVV. Обязателен, если функция включена для продавца на стороне Платежного шлюза. См. вложенные параметры. |
Необязательно | billingRecipientData |
Object | Блок данных о получателе. Обязателен, если функция включена для продавца на стороне Платежного шлюза. См. вложенные параметры. |
Описание параметров объекта shippingPayerData
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | shippingCity |
String [1..50] | Город заказчика (из адреса доставки) |
Необязательно | shippingCountry |
String [1..50] | Страна заказчика |
Необязательно | shippingAddressLine1 |
String [1..50] | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingAddressLine2 |
String [1..50] | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingAddressLine3 |
String [1..50] | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingPostalCode |
String [1..16] | Почтовый индекс клиента для доставки |
Необязательно | shippingState |
String [1..50] | Штат/регион покупателя (из адреса доставки) |
Необязательно | shippingMethodIndicator |
Integer [2] | Индикатор способа доставки. Возможные значения:
|
Необязательно | deliveryTimeframe |
Integer [2] | Срок поставки товара. Возможные значения:
|
Необязательно | deliveryEmail |
String [1..254] | Целевой адрес электронной почты для доставки цифрового распространения. Предпочтительно передавать электронную почту в самостоятельном параметре запроса email (но если вы передадите его в этом блоке, к нему применятся те же правила). |
Описание параметров объекта preOrderPayerData
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | preOrderDate |
String [10] | Ожидаемая дата доставки (для предзаказанных покупок) в формате ГГГГММДД. |
Необязательно | preOrderPurchaseInd |
Integer [2] | Индикатор размещения клиентом заказа на доступную или будущую доставку. Возможные значения:
|
Необязательно | reorderItemsInd |
Integer [2] | Индикатор того, что клиент перебронирует ранее оплаченную доставку в составе нового заказа. Возможные значения:
|
Описание параметров объекта orderPayerData
.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | homePhone |
String [7..15] | Домашний телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | workPhone |
String [7..15] | Рабочий телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | mobilePhone |
String [7..15] | Номер мобильного телефона владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
Для платежей по VISA с 3DS авторизацией необходимо указать либо электронную почту, либо номер телефона владельца карты. Если у вас настроено отображение номера телефона на платежной странице и вы указали неверный номер телефона, клиент сможет исправить его на платежной странице. |
Ниже приведены параметры блока billingPayerData
(данные об адресе регистрации клиента).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | billingCity |
String [0..50] | Город, зарегистрированный по конкретной карте у Банка Эмитента. |
Необязательно | billingCountry |
String [0..50] | Страна, зарегистрированная по конкретной карте банка-эмитента. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или наименование страны. Рекомендуем передавать двух/трехбуквенный ISO код страны. |
Необязательно | billingAddressLine1 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 1. Обязательно к передаче для AVS-проверки. |
Необязательно | billingAddressLine2 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 2. |
Необязательно | billingAddressLine3 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 3. |
Необязательно | billingPostalCode |
String [0..9] | Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно к передаче для AVS-проверки. |
Необязательно | billingState |
String [0..50] | Штат, зарегистрированный по конкретной карте у Банка Эмитента. Формат: полное значение кода ISO 3166-2, его часть или наименование штата/региона. Может содержать буквы только латинского алфавита. Рекомендуем передавать двухбуквенный ISO код штата/региона. |
Optional | payerAccount |
String [1..32] | Номер счета отправителя. |
Необязательно | payerLastName |
String [1..64] | Фамилия отправителя. |
Необязательно | payerFirstName |
String [1..35] | Имя отправителя. |
Необязательно | payerMiddleName |
String [1..35] | Отчество отправителя. |
Необязательно | payerCombinedName |
String [1..99] | Полное имя отправителя. |
Необязательно | payerIdType |
String [1..8] | Тип предоставленного идентифицирующего документа отправителя. Возможные значения:
|
Необязательно | payerIdNumber |
String [1..99] | Номер предоставленного идентифицирующего документа отправителя. |
Необязательно | payerBirthday |
String [1..20] | Дата рождения отправителя в формате YYYYMMDD. |
Ниже приведены параметры блока billingRecipientData
(данные о получателе).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | recipientCity |
String [0..40] | Код города получателя. Формат ISO 3166-1 alpha-3. Может содержать буквы только латинского алфавита. |
Необязательно | recipientCountry |
String [0..50] | Код страны получателя. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или название страны. Рекомендуем передавать двух/трехбуквенный ISO код страны. |
Необязательно | recipientAddressLine1 |
String [0..50] | Адрес получателя. Может содержать буквы только латинского алфавита. |
Необязательно | recipientPostalCode |
String [0..9] | Почтовый индекс получателя. |
Необязательно | recipientState |
String [0..50] | Код штата получателя. Формат: полное значение кода ISO 3166-2, его часть или наименование штата/региона. Может содержать буквы только латинского алфавита. Рекомендуем передавать двухбуквенный ISO код штата/региона. |
Необязательно | recipientAccount |
String [0..32] | Номер счета получателя. |
Необязательно | recipientLastName |
String [0..64] | Фамилия получателя. |
Необязательно | recipientFirstName |
String [0..35] | Имя получателя. |
Необязательно | recipientMiddleName |
String [0..35] | Отчество получателя. |
Необязательно | recipientCombinedName |
String [0..99] | Полное имя получателя. |
Необязательно | recipientIdType |
String [1..8] | Тип предоставленного идентифицирующего документа получателя. Возможные значения:
|
Необязательно | recipientIdNumber |
String [1..99] | Номер предоставленного идентифицирующего документа получателя. |
Необязательно | recipientBirthday |
String [1..20] | Дата дня рождения получателя в формате YYYYMMDD. |
Блок fromCard
(если списание производится сторонней системой, то этот блок должен отсутствовать) включает в себя следующие параметры:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Условие | bindingId |
String [1..255] | Идентификатор связки, созданной при оплате заказа или использованной для оплаты. Доступно, только если продавцу разрешено создавать связки. Необходимо передать один из следующих наборов параметров: |
Условие | pan |
String [1..19] | Номер карты списания денежных средств. Необходимо передать один из следующих наборов параметров: |
Условие | cvc |
Integer [3] | Код CVC/CVV2 на обратной стороне карты списания. Обязателен, если оплата не проводится по связке и/или у продавца нет разрешения на оплату без CVC. |
Условие | expirationYear |
Integer [4] | Год истечения действия карты списания. Принимаются значения от 2000 до 2200. Необходимо передать один из следующих наборов параметров: |
Условие | expirationMonth |
Integer [2] | Месяц истечения действия карты списания. Доступные значения: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12. Необходимо передать один из следующих наборов параметров: |
Необязательно | cardholderName |
String [1..26] | Имя держателя карты списания. |
Условие | seToken |
String | Зашифрованные данные карты. Обязательно, если используется вместо данных карты. Обязательные параметры для строки seToken: timestamp , UUID , PAN , EXPDATE , MDORDER . Подробнее о генерации seToken см. здесь.Необходимо передать один из следующих наборов параметров: |
Необязательно | threeDsAuthResult |
Object | Блок с данными о результате аутентификации 3 DS с использованием MPI/3DS Server мерчанта. Обязателен для транзакций перевода с карты на карту и AFT с использованием MPI/3DS Server мерчанта. См. вложенные параметры. |
При платежах с использованием токенов (APPLE, SAMSUNG, GOOGLE) вместо данных карты в блоке fromCard
передается:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Условие | vendor |
String | Параметр используется при оплате через токены. В качестве значения передается наименование поставщика платежного сервиса: APPLE , GOOGLE , SAMSUNG .Данный параметр должен передаваться одновременно с параметром paymentToken (значение токена).Данный параметр не может присутствовать одновременно с параметрами: pan , cvc , expiry , bindingId , seToken . |
Условие | paymentToken |
String [1..8192] | Значение токена поставщика, указанного в параметре vendor (APPLE, GOOGLE, SAMSUNG ). Если vendor указан, параметр является обязательным к передаче.Данный параметр не может присутствовать одновременно с параметрами: pan , cvc , expiry , bindingId , seToken . |
Необязательно | decryptedToken |
Boolean | Расшифрованный токен для платежей через вендоров (ApplePay, GooglePay и т. д.). Возможные значения:
Если не передавать этот параметр, то по умолчанию будет считаться, что передано decryptedToken = false . |
Необязательно | protocolVersion |
String | Версия протокола, определенная Google для платежного токена: ECv1 (по умолчанию) или ECv2
|
Ниже перечислены параметры блока threeDsAuthResult
(данные о результате аутентификации 3 DS).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | cavv |
String [0..200] | Значение проверки аутентификации владельца карты. Указан только после оплаты заказа и в случае наличия соответствующего разрешения. |
Необязательно | xid |
String [1..80] | Электронный коммерческий идентификатор транзакции. Указан только после оплаты заказа и в случае наличия соответствующего разрешения. |
Необязательно | eci |
Integer [1..4] | Электронный коммерческий индикатор. Указан только после оплаты заказа и в случае наличия соответствующего разрешения. Ниже приводится расшифровка ECI-кодов.
|
Conditional | authenticationTypeIndicator |
String | Тип аутентификации 3DS. В зависимости от значения ECI. Обязателен для платежей с использованием MPI/3DS Server мерчанта и аутентификации 3DS 2. Допустимые значения:
|
Необязательно | threeDSProtocolVersion |
String | Версия протокола 3DS. Возможные значения: "2.1.0", "2.2.0" для 3DS2. Если в запросе не передается threeDSProtocolVersion , то для авторизации 3D Secure будет использоваться значение по умолчанию (2.1.0 - для 3DS 2). |
Блок toCard
(если зачисление производится сторонней системой, то этот блок должен отсутствовать) включает в себя следующие параметры:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Условие | bindingId |
String [1..255] | Идентификатор связки, созданной при оплате заказа или использованной для оплаты. Доступно, только если продавцу разрешено создавать связки. Необходимо передать один из следующих параметров: |
Условие | pan |
String [1..19] | Номер карты для зачисления денежных средств. Необходимо передать один из следующих параметров: |
Необязательно | expirationYear |
Integer [4] | Год истечения действия карты зачисления. Принимаются значения от 2000 до 2200. |
Необязательно | expirationMonth |
Integer [2] | Месяц истечения действия карты зачисления. Доступные значения: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12. |
Необязательно | cardholderName |
String [1..26] | Имя держателя карты зачисления. |
Условие | seToken |
String | Зашифрованные данные карты. Обязательно, если используется вместо данных карты. Обязательные параметры для строки seToken: timestamp , UUID , PAN , EXPDATE , MDORDER . Подробнее о генерации seToken см. здесь.Необходимо передать один из следующих параметров: |
См. описание | replacementData |
Object | Блок данных для замены места назначения перевода в AFT транзакциях. Он содержит номер карты и номер транзитного счета получателя. Некоторые платежные системы требуют передачи этих данных в AFT транзакциях, т.е. эти данные используются для аутентификации на ACS во время 3DS авторизации. Для использования этого блока мерчанту необходимо иметь специальное разрешение (уточните у команды поддержки). См. вложенные параметры. |
Ниже перечислены параметры блока replacementData
(данные для замены места назначения в AFT транзакциях):
Required | Name | Type | Description |
---|---|---|---|
Необязательно | card | String [1..19] | Номер карты получателя, если он известен в момент перевода. |
Необязательно | account | String [1..30] | Номер транзитного счета (любой номер, переданный банком). |
При аутентификации по протоколу 3DS 2.0 также передаются следующие параметры:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | threeDSServerTransId |
String [1..36] | Идентификатор транзакции, созданный на сервере 3DS. |
Необязательно | threeDSVer2FinishUrl |
String [1..512] | URL-адрес, по которому клиент должен быть перенаправлен после аутентификации на сервере ACS. |
Необязательно | threeDSMethodNotificationUrl |
String [1..512] | URL-адрес для отправки уведомления о прохождении проверки на ACS. |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | errorCode |
Integer [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Необязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Необязательно | info |
String | Результат попытки перевода средств. Значение в случае успешного перевода: "Ваш платеж обработан, происходит переадресация..." Значение в случае ошибки: "Происходит переадресация..." |
Необязательно | acsUrl |
String [1..512] | При успешном ответе в случае оплаты 3D-Secure. URL-адрес для редиректа на ACS. Обязательный, если нужен редирект на ACS. Подробнее см. Редирект на ACS. |
Необязательно | paReq |
String [1..255] | При успешном ответе в случае оплаты 3D-Secure. PAReq (Payment Authentication Request) — сообщение, которое необходимо отправить в ACS вместе с редиректом. Это сообщение содержит данные в кодировке Base64, необходимые для аутентификации держателя карты. Подробнее см. Редирект на ACS. |
Необязательно | termUrl |
String [1..512] | При успешном ответе в случае оплаты 3D-Secure. URL-адрес для перенаправления клиента после взаимодействия с ACS для завершения платежа. |
При аутентификации по протоколу 3DS 2.0 в ответ на первый запрос приходят следующие параметры:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | is3DSVer2 |
Boolean | Возможные значения: true или false Флаг, показывающий, что платеж поступает из 3DS 2.0. |
Обязательно | threeDSServerTransId |
String [1..36] | Идентификатор транзакции, созданный на сервере 3DS. |
Необязательно | threeDSMethodUrl |
String [1..512] | URL-адрес сервера ACS для сбора данных браузера. |
Обязательно | threeDSMethodUrlServer |
String [1..512] | URL-адрес сервера 3DS для сбора данных браузера, которые будут включены в AReq (Authentication Request) с сервера 3DS на сервер ACS. |
Необязательно | threeDSMethodDataPacked |
String [1..1024] | Данные CReq (Challenge Response) в кодировке Base-64 для отправки на сервер ACS. |
Необязательно | threeDSMethodURLServerDirect |
String [1..512] | URL-адрес 3dsmethod.do для выполнения метода 3DS на сервере 3DS через платежный шлюз (при наличии соответствующего разрешения на уровне продавца). |
Ниже приведены параметры, которые должны присутствовать в ответе, после повторного запроса платежа и необходимости перенаправления клиента в ACS при аутентификации по протоколу 3DS 2.0:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Условие | acsUrl |
String [1..512] | При успешном ответе в случае оплаты 3D-Secure. URL-адрес для редиректа на ACS. Обязательный, если нужен редирект на ACS. Подробнее см. Редирект на ACS. |
Условие | packedCReq |
String | Запакованные данные challenge request. Обязательный, если нужен редирект на ACS. Это значение следует использовать как значение параметра creq ссылки на ACS (acsUrl ), для перенаправления клиента на ACS. |
Для завершения транзакции используйте метод /p2p/finishThreeDsVer2.do.
Примеры
Пример первого запроса в случае аутентификации по протоколу 3DS 2.0
curl -X POST 'https://3dsec.berekebank.kz/payment/rest/api/p2p/performP2P.do'
-H 'Content-Type: application/json'
--data-raw '{
"username":"test_user",
"password":"test_user_password",
"orderId": "0a4eaae8-653a-71a9-8259-46fc00a8ea58",
"amount" : "50000",
"fromCard": {
"vendor": "APPLE",
"paymentToken": "eyJkZXZpY2VNYW51ZmFjdHVyZXJJZGVudGlmaWVyIjoiMDUwMTEwMDMwMjczIiwiY3VycmVuY3lDb2RlIjoiOTc4IiwiYXBwbGljYXRpb25FeHBpcmF0aW9uRGF0ZSI6IjI3MDEzMSIsInBheW1lbnREYXRhIjp7Im9ubGluZVBheW1lbnRDcnlwdG9ncmFtIjoiQUc5WW5Pak1YOUJXQUFSaElJOFBBb0FCRkE9PSJ9LCJwYXltZW50RGF0YVR5cGUiOiIzRFNlY3VyZSIsInRyYW5zYWN0aW9uQW1vdW50IjoxMDAsImFwcGxpY2F0aW9uUHJpbWFyeUFjY291bnROdW1iZXIiOiI1NTU1NTU1NTU1NTU1NTk5In0=",
"decryptedToken":true,
"protocolVersion":"ECv1"
},
"toCard" : {
"pan" : "4111111111111111"
},
"params" : [
{"name" : "recipientName", "Name" : "Surname"},
{"name" : "payerName", "value" : "Name1 Surname1"},
{"name" : "payerCity", "value" : "City"},
{"name" : "payerCountry", "value" : "Country"},
{"name" : "payerPostalCode", "value" : "777777"},
{"name" : "payerState", "value" : "State"},
{"name" : "payerAddress", "value" : "street, 18"]
},
}'
Пример второго запроса в случае аутентификации по протоколу 3DS 2.0
curl -X POST 'https://3dsec.berekebank.kz/payment/rest/api/p2p/performP2P.do'
-H 'Content-Type: application/json'
--data-raw '{
"username":"test_user",
"password":"test_user_password",
"orderId": "0a4eaae8-653a-71a9-8259-46fc00a8ea58",
"fromCard": {
"cardholderName": "TEST CARDHOLDER",
"cvc": "123",
"expirationMonth": 12,
"expirationYear": 2030,
"pan": "5000001111111115"
},
"toCard": {
"pan": "4000001111111118"
},
"amount" : 50000,
"params" : [
{"name" : "recipientName", "Name" : "Surname"},
{"name" : "payerName", "value" : "Name1 Surname1"},
{"name" : "payerCity", "value" : "City"},
{"name" : "payerCountry", "value" : "Country"},
{"name" : "payerPostalCode", "value" : "777777"},
{"name" : "payerState", "value" : "State"},
{"name" : "payerAddress", "value" : "street, 18"
"threeDSServerTransId" : "3afc168a-94b4-4eb3-8e2e-80f6c186669d",
"threeDSVer2FinishUrl" : "https://example.com/acs2/acs/3dsMethod"
}'
Пример запроса AFT перевода
curl -X POST 'https://3dsec.berekebank.kz/payment/rest/api/p2p/performP2P.do'
-H 'Content-Type: application/json'
--data-raw '{
"username": "test_user",
"password": "test_user_password",
"orderId": "0a4eaae8-653a-71a9-8259-46fc00a8ea58",
"fromCard": {
"cardholderName": "TEST CARDHOLDER",
"cvc": "123",
"expirationMonth": 12,
"expirationYear": 2030,
"pan": "5000001111111115"
},
"toCard": {
"replacementData": {
"card": "4111111111111111",
"account": "A044039940702810010192938471"
}
},
"amountInput": "1000025",
"type": "STANDARD"
}'
Пример ответа на первый запрос в случае аутентификации по протоколу 3DS 2.0
{
"errorCode": 0,
"is3DSVer2": true,
"threeDSServerTransId": "3afc168a-94b4-4eb3-8e2e-80f6c186669d",
"threeDSMethodURL": "https://example.com/acs2/acs/3dsMethod",
"threeDSMethodURLServer": "https://example.com/3dsserver/api/v1/client/gather?threeDSServerTransID=3afc168a-94b4-4eb3-8e2e-80f6c186669d",
"threeDSMethodDataPacked": "eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoiaHR0cHM6Ly9hY3F1aXJlci5jb20vM2Rzc2VydmVyL2FwaS92MS9hY3Mvbm90aWZpY2F0aW9uP3RocmVlRFNTZXJ2ZXJUcmFuc0lEPTNhZmMxNjhhLTk0YjQtNGViMy04ZTJlLTgwZjZjMTg2NjY5ZCIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiM2FmYzE2OGEtOTRiNC00ZWIzLThlMmUtODBmNmMxODY2NjlkIn0="
}
Пример ответа на второй запрос в случае аутентификации по протоколу 3DS 2.0
{
"errorCode": 0,
"info": "Your order is proceeded, redirecting...",
"acsUrl": "https://example.com/acs2/acs/creq",
"is3DSVer2": true,
"packedCReq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNhZmMxNjhhLTk0YjQtNGViMy04ZTJlLTgwZjZjMTg2NjY5ZCIsIm1lc3NhZ2VUeXBlIjoiQ1JlcSIsIm1lc3NhZ2VWZXJzaW9uIjoiMi4xLjAiLCJhY3NUcmFuc0lEIjoiOWM3NTkxMmEtZTg0NC00ODgyLWI5YzctYzZmYmMzNjIyNGQ3IiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0"
}
P2P перевод по связке
Чтобы выполнить перевод с карты на карту с помощью связки, используйте запрос https://3dsec.berekebank.kz/payment/rest/api/p2p/performP2PByBinding.do
.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/json
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | username |
String [1..100] | Логин учетной записи API продавца. |
Обязательно | password |
String [1..200] | Пароль учетной записи API продавца. |
Необязательно | language |
String [2] | Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: ru, en. |
Необязательно | ip |
String [1..39] | IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов). |
Необязательно | email |
String [1..40] | Электронная почта для отображения на платежной странице. Если для продавца настроены уведомления клиента, электронную почту необходимо указать. Пример: client_mail@email.com . Для платежей по VISA с 3DS авторизацией необходимо указать либо электронную почту, либо номер телефона владельца карты. |
Необязательно | type |
String | В случае денежного перевода с данными только по одной карте необходимо передать в этом параметре соответствующее значение:
|
Обязательно | orderId |
String [1..36] | Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. |
Необязательно | amountInput |
Integer [0..12] | Сумма перевода в минимальных единицах валюты (например, в копейках). Если в этом параметре указана сумма, перевод будет осуществлен на эту сумму (независимо от суммы, переданной в запросе на оформление заказа). |
Необязательно | params |
Object | Поля дополнительной информации для последующего хранения, передаются в следующем виде: {"param":"value","param2":"value2"} .Данные поля могут быть переданы в процессинг банка для последующего отображения в реестрах банка. По умолчанию передаются orderNumber (номер заказа) и orderDescription (описание заказа).orderDescription не должно превышать 99 символов, не используйте следующие символы: % , + , возврат каретки \r и перевод строки \n ).Чтобы включить эту функциональность, обратитесь в банк. В объекте params запроса на перевод денег с карты на карту могут быть переданы следующие данные клиента (формат значений зависит от используемого метода обработки данных):
params следующую информацию (формат значений определяется используемым методом обработки данных):
При необходимости обратитесь в команду поддержки для указания постоянных значений параметров payer* и recipientName , чтобы не передавать их каждый раз во всех запросах. |
Условие | fromCard |
Object | Блок с атрибутами карты списания. Если списание производится сторонней системой, этот блок должен отсутствовать. В иных случаях он обязателен. См. вложенные параметры. |
Условие | toCard |
Object | Блок с атриубутами карты начисления. Если начисление производится сторонней системой, этот блок должен отсутствовать. В иных случаях он обязателен. См. вложенные параметры. |
Необязательно | shippingPayerData |
Object | Объект, содержащий данные о доставке клиенту. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | preOrderPayerData |
Object | Объект, содержащий данные предварительного заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | orderPayerData |
Object | Объект, содержащий данные о плательщике заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры. |
Необязательно | billingAndShippingAddressMatchIndicator |
String [1] | Индикатор соответствия платежного адреса владельца карты и адреса доставки. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. Возможные значения:
|
Необязательно | billingPayerData |
Object | Блок с регистрационными данными клиента (адрес, почтовый индекс), необходимый для прохождения проверки адреса в рамках сервисов AVS/AVV. Обязателен, если функция включена для продавца на стороне Платежного шлюза. См. вложенные параметры. |
Необязательно | billingRecipientData |
Object | Блок данных о получателе. Обязателен, если функция включена для продавца на стороне Платежного шлюза. См. вложенные параметры. |
Блок fromCard
(если списание производится сторонней системой, то этот блок должен отсутствовать) включает в себя следующие параметры:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Условие | bindingId |
String [1..255] | Идентификатор связки, созданной при оплате заказа или использованной для оплаты. Доступно, только если продавцу разрешено создавать связки. Необходимо передать один из следующих наборов параметров: |
Условие | pan |
String [1..19] | Номер карты списания денежных средств. Необходимо передать один из следующих наборов параметров: |
Условие | cvc |
Integer [3] | Код CVC/CVV2 на обратной стороне карты списания. Обязателен, если оплата не проводится по связке и/или у продавца нет разрешения на оплату без CVC. |
Условие | expirationYear |
Integer [4] | Год истечения действия карты списания. Принимаются значения от 2000 до 2200. Необходимо передать один из следующих наборов параметров: |
Условие | expirationMonth |
Integer [2] | Месяц истечения действия карты списания. Доступные значения: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12. Необходимо передать один из следующих наборов параметров: |
Необязательно | cardholderName |
String [1..26] | Имя держателя карты списания. |
Условие | seToken |
String [1..8192] | Зашифрованные данные карты. Обязательно, если используется вместо данных карты. Обязательные параметры для строки seToken: timestamp , UUID , bindingId , MDORDER . Подробнее о генерации seToken см. здесь.Необходимо передать один из следующих наборов параметров: |
Блок toCard
(если зачисление производится сторонней системой, то этот блок должен отсутствовать) включает в себя следующие параметры:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Условие | bindingId |
String [1..255] | Идентификатор связки, созданной при оплате заказа или использованной для оплаты. Доступно, только если продавцу разрешено создавать связки. Необходимо передать один из следующих параметров: |
Условие | pan |
String [1..19] | Номер карты для зачисления денежных средств. Необходимо передать один из следующих параметров: |
Необязательно | expirationYear |
Integer [4] | Год истечения действия карты зачисления. Принимаются значения от 2000 до 2200. |
Необязательно | expirationMonth |
Integer [2] | Месяц истечения действия карты зачисления. Доступные значения: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12. |
Необязательно | cardholderName |
String [1..26] | Имя держателя карты зачисления. |
Условие | seToken |
String | Зашифрованные данные карты. Обязательно, если используется вместо данных карты. Обязательные параметры для строки seToken: timestamp , UUID , PAN , EXPDATE , MDORDER . Подробнее о генерации seToken см. здесь.Необходимо передать один из следующих параметров: |
Описание параметров объекта shippingPayerData
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | shippingCity |
String [1..50] | Город заказчика (из адреса доставки) |
Необязательно | shippingCountry |
String [1..50] | Страна заказчика |
Необязательно | shippingAddressLine1 |
String [1..50] | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingAddressLine2 |
String [1..50] | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingAddressLine3 |
String [1..50] | Основной адрес клиента (из адреса доставки) |
Необязательно | shippingPostalCode |
String [1..16] | Почтовый индекс клиента для доставки |
Необязательно | shippingState |
String [1..50] | Штат/регион покупателя (из адреса доставки) |
Необязательно | shippingMethodIndicator |
Integer [2] | Индикатор способа доставки. Возможные значения:
|
Необязательно | deliveryTimeframe |
Integer [2] | Срок поставки товара. Возможные значения:
|
Необязательно | deliveryEmail |
String [1..254] | Целевой адрес электронной почты для доставки цифрового распространения. Предпочтительно передавать электронную почту в самостоятельном параметре запроса email (но если вы передадите его в этом блоке, к нему применятся те же правила). |
Описание параметров объекта preOrderPayerData
:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | preOrderDate |
String [10] | Ожидаемая дата доставки (для предзаказанных покупок) в формате ГГГГММДД. |
Необязательно | preOrderPurchaseInd |
Integer [2] | Индикатор размещения клиентом заказа на доступную или будущую доставку. Возможные значения:
|
Необязательно | reorderItemsInd |
Integer [2] | Индикатор того, что клиент перебронирует ранее оплаченную доставку в составе нового заказа. Возможные значения:
|
Описание параметров объекта orderPayerData
.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | homePhone |
String [7..15] | Домашний телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | workPhone |
String [7..15] | Рабочий телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
|
Необязательно | mobilePhone |
String [7..15] | Номер мобильного телефона владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
Для платежей по VISA с 3DS авторизацией необходимо указать либо электронную почту, либо номер телефона владельца карты. Если у вас настроено отображение номера телефона на платежной странице и вы указали неверный номер телефона, клиент сможет исправить его на платежной странице. |
Ниже приведены параметры блока billingPayerData
(данные об адресе регистрации клиента).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | billingCity |
String [0..50] | Город, зарегистрированный по конкретной карте у Банка Эмитента. |
Необязательно | billingCountry |
String [0..50] | Страна, зарегистрированная по конкретной карте банка-эмитента. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или наименование страны. Рекомендуем передавать двух/трехбуквенный ISO код страны. |
Необязательно | billingAddressLine1 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 1. Обязательно к передаче для AVS-проверки. |
Необязательно | billingAddressLine2 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 2. |
Необязательно | billingAddressLine3 |
String [0..50] | Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 3. |
Необязательно | billingPostalCode |
String [0..9] | Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно к передаче для AVS-проверки. |
Необязательно | billingState |
String [0..50] | Штат, зарегистрированный по конкретной карте у Банка Эмитента. Формат: полное значение кода ISO 3166-2, его часть или наименование штата/региона. Может содержать буквы только латинского алфавита. Рекомендуем передавать двухбуквенный ISO код штата/региона. |
Optional | payerAccount |
String [1..32] | Номер счета отправителя. |
Необязательно | payerLastName |
String [1..64] | Фамилия отправителя. |
Необязательно | payerFirstName |
String [1..35] | Имя отправителя. |
Необязательно | payerMiddleName |
String [1..35] | Отчество отправителя. |
Необязательно | payerCombinedName |
String [1..99] | Полное имя отправителя. |
Необязательно | payerIdType |
String [1..8] | Тип предоставленного идентифицирующего документа отправителя. Возможные значения:
|
Необязательно | payerIdNumber |
String [1..99] | Номер предоставленного идентифицирующего документа отправителя. |
Необязательно | payerBirthday |
String [1..20] | Дата рождения отправителя в формате YYYYMMDD. |
Ниже приведены параметры блока billingRecipientData
(данные о получателе).
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | recipientCity |
String [0..40] | Код города получателя. Формат ISO 3166-1 alpha-3. Может содержать буквы только латинского алфавита. |
Необязательно | recipientCountry |
String [0..50] | Код страны получателя. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или название страны. Рекомендуем передавать двух/трехбуквенный ISO код страны. |
Необязательно | recipientAddressLine1 |
String [0..50] | Адрес получателя. Может содержать буквы только латинского алфавита. |
Необязательно | recipientPostalCode |
String [0..9] | Почтовый индекс получателя. |
Необязательно | recipientState |
String [0..50] | Код штата получателя. Формат: полное значение кода ISO 3166-2, его часть или наименование штата/региона. Может содержать буквы только латинского алфавита. Рекомендуем передавать двухбуквенный ISO код штата/региона. |
Необязательно | recipientAccount |
String [0..32] | Номер счета получателя. |
Необязательно | recipientLastName |
String [0..64] | Фамилия получателя. |
Необязательно | recipientFirstName |
String [0..35] | Имя получателя. |
Необязательно | recipientMiddleName |
String [0..35] | Отчество получателя. |
Необязательно | recipientCombinedName |
String [0..99] | Полное имя получателя. |
Необязательно | recipientIdType |
String [1..8] | Тип предоставленного идентифицирующего документа получателя. Возможные значения:
|
Необязательно | recipientIdNumber |
String [1..99] | Номер предоставленного идентифицирующего документа получателя. |
Необязательно | recipientBirthday |
String [1..20] | Дата дня рождения получателя в формате YYYYMMDD. |
При аутентификации по протоколу 3DS 2.0 также передаются следующие параметры:
Обязательно | Название | Тип | Описание |
---|---|---|---|
Необязательно | threeDSServerTransId |
String [1..36] | Идентификатор транзакции, созданный на сервере 3DS. |
Необязательно | threeDSVer2FinishUrl |
String [1..512] | URL-адрес, по которому клиент должен быть перенаправлен после аутентификации на сервере ACS. |
Необязательно | threeDSMethodNotificationUrl |
String [1..512] | URL-адрес для отправки уведомления о прохождении проверки на ACS. |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | errorCode |
Integer [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Обязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Необязательно | info |
String | Результат попытки перевода средств. Значение в случае успешного перевода: "Ваш платеж обработан, происходит переадресация..." Значение в случае ошибки: "Происходит переадресация..." |
Необязательно | acsUrl |
String [1..512] | При успешном ответе в случае оплаты 3D-Secure. URL-адрес для редиректа на ACS. Обязательный, если нужен редирект на ACS. Подробнее см. Редирект на ACS. |
Необязательно | paReq |
String [1..255] | При успешном ответе в случае оплаты 3D-Secure. PAReq (Payment Authentication Request) — сообщение, которое необходимо отправить в ACS вместе с редиректом. Это сообщение содержит данные в кодировке Base64, необходимые для аутентификации держателя карты. Подробнее см. Редирект на ACS. |
Необязательно | termUrl |
String [1..512] | При успешном ответе в случае оплаты 3D-Secure. Это URL-адрес, на который ACS перенаправляет владельца карты после аутентификации. Подробнее см. Редирект на ACS. |
При аутентификации по протоколу 3DS 2.0 в ответ на первый запрос приходят следующие параметры:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | is3DSVer2 |
Boolean | Возможные значения: true или false Флаг, показывающий, что платеж поступает из 3DS 2.0. |
Обязательно | threeDSServerTransId |
String [1..36] | Идентификатор транзакции, созданный на сервере 3DS. |
Необязательно | threeDSMethodUrl |
String [1..512] | URL-адрес сервера ACS для сбора данных браузера. |
Обязательно | threeDSMethodUrlServer |
String [1..512] | URL-адрес сервера 3DS для сбора данных браузера, которые будут включены в AReq (Authentication Request) с сервера 3DS на сервер ACS. |
Необязательно | threeDSMethodDataPacked |
String [1..1024] | Данные CReq (Challenge Response) в кодировке Base-64 для отправки на сервер ACS. |
Необязательно | threeDSMethodURLServerDirect |
String [1..512] | URL-адрес 3dsmethod.do для выполнения метода 3DS на сервере 3DS через платежный шлюз (при наличии соответствующего разрешения на уровне продавца). |
Ниже приведены параметры, которые должны присутствовать в ответе, после повторного запроса платежа и необходимости перенаправления клиента в ACS при аутентификации по протоколу 3DS 2.0:
Обязательность | Название | Тип | Описание |
---|---|---|---|
Условие | acsUrl |
String [1..512] | При успешном ответе в случае оплаты 3D-Secure. URL-адрес для редиректа на ACS. Обязательный, если нужен редирект на ACS. Подробнее см. Редирект на ACS. |
Условие | packedCReq |
String | Запакованные данные challenge request. Обязательный, если нужен редирект на ACS. Это значение следует использовать как значение параметра creq ссылки на ACS (acsUrl ), для перенаправления клиента на ACS. |
Примеры
Пример запроса
curl -X POST 'https://3dsec.berekebank.kz/payment/rest/api/p2p/performP2PByBinding.do'
-H 'Content-Type: application/json'
--data-raw '{
"amountInput" : 1000,
"fromCard" : {
"seToken": "ofVx1r3aIJ3Mlx3nkfeOIJgFOnwfsgFK+V6Yzm+KxJgsq19l74GChhX0We/LEFq78Rhn9uFAEZGdeyDhnIc/KfuvObf0EzoDA65Uj1Z8FjwWyjnEwTBHZL4KmdFBCSk8jLxHt70mXwyjiHYyCVH1fT/UVOnsrkZVGrqmEG4MTi5dX9Znzf24DwRg4iezvdT8vf0dUW5lJdvY1tgOsOnBulwy6kH/YbHVsnR6yxO6d6IsdnT5f8PxaB+7ZyUqgrd6VA88FGJKJgdoxk4721pqKSG5dYroLJG96s23EDJ2Hpi4e9wU2rP7E6dlFw+qzATqX/eaJbaQ9eakkdMWnkj7aQ=="
},
"toCard": {
"cardholderName": "IVAN IVANOV",
"cvc": "123",
"expirationMonth": 12,
"expirationYear": 2024,
"pan": "5555555555555599"
},
"orderId" : "3dbaf8bb-1d68-76b3-b4e6-784700f26b04",
"password" : "test_user_password",
"type" : "WITHOUT_TO_CARD",
"username" : "test_user"
}'
Пример первого запроса в случае аутентификации по протоколу 3DS 2.0
curl -X POST 'https://3dsec.berekebank.kz/payment/rest/api/p2p/performP2PByBinding.do'
-H 'Content-Type: application/json'
--data-raw '{
"amountInput" : 1000,
"currency" : "398",
"fromCard" : {
"bindingId" : "fd3afc57-c6d0-4e08-aaef-1b7cfeb093dc"
},
"orderId" : "38b7a9e0-7cfa-46f7-8655-f206a8898e7a",
"password" : "test_user_password",
"type" : "WITHOUT_TO_CARD",
"username" : "test_user",
"params" : {
"name" : "payerAddress",
"value" : "payer Address"
}
}'
Пример второго запроса в случае аутентификации по протоколу 3DS 2.0
curl -X POST 'https://3dsec.berekebank.kz/payment/rest/api/p2p/performP2PByBinding.do'
-H 'Content-Type: application/json'
--data-raw '{
"amountInput" : 1000,
"currency" : "398",
"fromCard" : {
"bindingId" : "fd3afc57-c6d0-4e08-aaef-1b7cfeb093dc"
},
"orderId" : "38b7a9e0-7cfa-46f7-8655-f206a8898e7a",
"password" : "test_user_password",
"type" : "WITHOUT_TO_CARD",
"username" : "test_user",
"params" : {
"name" : "payerAddress",
"value" : "payer Address"
},
"threeDSServerTransId" : "f44d6d21-1874-45a5-aeb0-1c710dd6e134",
"threeDSVer2FinishUrl" : "https://example.com/acs2/acs/3dsMethod"
}'
Пример ответа
{
"errorCode" : 0,
"errorMessage" : "Successful",
"info" : "Your order is proceeded, redirecting...",
"redirect" : "https://example.com/?orderId=47743354-be15-7c70-b9ef-4bfc482e68dc&lang=en",
"is3DSVer2" : false
}
Пример ответа на первый запрос в случае аутентификации по протоколу 3DS 2.0
{
"errorCode": 0,
"is3DSVer2": true,
"threeDSServerTransId": "f44d6d21-1874-45a5-aeb0-1c710dd6e134",
"threeDSMethodURLServer": "https://example.com/3dsserver/api/v1/client/gather?threeDSServerTransID=f44d6d21-1874-45a5-aeb0-1c710dd6e134",
}
Пример ответа на второй запрос в случае аутентификации по протоколу 3DS 2.0
{
"errorCode": 0,
"info": "Your order is proceeded, redirecting...",
"acsUrl": "https://example.com/acs2/acs/creq",
"is3DSVer2": true,
"packedCReq" : "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjVmMzEyMjdlLTljZmQtNDQwYi1hNDNjLTE4NjljMzNhNGI5YiIsImFjc1RyYW5zSUQiOiI5YTQyYzQ4ZC1hNWRiLTQ3NjEtYmI4Mi05ZmY5MmM0NzZiM2QiLCJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDQiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0="
}
Статус P2P перевода
Чтобы получить статус зарегистрированного заказа P2P, используйте запрос https://3dsec.berekebank.kz/payment/rest/api/p2p/getP2PStatus.do
.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/json
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | username |
String [1..100] | Логин учетной записи API продавца. |
Обязательно | password |
String [1..200] | Пароль учетной записи API продавца. |
Необязательно | language |
String [2] | Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина. Поддерживаемые языки: ru, en. |
Условие | orderId |
String [1..36] | Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза. |
Условие | orderNumber |
String [1..36] | Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа. |
Параметры ответа
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | errorCode |
Integer [1..2] | Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
|
Обязательно | errorMessage |
String [1..512] | Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде. Язык описания задается в параметре language запроса. |
Необязательно | orderStatus |
Integer | Значение этого параметра указывает статус заказа в платежном шлюзе. Отсутствует, если заказ не был найден. Ниже приведен список доступных значений:
|
Необязательно | orderNumber |
String [1..36] | Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа. |
Необязательно | panMaskedFrom |
String [1..19] | Маскированный номер карты для списания средств. |
Необязательно | panMaskedTo |
String [1..19] | Маскированный номер карты для зачисления средств. |
Необязательно | amount |
Integer [0..12] | Сумма платежа в минимальных единицах валюты (например, в копейках). |
Необязательно | currency |
Integer [3] | Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию. |
Необязательно | creationDate |
Integer | Дата регистрации заказа. |
Необязательно | orderDescription |
String [1..600] | Описание заказа передаваемое платежному шлюзу при регистрации. В этом поле недопустимо передавать персональные данные или платежные данные (номера карт т.п.). Данное требование связано с тем, что описание заказа нигде не маскируется. |
Необязательно | ip |
String [1..39] | IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов). |
Обязательно | resultCode |
Integer | Код ошибки при выполнении запроса. Возможные значения:
|
Необязательно | orderParams |
Object | Объект с атрибутами продавца. В ответе может быть представлено более одного блока orderParams .Объект должен передаваться следующим образом: {"param":"value","param2":"value2"} . |
Необязательно | operationList |
Object | Объект, содержащий информацию о транзакциях, завершенных в заказе. В ответе может присутствовать более одного блока operationList .Параметры, которые можно передать, описаны ниже. |
Необязательно | binding |
String | Идентификатор связки (если она уже была создана). Этот параметр возвращается, только если версия getP2PStatus равна 3 или выше. |
Ниже приведены возможные параметры блока operationList
.
Обязательность | Название | Тип | Описание |
---|---|---|---|
Необязательно | operationType |
String | Тип транзакции. Доступны следующие значения:
|
Необязательно | amount |
Integer [0..12] | Сумма платежа в минимальных единицах валюты (например, в копейках). |
Необязательно | currency |
Integer [3] | Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию. |
Необязательно | datetime |
String | Дата и время совершения операции. |
Необязательно | resultCode |
Integer | Код ошибки при выполнении запроса. Возможные значения:
|
Необязательно | resultCodeDescription |
String [1..512] | Описание кода ошибки транзакции. |
Необязательно | maskedPan |
String [1..19] | Маскированный номер карты или токена, использованного для оплаты. |
Необязательно | cardholderName |
String [1..26] | Имя держателя карты (при наличии). |
Необязательно | refNum |
String [12] | Уникальный идентификационный номер, который присваивается операции по ее завершению. |
Примеры
Пример запроса
curl -X POST 'https://3dsec.berekebank.kz/payment/rest/api/p2p/getP2PStatus.do'
-H 'Content-Type: application/json'
--data-raw '{
"username": "test_user",
"password": "test_user_password",
"orderId" : "0a4eaae8-653a-71a9-8259-46fc00a8ea58"
}'
Пример ответа
{
"orderStatus": 0,
"errorCode": 0,
"errorMessage": "Successful",
"orderNumber": "2009",
"amount": 50000,
"currency": "398",
"creationDate": 1674137044330,
"orderParams": [],
"operationList": [],
"resultCode": 0
}
Завершение P2P-транзакции 3DS2 через API
Чтобы завершить P2P-транзакцию, продавец отправляет идентификатор транзакции на шлюз, используя метод https://3dsec.berekebank.kz/payment/rest/api/p2p/finishThreeDsVer2.do
.
При выполнении запроса необходимо использовать заголовок:
Content-Type: application/x-www-form-urlencoded
Параметры запроса
Обязательность | Название | Тип | Описание |
---|---|---|---|
Обязательно | username |
String [1..100] | Логин учетной записи API продавца. |
Обязательно | password |
String [1..200] | Пароль учетной записи API продавца. |
Обязательно | tDsTransId |
String [1..36] | Уникальный идентификатор транзакции, полученный от сервера 3DS. |
Параметры ответа
Ответ на этот запрос не содержит никаких параметров JSON. Вместо этого он перенаправляет клиента на один из следующих URL-адресов:
- Если обработка запроса прошла успешно, платежный шлюз перенаправляет клиента на URL-адрес, указанный в параметре
returnUrl
при регистрации заказа, с добавленными параметрамиorderId
иlang
; - Если обработка запроса прошла неуспешно, платежный шлюз перенаправляет клиента на URL-адрес, указанный в параметре
failUrl
при регистрации заказа, с добавленными параметрамиorderId
иlang
.
Примеры
Пример запроса
curl --request POST \
--url https://3dsec.berekebank.kz/payment/rest/api/p2p/finishThreeDsVer2.do \
--header 'content-type: application/x-www-form-urlencoded' \
--data '{
"username": "test_user",
"password": "test_user_password",
"threeDSServerTransId": "65020d0c-2627-4a45-8eab-b93b58fc52ae"
}'
Пример URL редиректа
https://mybestmerchantreturnurl.com/finish.html?orderId=906bf262-bd53-4ac7-983c-07127954681b&lang=en