Ask-First Cards

An ask-first card charges nothing until the person who holds it has approved that exact purchase. You ask before you pay; Moon emails them a one-time link; the authorization engine then lets through the charges that match what they approved.

It exists for software that spends on someone's behalf. A card can be capped and locked down in advance, but a cap cannot tell a purchase the person wanted from one they did not. Ask-first moves that decision to the person, per purchase, without putting them in the payment path.

An approval can be one of three things, and you choose which when you ask: a single purchase, an order budget at one merchant over a few days, or a standing permission bounded by a monthly limit. See Which kind to ask for.

Issuing an ask-first card

Set ask_first when you create the card:

curl --request POST \
     --url https://api.themooncard.com/v2/api-gateway/cards \
     --header 'content-type: application/json' \
     --header 'x-api-key: YOUR_API_KEY' \
     --data '{
       "cardholder_id": "9d4a1f70-2c8b-4f31-a6de-7b5c0e93af12",
       "account_id": "0b1c2d3e-4f50-4a6b-8c9d-0e1f2a3b4c5d",
       "ask_first": true
     }'

GET /v2/api-gateway/cards and GET /v2/api-gateway/cards/{card_id} report ask_first on every card.

Under the hood the card is issued with one fixed velocity control (INTENT over TOTAL), and that control is what the authorization engine reads. It lists and reads through the velocity-control endpoints like any other control, flagged fixed: true, and the generic update and delete calls refuse it with CONTROL_IS_FIXED. limit_amount is inert on it: an INTENT control measures no window.

A card can be ask-first and single-use and merchant-locked. Those are three independent fixed controls, and any one of them can decline an authorization on its own.

An agent connected over MCP can also turn the mode on and off for a card that already exists, with enable_ask_first and disable_ask_first. Both are idempotent and say which they were: enable_ask_first on a card that already asks first answers enabled: false. Disabling leaves approvals the person has already given alone — they simply stop being consulted, and count again if ask-first is turned back on before they expire. See MCP Server.

The flow

1. Ask. POST /v2/api-gateway/purchase-intents with the card, the merchant, the price — in the card's currency, or as the store shows it in another currency — a one-sentence reason and, when you know it, the site.
2. Moon emails the approver a one-time link and answers 201 with the intent in AWAITING_APPROVAL.
3. Wait. For the PURCHASE_INTENT_APPROVED webhook, or by polling GET /v2/api-gateway/purchase-intents/{id}. Never attempt the payment first, and never retry it in a loop — the answer is a person's, and an authorization sent before they answer is simply declined.
4. Pay. The engine matches the authorization against the approval.

An agent working over MCP does the same four steps with request_purchase, get_purchase_intent and get_payment_credential — the last of which is the only way to get the card number of an ask-first card. See MCP Server.

1. Request approval

Send an Idempotency-Key header. A retry with the same key returns the first attempt's answer rather than emailing the person a second time. See Idempotency.

Nothing here charges the card and nothing here moves money. It asks a person a question.

deduplicated: true means nothing new was created: an identical request on the same card was still waiting for the person's answer, so that request came back and nobody was emailed again. See Identical requests are asked once.

merchant_names is every name the approval matches: merchant.name first, then the other spellings you gave and any Moon expanded from a brand it recognises. The approver is shown the whole list before deciding.

2. What the approver sees

The email carries the merchant, the amount, the card's last four digits, your reason and — when you sent one — the merchant_domain, with an Approve and a Deny button. The link takes no login, works once for the decision, and stops working at expires_at. Unknown, used and expired links all show the same page — which of the three it was is not a visitor's business.

For an order or a recurring approval the page also states, above the buttons, exactly what else they are agreeing to:

• an order — "Approve up to max_total currency at merchant over the next N days. The store may charge this in several parts."
• a standing approval — "Approving also allows future charges from merchant on this card, up to monthly_limit currency per calendar month, without asking again, until it is stopped."

For both, the same link keeps working after the decision and shows what has been charged and what is left, with a Stop button that ends the approval.

If the request was signed with a registered agent key, the email and the page also name the agent: "Requested by label (key …last 8 of the thumbprint)". An unsigned request reads only as "an agent". See Agent keys and signed requests.

The email is not the only way to answer:

approved_via on the intent says which it was: email, mcp or web. The two tools record a decision the person has stated; an agent must never decide on their behalf, and when one records a decision Moon emails the approver a receipt of it. A partner API key cannot answer at all — it is the credential that asks. See Purchase intents.

3. Wait for the answer

status is evaluated against expires_at on every read, so a request nobody answered in time reports EXPIRED rather than an AWAITING_APPROVAL that can never be satisfied. The list filter matches the same effective status.

4. Pay

Once the intent is APPROVED, charge the card as you normally would. The engine matches the authorization against the approval; consumed_transaction_id then names the authorization that spent a single approval.

An agent that needs the card number for this step calls get_payment_credential({ intent_id }) over MCP. It returns the credential for that one approved purchase together with approved_for — merchant, amount, and the range the gate will actually accept: the symmetric band on a single approval, what is left of the budget on an order, the monthly limit on a standing one. One approval may hand the credential over at most 10 times. reveal_card_credentials refuses on an ask-first card. See MCP Server.

Which kind to ask for

order and recurring cannot be combined: one is a budget for a few days, the other a permission with no end date. The call is refused if you send both.

A single approval is declined by a small verification authorization, by a charge that arrives when the order ships rather than when it is placed, by a split shipment, and by a final amount a few percent off the estimate. Every one of those is ordinary, and every one of them is what order is for.

Order approvals

• max_total is amount plus the tolerance band, computed when the intent is created and returned on every read alongside spent and remaining. Every authorization at that merchant is accepted while spent + this charge <= max_total, with no lower bound per charge.
• The default tolerance for an order is 10 percent, not one minor unit. Shipping quoted at checkout, tax computed at the warehouse, a weight-priced grocery item, a tip and an acquirer's own conversion are all proportional, and a one-cent band would decline the ordinary case. Every point of tolerance is budget the person is agreeing to, so name your own when you can.
• valid_for_days (1–90, default 14) is counted from the moment the person approves. answer_within_minutes still bounds how long they have to answer; on approval expires_at is rewritten to the window, and reads report it as spendable_until. Marketplaces and pre-orders charge at shipment, so set it to cover the latest delivery estimate plus a week.
• An order closes only when its budget is gone. There is no "that was the final capture" signal in an authorization stream, so the arrival of the order total proves nothing: until the budget runs out the order stays APPROVED and ends when its window does. A closed order reads CONSUMED and authorizes nothing further — unlike a standing approval, it is not a permission.
• At the end of its window, an order that was charged moves to CONSUMED and emits no PURCHASE_INTENT_EXPIRED: it is a purchase that happened, not an approval nobody answered. One that was never charged expires with the event like any other.
• A charge that would take it past max_total, or that arrives after the window, is declined INTENT_MISMATCH and nothing is recorded.

Standing (recurring) approvals

• monthly_limit — not the per-charge amount — is what bounds it, and it is the number the person is shown.
• The first charge is accepted when the merchant matches and the amount fits monthly_limit. It does not have to match amount: a free trial charges nothing today and its first real charge arrives weeks later for a figure nobody quoted, so holding it to the exact band declined the commonest subscription there is. It consumes the intent exactly as a one-off would, and counts against its month.
• first_charge_within_days (1–60, default 45) is how long the approval waits for that first charge. As with an order, expires_at is rewritten on approval, so the approval is still there weeks later.
• Every later charge is let through when the merchant matches and spent this UTC calendar month + this charge <= monthly_limit. The per-charge band does not apply to it, because a usage-billed subscription varies month to month. recurring_spent_this_month and recurring_period_start report where the month stands.
• A charge that would take the month past the limit is declined INTENT_MISMATCH and nothing is recorded. Ask for a higher monthly_limit with a fresh request.
• A standing approval is pinned to the merchant category it was first used at (recurring_mcc). A later authorization carrying a different category is refused.
• A card may hold at most 20 standing approvals at once (TOO_MANY_RECURRING_APPROVALS). A standing approval does not expire, so that cap is cleared by cancelling one, not by waiting.

Refunds and reversals do not give budget back, on an order or on a standing approval. That is deliberately conservative: a refund must not be a way to make room for another charge.

Matching

The merchant is matched with exactly the same rules as a card merchant lock, so an intent and a lock on the same card can never disagree about what "this merchant" means:

• name is matched case-insensitively as a substring of the acquirer's merchant descriptor. Acquirers pad and prefix that descriptor unpredictably, so TRAIN TICKETS matches SQ *TRAIN TICKETS SAN FRANCISCO and TRAIN TICKETS *BOOKING alike. Send the shortest string that identifies the merchant.
• mcc is an exact four-digit merchant category code, never a substring.
• Every field the intent names has to match. Give both and both must match.

Naming a merchant you cannot see yet

The acquirer descriptor does not exist until the first charge, and it is rarely the brand: a marketplace bills as an abbreviation, an app store as a billing domain, a hosted store under its platform's prefix. An approval naming only the brand misses all of them and the charge is declined INTENT_MISMATCH — for a purchase the person explicitly said yes to.

Three things address that, and they stack:

1. merchant.name takes an array of up to five names, and any one of them matching is enough.
2. Moon expands a brand it recognises into the statement descriptors that brand is known to bill under, at request time. The expanded list comes back as merchant_names and the approver is shown every name before deciding — nothing is hidden. That table is curated by hand and is best-effort: treat a miss as ordinary rather than a bug.
3. After a mismatch, read the descriptor the network actually sent and ask again naming it. An agent over MCP does this with list_card_declines, which returns the recent declines on a card with merchant_descriptor exactly as it arrived. Do not retry the payment against the old approval.

Amounts

The single band is symmetric on purpose: a charge below the approved amount is outside it too, so a merchant that authorizes one cent before the real charge cannot spend a $500 approval on the cent.

A zero-amount card verification — what many subscription merchants send before a real charge — passes on a merchant match alone and does not spend the approval. The approval is still there when the real charge arrives.

When several approvals could take one charge

A card can hold an open order and a subscription at the same merchant at once. Moon tries them in this order, and stops at the first that authorizes:

1. a single or recurring approval whose exact band the charge fits;
2. the open order budgets at that merchant, oldest first;
3. a recurring approval's first charge, against its monthly limit;
4. the standing approvals already in force.

A recurring first charge accepts anything up to a month's budget, which is a very wide match — so it is tried after the orders rather than before them, or a shipment would spend a subscription's one first charge.

merchant_domain

A bare hostname: shop.example.com, never https://shop.example.com/checkout. It is trimmed and lower-cased, and a URL, a port, an @, an IP address or a unicode domain is rejected with a validation error rather than repaired — send the punycode form of an internationalised name. Guessing which part of a URL was the merchant's site, in a value that goes in front of a person deciding whether to spend money, is worse than a clear refusal.

It is advisory at the network layer, and always will be. The card networks carry no domain in an authorization, so the gate does not and cannot check it, and no charge is ever declined for coming from a different site. What it buys is three things:

• the approval email and page show it next to the merchant, so ACME STORE stops being a descriptor the person has to take on trust;
• it is part of the idempotency fingerprint, because a different site is a different question to ask;
• get_payment_credential names it as the one place an agent may use the credential.

Lifetime

An unanswered request lasts answer_within_minutes — 60 minutes by default, anything from 5 to 1440 if you set it. That deadline applies only to answering; until then expires_at is that deadline. How long the answer is then worth something depends on the kind:

On approval expires_at is rewritten to that window, in the same statement that records the decision, and the reads also return it as spendable_until — null before approval and on a recurring approval. A denial keeps the original deadline.

There is no sweep job. An intent past expires_at is recognised as expired the first time it is read — by these endpoints, by an agent's tools, or by the approval page — and PURCHASE_INTENT_EXPIRED is emitted at that point. The authorization path never emits it: it answers the card network under a deadline, so it treats an expired approval as absent and declines INTENT_REQUIRED, exactly as if the approval had never existed.

Treat expires_at as the deadline and the webhook as a convenience. It can arrive well after expires_at, and an intent nobody ever looks at again never produces one.

A card may hold at most 20 live intents at once (TOO_MANY_PENDING_INTENTS). An approved order stays live for its whole window, so that cap is cleared by cancelling one rather than by waiting.

Cancelling and stopping

curl --request DELETE \
     --url https://api.themooncard.com/v2/api-gateway/purchase-intents/6c1f9a84-0b73-4d52-9e18-3a7c5d2b4e60 \
     --header 'x-api-key: YOUR_API_KEY'

The intent is not deleted — it comes back with status: CANCELLED, and a PURCHASE_INTENT_CANCELLED webhook is emitted carrying cancelled_by (partner when you called it, approver when the person did). Moon itself cancels only duplicate one-off approvals once an identical one has been spent, with cancel_reason: superseded_by_consumed_sibling — see Identical requests are asked once.

Three cases are allowed, and all three are endings rather than reversals:

Anything else is refused with 409 PURCHASE_INTENT_NOT_PENDING: an approval a person gave for one purchase is theirs, not yours to take back, so an APPROVED single intent, a spent one-off CONSUMED intent and one that has already expired are all left alone. A standing approval that is APPROVED but has not been charged yet is refused too; the person can stop it from their link at any time.

The person can end an order or a standing approval themselves, from the same emailed link, with a Stop button. Either party doing it emits the same webhook, so a partner whose subscription stops being authorized learns why without polling.

Declines

Two decline types are specific to ask-first cards, and they mean different things:

Both arrive as an ordinary CARD_DECLINE webhook. Software that cannot tell them apart will re-ask for the wrong thing forever, so branch on decline_type_id.

An agent over MCP can read the same declines directly with list_card_declines, which returns the acquirer descriptor the network sent — which is what an INTENT_MISMATCH is almost always about.

Errors

These are returned by POST /v2/api-gateway/purchase-intents in the standard error envelope.

On the reads and on cancel:

Related

• Purchase intents — the three kinds of approval side by side, prices in the store's currency, the answer and spend windows, duplicate requests, and every way the approver can answer.
• MCP Server — request_purchase, get_payment_credential, list_card_declines and the rest of the flow for an agent, plus agent keys.
• Webhooks — the PURCHASE_INTENT_* events and their payload.
• Errors — the error envelope and how to branch on a failure.
• Idempotency — the Idempotency-Key header.

Last updated September 26, 2026