Подготовка к интеграции

Содержание
  1. Неописанные параметры
  2. Пример запроса на возврат
  3. Правила формирования подписи при запросе данных счетов
  4. Оповещение об изменении статуса счета
  5. Создание подписки
  6. Алгоритм работы с подпиской
  7. Пример ожидаемого успешного ответа от системы мерчанта на оповещение от Pikassa
  8. Схема и пример данных ОФД
  9. Пример ответа с ошибкой на запрос на создание счета
  10. Алгоритм формирования ЭЦП
  11. Подготовка к работе
  12. Пример ответа с ошибкой на запрос на возврат
  13. Перечень возможных значений статусов выплаты
  14. Перечень возможных значений статусов платежа
  15. Пример запроса на получение данных
  16. Пример успешного ответа на запрос на создание счета
  17. Размер данных
  18. Пример ответа с ошибкой на запрос на создание подписки
  19. Пример запроса для оплаты счета по токену
  20. Пример успешного ответа на запрос на отмену счета
  21. Схема проведения запроса
  22. Примеры реализации алгоритма формирования x-sign
  23. Отправка данных в соответствии с ФЗ-54
  24. Оплата счета по реквизитам банковской карты
  25. Пример запроса для оплаты счета по реквизитам банковской карты
  26. Пример запроса на получение данных счетов
  27. Пример ответа с ошибкой на запрос оплаты счета
  28. Пример успешного ответа на запрос на создание подписки

Неописанные параметры

Когда приходит задача интегрироваться с сложным API, очень часто хочется как можно скорее просто начать работать. Это может быть ошибкой.Например, делая одну из интеграций мы по готовой инструкции сделали запрос на поиск из Алматы в Нур-Султан на 1 пассажира. Получили результаты с перелетами, и даже забронировали билет. Все это сделали сразу в клиенте.

Но для перелета туда – обратно все стало сложнее.

Работая над одной из интеграций, мы использовали инструкцию-пример для интеграции. В запросе на поиск перелета из Алматы в Нур-Султан помимо стандартных данных — город вылета, прилета, дата, и кол-во пассажиров , у нас был параметр FareFilterMethod, который никак не влияет на выдачу, если вы делаете запрос в одну сторону.

У этого параметра такое количество значений:

Стоит ли говорить о том, что описания к этим значениям в API нет. Не зная, на что он в принципе влияет, мы использовали то, что было дано в примере и вроде бы все пошло хорошо. Нам вернулись результаты поиска:

Оказывается все это уже готово на стороне API и мы можем для этого использовать параметр CombinabilityNestedRoundtripOnlyLowestFarePerFareType сразу. Вот только этот параметр меняет структуру выдачи и теперь она выглядит так:

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

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

Пример запроса на возврат

uuid – идентификатор счета, полученный в успешном ответе при создании счета.

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

Метод позволяет запросить данные нескольких счетов по фильтрам.

Передаваемые параметры не должны дублироваться.

Правила формирования подписи при запросе данных счетов

Подпись формируется следующим образом:

  • Значения передаваемых query-параметров сортируются по именам query-параметров, по алфавиту в нижнем регистре в прямом порядке
  • Значения параметров склеиваются (конкатенация) в строку через точку с запятой
  • К полученной строке приклеивается (конкатенация) секретный ключ магазина
  • Вычисляется контрольная сумма полученной строки по алгоритму md5, кодировка UTF-8
  • Контрольная сумма кодируется в base64
  • Полученная подпись передается в заголовке запроса : X-Sign
Описание параметров запроса на получение данных

“Счет на оплату заказа №1223080”

“Счет на оплату заказа №122”

Описание параметров успешного ответа на получение данных

​ Для подготовки к интеграции необходимо:

  • Зарегистрировать личный кабинет Pikassa по кнопке Подключиться на странице pikassa.io;
  • В личном кабинете создать магазин в разделе Магазины, перейти в настройки магазина и заполнить раздел Общие настройки;
  • Перейти в раздел настроек магазина Технические настройки и сгенерировать новый секретный ключ (secretPhrase) для формирования подписи;
  • Если требуется передача уведомлений об изменении статусов счета в одну из ваших систем (Callback), заполнить поле ResultURL адресом для получения уведомлений;
  • Активировать созданный магазин, связавшись с персональным менеджером.

Оповещение об изменении статуса счета

Оповещение об изменении статуса (Callback) происходит путем отправки POST-запроса по адресу, указанному в настройках магазина (раздел Технические настройки , параметр Result url)

Если на оповещение получен невалидный ответ/валидный ответ с ошибкой, или же ответ не получен, система отправляет повторное оповещение позднее. Оповещение отправляется повторно конечное число раз.

Создание подписки

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

Алгоритм работы с подпиской

  • Магазин отправляет в Pikassa запрос на создание счета, где указывает параметр createToken=true для создания платежного токена. Предварительно данную возможность необходимо согласовать с менеджером;
  • Логика оплаты счета описана в “Схеме проведения запроса”;
  • В случае если счет был успешно оплачен, то Pikassa отправляет магазину уведомление об успешной оплате, которое содержит идентификатор платежного токена;
    Магазин возвращает ответ-подтверждение о проведенной операции.
  • Магазин отправляет в Pikassa запрос на создание подписки, где указывает идентификатор платежного токена первого счета и данные подписки;
  • Pikassa обрабатывает запрос и если подписка создана корректно, возвращает ответ, содержащий идентификатор подписки;
  • В случае если наступил момент следующей оплаты счета Pikassa создает счет и проводит его аналогично первому платежу, но списание средств осуществляется уже без подтверждения клиентом;
  • Pikassa отправляет магазину уведомление об успешной/неуспешной оплате счета, которое содержит идентификатор подписки, на основе которой создан счет;
    Магазин возвращает ответ-подтверждение о проведенной операции.
Читайте также:  Детские пособия будут платить по новому

Пример ожидаемого успешного ответа от системы мерчанта на оповещение от Pikassa

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

Также метод используется при двухстадийном платеже и позволяет разблокировать ранее захолдированную сумму на карте плательщика.

Схема и пример данных ОФД

Схема запроса JSON , пример 1 и пример 2.

Пример ответа с ошибкой на запрос на создание счета

“Ошибка создания счета”

Описание параметров ответа с ошибкой создания счета

paymentToken – идентификатор платежного токена, полученный в нотификации (callback), после оплаты счета.

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

Метод позволяет запросить данные счета: статус счета, итоговая сумма счета, метод оплаты и др.

Алгоритм формирования ЭЦП

ЭЦП формируется следующим образом:

  • К сформированному телу запроса (body) добавляется secretPhrase магазина (операция конкатенации)
  • Вычисляется контрольная сумма по алгоритму md5, кодировка UTF-8
  • Контрольная сумма переводится в base64

Подготовка к работе

При работе с интеграцией у вас может не быть на руках доступа к документации до момента подписания договора с поставщиком API. А как только договор подписан, то время будет идти против вас. Но что у вас точно должно быть – это ваш пошаговый процесс как вы будете интегрировать API в соответствии с MVP.

Что же нужно запросить от поставщика, чтобы как можно скорее начать работу.

  • Документация.
  • Примеры запросов на каждый пункт вашего процесса в соответствии MVP — от Авторизации до успешной выписки билета
  • Доступы в тестовую среду. Получая доступы в тестовую среду надо сразу же их проверить.
  • Доступы в production среду. Далеко не всегда вам их дадут, но если дали, то надо их проверить.
  • Договориться о кол-ве часов для воркшопа, даже если поставщик их не предоставляет. Воркшоп очень поможет вам, особенно в моментах описанных в проблеме с параметрами API. В режиме онлайн вам будет проще объяснить и показать ваши вопросы. Чтобы ваш воркшоп прошел продуктивно подготовьте повестку с детализированными вопросам, которые будете обсуждать и отправьте поставщику заранее.
  • Узнать о процессе сертификации в деталях. Процесс сертификации у каждого поставщика идет по разному. Кому-то достаточно будет только примеров запросов к API. А кто-то может потребовать полноценную тестовую среду с интерфейсом, чтобы они могли самостоятельно проверить работу API. Вы должны быть к этому готовы.
  • Договориться, кто и как будет вести вашу техническую поддержку со стороны поставщика и обменяться контактами. Если для этого выделят отдельно 2 специалистов, которые будут в курсе ваших процессов интеграции – это ускорит процесс. Не придется каждый раз объяснять ваши проблемы новому сотруднику

Ранее мы с вами говорили о том, чтобы писать клиент на основе самого сложного и разнообразного кейса в вашем процессе. Но когда вы получили доступы в тестовую среду, получили документацию и примеры запросов я советую провести тест всего процесса с минимальным количеством данных. Взять Postman или аналогичный инструмент для отправки запросов и отправить сырые запросы например (XML) от авторизации до выписки билетов. Если MVP требует реализации возвратов билетов, проверьте и их тоже. Почему это важно? На стороне поставщика не всегда все сразу настроено как положено. Для нас с вами это черный ящик, мы даже не подразумеваем какие у них есть настройки, локали, и т.д. Лучше сразу понять что не работает из всего процесса, чтобы поставщик это исправил, настроил, пока вы только начинаете интеграцию.

Пример ответа с ошибкой на запрос на возврат

Тестовые карты для проведения платежей и осуществления выплат (для тестовых магазинов Pikassa)

Перечень возможных значений статусов выплаты

PayoutSucceeded
Выплата проведена успешно

Перечень возможных значений статусов платежа

PaymentTransactionCreated
Транзакция по платежу создана

Пример запроса на получение данных

Метод позволяет по ключу доступа получить баланс данного магазина. Если магазин работает с несколькими валютами, то баланс будет получен по каждой из валют.

Пример успешного ответа на запрос на создание счета

При выставлении платежа курьерское приложение автоматически переходит в Checkout, в котором сотрудник принимает оплату любым способом: картой, наличными или по QR-коду через Систему быстрых платежей (СБП). У клиента также есть возможность расплачиваться разными способами в одном чеке. Например, часть заказа оплатить наличными, а часть — картой. При этом, курьеру не нужно переходить из своего приложения в другое — Checkout. Именно благодаря API платежное приложение вызывается автоматически.

Читайте также:  Закон о пособиях малоимущим

Размер данных

Старые API очень часто используют XMLWSDL форматы. Как по мне это устаревшие и сложные для чтениявосприятия форматы. И к тому же, они многословные, что по итогу приводит к большому объему данных. Например, некоторые GDS на результаты поиска выдают 1.6 мб данных, а если запросить результаты на соседние даты, то получится 20 мб. Это накладывает свой отпечаток на скорость обработки. Поэтому когда мы использовали библиотеку suds для обработки SOAPWSDL результатов, у нас все тормозило. Пришлось переключиться на стандартную низкоуровневую библиотеку xml. Работать с ней не так приятно, но скорость важнее. Поэтому проверьте какой объем данных вы получаете от API и сравните производительность разных библиотек.

Тоже самое касается и хранения данных. В результате бронирования нам приходит огромный пласт данных в XML. Не все эти данные нам нужны для использования в проекте, поэтому мы выделяем нужные и сохраняем в удобном нам формате. Раньше мы распределяли их по сущностям в классы с большой вложенностью, практически как в исходном XML ответе. А затем сохраняли сериализованный класс в базу. Это отстой, не делайте так. Потому что с годами ваши классы обрастают новыми методами и атрибутами, и когда спустя время вы десериализуете старую бронь у нее не будет этих методов. Лучше переводите все в JSON структуру. Весит меньше, легче читается.

Пример ответа с ошибкой на запрос на создание подписки

“Ошибка создания подписки”

Описание параметров ответа с ошибкой на запрос на создание подписки
  • Магазин отправляет в Pikassa запрос на создание счета, где указывает параметр createToken=true для создания платежного токена (см. “Создание счета”). Предварительно данную возможность необходимо согласовать с менеджером;
  • Pikassa обрабатывает запрос и, если счет создан корректно, то возвращает успешный ответ с его идентификатором (uuid) и ссылкой для оплаты счета. Счет может быть оплачен любым удобным способом – либо по платежной ссылке, либо с помощью метода оплаты счета по реквизитам банковской карты;
  • Магазин получает платежный токен в уведомлении от Pikassa об успешной оплате счета, либо в ответе на запрос данных счета.
  • Для оплаты счета по токену, Магазин отправляет в Pikassa запрос на создание счета (см. “Создание счета”);
  • Pikassa обрабатывает запрос и, если счет создан корректно, то возвращает успешный ответ с его идентификатором (uuid);
  • Магазин отправляет в Pikassa запрос на оплату счета по полученному в предыдущем пункте идентификатору с платежным токеном в объекте details;
  • Pikassa отправляет магазину уведомление об успешной/неуспешной оплате счета;
  • Магазин возвращает ответ-подтверждение о проведенной операции.

Пример запроса для оплаты счета по токену

InvoicePaymentCreated
Платеж по счету создан

InvoiceFailed
Ошибка при оплате счета

InvoicePartlyRefunded
Выполнен частичный возврат

Пример успешного ответа на запрос на отмену счета

Описание параметров элемента коллекции data

Схема проведения запроса

  • Магазин отправляет в Pikassa запрос на создание счета;
  • Pikassa обрабатывает запрос и, если счет создан корректно, возвращает данные, содержащие ссылку для перехода на оплату;
  • Плательщик переходит по ссылке, выбирает способ оплаты и вводит платежные данные;
  • Pikassa отправляет запрос на списание денежных средств эквайеру;
  • Pikassa получает ответ об успешной/неуспешной оплате счета от эквайера;
    происходит переадресация плательщика на страницу магазина

    В случае успешной оплаты счета плательщик перенаправляется на страницу, указанную при создании счета в параметре successUrl;В случае неуспешной оплаты происходит перенаправление на страницу, указанную при создании счета в параметре failUrl;

  • В случае успешной оплаты счета плательщик перенаправляется на страницу, указанную при создании счета в параметре successUrl;
  • В случае неуспешной оплаты происходит перенаправление на страницу, указанную при создании счета в параметре failUrl;
  • Pikassa отправляет магазину уведомление об успешной/неуспешной оплате счета;
    Магазин возвращает ответ-подтверждение о проведенной операции.

Метод позволяет осуществлять вывод средств на платежные средства. Pikassa предлагает следующие способы вывода: на банковскую карту, кошелек WebMoney (P, Z), кошелек ЮMoney, кошелек QIWI, мобильный телефон. Для активации возможности создавать выплаты необходимо связаться с менеджером Pikassa.

Примеры реализации алгоритма формирования x-sign

Пример на языке C#

Пример на языке PHP

Отправка данных в соответствии с ФЗ-54

Для отправки фискальных данных используется протокол, совместимый с протоколом АТОЛ; поддерживаемый провайдер данных — АТОЛ.
Для подключения возможности передавать фискальные данные необходимо сообщить данные аккаунта АТОЛ менеджеру Pikassa.
Важно: Параметры, которые не должны быть указаны в JSON схеме: timestamp, external_id, service.

Оплата счета по реквизитам банковской карты

  • Магазин отправляет в Pikassa запрос на создание счета (см. “Создание счета”);
  • Pikassa обрабатывает запрос и, если счет создан корректно, то возвращает успешный ответ с его идентификатором (uuid);
  • Магазин отображает пользователю форму ввода карточных данных для данного счета;
  • Пользователь вводит банковские реквизиты на форме магазина;
  • Магазин отправляет в Pikassa запрос на оплату счета с реквизитами банковской карты в объекте details;
  • Pikassa обрабатывает запрос и, если от пользователя требуется ввод 3DS, то в ответе возвращается ссылка для перенаправления пользователя, в противном случае переходим к пункту 9;
  • Магазин перенаправляет пользователя на страницу ввода 3DS по полученным от Pikassa данным;
  • Пользователь вводит 3DS и перенаправляется на successUrl/failUrl (в зависимости от результата), который был указан в запросе на создание счета;
  • Pikassa отправляет магазину уведомление об успешной/неуспешной оплате счета;
  • Магазин возвращает ответ-подтверждение о проведенной операции.

Пример запроса для оплаты счета по реквизитам банковской карты

Checkout уже интегрирован в систему автоматизации курьерской доставки MEASOFT. Курьеры, которые используют данный сервис для развоза заказов, принимают оплату через Checkout. Платежи проходят в соответствии с 54-ФЗ: клиенты получают чек, а налоговая — отчетность.

Пример запроса на получение данных счетов

“Ошибка создания выплаты”

Описание параметров ответа с ошибкой создания выплаты

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

Структура API-документации может отличаться, однако существует 5 стандартных блоков. Они следующие.

  • Аутентификация. Этот блок обеспечивает безопасность запросов. Система должна знать, как определить, кто именно подает запрос и как на него стоит реагировать. Это реализуемо при помощи своеобразных ключей взаимодействия и эндпоинтов для аутентификации запросов.
  • Объект. В данном случае предоставляются данные клиента. Например, это могут быть имя, адрес электронной почты, номер телефона или любая другая важная информация. Документация должна содержать список обязательных параметров в зависимости от вида и типа запроса и используемого эндпоинта. Если в технической спецификации АПИ не указаны обязательные параметры для передачи в рамках запроса, такая документация не может считаться качественной и применимой.
  • Запрос. Для подачи запросов используются HTTP-методы (создание, чтение, обновление, удаление), заголовки и полезная нагрузка запроса – непосредственно информация, с целью передачи которой он осуществляется. Важно понимание типа запроса – например, GET или POST в зависимости от того, какой процесс необходимо выполнить в рамках бизнес-задачи.
  • Ответ. На любой запрос должен поступить ответ. Он включает в себя код статуса и полезную нагрузку – информацию, которую сервер передает клиенту в ответ на запрос. Стандартно, любая качественная API-документация должна содержать примеры запроса и ответа, с разными вариантами ответа от сервера (например, коды ответа 200 (ОК) и 500 (Internal Server Error)), чтобы у разработчика, занимающегося интеграцией, возникало как можно меньше вопросов, а на построение и отправку запросов, а также дебаг по части ответов – уходили считанные минуты.
  • Тестовое окружение. Любой качественный продукт содержит раздел с тестированием, где описаны методологии и инструменты, необходимые для воспроизведения его работы перед непосредственным запуском. Если мы говорим о платежном провайдере, в разделе с тестированием должна содержаться информация о тестовых банках и картах, которые могут быть использованы с эмулятором (без реального списания средств, но с эмуляцией успешного/неуспешного проведения платежа).

Все эти блоки представляют собой определенный шаблон. Именно по нему следует ориентироваться при подготовке документации. И очень важно при этом сохранить ее читаемость. API должна оставаться понятной для разработчика. Не перегружайте ее лишней информацией.

Пример ответа с ошибкой на запрос оплаты счета

Метод позволяет запросить данные выплаты: статус выплаты, сумму, метод вывода и др.

Пример успешного ответа на запрос на создание подписки

uuid – идентификатор выплаты, полученный в успешном ответе при создании выплаты.

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

“Счет на оплату заказа №12080”

Описание параметров успешного ответа на запрос на получение данных

“Ошибка при получении данных выплаты”

Описание параметров ответа с ошибкой на запрос на получение данных

//Проверка на доступность GPay для данного устройства

//Запрос на оплату в Google Pay API

В примере продемонстрированы 2 запроса:

  • isReadyToPay() – проверка на доступность GPay для данного устройства. В примере показано, как настроить поддержку платежных карт и токенов для устройств Android для платежных систем VISA и MASTERCARD.
  • paymentDataRequest() – запрос на оплату в Google Pay API. В этом примере показано, как настроить поддержку платежных карт и токенов для устройств Android для платежных систем VISA и MASTERCARD. Токенизация карт выполняется через шлюз pikassa. Запрос способа платежа осуществляется для выставления окончательного счета на сумму 123,12 рублей.

Параметр запроса платежного адреса BillingAddressParameters – не используется.

Оцените статью