Как интегрировать вашу платформу с Allpay

Разработчики платформ, которым требуется платежное решение, могут интегрироваться с Allpay.

Такая интеграция может быть добавлена в раздел интеграций Allpay на сайте и в приложении. Она станет доступна клиентам Allpay как готовый способ подключения вашей платформы.

Эта статья в процессе создания.

Требования

Чтобы ваша платформа была добавлена в каталог интеграций Allpay, должны быть соблюдены следующие условия:

1. Вы не участвуете в партнерской или реферальной программе Allpay.
   ‍Такая интеграция строится на принципе взаимного продвижения.
2. Интеграция должна быть предварительно согласована с Allpay.
   ‍Ваша платформа должна быть востребована в Израиле и уже использоваться реальными клиентами.
3. Поддержка интеграции.
   Обеспечение работоспособности интеграции и клиентской поддержки на постоянной основе.

Как начать

Чтобы согласовать интеграцию вашей платформы, напишите в поддержку Allpay и кратко опишите:

• вашу платформу;
• кто ваши клиенты;
• как именно вы хотите использовать платежи Allpay;
• какой способ интеграции планируете: ручной или автоматизированный;
• есть ли уже клиенты, которым требуется такая интеграция.

Способы интеграции

Интеграция с Allpay может быть реализована двумя способами:

• ручная интеграция;
• автоматизированная интеграция.

Ручная интеграция

При ручной интеграции вы реализуете подключение на своей стороне и размещаете на своем сайте инструкцию для клиентов.

Клиенту потребуется:

1. Открыть раздел интеграций в кабинете Allpay.
2. Создать API-ключи.
3. Скопировать ключи и вставить в настройках вашей платформы.

Техническое участие Allpay для такой интеграции обычно не требуется. После того как интеграция реализована на вашей стороне, пришлите нам информацию о вашей платформе. Мы проверим ее и после согласования добавим вашу платформу в каталог интеграций Allpay.

Автоматизированная интеграция

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

Перед началом реализации Allpay выдает вашей платформе:

<span class="u-richtext-element">partner_id</span> — индивидуальный номер интеграции;

<span class="u-richtext-element">secret_key</span> — секретный ключ для подписи и проверки серверных запросов.

<span class="u-richtext-counter">1</span>Переход из Allpay на страницу вашей платформы

Пользователь открывает в кабинете Allpay раздел<span class="u-richtext-element">Настройки</span> → <span class="u-richtext-element"> Интеграции</span> → <span class="u-richtext-element"> Ваша платформа</span> и нажимает кнопку подключения.

Allpay генерирует одноразовый токен для связки аккаунтов и перенаправляет пользователя на страницу подтверждения на стороне вашей платформы, например:

https://your-platform.com/connect?token=TOKEN

Где <span class="u-richtext-element">TOKEN</span> — одноразовый токен, созданный Allpay.

Стандартный срок действия токена — 1 час.

<span class="u-richtext-counter">2</span>Подтверждение подключения на стороне вашей платформы

На вашей стороне пользователь подтверждает подключение под своим аккаунтом.

После подтверждения ваша платформа перенаправляет пользователя обратно на универсальный endpoint Allpay:

https://allpay.to/services/endpoints/exchange.php?act=connect&partner_id=PARTNER_ID&token=TOKEN&external_uid=USER_ID

Где:

<span class="u-richtext-element">act=connect</span> — действие подключения интеграции;

<span class="u-richtext-element">partner_id</span> — индивидуальный номер интеграции;

<span class="u-richtext-element">token</span> — одноразовый токен, созданный Allpay;

<span class="u-richtext-element">external_uid</span> — внутренний идентификатор пользователя на вашей платформе.

<span class="u-richtext-counter">3</span>Создание и передача API-ключей на вашу платформу

После проверки токена Allpay связывает пользователя Allpay с пользователем вашей платформы и отправляет API-ключи <span class="u-richtext-element">api_login</span> и <span class="u-richtext-element">api_key</span> на ваш endpoint.

Пример endpoint на стороне вашей платформы:

POST https://your-platform.com/allpay/partner/exchange

Тело запроса:

{  
  "external_uid": "USER_ID",  
  "api_login": "API_LOGIN",  
  "api_key": "API_KEY",  
  "sign": "SIGNATURE"
}

Где:

<span class="u-richtext-element">external_uid</span> — идентификатор пользователя на вашей платформе;

<span class="u-richtext-element">api_login</span> — API login пользователя Allpay;

<span class="u-richtext-element">api_key</span> — API key пользователя Allpay;

<span class="u-richtext-element">sign</span> — подпись запроса.

<span class="u-richtext-counter">4</span>Подпись запроса

Серверный запрос с API-ключами подписывается с помощью HMAC SHA-256.

Формат подписи:

hash_hmac('sha256', $payload_json, $secret_key);

Где:

<span class="u-richtext-element">$payload_json</span> — JSON-тело запроса;

<span class="u-richtext-element">$secret_key</span> — индивидуальный секретный ключ.

<span class="u-richtext-counter">5</span>Ответ вашей платформы

После успешного получения и сохранения ключей ваша платформа должна вернуть успешный ответ, например:

{  
"ok": true
}

После этого Allpay отмечает интеграцию как активную.

Что нужно подготовить на стороне вашей платформы

Для автоматизированной интеграции вам потребуется подготовить:

1. Страницу подтверждения подключения
   На эту страницу Allpay будет перенаправлять пользователя после нажатия кнопки подключения.
2. Редирект обратно в Allpay после подтверждения
   После подтверждения подключения ваша платформа должна вернуть пользователя в Allpay, передав <span class="u-richtext-element">partner_id</span>, <span class="u-richtext-element">token</span> и <span class="u-richtext-element">external_uid</span>.
3. Endpoint для приема API-ключей
   ‍На этот endpoint Allpay отправит <span class="u-richtext-element">api_login</span> и <span class="u-richtext-element">api_key</span> пользователя.
4. Безопасное хранение API-ключей
   Полученные ключи должны храниться на вашей стороне в защищенном виде.
5. Обработку успешного и неуспешного подключения
   Ваша платформа должна корректно обрабатывать случаи, когда подключение завершилось успешно, было отменено пользователем или завершилось ошибкой.

Требования безопасности

При автоматизированной интеграции необходимо соблюдать следующие требования:

1. Передача только по HTTPS
   Все запросы между Allpay и вашей платформой должны выполняться только по HTTPS.
2. Подпись серверных запросов
   Серверный запрос с API-ключами должен быть подписан с помощью HMAC SHA-256 или другого согласованного механизма подписи.
3. Безопасное хранение ключей
   ‍Полученные <span class="u-richtext-element">api_login</span> и <span class="u-richtext-element">api_key</span> должны храниться на вашей стороне в защищенном виде.
4. Активация только после успешного обмена ключами
   Интеграция не должна считаться активной только после перехода пользователя по ссылке. Статус подключения должен меняться на активный после успешной передачи и сохранения API-ключей.

Отключение интеграции

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

Дополнительно ваша платформа должна отправить в Allpay POST-запрос на отключение интеграции:

POST https://allpay.to/services/endpoints/exchange.php?act=disconnect&partner_id=PARTNER_ID

Тело запроса:

{  
  "external_uid": "USER_ID",  
  "sign": "SIGNATURE"
}

Где:

<span class="u-richtext-element">external_uid</span> — идентификатор пользователя на вашей платформе;

<span class="u-richtext-element">sign</span> — подпись запроса.

Запрос на отключение также подписывается с помощью <span class="u-richtext-element">secret_key</span>.

Если пользователь отключает интеграцию из кабинета Allpay, Allpay может отправить уведомление об отключении на endpoint вашей платформы. Формат такого запроса согласовывается отдельно.

<span id="info">Информация для каталога интеграций</span>

После того как техническая часть завершена и интеграция работает, пришлите следующую информацию для добавления вашей платформы в каталог интеграций Allpay:

• логотип платформы в формате SVG;
• краткое описание платформы до 200 символов;
• расширенное описание платформы до 360 символов;
• контакты для технической поддержки интеграции: email и WhatsApp или Telegram;
• информацию о том, поддерживает ли ваша интеграция рассрочку, рекуррентные платежи и возвраты платежей;
• ссылку на инструкцию по подключению Allpay на вашем сайте.

Рекомендации по брендингу Allpay

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

• правильно: Allpay;
• неправильно: AllPay, All Pay, allpay.

Используйте официальный логотип Allpay.