Перейти к основному содержимому

Процесс сохранения клиентом PAN карты

Этот сценарий описывает отправку выплаты на банковскую карту в случае, если вы не можете собирать данные банковских карт и хранить на своей стороне (у вас нет сертификата PCI DSS).

Вы можете получить токенизированные данные карты с помощью виджета и безопасно провести выплату.

Процесс описывает шаги взаимодействия агента и клиента с web-приложением. Шаги взаимодействия могут быть с открытием формы ввода в отдельном окне и с открытием формы в iframe. Процесс позволяет клиенту вводить и сохранять данные карты через web-app.

Как выглядит виджет​

alt text

Авторизационные данные​

  • Тестовые авторизационные данные:
  • Боевые авторизационные данные:
    • url = https://a2c.qiwi.kz
    • agentId и agentSecretKey = предоставляются по запросу через менеджера сопровождения
Важно:

Для воспроизведения приложения в iframe необходимо предоставить список тестовых и боевых хостов с которых будет осуществляться встраивание.

Процесс открытия страницы в отдельном окне​

Шаги процесса​

  1. Генерация ссылки клиенту агентом

    • Агент генерирует ссылку URL формата: {host}/form?agentId={id агента}&requestId={id запроса}&language=ru&agentCallbackUrl={страница с возвратом результата ответа}&agentSign={подпись hmac}.
    • Параметр language может принимать значения: ru, en, kz. По умолчанию ru
    • URL содержит параметры, необходимые для идентификации агента, запроса, страницы возврата и подписи.
    • Алгоритм HMAC SHA256. Для вычисления hmac необходимо склеить строку requestId;agentId;agentCallbackUrl и применить agentSecretKey. Например воспользоваться https://www.freeformatter.com/hmac-generator.html Пример полученного URL: https://a2c-test.qiwi.kz/form?agentId=agent-01&requestId=12345678&language=ru&agentCallbackUrl=https://agent.site.kz&agentSign=bc305308aa5fa30a56d69ab166a7d5613cf2ca17783d034fdc08eeba23bad901
    • Переадресация Клиента на URL

  2. Ввод номера карты и сохранение

    • Клиент переходит по полученному URL.
    • Клиенту открывается web-app.
    • Клиент вводит номер своей карты в предоставленную форму.
    • После ввода данных, клиент нажимает кнопку "Сохранить" для отправки данных.

  3. Переход с ответом на agentCallbackUrl

    • В случае успешного ответа:
      • Происходит переадресация клиента на agentCallbackUrl с добавлением параметров к URL: ?requestId={id запроса}&panToken={Токен карты}.
    • В случае неуспешного ответа:
      • Происходит переадресация клиента на agentCallbackUrl с добавлением параметров об ошибке к URL: ?requestId={id запроса}&errorCode={Код ошибки}&errorMessage={Сообщение об ошибке}.
Параметры запроса

Параметры для строки редиректа и iframe​

ПараметрыТипОбязательныйОписание
agentIdstringДаСтроковый идентификатор агента.
requestIdLongДаУникальный идентификатор операции.
languagestringНетВыбор языка: ru, en, kz. По умолчанию ru.
agentCallbackUrlstringДаСсылка агента для перенаправления после окончания ввода данных карты.
stringНетДля открытия формы в iFrame. Будут сгенерированы события.
agent_signstringДаПодпись HMAC SHA256: requestId;agentId;agentCallbackUrl с использованием agentSecretKey.

Параметры ответа после сохранения​

ПараметрТипОбязательныйОписание
requestIdLongДаУникальный идентификатор операции.
panTokenstringНетТокен карты, передаваемый в случае успешного ответа.
errorCodestringНетКод ошибки, передаваемый в случае неуспешного ответа. Список ошибок
errorMessagestringНетСообщение об ошибке, передаваемое в случае неуспешного ответа.

Процесс встраивания приложения в iframe​

Этот процесс описывает взаимодействие между клиентом, агентом и приложением, встроенным в iframe, на сайте агента.

Шаги процесса​

  1. Инициация действия клиентом

    • Клиент на сайте агента инициирует действие, которое требует взаимодействия с веб-приложением.

  2. Встраивание приложения агентом

    • В ответ на действие клиента, агент встраивает веб-приложение в iframe на своем сайте, используя специально сформированный URL: 
      {host}/form?agentId={id агента}&requestId={id запроса}&language=ru&agentSign={подпись hmac}
    • Параметр language может принимать значения: ru, en, kz. По умолчанию ru
    • Алгоритм HMAC SHA256. Для вычисления hmac необходимо склеить строку requestId;agentId; и применить agentSecretKey. Например воспользоваться https://www.freeformatter.com/hmac-generator.html Пример: https://a2c-test.qiwi.kz/form?agentId=agent-01&requestId=123456789&language=ru&agentSign=3e77416dbc65b9225c1ff455d357cdc4200fa83ee273bce727aa34c8dc44c725

    Пример встраивания iframe:

    <iframe src="{адрес приложения}?agentId={id агента}&requestId={id запроса}&language=ru&agentSign={подпись hmac}" width="100%" height="100%" title="Embedded Iframe" frameBorder="0"></iframe>
    • iframe встраивается со значением ширины и высоты в 100%, что позволяет ему автоматически подстроиться под размер блока, в который он встраивается. Примечание: минимальная ширина блока должна быть 320px, а высота 500px.

  3. Ожидание готовности приложения

    • Агент ожидает сообщение о готовности приложения, которое приходит в виде postMessage со статусом "Ready".

  4. Проверка origin перед взаимодействием

    • После получения сообщения о готовности, агент передает любое событие в iframe через postMessage для проверки origin, подтверждая безопасность взаимодействия.

  5. Ввод данных клиентом

    • Клиент вводит данные карты и подтверждает действие через интерфейс приложения, встроенного в iframe.

  6. Обработка данных и отправка ответа

    • Приложение обрабатывает введенные данные и отправляет результат обработки агенту через postMessage.
      • В случае неуспешного ответа: приложение отправляет агенту JSON с информацией об ошибке: 
        {"requestId": "id запроса", "errorCode": "код ошибки", "errorMessage": "сообщение об ошибке"}
      • В случае успешного ответа: приложение отправляет агенту JSON с результатом обработки: 
        {"requestId": "id запроса", "panToken": "токен карты"}

Обработка ответа агентом​

  • Агент обрабатывает полученный ответ от приложения и соответствующим образом реагирует на результат операции, информируя клиента о статусе обработки.

Возможные типы ошибок​

Код ошибкиОписание
AGENT_NOT_FOUNDДанные агента переданы не верно
AGENT_SIGN_INVALIDПодпись невалидна
PARSE_REQUEST_ERRORПереданные данные невалидны
INVALID_SESSIONНарушение процесса на стороне клиента
INVALID_PANНомер карты невалидный
PAN_IS_EXISTS_FOR_REQUESTДля данного запроса уже существует сохранённый номер карты
FORBIDDENЗапросы блокированы. Попробуйте позже

Теперь вы можете делать выплаты на карты по токену