EBANX для WooCommerce — OXXO, SPEI, карты, Aplazo, Pix и Boleto

EBANX для WooCommerce подключает магазин к EBANX, платёжной платформе для Латинской Америки. Покупатель в Мексике платит наличными в OXXO, переводом SPEI, картой или в рассрочку через Aplazo, а покупатель из Бразилии — через Pix или Boleto. Заказ оплачивается и меняет статус сам, как только EBANX сообщает о платеже.

Что нужно от EBANX. Собственный мерчант-аккаунт, одобренный EBANX, и его учётные данные из Merchant Area (dashboard.ebanx.com). Данные песочницы и боевые разные, так же как и аккаунт cross-border (без местной компании, средства рассчитываются за рубежом) и local. Ключ интеграции или ключ JWS хранится в базе в зашифрованном виде и обратно на странице не показывается.

Что получает покупатель

На кассе появляются методы EBANX, доступные для страны покупателя и валюты магазина. Для покупателя из Мексики это OXXO Pay, а в Pro ещё SPEI, карта и Aplazo; для покупателя из Бразилии в Pro — Pix и Boleto. Под выбранным методом коротко написано, что будет дальше, и это работает и на обычной, и на блочной кассе.

OXXO Pay: после оформления покупатель получает ваучер со штрихкодом и платит наличными в любом OXXO. Сумма, номер штрихкода, дата, до которой можно заплатить, и ссылка на ваучер для печати есть на странице благодарности, в «Моём аккаунте» и в письме о заказе. Счёт выставляется в песо (MXN) или долларах (USD), а количество дней на оплату от 1 до 30 вы задаёте сами.

Что получает админ

WooCommerce → EBANX: тип аккаунта (cross-border или local), среда (песочница или боевая), способ входа (ключ интеграции или подпись JWS с ключом и Key ID) и кнопка «Check connection». Она сразу показывает, подходят ли данные к выбранному типу аккаунта и среде: чужой это тип или ключ другой среды. Здесь же адрес уведомлений, который вызывает EBANX, чтобы сообщить об оплате, и количество дней на оплату ваучера.

Каждое уведомление от EBANX проверяется: подпись вызова сверяется, а платёж заново читается из EBANX — статус, сумма, валюта и номер заказа. Только после этого заказ считается оплаченным. Если сумма или валюта не совпадают, заказ уходит «на удержание» с заметкой. Просроченный ваучер отменяет заказ, а возврат средств и чарджбэк оставляют заметку.

В заказе есть блок EBANX: хеш платежа, статус в EBANX, сумма, штрихкод, срок и ссылка на ваучер. Кнопка «Check payment status» спрашивает у EBANX о платеже, если уведомление не дошло. Всё работает и с HPOS, и с обычным хранилищем заказов.

Что добавляет Pro

В Pro добавляются ещё четыре способа оплаты. SPEI: покупатель получает счёт CLABE и референс платежа. Карты Visa, Mastercard, American Express и Carnet: номер, срок действия и имя на карте вводятся на кассе, а токен создаёт EBANX.js в браузере покупателя, так что номер карты не попадает на ваш сервер. Если EBANX возвращает страницу для 3-D Secure, покупателя перенаправляет на неё. Aplazo: покупай сейчас, плати потом; покупатель вводит CURP и подтверждает план на странице Aplazo, а потом возвращается в магазин.

Pix и Boleto для Бразилии: покупатель вводит CPF или CNPJ. Для Pix на странице благодарности показывается код для копирования, для Boleto — штрихкод и ваучер. Сумма выставляется в реалах (BRL), а методы появляются только для покупателей из Бразилии.

Возвраты из заказа WooCommerce уходят в EBANX: полный или частичный, для карт, SPEI, Aplazo и Pix, а отказ EBANX показан причиной в самом окне возврата. Для наличных ваучеров OXXO и Boleto возврат из магазина не предусмотрен.

Автоматика: каждый час плагин спрашивает у EBANX о неоплаченных заказах, если уведомление потерялось, а массовое действие «Check EBANX payment status» в списке заказов делает то же для выбранных. Отмена неоплаченного заказа в магазине отменяет и платёж в EBANX, так что ваучер больше нельзя оплатить.

Как это работает, шаг за шагом

1. Устанавливаете плагин и включаете его (WooCommerce должен быть активен).
2. В Merchant Area EBANX берёте учётные данные и вписываете их в WooCommerce → EBANX: тип аккаунта, среда, ключ интеграции.
3. Нажимаете «Check connection» и сохраняете настройки.
4. Адрес уведомлений с этой же страницы вписываете в Merchant Area EBANX (Account Settings → Integrations → Notification URL), если он ещё не стоит.
5. В WooCommerce → Настройки → Платежи включаете OXXO Pay (и методы Pro, если они нужны).
6. Оформляете пробный заказ, проверяете ваучер и статус заказа в блоке EBANX.

Что под капотом

• Pay-in API EBANX (docs.ebanx.com): создание платежа /ws/direct, статус /ws/query, возврат /ws/refund и отмена /ws/cancel. Адреса зависят от аккаунта: api.ebanxpay.com или sandbox.ebanxpay.com для cross-border, api-local-latam.ebanxpay.com или sandbox-local-latam.ebanxpay.com для local.
• Вход через ключ интеграции или через подпись JWS (RS256 с Key ID), приватный ключ JWS остаётся на вашем сервере и хранится зашифрованным.
• Уведомления приходят формой operation=payment_status_change на адрес вашего магазина. Подпись RSA-SHA1 сверяется с открытым ключом EBANX, который идёт в плагине, а платёж всё равно читается из EBANX и должен принадлежать заказу этого магазина.
• Оплата картой всегда одним платежом, без рассрочки по карте. Дебетовые карты, требующие 3-D Secure, проходят через страницу, которую возвращает EBANX.
• Тексты плагина: английский и испанский (Мексика). Для Pix и Boleto португальского перевода нет.
• Совместимо с HPOS, обычной и блочной кассой.

Как установить

1. Плагины → Добавить новый → Загрузить плагин: выберите zip и активируйте.
2. WooCommerce → EBANX: тип аккаунта, среда, ключ интеграции, «Check connection», сохранение.
3. WooCommerce → Настройки → Платежи: включите OXXO Pay (и методы Pro, если нужны).
4. Вставьте адрес уведомлений в Merchant Area EBANX.
5. Для Pro: вставьте лицензионный ключ или запустите пробный период в разделе «Licence» на той же странице.