API Versions (V1 vs V2)

Choosing between the V1 and V2 API.

API versions (V1 and V2)

Moon exposes two API versions side by side. Both are active, both authenticate with the same x-api-key, and both operate on the same organization, cardholders and cards. They differ in how you identify cardholders, how cards are funded, and in which resources they expose. Neither is a superset of the other — check the map below before choosing.

V1

The simplest way to issue and manage cards. You reference cardholders by an external_id you choose; if no cardholder with that id exists when you issue a card, one is created under your organization. Cards are funded from your prepaid balance one card at a time. The Issuing your first card guide uses V1.

V2

A richer model for larger integrations. V2 adds first-class organizations (with children), accounts that hold balances, cardholders as a resource you create, list and update, KYC/KYB status and verification links per cardholder or organization, and cardholder login, which gives a cardholder a token to read and manage their own cards directly.

In V2, POST /cards requires both cardholder_id and account_id (a missing id returns 400), plus the card_product_id to issue from.

Only V2 has: organizations, accounts and transfers, cardholder create/list/update, GET /webhooks to read the registered URL, cardholder login, and GET /controls/velocity/status, which lets a logged-in cardholder read their own spending status.

Endpoint map

Paths are relative to each version's base URL. "—" means the version has no equivalent.

Webhook events (including JIT authorization requests) are delivered to the one URL registered for your organization, whichever version you registered it with — see Webhooks.

Differences to plan for when moving from V1 to V2

• Creating a card. V1 takes the card product in the path and external_id in the body, and can load the card in the same request with amount (paid from the prepaid balance, in card_currency). V2 takes card_product_id, cardholder_id and account_id in the body, has no amount, and requires the cardholder and account to exist already. Create the cardholder with POST /cardholders (setting external_id to the value you used as external_id), create or pick an account, fund it, then issue.
• Card object. Identical fields in both versions, with one addition in V2: card_type.
• Freeze response. V1 returns { message, frozen }; V2 returns { message } only. Fetch the card if you need the new state.
• Filtering cards by your own id. Both GET /card (V1) and GET /cards (V2) accept external_id; V2 also accepts card_holder_id.
• Cardholder tokens. V2 card routes (create, list, get, activate, transactions) accept a cardholder's token from POST /cardholders/auth/login in place of your API key, scoped to that cardholder's cards. GET /controls/velocity/status goes further: it requires a cardholder token and rejects an API key with 403.

You do not have to migrate everything at once: a card issued through V1 is visible through V2 GET /cards, and a cardholder created implicitly by V1 is the same record V2 returns from GET /cardholders, with your id in external_id.

Which should I use?

• Use V2 if you need organizations, accounts, cardholders as first-class resources, KYC/KYB per cardholder or organization, or want cardholders to log in and manage their own cards.

If you are unsure, contact our team.

How changes are communicated

• Breaking changes are introduced as a new version rather than by changing an existing one. Additive changes — new endpoints, new optional fields, new enum values — can appear in either version at any time, so parse responses leniently and ignore fields you do not know.
• Response fields are spelled one way only, in snake_case.
• This page and the affected endpoint pages are updated when behaviour changes. Dated entries for each customer-visible change are on Versioning and changelog.

Last updated August 17, 2026