API reference

Base URL: https://app.mintagepay.com/v1 (sandbox: https://sandbox.mintagepay.com/v1). All request and response bodies are JSON. Amounts are decimal strings.

A machine-readable description of every route is at /v1/openapi.json. No key is needed to read it.

Authentication

Send your key as a bearer token:

Authorization: Bearer mp_live_YOUR_KEY

Create keys in the dashboard under Developers > API keys. A key is shown once; only its hash is stored. Revoked keys get 401.

GET /v1/me works with any key. It tells an integration where it is and what the account can do:

• mode: "live" (real money) or "test" (the sandbox);
• name: the business name;
• rails: what the account can be paid with here, for example [{ "id": "base-usdc", "network": "base", "token": "USDC" }];
• merchant: id, name, fee_bps and underpayment_tolerance_bps;
• api_key: the key's id and scopes.

Scopes

Each key has scopes, chosen when it is created. A call the key's scopes do not allow gets 403 insufficient_scope, and details.required names the missing scope.

The Developers page offers presets: Full access, Read only and AI agent: read + create invoices. Only team members who may see customer details (owner, admin) can give a key orders:read.

Errors

Errors look like this:

{ "error": "not_found", "message": "Invoice not found" }

Invalid input is 400 with "error": "validation_failed" and one details item per problem:

{ "error": "validation_failed", "message": "Invalid request",
  "details": [{ "path": "redirect_url", "code": "invalid_url", "message": "Invalid URL" }] }

• path is the request field as you sent it. Nested fields are joined with dots (shipping.postal_code).
• code is stable, so you can write your own wording for it: required, too_short, too_long, too_small, too_big, invalid_email, invalid_url, invalid_format, invalid_choice, invalid_type, invalid_amount and others.
• message is English, for developers.

Create an invoice

POST /v1/invoices (scope invoices:write)

Send the header Idempotency-Key with your order id or any unique string. Repeating the same key returns the same invoice (200), so a retry never creates a second one. Reusing the key with a different amount or order id returns 409. So does reusing it with a different metadata.order_key, when both requests carry one: put a value that belongs to the one order there if your order numbers can start again (a rebuilt store, or two stores on one account).

{
  "amount": "15.00",
  "currency": "USD",
  "order_id": "1042",
  "description": "Order #1042",
  "buyer_email": "customer@example.com",
  "redirect_url": "https://example.com/thank-you",
  "cancel_url": "https://example.com/cart",
  "metadata": { "any": "json" },
  "expires_in_minutes": 60,
  "send_email": false,
  "send_receipt": true,
  "locale": "es"
}

Returns 201 with an invoice object. Send the customer to its checkout_url.

With "send_email": true the response also has "email_sent": true, or false with an email_error. The invoice is created either way, and you can retry with POST /v1/invoices/{id}/send.

Checkout language

The payment page and the customer emails come in English, Spanish, Portuguese (Brazil), French, German, Italian, Turkish, Indonesian, Vietnamese, Thai, Arabic (right to left), Hindi and Russian. locale sets the customer's language: en, es, pt-BR, fr, de, it, tr, id, vi, th, ar, hi or ru. Any language tag works (es-MX, de_DE), so a store can pass its own language as it is. A language that is not offered never fails the invoice; the page then follows the customer's browser.

On the page, the first match wins: the language the customer picks in the page's switcher, ?lang= in the URL, the language they picked on an earlier visit, the invoice's locale, the browser language, then English.

Prices in other currencies

Customers always pay in US dollar stablecoins. You can still price in your own currency. Send currency with one of: 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, XOF.

• Conversion: when the invoice is created, your price is converted to the USD amount the customer pays, rounded up to the cent, so you never receive less than your price. That USD amount is amount. It does not change afterwards.
• The rate: a live rate, checked against central bank reference rates. If the two differ by more than 1%, or no recent rate is available, the request fails with 503 and "error": "fx_unavailable", and nothing is created. Try again later or price in USD.
• On the invoice: price_currency and price_amount are your price. fx_rate is USD per 1 unit of your currency, exactly as applied. fx_source and fx_at say where and when the rate came from.
• At checkout: the customer sees your price, the amount to pay and the rate.

Other invoice calls

Payment request emails are limited to 50 per store per hour and 10 per recipient per day (429 rate_limited).

The invoice object

{
  "id": "Kp3...",
  "object": "invoice",
  "status": "open",
  "amount": "15.00",
  "currency": "USD",
  "price_currency": "USD",
  "price_amount": "15.00",
  "fx_rate": "1",
  "fx_source": null,
  "fx_at": null,
  "amount_paid": "0.00",
  "amount_pending": "0.00",
  "amount_remaining": "15.00",
  "overpaid": "0.00",
  "amount_short": "0.00",
  "paid_late": false,
  "held_for_review": false,
  "order_id": "1042",
  "description": "Order #1042",
  "metadata": {},
  "locale": "es",
  "checkout_url": "https://pay.mintagepay.com/i/Kp3...",
  "redirect_url": "https://example.com/thank-you",
  "expires_at": "2026-10-01T19:00:00.000Z",
  "paid_at": null,
  "created_at": "2026-10-01T18:00:00.000Z",
  "payments": [
    { "network": "base", "token": "USDC", "amount": "15.000000", "status": "confirmed",
      "tx": "0x...", "explorer_url": "https://basescan.org/tx/0x...", "late": false,
      "from_address": "0x..." }
  ],
  "refunds": [],
  "amount_refunded": "0.00",
  "send_receipt": true,
  "subscription": null
}

Amounts inside payments and refunds have up to 6 decimals, for example "15.000000".

Status

Payments are still watched for after an invoice expires or is cancelled. Money sent anyway still reaches your wallet. If it completes the amount, the invoice becomes paid with paid_late: true. If it still falls short, the status stays as it was, paid_late becomes true and invoice.partially_paid is sent.

Underpayments and overpayments

• Tolerance (dashboard, Settings > Payments, 0% to 5%, default 0%): an invoice short of amount by no more than this share becomes paid, with amount_short set. Some wallets and exchanges take their fee from what the customer sends; this covers that.
• Overpayment: overpaid shows the extra. You also get a notice with the amount and the address the customer paid from, so you can send the extra back.
• Fees are always charged on what arrived.

Refunds

Mintage Pay never holds your money, so you send a refund yourself, from any wallet or exchange, on the network the customer paid on. Then record it in the dashboard: open the payment under Payments, choose Refund, enter the amount and address, send it, and paste the transaction hash.

A refund counts once it is final on the network and sends the right stablecoin, at least the amount, to that address. Refunds can never add up to more than was paid. The Mintage Pay fee is not refunded. When a refund is verified, your endpoint receives invoice.refunded.

A refund object:

{ "id": "...", "network": "base", "token": "USDC", "amount": "5.000000", "to": "0x...",
  "amount_micro": "5000000", "amount_units": "5000000", "decimals": 6,
  "status": "confirmed",
  "tx": "0x...", "explorer_url": "https://basescan.org/tx/0x...", "created_at": "...", "confirmed_at": "..." }

status is requested or confirmed. Add up amount_micro (millionths of a dollar) for totals.

Payment links

A payment link is a product or donation page hosted by Mintage Pay. Most stores create them in the dashboard; see Payment links and the buy button. They can also be created through the API.

POST /v1/payment-links (scope links:write) creates a link and returns it (201) with the page address in url.

GET /v1/payment-links (scope links:read) returns { "data": [...] }, active links first.

The answer is 403 review_required until your account has been reviewed.

Orders from a link

Invoices created from a link carry a payment_link object: id, name, kind, order_id, quantity, currency, unit_price and shipping.

GET /v1/orders/{invoice id} (scope orders:read) returns the order with a customer object: email, name, phone, custom, message and shipping_address. Customer details are kept for 2 years, then removed.

Bank transfer

Stores approved for business-to-business sales can also offer bank transfer (ACH or wire) on the payment page, after adding a bank account in the dashboard.

• When the customer chooses it, the page shows your account details and a reference unique to the invoice. invoice.awaiting_bank_transfer is sent, the status stays open, and expires_at moves out to your payment terms (1 to 30 days, 7 by default). Hold the order; do not cancel it.
• Mintage Pay never sees your bank. When the money arrives, record it in the dashboard under Bank transfers. Each amount counts as a confirmed payment, so the invoice becomes partially_paid or paid and the usual events are sent.
• Single invoice reads and webhooks carry a bank_transfer object with the reference, the amount due, the amount_received and the receipts you recorded.

Not covered here

Subscriptions and payments by AI agents (x402) can be tried in the sandbox. They are not available on live accounts yet, so they are not part of this reference.

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