Карты ARCA и 3-D Secure: что нужно знать интернет-продавцу в Армении

Карты по-прежнему остаются способом оплаты, который охватывает всех покупателей, включая тех, кто платит из-за рубежа в армянский магазин. В Армении такие платежи проходят через ARCA, национальную карточную сеть, и через банки-участники, которые занимаются эквайрингом. В этой статье разбираются именно те моменты, с которыми приходится иметь дело продавцу: кто что выдает, что меняет 3-D Secure, как тестировать и что API говорит о возвратах.

Кто есть кто в карточном платеже

За одной кнопкой на вашей странице оплаты стоят три стороны.

• Карточная сеть. Карты Visa, Mastercard и ArCa обрабатываются через ARCA и банки-участники, которые проводят эквайринг.
• Ваш банк-эквайер. Это тот, с кем вы подписываете договор интернет-эквайринга, кто устанавливает вашу ставку и кто перечисляет деньги на ваш счет. Ameriabank, Inecobank, Evocabank, Converse Bank, AraratBank, ACBA, AmioBank, IDBank, Ardshinbank и другие банки-участники ARCA выступают каждый как отдельный процессор, со своими реквизитами и своим вариантом оплаты.
• Шлюз. Paynet стоит перед всеми ними, чтобы ваш магазин работал с одним API и одной страницей оплаты вместо отдельной интеграции под каждый банк. Он не держит ваши деньги и не заменяет договор с банком.

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

Реквизиты, которые выдает банк

Карточные реквизиты короткие, что удивляет тех, кто ожидает целую папку файлов. Для ARCA и банков-участников, работающих на стеке ARCA, вы получаете:

• имя пользователя API
• пароль API

И это все. Адрес шлюза уже определен для каждого провайдера, так что настраивать больше нечего. Шлюз Ameriabank - единственное исключение из этого набора: он проверяет подлинность по имени пользователя, паролю и Client ID.

С банковскими реквизитами связаны две практические тонкости:

• Белый список IP-адресов. Некоторые эквайеры принимают запросы на оплату только с адресов, зарегистрированных у них для вашего мерчант-счета. Inecobank работает именно так. Поскольку договор с банком у вас, именно вы можете сделать такой запрос, а Paynet показывает точный адрес для отправки, как только вы выбираете такого провайдера. Пока банк его не зарегистрирует, каждый платеж через этого провайдера будет завершаться ошибкой, и никакой правильный код это не исправит.
• Какой вариант шлюза у вас используется. В настройках провайдера есть опция EPG, которая использует шлюз ARCA EPG вместо iPay. Если банк сообщил вам, на каком шлюзе работает ваш терминал, выставьте соответствующее значение. Если не сообщил, спросите, а не гадайте, чтобы потом не отлаживать отклоненный вход.

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

Что меняет 3-D Secure

3-D Secure - это этап, на котором банк-эмитент проверяет держателя карты перед одобрением онлайн-платежа, обычно с помощью одноразового кода или подтверждения в банковском приложении. С точки зрения продавца это меняет три вещи, и все три касаются обработки заказов, а не платежного кода.

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

Больше платежей заканчиваются статусом, который не сводится просто к "отклонено". Проверка может не пройти сама по себе, отдельно от того, действительна ли карта. Paynet явно это различает: на странице оплаты покупателю показывается "Проверка карты не пройдена. Попробуйте еще раз", и это отличается от сообщений "Карта отклонена" или "Недостаточно средств на карте". Показывайте это различие и в своей админке. Ошибку проверки обычно стоит повторить, а отказ, как правило, нет.

Со временем все становится не так аккуратно. Платеж остается открытым 20 минут до истечения срока, тогда как сама checkout_url действительна 24 часа. А запоздалое подтверждение от провайдера может перевести платеж, уже помеченный как failed или expired, в статус completed. Это не баг, который нужно обходить, а реальность покупателя, завершившего аутентификацию чуть позже, чем закончилось ваше терпение. Всегда действуйте на основании последнего прочитанного статуса, а не первого увиденного webhook, и никогда не отмечайте заказ оплаченным только потому, что браузер попал на страницу благодарности. Проверяйте подпись webhook, исключайте дубли по delivery_id, а затем считывайте истинное состояние через GET /api/v1/orders/{order_id}/payment.

В этом же семействе есть QR-вариант карточной оплаты. С ArcaQR покупатель сканирует код банковским приложением, чтобы заплатить, и код действует недолго: на странице оплаты идет обратный отсчет для QR-кода, действительного 60 секунд, а по истечении срока предлагается новый.

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

Карточные процессоры - это та часть армянского платежного ландшафта, где можно по-настоящему все отрепетировать, поскольку ARCA - единственное семейство с полноценной тестовой средой. Доступны два уровня, и нужны оба.

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

• 4111 1111 1111 1111 - одобрено
• 4000 0000 0000 0002 - отклонено эмитентом
• 4000 0000 0000 0069 - недостаточно средств
• 4000 0000 0000 0101 - ошибка 3-D Secure
• 4000 0000 0000 0119 - тайм-аут процессора
• 4000 0000 0000 0127 - превышен лимит суммы
• 4000 0000 0000 0200 - дублирующая транзакция
• 4000 0000 0000 0259 - истек срок транзакции
• 4000 0000 0000 0309 - процессор недоступен
• 4000 0000 0000 0341 - общая ошибка

Специально прогоните сценарий с ошибкой 3-D Secure и посмотрите, что видит покупатель в вашем магазине и что видит ваша служба поддержки. Эти пять минут стоят больше, чем любое количество прочитанной документации.

Собственный тестовый терминал банка - для ваших реквизитов. Провайдеры семейства ARCA поддерживают тестовый режим с отдельными тестовыми реквизитами. Банк выделяет диапазон OrderID для тестовых платежей, а вы вводите его начало и конец в настройках провайдера; тестовые платежи используют следующий незанятый номер в диапазоне и никогда не повторяют его. Если банк выдал вам тестовый терминал, используйте его до переключения провайдера в боевой режим.

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

Возвраты в описании API

Возврат - это один вызов: POST /api/v1/payments/{uuid}/refund. В теле запроса есть необязательный параметр amount, который по умолчанию равен всему оставшемуся балансу, и необязательный reason. Важны несколько правил вокруг этого.

• Полный и частичный возврат по-разному отражаются в записи. Платеж со статусом completed переходит в refunded только при полном возврате. Частичный возврат оставляет статус completed и поднимает refunded_amount выше нуля. Если ваша сверка смотрит только на статус, частичные возвраты незаметно из нее выпадут.
• Отправляйте Idempotency-Key. С ним один и тот же ключ для одного и того же платежа возвращает один и тот же возврат: 201 при создании и 200 при повторе. Без него второй вызов создает второй возврат. Если вызов возврата завершился по тайм-ауту, перед повторной попыткой считайте платеж через GET /api/v1/payments/{uuid}.
• Читайте коды ошибок, они означают разное. not_refundable, already_refunded, refund_in_progress, refund_declined, processor_unavailable и refund_outcome_unknown приходят с кодом 409, а refund_not_supported, invalid_amount и amount_exceeds_remaining - с кодом 422. Возврат с неизвестным результатом - это не то же самое, что возврат с ошибкой, и если относиться к ним одинаково, клиент рискует получить деньги дважды.
• Возвраты тоже вызывают webhook. Событие payment.refunded отправляется на callback_url платежа и содержит uuid возврата, сумму и причину.
• У ключей может быть ограниченная область доступа. API-ключ, созданный как "только платежи", может создавать и читать платежи и ссылки, но не может делать возвраты или покупать единицы, и получит 403 insufficient_scope при попытке. Такой ключ можно передать витрине или подрядчику, а ключи с полным доступом держите на собственном сервере.

Что касается стоимости, сами возвраты бесплатны. Потраченная единица транзакции не возвращается, поскольку на момент платежа он был успешным. Неудачные платежи и все тестовые платежи также ничего не стоят. Остальное - на странице тарифов.

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

• Уточните у своего банка-эквайера, какие реквизиты у вас есть: имя пользователя и пароль, а также Client ID, если вы работаете с Ameriabank, и на каком шлюзе, EPG или iPay, находится ваш терминал.
• Если банк использует белый список адресов, отправьте ему IP-адрес, показанный на экране провайдера, прежде чем что-либо тестировать.
• Добавьте провайдера в Paynet, подключите его к своему верифицированному домену и убедитесь, что домен показывает его как активный способ оплаты.
• Прогоните весь список тестовых карт от начала до конца, включая ошибку 3-D Secure, и убедитесь, что ваша админка различает ошибки проверки и отказы.
• Решите в коде, как вы обрабатываете запоздалое подтверждение и возврат с неизвестным результатом.
• Полный справочник по эндпоинтам, включая возвраты и webhook, находится на paynet.am/docs/api, а краткий обзор - на странице для разработчиков.

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