Plugins and links / Saleor

Saleor

A Saleor app for the Transaction API. Your storefront sends the customer to the Mintage Pay payment page, and the app reports the charge to Saleor by itself when the payment is final.

A Saleor app is a small service that you host. You run it at a public https address and install it in the Saleor Dashboard from its manifest address.

Tested on 5 October 2026 with Saleor 3.21 and the app on Node 22, against the sandbox: connect, install from the manifest, payment gateway offered at checkout, payment, charge reported to Saleor, order created fully paid, and removal. The run used a channel priced in US dollars and the GraphQL API. A channel in another currency and the Dashboard's own install screen have not been run yet, so test them with a sandbox key first.

What you need

• Saleor 3.20 or later, and a staff user who may manage apps.
• A host for the app: Node 20.19 or later, a public https address, and a folder that survives restarts for the app's data file.
• Your Saleor API address exactly as Saleor uses it, for example https://shop.example.com/graphql/.
• The storefront repository: it needs three GraphQL calls and a return page.
• Channel currencies 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. Your customers always pay in US dollar stablecoins: a price in another currency is converted when they check out, and the payment page shows both amounts.
• A Mintage Pay account with at least one payout address set.

The app calls Mintage Pay and your Saleor API, and both call the app. Firewalls must allow that.

Install

1. Download mintagepay-saleor-app.zip and unpack it on the host. In the folder, run:

   Copy

   npm ci --omit=dev

2. Copy .env.example to .env and set:

   • APP_URL: the app's public https address;
   • MINTAGEPAY_API_KEY: a key from Developers > API keys in the Mintage Pay dashboard. It is shown only once;
   • ALLOWED_SALEOR_API_URLS: your Saleor API address;
   • DATA_FILE: a file in the folder that survives restarts.

   Keep .env and the data file private. They hold your key, the app's Saleor token and the webhook secret.

3. Connect the app to Mintage Pay:

   Copy

   node --env-file=.env dist/cli/connect.js

   It prints your business name and registers the app's address with Mintage Pay. It never prints the secret. Run it again whenever APP_URL changes.

4. Start the app and keep it running, restarting it if it stops:

   Copy

   node --env-file=.env dist/server.js

   Run one copy of it. Check that https://your-app/api/manifest answers.

5. In the Saleor Dashboard, go to Apps > Install external app, enter https://your-app/api/manifest and approve the permission Handle payments.

The key decides where the app connects: a live key (mp_live_...) uses the live service and a test key (mp_test_...) uses the sandbox.

Update the storefront

Start the payment with the gateway mintagepay.pay:

mutation {
  transactionInitialize(
    id: "(checkout id)"
    paymentGateway: {
      id: "mintagepay.pay"
      data: {
        redirectUrl: "https://shop.example.com/checkout/mintagepay-return"
        cancelUrl: "https://shop.example.com/cart"
      }
    }
  ) {
    transaction { id }
    transactionEvent { type message }
    data
    errors { field message code }
  }
}

1. Send the customer to data.checkoutUrl.
2. On the return page, call transactionProcess with the transaction id.
3. On CHARGE_SUCCESS, call checkoutComplete. On CHARGE_ACTION_REQUIRED, show "payment confirming" and ask again a little later. The app also reports the charge to Saleor by itself, so the payment is not lost if the customer closes the page.

Try it first with test money

1. Create a free account at sandbox.mintagepay.com, set a payout address and create a key there.
2. Put the sandbox key in .env, run the connect command and start the app. The connect command says sandbox.
3. Start a checkout in your storefront and choose Mintage Pay. 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. Within a few minutes the transaction in Saleor is charged in full, and checkoutComplete creates the order.
6. When you are happy, put your live key in .env, run the connect command again and restart the app.

What you will see

Mintage Pay never holds your money, so it cannot send a refund for you. Send the refund from your own wallet and record it in the Mintage Pay dashboard.

If something is wrong

• Install is refused with SALEOR_URL_PROHIBITED: ALLOWED_SALEOR_API_URLS does not match your Saleor API address.
• Install is refused with JWKS_NOT_AVAILABLE: the app cannot reach your Saleor API.
• Saleor's calls get 401 not_registered: the data file was lost or the app was installed somewhere else. Install the app again.
• Mintage Pay's calls get 401 not_configured: the connect command was not run, or the data file changed.
• A payment stays at "charge action required": look at the webhook delivery in the Mintage Pay dashboard, then at the app's log.

Remove the app

1. Remove the app under Apps in the Saleor Dashboard.

2. Switch off the connection at Mintage Pay:

   Copy

   node --env-file=.env dist/cli/connect.js --disable

3. Stop the service. Delete the data file once no payment is waiting.

Last updated 25 October 2026. This page as Markdown. Something missing or wrong? Write to hello@mintagepay.com.