Платежи из кошелька Telcell на вашем сайте: настройка, тестирование и на что обратить внимание

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

Как проходит платеж Telcell

Для покупателя:

1. На вашей странице оплаты он выбирает Telcell среди способов, включенных вами для этого домена. На размещенной странице оплаты Paynet он показан как кошелек, под выбранным вами отображаемым названием.
2. Его переводят платить в Telcell, и именно там происходит все чувствительное. Через ваш сервер ничего из этого не проходит.
3. Telcell подтверждает платеж, и покупатель возвращается на return_url, указанный вами при создании платежа.
4. Ваш магазин считывает реальный статус из API и только после этого отмечает заказ оплаченным.

Для вас как продавца тот же процесс выглядит иначе. Вы создали платеж с суммой в целых драмах и своим order_id, передали покупателю checkout_url, и теперь ждете подписанный webhook, сообщающий, что платеж достиг финального статуса. Все остальное - бухгалтерия.

Что выдает вам Telcell

Вы подписываете договор с Telcell напрямую, и кошелек рассчитывается с вами по этому соглашению. Paynet не держит деньги и не перепродает договор. От Telcell вы получаете пару реквизитов:

• Shop ID
• Shop Key

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

Включение Telcell в Paynet

1. Откройте "Провайдеры", выберите "Добавить провайдера", выберите Telcell в качестве процессора, дайте ему отображаемое название и вставьте Shop ID и Shop Key.
2. Подключите этого провайдера к своему верифицированному домену. Провайдеры включаются и выключаются по доменам, так что провайдер, которого вы добавили, но не подключили, не появится ни на чьей странице оплаты.
3. Проверьте страницу "Домены". Она показывает активные способы оплаты по каждому домену и отмечает домен, у которого их нет.

Стоит знать два поведения панели управления, прежде чем они вам понадобятся:

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

Тестирование без песочницы кошелька

У Telcell нет публичной тестовой среды, как и у Idram. Отрепетировать на фиктивном Telcell невозможно. Поэтому разделите задачу на две части.

Шаг первый: проверьте свою интеграцию с помощью провайдера Sandbox. Установите провайдера Sandbox из панели управления и отправляйте "processor": "sandbox", либо создайте API-ключ в тестовой среде, который начинается с sk_test_ и превращает каждый совершенный с его помощью платеж в тестовый платеж sandbox. Ни один провайдер не задействуется, деньги не перемещаются, ничего не выставляется в счет и не засчитывается. На тестовой странице оплаты номер карты определяет результат:

• 4111 1111 1111 1111 одобрен
• 4000 0000 0000 0002 отклонен эмитентом
• 4000 0000 0000 0069 недостаточно средств
• 4000 0000 0000 0119 тайм-аут процессора
• 4000 0000 0000 0259 истек срок транзакции
• 4000 0000 0000 0309 процессор недоступен

Любой другой 16-значный номер одобряется, а срок действия, CVV и имя держателя карты не проверяются. Тестовые платежи отображаются на вкладке "Тест" в панели управления и вызывают webhook с livemode: false, так что можно проверить весь путь, включая обработку ошибок, прежде чем в дело вступит хоть один драм. Провайдер Sandbox также работает внутри плагинов CMS, так что витрину можно протестировать именно так, как ею воспользуется покупатель.

Шаг второй: проверьте реквизиты Telcell одним небольшим реальным платежом. Sandbox подтверждает, что ваш код верен. Он не может подтвердить, правильно ли введен ваш Shop Key. Когда прогон в песочнице прошел чисто, заплатите себе небольшую сумму через Telcell по-настоящему. Платежи до 500 драм бесплатны на стороне Paynet, так что репетиция ничего не стоит, кроме того, что взимает ваш собственный договор.

Подтверждение: часть, которую нужно сделать правильно

Telcell, как и Idram, не предоставляет API статуса, который можно опросить постфактум. Спросить у кошелька позже, что на самом деле произошло, невозможно, поэтому путь подтверждения должен быть надежным с первого раза.

Придерживайтесь той же дисциплины, вокруг которой построен API:

• Никогда не доверяйте перенаправлению. То, что покупатель попал на вашу страницу благодарности, доказывает лишь то, что браузер куда-то перешел, и ничего больше.
• Проверяйте подпись. X-Paynet-Signature - это шестнадцатеричный HMAC-SHA256 в нижнем регистре от необработанного тела запроса под вашим секретом webhook. Хэшируйте исходные байты, сравнивайте с постоянным временем выполнения и отклоняйте все, что не совпадает. Во время ротации секрета X-Paynet-Signature-Next в течение 24 часов несет подпись под новым секретом, так что принимайте любую из них.
• Исключайте дубли по delivery_id, затем быстро отвечайте 200. Paynet ждет 2xx-ответ 10 секунд и повторяет попытку три раза: через 1, 5 и 30 минут.
• Считывайте истину. Вызывайте GET /api/v1/orders/{order_id}/payment и действуйте на основании того, что он возвращает. Этот эндпоинт дает вам самый решающий платеж для этого заказа, так что финальная запись побеждает устаревшую ожидающую.
• Ожидайте запоздалых новостей. Неоплаченный платеж истекает через 20 минут, но запоздалое подтверждение все еще может перевести платеж со статусом failed или expired в completed. Всегда действуйте на основании последнего статуса, а не первого увиденного webhook.

Готовый к использованию код проверки на PHP и Node.js есть в справочнике по API, а тот же процесс кратко изложен на странице для разработчиков.

Возвраты и другие обещания покупателям

Прежде чем писать политику возвратов, упоминающую мгновенные отмены, проверьте, что поддерживает данный способ оплаты. Эндпоинт возврата возвращает refund_not_supported, когда процессор не может провести возврат через шлюз, и refund_in_progress, already_refunded или processor_unavailable, когда может, но момент неподходящий. Свяжите эти коды с понятной формулировкой в своей админке, чтобы сотрудники поддержки знали, стоит ли ждать или организовать перевод вручную. На стороне Paynet сами возвраты бесплатны, а возврат не восстанавливает потраченную единицу транзакции: на момент платежа он был успешным.

Telcell в плагинах магазина

Если ваш магазин работает на WooCommerce, OpenCart 2, 3 или 4, PrestaShop, Tilda или Ecwid, вам не нужно писать ничего из этого самостоятельно. Установите плагин или включите коннектор, нажмите Connect один раз, и каждый подключенный вами в Paynet процессор появится при оплате как отдельная именованная опция. Плагины относятся к webhook как к подсказке и считывают достоверный статус из вашего аккаунта Paynet, прежде чем завершить заказ, так что поддельное уведомление не может отметить заказ оплаченным. Пошаговые инструкции по каждой платформе - на странице плагинов.

Что делать дальше

• Запросите у Telcell свои Shop ID и Shop Key, если вы их еще не получили.
• Добавьте Telcell как провайдера в Paynet и подключите его к своему верифицированному домену.
• Проведите полный прогон в sandbox, включая хотя бы один отклоненный и один просроченный по тайм-ауту платеж, чтобы ваш путь обработки ошибок был реальным кодом, а не догадкой.
• Совершите один реальный платеж до 500 драм через Telcell и убедитесь, что он поступает как оплаченный в вашем магазине, в панели управления и в фискальном чеке, если активен e-HDM.
• Решите заранее, что делает ваша админка с каждым кодом ошибки возврата, прежде чем спросит клиент.
• По любым неясным вопросам пишите на [email protected].

Telcell является товарным знаком своего владельца. Paynet - независимый платежный шлюз, которым управляет ООО Digital Brains в Ереване; продавцы заключают собственные договоры с каждым кошельком и банком.