QR & Transfers Payment Api (2.0)

Документ описывает порядок взаимодействия платформы Клиента и платформы Carusell (система "КПА") в рамках осуществления платежей и переводов в пользу различных получателей (мерчантов, банков) с инициацией транзакции через сканирование QR кода (scan-to-pay, MPM) или перевод из приложения Клиента по реквизитам.

Для интеграции необходимо выполнить настройку безопасного канала связи и получить доступ к платформе Carusell.

Взаимодействие с API происходит по защищенному протоколу HTTPS с использованием взаимной TLS-аутентификации (mTLS).

Чтобы получить сертификат со стороны Carusell для доступа к продовому контуру, необходимо:

1. Сгенерировать запрос на сертификат (CSR - Certificate Signing Request). Клиент создает файл с расширением .csr, который содержит публичный ключ и информацию об организации Клиента.
2. Отправить файл .csr. Сгенерированный файл необходимо предоставить по e-mail helpdesk@cyberpro.kg команде поддержки платформы Carusell для выпуска сертификата.
3. Получить подписанный сертификат (CRT). После обработки запроса Клиенту вернется файл сертификата с расширением .crt, который нужно будет установить на стороне Клиента. Этот сертификат необходим для аутентификации серверов Клиента при обращении к API платформы Carusell.

Для работы с тестовым контуром платформы сертификат не требуется.

Тестовый контур

Используйте следующие настройки:

1. Базовый URL: https://test.cyberasia.kg
2. Идентификатор сервиса (serviceId): смотри в таблице "Соответствие валюты списания с идентификатором сервиса" в разделе "Классификация методов"
3. API ключ (Api key): a78ddad5-1447-4998-9817-1b8f20755b81

Продовый контур

Для получения настроек доступа к продовому контуру Клиент направляет запрос по e-mail helpdesk@cyberpro.kg команде поддержки платформы Carusell.

Порядок работы с сервисом платежей с инициацией через сканирование QR (scan-to-pay):

1. Плательщик сканирует QR код, выпущенный оператором QR платежей в одной из стран (Вьетнам, Филиппины, Таиланд, Мексика и т.д.).
2. Клиент по строке внутри QR кода идентифицирует принадлежность QR к платежной системе определенной страны. Руководство по идентификации для каждой системы описано в разделе "Классификация методов".

   Допускается вариант, при котором Клиент может не выполнять этот шаг, поскольку запрос на декодирование QR кода позволяет определить принадлежность QR определенной платежной системе.

3. Содержимое внутри QR кода Клиенту нужно отправить в метод "Декодировать QR код". В ответ получить информацию о получателе (мерчанте) и информацию для расчета суммы списания (курс обмена местной валюты к валюте, в которой работает Клиент).
4. Если плательщик согласен на проведение платежа, Клиент вызывает метод "Совершить платёж". Если плательщик не согласен на проведение платежа, Клиент вызывает метод "Отменить платёж". Шаг опционален.
5. Если в результате совершения платежа получен статус PROCESSING, Клиенту необходимо запросить статус с использованием метода "Получить статус платежа".

Порядок работы с сервисом переводов по реквизитам:

1. Плательщик выбирает наименоваение получателя (банк, кошелек) из списка, который Клиент может получить, вызвав метод "Получить список банков", вводит реквизит (номер телефона / номер счета / номер IBAN / номер карты и т.д.) и ФИ получателя.
2. Клиент вызывает соответствующий метод "Инициировать перевод по []" в зависимости от реквизита. Получает ответ с подтверждением возможности совершить перевод и информацию для расчета суммы списания (курс обмена местной валюты к валюте, в которой работает Клиент).
3. Плательщик вводит сумму перевода в валюте зачисления, Клиент рассчитывает сумму в валюте списания и ожидает действий от плательщика.
4. Если плательщик согласен на совершение перевода, то Клиент вызывает метод "Совершить платёж". Если плательщик не согласен на проведение перевода, то Клиента вызывает метод "Отменить платёж".
5. Если в результате совершения перевода пришёл статус PROCESSING, Клиенту необходимо запросить статус с использованием метода "Получить статус платежа".

Общее

VietQR — это универсальный стандарт генерации QR-кодов для переводов, развиваемый Национальным банком Вьетнама совместно с платежной системой NAPAS, что обеспечивает высокий уровень адаптации метода, т.е. поддерживается подавляющим большинством мерчантов Вьетнама. Подключая этот метод, Клиент получает возможность предложить своим пользователям мгновенные и удобные платежи через сканирование QR-кода в любых торговых точках страны без необходимости интеграции с каждым мерчантом отдельно.

Идентификация QR

Формат: TLV (Tag--Length--Value), стандарт EMVCo
Чтение: слева направо (Tag[2] + Length[2] + Value)

Пример:

00020101021138560010A0000007270126000697040701128888123456780208QRIBFTTA53037045802VN63042249

Разбивка:

00 02 01 01 02 11 38 56 0010A000000727... 53 03 704 58 02 VN 63 04 2249

Ключевые теги:

• 58 → страна 58 02 VN
• 38 → платёжная система (контейнер)\внутри: 00 10 A000000727

Правило:

Payload = VietQR, если:

• 58 = VN
• в 38 есть A000000727 (NAPAS)

Тестовые данные

Лимиты на сумму транзакции: От 1 000 VND до 1 000 000 VND.

Таблица соответствия валюты списания (bankCurrency) и идентификатора сервиса (serviceId)

Прочее

Валюта зачисления

Вьетнамский донг, код ISO 4217: VND (числовой 704)

Данные плательщика

Передавать не требуется (поле payerInfo)

Лимиты в продовой среде

• Минимальная сумма транзакции: 5 000 VND
• Максимальня сумма транзакции: 250 000 000 VND

Общее

ThaiQR (PromptPay) — национальный стандарт QR-платежей в Таиланде на базе EMVCo Merchant Presented Mode. QR-коды используются для оплаты у мерчантов (Bill Payment / Merchant Presented QR), переводов на мобильный номер, национальный ID, e-wallet и банковский счёт.

Идентификация QR

Формат: TLV (Tag--Length--Value), стандарт EMVCo
Чтение: слева направо (Tag[2] + Length[2] + Value)

Пример (Merchant / Bill Payment, фиксированная сумма):

00020101021230820016A0000006770101120115010753600037405021500000220066077703204611316260181X00000053037645406178.225802TH5918LIM TREND EMPORIUM6212070846113162630427E5

Разбивка (ключевые теги):

00 02 01 — формат нагрузки EMV QR
01 02 12 — динамический QR
30 82 ... — информация о счёте получателя (Bill Payment)
30.00 16 A000000677010112 — AID PromptPay Bill Payment
30.01 15 010753600037405 — идентификатор биллера (receiverProxyValue)
30.02 15 000002200660777 — billReference1
30.03 20 4611316260181X000000 — billReference2
53 03 764 — валюта THB
54 06 178.22 — сумма
58 02 TH — страна Таиланд
59 18 LIM TREND EMPORIUM — наименование получателя
63 04 27E5 — CRC-16

Ключевые теги:

• 58 → страна 58 02 TH
• 53 → валюта 53 03 764 (THB)
• 29 / 30 → информация о счёте получателя (контейнер)
• 54 → сумма (если отсутствует, сумму вводит плательщик)

Правило:

Payload = ThaiQR, если:

• 58 = TH
• 53 = 764 (THB)
• есть контейнер 29 - P2P платёж, есть контейнер 30 - платёж мерчанту

Тестовые данные

Лимиты на сумму транзакции: От 1 000 THB до 1 000 000 THB.

Таблица соответствия валюты списания (bankCurrency) и идентификатора сервиса (serviceId)

Прочее

Валюта зачисления

Тайский бат, код ISO 4217: THB (числовой 764)

Данные плательщика

Обязательные поля в элементе documents (для выбранного документа):

Пример payerInfo:

{
  "id": "user-id-1",
  "firstName": "Ivan",
  "lastName": "Ivanov",
  "phone": "0891234567",
  "dateOfBirth": "1990-01-01",
  "citizenship": "TH",
  "address": "Bangkok",
  "documents": [
    {
      "type": "FOREIGN_PASSPORT",
      "documentNumber": "FP-123",
      "expiryDate": "2030-01-01"
    }
  ]
}

Лимиты в продовой среде

• Минимальная сумма транзакции: 1 THB
• Минимальная сумма транзакции: 30 000 THB

Общее

QRPh — это национальный стандарт генерации QR-кодов для платежей, разработанный Центральным банком Филиппин (Bangko Sentral ng Pilipinas) и работающий на базе системы мгновенных переводов InstaPay. Данное решение обеспечивает полную совместимость (интероперабельность) между всеми участниками рынка: клиенты любых банков и электронных кошельков могут проводить платежи через единый QR-код, объединяя более 2 миллионов мерчантов по всей стране. Подключая этот метод, Клиент получает возможность предложить своим пользователям мгновенные (благодаря рельсам InstaPay), безопасные и удобные платежи через сканирование QR-кода, совершая платежи в адрес мерчантов, которым не обязательно устанавливать отдельные POS-терминалы.

Идентификация QR

Формат: TLV (Tag--Length--Value), стандарт EMVCo
Чтение: слева направо (Tag[2] + Length[2] + Value)

Пример:

00020101021128600011ph.ppmi.p2m0111DCPHPHM1XXX0319206753426176814387205030105204593253036085802PH5906BNNALU6002PH62380011ph.ppmi.p2m051921849279383389809686304495E

Разбивка:

00 02 01 01 02 11 28 60 0011ph.ppmi.p2m... 53 03 608 58 02 PH 59 06 BNNALU 60 02 PH 63 04 495E

Ключевые теги:

58 → страна: 58 02 PH

Внутри тега 28 (контейнер для платёжной системы / идентификатора мобильного кошелька) содержится ph.ppmi.p2m — это тоже указывает на использование стандарта QR Ph (P2M — Person-to-Merchant).

Тестовые данные

Лимиты на сумму транзакции: От 1 000 PHP до 1 000 000 PHP.

Таблица соответствия валюты списания (bankCurrency) и идентификатора сервиса (serviceId)

Прочее

Валюта зачисления

Филиппинский песо, код ISO 4217: PHP (числовой 608)

Данные плательщика

Передавать не требуется (поле payerInfo)

Лимиты в продовой среде

• Минимальная сумма транзакции: 1 PHP
• Максимальня сумма транзакции: 50 000 PHP

Описание запроса на декодирование QR кода и получения реквизитов получателя

Описание запросов, связанных с инициализацией переводов по реквизитам

Описание запросов, относящихся к фазе совершения платежа