VPOS (онлайн эквайринг) в Армении: техническая интеграция
Вступление
Эта статья — часть серии про варианты приёма онлайн платежей в контексте иммиграции в Армению.
Она фокусируется на технических нюансах интеграции онлайн эквайринга (VPOS) от ArCa и банков в Армении.
3DS
3DS банками в армении поддерживается всегда, о выборе методов вам как бенефициару ЮЛ скорее всего думать не придётся.
Способ подтверждения платежа (код из SMS, push notification в приложение, биометрия) для каждой транзакции выбирает банк-эмитент карты покупателя, а не ваш банк-эквайер.
В мануале ArCa это описано следующим образом: компонент ACS валидирует плательщика на стороне эмитента. Значит, то, как тот или иной армянский банк проводит 3DS для своих выпущенных карт, не влияет на конверсию вашего онлайн экваринга (VPOS) для карт других банков: при выборе банка в Армении для ЮЛ этот фактор можно не учитывать.
Если с 3DS с иностранными картами возникают проблемы, то решаются они путём выбора Merchant of Record сервиса вроде Paddle, а не сменой банка в Армении.
Токенизация и поддержка Apple Wallet, Google Wallet
Карты ArCa добавляются в Apple Wallet и Google Wallet, и на шаге завершения оплаты у клиента будет вариант оплаты через Apple Pay или Google Pay (детальнее о них — ниже).
Для регулярных списаний потребуется вариант с поддержкой токенизации. Она описана в разделе Рекуррентные платежи и сохранение карты ниже.
Способы приёма платежей
После подключения VPOS платежи можно принимать несколькими способами. Большинство применимо и к сценариям с использованием Paddle или Юкассы, но конкретные API и нюансы UI, UX у каждого сервиса свои.
1️⃣ На сайте с помощью интеграции с помощью API, SDK
Это семейство вариантов позволяет поддерживать следующий сценарий (checkout flow): на шаге оплаты вашего сайта клиент выбирает “Оплатить”, попадает на платёжную страницу банка (ArCa), вводит данные карты, проходит подтверждение чреез 3DS и возвращается обратно на нужную страницу сайта.
Технические варианты
- Redirect (классика) — клиент уходит на полностью банковскую страницу. Безопаснее и проще, но клиент уходит с вашего домена
- Iframe — платёжная форма банка встроена в ваш сайт. Сложнее настройка, но клиент остаётся “на вашем сайте”
- Server-to-server API — клиент вводит данные карты на вашей форме. Этот вариант наболее сложный и требует реализации в соответствии PCI DSS compliance на вашей стороне
Мануал ArCa сводит это к двум сценариям:
- Реквизиты вводятся на стороне платёжного шлюза (
ipay.arca.amилиepg.arca.am— для случая с redirect либо iframe, PCI DSS compliance не требуется) - Реквизиты карты вводятся на стороне магазина: требует server-to-server взаимодействия, собственную платёжную форму, и как следствие прохождения карточных данных через ваш API — PCI DSS compliance. Для процедур регистрации заказа, оплаты, статуса, возврата (refund) вам нужно будет использовать API банка
Если на платёжной странице вы видите хост epg.arca.am, а не привычный ipay.arca.am , не стоит переживать: это та же gateway-платформа ArCa, просто разные банки используют разные хосты: через epg.arca.am работают ACBA, Ardshinbank и Inecobank.
С точки зрения технической интеграции разницы нет: меняется лишь базовый домен при работе с API банка, но не endpoints, механизм аутентификации, и прочее. Это тот же самый API, развёрнутый в другом домене.
Документация и SDK для итеграции с онлайн эквайрингом через ArCa
Главный мануал для API, использующийся ArCA, называется **Merchant[’s] Manual.** У ArCa его можно найти в открытом доступе на страницу Для интернет-магазинов.
Порядок подключения магазина к ArCa e-commerce, согласно документации ArCa, выглядит так:
- Обратиться в банк-участник за первичной информацией и настройками
- Изучить Integration Manual
- Реализовать нужный функционал в вашем приложении или на вашем сайте согласно описанному в документации процессу
- После успешного прохождения тестового окружения получить в банке настройки для production среды
2️⃣ По ссылке и через QR
Технически платёжная ссылка — это URL зарегистрированного заказа на том же шлюзе (ipay.arca.am или epg.arca.am), а QR code — просто визуальное представление этой ссылки. Отдельной интеграции для приёма “по ссылке” не нужно: это тот же эквайринг, меняется лишь способ доставки ссылки клиенту.
Если у вас нет своего сайта и он не нужен, на банковском рынке Армении есть несколько продуктов, которые позволяют принимать оплату по ссылке без какой-либо интеграции через API: Ameria PayLink, ACBA LinkPay, Converse C-PAY, ArCa Link. Они описаны несколько детальнее в другой статье про приём онлайн платежей.
3️⃣ Apple Pay и Google Pay
Поддержку этих способов оплаты продавцу нужно будет активировать лишь один раз. Возможно, что у отдельных банков они будут включены по умолчанию.
Кнопки Apple Pay, Google Pay в интерфейс позволяют избежать ввода клиентом карточных данных и подтверждение с помощью 3DS, вместо них используется биометрическая аутентификация, что упрощает и ускоряет оплату. При этом нужная карта должна быть заранее добавлена в Apple Wallet или Google Wallet.
Ameria заявляет о поддержке как Apple Pay, так и Google Pay. Ardshinbank — только Apple Pay через ArCa.
Рекуррентные (recurring, периодические) платежи и сохранение данных карты
Рекуррентные (периодические) платежи реализуются через токенизацию карты при первой оплате. Банк возвращает card token, который вы потом используете для merchant-initiated (к ним относятся и периодические) списаний.
В терминах ArCa это называется “привязкой карты” (card bindings), для чего существуют различные вариации как для привязки карты, так и последующих списаний по ней.
Поддержка зависит от банка: Ameria заявляет привязку карты и рекуррентные платежи прямо на своей e-commerce-странице, у остальных банков детали поддержки придётся уточнять при подключении.
Важнейший юридический аспект для получения подписочных (периодических) платежей: вашему приложению либо сайту нужно получить явное согласие клиента с условиями автосписания. В частности это обязательно должно быть упомянуто в Terms of Service, со ссылкой либо цитированием и на форме оплаты.
Технический аспект: первая транзакция из серии рекуррентных списаний потребует от клиента подтвердить её через 3DS. Последующие списания такого подтверждения уже не потребуют.
Использование собственной платёжной формы
Речь идёт о визуальной кастомизации формы для клиента, если вдруг вы не хотите использовать стандартную форму от ArCa либо банка.
Если вам не нужна подобная кастомизация, эту часть можно пропустить.
Если же вам важно иметь визуальную кастомизацию, уточняйте требования и процедуры выбранного банка до подписания договора.
Насколько VPOS от ArCa позволяет кастомизировать форму оплаты?
Платёжная страница хостится на стороне банка либо ArCa. Как правило онлайн эквайринг в Армении настроен так, что клиент вводит карту на этой странице, не на вашем домене. По умолчанию у ArCa это шаблон банка, поэтому страницы эквайринга разных банков могут выглядеть идентично.
Однако определенные возможности для кастомизации страницы оплаты у решения от ArCa есть. В документации ArCa в части “Оформление платежной страницы” говорится, что merchant может использовать кастомную страницу (пару страниц): payment_<locale>.html и errors_<locale>.html плюс использовать кастомные стили (CSS), изображения и скрипты. Результат передаётся банку для интеграции в виде одного архива.
Требования к разметке при этом строгие: валидный xHTML с описанием формата в виде XML DTD, разрешено использовать только относительные пути к ресурсам вроде JS, CSS и изображений, а также предоставить обязательный набор полей формы с диктуемыми ArCa именами.
Процедура тестирования и деплоя
Далее свёрстанная страница проверяется банком на тестовом сервере и мигрируется в production среду. Шаги с вёрсткой можно пропустить, если банк даёт готовую страницу для кастомизации. Именно этим путём и идёт большинство ЮЛ.
То есть любая кастомизация проходит проверку банка. Что именно банк готов пропустить, а что нет — его внутреннее решение, и у разных банков оно различается, так что если вам нужно кастомизировать страницу, уточняйте требования и процедуры выбранного банка до подписания договора.
Официальные материалы (и их отсутствие) на тему кастомизации формы оплаты
В публичных материалах банков кастомизация платёжной страницы не описана вовсе. Условия эквайринга (например, “Internet Acquiring Terms & Conditions” Ameria) регламентируют только ваш сайт и указывают, что платёжный компонент строится “как согласовано с банком” по требованиям банка и процессингового центра, а менять предоставленный банком софт мерчанту нельзя.
Единственное упоминание логотипов в условиях — требование показать на вашем сайте цветные логотипы платёжных систем (ArCa, Visa, MasterCard), а не поставить ваш логотип на страницу оплаты. В техническом мануале интеграции собственная вёрстка описана, в публичных условиях банков — нет, так что договариваться придётся индивидуально.
Прочие технические детали для разработчиков
В банке вы получаете индивидуальные настройки и credentials (сначала тестовые, потом production). Сам Integration Manual при этом публичен и является одинаковым для всех банков, см. выше.
Для начала работы вам потребуется получить credentials для доступа к песочнице у банка-эквайрера. У ArCa есть тестовое окружение с тестовыми картами. Как и у Stripe, это специальные номера карт, операции по которым будут одобряться, отклоняться, инициировать chargeback после успешной оплаты, или требовать 3DS flow в зависимости от номера. В этом инструментарий от ArCa вполне соответствует стандартному набору у MoR сервисов в индустрии.
После оплаты клиент перенаправляется на указанный returnUrl, после чего вам нужно воспользоваться ArCa e-Commerce Payment Gateway операцией getOrderStatus для подтверждения статуса заказа.
Не забывайте, что если вы используете интеграцию через server-to-server API, то есть карточные данные проходят через ваш API, вам потребуется соответствовать PCI DSS compliance, что далеко не тривиально.
API от ArCa также поддерживает двухшаговые платежи (пре-авторизация/hold с последующим списанием), отмена hold (pre-authorization reversal) и как полные, так и частичные refunds (возврат средств).
Если вы хотите отблагодарить создателей ponaehali.am
Отблагодарить наше сообщество можно, отправив донат шелтеру для животных, Armenian Food Bank и/или Teach for Armenia на любую кажущуюся вам справедливой сумму.
Есть что добавить?
Если вы проживаете или проживали в РА, и вам есть что конструктивно добавить по теме, добро пожаловать в наш чат. Вы также можете ознакомиться с самыми важными постами в сообществе.