По любому вопросу мы в одном клике

Задать вопрос
Поиск по ключевым словам
/

P2P-переводы

P2P-транзакция

Функциональность P2P помогает вам предоставить пользователям (текущим или потенциальным клиентам) возможность отправлять деньги друг другу. Также она позволяет принимать переводы на ваши карты, не отправляя никому свои данные, и зарабатывать комиссионные, предоставляя услугу широкому кругу пользователей.

Сервис P2P — это сервис, доступный для для настройки и интеграции со сторонними веб-сайтами, мобильными приложениями, а также интернет- и мобильными банками.

Пользователям доступен полный перечень операций, отправка/получение переводов, регистрация/авторизация в сервисе, управление сохраненными картами.

Важной особенностью сервиса P2P является возможность совершать переводы по номеру телефона, даже если пользователь еще не зарегистрирован в системе.

Существует несколько сценариев реализации P2P-транзакций:

Сценарий проведения P2P операции с вводом платежных данных на стороне платежного шлюза

sequenceDiagram participant C as Клиент participant OS as Интернет-магазин participant PG as Платежный шлюз participant ACS as ACS autonumber C ->> OS: Формирование заказа OS ->> PG: Регистрация заказа PG -->> OS: orderId, formUrl OS -->> C: Перенаправление на форму сбора карточных данных C ->> PG: Получение формы сбора карточных данных PG -->> C: Форма сбора карточных данных C ->> PG: Отправка данных в заполненной форме PG ->> PG: Проверка вовлеченности карты в 3-D Secure PG -->> C: Перенаправление клиента в ACS C ->> ACS: Получение формы авторизации ACS -->> C: Формы авторизации C ->> ACS: Заполнение формы ACS -->> C: Перенаправление клиента в платежный шлюз C ->> PG: Завершение безопасного платежа PG ->> PG: Проведение оплаты PG -->> C: Перенаправление клиента в интернет-магазин C ->> OS: Получение страницы с результатом OS ->> PG: Проверка статуса PG -->> OS: Статус заказа OS -->> C: Отображение результата
  1. На сайте продавца (например, в интернет-магазине) держатель карты запрашивает выполнение денежного перевода P2P.
  2. Система интернет-магазина регистрирует заказ в Платежном шлюзе через registerP2P.do. Используемые параметры регистрации включают сумму перевода, валюту, номер заказа в системе продавца и URL возврата для клиента.
  3. Платежный шлюз в ответ на запрос регистрации возвращает уникальный идентификатор заказа в платежной системе и URL для перенаправления клиента на форму сбора карточных данных.
  4. Система интернет-магазина передает URL-адрес перенаправления, полученный на Шаге 3, браузеру клиента.
  5. Браузер клиента открывает URL-адрес.
  6. По указанному URL браузер клиента получает форму для сбора карточных данных.
  7. Клиент заполняет форму, и данные отправляются на сервер платежного шлюза.
  8. Система проверяет принадлежность карты к 3-D Secure (SecureCode).
  9. Шлюз отправляет ссылку перенаправления на страницу сервера управления доступом (ACS) банка-эмитента в веб-браузер клиента (этот шаг необходим для реализации 3DS).
  10. Веб-браузер клиента запрашивает форму авторизации пользователя из ACS.
  11. ACS отправляет форму авторизации в веб-браузер клиента.
  12. Клиент заполняет форму, и данные отправляются на сервер платежного шлюза.
  13. ACS обрабатывает форму и, независимо от результата, отправляет URL-адрес перенаправления страниц платежного шлюза в веб-браузер клиента. Вместе с этим URL отправляются зашифрованные параметры результата авторизации.
  14. Веб-браузер клиента запрашивает страницу платежного шлюза при передаче зашифрованных параметров результата авторизации.
  15. Платежный шлюз переводит деньги.
  16. Когда деньги переведены, платежный шлюз отправляет обратный URL-адрес в веб-браузер клиента (URL-адрес был указан при регистрации заказа интернет-магазином на Шаге 2).
  17. Веб-браузер клиента запрашивает результаты перевода денег из интернет-магазина.
  18. Система интернет-магазина запрашивает информацию о статусе заказа у платежного шлюза – getP2PStatus.do.
  19. Платежный шлюз возвращает статус заказа.
  20. Система интернет-магазина показывает клиенту результат оплаты.

Сценарий проведения P2P операции с вводом платежных данных на стороне интернет-магазина

sequenceDiagram participant C as Клиент participant OS as Интернет-магазин participant PG as Платежный шлюз participant 3DSS as 3DS Server participant ACS as ACS autonumber C ->> OS: Формирование заказа OS ->> OS: Сбор данных карты OS ->> PG: Регистрация заказа PG -->> OS: Ответ на регистрацию заказа OS ->> PG: Запрос суммы комиссии PG -->> OS: Получение суммы комиссии OS ->> PG: Запрос на перевод с карты на карту PG -> 3DSS: Проверка доступности 3DSv2 PG -->> OS: Ответ на запрос о переводе с карты на карту OS ->> 3DSS: Вызов скрытого iframe (threeDSMethodURLServer) opt [если threeDSMethodURL есть в ответе] OS ->> ACS: Вызов скрытого iframe (threeDSMethodURL) end OS ->> PG: Второй запрос на перевод средств PG ->> 3DSS: Запрос аутентификации 3DSS ->> ACS: Запрос аутентификации ACS -->> 3DSS: Ответ на запрос аутентификации 3DSS -->> PG: Ответ на запрос аутентификации PG -->> OS: Ответ на запрос opt [Требуется перенаправление на ACS] OS ->> ACS: CReq (ChallengeRequest) ACS -->> C: HTML-форма для прохождения аутентификации C ->> ACS: Подтверждение подлинности ACS ->> ACS: Обработка данных ACS -> 3DSS: Обмен данными ACS -->> C: Результат обработки данных и перенаправление клиента на страницу магазина OS ->> PG: finish3dsVer2Payment.do PG -->> OS: Ответ на запрос end OS ->> PG: Запрос статуса заказа PG -->> OS: Ответ на запрос статуса заказа OS -->> C: Отображение результата
  1. Держатель карты (клиент) взаимодействует с интернет-магазином для создания заказа.
  2. Система интернет-магазина собирает данные карты на своей стороне.
  3. Система интернет-магазина регистрирует заказ в Платежном шлюзе через registerP2P.do. Используемые параметры регистрации включают сумму перевода, валюту, номер заказа в системе продавца и URL возврата для клиента.
  4. Платежный шлюз в ответ на запрос регистрации возвращает уникальный идентификатор заказа в платежной системе.
  5. Необязательно. Если интернет-магазин работает с комиссией, интернет-магазин отправляет платежному шлюзу запрос на сумму комиссии через verifyP2P.do / verifyP2PByBinding.do.
  6. Необязательно. Платежный шлюз отправляет в ответ сумму комиссии.
  7. Интернет-магазин отправляет запрос на перевод средств в Платежный шлюз через performP2P.do / performP2PByBinding.do.
    На этом этапе инициируется работа 3DS2.
  8. Платежный шлюз проверяет на сервере 3DS, может ли клиент аутентифицироваться с использованием протокола 2.0.
  9. Платежный шлюз отправляет ответ на запрос, сделанный на Шаге 6. Ответ также возвращает следующие параметры:
    • is3DSVer2 - флаг возможности аутентификации 3DSv2 (true/false)
    • threeDSServerTransId - идентификатор транзакции, присвоенный сервером 3DS
    • threeDSMethodURLServer - адрес сервера 3DS для сбора данных браузера
    • threeDSMethodURL - (необязательно) адрес сервера ACS для сбора данных браузера
    • threeDSMethodDataPacked - (необязательно) данные для сбора данных браузера на ACS

    (См. также описание запроса).
  10. Интернет-магазин вызывает threeDSMethodURLServer в отдельном iframe с помощью метода POST, используя значение, полученное из ответа на запрос на перевод средств. Это позволяет серверу 3DS собирать данные о браузере клиента.
  11. Необязательно. Если в ответе на запрос о переводе средств были получены параметры threeDSMethodURL и threeDSMethodDataPacked, интернет-магазин вызывает в отдельном iframe методом POST threeDSMethodURL.
  12. Перевод средств - этап 2. Интернет-магазин повторно отправляет запрос на выполнение перевода через performP2P.do / performP2PByBinding.do.
    Необъодимо передать параметр threeDSServerTransId - идентификатор транзакции, который был создан сервером 3DS и возвращен на Шаге 10.
  13. Платежный шлюз отправляет запрос на аутентификацию на сервер 3DS.
  14. Сервер 3DS отправляет запрос аутентификации (AReq) на сервер ACS.
  15. Сервер ACS отправляет ответ на запрос аутентификации (ARes) на сервер 3DS.
  16. Сервер 3DS отправляет полученные данные в платежный шлюз.

    • Если клиенту не нужно проходить аутентификацию в ACS, платежный шлюз возвращает ответ на запрос о переводе средств. В этом случае сценарий продолжается с Шага 27.
    • Если клиенту необходимо пройти аутентификацию в ACS, Платежный шлюз отправит ответ на платежную страницу с данными перенаправления на ACS.
  18. Страница оплаты перенаправляется на acsUrl с параметром creq=packedCReq.
  19. ACS отображает страницу аутентификации для клиента (страница challenge).
  20. Клиент аутентифицирован.
  21. Сервер ACS проверяет подлинность данных аутентификации.
  22. Происходит обмен данными между серверами ACS и 3DS и подтверждается результат обработки.
  23. Сервер ACS перенаправляет клиента на страницу магазина.
  24. Интернет-магазин отправляет запрос /p2p/finishThreeDsVer2.do платежному шлюзу.
  25. Платежный шлюз отправляет интернет-магазину ответ на сделанный запрос.
  26. Интернет-магазин отправляет getP2PStatus.do в платежный шлюз, чтобы узнать статус заказа.
  27. Платежный шлюз отправляет ответ на сделанный запрос.
  28. Интернет-магазин отображает страницу результата клиенту.

API-вызовы

Запросы по P2P-транзакциям должны быть подписаны. Информация о подписях запросов доступна в нашем Руководстве по API.

Регистрация заказа P2P

Для оформления заказа на перевод денег с карты на карту используйте запрос https://3dsec.berekebank.kz/payment/rest/api/p2p/registerP2P.do.


При выполнении запроса необходимо использовать заголовок: Content-Type: application/json

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

Обязательность Название Тип Описание
Обязательно

username String [1..30] Логин учетной записи API продавца.
Обязательно

password String [1..30] Пароль учетной записи API продавца.
Обязательно

orderNumber String [1..36] Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа.
Обязательно

amount Integer [0..12] Сумма платежа в минимальных единицах валюты (например, в копейках).
Обязательно

currency String [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,by,kz,kk.
Необязательно

clientId String [0..255] Номер клиента (ID) в системе мерчанта — до 255 символов. Используется для реализации функциональности связок. Может возвращаться в ответе, если мерчанту разрешено создавать связки.
Указание этого параметра при обработке платежей по связке обязательно. В противном случае платеж будет невозможен.
Необязательно

merchantLogin String [1..255] Чтобы зарегистрировать заказ от имени другого мерчанта, укажите его логин (для API-аккаунта) в этом параметре.
Можно использовать, только если у вас есть разрешение на просмотр транзакций других продавцов или если указанный продавец является вашим дочерним продавцом.
Необязательно

dynamicCallbackUrl String [1..512] Параметр для передачи динамического адреса для получения "платежных" callback-уведомлений по заказу, активированных для мерчанта (успешная авторизация, успешное списание, возврат, отмена, отклонение платежа по таймауту, отклонение card present платежа).
"Не платежные" callback-уведомления (включение/выключение связки, создание связки), будут отправляться на статический callback адрес.
Необязательно

sessionTimeoutSecs Integer [1..9] Продолжительность жизни заказа в секундах. В случае если параметр не задан, будет использовано значение, указанное в настройках мерчанта, или время по умолчанию (1200 секунд = 20 минут). Если в запросе присутствует параметр expirationDate, то значение параметра sessionTimeoutSecs не учитывается.
Необязательно

sessionExpiredDate String Дата и время истечения срока действия заказа. Формат: yyyy-MM-ddTHH:mm:ss.
Если этот параметр не передается в запросе, то для определения времени истечения срока действия заказа используется параметр sessionTimeoutSecs.
Необязательно

bindingId String [1..255] Идентификатор уже существующей связки (идентификатор карты, токенизированной шлюзом). Его можно использовать, только если у мерчанта есть разрешение на работу со связками. Если этот параметр передается в этом запросе, это означает, что:
  • Этот заказ можно оплатить только с помощью связки;
  • Плательщик будет перенаправлен на страницу оплаты, где требуется только ввод CVC.
Необязательно

creditBindingId String [0..255] Идентификатор связки карты для зачисления. Используется при переводах с карты на карту, когда заранее известна карта получателя. Этот параметр нужно сначала передать в запросе на регистрацию платежа (registerP2P.do - здесь же должен быть передан параметр clientId), затем в запросе на перевод средств по cвязке (performP2PByBinding.do - значение параметра creditBindingId, переданного в registerP2P.do, должно быть передано в параметре bindingId в блоке toCard).
Обязательно

transactionTypeIndicator String Используется в однонаправленных типах транзакций.
Возможны такие значения:
  • A - Перевод с карты на карту одного владельца (со счета на счет)
  • B - Перевод с целью приобретения криптовалюты
  • C - Перевод для целей покупки криптовалюты
  • D - Выплата средств
  • F - Перевод для ставок по азартным играм
  • G - Выплата в азартных играх онлайн
  • H - Вывод средств (Cash Out). Вывод средств агентом.
  • I - Государственные выплаты
  • J - Денежный перевод, инициированный банком
  • L - Перевод для целей погашения счетов по кредитной карте
  • O - Перевод для целей оплаты задолженности
  • P - Перевод с карты на карту разных владельцев
  • W - Перевод на собственный счет поэтапного цифрового кошелька для оплаты
Обязательно

features Object Контейнер для параметра feature, обязателен для однонаправленных операций.
Если выполняется операция AFT (перевод с карты на счет) - в параметре feature должно быть передано WITHOUT_TO_CARD.
Пример: "features" : { "feature" : ["WITHOUT_TO_CARD"] }
Необязательно

params Object Поля дополнительной информации для последующего хранения, передаются в следующем виде:
"params": [ {"name": "param1", "value": "value1"}, {"name": "param2", "value": "value2"} ].
Данные поля могут быть переданы в процессинг банка для последующего отображения в реестрах банка.
По умолчанию передаются orderNumber (номер заказа) и orderDescription (описание заказа).orderDescription не должно превышать 99 символов, не используйте следующие символы: %, +, возврат каретки \r и перевод строки \n).

Чтобы включить эту функциональность, обратитесь в банк.
Необязательно

feeInput String Размер комиссии в минимальных единицах валюты. Функциональность должна быть включена на уровне продавца в шлюзе. Если для мерчанта выставлено соответствующее разрешение, и он осуществляет операции AFT, комиссия мерчанта поступает в запросе на регистрацию и отправляется в сообщении в процессинг.
  • Если feeInput больше 0, атрибут externalFee будет добавлен в TransactionModel, и при вызове verifyP2P.do запрос на проверку не будет отправлен в процессинг. В запрос в процессинг будут добавлены следующие теги, если они были переданы в дополнительных параметрах запроса на регистрацию: acc_number, contract, fio_sender, reference, fio_reciever.
  • Если feeInput не передан или равен 0, то будет выполнен стандартный запрос registerP2P.do (атрибут externalFee не будет добавлен в TransactionModel, и при вызове verifyP2P.do запрос на проверку будет отправлен в процессинг.
Необязательно shippingPayerData Object Объект, содержащий данные о доставке клиенту. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры.
Необязательно preOrderPayerData Object Объект, содержащий данные предварительного заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры.
Необязательно orderPayerData Object Объект, содержащий данные о плательщике заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры.
Необязательно

billingAndShippingAddressMatchIndicator String [1] Индикатор соответствия платежного адреса владельца карты и адреса доставки. Этот параметр используется для дальнейшей 3DS-аутентификации клиента.
Возможные значения:
  • Y - совпадение платежного адреса держателя карты и адреса доставки;
  • N - платежный адрес владельца карты и адрес доставки не совпадают.
Условие billingPayerData Object Блок с регистрационными данными клиента (адрес, почтовый индекс), необходимый для прохождения проверки адреса в рамках сервисов AVS/AVV. Обязателен, если функция включена для продавца на стороне Платежного шлюза. Должен был включен либо в запрос registerP2P.do, либо в запрос performP2P.do. См. вложенные параметры.
Условие billingRecipientData Object Блок данных о получателе. Обязателен, если функция включена для продавца на стороне Платежного шлюза. Должен был включен либо в запрос registerP2P.do, либо в запрос performP2P.do. См. вложенные параметры.

Описание параметров объекта 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] Индикатор способа доставки.
Возможные значения:
  • 01 - доставка на платежный адрес держателя карты.
  • 02 - доставка на другой адрес, проверенный Мерчантом.
  • 03 - доставка по адресу, отличному от основного адреса держателя карты.
  • 04 - отправка в магазин/самовывоз (адрес магазина должен быть указан в соответствующих параметрах доставки)
  • 05 - Цифровое распространение (включает онлайн-сервисы и электронные подарочные карты)
  • 06 - билеты на путешествия и мероприятия, которые нельзя доставить.
  • 07 - Прочее (например, игры, цифровые товары, не подлежащие доставке, цифровые подписки и т. д.)
Необязательно deliveryTimeframe Integer [2] Срок поставки товара.
Возможные значения:
  • 01 - цифровая дистрибуция
  • 02 - доставка в тот же день
  • 03 - доставка на следующий день
  • 04 - доставка в течение 2-х дней после оплаты и позже.
Необязательно deliveryEmail String [1..254] Целевой адрес электронной почты для доставки цифрового распространения. Предпочтительно передавать электронную почту в самостоятельном параметре запроса email (но если вы передадите его в этом блоке, к нему применятся те же правила).

Описание параметров объекта preOrderPayerData:

Обязательность Название Тип Описание
Необязательно preOrderDate String [10] Ожидаемая дата доставки (для предзаказанных покупок) в формате ГГГГММДД.
Необязательно preOrderPurchaseInd Integer [2] Индикатор размещения клиентом заказа на доступную или будущую доставку.
Возможные значения:
  • 01 - возможна доставка;
  • 02 - будущая доставка
Необязательно reorderItemsInd Integer [2] Индикатор того, что клиент перебронирует ранее оплаченную доставку в составе нового заказа.
Возможные значения:
  • 01 - заказ размещается впервые;
  • 02 - повторный заказ

Описание параметров объекта orderPayerData.

Обязательность Название Тип Описание
Необязательно homePhone String [7..15] Домашний телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
  • +35799988877;
  • 0035799988877;
  • 35799988877.
Необязательно workPhone String [7..15] Рабочий телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
  • +35799988877;
  • 0035799988877;
  • 35799988877.
Необязательно mobilePhone String [7..15] Номер мобильного телефона владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
  • +35799988877;
  • 0035799988877;
  • 35799988877.

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

Ниже приведены параметры блока billingPayerData (данные об адресе регистрации клиента).

Обязательность Название Тип Описание
Условие

billingCity String [0..50] Город, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно для Visa.
Условие

billingCountry String [0..50] Страна, зарегистрированная по конкретной карте банка-эмитента. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или наименование страны. Рекомендуем передавать двух/трехбуквенный ISO код страны. Обязательно для Visa.
Условие

billingAddressLine1 String [0..50] Адрес, зарегистрированный по конкретной карте у Банка Эмитента (адрес плательщика). Строка 1. Обязательно к передаче для AVS-проверки. Обязательно для Visa.
Необязательно

billingAddressLine2 String [0..50] Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 2.
Необязательно

billingAddressLine3 String [0..50] Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 3.
Необязательно

billingPostalCode String [0..9] Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно к передаче для AVS-проверки.
Необязательно

billingState String [0..50] Штат, зарегистрированный по конкретной карте у Банка Эмитента. Формат: полное значение кода ISO 3166-2, его часть или наименование штата/региона. Может содержать буквы только латинского алфавита. Рекомендуем передавать двухбуквенный ISO код штата/региона.
Обязательно

payerAccount String [1..32] Номер счета отправителя.
Условие

payerLastName String [1..64] Фамилия отправителя. Обязательно для Visa.
Условие

payerFirstName String [1..35] Имя отправителя. Обязательно для Visa.
Необязательно

payerMiddleName String [1..35] Отчество отправителя.
Необязательно

payerCombinedName String [1..99] Полное имя отправителя.
Необязательно

payerIdType String [1..8] Тип предоставленного идентифицирующего документа отправителя.
Возможные значения:
  • IDTP1 - Паспорт
  • IDTP2 - Водительское удостоверение
  • IDTP3 - Социальная карта
  • IDTP4 - ID карта гражданина
  • IDTP5 - Сертификат ведения бизнеса
  • IDTP6 - Сертификат беженца
  • IDTP7 - Вид на жительство
  • IDTP8 - Заграничный паспорт
  • IDTP9 - Официальный паспорт
  • IDTP10 - Временный паспорт
  • IDTP11 - Паспорт моряка
Необязательно

payerIdNumber String [1..99] Номер предоставленного идентифицирующего документа отправителя.
Условие

payerBirthday String [1..20] Дата рождения отправителя в формате YYYYMMDD. Обязательно для Visa.

Ниже приведены параметры блока billingRecipientData (данные о получателе).

Обязательность Название Тип Описание
Необязательно

recipientCity String [0..40] Код города получателя. Формат ISO 3166-1 alpha-3. Может содержать буквы только латинского алфавита.
Условие

recipientCountry String [0..50] Код страны получателя. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или название страны. Рекомендуем передавать двух/трехбуквенный ISO код страны. Обязательно для Mastercard.
Необязательно

recipientAddressLine1 String [0..50] Адрес получателя. Может содержать буквы только латинского алфавита.
Необязательно

recipientPostalCode String [0..9] Почтовый индекс получателя.
Необязательно

recipientState String [0..50] Код штата получателя. Формат: полное значение кода ISO 3166-2, его часть или наименование штата/региона. Может содержать буквы только латинского алфавита. Рекомендуем передавать двухбуквенный ISO код штата/региона.
Условие

recipientAccount String [0..32] Номер счета получателя. Обязательно для Mastercard.
Условие

recipientAccountNumberType Integer [1..2] Тип счета получателя. Возможные значения:
  • 1 - RTN + Bank Account;
  • 2 - IBAN;
  • 3 - Card Account;
  • 4 - E-mail;
  • 5 - Phone Number;
  • 6 - Bank account number (BAN) + Bank Identification Code (BIC);
  • 7 - Wallet Id;
  • 8 - Social Network Id;
  • 100 - Other.

Обязательно для Mastercard.
Обязательно

recipientLastName String [0..35] Фамилия получателя.
Обязательно

recipientFirstName String [0..35] Имя получателя.
Необязательно

recipientMiddleName String [0..35] Отчество получателя.
Необязательно

recipientCombinedName String [0..99] Полное имя получателя.
Необязательно

recipientIdType String [1..8] Тип предоставленного идентифицирующего документа получателя.
Возможные значения:
  • IDTP1 - Паспорт
  • IDTP2 - Водительское удостоверение
  • IDTP3 - Социальная карта
  • IDTP4 - ID карта гражданина
  • IDTP5 - Сертификат ведения бизнеса
  • IDTP6 - Сертификат беженца
  • IDTP7 - Вид на жительство
  • IDTP8 - Заграничный паспорт
  • IDTP9 - Официальный паспорт
  • IDTP10 - Временный паспорт
  • IDTP11 - Паспорт моряка
Необязательно

recipientIdNumber String [1..99] Номер предоставленного идентифицирующего документа получателя.
Необязательно

recipientBirthday String [1..20] Дата дня рождения получателя в формате YYYYMMDD.

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

Обязательность Название Тип Описание
Обязательно

errorCode String [1..2] Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
  • значение 0 - указывает на успех обработки запроса;
  • другое числовое значение (1-99) - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр errorMesage.
Может отсутствовать, если результат не вызвал ошибки.
Обязательно

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 для передачи атрибутов карты для списания.


При выполнении запроса необходимо использовать заголовок: Content-Type: application/json

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

Обязательность Название Тип Описание
Обязательно

username String [1..30] Логин учетной записи API продавца.
Обязательно

password String [1..30] Пароль учетной записи API продавца.
Обязательно

orderId String [1..36] Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза.
Необязательно

language String [2] Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина.
Поддерживаемые языки: ru,en,by,kz,kk.
Необязательно

amount String [0..12] Сумма перевода в минимальных единицах валюты (например, в копейках).
Этот параметр передается, если плательщик решит изменить сумму перевода при осуществлении денежного перевода.
Необязательно billingPayerData Object Блок с регистрационными данными клиента (адрес, почтовый индекс), необходимый для прохождения проверки адреса в рамках сервисов AVS/AVV. Обязателен, если функция включена для продавца на стороне Платежного шлюза. См. вложенные параметры.
Необязательно billingRecipientData Object Блок данных о получателе. Обязателен, если функция включена для продавца на стороне Платежного шлюза. См. вложенные параметры.
Обязательно

fromCard Object Блок с атрибутами карты списания. См. вложенные параметры.

Блок fromCard включает в себя следующие параметры:

Обязательность Название Тип Описание
Обязательно

pan String [1..19] Номер карты списания денежных средств.

Необходимо передать один из следующих наборов параметров: bindingId, pan+expirationYear+expirationMonth или seToken.
Необязательно

cvc String [3] Код CVC/CVV2 на обратной стороне карты списания.
Обязателен, если оплата не проводится по связке и/или у продавца нет разрешения на оплату без CVC.
Допускаются только цифры.
Обязательно

expirationYear Integer [4] Год истечения действия карты списания. Принимаются значения от 2000 до 2200.

Необходимо передать один из следующих наборов параметров: bindingId, pan+expirationYear+expirationMonth или seToken.
Обязательно

expirationMonth Integer [2] Месяц истечения действия карты списания. Доступные значения: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12.

Необходимо передать один из следующих наборов параметров: bindingId, pan+expirationYear+expirationMonth или seToken.
Обязательно

cardholderName String [1..26] Имя держателя карты списания.
Условие

seToken String Зашифрованные данные карты.
Обязательно, если используется вместо данных карты. Обязательные параметры для строки seToken: timestamp, UUID, PAN, EXPDATE, MDORDER. Подробнее о генерации seToken см. здесь.

Необходимо передать один из следующих наборов параметров: bindingId, pan+expirationYear+expirationMonth или seToken.

Ниже приведены параметры блока billingPayerData (данные об адресе регистрации клиента).

Обязательность Название Тип Описание
Условие

billingCity String [0..50] Город, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно для Visa.
Условие

billingCountry String [0..50] Страна, зарегистрированная по конкретной карте банка-эмитента. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или наименование страны. Рекомендуем передавать двух/трехбуквенный ISO код страны. Обязательно для Visa.
Условие

billingAddressLine1 String [0..50] Адрес, зарегистрированный по конкретной карте у Банка Эмитента (адрес плательщика). Строка 1. Обязательно к передаче для AVS-проверки. Обязательно для Visa.
Необязательно

billingAddressLine2 String [0..50] Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 2.
Необязательно

billingAddressLine3 String [0..50] Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 3.
Необязательно

billingPostalCode String [0..9] Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно к передаче для AVS-проверки.
Необязательно

billingState String [0..50] Штат, зарегистрированный по конкретной карте у Банка Эмитента. Формат: полное значение кода ISO 3166-2, его часть или наименование штата/региона. Может содержать буквы только латинского алфавита. Рекомендуем передавать двухбуквенный ISO код штата/региона.
Обязательно

payerAccount String [1..32] Номер счета отправителя.
Условие

payerLastName String [1..64] Фамилия отправителя. Обязательно для Visa.
Условие

payerFirstName String [1..35] Имя отправителя. Обязательно для Visa.
Необязательно

payerMiddleName String [1..35] Отчество отправителя.
Необязательно

payerCombinedName String [1..99] Полное имя отправителя.
Необязательно

payerIdType String [1..8] Тип предоставленного идентифицирующего документа отправителя.
Возможные значения:
  • IDTP1 - Паспорт
  • IDTP2 - Водительское удостоверение
  • IDTP3 - Социальная карта
  • IDTP4 - ID карта гражданина
  • IDTP5 - Сертификат ведения бизнеса
  • IDTP6 - Сертификат беженца
  • IDTP7 - Вид на жительство
  • IDTP8 - Заграничный паспорт
  • IDTP9 - Официальный паспорт
  • IDTP10 - Временный паспорт
  • IDTP11 - Паспорт моряка
Необязательно

payerIdNumber String [1..99] Номер предоставленного идентифицирующего документа отправителя.
Условие

payerBirthday String [1..20] Дата рождения отправителя в формате YYYYMMDD. Обязательно для Visa.

Ниже приведены параметры блока billingRecipientData (данные о получателе).

Обязательность Название Тип Описание
Необязательно

recipientCity String [0..40] Код города получателя. Формат ISO 3166-1 alpha-3. Может содержать буквы только латинского алфавита.
Условие

recipientCountry String [0..50] Код страны получателя. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или название страны. Рекомендуем передавать двух/трехбуквенный ISO код страны. Обязательно для Mastercard.
Необязательно

recipientAddressLine1 String [0..50] Адрес получателя. Может содержать буквы только латинского алфавита.
Необязательно

recipientPostalCode String [0..9] Почтовый индекс получателя.
Необязательно

recipientState String [0..50] Код штата получателя. Формат: полное значение кода ISO 3166-2, его часть или наименование штата/региона. Может содержать буквы только латинского алфавита. Рекомендуем передавать двухбуквенный ISO код штата/региона.
Условие

recipientAccount String [0..32] Номер счета получателя. Обязательно для Mastercard.
Условие

recipientAccountNumberType Integer [1..2] Тип счета получателя. Возможные значения:
  • 1 - RTN + Bank Account;
  • 2 - IBAN;
  • 3 - Card Account;
  • 4 - E-mail;
  • 5 - Phone Number;
  • 6 - Bank account number (BAN) + Bank Identification Code (BIC);
  • 7 - Wallet Id;
  • 8 - Social Network Id;
  • 100 - Other.

Обязательно для Mastercard.
Обязательно

recipientLastName String [0..35] Фамилия получателя.
Обязательно

recipientFirstName String [0..35] Имя получателя.
Необязательно

recipientMiddleName String [0..35] Отчество получателя.
Необязательно

recipientCombinedName String [0..99] Полное имя получателя.
Необязательно

recipientIdType String [1..8] Тип предоставленного идентифицирующего документа получателя.
Возможные значения:
  • IDTP1 - Паспорт
  • IDTP2 - Водительское удостоверение
  • IDTP3 - Социальная карта
  • IDTP4 - ID карта гражданина
  • IDTP5 - Сертификат ведения бизнеса
  • IDTP6 - Сертификат беженца
  • IDTP7 - Вид на жительство
  • IDTP8 - Заграничный паспорт
  • IDTP9 - Официальный паспорт
  • IDTP10 - Временный паспорт
  • IDTP11 - Паспорт моряка
Необязательно

recipientIdNumber String [1..99] Номер предоставленного идентифицирующего документа получателя.
Необязательно

recipientBirthday String [1..20] Дата дня рождения получателя в формате YYYYMMDD.

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

Обязательность Название Тип Описание
Обязательно

errorCode String [1..2] Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
  • значение 0 - указывает на успех обработки запроса;
  • другое числовое значение (1-99) - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр errorMesage.
Может отсутствовать, если результат не вызвал ошибки.
Обязательно

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..30] Логин учетной записи API продавца.
Обязательно

password String [1..30] Пароль учетной записи API продавца.
Необязательно

language String [2] Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина.
Поддерживаемые языки: ru,en,by,kz,kk.
Обязательно

orderId String [1..36] Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза.
Обязательно

fromCard Object Блок с атрибутами карты списания. См. вложенные параметры.

Блок fromCard включает в себя следующие параметры:

Обязательность Название Тип Описание
Необязательно

bindingId String [1..255] Идентификатор связки, созданной при оплате заказа или использованной для оплаты. Доступно, только если продавцу разрешено создавать связки.

Необходимо передать один из следующих наборов параметров: bindingId, pan+expirationYear+expirationMonth или seToken.
Обязательно

pan String [1..19] Номер карты списания денежных средств.

Необходимо передать один из следующих наборов параметров: bindingId, pan+expirationYear+expirationMonth или seToken.
Необязательно

cvc String [3] Код CVC/CVV2 на обратной стороне карты списания.
Обязателен, если оплата не проводится по связке и/или у продавца нет разрешения на оплату без CVC.
Допускаются только цифры.
Обязательно

expirationYear Integer [4] Год истечения действия карты списания. Принимаются значения от 2000 до 2200.

Необходимо передать один из следующих наборов параметров: bindingId, pan+expirationYear+expirationMonth или seToken.
Обязательно

expirationMonth Integer [2] Месяц истечения действия карты списания. Доступные значения: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12.

Необходимо передать один из следующих наборов параметров: bindingId, pan+expirationYear+expirationMonth или seToken.
Обязательно

cardholderName String [1..26] Имя держателя карты списания.
Необязательно

seToken String [1..8192] Зашифрованные данные карты. Обязательно, если используется вместо данных карты.
Обязательные параметры для строки seToken: timestamp, UUID, bindingId, MDORDER. Подробнее о генерации seToken см. здесь.

Необходимо передать один из следующих наборов параметров: bindingId, pan+expirationYear+expirationMonth или seToken.

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

Обязательность Название Тип Описание
Обязательно

errorCode String [1..2] Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
  • значение 0 - указывает на успех обработки запроса;
  • другое числовое значение (1-99) - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр errorMesage.
Может отсутствовать, если результат не вызвал ошибки.
Обязательно

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 для передачи атрибутов карты для списания.

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

Обязательность Название Тип Описание
Обязательно

username String [1..30] Логин учетной записи API продавца.
Обязательно

password String [1..30] Пароль учетной записи API продавца.
Необязательно

language String [2] Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина.
Поддерживаемые языки: ru,en,by,kz,kk.
Обязательно

orderId String [1..36] Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза.
Необязательно

ip String [1..39] IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов).
Необязательно

email String [1..40] Электронная почта плательщика.
Необязательно

amount String [0..12] Сумма перевода в минимальных единицах валюты (например, в копейках).
Этот параметр передается, если плательщик решит изменить сумму перевода при осуществлении денежного перевода.
Необязательно

type String В случае денежного перевода с данными только по одной карте необходимо передать в этом параметре соответствующее значение:
WITHOUT_TO_CARD - без указания карты для зачисления.
Необязательно

amountInput Integer [0..12] Сумма перевода в минимальных единицах валюты (например, в копейках). Если в этом параметре указана сумма, перевод будет осуществлен на эту сумму (независимо от суммы, переданной в запросе на оформление заказа).
Необязательно

captcha String CAPTCHA (текст, предназначенный для того, чтобы отличать человеческий ввод от машинного)
Необязательно

threeDSSDK Boolean Возможные значения: true или false Флаг, показывающий, что платеж поступает из 3DS SDK.
Необязательно

threeDSSDKEncData String Зашифрованные данные об устройстве.

Параметр является обязательным для SDK.
Необязательно

threeDSSDKReferenceNumber String Официальный идентификатор 3DS2 SDK
Необязательно

threeDSSDKEphemPubKey String Публичная часть эфемерного ключа. Требуется для установки сеанса с ACS.

Параметр является обязательным для SDK.
Необязательно

threeDSSDKAppId String Уникальный идентификатор SDK.

Параметр является обязательным для SDK.
Необязательно

threeDSSDKTransId String Уникальный идентификатор транзакции в SDK.

Параметр является обязательным для SDK.
Необязательно

threeDSMethodNotificationUrl String [1..512] URL-адрес для отправки уведомления о прохождении проверки на ACS.
Условие

threeDSServerTransId String [1..36] Идентификатор транзакции, созданный на сервере 3DS. Обязателен для аутентификации 3DS.
Необязательно

threeDSVer2FinishUrl String [1..512] URL-адрес, по которому клиент должен быть перенаправлен после аутентификации на сервере ACS.
Условие

threeDSVer2MdOrder String [1..36] Номер заказа, который был зарегистрирован в первой части запроса в рамках 3DS2 операции. Обязателен для аутентификации 3DS.
Если данный параметр присутствует в запросе, то используется mdOrder, который передается в настоящем параметре. В таком случае регистрация заказа не происходит, а происходит сразу оплата заказа.
Этот параметр передается только при использовании методов мгновенной оплаты, т.е., когда заказ регистрируется и оплачивается в рамках одного запроса.
Необязательно

bindingNotNeeded Boolean Допустимые значения:
  • true- создание связки после совершения платежа отключено (связка – это идентификатор клиента, переданный в запросе на регистрацию заказа, который после запроса оплаты будет удален из деталей заказа);
  • false – в случае успешной оплаты может быть создана связка (при соблюдении необходимых условий). Это значение по умолчанию.
Условие

originalPaymentNetRefNum String Идентификатор оригинальной или предыдущей успешной транзакции в платежной системе по отношению к выполняемой операции по связке - TRN ID. Передается, если значение параметра tii = R,U или F.
Обязателен при использовании связок мерчанта в переводах по связке.
Условие tii String Идентификатор инициатора транзакции. Параметр, указывающий, какой тип операции будет выполнять инициатор (Клиент или Мерчант).
Обязательно для операций AFT и перевода с использованием связки в блоке fromCard или собственной связки мерчанта.
Возможные значения
Обязательно

params Object Поля дополнительной информации для последующего хранения, передаются в следующем виде: {"param":"value","param2":"value2"}.
Данные поля могут быть переданы в процессинг банка для последующего отображения в реестрах банка.
По умолчанию передаются orderNumber (номер заказа) и orderDescription (описание заказа).orderDescription не должно превышать 99 символов, не используйте следующие символы: %, +, возврат каретки \r и перевод строки \n).
Чтобы включить эту функциональность, обратитесь в банк.

В объекте params запроса на перевод денег с карты на карту могут быть переданы следующие данные клиента (формат значений зависит от используемого метода обработки данных):
  • В параметре payerName - имя отправителя денег.
  • В параметре payerAddress - адрес отправителя.
  • В параметре payerCity - город отправителя.
  • В параметре payerCountry - страна отправителя в виде кода ISO 3166-1 alpha-3 (трехбуквенный код).
  • В параметре payerPostalCode - почтовый индекс отправителя.
  • В параметре payerState - регион отправителя.
Для платежной системы Visa в запросе на перевод денег с карты на карту также необходимо передать в параметре params следующую информацию (формат значений определяется используемым методом обработки данных):
  • В параметре recipientName - имя получателя денег.

При необходимости обратитесь в команду поддержки для указания постоянных значений параметров payer* и recipientName, чтобы не передавать их каждый раз во всех запросах.
Необязательно shippingPayerData Object Объект, содержащий данные о доставке клиенту. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры.
Необязательно preOrderPayerData Object Объект, содержащий данные предварительного заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры.
Необязательно orderPayerData Object Объект, содержащий данные о плательщике заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры.
Условие billingPayerData Object Блок с регистрационными данными клиента (адрес, почтовый индекс), необходимый для прохождения проверки адреса в рамках сервисов AVS/AVV. Обязателен, если функция включена для продавца на стороне Платежного шлюза. Должен был включен либо в запрос registerP2P.do, либо в запрос performP2P.do. См. вложенные параметры.
Условие billingRecipientData Object Блок данных о получателе. Обязателен, если функция включена для продавца на стороне Платежного шлюза. Должен был включен либо в запрос registerP2P.do, либо в запрос performP2P.do. См. вложенные параметры.
Обязательно

fromCard Object Блок с атрибутами карты списания. См. вложенные параметры.

Возможные значения параметры tii:

Значение tii Описание Тип транзакции Инициатор транзакции Данные карты для транзакции Данные карты сохраняются после транзакции Комментарий
CI Инициирующий - Обычный (CIT) Инициирующая Покупатель Вводится покупателем Да Транзакция электронной коммерции с сохранением связки.
F Внеплановый платеж (CIT) Последующая Покупатель Клиент выбирает карту вместо ручного ввода Нет Транзакция электронной коммерции, использующая ранее сохраненную обычную связку.

Описание параметров объекта 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] Индикатор способа доставки.
Возможные значения:
  • 01 - доставка на платежный адрес держателя карты.
  • 02 - доставка на другой адрес, проверенный Мерчантом.
  • 03 - доставка по адресу, отличному от основного адреса держателя карты.
  • 04 - отправка в магазин/самовывоз (адрес магазина должен быть указан в соответствующих параметрах доставки)
  • 05 - Цифровое распространение (включает онлайн-сервисы и электронные подарочные карты)
  • 06 - билеты на путешествия и мероприятия, которые нельзя доставить.
  • 07 - Прочее (например, игры, цифровые товары, не подлежащие доставке, цифровые подписки и т. д.)
Необязательно deliveryTimeframe Integer [2] Срок поставки товара.
Возможные значения:
  • 01 - цифровая дистрибуция
  • 02 - доставка в тот же день
  • 03 - доставка на следующий день
  • 04 - доставка в течение 2-х дней после оплаты и позже.
Необязательно deliveryEmail String [1..254] Целевой адрес электронной почты для доставки цифрового распространения. Предпочтительно передавать электронную почту в самостоятельном параметре запроса email (но если вы передадите его в этом блоке, к нему применятся те же правила).

Описание параметров объекта preOrderPayerData:

Обязательность Название Тип Описание
Необязательно preOrderDate String [10] Ожидаемая дата доставки (для предзаказанных покупок) в формате ГГГГММДД.
Необязательно preOrderPurchaseInd Integer [2] Индикатор размещения клиентом заказа на доступную или будущую доставку.
Возможные значения:
  • 01 - возможна доставка;
  • 02 - будущая доставка
Необязательно reorderItemsInd Integer [2] Индикатор того, что клиент перебронирует ранее оплаченную доставку в составе нового заказа.
Возможные значения:
  • 01 - заказ размещается впервые;
  • 02 - повторный заказ

Описание параметров объекта orderPayerData.

Обязательность Название Тип Описание
Необязательно homePhone String [7..15] Домашний телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
  • +35799988877;
  • 0035799988877;
  • 35799988877.
Необязательно workPhone String [7..15] Рабочий телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
  • +35799988877;
  • 0035799988877;
  • 35799988877.
Необязательно mobilePhone String [7..15] Номер мобильного телефона владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
  • +35799988877;
  • 0035799988877;
  • 35799988877.

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

Ниже приведены параметры блока billingPayerData (данные об адресе регистрации клиента).

Обязательность Название Тип Описание
Условие

billingCity String [0..50] Город, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно для Visa.
Условие

billingCountry String [0..50] Страна, зарегистрированная по конкретной карте банка-эмитента. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или наименование страны. Рекомендуем передавать двух/трехбуквенный ISO код страны. Обязательно для Visa.
Условие

billingAddressLine1 String [0..50] Адрес, зарегистрированный по конкретной карте у Банка Эмитента (адрес плательщика). Строка 1. Обязательно к передаче для AVS-проверки. Обязательно для Visa.
Необязательно

billingAddressLine2 String [0..50] Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 2.
Необязательно

billingAddressLine3 String [0..50] Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 3.
Необязательно

billingPostalCode String [0..9] Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно к передаче для AVS-проверки.
Необязательно

billingState String [0..50] Штат, зарегистрированный по конкретной карте у Банка Эмитента. Формат: полное значение кода ISO 3166-2, его часть или наименование штата/региона. Может содержать буквы только латинского алфавита. Рекомендуем передавать двухбуквенный ISO код штата/региона.
Обязательно

payerAccount String [1..32] Номер счета отправителя.
Условие

payerLastName String [1..64] Фамилия отправителя. Обязательно для Visa.
Условие

payerFirstName String [1..35] Имя отправителя. Обязательно для Visa.
Необязательно

payerMiddleName String [1..35] Отчество отправителя.
Необязательно

payerCombinedName String [1..99] Полное имя отправителя.
Необязательно

payerIdType String [1..8] Тип предоставленного идентифицирующего документа отправителя.
Возможные значения:
  • IDTP1 - Паспорт
  • IDTP2 - Водительское удостоверение
  • IDTP3 - Социальная карта
  • IDTP4 - ID карта гражданина
  • IDTP5 - Сертификат ведения бизнеса
  • IDTP6 - Сертификат беженца
  • IDTP7 - Вид на жительство
  • IDTP8 - Заграничный паспорт
  • IDTP9 - Официальный паспорт
  • IDTP10 - Временный паспорт
  • IDTP11 - Паспорт моряка
Необязательно

payerIdNumber String [1..99] Номер предоставленного идентифицирующего документа отправителя.
Условие

payerBirthday String [1..20] Дата рождения отправителя в формате YYYYMMDD. Обязательно для Visa.

Ниже приведены параметры блока billingRecipientData (данные о получателе).

Обязательность Название Тип Описание
Необязательно

recipientCity String [0..40] Код города получателя. Формат ISO 3166-1 alpha-3. Может содержать буквы только латинского алфавита.
Условие

recipientCountry String [0..50] Код страны получателя. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или название страны. Рекомендуем передавать двух/трехбуквенный ISO код страны. Обязательно для Mastercard.
Необязательно

recipientAddressLine1 String [0..50] Адрес получателя. Может содержать буквы только латинского алфавита.
Необязательно

recipientPostalCode String [0..9] Почтовый индекс получателя.
Необязательно

recipientState String [0..50] Код штата получателя. Формат: полное значение кода ISO 3166-2, его часть или наименование штата/региона. Может содержать буквы только латинского алфавита. Рекомендуем передавать двухбуквенный ISO код штата/региона.
Условие

recipientAccount String [0..32] Номер счета получателя. Обязательно для Mastercard.
Условие

recipientAccountNumberType Integer [1..2] Тип счета получателя. Возможные значения:
  • 1 - RTN + Bank Account;
  • 2 - IBAN;
  • 3 - Card Account;
  • 4 - E-mail;
  • 5 - Phone Number;
  • 6 - Bank account number (BAN) + Bank Identification Code (BIC);
  • 7 - Wallet Id;
  • 8 - Social Network Id;
  • 100 - Other.

Обязательно для Mastercard.
Обязательно

recipientLastName String [0..35] Фамилия получателя.
Обязательно

recipientFirstName String [0..35] Имя получателя.
Необязательно

recipientMiddleName String [0..35] Отчество получателя.
Необязательно

recipientCombinedName String [0..99] Полное имя получателя.
Необязательно

recipientIdType String [1..8] Тип предоставленного идентифицирующего документа получателя.
Возможные значения:
  • IDTP1 - Паспорт
  • IDTP2 - Водительское удостоверение
  • IDTP3 - Социальная карта
  • IDTP4 - ID карта гражданина
  • IDTP5 - Сертификат ведения бизнеса
  • IDTP6 - Сертификат беженца
  • IDTP7 - Вид на жительство
  • IDTP8 - Заграничный паспорт
  • IDTP9 - Официальный паспорт
  • IDTP10 - Временный паспорт
  • IDTP11 - Паспорт моряка
Необязательно

recipientIdNumber String [1..99] Номер предоставленного идентифицирующего документа получателя.
Необязательно

recipientBirthday String [1..20] Дата дня рождения получателя в формате YYYYMMDD.

Блок fromCard включает в себя следующие параметры:

Обязательность Название Тип Описание
Условие

pan String [1..19] Номер карты списания денежных средств.

Необходимо передать один из следующих наборов параметров: bindingId, pan+expirationYear+expirationMonth или seToken.
Условие

cvc String [3] Код CVC/CVV2 на обратной стороне карты списания.
Обязателен, если оплата не проводится по связке и/или у продавца нет разрешения на оплату без CVC.
Допускаются только цифры.
Условие

expirationYear Integer [4] Год истечения действия карты списания. Принимаются значения от 2000 до 2200.

Необходимо передать один из следующих наборов параметров: bindingId, pan+expirationYear+expirationMonth или seToken.
Условие

expirationMonth Integer [2] Месяц истечения действия карты списания. Доступные значения: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12.

Необходимо передать один из следующих наборов параметров: bindingId, pan+expirationYear+expirationMonth или seToken.
Необязательно

cardholderName String [1..26] Имя держателя карты списания.
Условие

seToken String Зашифрованные данные карты.
Обязательно, если используется вместо данных карты. Обязательные параметры для строки seToken: timestamp, UUID, PAN, EXPDATE, MDORDER. Подробнее о генерации seToken см. здесь.

Необходимо передать один из следующих наборов параметров: bindingId, pan+expirationYear+expirationMonth или 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 и т. д.). Возможные значения:
  • true – для расшифрованного токена;
  • false – для зашифрованного токена.

Если не передавать этот параметр, то по умолчанию будет считаться, что передано decryptedToken = false.
Необязательно

protocolVersion String Версия протокола, определенная Google для платежного токена: ECv1 (по умолчанию) или ECv2

Ниже перечислены параметры блока threeDsAuthResult (данные о результате аутентификации 3 DS).

Обязательность Название Тип Описание
Необязательно

cavv String [0..200] Значение проверки аутентификации владельца карты. Указан только после оплаты заказа и в случае наличия соответствующего разрешения.
Необязательно

xid String [1..80] Электронный коммерческий идентификатор транзакции. Указан только после оплаты заказа и в случае наличия соответствующего разрешения.
Необязательно

eci Integer [1..4] Электронный коммерческий индикатор. Указан только после оплаты заказа и в случае наличия соответствующего разрешения. Ниже приводится расшифровка ECI-кодов.
  • ECI=01 или ECI=06 - мерчант поддерживает 3-D Secure, платежная карта не поддерживает 3-D Secure, платеж обрабатывается на основе кода CVV2/CVC.
  • ECI=02 или ECI=05 - и мерчант, и платежная карта поддерживают 3-D Secure;
  • ECI=07 - мерчант не поддерживает 3-D Secure, платеж обрабатывается на основе кода CVV2/CVC.
Условие

authenticationTypeIndicator String Тип аутентификации 3DS. Этот параметр обязателен для оплаты через ваш 3DS сервер с 3DS 2. Для 3DS 1 и SSL платежей этот параметр необязателен и определяется в зависимости от значения ECI. Допустимые значения:
  • 0 - SSL-аутентификация
  • 1 - Аутентификация 3DS 1
  • 2 - Попытка аутентификации 3DS 1
  • 3 - Строгая аутентификация клиентов (SCA) с 3DS 2
  • 4 - Аутентификация на основе риска (RBA) с 3DS 2
  • 5 - Попытка аутентификации 3DS 2
Необязательно

threeDSProtocolVersion String Версия протокола 3DS. Возможные значения: "2.1.0", "2.2.0" для 3DS2.
Если в запросе не передается threeDSProtocolVersion, то для авторизации 3D Secure будет использоваться значение по умолчанию (2.1.0 - для 3DS 2).

В некоторых случаях запрос для AFT транзакции включает в себя блок toCard с вложенным блоком replacementData с данными для замены места назначения перевода в AFT транзакциях. Он содержит номер карты и номер транзитного счета получателя. Некоторые платежные системы требуют передачи этих данных в AFT транзакциях, т.е. эти данные используются для аутентификации на ACS во время 3DS авторизации.
Для использования этого блока мерчанту необходимо иметь специальное разрешение (уточните у команды поддержки).

Ниже перечислены параметры блока replacementData (данные для замены места назначения в AFT транзакциях):

Required Name Type Description
Необязательно card String [1..19] Номер карты получателя, если он известен в момент перевода.
Необязательно account String [1..30] Номер транзитного счета (любой номер, переданный банком).

При аутентификации по протоколу 3DS2 также передаются следующие параметры:

Обязательность Название Тип Описание
Необязательно

threeDSServerTransId String [1..36] Идентификатор транзакции, созданный на сервере 3DS. Обязателен для аутентификации 3DS.
Необязательно

threeDSVer2FinishUrl String [1..512] URL-адрес, по которому клиент должен быть перенаправлен после аутентификации на сервере ACS.
Необязательно

threeDSMethodNotificationUrl String [1..512] URL-адрес для отправки уведомления о прохождении проверки на ACS.

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

Обязательность Название Тип Описание
Обязательно

errorCode String [1..2] Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
  • значение 0 - указывает на успех обработки запроса;
  • другое числовое значение (1-99) - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр errorMesage.
Может отсутствовать, если результат не вызвал ошибки.
Необязательно

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 для завершения платежа.
Необязательно

originalPaymentNetRefNum String Идентификатор оригинальной или предыдущей успешной транзакции в платежной системе по отношению к выполняемой операции по связке - TRN ID. Передается, если значение параметра tii = R,U или F.
Обязателен при использовании связок мерчанта в переводах по связке.
Условие

mcTransactionReference String [1..19] Идентификатор AFT транзакции по карте Mastercard. Применимо (и обязательно) только для Mastercard.
Условие statusResponse Object Параметры статуса ответа. Этот блок возвращается, только если у вас включена соответствующая настройка. Для включения этой функциональности, обратитесь в техническую поддержку. См. вложенные параметры.

При аутентификации по протоколу 3DS2 в ответ на первый запрос приходят следующие параметры:

Обязательность Название Тип Описание
Обязательно

is3DSVer2 Boolean Возможные значения: true или false Флаг, показывающий, что платеж поступает из 3DS2.
Обязательно

threeDSServerTransId String [1..36] Идентификатор транзакции, созданный на сервере 3DS. Обязателен для аутентификации 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 при аутентификации по протоколу 3DS2:

Обязательность Название Тип Описание
Условие

acsUrl String [1..512] При успешном ответе в случае оплаты 3D-Secure. URL-адрес для редиректа на ACS. Обязательный, если нужен редирект на ACS. Подробнее см. Редирект на ACS.
Условие

packedCReq String Запакованные данные challenge request. Обязательный, если нужен редирект на ACS. Это значение следует использовать как значение параметра creq ссылки на ACS (acsUrl), для перенаправления клиента на ACS.

Параметры блока statusResponse:

Обязательность Название Тип Описание
Обязательно

errorCode String [1..2] Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
  • значение 0 - указывает на успех обработки запроса;
  • другое числовое значение (1-99) - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр errorMesage.
Может отсутствовать, если результат не вызвал ошибки.
Обязательно

errorMessage String [1..512] Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде.
Язык описания задается в параметре language запроса.
Необязательно

orderStatus Integer Значение этого параметра указывает статус заказа в платежном шлюзе. Отсутствует, если заказ не был найден. Ниже приведен список доступных значений:
  • 0 - заказ зарегистрирован, но не оплачен;
  • 2 - проведена полная авторизация суммы заказа;
  • 3 - авторизация отменена;
  • 5 - инициирована авторизация через ACS банка-эмитента;
  • 6 - авторизация отклонена;
Необязательно

orderNumber String [1..36] Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа.
Необязательно

panMaskedFrom String [1..19] Маскированный номер карты для списания средств.
Необязательно

panMaskedTo String [1..19] Маскированный номер карты для зачисления средств.
Необязательно

amount Integer [0..12] Сумма платежа в минимальных единицах валюты (например, в копейках).
Необязательно

currency String [3] Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию. Допускаются только цифры.
Необязательно

creationDate Integer Дата регистрации заказа.
Необязательно

orderDescription String [1..600] Описание заказа передаваемое платежному шлюзу при регистрации.
В этом поле недопустимо передавать персональные данные или платежные данные (номера карт т.п.). Данное требование связано с тем, что описание заказа нигде не маскируется.
Необязательно

ip String [1..39] IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов).
Обязательно

resultCode Integer Код ошибки при выполнении запроса. Возможные значения:
  • 0 - в случае успеха;
  • 1 - в случае ошибки.
Необязательно

orderParams Object Объект с мерчантскими атрибутами заказа. В ответе может быть представлено более одного блока orderParams.
Объект должен передаваться следующим образом: {"param":"value","param2":"value2"}.
Необязательно

operationList Object Объект, содержащий информацию о транзакциях, завершенных в заказе. В ответе может присутствовать более одного блока operationList.
Параметры, которые можно передать, описаны ниже.
Необязательно

binding String Идентификатор связки (если она уже была создана). Этот параметр возвращается, только если версия getP2PStatus равна 3 или выше.

Для завершения транзакции используйте метод /p2p/finishThreeDsVer2.do.

Примеры

Пример первого запроса в случае аутентификации по протоколу 3DS2

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"]
  },        

}'

Пример второго запроса в случае аутентификации по протоколу 3DS2

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"
}'

Пример ответа на первый запрос в случае аутентификации по протоколу 3DS2

{
  "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="
}

Пример ответа на второй запрос в случае аутентификации по протоколу 3DS2

{
  "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..30] Логин учетной записи API продавца.
Обязательно

password String [1..30] Пароль учетной записи API продавца.
Необязательно

language String [2] Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина.
Поддерживаемые языки: ru,en,by,kz,kk.
Необязательно

ip String [1..39] IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов).
Необязательно

email String [1..40] Электронная почта для отображения на платежной странице. Если для продавца настроены уведомления клиента, электронную почту необходимо указать. Пример: client_mail@email.com.
Для платежей по VISA с 3DS авторизацией необходимо указать либо электронную почту, либо номер телефона владельца карты.
Обязательно

type String В случае денежного перевода с данными только по одной карте необходимо передать в этом параметре соответствующее значение:
WITHOUT_TO_CARD - без указания карты для зачисления.
Обязательно

orderId String [1..36] Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза.
Необязательно

amountInput Integer [0..12] Сумма перевода в минимальных единицах валюты (например, в копейках). Если в этом параметре указана сумма, перевод будет осуществлен на эту сумму (независимо от суммы, переданной в запросе на оформление заказа).
Необязательно

amountInput Integer [0..12] Сумма перевода в минимальных единицах валюты (например, в копейках). Если в этом параметре указана сумма, перевод будет осуществлен на эту сумму (независимо от суммы, переданной в запросе на оформление заказа).
Необязательно

captcha String CAPTCHA (текст, предназначенный для того, чтобы отличать человеческий ввод от машинного)
Необязательно

threeDSSDK Boolean Возможные значения: true или false Флаг, показывающий, что платеж поступает из 3DS SDK.
Необязательно

threeDSSDKEncData String Зашифрованные данные об устройстве.

Параметр является обязательным для SDK.
Необязательно

threeDSSDKReferenceNumber String Официальный идентификатор 3DS2 SDK
Необязательно

threeDSSDKEphemPubKey String Публичная часть эфемерного ключа. Требуется для установки сеанса с ACS.

Параметр является обязательным для SDK.
Необязательно

threeDSSDKAppId String Уникальный идентификатор SDK.

Параметр является обязательным для SDK.
Необязательно

threeDSSDKTransId String Уникальный идентификатор транзакции в SDK.

Параметр является обязательным для SDK.
Необязательно

threeDSMethodNotificationUrl String [1..512] URL-адрес для отправки уведомления о прохождении проверки на ACS.
Условие

threeDSServerTransId String [1..36] Идентификатор транзакции, созданный на сервере 3DS. Обязателен для аутентификации 3DS.
Необязательно

threeDSVer2FinishUrl String [1..512] URL-адрес, по которому клиент должен быть перенаправлен после аутентификации на сервере ACS.
Условие

threeDSVer2MdOrder String [1..36] Номер заказа, который был зарегистрирован в первой части запроса в рамках 3DS2 операции. Обязателен для аутентификации 3DS.
Если данный параметр присутствует в запросе, то используется mdOrder, который передается в настоящем параметре. В таком случае регистрация заказа не происходит, а происходит сразу оплата заказа.
Этот параметр передается только при использовании методов мгновенной оплаты, т.е., когда заказ регистрируется и оплачивается в рамках одного запроса.
Необязательно

bindingNotNeeded Boolean Допустимые значения:
  • true- создание связки после совершения платежа отключено (связка – это идентификатор клиента, переданный в запросе на регистрацию заказа, который после запроса оплаты будет удален из деталей заказа);
  • false – в случае успешной оплаты может быть создана связка (при соблюдении необходимых условий). Это значение по умолчанию.
Условие

originalPaymentNetRefNum String Идентификатор оригинальной или предыдущей успешной транзакции в платежной системе по отношению к выполняемой операции по связке - TRN ID. Передается, если значение параметра tii = R,U или F.
Обязателен при использовании связок мерчанта в переводах по связке.
Условие tii String Идентификатор инициатора транзакции. Параметр, указывающий, какой тип операции будет выполнять инициатор (Клиент или Мерчант).
Обязательно для операций AFT и перевода с использованием связки в блоке fromCard или собственной связки мерчанта.
Возможные значения
Необязательно

params Object Поля дополнительной информации для последующего хранения, передаются в следующем виде: {"param":"value","param2":"value2"}.
Данные поля могут быть переданы в процессинг банка для последующего отображения в реестрах банка.
По умолчанию передаются orderNumber (номер заказа) и orderDescription (описание заказа).orderDescription не должно превышать 99 символов, не используйте следующие символы: %, +, возврат каретки \r и перевод строки \n).
Чтобы включить эту функциональность, обратитесь в банк.

В объекте params запроса на перевод денег с карты на карту могут быть переданы следующие данные клиента (формат значений зависит от используемого метода обработки данных):
  • В параметре payerName - имя отправителя денег.
  • В параметре payerAddress - адрес отправителя.
  • В параметре payerCity - город отправителя.
  • В параметре payerCountry - страна отправителя в виде кода ISO 3166-1 alpha-3 (трехбуквенный код).
  • В параметре payerPostalCode - почтовый индекс отправителя.
  • В параметре payerState - регион отправителя.
Для платежной системы Visa в запросе на перевод денег с карты на карту также необходимо передать в параметре params следующую информацию (формат значений определяется используемым методом обработки данных):
  • В параметре recipientName - имя получателя денег.

При необходимости обратитесь в команду поддержки для указания постоянных значений параметров payer* и recipientName, чтобы не передавать их каждый раз во всех запросах.
Необязательно shippingPayerData Object Объект, содержащий данные о доставке клиенту. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры.
Необязательно preOrderPayerData Object Объект, содержащий данные предварительного заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры.
Необязательно orderPayerData Object Объект, содержащий данные о плательщике заказа. Этот параметр используется для дальнейшей 3DS-аутентификации клиента. См. вложенные параметры.
Необязательно

billingAndShippingAddressMatchIndicator String [1] Индикатор соответствия платежного адреса владельца карты и адреса доставки. Этот параметр используется для дальнейшей 3DS-аутентификации клиента.
Возможные значения:
  • Y - совпадение платежного адреса держателя карты и адреса доставки;
  • N - платежный адрес владельца карты и адрес доставки не совпадают.
Условие billingPayerData Object Блок с регистрационными данными клиента (адрес, почтовый индекс), необходимый для прохождения проверки адреса в рамках сервисов AVS/AVV. Обязателен, если функция включена для продавца на стороне Платежного шлюза. См. вложенные параметры.
Условие billingRecipientData Object Блок данных о получателе. Обязателен, если функция включена для продавца на стороне Платежного шлюза. См. вложенные параметры.
Обязательно

fromCard Object Блок с атрибутами карты списания. См. вложенные параметры.

Возможные значения параметры tii:

Значение tii Описание Тип транзакции Инициатор транзакции Данные карты для транзакции Данные карты сохраняются после транзакции Комментарий
CI Инициирующий - Обычный (CIT) Инициирующая Покупатель Вводится покупателем Да Транзакция электронной коммерции с сохранением связки.
F Внеплановый платеж (CIT) Последующая Покупатель Клиент выбирает карту вместо ручного ввода Нет Транзакция электронной коммерции, использующая ранее сохраненную обычную связку.

Блок fromCard включает в себя следующие параметры:

Обязательность Название Тип Описание
Условие

bindingId String [1..255] Идентификатор связки, созданной при оплате заказа или использованной для оплаты. Доступно, только если продавцу разрешено создавать связки.

Необходимо передать один из следующих наборов параметров: bindingId, pan+expirationYear+expirationMonth или seToken.
Условие

pan String [1..19] Номер карты списания денежных средств.

Необходимо передать один из следующих наборов параметров: bindingId, pan+expirationYear+expirationMonth или seToken.
Условие

cvc String [3] Код CVC/CVV2 на обратной стороне карты списания.
Обязателен, если оплата не проводится по связке и/или у продавца нет разрешения на оплату без CVC.
Допускаются только цифры.
Условие

expirationYear Integer [4] Год истечения действия карты списания. Принимаются значения от 2000 до 2200.

Необходимо передать один из следующих наборов параметров: bindingId, pan+expirationYear+expirationMonth или seToken.
Условие

expirationMonth Integer [2] Месяц истечения действия карты списания. Доступные значения: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12.

Необходимо передать один из следующих наборов параметров: bindingId, pan+expirationYear+expirationMonth или seToken.
Необязательно

cardholderName String [1..26] Имя держателя карты списания.
Условие

seToken String [1..8192] Зашифрованные данные карты. Обязательно, если используется вместо данных карты.
Обязательные параметры для строки seToken: timestamp, UUID, bindingId, MDORDER. Подробнее о генерации seToken см. здесь.

Необходимо передать один из следующих наборов параметров: bindingId, pan+expirationYear+expirationMonth или seToken.
Условие threeDsAuthResult Object Блок с данными о результате аутентификации 3 DS с использованием MPI/3DS Server мерчанта.
Обязателен для транзакций перевода с карты на карту и AFT с использованием MPI/3DS Server мерчанта.
См. вложенные параметры.

Ниже перечислены параметры блока threeDsAuthResult (данные о результате аутентификации 3 DS).

Обязательность Название Тип Описание
Необязательно

cavv String [0..200] Значение проверки аутентификации владельца карты. Указан только после оплаты заказа и в случае наличия соответствующего разрешения.
Необязательно

xid String [1..80] Электронный коммерческий идентификатор транзакции. Указан только после оплаты заказа и в случае наличия соответствующего разрешения.
Необязательно

eci Integer [1..4] Электронный коммерческий индикатор. Указан только после оплаты заказа и в случае наличия соответствующего разрешения. Ниже приводится расшифровка ECI-кодов.
  • ECI=01 или ECI=06 - мерчант поддерживает 3-D Secure, платежная карта не поддерживает 3-D Secure, платеж обрабатывается на основе кода CVV2/CVC.
  • ECI=02 или ECI=05 - и мерчант, и платежная карта поддерживают 3-D Secure;
  • ECI=07 - мерчант не поддерживает 3-D Secure, платеж обрабатывается на основе кода CVV2/CVC.
Условие

authenticationTypeIndicator String Тип аутентификации 3DS. Этот параметр обязателен для оплаты через ваш 3DS сервер с 3DS 2. Для 3DS 1 и SSL платежей этот параметр необязателен и определяется в зависимости от значения ECI. Допустимые значения:
  • 0 - SSL-аутентификация
  • 1 - Аутентификация 3DS 1
  • 2 - Попытка аутентификации 3DS 1
  • 3 - Строгая аутентификация клиентов (SCA) с 3DS 2
  • 4 - Аутентификация на основе риска (RBA) с 3DS 2
  • 5 - Попытка аутентификации 3DS 2
Необязательно

threeDSProtocolVersion String Версия протокола 3DS. Возможные значения: "2.1.0", "2.2.0" для 3DS2.
Если в запросе не передается threeDSProtocolVersion, то для авторизации 3D Secure будет использоваться значение по умолчанию (2.1.0 - для 3DS 2).

Описание параметров объекта 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] Индикатор способа доставки.
Возможные значения:
  • 01 - доставка на платежный адрес держателя карты.
  • 02 - доставка на другой адрес, проверенный Мерчантом.
  • 03 - доставка по адресу, отличному от основного адреса держателя карты.
  • 04 - отправка в магазин/самовывоз (адрес магазина должен быть указан в соответствующих параметрах доставки)
  • 05 - Цифровое распространение (включает онлайн-сервисы и электронные подарочные карты)
  • 06 - билеты на путешествия и мероприятия, которые нельзя доставить.
  • 07 - Прочее (например, игры, цифровые товары, не подлежащие доставке, цифровые подписки и т. д.)
Необязательно deliveryTimeframe Integer [2] Срок поставки товара.
Возможные значения:
  • 01 - цифровая дистрибуция
  • 02 - доставка в тот же день
  • 03 - доставка на следующий день
  • 04 - доставка в течение 2-х дней после оплаты и позже.
Необязательно deliveryEmail String [1..254] Целевой адрес электронной почты для доставки цифрового распространения. Предпочтительно передавать электронную почту в самостоятельном параметре запроса email (но если вы передадите его в этом блоке, к нему применятся те же правила).

Описание параметров объекта preOrderPayerData:

Обязательность Название Тип Описание
Необязательно preOrderDate String [10] Ожидаемая дата доставки (для предзаказанных покупок) в формате ГГГГММДД.
Необязательно preOrderPurchaseInd Integer [2] Индикатор размещения клиентом заказа на доступную или будущую доставку.
Возможные значения:
  • 01 - возможна доставка;
  • 02 - будущая доставка
Необязательно reorderItemsInd Integer [2] Индикатор того, что клиент перебронирует ранее оплаченную доставку в составе нового заказа.
Возможные значения:
  • 01 - заказ размещается впервые;
  • 02 - повторный заказ

Описание параметров объекта orderPayerData.

Обязательность Название Тип Описание
Необязательно homePhone String [7..15] Домашний телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
  • +35799988877;
  • 0035799988877;
  • 35799988877.
Необязательно workPhone String [7..15] Рабочий телефон владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
  • +35799988877;
  • 0035799988877;
  • 35799988877.
Необязательно mobilePhone String [7..15] Номер мобильного телефона владельца карты. Необходимо всегда указывать код страны, но знак + или 00 в начале можно указать или опустить. Номер должен иметь длину от 7 до 15 цифр. Таким образом, возможны следующие значения:
  • +35799988877;
  • 0035799988877;
  • 35799988877.

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

Ниже приведены параметры блока billingPayerData (данные об адресе регистрации клиента).

Обязательность Название Тип Описание
Условие

billingCity String [0..50] Город, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно для Visa.
Условие

billingCountry String [0..50] Страна, зарегистрированная по конкретной карте банка-эмитента. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или наименование страны. Рекомендуем передавать двух/трехбуквенный ISO код страны. Обязательно для Visa.
Условие

billingAddressLine1 String [0..50] Адрес, зарегистрированный по конкретной карте у Банка Эмитента (адрес плательщика). Строка 1. Обязательно к передаче для AVS-проверки. Обязательно для Visa.
Необязательно

billingAddressLine2 String [0..50] Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 2.
Необязательно

billingAddressLine3 String [0..50] Адрес, зарегистрированный по конкретной карте у Банка Эмитента. Строка 3.
Необязательно

billingPostalCode String [0..9] Почтовый индекс, зарегистрированный по конкретной карте у Банка Эмитента. Обязательно к передаче для AVS-проверки.
Необязательно

billingState String [0..50] Штат, зарегистрированный по конкретной карте у Банка Эмитента. Формат: полное значение кода ISO 3166-2, его часть или наименование штата/региона. Может содержать буквы только латинского алфавита. Рекомендуем передавать двухбуквенный ISO код штата/региона.
Обязательно

payerAccount String [1..32] Номер счета отправителя.
Условие

payerLastName String [1..64] Фамилия отправителя. Обязательно для Visa.
Условие

payerFirstName String [1..35] Имя отправителя. Обязательно для Visa.
Необязательно

payerMiddleName String [1..35] Отчество отправителя.
Необязательно

payerCombinedName String [1..99] Полное имя отправителя.
Необязательно

payerIdType String [1..8] Тип предоставленного идентифицирующего документа отправителя.
Возможные значения:
  • IDTP1 - Паспорт
  • IDTP2 - Водительское удостоверение
  • IDTP3 - Социальная карта
  • IDTP4 - ID карта гражданина
  • IDTP5 - Сертификат ведения бизнеса
  • IDTP6 - Сертификат беженца
  • IDTP7 - Вид на жительство
  • IDTP8 - Заграничный паспорт
  • IDTP9 - Официальный паспорт
  • IDTP10 - Временный паспорт
  • IDTP11 - Паспорт моряка
Необязательно

payerIdNumber String [1..99] Номер предоставленного идентифицирующего документа отправителя.
Условие

payerBirthday String [1..20] Дата рождения отправителя в формате YYYYMMDD. Обязательно для Visa.

Ниже приведены параметры блока billingRecipientData (данные о получателе).

Обязательность Название Тип Описание
Необязательно

recipientCity String [0..40] Код города получателя. Формат ISO 3166-1 alpha-3. Может содержать буквы только латинского алфавита.
Условие

recipientCountry String [0..50] Код страны получателя. Формат: ISO 3166-1 (Alpha 2 / Alpha 3 / Number-3) или название страны. Рекомендуем передавать двух/трехбуквенный ISO код страны. Обязательно для Mastercard.
Необязательно

recipientAddressLine1 String [0..50] Адрес получателя. Может содержать буквы только латинского алфавита.
Необязательно

recipientPostalCode String [0..9] Почтовый индекс получателя.
Необязательно

recipientState String [0..50] Код штата получателя. Формат: полное значение кода ISO 3166-2, его часть или наименование штата/региона. Может содержать буквы только латинского алфавита. Рекомендуем передавать двухбуквенный ISO код штата/региона.
Условие

recipientAccount String [0..32] Номер счета получателя. Обязательно для Mastercard.
Условие

recipientAccountNumberType Integer [1..2] Тип счета получателя. Возможные значения:
  • 1 - RTN + Bank Account;
  • 2 - IBAN;
  • 3 - Card Account;
  • 4 - E-mail;
  • 5 - Phone Number;
  • 6 - Bank account number (BAN) + Bank Identification Code (BIC);
  • 7 - Wallet Id;
  • 8 - Social Network Id;
  • 100 - Other.

Обязательно для Mastercard.
Обязательно

recipientLastName String [0..35] Фамилия получателя.
Обязательно

recipientFirstName String [0..35] Имя получателя.
Необязательно

recipientMiddleName String [0..35] Отчество получателя.
Необязательно

recipientCombinedName String [0..99] Полное имя получателя.
Необязательно

recipientIdType String [1..8] Тип предоставленного идентифицирующего документа получателя.
Возможные значения:
  • IDTP1 - Паспорт
  • IDTP2 - Водительское удостоверение
  • IDTP3 - Социальная карта
  • IDTP4 - ID карта гражданина
  • IDTP5 - Сертификат ведения бизнеса
  • IDTP6 - Сертификат беженца
  • IDTP7 - Вид на жительство
  • IDTP8 - Заграничный паспорт
  • IDTP9 - Официальный паспорт
  • IDTP10 - Временный паспорт
  • IDTP11 - Паспорт моряка
Необязательно

recipientIdNumber String [1..99] Номер предоставленного идентифицирующего документа получателя.
Необязательно

recipientBirthday String [1..20] Дата дня рождения получателя в формате YYYYMMDD.

При аутентификации по протоколу 3DS2 также передаются следующие параметры:

Обязательно Название Тип Описание
Необязательно

threeDSServerTransId String [1..36] Идентификатор транзакции, созданный на сервере 3DS. Обязателен для аутентификации 3DS.
Необязательно

threeDSVer2FinishUrl String [1..512] URL-адрес, по которому клиент должен быть перенаправлен после аутентификации на сервере ACS.
Необязательно

threeDSMethodNotificationUrl String [1..512] URL-адрес для отправки уведомления о прохождении проверки на ACS.

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

Обязательность Название Тип Описание
Обязательно

errorCode String [1..2] Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
  • значение 0 - указывает на успех обработки запроса;
  • другое числовое значение (1-99) - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр errorMesage.
Может отсутствовать, если результат не вызвал ошибки.
Обязательно

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.
Условие statusResponse Object Параметры статуса ответа. Этот блок возвращается, только если у вас включена соответствующая настройка. Для включения этой функциональности, обратитесь в техническую поддержку. См. вложенные параметры.

При аутентификации по протоколу 3DS2 в ответ на первый запрос приходят следующие параметры:

Обязательность Название Тип Описание
Обязательно

is3DSVer2 Boolean Возможные значения: true или false Флаг, показывающий, что платеж поступает из 3DS2.
Обязательно

threeDSServerTransId String [1..36] Идентификатор транзакции, созданный на сервере 3DS. Обязателен для аутентификации 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 при аутентификации по протоколу 3DS2:

Обязательность Название Тип Описание
Условие

acsUrl String [1..512] При успешном ответе в случае оплаты 3D-Secure. URL-адрес для редиректа на ACS. Обязательный, если нужен редирект на ACS. Подробнее см. Редирект на ACS.
Условие

packedCReq String Запакованные данные challenge request. Обязательный, если нужен редирект на ACS. Это значение следует использовать как значение параметра creq ссылки на ACS (acsUrl), для перенаправления клиента на ACS.

Параметры блока statusResponse:

Обязательность Название Тип Описание
Обязательно

errorCode String [1..2] Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
  • значение 0 - указывает на успех обработки запроса;
  • другое числовое значение (1-99) - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр errorMesage.
Может отсутствовать, если результат не вызвал ошибки.
Обязательно

errorMessage String [1..512] Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде.
Язык описания задается в параметре language запроса.
Необязательно

orderStatus Integer Значение этого параметра указывает статус заказа в платежном шлюзе. Отсутствует, если заказ не был найден. Ниже приведен список доступных значений:
  • 0 - заказ зарегистрирован, но не оплачен;
  • 2 - проведена полная авторизация суммы заказа;
  • 3 - авторизация отменена;
  • 5 - инициирована авторизация через ACS банка-эмитента;
  • 6 - авторизация отклонена;
Необязательно

orderNumber String [1..36] Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа.
Необязательно

panMaskedFrom String [1..19] Маскированный номер карты для списания средств.
Необязательно

panMaskedTo String [1..19] Маскированный номер карты для зачисления средств.
Необязательно

amount Integer [0..12] Сумма платежа в минимальных единицах валюты (например, в копейках).
Необязательно

currency String [3] Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию. Допускаются только цифры.
Необязательно

creationDate Integer Дата регистрации заказа.
Необязательно

orderDescription String [1..600] Описание заказа передаваемое платежному шлюзу при регистрации.
В этом поле недопустимо передавать персональные данные или платежные данные (номера карт т.п.). Данное требование связано с тем, что описание заказа нигде не маскируется.
Необязательно

ip String [1..39] IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов).
Обязательно

resultCode Integer Код ошибки при выполнении запроса. Возможные значения:
  • 0 - в случае успеха;
  • 1 - в случае ошибки.
Необязательно

orderParams Object Объект с мерчантскими атрибутами заказа. В ответе может быть представлено более одного блока orderParams.
Объект должен передаваться следующим образом: {"param":"value","param2":"value2"}.
Необязательно

operationList Object Объект, содержащий информацию о транзакциях, завершенных в заказе. В ответе может присутствовать более одного блока operationList.
Параметры, которые можно передать, описаны ниже.
Необязательно

binding String Идентификатор связки (если она уже была создана). Этот параметр возвращается, только если версия getP2PStatus равна 3 или выше.

Примеры

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

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"
}'

Пример первого запроса в случае аутентификации по протоколу 3DS2

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"
  }
}'

Пример второго запроса в случае аутентификации по протоколу 3DS2

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
}

Пример ответа на первый запрос в случае аутентификации по протоколу 3DS2

{
  "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",
}

Пример ответа на второй запрос в случае аутентификации по протоколу 3DS2

{
  "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..30] Логин учетной записи API продавца.
Обязательно

password String [1..30] Пароль учетной записи API продавца.
Необязательно

language String [2] Ключ языка по ISO 639-1. Если язык не указан, используется язык по умолчанию, указанный в настройках магазина.
Поддерживаемые языки: ru,en,by,kz,kk.
Условие

orderId String [1..36] Номер заказа в платежном шлюзе. Уникален в пределах платежного шлюза.
Условие

orderNumber String [1..36] Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа.

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

Обязательность Название Тип Описание
Обязательно

errorCode String [1..2] Информационный параметр в случае ошибки, который может иметь разные кодовые значения:
  • значение 0 - указывает на успех обработки запроса;
  • другое числовое значение (1-99) - указывает на ошибку, для получения более подробной информации о которой необходимо проверить параметр errorMesage.
Может отсутствовать, если результат не вызвал ошибки.
Обязательно

errorMessage String [1..512] Информационный параметр, являющийся описанием ошибки в случае возникновения ошибки. Значение errorMessage может варьироваться, поэтому не следует явным образом ссылаться на его значения в коде.
Язык описания задается в параметре language запроса.
Необязательно

orderStatus Integer Значение этого параметра указывает статус заказа в платежном шлюзе. Отсутствует, если заказ не был найден. Ниже приведен список доступных значений:
  • 0 - заказ зарегистрирован, но не оплачен;
  • 2 - проведена полная авторизация суммы заказа;
  • 3 - авторизация отменена;
  • 5 - инициирована авторизация через ACS банка-эмитента;
  • 6 - авторизация отклонена;
Необязательно

orderNumber String [1..36] Номер заказа (ID) в системе мерчанта; должен быть уникальным для каждого заказа.
Необязательно

panMaskedFrom String [1..19] Маскированный номер карты для списания средств.
Необязательно

panMaskedTo String [1..19] Маскированный номер карты для зачисления средств.
Необязательно

amount Integer [0..12] Сумма платежа в минимальных единицах валюты (например, в копейках).
Необязательно

currency String [3] Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию. Допускаются только цифры.
Необязательно

creationDate Integer Дата регистрации заказа.
Необязательно

orderDescription String [1..600] Описание заказа передаваемое платежному шлюзу при регистрации.
В этом поле недопустимо передавать персональные данные или платежные данные (номера карт т.п.). Данное требование связано с тем, что описание заказа нигде не маскируется.
Необязательно

ip String [1..39] IP адрес плательщика. IPv6 поддерживается во всех запросах (до 39 символов).
Обязательно

resultCode Integer Код ошибки при выполнении запроса. Возможные значения:
  • 0 - в случае успеха;
  • 1 - в случае ошибки.
Необязательно

orderParams Object Объект с мерчантскими атрибутами заказа. В ответе может быть представлено более одного блока orderParams.
Объект должен передаваться следующим образом: {"param":"value","param2":"value2"}.
Необязательно

operationList Object Объект, содержащий информацию о транзакциях, завершенных в заказе. В ответе может присутствовать более одного блока operationList.
Параметры, которые можно передать, описаны ниже.
Необязательно

binding String Идентификатор связки (если она уже была создана). Этот параметр возвращается, только если версия getP2PStatus равна 3 или выше.

Ниже приведены возможные параметры блока operationList.

Обязательность Название Тип Описание
Необязательно

operationType String Тип транзакции. Доступны следующие значения:
  • P2P_VERIFY - запрашивает сумму комиссии;
  • P2P_DEBIT - списывает деньги;
  • P2P_CREDIT - зачисляет деньги;
  • P2P_DEBIT_REVERSAL - отмена списания;
  • P2P_CREDIT_REVERSAL — отмена зачисления;
  • P2P_TRANSFER - перевод денег с карты на карту;
  • P2P_TRANSFER_REVERSAL - автоматический возврат, если при переводе произошла ошибка.
    Необязательно

    		amount Integer [0..12] Сумма платежа в минимальных единицах валюты (например, в копейках).
    Необязательно

    		currency String [3] Код валюты платежа ISO 4217. Если не указано, то используется значение по умолчанию. Допускаются только цифры.
    Необязательно

    		datetime String Дата и время совершения операции.
    Необязательно

    		resultCode Integer Код ошибки при выполнении запроса. Возможные значения:
    • 0 - в случае успеха;
    • 1 - в случае ошибки.
    Необязательно

    		resultCodeDescription String [1..512] Описание кода ошибки транзакции.
    Необязательно

    		maskedPan String [1..19] Маскированный номер карты или токена, использованного для оплаты.
    Необязательно

    		cardholderName String [1..26] Имя держателя карты (при наличии).
    Необязательно

    		refNum String [12] Уникальный идентификатор операции, присваиваемый банком-эквайером при проведении платежа по банковской карте. RRN создаётся исключительно банком-эквайером и используется для последующего поиска, проверки и урегулирования операций (включая возвраты, чарджбеки и расследования).

    Примеры

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

    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..30] Логин учетной записи API продавца.
    Обязательно

    		password String [1..30] Пароль учетной записи API продавца.
    Обязательно

    		tDsTransId String [1..36] Уникальный идентификатор транзакции, полученный от сервера 3DS.

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

    Ответ на этот запрос не содержит никаких параметров JSON. Вместо этого он перенаправляет клиента на один из следующих URL-адресов:

    Примеры

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

    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&amp;lang=en

    Категории:
    eCommerce API V1
    Категории
    Результаты поиска
    Навигация
    Перейти
    Закрыть
    Категории
    Результаты поиска