# Drupal Commerce

> Install Mintage Pay on Drupal Commerce, test it with test money and go live.

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

Adds **Pay with USDC or USDT** as a payment gateway in Drupal Commerce. The customer pays on the Mintage Pay payment
page and the payment is marked **Completed** by itself when it is final.

Tested on 5 October 2026 with Drupal 11.4 and Commerce 3 against the sandbox: add the gateway, checkout, payment,
payment completed, and removal. Drupal 10 and Commerce 2 are supported by the module but have not been run yet, so
test them with a sandbox key first.

## What you need

- Drupal 10 or 11 with Commerce 2 or 3 (Payment and Checkout enabled). PHP 8.1 or later, with the `bcmath` extension
  that Commerce itself needs.
- A way to add a module to the site: Composer or Git deploys, or file access to `web/modules/custom/`.
- An admin account that can administer modules and payment gateways.
- A store currency 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. Other currencies are refused at checkout. Your customers always pay in US dollar
  stablecoins: a price in another currency is converted when they check out.
- Your site on **https**, reachable from the internet. Mintage Pay tells your store about payments by calling
  `https://your-site/payment/notify/(gateway machine name)`. Firewalls and password protection must let that address
  through, and `trusted_host_patterns` in `settings.php` must include your public host.
- A Mintage Pay account with at least one payout address set.

## Install

1. Download [commerce_mintage_pay.zip](https://app.mintagepay.com/downloads/commerce_mintage_pay.zip) and
   unpack it. Copy the `commerce_mintage_pay` folder to `web/modules/custom/`.
2. Enable the module: `drush en commerce_mintage_pay -y`, or go to **Extend**, tick **Commerce Mintage Pay** and
   click **Install**.
3. In the Mintage Pay dashboard, open **Developers > API keys** and create a key. Copy it: it is shown only once.
4. Go to **Commerce > Configuration > Payment > Payment gateways** and click **Add payment gateway**:
   - **Name:** Mintage Pay. The machine name becomes part of the address Mintage Pay calls, so do not change it
     later.
   - **Plugin:** Mintage Pay (USDC / USDT, off-site).
   - **Display name:** Pay with USDC or USDT, or your own wording.
   - **API key:** paste the key. It is stored encrypted and never shown again.
   - **Status:** Enabled.
5. Click **Save**. The page says **Mintage Pay: API key verified for (your business name). Webhook connected.**
6. Rebuild the cache (`drush cr`, or **Configuration > Performance > Clear all caches**) so the new payment option
   appears at checkout.
7. Recommended: under **Commerce > Configuration > Order types > Default**, choose the **Fulfillment** workflow. With
   the plain Default workflow a placed order is at once "Completed" and unpaid orders cannot be cancelled for you.

## 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. Add the gateway with the sandbox key, or edit it and save.
3. In a private browser window, add a product, check out and choose **Pay with USDC or USDT**. You land on a payment
   page with a **Test mode** banner.
4. Pay on the payment page with free test money. The page has a button to get some.
5. The payment page sends you back to the store and the order is placed. Open the order's **Payments** tab: within a
   minute or two the payment is **Completed**.
6. When you are happy, edit the gateway, paste your live key and save.

## When to ship

**Ship when the payment is Completed, not when the order is placed.** The customer is sent back to your store as
soon as their payment is seen, which can be a short while before it is final. During that time the order is already
placed and its payment is **Pending**. It becomes **Completed** by itself, usually within a minute.

## What you will see

| What happened | In Commerce |
|---|---|
| Customer sent to pay | Payment New, order still a cart |
| Customer returned, payment not final yet | Order placed, payment Pending |
| Paid in full | Payment Completed |
| Paid, but the amount does not match the order | Payment Pending, with a comment. Check before you ship |
| Part paid | Payment Pending, with a comment saying how much is still owed |
| Payment window closed with part paid | Payment Pending. Refund the customer or collect the rest |
| Payment window closed with nothing paid | Payment Voided. A placed order is cancelled (Fulfillment workflow); a cart is kept |
| Paid after the order was cancelled | Payment Pending, with a comment |
| Refund recorded in Mintage Pay | The refunded amount on the payment |

Comments go to **Reports > Recent log messages**, type `commerce_mintage_pay`. Enable the **Commerce Log** module
to see them in the order's activity as well.

## If something is wrong

- **The payment option does not show at checkout:** rebuild the cache, and check that the gateway is enabled and the
  order currency is supported.
- **A payment did not update:** look in **Reports > Recent log messages**. A 401 there means the stored secret does
  not match: save the gateway again.
- **After moving the site to a new address or server:** edit the gateway and save it again. If `hash_salt` in
  `settings.php` changed, paste the API key again first.

Your key and webhook secret are never written to the log.

## Update to a new version

1. Replace the `commerce_mintage_pay` folder in `web/modules/custom/` with the new one.
2. Run `drush updb -y`, then `drush cr`.

Your gateway, your key and your past payments are kept. An order that was waiting for payment when you updated is
still completed when the payment arrives.

## Remove the module

1. `drush pmu commerce_mintage_pay -y`, or **Extend > Uninstall**. This switches off your store's connection at
   Mintage Pay and removes the gateway and its stored key.
2. Delete the `commerce_mintage_pay` folder.

Your orders and their payments are kept.