Moon Card API documentation
Issue and control payment cards with the Moon Card Issuing API, and let AI agents pay through the MCP server with a person approving each purchase.
The Moon Card Issuing API lets you issue payment cards to your own customers and control how they spend. You fund a balance with Moon, issue cards against it, decide what each card may spend, and follow every authorization, clearing, reversal and refund as it happens.
With it you can:
- Issue and manage cards — create a card from a card product, read it back with its full card details, freeze it, activate it, and terminate it.
- Fund and load — add money to your prepaid balance by bank transfer, then load it onto cards.
- Control spending — attach velocity controls to a card or a cardholder, and read how much of a limit is used.
- Verify cardholders and organizations — run identity and business verification, and track its status.
- Follow the money — read a card's transaction feed, and receive webhooks for transactions, declines, funding and verification updates.
- Decide authorizations yourself — approve or decline each purchase in real time with just-in-time authorization.
- Let AI agents pay, with a person in the loop — connect your AI assistant or your own agent to the MCP server and issue ask-first cards that charge nothing until the person who holds the card has approved the purchase through a purchase intent. Connecting an AI assistant takes a few minutes.
Two versions
Two versions of the API run side by side. Both are active, both authenticate with the same key, and both act on the same organization, cardholders and cards.
- V1 is the shortest path to a card. You reference a cardholder by an identifier you choose, and fund each card directly from your prepaid balance.
- V2 models the pieces V1 keeps implicit: organizations you can nest, accounts that hold balances, cardholders as records you create, and a session token that lets a cardholder manage their own cards from your app.
Neither is a superset of the other, and you can use both with one key. API versions compares them endpoint by endpoint; Versioning and changelog states how changes are made and lists what has changed.
How an integration fits together
You start by funding your prepaid balance — the money you have added to Moon but not yet put on a card. You then identify the cardholder the card is for, either by your own customer id (V1) or as a cardholder record you create under an organization (V2). You issue the card from a card product and put money on it: from the prepaid balance in V1, or from the account the card is issued against in V2. From then on the cardholder spends, and Moon applies your spending controls and the agreed fees on every transaction. You read those transactions back from the card's feed and receive them as webhooks as they happen.
The words this documentation uses for each of those things are defined in the Glossary.
Base URLs
| Environment | Base URL | V1 | V2 |
|---|---|---|---|
| Production | https://api.themooncard.com | /v1/api-gateway | /v2/api-gateway |
See Environments.
Authenticating
Send your API key in the x-api-key header on every request; there is no token exchange step. See Authentication for key handling, for the cardholder session token, and for the few endpoints that need no credential.
Start here
| If you want | Go to |
|---|---|
| A card in three requests, keyed by your own customer id | Issuing your first card (V1) |
| Organizations, accounts and cardholders as first-class resources | Quickstart (V2) |
Both walkthroughs run end to end in Sandbox. Once a card exists, Adding a balance, Simulating card transactions and Webhooks take you through funding, spending and reconciling.
Before you write much client code, read Data formats and ids, Pagination, Errors and Rate limits. Between them they cover the conventions every endpoint follows.
Questions the docs do not answer go to our team.
Last updated September 25, 2026