Payment Gateways: Americas

This page covers the gateways for North and Latin America: Square, Authorize.net, NMI, Clover, Elavon Converge and Mercado Pago. See Payment Gateways for how these gateways work in general and for the general go-live checklist.

Square

For merchants with a Square account in the US, Canada, UK, Ireland, France, Spain, Australia or Japan. The customer pays on a Square hosted checkout page (a Quick Pay payment link) with a card, Apple Pay, Google Pay, Cash App Pay or Afterpay/Clearpay. Supported currencies: USD, CAD, GBP, EUR, AUD and JPY. The store currency must also be the currency of your Square location.

Available from v3.13.0

payment_gateway="square"

Setup

Do these steps once in the sandbox and once in production.

1. Log in to the Square Developer Console and open your application (or create one).
2. Under Credentials, copy the Access token (sandbox or production).
3. Under Locations, copy the Location ID of the location that receives the payments. Its currency must match the store currency.
4. Under Webhooks → Subscriptions, add a subscription, see Webhook below.

Then configure Square in the payment gateway settings in the CP:

Field	Description
Debug mode	On uses the sandbox fields, off uses the production fields
Additional payment methods	Apple Pay, Google Pay, Cash App Pay, Afterpay / Clearpay. Cards are always accepted. When none are selected, the defaults of your Square account are used
Sandbox Access Token	Developer Console → your application → Credentials (sandbox)
Sandbox Location ID	Developer Console → your application → Locations (sandbox)
Sandbox Webhook Signature Key	The signature key of the sandbox webhook subscription
Production Access Token	Developer Console → your application → Credentials (production)
Production Location ID	Developer Console → your application → Locations (production)
Production Webhook Signature Key	The signature key of the production webhook subscription

Webhook

In the Developer Console, go to Webhooks → Subscriptions and add a subscription with the notify URL shown in the CP as the notification URL, and the events payment.created and payment.updated. Copy the Signature key of the subscription into the matching Webhook Signature Key field in the CP.

The signature is calculated over the notification URL, so the URL in Square must be exactly the notify URL from the CP.

Without a signature key, webhooks are still processed (the payment is always fetched from the Square API) and an error is logged. With a wrong key, webhooks are refused (webhook verification failed). Webhooks for payments that do not belong to a store order, such as in-store payments, are ignored.

How the payment works

• On checkout, the module creates a payment link for the order total (one line for the whole order) and sends the customer to Square.
• After paying, the customer returns to your site. The module fetches the Square order and its payment: a completed payment makes the order complete, an approved or pending payment makes it pending.
• A declined or failed attempt leaves the order as it is: the customer can try again on the same payment link.
• Square's checkout has no cancel link. An abandoned payment leaves the order open.
• Refunds from the CP refund the full order amount. A refund made in the Square Dashboard also reaches the store via the payment.updated webhook and sets the order to refunded.

Limitations

• Only USD, CAD, GBP, EUR, AUD and JPY, and only the currency of the Square location.
• Square does not ask for a shipping address; the address from your checkout is used.

Test checklist

• [ ] Square adds its own parameters (such as ?orderId=...) to the return URL. Check that the customer still lands on the order page after paying.
• [ ] Refund a payment in test mode, and check that the payment.updated webhook arrives and the order becomes refunded.
• [ ] The store currency is the same as the currency of the Square location; otherwise Square refuses the payment link.
• [ ] Use the Square sandbox test cards for successful and declined payments.

Authorize.net

For merchants with an Authorize.net account in the US, Canada, UK, Europe or Australia. The customer pays on the Authorize.net Accept Hosted payment form, by card or (optionally) eCheck. Supported currencies: USD, CAD, GBP, EUR, AUD, NZD, CHF, DKK, NOK, PLN and SEK, but an Authorize.net account has a single currency, so the store currency must be the currency of your account.

Available from v3.13.0

payment_gateway="authorize_net"

Setup

Do these steps once in the sandbox and once in your production account.

1. Log in to the Merchant Interface (or the sandbox).
2. Go to Account → Settings → API Credentials & Keys and get the API Login ID, a Transaction Key and a Signature Key.
3. Go to Account → Settings → Transaction Details API and enable it. The module uses this API to look up every payment; without it orders never complete.
4. Go to Account → Webhooks and add the webhook, see Webhook below.
5. If you want to accept eCheck, it must also be enabled on your Authorize.net account.

Then configure Authorize.net in the payment gateway settings in the CP:

Field	Description
Debug mode	On uses the sandbox fields, off uses the production fields
Available payment methods	Card and/or eCheck (bank account). eCheck must also be enabled on your Authorize.net account. Defaults to cards
Sandbox API Login ID	Account → Settings → API Credentials & Keys (sandbox)
Sandbox Transaction Key	Account → Settings → API Credentials & Keys (sandbox)
Sandbox Signature Key	Account → Settings → API Credentials & Keys (sandbox). Used to verify the webhooks
Production API Login ID	Account → Settings → API Credentials & Keys
Production Transaction Key	Account → Settings → API Credentials & Keys
Production Signature Key	Account → Settings → API Credentials & Keys. Used to verify the webhooks

Webhook

In the Merchant Interface, go to Account → Webhooks and add an endpoint with the notify URL shown in the CP and the events net.authorize.payment.authcapture.created, net.authorize.payment.fraud.approved and net.authorize.payment.fraud.held. The webhooks are signed with the Signature Key you entered in the CP.

Without a Signature Key, webhooks are still processed (the transaction is always fetched from the API) and an error is logged. With a wrong key, webhooks are refused (webhook verification failed). Declined attempts and transactions that do not belong to a store order (for example from the Virtual Terminal) are ignored.

How the payment works

• On checkout, the customer's browser is sent (with a form POST) to the Authorize.net payment form for the order total.
• After paying, Authorize.net shows its receipt; the Continue button brings the customer back to your site. Cancel brings the customer back to the checkout and the order becomes cancelled.
• The order is linked by its invoice number. If the customer returns before the webhook, the module looks the payment up in the unsettled transactions. A captured or settled payment makes the order complete; a payment held for review makes it pending.
• A declined card can be retried on the payment form.
• Refunds from the CP are for the full order amount. A transaction that is not settled yet is voided instead of refunded. eCheck payments are refunded to the same bank account.
• A refund made in the Merchant Interface does not update the order in the store (there is no refund webhook); use the CP to refund.

Limitations

• An Authorize.net account is single-currency: the store currency must match the account currency.
• A transaction that is neither settled nor waiting for settlement (for example a refund in progress) cannot be refunded from the CP.

Test checklist

• [ ] The Transaction Details API is enabled (Account → Settings). Without it, orders never become complete.
• [ ] Webhook signature verification works with your Signature Key: after a test payment the Store log shows no webhook verification failed error.
• [ ] If you offer eCheck, test an eCheck payment and an eCheck refund.
• [ ] The store currency is the currency of your Authorize.net account (an account supports only one currency).
• [ ] A refund right after the payment (a void) and a refund after settlement both work.
• [ ] Use the test cards and bank accounts from the Authorize.net testing guide.

NMI

For merchants in the US and Canada with NMI, or with a processor or ISO that offers a white-label NMI gateway. The customer pays on NMI's hosted QuickClick checkout page, by card or eCheck. Supported currencies: USD and CAD.

Available from v3.13.0

payment_gateway="nmi"

Setup

1. Log in to the NMI Merchant Control Panel of your (white-label) gateway.
2. Under Settings → Security Keys, create an API key with Query API access, and a QuickClick verification key (you get a key ID and a key text).
3. Under Settings → QuickClick → Security, enable Require that all values be verified using a security key.
4. Make sure no QuickClick tax or shipping is configured in NMI: the order total from the store already includes them.
5. Under Settings → Webhooks, add the webhook, see Webhook below.

QuickClick must be available on your gateway. Some white-label gateways do not offer it; ask your processor if you cannot find it.

Then configure NMI in the payment gateway settings in the CP:

Field	Description
Debug mode	On uses the test fields, off uses the live fields (for example of a merchant account in test mode)
Gateway host	The host of your (white-label) NMI gateway, for example secure.nmi.com or secure.yourprocessorgateway.com. Defaults to secure.nmi.com
Test API Security Key	The API key (with Query API access) of your test account
Test QuickClick Key ID	The key ID of the QuickClick verification key of your test account
Test QuickClick Key Text	The key text of the QuickClick verification key of your test account
Test Webhook Signing Key	The signing key of the webhook of your test account
Live API Security Key	Settings → Security Keys: the API key with Query API access
Live QuickClick Key ID	Settings → Security Keys: the key ID of the QuickClick verification key
Live QuickClick Key Text	Settings → Security Keys: the key text of the QuickClick verification key
Live Webhook Signing Key	Settings → Webhooks: the signing key

Webhook

In the Merchant Control Panel, go to Settings → Webhooks and add the notify URL shown in the CP with the events transaction.sale.success, transaction.refund.success and transaction.void.success. Copy the signing key into the matching Webhook Signing Key field in the CP.

Without a signing key, webhooks are still processed (the transaction is always looked up via the Query API) and an error is logged. With a wrong key, webhooks are refused (webhook verification failed). Transactions that were not started by the store are ignored.

How the payment works

• On checkout, the customer's browser is sent (with a form POST) to the QuickClick page with a fixed amount. The amount and currency are protected by the verification key and cannot be changed in the browser.
• After paying, NMI sends the customer back to your site with a POST. The module looks the payment up via the Query API and checks the amount and currency. A paid transaction makes the order complete; an authorization without capture makes it pending.
• A declined card can be retried on the QuickClick page.
• QuickClick has no cancel URL: an abandoned payment leaves the order open.
• Refunds from the CP are for the full order amount. A transaction that is not settled yet is voided. Refunds and voids done in NMI also reach the store via the webhook: a refund sets the order to refunded.
• A returned eCheck or a chargeback sets the order to paid (chargeback).

Limitations

• Only USD and CAD.
• QuickClick tax and shipping in NMI must be off, otherwise the customer pays more than the order total.
• QuickClick must be available on your gateway.

Test checklist

• [ ] QuickClick is available on your (white-label) gateway and in your test or sandbox account.
• [ ] After paying, the POST back from NMI lands the customer on the order page.
• [ ] QuickClick tax and shipping are off in NMI: the amount on the QuickClick page equals the order total.
• [ ] A declined card can be retried on the QuickClick page, and the retry completes the order.
• [ ] A refund (from the CP, and from NMI) shows up correctly: the order becomes refunded.
• [ ] An abandoned payment leaves the order open (QuickClick has no cancel URL).
• [ ] For test cards and amounts that trigger a decline, see the testing information in the NMI integration portal or ask your processor.

Clover

For Clover (Fiserv) merchants in the US and Canada. The customer pays on the Clover Hosted Checkout page, by card or with the wallets enabled on your Clover merchant. Supported currencies: USD and CAD; Clover always charges in the currency of your merchant account, so the store currency must match it.

Available from v3.13.0

payment_gateway="clover"

Setup

Do these steps once in the sandbox Merchant Dashboard and once in the live one.

1. Log in to the Clover Merchant Dashboard.
2. Go to Account & Setup → Ecommerce → Ecommerce API Tokens and create a private token for the Hosted Checkout integration.
3. Note the Merchant ID, shown under Account & Setup → Merchants.
4. Go to Ecommerce → Hosted Checkout. Leave the Redirect URLs empty: URLs entered there override the ones the module sends with each payment.
5. On the same page, set up the webhook, see Webhook below.

Then configure Clover in the payment gateway settings in the CP:

Field	Description
Debug mode	On uses the sandbox environment and the test fields, off uses the live fields
Test Merchant ID	Account & Setup → Merchants (sandbox)
Test Private Token	Account & Setup → Ecommerce → Ecommerce API Tokens: the private token (sandbox)
Test Webhook Signing Secret	Ecommerce → Hosted Checkout: the signing secret (sandbox). Required
Live Merchant ID	Account & Setup → Merchants
Live Private Token	Account & Setup → Ecommerce → Ecommerce API Tokens: the private token
Live Webhook Signing Secret	Ecommerce → Hosted Checkout: the signing secret. Required

Webhook

The webhook is required for this gateway. Clover has no API to look up a checkout session, so only the webhook tells the module which payment belongs to the order.

In the Merchant Dashboard, go to Ecommerce → Hosted Checkout, enter the notify URL shown in the CP as the Webhook URL, click Generate and copy the Signing Secret into the matching Webhook Signing Secret field in the CP.

Without a signing secret, every webhook is refused and an error is logged (no webhook signing secret configured, refusing the webhook): orders then never become complete. Webhooks with an invalid signature or of another merchant are refused; declined attempts are ignored.

How the payment works

• On checkout, the module creates a Hosted Checkout session for the order total and sends the customer to Clover.
• When the customer returns before the webhook has arrived, the order becomes pending. The webhook then completes it: the module fetches the payment (charge) from the Clover Ecommerce API, checks the amount and currency, and sets the order to complete.
• A declined card can be retried on the Clover page, up to 5 attempts. After the 5th declined attempt, or when the customer cancels, the customer returns to the checkout and the order becomes cancelled.
• The customer may add a tip on the Clover page, so the charge can be higher than the order total.
• Refunds from the CP refund the order total. A refund made in Clover does not update the order in the store.

Limitations

• Only USD and CAD, in the currency of your Clover merchant account.
• Tips are not refunded: a refund is always for the order total.
• The Redirect URLs in the Hosted Checkout settings must stay empty.

Test checklist

• [ ] The Webhook Signing Secret is set. Without it, webhooks are refused and orders never complete.
• [ ] The payment id from the webhook works: after a test payment the order becomes complete, and a refund from the CP succeeds.
• [ ] The Redirect URLs in the Hosted Checkout dashboard are empty (URLs entered there override the module's URLs).
• [ ] A customer who returns before the webhook sees the order as pending, and the webhook then completes it.
• [ ] Tips are not refunded: a refund is for the order total only.
• [ ] Use the Clover test card numbers in the sandbox.

Elavon Converge

For merchants with an Elavon Converge account in the US or Canada. The customer pays by card on the Converge Hosted Payments Page. Payments are in the currency of your terminal (USD or CAD), or in the order currency if your terminal has the Multi Currency option. Converge in Europe has been replaced by the Elavon Payment Gateway, which this gateway does not support.

Available from v3.13.0

payment_gateway="converge"

Setup

1. Ask Elavon to:

   • enable the Hosted Payments Page on your account;
   • create a user with Hosted Payment API User status;
   • allowlist the IP address of your server.

   Elavon also provides the demo account for testing.

2. In Converge, go to Settings → Hosted Payments → Setup for Payment Page and set the Redirect URL (POST) to the notify URL shown in the CP, with method=notify replaced by method=redirect. For example, ...&method=notify&gateway=converge becomes ...&method=redirect&gateway=converge.

3. Optionally, ask Elavon to add an export script that POSTs to the notify URL shown in the CP, see Webhook below.

Then configure Elavon Converge in the payment gateway settings in the CP:

Field	Description
Debug mode	On uses the Converge demo environment and the test fields, off uses the live fields
Terminal currency	The currency of your Converge terminal (USD or CAD)
Multi-currency	Only enable when your terminal has the Multi Currency option; the order currency is then sent to Converge
Test Account ID	The Converge Account ID (formerly Merchant ID) of the demo account
Test User ID	The Hosted Payment API user of the demo account
Test PIN	The PIN of that user
Live Account ID	The Converge Account ID (formerly Merchant ID)
Live User ID	The Hosted Payment API user
Live PIN	The PIN of that user

Webhook

Converge has no signed webhooks. The customer's return to the Redirect URL is what completes the order. As a backup, Elavon can add an export script that POSTs each transaction to the notify URL shown in the CP; ask Elavon for this. Without it, an order only completes when the customer returns to your site.

The data Converge posts (to the Redirect URL or the export script) is not signed. The module only uses the transaction id from it and looks the transaction up with the Converge XML API (txnquery), which must report this order's invoice number, at least the order total and the order currency.

How the payment works

• On checkout, the module requests a session token (valid for 15 minutes) and sends the customer's browser (with a form POST) to the Hosted Payments Page.
• After paying, Converge posts the result to the Redirect URL. The module looks the transaction up and sends the customer to the order page. An approved transaction makes the order complete; a transaction pended by the merchant or in review makes it pending.
• A declined card leaves the order as it is: the customer can try again.
• The module sends no cancel URL: an abandoned payment leaves the order open.
• Refunds from the CP are for the full order amount: a void while the transaction is in the open batch, a return once it is settled. A refund made in Converge does not update the order.

Limitations

• USD or CAD (the terminal currency). Other currencies only with a Multi Currency terminal and the Multi-currency setting on.
• Only the US and Canada (Converge, not the Elavon Payment Gateway).
• The Redirect URL is set per terminal in Converge, not per payment.

Test checklist

• [ ] Elavon has enabled the Hosted Payments Page, created a Hosted Payment API user and allowlisted your server's IP address (in the demo and the live account).
• [ ] The Redirect URL in Converge is the notify URL with method=notify replaced by method=redirect, and after paying the customer lands on the order page.
• [ ] The transaction lookup (txnquery) works: after a test payment the order becomes complete (no API error on txnquery in the Store log).
• [ ] Only enable Multi-currency if your terminal supports it; test a payment in each currency you sell in.
• [ ] A refund right after the payment (a void) works.
• [ ] Ask Elavon for the test cards of the demo environment.

Mercado Pago

For merchants in Latin America with a Mercado Pago account. The customer pays on Mercado Pago's Checkout Pro page with cards, Pix, boleto, OXXO, the Mercado Pago wallet and the other methods available in your country. The currency is not limited by the module; use the currency of your Mercado Pago account's country.

Available from v3.13.0

payment_gateway="mercado_pago"

Setup

1. Log in to Mercado Pago Developers and open your application (or create one).
2. Copy the Access Token from the test credentials and from the production credentials.
3. Under Webhooks, enable the Payments event and copy the secret signature, see Webhook below.

Then configure Mercado Pago in the payment gateway settings in the CP:

Field	Description
Debug mode	On uses the test access token and the sandbox checkout, off uses the live fields
Available payment types	Credit card, debit card, prepaid card, cash/voucher (boleto, OXXO, Rapipago, ...), bank transfer (Pix, PSE, ...), ATM. The types that are not selected are excluded from the checkout. Defaults to all types
Test Access Token	Your application → test credentials
Test Webhook Secret Signature	Your application → Webhooks: the secret signature (test)
Live Access Token	Your application → production credentials
Live Webhook Secret Signature	Your application → Webhooks: the secret signature (production)

Webhook

The module sends the notify URL with every payment, so you do not have to enter it for the payments to be processed (the CP does not show a notify URL for this gateway). You do need the secret signature: in your application, go to Webhooks, enable the Payments event and copy the secret signature into the matching Webhook Secret Signature field in the CP. If Mercado Pago asks for a URL there, use your notify URL: <your action URL>&method=notify&gateway=mercado_pago (the same as the notify URL of other gateways, ending in gateway=mercado_pago).

Without a secret signature, webhooks are still processed (the payment is always fetched from the API) and an error is logged. With a wrong secret, webhooks are refused (webhook verification failed). Legacy IPN calls are ignored; Mercado Pago sends a webhook as well.

How the payment works

• On checkout, the module creates a Checkout Pro preference for the order total (one item for the whole order) and sends the customer to Mercado Pago.
• After an approved payment, the customer is sent back automatically. The module searches the payments of the order: an approved payment makes the order complete; a pending payment (for example a boleto or OXXO voucher that is not paid yet, or a payment under review) makes it pending, and the webhook completes it once paid.
• A rejected payment leaves the order as it is; the customer can try again. If the customer goes back to the store from the failure page, the order becomes cancelled.
• Refunds from the CP are for the full order amount. Refunds and chargebacks in Mercado Pago also reach the store via the webhook (order refunded or paid (chargeback)).

Limitations

• The module uses the Checkout Pro Preferences API, which Mercado Pago now marks as legacy; the Orders API is the newer one.
• Payment methods depend on your country; the module can only exclude payment types, not add them.

Test checklist

• [ ] Webhooks are verified with your application's secret signature, also for the notification URL the module sends with each payment: after a test payment the Store log shows no webhook verification failed error.
• [ ] The sandbox checkout (sandbox_init_point) works with Mercado Pago test users: log in as a test buyer, preferably in a private browser window.
• [ ] Test the refund statuses: a refund from the CP succeeds, and the order becomes refunded.
• [ ] A voucher payment (boleto, OXXO) keeps the order pending until it is paid.
• [ ] Note that Mercado Pago marks the Preferences API as legacy (the Orders API is the newer one); check Mercado Pago's announcements for an end-of-life date.
• [ ] Use the test cards and cardholder names from Mercado Pago's test purchases page for your country.