Разработчики платформ, которым требуется платежное решение, могут интегрироваться с Allpay.
Эта модель подходит платформам, которые хотят добавить Allpay как платежный метод и быть представлены в каталоге интеграций Allpay. Она не предполагает партнерских выплат и строится на взаимном продвижении (другие модели партнерства).
Такая интеграция станет доступна клиентам Allpay как готовый способ подключения вашей платформы.
Требования
Чтобы ваша платформа была добавлена в каталог интеграций Allpay, должны быть соблюдены следующие условия:
- Вы не участвуете в партнерской или реферальной программе Allpay.
Такая интеграция строится на принципе взаимного продвижения. - Интеграция должна быть предварительно согласована с Allpay.
Ваша платформа должна быть востребована в Израиле и уже использоваться реальными клиентами. - Вы готовы поддерживать интеграцию на постоянной основе.
Вы обеспечиваете работоспособность интеграции и клиентскую поддержку со своей стороны.
Как начать
Чтобы согласовать интеграцию вашей платформы, напишите в поддержку Allpay и кратко опишите:
- вашу платформу;
- кто ваши клиенты;
- как именно вы хотите использовать платежи Allpay;
- какой способ интеграции планируете: ручной или автоматизированный;
- есть ли уже клиенты, которым требуется такая интеграция.
Способы интеграции
Интеграция с Allpay может быть реализована двумя способами:
- ручная интеграция;
- автоматизированная интеграция.
Ручная интеграция
При ручной интеграции вы реализуете подключение на своей стороне и размещаете на своем сайте инструкцию для клиентов.
Клиенту потребуется:
- Открыть раздел интеграций в кабинете Allpay.
- Создать API-ключи.
- Скопировать ключи и вставить в настройках вашей платформы.
Техническое участие Allpay для такой интеграции обычно не требуется. После реализации пришлите нам информацию о вашей платформе и ссылку на инструкцию по подключению 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&display_name=DISPLAY_NAME
Где:
<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-element">display_name</span> — человекочитаемое название подключаемого аккаунта (например, логин, имя или поддомен на вашей платформе). Это значение отображается в личном кабинете Allpay в списке интеграций — передавайте то, что пользователь узнает, а не внутренний технический идентификатор. Значение должно быть закодировано через URL-encoding, максимум 255 символов.
<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
Тело запроса, который посылает Allpay:
{
"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 отмечает интеграцию как активную.
Отключение интеграции
Если пользователь отключает интеграцию на стороне вашей платформы, вы должны удалить сохраненные 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 вашей платформы. Для получения такого уведомления предоставьте endpoint на вашей стороне.
Подключение по ссылке из вашего кабинета
Подключение можно начать и на вашей стороне, а не из кабинета Allpay. Вы формируете подписанную ссылку и показываете её пользователю (кнопка в вашем кабинете):
https://allpay.to/services/endpoints/exchange.php?partner_id=<ваш id>&show=start&external_uid=<…>&state=<…>&display_name=<…>&expires=<unix>&return_url=<…>&sign=<…>
Пользователь подтверждает подключение в Allpay, Allpay отправляет ключи на ваш <span class="u-richtext-element">keys_url</span>, после чего пользователь возвращается на ваш <span class="u-richtext-element">return_url</span>.
Параметры ссылки
<span class="u-richtext-element">partner_id</span> — ваш идентификатор партнёра;
<span class="u-richtext-element">show</span> — всегда <span class="u-richtext-element">start</span>, в подписи не участвует;
<span class="u-richtext-element">external_uid</span> — идентификатор того, что подключается, на вашей платформе (например, id филиала), до 255 символов. Ссылка с более длинным значением отклоняется;
<span class="u-richtext-element">state</span> — любое значение, которое вы генерируете для этой ссылки, до 500 символов (более длинное значение обрезается). Сохраните его у себя вместе с пользователем, который запросил ссылку, и <span class="u-richtext-element">external_uid</span>. Мы вернём его в запросе на <span class="u-richtext-element">keys_url</span> и в перенаправлении на <span class="u-richtext-element">return_url</span>;
<span class="u-richtext-element">display_name</span> — что подключается (например, название филиала), до 255 символов. Необязательный параметр, но мы рекомендуем его передавать: он показывается пользователю на экране подтверждения в Allpay и в кабинете Allpay;
<span class="u-richtext-element">expires</span> — unix-время, до которого действует ссылка. Не позже чем через 30 дней от текущего момента, ссылка с более далёким сроком отклоняется;
<span class="u-richtext-element">return_url</span> — обязательный параметр; адрес, куда вернуть пользователя после успешного подключения. Только <span class="u-richtext-element">https</span>, хост должен точно совпадать с хостом вашего <span class="u-richtext-element">connect_url</span> (поддомены не подходят). Ссылка без допустимого <span class="u-richtext-element">return_url</span> отклоняется;
<span class="u-richtext-element">sign</span> — подпись ссылки. Считается по тем же правилам, что и для запросов к API. Подписываются все параметры, кроме <span class="u-richtext-element">show</span> и <span class="u-richtext-element">sign</span>.
Что происходит дальше
- Пользователь открывает ссылку и входит в Allpay, если ещё не вошёл.
- На экране Allpay он видит, какой аккаунт Allpay подключается (<span class="u-richtext-element">display_name</span>), и нажимает «Подключить».
- Allpay отправляет ключи на ваш <span class="u-richtext-element">keys_url</span> POST-запросом в формате JSON. В заголовке <span class="u-richtext-element">X-Allpay-Signature</span> передаётся HMAC-SHA256 исходного тела запроса, подписанный вашим <span class="u-richtext-element">partner_secret</span>. Поля тела запроса:
<span class="u-richtext-element">external_uid</span> — из ссылки;
<span class="u-richtext-element">state</span> — из ссылки (если вы его передали);
<span class="u-richtext-element">api_login</span>, <span class="u-richtext-element">api_key</span> — API-ключи;
<span class="u-richtext-element">token</span> — внутреннее значение, его можно игнорировать.
Ваш сервер должен ответить именно HTTP 200. - Пользователь возвращается на <span class="u-richtext-element">return_url</span> с добавленным <span class="u-richtext-element">state</span> (если вы его передали): <span class="u-richtext-element">return_url?state=<state></span>, а если в <span class="u-richtext-element">return_url</span> уже есть параметры — <span class="u-richtext-element">&state=<state></span>.
Если ваш <span class="u-richtext-element">keys_url</span> не ответил HTTP 200, подключение не выполняется, пользователь видит ошибку в Allpay, а ту же ссылку можно открыть ещё раз.
Проверьте пользователя на своей стороне
Ссылка не привязана к конкретной компании Allpay: подтвердить её может любой, кто откроет её и войдёт в Allpay.
Ключи приходят на ваш <span class="u-richtext-element">keys_url</span> раньше, чем пользователь возвращается к вам, поэтому не активируйте их сразу:
- когда придут ключи, найдите ссылку по <span class="u-richtext-element">state</span> и проверьте, что <span class="u-richtext-element">external_uid</span> совпадает;
- на <span class="u-richtext-element">return_url</span> потребуйте, чтобы пользователь был авторизован в вашем кабинете. Если нет, отправьте его на вход и затем обратно;
- проверьте, что этот <span class="u-richtext-element">state</span> выдан именно тому пользователю, который сейчас авторизован, что срок его действия не истёк и что у пользователя есть права на этот <span class="u-richtext-element">external_uid</span>. Если все проверки пройдены, активируйте ключи и пометьте <span class="u-richtext-element">state</span> использованным.
Эта проверка не защищает от случая, когда ваш пользователь подключает не тот аккаунт Allpay, например войдя под другой компанией. Если для вас это важно, покажите пользователю, какое именно подключение выполнено, до активации ключей.
Важно
Ссылка одноразовая. После успешного подключения по ней повторное открытие отклоняется, даже если подключение потом отключили. Для каждой попытки подключения формируйте новую ссылку, с новым <span class="u-richtext-element">state</span>: ссылки с полностью совпадающими параметрами (включая <span class="u-richtext-element">expires</span>) для Allpay считаются одной и той же ссылкой.
Существующее подключение никогда не заменяется. Подключение отклоняется, если:
- у компании Allpay уже есть подключение к вашей платформе, в том числе приостановленное;
- этот <span class="u-richtext-element">external_uid</span> уже подключён к любому аккаунту Allpay.
Чтобы подключить другой аккаунт, сначала отключите текущее подключение: в кабинете Allpay или запросом <span class="u-richtext-element">act=disconnect</span> с вашей стороны. Приостановленное подключение через <span class="u-richtext-element">act=disconnect</span> отключить нельзя, только в кабинете Allpay.
Открывайте и подтверждайте ссылку в одном браузере. Новая ссылка вашей платформы, открытая в той же сессии, заменяет предыдущую.
Требования безопасности
При автоматизированной интеграции необходимо соблюдать следующие требования:
- Передача только по HTTPS
Все запросы между Allpay и вашей платформой должны выполняться только по HTTPS. - Безопасное хранение ключей
Полученные <span class="u-richtext-element">api_login</span> и <span class="u-richtext-element">api_key</span> должны храниться на вашей стороне в защищенном виде. - Подпись серверных запросов
Серверные запросы должны подписываться с помощью <span class="u-richtext-element">secret_key</span>.
<span id="info">Информация для каталога интеграций</span>
После того как техническая часть завершена и интеграция работает, пришлите следующую информацию для добавления вашей платформы в каталог интеграций Allpay:
- логотип платформы в формате SVG;
- краткое описание платформы до 200 символов;
- расширенное описание платформы до 360 символов;
- контакты для технической поддержки интеграции: email и WhatsApp или Telegram;
- информацию о том, поддерживает ли ваша интеграция рассрочку, рекуррентные платежи и возвраты платежей;
- ссылку на инструкцию по подключению Allpay на вашем сайте.
Рекомендации по брендингу Allpay
Используйте корректное написание бренда:
- правильно: Allpay;
- неправильно: AllPay, All Pay, allpay.
Используйте официальный логотип Allpay.
