NAV Navbar

Введение

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

Что дальше:

  1. Подключите свое ПО к нашей демо-зоне
  2. Проведите несколько тестовых платежей
  3. Выводите свое ПО в боевой режим

Основные понятия

Рекуррентный платеж - платеж, созданный по ранее сохраненным данным банковской карты.

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

Общество - юридическое лицо, действующее по поручению Поставщика, являющееся посредником между Поставщиком и конечным потребителем услуги (Плательщиком).

Банк - эмитент - банк, выпускающий в обращение (эмитирующий) денежные знаки или ценные бумаги и платёжно-расчётные документы (банковские карты, чековые книжки). В нашем случае, говоря простыми словами, это банк, имеющий доступ к денежным средствам на счете клиента.

Интернет эквайринг - технология, позволяющая принимать к оплате банковские карты, виртуальные карты и электронные кошельки.

Агрегатор - компании, предоставляющие программное обеспечение Поставщикам Услуг. Фактически, интеграция происходит в программном обеспечении Агрегатора.

Технолог - разработчик программного обеспечения, который имеет собственный процессинг и предоставляет собственную инфраструктуру клиенту.

Процессинг - это деятельность по обработке информации, используемой при совершении платёжных операций. Такую деятельность осуществляют процессинговые центры.

ОП - отдел продаж

Процесс интеграции

Общие требования:

Тестовые параметры:

Тестовые карты

Вы можете проверить сценарий оплаты банковскими картами разных типов с разными результатами:

pan (номер карты) срок CVV ожидаемый результат RC Платёжная система Актуальная
5479 2700 0000 0000 03/22 123 Успех с 3ds 12345678 00 MASTER CARD Да
4111 1111 1111 1111 12/24 123 Успех с 3ds 12345678 00 VISA Да
6011 0000 0000 0004 12/24 123 Успех с 3ds 12345678 00 MAESTRO Да
-Для получения RC=05 необходимо ввести неверный код cvc2.

Боевые параметры

Платеж с 3ds

Некоторые рекуррентные платежи невозможны без данной технологии. При этом будет сгенерировано исключение NeedPass3dsException (смотри код 2365 в разделе Разбор ошибок), которое содержит номер платежа regPayNum и securePageURL (URL - тот, на который необходимо перенаправить пользователя для прохождения 3ds методом GET)

Ислючение может быть получено на этапе создания рекуррента (описан в разделе "создание платежа"), а так же на этапе проверки статуса платежа (описан в разделе "Получение статуса платежа")

Параметр enableSMSConfirm

Параметр payType

Создан для того, чтоб указать тип оплаты в запросах. Возможные значения поля:

Параметр orderBestBefore

Данным параметром можно передать время истечения жизни заказа (в секундах). Время, до которого нужно оплатить заказ.

Значение параметра - абсолютная дата UTC, в секундах (сформировать абсолютную дату). Например:

Параметр clientAuInfo

Пример заполнения параметра clientAuInfo


{
   "ipAddress": "xxx.xxx.xxx.xxx",
    "agentName": "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:80.0) Gecko/20100101 Firefox/80.0",
    "authenticationInfo": "e2RldmljZS5icm93c2VyQWNjZXB0SGVhZGVyPXRleHQvaHRtbA0KZGV2aWNlLmJyb3dzZXJJUD05NC4xMzguMTQ5LjM0DQpicm93c2VySmF2YUVuYWJsZWQ6IGZhbHNlDQpicm93c2VyTGFuZ3VhZ2U6ICJydS1SVSINCmJyb3dzZXJDb2xvckRlcHRoOiAyNA0KYnJvd3NlclNjcmVlbkhlaWdodDogMTA4MA0KYnJvd3NlclNjcmVlbldpZHRoOiAxOTIwDQpicm93c2VyVFo6IC0zMDANCmJyb3dzZXJVc2VyQWdlbnQ6ICJNb3ppbGxhLzUuMCAoWDExOyBVYnVudHU7IExpbnV4IHg4Nl82NDsgcnY6ODAuMCkgR2Vja28vMjAxMDAxMDEgRmlyZWZveC84MC4wIn0="
}

Скрипт получения данных в браузере клиента


function getFingerprint() {
    return btoa(JSON.stringify({
        browserTZ: new Date().getTimezoneOffset(),
        browserColorDepth: window.screen.colorDepth,
        browserScreenHeight:  window.screen.height,
        browserScreenWidth: window.screen.width,
        browserLanguage: navigator.language,
        browserUserAgent: window.navigator.userAgent,
        browserJavaEnabled: window.navigator.javaEnabled()
    }));
}

В параметре clientAuInfo необходимо передавать данные для корректного прохождения 3ds v2.

Применимо только для методов рекуррентного платежа: Cоздание рекуррентного платежа

Для метода Анонимного платежа наша форма оплаты сама соберёт необходимые данные.

Описание данных:

Параметр orderNote

В параметре orderNote передаются дополнительные данные, которые будут отображаться на платёжной форме.

Доп. справочное поле для пользователя.

Применимо только для методов, когда используется форма для ввода данных карты: Создание платежа, анонимного платежа, Cоздание рекуррентного платежа с типом оплаты картой ("payType":"card") и без заполненного параметра cardToken

Описание:

В параметре также есть возможность передачи валюты. Для этого необходимо указать валюту в кодировке ISO 4217 (буквенной). На форме ввода данных карты валюта в кодировке ISO 4217 будет показа символьным эквивалентом. Передавать в параметр валюту необходимо в таком виде _KZT_ Список допустимых валют:

Буквенный код Цифровой код Валюта Разменная валюта Символ
KZT 398 тенге, Казахстан тиын(1⁄100) 〒
RUB 643 российский рубль копейки (1⁄100) ₽
USD 840 американский бакс цент (1⁄100) $
EUR 978 ойро евроцент (1⁄100) €
GPB 826 фунт, Великобритания пе́нни (1⁄100) £
KGS 417 сом, Киргизия тыйын (1⁄100) с •
UZS 860 сум, узбекский тийин (1⁄100) So'm
AZN 944 азербайджанский манат гяпик (1⁄100) ₼
GEL 981 лари, Грузия тетри (1⁄100) ₾
TRY 949 турецкая лира куруш (1⁄100) ₺
CNY 156 юань фынь (1⁄100) ¥
AMD 051 армянский драм лума (1⁄100) ֏

Статусы платежей

Платеж - последовательная сущность. Он линейно переходит из одного статуса в другой. Если что-то пошло не так, есть альтернативный набор статусов, сигнализирующий о неуспешности оплаты.

Cтатусы c неуспешным результатом (платеж не достиг состояния "оплачен"):

Получение статуса платежа

Пример запроса статуса платежа

{
  "regPayNum":"1310958041"
}

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

{
  'errorCode':'1001',
  'provisionServices':'true',
  totalAmount':'100000',
  'serviceCode':'serviceCode',
  'providerName':'providerName',
  'state':'payed',
  'createdDate':'2012-10-06 03:02:01',
  'error':'error',
  'message':'message',
  'procDate':'2015-01-05 12:14:18'
}

{
"
"state":"holded",
"totalAmount":2575,
"createdDate":"2020-05-29 14:11:21",
"providerServCode":"1000-13864-3",
"providerName":"Тест ShopAPI",
"errorCode":null,
"error":null,
"message":null,
"provisionServices":false,
"procDate":null
}

Отправляется несколько попыток с нарастающим интервалом

Наш API позволяет отправлять повторные уведомления для одного платежа, в таких случаях ожидается успешный ответ

При оплате рекуррентом с обязательным вводом 3ds в ответе будет получено исключение:NeedPass3dsException(смотри код 2365 в разделе Разбор ошибок)

Для прохождения 3ds проверки необходимо перенаправить пользователя по ссылке в параметре securePageURL методом GET

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

Обязательные Параметры ответа:

Необязательные параметры ответа:

Уведомление об оплате

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

{
"regPayNum":"1310958041",
"amount":"100000",
"comission":"1000",
"state":"payed"
}

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


Ожидается любой ответ со статусом "200"

По умолчанию отправляются только успешные платежи

При неуспешном создании платежа уведомление не отправляется

С нашеё стороны отправляется POST запросы с нарастающим интервалом

Ожидается любой ответ с http - статусом 200

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

Параметр Обязательный Описание
regPayNum + номер платежа в нашей системе
amount + сумма платежа в копейках
comission + сумма комиссии в копейках
state + статус платежа. Подробнее
errorCode - код ошибки
errorMsg - текст ошибки

Возврат платежа

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


{
    "regPayNum": "13693892457",
    "note": "test",
    "refundAmount": "2400",
    "remainingAmount": "225"
}

С помощью данного метода можно можно отправлять заявки на возврат и частичный возврат. Метод доступен только для Магазин. Рекуррентный платёж или Магазин. Анонимный платеж.

Параметры запроса(все обязательные):

Параметры ответа(все обязательные):

Магазин. Анонимный платеж

Онлайн магазин, в котором принимается к оплате банковская карта.

Под "Анонимным" платежом предполагается платеж без сохраненных ранее данных по банковской карте.

Алгоритм работы

img_magaz_anon

Создание анонимного платежа

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


{
"serviceCode":"109-5804-1",
"amount":450,
"comission":13300,
"payType":"card",
"clientType":"web",
"userPhone":"79020000000",
"userEmail":"[email protected]",
"properties":
  [
  {"name":"Л/СЧЕТ","value":"9503006477"},
  {"name":"ФИО","value":"Иванов Н П"},
  {"name":"АДРЕС","value":"Ленина 10"},
  {"name":"МЕСЯЦ","value":"05.2015"},
  {"name":"СУММА_ПЕНИ","value":"10000"}
  ],
"orderItems":
  [
  {"num":1,"name":"name1","quantity":2,"price":100,"tax":"vat0"},
  {"num":2,"name":"name2","quantity":5,"price":50,"tax":"vat110"}
  ]
}

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

{
  'regPayNum':'1234567890',
  'methodType':'GET',
  'payUrl':'https://bisys.kz/payment/#!search_payment',
  'userToken':'USER_TOKEN'
}

Метод вызывается после успешной проверки на возможность создания платежа.

В ответ приходит номер платежа, URL и способ перехода.

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

Параметр Обязательный Описание
serviceCode + код провайдера
amount + сумма платежа в копейках (сумма которая идет на счет пользователю)
comission + комиссия платежа в копейках (если нет комиссии - передается 0)
gpayToken - Токен при оплате через Google Pay. Более подробно в разделе Google Pay
payType - способ оплаты Функция payType
clientType - тип клиента*
userPhone - Номер телефона пользователя(для СМС платежа), с которого будет произведена полата
orderBestBefore - Время истечения срока жизни заказа в секундах. Подробнее
properties + массив реквизитов**
orderNote - Доп. справочное поле для пользователя. Подробнее

Параметры ответа (все обязательные):

Магазин. Рекуррентный платеж

Онлайн магазин, позволяющий сохранять данные карты, держать список карт по пользователю, проводить оплату из сохраненных карточных данных.

Алгоритм работы

img_rek

Регистрация пользователя

Пример запроса на регистрацию пользователя

{
"login":"Login",
"email":"Email",
"name":"Name",
"surName":"SurName",
"middleName":"MiddleName"
}

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

Параметр Обязательный Описание
login + номер телефона с кодом, но без '+', например - 79020000000.
email - e-mail (на него отправляются чеки после оплаты)
name - имя
surName - фамилия
middleName - отчество

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

Параметр Обязательный Описание
login + номер телефона с кодом, но без '+', например - 79020000000.
email - e-mail (на него отправляются чеки после оплаты)
name - имя
surName - фамилия
middleName - отчество
state + статус. Более подробно - Статус пользователя
userToken + идентификатор пользователя

Статус пользователя

Пример запроса статуса пользователя

{
"login":"79150000000"
}

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

{
"state":"active",
"login":"getLogin()",
"email":"getEmail()",
"name":"getName()",
"surName":"getSurName()",
"middleName":"getMiddleName()"
,"userToken":"USER_TOKEN"
}

Если пользователь не зарегистрирован, то будет сгенерировано исключение UserNotRegisteredForShop (см. Разбор ошибок)

Параметры запроса (все параметры обязательные):

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

Параметр Обязательный Описание
login + номер телефона
email - e-mail
name - имя
surName - фамилия
middleName - отчество
state + статус*
userToken + идентификатор пользователя

Регистрация карты

Пример запроса на регистрацию карты

{
"userToken":"USER_TOKEN",
"clientType":"web"
}

Во время регистрации карты будет списано до 5 тенге, после добавления карты деньги будут возвращены

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

Для тестового соединения нужно использовать тестовую карту, см. пункт Тестовые, боевые данные

В ответ на запрос приходит номер платежа, url регистрации и способ перехода.

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

Параметр Обязательный Описание
clientType - тип клиента*
userToken + идентификатор пользователя
successUrl - динамический url возврата клиента после успешной оплаты**
failUrl - динамический url возврата клиента после неуспешной оплаты**
cbUrl - динамический url для отправки уведомлений, более подробно: Уведомление о регистрации карты

Параметры ответа (все параметры обязательные):

Получение списка карт

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

{
"userToken":"USER_TOKEN"
}


{

"userToken":"cc507cb4-fe90-4cb4-af75-37b9b5b41387"
"cards":
[{
"cardMask":"400000******0002",
"cardToken":"ae7f3942-4e7c-44d3-9ab9-8c84d118b5ed",
"cardType":"visa",
"state":"active"
}]
}

Для того что бы карта появилась в списке нужно произвести регистрацию карты см. пункт Регистрация карты

Параметры запроса (все параметры обязательные):

Параметры ответа (все параметры обязательные):

Деактивация/удаление карты

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

{
"userToken":"USER_TOKEN",
"cardToken":"CARD_TOKEN"
}

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

{
"resultState":"success",
"desc":"descSuccess",
"userToken":"USER_TOKEN"
}

После исполнения запроса состояние карты становится inactive и карта будет недоступна для оплаты (необходимо будет провести повторную привязку карты, см пункт Регистрация карты

Параметры запроса (все параметры обязательные):

Параметры ответа (все параметры обязательные):

Cоздание рекуррентного платежа

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

{
"cardToken":"CARD_TOKEN",
"value":"10000",
"clientType":"web",
"payType":"card",
"properties":
  [
  {"name":"Л/СЧЕТ","value":"9503006477"},
  {"name":"ФИО","value":"Иванов Н П"},
  {"name":"АДРЕС","value":"Ленина10"},
  {"name":"МЕСЯЦ","value":"05.2015"},
  {"name":"СУММА_ПЕНИ","value":"10000"}
  ],
"orderItems":
  [
  {"num":1,"name":"name1","quantity":2,"price":100,"tax":"vat0"},
  {"num":2,"name":"name2","quantity":5,"price":50,"tax":"vat110"}
  ],
"serviceCode":"109-5804-1",
"userToken":"USER_TOKEN",
"amount":"10000",
"comission":"13300"
}

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

{
'regPayNum':'1234567890',
'methodType':'GET',
'payUrl':'https://bisys.kz/payment/#!search_payment',
'userToken':'USER_TOKEN'
}

В ответ приходит номер платежа, url для оплаты и способ перехода.

При рекурентном платеже - url со ссылкой на чек.

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

Параметр Обязательный Описание
serviceCode + код провайдера
userToken + идентификатор пользователя
amount + сумма платежа в копейках, которая идет на счет пользователю
comission + комиссия платежа в копейках (при отсутствии комиссии передается 0)
gpayToken - Токен при оплате через Google Pay. Более подробно в разделе Google Pay
cardToken - идентификатор карты (для рекуррентного платежа), см. пункт Получение списка карт
enableSMSConfirm - более подробно: EnableSMScnfirm
payType - способ оплаты подробнее в п. Параметр payType
clientType - более подробно в п. Создание анонимного платежа
orderBestBefore - Время истечения срока жизни заказа в секундах. Подробнее
properties + массив реквизитов. Более подробно в п. Создание анонимного платежа
orderNote - Доп. справочное поле для пользователя. Подробнее

Параметры ответа (все параметры обязательные):

Уведомление о регистрации карты

Пример запроса создания уведомления

{
"userToken":"USER_TOKEN",
"cardMask":"546949******9929",
"cardToken":"77a3adeb-1f50-400a-88a9-7127dc9ea9f3",
"cardType":"master_card"
}

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

Параметр Обязательный Описание
userToken + идентификатор пользователя
cardToken + токен карты
cardMask + маскированый номер карты
cardType + тип карты. Подробнее см. п. Получение списка карт

В ответ ожидается любой ответ со статусом 200

Google Pay™

С помощью системы Google Pay™ вы сможете быстро принимать в своем приложении оплату от миллионов пользователей, которые сохранили данные банковских карт в своих аккаунтах Google.

Введение

Нажав на кнопку оплаты через Google Pay, пользователь переходит на страницу, где указаны способы оплаты и адреса доставки, сохраненные в его аккаунте Google. Здесь он может быстро выбрать нужную информацию или добавить новую.

Как это работает: оплата осуществляется из мобильного приложения с устройства пользователя. В сценарии приложение запрашивает зашифрованные данные у Google Pay. Эти данные необходимо передать в платежный шлюз: тоесть, нам.

Итак, вы приняли решение внедрить технологию Google Pay в ваше приложение. С чего начать?

Алгоритм работы

Пример инициализации структуры Подробнее

"type": "CARD",
  "parameters": {
    "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
    "allowedCardNetworks": ["MASTERCARD", "VISA"]

В настоящее время шлюз поддерживает платежные системы Visa и MasterCard, а так же обработку токенизированных и нетокенизированных карт (PAN_ONLY и CRYPTOGRAM_3DS).

Наш шлюз поддерживает возможность оплаты через Google Pay как в вашем android приложении, так и в вашем web-приложении (на сайте).

img_gpay

1. Пользователь в приложении выбирает тип оплаты Google Pay (привязывает карту, либо выбирает уже привязанную).

2. Приложение запрашивает у Google Pay данные карт, привязанных к Google в маскированном виде. Для того, чтоб приложение могло успешно общаться с системой Google Pay не нужно к ним интегрироваться, достаточно знать несколько параметров. Мы рассмотрим их ниже.

3. Google Pay возвращает в приложение данные карт (привязанных к Google) в маскированном виде.

4. Приложение показывает пользователю данные его карт/карты (привязанной к Google) в маскированном виде.

5. Пользователь подтверждает оплату (выбирает карту, либо другой способ оплаты).

6. Приложение запрашивает у Google Pay карточные данные в зашифрованном виде.

7. Google Pay шифрует данные, используя открытый ключ - соответствующий ему закрытый ключ расположен в платёжном шлюзе. То есть, собирает некую посылку в виде криптограммы.

Пример криптограммы от Google Pay

{"signature":"MEYCIQDzIjWGqr1teZiawa3HJ9IgJ/j4ZJnHkgIXzJv1pD1MIQIhAMWLvRlTZjdVCJBHO6/Jo+wuIudYqlrIxKU3nJdcU9XW","protocolVersion":"ECv1","signedMessage":"{\"encryptedMessage\":\"s3w41rMoVYpgOaWGWF8Sk6WAxxbDCPkepD94OIPTt4BMCJYTFMkM34KG60ONbu1bQkSfibSveqTtP0+bnXNcF2N50ZT+QTJ4rt7411nyXmWlsqHVGTHCI7RT02Q45l9NM33BIA8zuqAigqhPd91a3x1b0ZrBZW7xBOPf8Vzh5sokepySQRLIWwN/F40aO3DC3AP+wt8FT+ly4M3C7srDZAJT4/pbE4Qyr9ftvdqFze2fRJmPv0Uc1m8C+4AZHYwZSY8jCMlhdsEECR1pHdaXqpiTNDutY9Qw0ESQq63zMqPsfpDLo15bl4l52zkqtC7bxPfI31CaB0dmV+Et8rw6TYVa0+8DvvYAEWoHU1aZAXQd2amI7rGdJ3p6KO8IaL5QwwtFk5byjvxrsjN1Nq9EQJnzCVfE5/P7PdGVB3LLLTLmc5xJJH89CYuu6er4erVcfw\\u003d\\u003d\",\"ephemeralPublicKey\":\"BGLg5omp43/eI6V43NvI1FEF2TpTnz/S9T4hByZ3Oa726uLc3BTVzOpcUefzBDL5gePdvRqQTrL3U0vV4JRHFhU\\u003d\",\"tag\":\"x1hLpFnhsB2tSUO4CMAWCbZgvClC3ieIKkjRtCSQV1Q\\u003d\"}"}

8. Google возвращает в приложение зашифрованные данные о платеже (криптограмму).

9. Приложение отправляет в нашу платежную систему запрос на оплату, указывая полученный ранее Google Pay Token.

10. Наша платежная система собирает данные о платеже и отправляет платеж в эквайринг.

11. Эквайринг проводит платеж в обычном режиме (методами того типа магазина, который вы выбрали).

12. Информация о статусе платежа отправляется на Backend приложения.

В мобильном приложении

Пример выбора способа токенизации (из документации Google Pay API)

  private static JSONObject getGatewayTokenizationSpecification() throws JSONException {
    return new JSONObject(){{
      put("type", "PAYMENT_GATEWAY");
      put("parameters", new JSONObject(){{
        put("gateway", "bisysgpay");
        put("gatewayMerchantId", "shopToken");
        }
      });
    }};
  }

Если с какими-то параметрами, запросами у вас возникли проблемы и ошибки, то обязательно загляните в раздел Устранение неполадок. Ведь с большинством проблем уже столкнулись, решили и описали их решение.

На сайте

Пример выбора способа токенизации (из документации Google Pay API для сайта)

const tokenizationSpecification = {
  type: 'PAYMENT_GATEWAY',
  parameters: {
    'gateway': 'bisysgpay',
    'gatewayMerchantId': 'shopToken'
  }
};

Если с какими-то параметрами, запросами у вас возникли проблемы и ошибки, то обязательно загляните в раздел Устранение неполадок. Ведь с большинством проблем уже столкнулись, решили и описали их решение.

Разбор ошибок

Ошибки, сигнализирующие о том, что необходимо заново регистрировать карту:

Ошибки, связанные со сложностями в авторизации:

Не удалось получить список услуг:

Сложности с регистрацией:

Сложности с активацией:

Проблемы со статусом платежа:

Трудности в создании платежа:

Общее:

Коды ошибок проводки платежа

Общие ошибки: