{"openapi":"3.1.0","info":{"title":"Mintage Pay merchant API","version":"1","description":"Accept USDC and USDT stablecoin payments. Create an invoice, send the customer to `checkout_url`, and receive a signed webhook when it is paid. API keys start with `mp_live_`; use the sandbox (https://sandbox.mintagepay.com) for testing. Each key has scopes, chosen when it is created: `invoices:read`, `invoices:write`, `links:read`, `links:write`, `orders:read`, `refunds:read`, `webhooks:manage`, `subscriptions:read`, `subscriptions:write`. Every operation names the one it needs in `x-required-scope`; a key without it gets 403 `insufficient_scope`. One also names a second scope in `x-also-requires-scope` (403 `scope_missing` without it). GET /me shows the scopes of the key. The `x402` scope is for the x402 facilitator, which lives outside /v1: see `x-x402-facilitator`."},"x-x402-facilitator":{"url":"https://app.mintagepay.com/x402","spec":"https://github.com/coinbase/x402/blob/main/specs/x402-specification-v2.md","scheme":"https://github.com/coinbase/x402/blob/main/specs/schemes/exact/scheme_exact_evm.md","auth":"Authorization: Bearer <API key with the x402 scope>","description":"Off unless the operator enabled x402. Only the exact scheme with EIP-3009 (USDC; USDT0 where enabled). payTo must be your receiver from GET /x402/receivers. Settlement gas is charged to your prepaid fee credit (at least $0.01 per settlement, at finality); settle answers insufficient_fee_credit when it cannot be covered. Money collects at the receiver and is paid out to your payout address, minus the platform fee, once $5 has settled.","endpoints":{"POST /verify":{"request":"{ x402Version: 2, paymentPayload, paymentRequirements }","response":"{ isValid, invalidReason?, invalidMessage?, payer? }"},"POST /settle":{"request":"{ x402Version: 2, paymentPayload, paymentRequirements }","response":"{ success, errorReason?, errorMessage?, payer?, transaction, network, amount? }","note":"Waits up to 30 s for the transfer to be in a block; otherwise success false with errorReason settlement_pending and the webhook x402.payment.settled_late if it lands later. Repeating the same request is safe (answered from the first)."},"GET /supported":{"response":"{ kinds: [{ x402Version: 2, scheme: \"exact\", network }], extensions: [], signers: { \"eip155:*\": [address] } }"},"GET /receivers":{"response":"{ facilitatorUrl, receivers: [{ network, networkName, payTo, assets: [{ asset, symbol, decimals, extra: { name, version } }], feeBps, payoutAddress }] }"}}},"servers":[{"url":"https://app.mintagepay.com/v1"}],"security":[{"apiKey":[]}],"paths":{"/me":{"get":{"summary":"The merchant this key belongs to","responses":{"200":{"description":"Merchant","content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["live","test"],"description":"live: real money (mainnet); test: the sandbox (test networks, test money)"},"name":{"type":"string","description":"The business name"},"rails":{"type":"array","description":"What this account can be paid with here: rails switched on in this environment whose network has a payout address","items":{"type":"object","properties":{"id":{"type":"string","examples":["base-usdc"]},"network":{"type":"string"},"token":{"type":"string","enum":["USDC","USDT","PYUSD"]}}}},"merchant":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"fee_bps":{"type":"integer"},"underpayment_tolerance_bps":{"type":"integer","minimum":0,"maximum":500,"description":"Payments short by up to this many basis points of the amount count as paid (see amount_short)"}}},"api_key":{"type":"object","description":"The key making this request","properties":{"id":{"type":"string","format":"uuid"},"scopes":{"type":"array","items":{"type":"string","enum":["invoices:read","invoices:write","links:read","links:write","orders:read","refunds:read","webhooks:manage","subscriptions:read","subscriptions:write","x402"]}}}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payment-options":{"get":{"summary":"What the payment page would offer for an order of this amount right now","description":"For describing the payment method on the store's own checkout before an invoice exists. Uses the same rules as the payment page: minimums (Cash App $1, PayPal and Venmo $10), switches, the coins the store accepts, and networks that are temporarily unavailable. `apple_pay` and `google_pay` are both true when the card page is open: the buyer's browser decides which one shows (Apple Pay where `ApplePaySession` exists, Google Pay elsewhere).","parameters":[{"name":"amount","in":"query","required":true,"schema":{"type":"string","examples":["12.00"]},"description":"The order total in `currency`"},{"name":"currency","in":"query","schema":{"type":"string","default":"USD"},"description":"ISO 4217; not USD: converted like an invoice price"}],"responses":{"200":{"description":"Options","content":{"application/json":{"schema":{"type":"object","properties":{"amount_usd":{"type":"string"},"options":{"type":"object","properties":{"apple_pay":{"type":"boolean"},"google_pay":{"type":"boolean"},"cash_app":{"type":"boolean"},"venmo":{"type":"boolean"},"paypal":{"type":"boolean"},"coinbase":{"type":"boolean"},"exchange":{"type":"boolean"},"wallet":{"type":"boolean"}}},"order":{"type":"array","description":"The available options in the order the payment page lists them","items":{"type":"string"}},"rails":{"type":"array","description":"Rails open for this amount now","items":{"type":"string"}},"card":{"type":"object","description":"A typed card through Stripe (the buyer pays the fee on top). `app_or_card`: the store may offer \"Pay by card\" and \"Pay by app\" as two choices and open `<checkout_url>/card?method=card` (a card only) or `<checkout_url>?pay=app`. `in_popup`: the card form also runs inside the store's pop-up. `fee_on_top`: the card buyer pays the Mintage Pay fee on top (false: the store pays every card fee, Mintage Pay's and the card processor's, and the buyer pays the order total only; see `card_fee_paid_by_store`).","properties":{"available":{"type":"boolean"},"app_or_card":{"type":"boolean"},"in_popup":{"type":"boolean"},"fee_on_top":{"type":"boolean"},"excluded_states":{"type":"array","items":{"type":"string"},"description":"US billing states (2 letters) the card route cannot serve: hide the card for a billing address there"}}},"popup":{"type":"boolean","description":"The payment page may be shown in a pop-up over the store's checkout (framed only by the site of the invoice's `redirect_url`)"}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"fx_unavailable: no reliable exchange rate for a non-USD amount right now","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/invoices":{"post":{"summary":"Create an invoice","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Repeating a key returns the same invoice (200); a different amount or order id with it is a 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvoice"}}}},"description":"With `send_email: true` the response also carries `email_sent` (and `email_error`, e.g. `rate_limited`, when it was not sent; the invoice is created either way). A replayed Idempotency-Key never emails again.","responses":{"200":{"description":"Same Idempotency-Key: the existing invoice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the invoices:write scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"fx_unavailable: no reliable exchange rate for a non-USD price right now (retry later); email_unavailable: send_email but email is not set up","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"invoices:write"},"get":{"summary":"List invoices (newest first)","parameters":[{"name":"order_id","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["open","partially_paid","paid","expired","cancelled"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Invoices","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the invoices:read scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"invoices:read"}},"/invoices/{id}":{"get":{"summary":"Get an invoice, with its payments, refunds, bank transfer and payment link","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Invoice id (the public id, e.g. 9N4zvDFEcGKBg78rDcVa)"}],"responses":{"200":{"description":"Invoice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the invoices:read scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"invoices:read"}},"/invoices/{id}/send":{"post":{"summary":"Email the customer this payment request (amount, description, due time and checkout link)","description":"Open invoices only. Sent to `email`, or to the buyer_email of the invoice. An invoice without a buyer_email takes this address, so the customer also gets a receipt once paid. Limits: 50 emails per merchant per hour, 10 per recipient per day.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Invoice id (the public id, e.g. 9N4zvDFEcGKBg78rDcVa)"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","maxLength":254}}}}}},"responses":{"200":{"description":"Sent","content":{"application/json":{"schema":{"type":"object","properties":{"sent":{"const":true},"sent_at":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the invoices:write scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"invoice_closed: paid, expired or cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"email_failed: the mail server refused it, try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"email_unavailable: email is not set up on this server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"invoices:write"}},"/invoices/{id}/cancel":{"post":{"summary":"Cancel an unpaid or part-paid invoice","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Invoice id (the public id, e.g. 9N4zvDFEcGKBg78rDcVa)"}],"responses":{"200":{"description":"Cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the invoices:write scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"invoices:write"}},"/orders/{id}":{"get":{"summary":"A payment-link order with the customer's details (by invoice id)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Invoice id (the public id, e.g. 9N4zvDFEcGKBg78rDcVa)"}],"responses":{"200":{"description":"Order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the orders:read scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"orders:read"}},"/invoices/{id}/refund-address":{"post":{"summary":"Ask the customer for their own refund address","description":"For a paid (or part-paid) invoice. Creates a link (`url`, valid 14 days) where the customer picks a network they paid on and enters an address of their own; the link is emailed to `email`, or to the buyer_email of the invoice (`email: null` = only return the link). A new request replaces an open one. The answer appears in GET /invoices/{id}/refund-address and as the first refund suggestion in the dashboard. Limits: 20 emails per merchant per hour, 5 per recipient per day.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Invoice id (the public id, e.g. 9N4zvDFEcGKBg78rDcVa)"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":["string","null"],"format":"email","maxLength":254},"amount":{"type":["string","null"],"description":"The refund you intend, in USD, shown to the customer"}}}}}},"responses":{"200":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"enum":["open","answered","expired"]},"networks":{"type":"array","items":{"type":"string"}},"amount":{"type":["string","null"]},"network":{"type":["string","null"]},"address":{"type":["string","null"]},"answered_at":{"type":["string","null"],"format":"date-time"},"emailed":{"type":"boolean"},"expires_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"url":{"type":"string","format":"uri"}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the invoices:write scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"invoices:write"},"get":{"summary":"The latest refund address request of an invoice, with the customer's answer","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Invoice id (the public id, e.g. 9N4zvDFEcGKBg78rDcVa)"}],"responses":{"200":{"description":"Request","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"enum":["open","answered","expired"]},"networks":{"type":"array","items":{"type":"string"}},"amount":{"type":["string","null"]},"network":{"type":["string","null"]},"address":{"type":["string","null"]},"answered_at":{"type":["string","null"],"format":"date-time"},"emailed":{"type":"boolean"},"expires_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the refunds:read scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"refunds:read"}},"/invoices/{id}/disputes":{"post":{"summary":"Report that the customer disputed the card charge of this order","description":"Only for an order a card paid (the invoice has a `card` object). Card disputes are decided by the card provider (Stripe, or Coinbase for Apple Pay and Google Pay), not by Mintage Pay; reporting one records it, adds it to the order's evidence pack and counts toward the store's reported dispute rate. A second report while one is live adds to it (200, `created: false`). Give `delivery` when the order was delivered: tracking is part of the evidence.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Invoice id (the public id, e.g. 9N4zvDFEcGKBg78rDcVa)"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","enum":["unrecognized","fraud","not_received","not_as_described","credit_not_processed","duplicate","other","unknown"],"default":"unknown"},"amount":{"type":["string","null"],"description":"The disputed amount in USD, when known"},"provider_case_ref":{"type":["string","null"],"maxLength":200},"opened_at":{"type":["string","null"],"format":"date-time"},"delivery":{"type":["object","null"],"properties":{"carrier":{"type":["string","null"]},"tracking":{"type":["string","null"]},"delivered_at":{"type":["string","null"],"format":"date-time"}}}}}}}},"responses":{"200":{"description":"Added to the live dispute of this order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dispute"}}}},"201":{"description":"Recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dispute"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the invoices:write scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"not_a_card_order: no card was charged for this order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"invoices:write"},"get":{"summary":"The disputes reported on an invoice","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Invoice id (the public id, e.g. 9N4zvDFEcGKBg78rDcVa)"}],"responses":{"200":{"description":"Disputes","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Dispute"}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the invoices:read scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"invoices:read"}},"/invoices/{id}/refunds":{"get":{"summary":"The refunds of an invoice (cancelled ones left out)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Invoice id (the public id, e.g. 9N4zvDFEcGKBg78rDcVa)"}],"responses":{"200":{"description":"Refunds","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the refunds:read scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"refunds:read"},"post":{"summary":"Create a refund for you to send","x-also-requires-scope":"webhooks:manage","description":"Needs `invoices:write` AND `webhooks:manage` (a key without `webhooks:manage` gets 403 `scope_missing`; every store plugin's Connect key has both). Creates the same refund as the dashboard's Refund: nothing is sent by Mintage Pay. You send it from your wallet or exchange (the `link` opens it in the dashboard) and it is verified on the network; `invoice.refunded` follows. Where it goes: the customer's open refund request (approved by this call), else the address they gave through a refund address link, else the paying wallet when it is known to be their own (never a card's temporary wallet). None of those: 202 `needs_address`, and nothing is created (no refund, no Idempotency-Key recorded, no email, an open refund address request is left as it is): ask for their address with POST /invoices/{id}/refund-address and try again. 200 `already_waiting`: a refund of the same amount that was not sent yet is open on this invoice (its id and link; nothing new). Off for your account: 409 `refunds_api_off`. Orders priced in another currency: 409 `non_usd_order` (refund in the dashboard). WooCommerce: with plugin 1.21.0 a refund made through the WooCommerce REST API with `api_refund=true` (an ERP, a script) on a Mintage Pay order also calls this, so it creates a real refund here; WooCommerce then answers that REST call with HTTP 500 and the message with the link, and keeps no refund record until the money is confirmed. Retrying it is safe (the same Idempotency-Key replays).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Invoice id (the public id, e.g. 9N4zvDFEcGKBg78rDcVa)"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Repeating a key with the same body returns the same refund (200, `replayed: true`); with another body it is a 409 `idempotency_conflict` carrying the existing refund's `refund_id` and `link`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"string","pattern":"^\\d+\\.\\d{2}$","examples":["15.00"],"description":"In USD; at most what is left to refund (`refundable_max` less `amount_refunded`)"},"reason":{"type":["string","null"],"description":"Kept as the refund's note (cut to 300 characters)"},"line_items":{"type":["array","null"],"maxItems":500,"items":{"type":"object"},"description":"Your own line items (for example item_id, qty, amount), kept for your records and returned as given; never used for money. A list over 500 items or about 24 KB is not kept (the refund is still made)."},"source":{"type":"string","enum":["api","woo_button"],"default":"api","description":"woo_button: sent by the WooCommerce Refund button"}}}}}},"responses":{"200":{"description":"replayed (same Idempotency-Key and body) or already_waiting (nothing new)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundCreated"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundCreated"}}}},"202":{"description":"needs_address: nothing was created","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"refund_needs_address"},"status":{"const":"needs_address"},"code":{"const":"needs_address"},"invoice_id":{"type":"string"},"order_id":{"type":["string","null"]},"amount":{"type":"string","pattern":"^\\d+\\.\\d{2}$","examples":["15.00"]},"message":{"type":"string"},"link":{"type":"string","format":"uri","description":"The payment in the dashboard, where you can ask the customer for their address"},"ask_address":{"type":"string","description":"The API call that asks the customer for their address"}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the invoices:write scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"refunds_api_off, non_usd_order, not_refundable, held_for_review, refund_exceeds_paid (details.refundable), or idempotency_conflict: that body also carries the existing refund (all the RefundCreated fields: id, refund_id, refund, link) and details (refund_id, invoice_id, link, status, amount)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"invoices:write"}},"/order-addresses":{"get":{"summary":"The addresses your orders were paid to on EVM networks, with what each was derived from","description":"On Base, Polygon and the other EVM networks every order is paid to an address of its own: a small contract that can only split what it holds between your payout address and the fee wallet. Anyone may ask it to do that, so with the values listed here (factory, payees, fee, salt) you can collect an order's money yourself if this service is ever unavailable. Oldest first. Your standing x402 addresses come with the first page, one row per token. Solana and TRON payments go straight to your own wallet and are not listed. Needs `invoices:read`.","parameters":[{"name":"network","in":"query","schema":{"type":"string"},"description":"Only this network (base, polygon, ...)"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":200}},{"name":"after","in":"query","schema":{"type":"string"},"description":"The `next` value of the page before"}],"responses":{"200":{"description":"One page","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["order","x402"]},"invoice":{"type":["string","null"]},"order_id":{"type":["string","null"]},"network":{"type":"string"},"chain_id":{"type":"integer"},"address":{"type":"string","description":"The address the customer paid"},"token":{"type":"string","description":"Token contract"},"asset":{"type":"string","description":"USDC or USDT"},"factory":{"type":"string"},"merchant":{"type":"string","description":"Your payout address this order address pays"},"platform":{"type":"string","description":"The fee wallet"},"fee_bps":{"type":"integer"},"salt":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}},"has_more":{"type":"boolean"},"next":{"type":["string","null"]}}}}}},"400":{"description":"invalid_cursor: `after` is not a value this endpoint returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the invoices:read scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"invoices:read"}},"/payment-links":{"get":{"summary":"List payment links (product, donation and subscription pages), active first","responses":{"200":{"description":"Payment links","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PaymentLink"}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the links:read scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"links:read"},"post":{"summary":"Create a payment link: a reusable page at `url` where customers pay a price you set here","description":"Each customer who opens the link gets their own invoice, priced from the link. With `kind: subscription` and `plan_id`, the page signs customers up to that plan instead (priced by the plan; no price fields). Needs a reviewed account (403 `review_required` otherwise).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentLink"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLink"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"review_required: payment links need a reviewed account; insufficient_scope: the key lacks links:write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"payment_links_unavailable: payment links are turned off on this server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"links:write"}},"/webhook-endpoints":{"get":{"summary":"List webhook endpoints","responses":{"200":{"description":"Endpoints","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"description":{"type":["string","null"]},"event_types":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"}}}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the webhooks:manage scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"webhooks:manage"},"post":{"summary":"Register a webhook endpoint (the signing secret is returned once)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string","maxLength":200},"events":{"type":"array","minItems":1,"maxItems":30,"items":{"type":"string","enum":["invoice.*","invoice.payment_detected","invoice.partially_paid","invoice.paid","invoice.expired","invoice.cancelled","invoice.refunded","invoice.awaiting_bank_transfer","invoice.held_for_review","invoice.overpaid","invoice.deadline_extended","subscription.*","subscription.created","subscription.activated","subscription.renewed","subscription.payment_failed","subscription.past_due","subscription.trial_will_end","subscription.paused","subscription.resumed","subscription.cancelled","subscription.ended","subscription.authorization_active","subscription.authorization_required","subscription.authorization_cancelled","x402.*","x402.payment.settled_late","dispute.*","dispute.reported","dispute.updated","refund_request.*","refund_request.created","refund_request.updated"]},"description":"Events this endpoint receives: exact names or a whole family (`invoice.*`). Default `[\"invoice.*\"]`."}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"secret":{"type":"string","description":"whsec_…, shown once"},"event_types":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the webhooks:manage scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"webhooks:manage"}},"/webhook-endpoints/{id}":{"patch":{"summary":"Change which events an endpoint receives, or its description","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","minItems":1,"maxItems":30,"items":{"type":"string","enum":["invoice.*","invoice.payment_detected","invoice.partially_paid","invoice.paid","invoice.expired","invoice.cancelled","invoice.refunded","invoice.awaiting_bank_transfer","invoice.held_for_review","invoice.overpaid","invoice.deadline_extended","subscription.*","subscription.created","subscription.activated","subscription.renewed","subscription.payment_failed","subscription.past_due","subscription.trial_will_end","subscription.paused","subscription.resumed","subscription.cancelled","subscription.ended","subscription.authorization_active","subscription.authorization_required","subscription.authorization_cancelled","x402.*","x402.payment.settled_late","dispute.*","dispute.reported","dispute.updated","refund_request.*","refund_request.created","refund_request.updated"]},"description":"Events this endpoint receives: exact names or a whole family (`invoice.*`). Default `[\"invoice.*\"]`."},"description":{"type":["string","null"],"maxLength":200}}}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"description":{"type":["string","null"]},"event_types":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the webhooks:manage scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"webhooks:manage"},"delete":{"summary":"Disable a webhook endpoint","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Disabled"},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the webhooks:manage scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"webhooks:manage"}},"/webhook-endpoints/{id}/test":{"post":{"summary":"Send a test event to a webhook endpoint now","description":"POSTs one `webhook.test` event to the endpoint, signed and with the same headers as real events, whatever events it subscribed to. Not retried. Answer it with any 2xx. Integrations should answer 2xx to event types they do not handle. Rate limit: 10 a minute per key.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Sent: whether the endpoint answered 2xx","content":{"application/json":{"schema":{"type":"object","properties":{"event_id":{"type":"string","description":"evt_..."},"type":{"type":"string","enum":["webhook.test"]},"delivered":{"type":"boolean"},"status_code":{"type":["integer","null"]},"error":{"type":["string","null"]}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the webhooks:manage scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"webhooks:manage"}},"/plans":{"get":{"summary":"List plans","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["active","archived"]}}],"responses":{"200":{"description":"Plans","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Plan"}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the subscriptions:read scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"subscriptions:read"},"post":{"summary":"Create a plan (a price and a billing period)","description":"A subscription copies the plan's terms when it starts. To change a price, create a new plan and archive the old one. 409 `subscriptions_unavailable` while subscriptions are switched off.","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Repeating a key returns the same object (200)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePlan"}}}},"responses":{"200":{"description":"Same Idempotency-Key: the existing plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Plan"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Plan"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the subscriptions:write scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"subscriptions:write"}},"/plans/{id}":{"get":{"summary":"Get a plan","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Plan"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the subscriptions:read scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"subscriptions:read"}},"/plans/{id}/archive":{"post":{"summary":"Archive a plan: no new subscriptions; current subscribers keep their terms","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Archived","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Plan"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the subscriptions:write scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"subscriptions:write"}},"/subscriptions":{"get":{"summary":"List subscriptions (newest first), with the customer's email and name","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["incomplete","trialing","active","paused","past_due","unpaid","cancelled","ended","held"]}},{"name":"plan_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"external_ref","in":"query","schema":{"type":"string","maxLength":200}},{"name":"before_id","in":"query","schema":{"type":"string","format":"uuid"},"description":"Next page: the id of the last subscription of the previous page"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Subscriptions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Subscription"}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the subscriptions:read scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"subscriptions:read"},"post":{"summary":"Start a subscription","description":"`schedule_source` mintagepay (default): we bill each period. Without a trial the first period invoice is created now (`latest_invoice`: send the customer to its `checkout_url`); with a trial it is created when the trial ends. Every period the customer gets an email with the payment link and a link to manage or cancel. Nothing is taken from a wallet automatically. `external`: your own billing system (e.g. WooCommerce Subscriptions) creates each period invoice with POST /subscriptions/{id}/invoices.","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Repeating a key returns the same object (200)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubscription"}}}},"responses":{"200":{"description":"Same Idempotency-Key: the existing subscription","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Subscription"},{"type":"object","properties":{"latest_invoice":{"anyOf":[{"$ref":"#/components/schemas/Invoice"},{"type":"null"}]}}}]}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Subscription"},{"type":"object","properties":{"latest_invoice":{"anyOf":[{"$ref":"#/components/schemas/Invoice"},{"type":"null"}]}}}]}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the subscriptions:write scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"plan_archived, subscriptions_unavailable, or the Idempotency-Key was used with another plan or customer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"fx_unavailable: no reliable exchange rate for a non-USD plan right now","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"subscriptions:write"}},"/subscriptions/{id}":{"get":{"summary":"Get a subscription, with the customer's email and name","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the subscriptions:read scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"subscriptions:read"}},"/subscriptions/{id}/periods":{"get":{"summary":"The billed periods and their invoices (newest first)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Periods","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SubscriptionPeriod"}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the subscriptions:read scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"subscriptions:read"}},"/subscriptions/{id}/cancel":{"post":{"summary":"Cancel a subscription","description":"`at_period_end: true` (trialing, active or past_due): no more periods are billed and it ends when the current period or trial is over. Otherwise it is cancelled now and its unpaid open period invoices are cancelled.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"at_period_end":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the subscriptions:write scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"subscription_closed: already cancelled or ended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"subscriptions:write"}},"/subscriptions/{id}/pause":{"post":{"summary":"Pause: no new periods are billed (an invoice already sent stays payable)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Paused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the subscriptions:write scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"subscriptions:write"}},"/subscriptions/{id}/resume":{"post":{"summary":"Resume a paused subscription: billing continues with the period that contains today","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Resumed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the subscriptions:write scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"subscriptions:write"}},"/subscriptions/{id}/portal-link":{"post":{"summary":"The customer's link to manage or cancel the subscription (the same link the emails carry)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"rotate":{"type":"boolean","default":false,"description":"Make a new link; every earlier link stops working"}}}}}},"responses":{"200":{"description":"Link","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the subscriptions:write scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"subscriptions:write"}},"/subscriptions/{id}/invoices":{"post":{"summary":"Bill a period of an external-schedule subscription (e.g. a WooCommerce renewal order)","description":"Only for `schedule_source: external`. At most the subscription's amount, in its currency. The same `order_id` returns the same invoice (200), whatever its state. The customer is emailed the payment link.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","order_id"],"properties":{"amount":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["49.00","1500"],"description":"In the subscription's currency, at most its amount"},"order_id":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":500},"redirect_url":{"type":"string","format":"uri"},"cancel_url":{"type":"string","format":"uri"},"locale":{"type":["string","null"],"maxLength":35},"metadata":{"type":"object","description":"Added to the invoice metadata (subscription_id and subscription_period are ours)"}}}}}},"responses":{"200":{"description":"Same order_id: the existing invoice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"400":{"description":"Above the plan amount, or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope: this key does not have the subscriptions:write scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"not_external (billed by Mintage Pay), or subscription_closed (cancelled, ended, paused or held)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-required-scope":"subscriptions:write"}}},"webhooks":{"invoiceEvent":{"post":{"summary":"Invoice event, sent to your endpoint","description":"Headers: `MintagePay-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, t + \".\" + raw body)>` and `MintagePay-Event-Id`. Verify the signature with your endpoint secret, reject timestamps more than 300 s old, answer 2xx within 10 s. Events may repeat or arrive out of order: re-read the invoice and act idempotently.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Received"}}}},"x402Event":{"post":{"summary":"x402 event (only to endpoints that chose x402.* or the event)","description":"`x402.payment.settled_late`: a /x402/settle call answered settlement_pending, and the transfer then settled. Same signature headers as invoice events.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402Event"}}}},"responses":{"200":{"description":"Received"}}}},"subscriptionEvent":{"post":{"summary":"Subscription event (only to endpoints that chose subscription.* or the event)","description":"Same signature headers as invoice events. `data.subscription` never holds the customer's email or name: read GET /subscriptions/{id}. `data.period` (index and invoice id) is set on activated, renewed, payment_failed and past_due. `cancelled` is also sent when a cancellation at the period end is requested (`cancel_at_period_end: true`); `ended` follows when it takes effect. `resumed` is also sent when a pending cancellation is withdrawn.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionEvent"}}}},"responses":{"200":{"description":"Received"}}}},"disputeEvent":{"post":{"summary":"Card dispute event (only to endpoints that chose dispute.* or the event)","description":"Same signature headers as invoice events. `dispute.reported`: a dispute was recorded on an order (by you, the customer, or Mintage Pay). `dispute.updated`: its status or details changed. `data.invoice.id` is the invoice; re-read GET /invoices/{id}/disputes and act idempotently.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["dispute.reported","dispute.updated"]},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"dispute":{"$ref":"#/components/schemas/Dispute"},"invoice":{"type":"object","properties":{"id":{"type":"string"},"order_id":{"type":["string","null"]}}}}}}}}}},"responses":{"200":{"description":"Received"}}}},"refundRequestEvent":{"post":{"summary":"Refund request event (only to endpoints that chose refund_request.* or the event)","description":"Same signature headers as invoice events. `refund_request.created`: a customer asked for a refund on an order (card or crypto) on the refund request page. `refund_request.updated`: it was approved, declined, withdrawn by the customer, or is waiting again (its refund was cancelled). Answer it in the dashboard (Refunds). `data.invoice.id` is the invoice; the invoice also lists `refund_requests`. Act idempotently.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["refund_request.created","refund_request.updated"]},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"refund_request":{"$ref":"#/components/schemas/RefundRequest"},"invoice":{"type":"object","properties":{"id":{"type":"string"},"order_id":{"type":["string","null"]}}}}}}}}}},"responses":{"200":{"description":"Received"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"mp_live_… key"}},"schemas":{"RefundRequest":{"type":"object","description":"A customer's request for a refund. `status`: open (waiting for the store), approved (a refund was created to `destination`), declined (with `store_message`, emailed to the customer), withdrawn (by the customer).","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["open","approved","declined","withdrawn"]},"reason":{"type":"string","enum":["not_received","not_as_described","damaged","changed_mind","unrecognized","duplicate","other"]},"message":{"type":["string","null"]},"amount":{"type":"string"},"destination":{"type":"object","description":"Kind `cash_app_tag` (R4): a Cash App $cashtag. `address` is the $cashtag and `network` the network the store sends USDC from; Flashnet pays the cashtag in Lightning bitcoin, and it arrives in Cash App as bitcoin, not dollars. The value credited is not guaranteed.","properties":{"kind":{"type":"string","enum":["cash_app","coinbase","wallet","cash_app_tag"]},"network":{"type":"string"},"address":{"type":"string"}}},"bank_dispute_opened":{"type":"boolean"},"store_message":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"decided_at":{"type":["string","null"],"format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"string","description":"Machine code, e.g. validation_failed, not_found, insufficient_scope"},"message":{"type":"string"},"details":{"description":"validation_failed: one item per problem. path is the field in snake_case (nested fields joined with dots), code a stable machine code (required, too_short, too_long, too_small, too_big, invalid_email, invalid_url, invalid_format, invalid_choice, invalid_amount, invalid)","type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}},"CreateInvoice":{"type":"object","required":["amount"],"properties":{"amount":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["49.00","1500"],"description":"The price in `currency`: at most that currency's decimals (2 for USD and EUR, none for JPY, KRW, VND, CLP, PYG, ISK, XAF and XOF, VND, CLP, PYG, ISK, XAF and XOF). The USD amount due must come to 1000000.00 or less."},"currency":{"type":"string","enum":["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"],"default":"USD","description":"Price currency (ISO 4217). Not USD: converted when the invoice is created to the USD amount the customer pays in stablecoins, at a cross-checked exchange rate (rounded up to the cent). 503 `fx_unavailable` when no reliable rate is available right now."},"order_id":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":500},"buyer_email":{"type":"string","format":"email"},"redirect_url":{"type":"string","format":"uri"},"cancel_url":{"type":"string","format":"uri"},"metadata":{"type":"object","description":"Any JSON, up to 4000 characters"},"expires_in_minutes":{"type":"integer","minimum":5,"maximum":10080,"default":60},"send_email":{"type":"boolean","default":false,"description":"Email the checkout link to buyer_email now (needs buyer_email). See POST /invoices/{id}/send."},"send_receipt":{"type":"boolean","default":true,"description":"false: your store sends its own receipt, so Mintage Pay does not email one when the invoice is paid. buyer_email is still stored."},"locale":{"type":["string","null"],"maxLength":35,"examples":["es","pt-BR","de-DE"],"description":"The customer's language for the checkout page and customer emails: en, es, pt-BR, fr, de, it, tr, id, vi, th, ar, hi or ru. Any language tag is accepted (\"es-MX\", \"de_DE\"; any Portuguese is pt-BR). A language not offered is stored as null and the page follows the customer's browser. The customer can always switch on the page."}}},"Invoice":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"invoice"},"status":{"type":"string","enum":["open","partially_paid","paid","expired","cancelled","held_for_review"]},"amount":{"type":"string","pattern":"^\\d+\\.\\d{2}$","examples":["15.00"],"description":"The USD amount due (what the customer pays in USDC/USDT)"},"currency":{"const":"USD"},"price_currency":{"type":"string","description":"The currency the merchant priced in (USD when not converted)"},"price_amount":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["49.00","1500"],"description":"The price in price_currency"},"fx_rate":{"type":"string","description":"USD per 1 unit of price_currency, as applied: amount = price_amount x fx_rate, rounded up to the cent. \"1\" for USD."},"fx_source":{"type":["string","null"],"description":"Rate source, e.g. \"coinbase+frankfurter\" (checked against each other); null for USD"},"fx_at":{"type":["string","null"],"format":"date-time","description":"When the rate was fetched or published; null for USD"},"amount_paid":{"type":"string","pattern":"^\\d+\\.\\d{2}$","examples":["15.00"]},"amount_pending":{"type":"string","pattern":"^\\d+\\.\\d{2}$","examples":["15.00"]},"amount_remaining":{"type":"string","pattern":"^\\d+\\.\\d{2}$","examples":["15.00"],"description":"Still to pay; 0.00 once paid"},"overpaid":{"type":"string","pattern":"^\\d+\\.\\d{2}$","examples":["15.00"]},"buyer_fee":{"type":"string","pattern":"^\\d+\\.\\d{2}$","examples":["15.00"],"description":"Paid by card on the payment page: the fee the customer paid on top of `amount`, so the store receives the full amount. Included in `amount_paid`, never in `overpaid`. 0.00 otherwise."},"amount_short":{"type":"string","pattern":"^\\d+\\.\\d{2}$","examples":["15.00"],"description":"Paid, but this much less than `amount` arrived: accepted by the underpayment tolerance of the merchant. 0.00 otherwise. Fees are only ever on what arrived."},"card_fee_paid_by_store":{"type":"string","pattern":"^\\d+\\.\\d{2}$","examples":["15.00"],"description":"Paid by card where the store pays every card fee (its card buyer pays the order total only): the card processor's fee, which the store covered, so this much less than `amount` arrived and it still counts as paid. Not in `amount_paid`, never in `amount_short`. 0.00 otherwise."},"app_fee_paid_by_store":{"type":"string","pattern":"^\\d+\\.\\d{2}$","examples":["15.00"],"description":"Paid from an app (Cash App, Cash App one-tap, an exchange, Venmo, PayPal) where the store pays every app fee: the network or withdrawal fee the customer's app took out of their send of the order total (for Cash App one-tap: the Lightning conversion fees and Mintage Pay's 1.2% one-tap fee), which the store covered, so this much less than `amount` arrived and it still counts as paid. Not in `amount_paid`, never in `amount_short`. 0.00 otherwise."},"paid_late":{"type":"boolean"},"send_receipt":{"type":"boolean","description":"false: created with send_receipt=false (the store sends its own receipt)"},"held_for_review":{"type":"boolean","description":"A payment came from an address on the OFAC sanctions list. Do not fulfil; invoice.paid is held back until the hold is released."},"order_id":{"type":["string","null"]},"description":{"type":["string","null"]},"metadata":{"type":"object"},"locale":{"type":["string","null"],"enum":["en","es","pt-BR","fr","de","it","tr","id","vi","th","ar","hi","ru",null],"description":"The customer's language for the checkout and emails (null: the customer's browser language, English emails)"},"checkout_url":{"type":"string","format":"uri"},"redirect_url":{"type":["string","null"]},"expires_at":{"type":"string","format":"date-time"},"paid_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"payments":{"type":"array","items":{"type":"object","properties":{"network":{"type":"string"},"token":{"type":"string"},"amount":{"type":"string"},"status":{"type":"string","enum":["pending","confirmed"]},"tx":{"type":"string"},"explorer_url":{"type":["string","null"]},"late":{"type":"boolean"},"from_address":{"type":["string","null"]}}}},"refunds":{"type":"array","items":{"type":"object"}},"amount_refunded":{"type":"string","pattern":"^\\d+\\.\\d{2}$","examples":["15.00"]},"refundable_max":{"type":"string","pattern":"^\\d+\\.\\d{2}$","examples":["15.00"],"description":"The most that can be refunded in total (subtract `amount_refunded` for what is left): what was paid, plus the card provider's fee when a card paid and the store refunds card fees (on by default); where the store pays every card fee, never more than the customer's card statement shows"},"refund_request_url":{"type":["string","null"],"format":"uri","description":"The customer's page to ask the store for a refund, for any paid order (card or crypto); put it in your order emails. Null before payment, or while refund requests are switched off."},"refund_requests":{"type":"array","items":{"$ref":"#/components/schemas/RefundRequest"},"description":"The customer's refund requests on this order, oldest first"},"card":{"type":["object","null"],"description":"Paid by card on the payment page (null otherwise). `charged` and `fee` are what the card page reported, only when within the quoted total; null when unknown.","properties":{"rail":{"type":"string","enum":["card","apple_pay","google_pay"]},"from_balance":{"type":"boolean","description":"Paid from a balance an earlier card purchase left: no new card charge for this order"},"charged":{"type":["string","null"]},"fee":{"type":["string","null"]},"brand":{"type":["string","null"]},"last4":{"type":["string","null"]},"wallet_type":{"type":["string","null"]},"descriptor":{"type":["string","null"],"description":"What the customer's card statement shows, when known"},"purchased_at":{"type":"string","format":"date-time"},"delivery_verified":{"type":"boolean","description":"The card provider's USDC reaching the customer's wallet, and that wallet paying this invoice, were found on chain"},"refund_request_url":{"type":["string","null"],"format":"uri","description":"The customer's page to ask the store for a refund (put it in your order emails)"}}},"disputes":{"type":"array","items":{"$ref":"#/components/schemas/Dispute"},"description":"Card disputes reported on this order"},"bank_transfer":{"type":["object","null"],"description":"Single-invoice reads and webhooks only"},"payment_link":{"type":["object","null"],"description":"Single-invoice reads and webhooks only: the product or donation link it was paid from (`kind`: product or donation)"},"customer":{"type":["object","null"],"description":"invoice.paid webhooks of payment-link orders only"},"subscription":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"period_index":{"type":"integer"}},"description":"The subscription and period this invoice bills (null: not a subscription invoice)"}}},"Dispute":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"const":"dispute"},"source":{"type":"string","enum":["store_report","buyer_declared","operator","provider_notice"]},"reason":{"type":"string","enum":["unrecognized","fraud","not_received","not_as_described","credit_not_processed","duplicate","other","unknown"]},"status":{"type":"string","enum":["reported","open","buyer_won","buyer_lost","withdrawn","unknown"]},"amount":{"type":["string","null"]},"provider_case_ref":{"type":["string","null"]},"opened_at":{"type":["string","null"],"format":"date-time"},"closed_at":{"type":["string","null"],"format":"date-time"},"refund_sent_before":{"type":"boolean","description":"A refund had already been sent when the dispute was reported"},"delivery":{"type":["object","null"],"properties":{"carrier":{"type":["string","null"]},"tracking":{"type":["string","null"]},"delivered_at":{"type":["string","null"],"format":"date-time"}}},"reported_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Refund":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"network":{"type":"string"},"token":{"type":"string","description":"USDC or USDT"},"token_address":{"type":"string"},"chain_id":{"type":["integer","null"]},"amount":{"type":"string","description":"In the token (USD stablecoin), e.g. 5.000000"},"amount_micro":{"type":"string"},"amount_units":{"type":"string","description":"In the token's own units"},"decimals":{"type":"integer"},"to":{"type":"string","description":"The customer's address"},"status":{"type":"string","enum":["requested","confirmed","cancelled"],"description":"cancelled appears only in a replayed POST /invoices/{id}/refunds answer (lists leave cancelled refunds out)"},"tx":{"type":["string","null"]},"explorer_url":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"confirmed_at":{"type":["string","null"],"format":"date-time"},"detected":{"type":"boolean","description":"Recorded because the transfer was found on the network (for example a withdrawal from an exchange), without a transaction ID being given"},"source":{"type":"string","enum":["dashboard","request","api","woo_button","operator"],"description":"Where it was created: your dashboard, a customer's refund request you approved, the refund API, the WooCommerce Refund button, or Mintage Pay (a refund paid on your behalf). Refunds before this field existed are `dashboard`."},"paid_by":{"type":"string","enum":["store","operator"],"description":"Who sent this refund: `store` (you) or `operator` (Mintage Pay sent it on your behalf)"},"line_items":{"type":["array","null"],"items":{"type":"object"},"description":"The line items given when it was created through the API, as given"},"cash_app_tag":{"type":"string","description":"Only on a refund to a Cash App $cashtag (R4): the $cashtag. Such a refund is sent through Flashnet: `to` is the deposit address Flashnet gave (or the $cashtag before the store asked for a quote), `tx` the deposit the store sent, and it is confirmed when Flashnet paid the cashtag."},"cash_app_tag_status":{"type":["string","null"],"enum":["to_send","sending","completed","problem","cancelled",null]}}},"RefundCreated":{"type":"object","description":"A refund (all the Refund fields) with what POST /invoices/{id}/refunds adds.","allOf":[{"$ref":"#/components/schemas/Refund"},{"type":"object","properties":{"object":{"const":"refund"},"refund_id":{"type":"string","format":"uuid","description":"The same as id"},"refund":{"$ref":"#/components/schemas/Refund"},"invoice_id":{"type":"string","description":"The invoice's public id"},"order_id":{"type":["string","null"]},"link":{"type":"string","format":"uri","description":"The refund in the dashboard (/payments?invoice=…&refund=…), where it is sent"},"replayed":{"type":"boolean"},"already_waiting":{"type":"boolean"},"destination":{"type":"string","enum":["refund_request","customer_address","payer_wallet"],"description":"Only on 201: where the address came from"},"warnings":{"type":"array","description":"A card dispute on this order (the bank may already have paid the buyer back). Warn only: the refund is made.","items":{"type":"object","properties":{"code":{"type":"string","enum":["dispute_open","dispute_buyer_won"]},"message":{"type":"string"},"dispute_id":{"type":"string","format":"uuid"}}}}}}]},"CreatePaymentLink":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":120},"description":{"type":"string","maxLength":1000},"kind":{"type":"string","enum":["product","donation","subscription"],"default":"product"},"plan_id":{"type":"string","format":"uuid","description":"Subscription links (required with kind subscription): an active plan of yours. The link takes the plan's price and currency; price, quantity, shipping and stock fields are ignored."},"price_mode":{"type":"string","enum":["fixed","open"],"description":"fixed: unit_price; open: the customer picks between open_min and open_max. Default fixed (open for donations). Not used for subscription links."},"currency":{"type":"string","enum":["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"],"description":"Default: the account's default currency"},"unit_price":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["49.00","1500"]},"open_min":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["49.00","1500"]},"open_max":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["49.00","1500"]},"shipping":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["49.00","1500"]},"qty_min":{"type":"integer","minimum":1,"maximum":100,"default":1},"qty_max":{"type":"integer","minimum":1,"maximum":100,"default":1},"stock_limit":{"type":["integer","null"],"minimum":0},"collect_name":{"type":"boolean","default":true},"collect_phone":{"type":"boolean","default":false},"collect_shipping":{"type":"boolean","default":false},"custom_field_label":{"type":"string","maxLength":80},"success_url":{"type":"string","format":"uri","description":"https only"},"presets":{"type":"array","maxItems":6,"items":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["49.00","1500"]},"description":"Donation links: preset amounts"},"allow_custom":{"type":"boolean","description":"Donation links: the donor may enter an amount between open_min and open_max"},"locale":{"type":["string","null"],"description":"The page language (null: the customer's browser)"}}},"PaymentLink":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"const":"payment_link"},"url":{"type":"string","format":"uri","description":"Share this with customers"},"public_id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"kind":{"type":"string","enum":["product","donation","subscription"]},"plan_id":{"type":["string","null"],"format":"uuid","description":"Subscription links: the plan customers subscribe to"},"status":{"type":"string","enum":["active","archived"]},"price_currency":{"type":"string"},"price_mode":{"type":"string","enum":["fixed","open","plan"]},"unit_price":{"type":["string","null"]},"open_min":{"type":["string","null"]},"open_max":{"type":["string","null"]},"shipping":{"type":"string"},"presets":{"type":["array","null"],"items":{"type":"string"}},"allow_custom":{"type":["boolean","null"]},"qty_min":{"type":"integer"},"qty_max":{"type":"integer"},"stock_limit":{"type":["integer","null"]},"sold_count":{"type":"integer"},"paid_orders":{"type":["integer","null"]},"collect_name":{"type":"boolean"},"collect_phone":{"type":"boolean"},"collect_shipping":{"type":"boolean"},"custom_field_label":{"type":["string","null"]},"success_url":{"type":["string","null"]},"image_url":{"type":["string","null"]},"locale":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"Order":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"order"},"status":{"type":"string","enum":["open","partially_paid","paid","expired","cancelled"]},"product":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["product","donation"]}}},"quantity":{"type":"integer"},"price_currency":{"type":"string","description":"Currency of unit_price and shipping"},"unit_price":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["49.00","1500"]},"shipping":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["49.00","1500"]},"amount":{"type":"string","pattern":"^\\d+\\.\\d{2}$","examples":["15.00"],"description":"The USD amount of the invoice"},"paid_at":{"type":["string","null"]},"fulfilled_at":{"type":["string","null"]},"created_at":{"type":"string"},"customer":{"type":["object","null"],"properties":{"email":{"type":"string"},"name":{"type":["string","null"]},"phone":{"type":["string","null"]},"custom":{"type":["string","null"]},"message":{"type":["string","null"],"description":"Donation links: the donor's message"},"shipping_address":{"type":["object","null"]}}}}},"Plan":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"const":"plan"},"name":{"type":"string"},"description":{"type":["string","null"]},"amount":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["49.00","1500"]},"currency":{"type":"string"},"interval":{"type":"string","enum":["day","week","month","year"]},"interval_count":{"type":"integer"},"trial_days":{"type":"integer"},"max_failed_periods":{"type":"integer"},"dunning_action":{"type":"string","enum":["cancel","unpaid"]},"status":{"type":"string","enum":["active","archived"]},"metadata":{"type":"object"},"created_at":{"type":"string","format":"date-time"}}},"CreatePlan":{"type":"object","required":["name","amount","interval"],"properties":{"name":{"type":"string","maxLength":120},"description":{"type":["string","null"],"maxLength":1000},"amount":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["49.00","1500"],"description":"Per period, in `currency` (at least 1 unit)"},"currency":{"type":"string","enum":["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"],"default":"USD","description":"Each period invoice converts to USD at that day's rate, like any invoice"},"interval":{"type":"string","enum":["day","week","month","year"],"description":"Months and years are calendar periods from the start date; a start on the 31st bills on the last day of shorter months"},"interval_count":{"type":"integer","minimum":1,"default":1,"description":"day 1-365, week 1-52, month 1-12, year 1-5"},"trial_days":{"type":"integer","minimum":0,"maximum":365,"default":0},"max_failed_periods":{"type":"integer","minimum":1,"maximum":12,"default":3,"description":"Unpaid periods in a row before dunning_action"},"dunning_action":{"type":"string","enum":["cancel","unpaid"],"default":"cancel","description":"unpaid: stop billing new periods but keep the subscription (paying an open invoice brings it back)"},"metadata":{"type":"object"}}},"Subscription":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"const":"subscription"},"status":{"type":"string","enum":["incomplete","trialing","active","paused","past_due","unpaid","cancelled","ended","held"]},"plan":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"amount":{"type":"string","pattern":"^\\d+(\\.\\d+)?$","examples":["49.00","1500"]},"currency":{"type":"string"},"interval":{"type":"string"},"interval_count":{"type":"integer"},"schedule_source":{"type":"string","enum":["mintagepay","external"]},"external_ref":{"type":["string","null"]},"locale":{"type":["string","null"]},"customer":{"type":["object","null"],"properties":{"email":{"type":"string"},"name":{"type":["string","null"]}},"description":"API reads only (never in webhooks); null once purged, 2 years after the subscription ended"},"current_period":{"type":["object","null"],"properties":{"index":{"type":"integer"},"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}},"next_billing_at":{"type":["string","null"],"format":"date-time","description":"When the next period invoice is created (mintagepay schedule)"},"trial_end":{"type":["string","null"],"format":"date-time"},"cancel_at_period_end":{"type":"boolean"},"cancelled_at":{"type":["string","null"],"format":"date-time"},"cancel_reason":{"type":["string","null"],"enum":["merchant","customer","dunning","incomplete_expired","merchant_disabled",null]},"ended_at":{"type":["string","null"],"format":"date-time"},"paused_at":{"type":["string","null"],"format":"date-time"},"failed_periods":{"type":"integer","description":"Unpaid periods in a row"},"metadata":{"type":"object"},"created_via":{"type":"string","enum":["api","dashboard","payment_link"]},"created_at":{"type":"string","format":"date-time"}}},"CreateSubscription":{"type":"object","required":["plan_id","customer"],"properties":{"plan_id":{"type":"string","format":"uuid"},"customer":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"name":{"type":"string","maxLength":120}}},"locale":{"type":["string","null"],"maxLength":35,"description":"The customer's language for the emails and pages (en, es, pt-BR, fr, de, it, tr, id, vi, th, ar, hi, ru)"},"schedule_source":{"type":"string","enum":["mintagepay","external"],"default":"mintagepay"},"external_ref":{"type":"string","maxLength":200,"description":"Your id for it (required for external)"},"redirect_url":{"type":"string","format":"uri","description":"Where the first invoice's checkout returns to"},"metadata":{"type":"object"}}},"SubscriptionPeriod":{"type":"object","properties":{"index":{"type":"integer"},"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"},"order_id":{"type":["string","null"]},"settled_at":{"type":["string","null"],"format":"date-time"},"failed_at":{"type":["string","null"],"format":"date-time"},"invoice":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"amount":{"type":"string","pattern":"^\\d+\\.\\d{2}$","examples":["15.00"]},"amount_paid":{"type":"string","pattern":"^\\d+\\.\\d{2}$","examples":["15.00"]},"checkout_url":{"type":"string"},"expires_at":{"type":"string"},"paid_at":{"type":["string","null"]}}}}},"SubscriptionEvent":{"type":"object","properties":{"id":{"type":"string","description":"evt_…"},"type":{"type":"string","enum":["subscription.created","subscription.activated","subscription.renewed","subscription.payment_failed","subscription.past_due","subscription.trial_will_end","subscription.paused","subscription.resumed","subscription.cancelled","subscription.ended","subscription.authorization_active","subscription.authorization_required","subscription.authorization_cancelled"]},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"subscription":{"$ref":"#/components/schemas/Subscription"},"period":{"type":"object","properties":{"index":{"type":"integer"},"invoice_id":{"type":["string","null"]}}}}}}},"X402Event":{"type":"object","properties":{"id":{"type":"string","description":"evt_…"},"type":{"type":"string","enum":["x402.payment.settled_late"]},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"x402_payment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["x402_payment"]},"status":{"type":"string"},"network":{"type":"string","description":"CAIP-2, e.g. eip155:8453"},"network_name":{"type":"string"},"asset":{"type":"string"},"pay_to":{"type":"string"},"payer":{"type":"string"},"amount":{"type":"string","description":"Atomic token units"},"amount_usd":{"type":"string"},"nonce":{"type":"string"},"transaction":{"type":["string","null"]},"resource_url":{"type":["string","null"]},"settled_at":{"type":["string","null"],"format":"date-time"},"final":{"type":"boolean"}}}}}}},"Event":{"type":"object","properties":{"id":{"type":"string","description":"evt_…"},"type":{"type":"string","enum":["invoice.payment_detected","invoice.partially_paid","invoice.paid","invoice.expired","invoice.cancelled","invoice.refunded","invoice.awaiting_bank_transfer","invoice.held_for_review","invoice.overpaid","invoice.deadline_extended"]},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"invoice":{"$ref":"#/components/schemas/Invoice"}}}}}}}}