NAV Navbar

Введение

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

Что дальше:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

pan (номер карты) срок CVV ожидаемый результат RC Платёжная система Актуальная
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 Да
2201 3820 0000 0013 12/24 123 Успех с 3ds 12345678 00 МИР Да
2201 3820 0000 0062 12/24 123 Успех с 3ds 12345678 00 МИР Да
2201 3820 0000 0039 12/24 123 Успех с 3ds 12345678 00 МИР Да
-Для получения 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 будет показа символьным эквивалентом. Передавать в параметр валюту необходимо в таком виде _RUB_ Список допустимых валют:

Буквенный код Цифровой код Валюта Разменная валюта Символ
RUB 643 российский рубль копейки (1⁄100) ₽
KZT 398 тенге, Казахстан тиын(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":"ana@mi.ru",
"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://ipsp.kz/payment/#!search_payment',
  'userToken':'USER_TOKEN'
}

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

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

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

Параметр Обязательный Описание
serviceCode + код провайдера
amount + сумма платежа в копейках (сумма которая идет на счет пользователю)
comission + комиссия платежа в копейках (если нет комиссии - передается 0)
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 + идентификатор пользователя

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

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

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

{
"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://ipsp.kz/payment/#!search_payment',
'userToken':'USER_TOKEN'
}

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

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

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

Параметр Обязательный Описание
serviceCode + код провайдера
userToken + идентификатор пользователя
amount + сумма платежа в копейках, которая идет на счет пользователю
comission + комиссия платежа в копейках (при отсутствии комиссии передается 0)
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

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

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

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

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

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

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

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

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

Общее:

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

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