Payments with EBANX for WooCommerce — OXXO, SPEI, cards, Aplazo, Pix and Boleto

Payments with EBANX for WooCommerce connects your store to EBANX, a payment platform for Latin America. A buyer in Mexico pays cash at OXXO, by SPEI bank transfer, by card or in instalments with Aplazo, and a buyer from Brazil pays with Pix or Boleto. The order is paid and changes status by itself as soon as EBANX reports the payment.

What you need from EBANX. Your own merchant account approved by EBANX and its credentials from the Merchant Area (dashboard.ebanx.com). Sandbox and live credentials are different, and so are the cross-border account (no local company, funds settled abroad) and the local one. The integration key or the JWS key is stored encrypted and is never shown back on the page.

What the buyer gets

The checkout shows the EBANX methods available for the buyer’s country and the store currency. For a buyer from Mexico that is OXXO Pay and, in Pro, also SPEI, card and Aplazo; for a buyer from Brazil, in Pro, Pix and Boleto. A short note under the chosen method says what happens next, on both the classic and the block checkout.

OXXO Pay: after placing the order the buyer gets a voucher with a barcode and pays cash at any OXXO store. The amount, the barcode number, the date to pay by and a link to the printable voucher are on the order-received page, in My Account and in the order email. The voucher is issued in Mexican pesos (MXN) or US dollars (USD), and you set the days to pay, from 1 to 30.

What the admin gets

WooCommerce → EBANX: account type (cross-border or local), environment (sandbox or live), sign-in method (integration key or a JWS signature with a private key and Key ID) and the “Check connection” button. It tells you at once whether the credentials fit the chosen account type and environment, for example a key of the other environment. The same page shows the notification address EBANX calls to report a payment and the days to pay a voucher.

Every notification from EBANX is checked: the signature of the call is verified and the payment is read from EBANX again, with its status, amount, currency and order reference. Only then is the order paid. If the amount or the currency does not match, the order goes on hold with a note. An expired voucher cancels the order, and a refund or a chargeback leaves a note.

The order has an EBANX box: the payment hash, the status at EBANX, the amount, the barcode, the due date and the voucher link. The “Check payment status” button asks EBANX about the payment if a notification did not arrive. Everything works with HPOS and with the classic order storage.

What Pro adds

Pro adds four more ways to pay. SPEI: the buyer gets a CLABE account and a payment reference. Cards Visa, Mastercard, American Express and Carnet: the number, expiry date and name are typed at the checkout and EBANX.js turns them into a token in the buyer’s browser, so the card number never reaches your server. When EBANX returns a 3-D Secure page, the buyer is redirected to it. Aplazo: buy now, pay later; the buyer enters a CURP, confirms the plan on the Aplazo page and comes back to the store.

Pix and Boleto for Brazil: the buyer enters a CPF or CNPJ. For Pix the order-received page shows a copy-and-paste code, for Boleto a barcode and a voucher. The amount is in Brazilian reais (BRL), and the methods appear only for buyers from Brazil.

Refunds from the WooCommerce order go to EBANX: full or partial, for cards, SPEI, Aplazo and Pix, and if EBANX refuses, the reason is shown in the refund window itself. Cash vouchers of OXXO and Boleto cannot be refunded from the store.

Automation: every hour the plugin asks EBANX about unpaid orders in case a notification was lost, and the bulk action “Check EBANX payment status” in the orders list does the same for the selected ones. Cancelling an unpaid order in the store also cancels its EBANX payment, so the voucher cannot be paid any more.

How it works, step by step

1. Install the plugin and activate it (WooCommerce must be active).
2. Take the credentials in the EBANX Merchant Area and enter them in WooCommerce → EBANX: account type, environment, integration key.
3. Press “Check connection” and save the settings.
4. Enter the notification address from the same page in the EBANX Merchant Area (Account Settings → Integrations → Notification URL) if it is not set yet.
5. In WooCommerce → Settings → Payments switch on OXXO Pay (and the Pro methods you need).
6. Place a trial order and check the voucher and the order status in the EBANX box.

Under the hood

• EBANX Pay-in API (docs.ebanx.com): payment creation /ws/direct, status /ws/query, refund /ws/refund and cancellation /ws/cancel. The addresses depend on the account: api.ebanxpay.com or sandbox.ebanxpay.com for cross-border, api-local-latam.ebanxpay.com or sandbox-local-latam.ebanxpay.com for local.
• Sign-in with the integration key or with a JWS signature (RS256 with a Key ID); the JWS private key stays on your server and is stored encrypted.
• Notifications arrive as a form with operation=payment_status_change at your store address. The RSA-SHA1 signature is checked against the EBANX public key bundled in the plugin, and the payment is read from EBANX anyway and must belong to an order of this store.
• A card payment is always a single payment, with no card instalments. Debit cards that need 3-D Secure go through the page EBANX returns.
• Plugin texts: English and Spanish (Mexico). There is no Portuguese translation for Pix and Boleto.
• Compatible with HPOS, the classic and the block checkout.

Installation

1. Plugins → Add New → Upload Plugin: choose the zip and activate.
2. WooCommerce → EBANX: account type, environment, integration key, “Check connection”, save.
3. WooCommerce → Settings → Payments: switch on OXXO Pay (and the Pro methods you need).
4. Paste the notification address into the EBANX Merchant Area.
5. For Pro: paste the licence key or start the trial in the “Licence” section of the same page.