Получение данных карты¶

Чтобы предоставить клиенту изображение карты с неполными реквизитами или показать полные реквизиты в интерфейсе, необходимо получить данные у BaaS.

Получение нечувствительных данных¶

К нечувствительным данным относятся:

• cardTokenId — идентификатор карты;
• cardPaymentSystem — тип платёжной системы;
• maskedPan — маскированный PAN;
• expiryDate — дата окончания срока действия карты;
• embossedName — имя владельца карты.

Для получения данных следует передать BaaS orderId заказа, в рамках которого оформлялась карта.

Успешный сценарий получения нечувствительных данных виртуальной карты изображён на диаграмме ниже.

%%{init: {
    "sequence" : {
        "wrap":true,
        "messageFontSize":13,
        "noteFontSize":12,
        "actorMargin":
        75 }}}%%
sequenceDiagram
    participant С as Клиент
    participant P as Партнёр
    participant B as BaaS
    С->>P: Переход на страницу интерфейса
    Note right of С: Страница с изображением карты
    P->>+B: Запрос на получение информации о заказе
    Note right of P: productId, orderId
    B-->>-P: Ответ на запрос получения информации о заказе
    Note left of B: cardInsensitiveInfo (cardTokenId, cardPaymentSystem, maskedPan, expiryDate)
    P->>С: Отрисовка реквизитов на карте в интерфейсе
    Note left of P: Последние 4 цифры PAN, expiryDate

Запрос описан в документации Cards-lifecycle API.

Получение чувствительных данных¶

PAN и CVV являются чувствительной информацией. Получить их можно двумя способами:

• с помощью API;
• с помощью формы.

Получение данных c помощью API¶

Для получение PAN и CVV c помощью API партнёру необходимо:

• отвечать стандартам безопасности PCI DSS и иметь соответствующий сертификат;
• использовать собственную форму для отображения реквизитов;
• знать cardTokenId — возвращается в ответ на запрос создания заказа на выпуск карты или запрос получения информации о заказе;
• дешифровать реквизиты — BaaS возвращает их в шифрованном виде.

Чтобы дешифровать PAN и CVV, партнёру необходимо:

• создать ключевую пару RSA 4096 бит;
• сохранить закрытый ключ у себя;
• закодировать открытый ключ в Base64 и передать его в запросе на получение PAN и CVV в качестве значения параметра publicKey.
• расшифровать полученные в ответе значения encryptedPan и encryptedCvv (которые были зашифрованы BaaS при помощи publicKey), используя закрытый ключ.

Переданный publicKey в BaaS не сохраняется.

Успешный сценарий получения PAN и CVV c помощью API изображён на диаграмме ниже.

%%{init: {
    "sequence" : {
        "wrap":true,
        "messageFontSize":14,
        "noteFontSize":12,
        "actorMargin":
        75 }}}%%
sequenceDiagram
    participant P as Партнёр
    participant B as BaaS
    Note left of P: Создана пара ключей RSA
    P->>+B: Запрос на получение PAN и CVV
    Note right of P: productId, cardTokenId, encryptionSpec, publicKey
    B-->>B: Шифрование с помощью publicKey алгоритмом encryptionSpec
    B-->>-P: Ответ на запрос получения PAN и CVV
    Note left of B: encryptedPan, encryptedCvv
    P-->>P: Дешифрование

Дешифрованные данные можно использовать для отображения реквизитов карты по запросу клиента в интерфейсе. Например на форме с элементом «Показать реквизиты».

Запрос описан в документации Cards-lifecycle API.

Получение данных c помощью формы¶

Форма просмотра реквизитов карты позволяет показать клиенту PAN, CVV и дату окончания срока действия в интерфейсе. Является альтернативой использованию Cards-lifecycle API. Преимущество использования формы в том, что партнёру не требуется:

• отвечать стандартам безопасности PCI DSS и иметь соответствующий сертификат;
• разрабатывать собственную форму для просмотра реквизитов карты;
• поддерживать информационное взаимодействие, описанное в разделе «Получение данных c помощью API».

Использование формы¶

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

Пример JavaScript-кода

 <script src="https://openapi-widget.qiwi.com/script.js" type="text/javascript"></script>
  <script>
    const widget = window.qwl.createCardInfoWidget({
      formUrl: 'https://openapi-widget.qiwi.com',
      token: '4ee7***ce61',
      allowCopy: 'clipboard-read; clipboard-write self',
      signature: '6cff***f555',
      style: {
        isModal: false,
        btn: ':hover {
          background: green;
        }',
        input: 'border-radius: 10px;
            :hover {
              color: red;
            }',
        layout: 'background: tomato;',
        rootId: 'form-container',
        titleColor: '#3c3c5b'
      },
    })
    widget.mount()
  </script>

Описание параметров и переменных

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

Успешный сценарий получения PAN и CVV c помощью формы изображён на диаграмме ниже.

%%{init: {
    "sequence" : {
        "wrap":true,
        "messageFontSize":13,
        "noteFontSize":13,
        "width":93,
        "actorMargin":81}}}%%
sequenceDiagram
    participant С as Клиент
    participant PF as Партнёр (Frontend)
    participant PB as Партнёр (Backend)
    participant B as BaaS
    С->>PF: Переход на страницу интерфейса
    Note right of С: Страница с реквизитами
    PF->>+PB: Запрос на получение токена формы
    Note right of PF: clientData
    PB->>+B: Запрос на получение токена формы
    Note right of PB: productId, cardTokenId
    B-->>-PB: Ответ на запрос получения токена формы
    Note left of B: formToken, formUrl
    PB->>PB: Вычисление signature
    PB-->>-PF: Ответ на запрос получения токена формы
    Note left of PB: formToken, formUrl, signature
    PF->>PF: Встраивание значений в JS-код
    rect rgb(230, 230, 230)
    Note over PF, B: JS-код формы просмотра реквизитов
    С->>PF: Событие/действие
    Note right of С: «Показать реквизиты»
    PF->>+B: Выполнение JS-кода (вызов API)
    B-->>-PF: PAN, CVV, expiryDate
    PF->>С: Отображение реквизитов на форме в интерфейсе
    Note left of PF: PAN, CVV, expiryDate
    end

Запросы описаны в документации Cards-lifecycle API.

Кастомизация формы¶

Кастомизация позволяет настроить внешний вид формы. CSS-свойства для кастомизации указываются в переменной style.

Пример style

      style: {
        isModal: false,
        btn: ': hover {
          background: gray;
        }',
        input: 'border-radius: 10px;
            :hover {
              color: orange;
            }',
        layout: 'background: orange;',
        rootId: 'form-container',
        titleColor: gray
      }

Описание параметров

Пример формы

Демонстрационная страница¶

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

Демо-страница позволяет:

• посмотреть результат кастомизации формы;
• протестировать работу формы с конкретными данными;
• получить JavaScript-код, сформированный после применения всех настроек и данных.

Чтобы увидеть результат кастомизации, необходимо:

• настроить стили согласно примеру на изображении выше;
• применить стили, нажав на соответствующую кнопку.

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

• ввести значения formUrl, token, signature, style (как получить значения см. в разделе «Использование формы»);
• применить настройки, нажав на соответствующую кнопку;
• нажать «Показать» на форме.

В случае успешного выполнения JavaScript форма отобразит реквизиты карты.