# Magento 2

> Install Mintage Pay on Magento 2, Mage-OS or Adobe Commerce, test it with test money and go live.

Source: https://mintagepay.com/docs/integrations/magento/ (last updated 2026-10-25)

Adds **Pay with USDC or USDT** to the Magento checkout. The order is placed as **Pending Payment**, the customer
pays on the Mintage Pay payment page, and the order is invoiced and moves to **Processing** by itself when the payment
is final.

Tested on 5 October 2026 with Mage-OS 3.5 (the open distribution of Magento 2.4) in production mode, against the
sandbox: install, connect, checkout, payment, order invoiced, return to the "Thank you" page, and disconnect. Adobe
Commerce uses the same code but has not been run yet, so test it with a sandbox key first.

## What you need

- Magento 2.4.4 or later, on PHP 8.1 to 8.4 with `curl`.
- An admin user with the **Stores > Configuration** permission.
- A way to add a module: server access with permission to run `bin/magento`, or the repository your store deploys
  from. Installing takes a few minutes of maintenance mode.
- The store's base currency and display currency must be the same, and one Mintage Pay supports: USD, EUR, GBP, CAD,
  AUD, CHF, JPY, MXN, BRL, INR, SGD, AED, PLN, SEK, NOK, DKK, NZD, ZAR, TRY, KRW, HKD, NGN, ARS, PHP, IDR, VND, PKR, EGP, BDT, KES, GHS, TZS, COP, CLP, PEN, UYU, PYG, BOB, DOP, GTQ, CRC, THB, MYR, TWD, LKR, NPR, KZT, UAH, ILS, SAR, QAR, CZK, HUF, RON, ISK, XAF or XOF. The method is hidden
  otherwise. Your customers always pay in US dollar stablecoins: a price in another currency is converted when they
  check out.
- Your storefront on **https**, reachable from the internet. Mintage Pay tells your store about payments by calling
  `https://your-store/mintagepay/webhook/index`. Firewalls, bot rules and password protection must let that address
  through.
- A Mintage Pay account with at least one payout address set.

## Install

1. Download [mintagepay-magento2.zip](https://app.mintagepay.com/downloads/mintagepay-magento2.zip) and unpack it.
   Copy its `Mintage` folder to `app/code/` in your Magento folder, so that `app/code/Mintage/Pay` exists.
2. From the Magento folder, as the user that owns the files, run:

   ```
   php bin/magento maintenance:enable
   php bin/magento module:enable Mintage_Pay
   php bin/magento setup:upgrade
   php bin/magento setup:di:compile
   php bin/magento setup:static-content:deploy -f
   php bin/magento cache:flush
   php bin/magento maintenance:disable
   ```

   The two lines in the middle (`setup:di:compile` and `setup:static-content:deploy`) are only needed in production
   mode.
3. In the Mintage Pay dashboard, open **Developers > API keys** and create a key. Copy it: it is shown only once.
4. In the Magento admin, go to **Stores > Configuration > Sales > Payment Methods > Mintage Pay (USDC / USDT)**.
   Set **Enabled** to Yes, paste the key and click **Save Config**.
5. The page says **Mintage Pay: connected to (your business name).** The **Connection** row says **Connected**.

Leave **API base URL** empty. The key decides where the module connects.

If it does not connect, run `php bin/magento mintagepay:connect` to see the reason.

## Try it first with test money

1. Create a free account at [sandbox.mintagepay.com](https://sandbox.mintagepay.com), set a payout address and
   create a key there.
2. Paste the sandbox key in the module settings and save. The Connection row says **(sandbox)**.
3. Place an order with a cheap product and choose **Pay with USDC or USDT**. You land on a payment page with a
   **Test mode** banner. In the admin the order is **Pending Payment**.
4. Pay on the payment page with free test money. The page has a button to get some.
5. Within a minute or two the order has an invoice and is **Processing**, with a comment giving the amount and a link
   to the transaction. The payment page sends you back to the store's "Thank you" page.
6. When you are happy, paste your live key and save. The Connection row says **(live)**.

Magento sends the order confirmation email when the payment is final, not when the order is placed.

## Unpaid orders

Keep **Stores > Configuration > Sales > Sales > Orders Cron Settings > Pending Payment Order Lifetime** (480 minutes
by default) longer than the module's **Payment window** (60 minutes by default). If Magento cancels an order and the
customer then pays, the order goes **On Hold** for you to check.

## What you will see

| What happened | Order |
|---|---|
| Customer sent to pay | Pending Payment |
| Paid in full | Processing, with an invoice |
| Paid, but the amount does not match the order | On Hold, with a comment. Check before you ship |
| Part paid | On Hold, with a comment saying how much is still owed |
| Payment window closed with nothing paid | Canceled. The stock goes back |
| Paid after the order was cancelled | On Hold. Refund the customer or restore the order |
| Refund recorded in Mintage Pay | An offline credit memo for that amount |

Refunding in Magento does not send any money. You send the refund yourself and record it in the Mintage Pay
dashboard.

## If an order did not update

1. Run `php bin/magento mintagepay:sync (order number)`. It reads the payment again and prints the new order state.
2. If that works but updates never arrive by themselves, something blocks calls to `/mintagepay/webhook/index`:
   a firewall, bot rules, password protection on a staging site, or an allowlist.
3. Look in `var/log/mintage_pay.log`. Switch on **Debug log** in the module settings for every step. Your key and
   webhook secret are never written to the log.

## Remove the module

```
php bin/magento mintagepay:disconnect
php bin/magento module:disable Mintage_Pay
rm -rf app/code/Mintage/Pay
php bin/magento setup:upgrade
php bin/magento cache:flush
```

`mintagepay:disconnect` switches off your store's connection at Mintage Pay. In production mode, also run
`setup:di:compile` and `setup:static-content:deploy -f` after `setup:upgrade`. Your orders keep their payment
details.