Browse the docs

Glossary

The terms used across these docs and the API surface each one maps to.

The words this documentation uses for the things the API works with, and the field or endpoint each one maps to. Where two terms sit close together, the entry says how to tell them apart.

Account

A funding pot inside an organization, in V2 only. Every V2 card draws its balance from exactly one account, and POST /accounts/transfer moves funds between accounts of the same organization.

Not to be confused with an organization, which is the business entity that owns accounts, cardholders and cards. One organization holds many accounts.

See Quickstart (V2) and API versions.

Card-creation fee

What issuing a card costs you, where a fee is agreed for the card product. It is charged once, at creation, against your prepaid balance — on top of the amount you load — less any discount on your account. A flat fee, or a fee with a floor, applies even when you issue the card unfunded. Topping a card up afterwards costs only the amount you move.

API surface: no field of its own. It is why POST /v1/api-gateway/card/{card_product_id} and POST /v1/api-gateway/card/{card_id}/add-balance can return 400 INSUFFICIENT_BALANCE when your prepaid balance covers amount but not amount plus the fee.

See Issuing your first card.

Card product

The template a card is issued from. It fixes the form factor, the currency, whether the card can be reloaded, and the minimum and maximum amounts it can hold. The list contains only the products enabled for your organization.

Card products are shared by V1 and V2, and both versions list them from the V1 route.

See Issuing your first card.

Cardholder

The person you issue a card to. In V1 a cardholder is created for you the first time you issue a card for a new external_id; in V2 you create one explicitly before issuing. The same record is visible from both versions.

API surface: V1 external_id in request bodies and /v1/api-gateway/cardholder/…; V2 POST /cardholders, GET /cardholders/{id}, and cardholder_id on POST /cards. The V2 cardholder's external_id holds the same value V1 calls external_id.

Not to be confused with end customer — the same person, named from your side rather than Moon's. This documentation says "cardholder" for the person and reserves "end customer" for describing the external_id field and the PATCH /v1/api-gateway/end-customer/{id} route.

See Quickstart (V2) and Data formats and ids.

Cardholder session token

A token that lets one of your cardholders read and act on their own cards from your app, without your API key reaching the client. You obtain it for them through cardholder login and send it as a bearer credential in the Authorization header. It is scoped to that one cardholder's cards.

API surface: POST /v2/api-gateway/cardholders/auth/login. Every other endpoint answers it with 403 FORBIDDEN.

Not to be confused with your API key, which authenticates your own server and carries your organization's full authority.

See Authentication.

Child organization

An organization nested under yours — one per customer, brand or region, when you want their accounts, cardholders and cards kept apart. Every account, cardholder and card belongs to exactly one organization.

API surface: POST /organizations with parent_organization_id; GET /organizations/{id}/children; GET /organizations/main for your top-level organization. V2 only.

See Quickstart (V2).

End customer

Your own name for the person who holds the card. It exists in the API as the identifier you choose, not as a resource: you send it and Moon stores it against the cardholder.

API surface: external_id on the V1 create-card body and as a list filter on GET /v1/api-gateway/card and GET /v2/api-gateway/cards; external_id on the V2 cardholder; PATCH /v1/api-gateway/end-customer/{id}.

Not to be confused with cardholder — see that entry. They are the same person; "end customer" names your identifier for them.

See Data formats and ids.

The six-digit code emailed to a cardholder when they sign in. It is valid for ten minutes, and five wrong codes for the same login return 429 TOO_MANY_ATTEMPTS — request a new one to reset the count.

API surface: POST /v2/api-gateway/cardholders/auth/login, sent as code on step 2.

Not to be confused with the one-time code used to activate a card. Different flow, different lifetime, different attempt limit.

See Authentication and Rate limits.

Prepaid balance

Your organization's balance on Moon: the money you have added but not yet allocated to a card.

API surface: read it with GET /v1/api-gateway/moon-reserve or GET /v2/api-gateway/moon-reserve, which return { "balance": <number> } — 0 before your first funding. The MOON_CREDIT_FUNDS_CREDITED webhook fires when funds land, and MOON_CREDIT_PURCHASE is the matching transaction type. 400 USER_BALANCE_NOT_FOUND means no prepaid balance exists yet; 400 INSUFFICIENT_BALANCE means it does not cover the request.

Not to be confused with a card balance, which is money already moved onto a single card, or a V2 account balance.

See Adding a balance.

One-time code

The six-digit code a cardholder enters to activate a card, valid for ten minutes and limited to three attempts per session. The three routes that issue and check it take no API key, so a cardholder can complete activation from your app.

API surface: GET /v1/public/2fa/session/id, POST /v1/public/2fa/card/activate/otp, POST /v1/public/2fa/card/activate. V1 only.

Not to be confused with a login code — see that entry.

See Errors and Rate limits.

Organization

The business entity everything else belongs to: your API key authenticates as one, and accounts, cardholders and cards each belong to exactly one. V2 exposes organizations as a resource you can read, update and nest; V1 works within your single organization implicitly.

API surface: GET /v2/api-gateway/organizations, GET /v2/api-gateway/organizations/main, POST /v2/api-gateway/organizations; business verification through /organizations/{id}/kyb and /organizations/{id}/check.

Not to be confused with an account — see that entry.

See Quickstart (V2).

Production

The live environment, at https://api.themooncard.com. Real cards, real money, real settlement. Simulation routes are refused here with 403 DEV_ONLY_ENDPOINT.

See Environments.

Sandbox

It runs the same request and response shapes as production and holds separate data, separate keys and separate balances. Balances there are still real: you fund Sandbox prepaid balance and load a card before a simulated purchase will approve.

Not to be confused with a simulation, which is something you do in Sandbox rather than the environment itself.

See Environments.

Signing secret

The secret Moon signs webhook deliveries with, so your endpoint can prove a request came from Moon. It is returned when you register a webhook and when you rotate it. Rotation takes effect immediately, with no grace period.

API surface: signing_secret on the webhook responses; POST /v1/api-gateway/webhook/signing-secret/rotate and POST /v2/api-gateway/webhooks/signing-secret/rotate. Deliveries carry the Moon-Signature header.

See Webhooks and Verifying webhook signatures.

Simulation

A simulated event runs through the same processing path as a real one: it moves the same balances, applies the same fees and controls, appears in the transaction feed, and delivers the same webhooks. Sandbox only.

See Simulating card transactions.

Velocity control

A rolling spend limit attached to one card or to one cardholder, plus the amount used so far in the current window. A control is a monthly spend limit: type: "SPEND" with velocity_window: "MONTH".

API surface: POST /controls/velocity, GET /controls/velocity, GET/PATCH/DELETE /controls/velocity/{id}, and the status routes under /controls/velocity/…/status. Same paths in V1 and V2. The response keys velocityControls and velocityControlId are camelCase.

Not to be confused with the per-card spend limit on a Moon X card, which is a property of the card raised by loading it, not a control you create.