API docs by Redocly

QR & Transfers Payment Api (2.0)

Download OpenAPI specification:

Введение

Документ описывает порядок взаимодействия платформы Клиента и платформы 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:
  2. Идентификатор сервиса (serviceId):
  3. API ключ (Api key):

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

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

Сценарий Scan2pay (QR)

Порядок работы с сервисом платежей с инициацией через сканирование 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

Общее

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)

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

Сценарий Payload
Успех, одноразовый код 00020101021138560010A0000007270126000697040701128888123456780208QRIBFTTA53037045802VN63042249
Неуспех декода: аккаунт заблокирован 00020101021138560010A0000007270126000697040701128888123456780208QRIBFTTA53037045802VN63042249

Прочее

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

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

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

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

Лимиты

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

QRPH

Общее

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

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

Прочее

QR Code

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

Декодировать QR код

Authorizations:
bearerAuth
Request Body schema: application/json
text
required
string [ 0 .. 8000 ] characters

Отсканированный QR код

bankCurrency
string (Currency)
Enum: "RUB" "VND" "PHP" "UZS" "AZN" "AMD" "TJS" "LKR" "KRW" "THB" "TWD" "JPY" "SGD" "MNT" "KHR" "TRY" "ARS" "MXN" "KZT" "USD" "USDT"

Трёхбуквенный код валюты, либо код криптовалюты

serviceId
integer <int64> (ServiceId)

Идентификатор сервиса. Выдаётся командой технической поддержки системы КПА.

object (UserInfo)

Responses

Request samples

Content type
application/json
{
  • "text": "string",
  • "bankCurrency": "RUB",
  • "serviceId": 0,
  • "payerInfo": {
    }
}

Response samples

Content type
application/json
{
  • "stId": 42,
  • "amount": 200.25,
  • "currency": "RUB",
  • "rate": 85.2445,
  • "merchantInfo": {
    },
  • "minimumAmount": 200.25,
  • "serviceId": 0,
  • "description": "Оплата на кассе"
}

Transfers

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

Получить список банков

Authorizations:
bearerAuth
path Parameters
serviceId
required
integer <int64> (ServiceId)

Уникальный числовой идентификатор сервиса перевода

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Инициировать перевод по реквизитам

Authorizations:
bearerAuth
Request Body schema: application/json
serviceId
required
integer <int64> (ServiceId)

Идентификатор сервиса. Выдаётся командой технической поддержки системы КПА.

bankCode
required
string

code из запроса getBanks

accountNumber
required
string

Номер счёта получателя

recipientName
required
string

Имя получателя

description
string

Описание перевода

object (UserInfo)
object (UserInfo)

Responses

Request samples

Content type
application/json
{
  • "serviceId": 0,
  • "bankCode": "aub",
  • "accountNumber": 123456789,
  • "recipientName": "Ivan Ivanov",
  • "description": "string",
  • "recipientInfo": {
    },
  • "payerInfo": {
    }
}

Response samples

Content type
application/json
{
  • "stId": 42,
  • "currency": "RUB",
  • "rate": 85.2445
}

Payment

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

Совершить платёж/перевод

Authorizations:
bearerAuth
Request Body schema: application/json
stId
required
integer <int64> (StId) >= 0

ID платежа в системе КПА

bankId
required
string

ID платежа в системе банка

amount
required
number <decimal> (Amount) > 0

Сумма в единицах валюты, например VND. Точность 2 десятичных знака

currency
required
string (Currency)
Enum: "RUB" "VND" "PHP" "UZS" "AZN" "AMD" "TJS" "LKR" "KRW" "THB" "TWD" "JPY" "SGD" "MNT" "KHR" "TRY" "ARS" "MXN" "KZT" "USD" "USDT"

Трёхбуквенный код валюты, либо код криптовалюты

bankAmount
required
number <decimal> (Amount) > 0

Сумма в единицах валюты, например VND. Точность 2 десятичных знака

object (UserInfo)

Responses

Request samples

Content type
application/json
{
  • "stId": 42,
  • "bankId": "test-id",
  • "amount": 200.25,
  • "currency": "RUB",
  • "bankAmount": 200.25,
  • "payerInfo": {
    }
}

Response samples

Content type
application/json
{
  • "status": "SUCCESS"
}

Отменить платёж/перевод

Eсли плательщик отказался от совершения платежа/перевода. Можно вызвать только до вызова запроса pay

Authorizations:
bearerAuth
path Parameters
stId
required
string

ID транзакции в системе КПА

Responses

Получить статус платежа/перевода

Authorizations:
bearerAuth
path Parameters
stId
required
string

ID платежа в системе КПА

Responses

Response samples

Content type
application/json
{
  • "status": "SUCCESS"
}