> ## Documentation Index > Fetch the complete documentation index at: https://developer.cartevo.co/llms.txt > Use this file to discover all available pages before exploring further. # Glossary > Definitions of the core concepts used across the Cartevo API — wallet, customer, card, transaction, debt, modes, and identifiers. A single reference for the vocabulary used across this documentation. Each entry is intentionally short — for full behavioral details, follow the cross-references. *** ## Wallet A **wallet** holds a balance in a single currency for a single country. A company can have multiple wallets (e.g. one XAF wallet for Cameroon, one XOF wallet for Côte d'Ivoire, one USD wallet for cards). Each wallet maintains two sub-balances: * **Pay-in balance** (`payin_balance`) — funds collected from end users via mobile money or other inbound rails. * **Pay-out balance** (`payout_balance`) — funds available to send to end users via payout rails. You can move funds between the two sub-balances via the wallet internal-transfer endpoints. The USD wallet is special: it is the source-of-funds for card issuance, card funding, and the destination for refunds when a card is terminated. See [POST /wallets](/api-reference/endpoint/post-wallets), [GET /wallets](/api-reference/endpoint/get-wallets). *** ## Customer A **customer** is the end user to whom you issue cards. Cartevo is a B2B2C platform: your *company* signs up with Cartevo, and you in turn create *customers* under your company. Every customer must complete KYC (Know Your Customer) before any card can be issued in their name. You can either: * Upload KYC documents directly (`POST /customers` with `multipart/form-data`), or * Provide hosted document URLs (`POST /customers/enroll`). A customer's KYC status is one of `PENDING`, `APPROVED`, `REJECTED`. Cards can only be issued to `APPROVED` customers. *** ## Cardholder In the underlying card-issuing platforms, a **cardholder** is the entity to which a card is issued. From the Cartevo API's perspective, every customer who has been successfully enrolled is automatically registered as a cardholder. You do not interact with cardholders directly — the customer abstraction is sufficient. *** ## Card A **card** is a virtual payment instrument issued to a customer. | Attribute | Value | | --------------- | ----------------------------------------- | | Type | Virtual only (physical cards coming soon) | | Currency | USD only | | Brand | `VISA` or `MASTERCARD` | | Maximum balance | 10,000 USD per card | | Validity | 3 years (auto-renewing) | **Card statuses:** * **`PENDING`** — issuance in progress. * **`ACTIVE`** — usable for transactions, funding, and withdrawals. * **`FROZEN`** — temporarily disabled by you. Balance preserved; can be unfrozen. * **`SUSPENDED`** — temporarily disabled by Cartevo (typically after multiple failed transactions). * **`TERMINATED`** — permanently disabled. Balance refunded to the company USD wallet. **Irreversible.** * **`FAILED`** — issuance failed. See the [Cards Overview](/api-reference/endpoint/Virtual-Card-Overview) for the full card lifecycle and the PCI DSS data-masking model. *** ## Transaction A **transaction** records any movement of money in the Cartevo system. Transactions have a `category` (the system that generated them) and a `type` (what they represent). **Categories:** `WALLET`, `CARD`, `PAYMENT`. **Card transaction types:** | Type | Meaning | | --------------- | ---------------------------------------------------------------- | | `AUTHORIZATION` | Card was used at a merchant; funds reserved | | `SETTLEMENT` | Authorized transaction cleared and funds moved | | `FUNDING` | Card was funded from a wallet | | `WITHDRAWAL` | Funds withdrawn from a card back to a wallet | | `TERMINATION` | Card terminated; balance refunded | | `DECLINE` | Card-use attempt rejected (e.g. insufficient balance) | | `REVERSAL` | Authorization reversed (typically within 24h, before settlement) | | `REFUND` | Funds returned after settlement | | `CROSS-BORDER` | A cross-border charge applied to a card transaction | **Transaction statuses:** `PENDING`, `PROCESSING`, `SUCCESS`, `FAILED`. *** ## Authorization vs. settlement When a card is used at a merchant: 1. **Authorization** — the merchant asks Cartevo to reserve funds. If the card has the balance and is `ACTIVE`, Cartevo holds the amount and emits `transaction.authorization.created`. 2. **Settlement** — usually 1–3 days later, the merchant claims the reserved funds. Cartevo emits `transaction.settlement.completed` and the funds leave the card. Between these two steps the merchant can cancel the authorization (→ `transaction.reversal.completed`) or partially settle (less common, partial reversals possible). After settlement, only a refund (→ `transaction.refund.completed`) can return the funds. *** ## Cross-border charge A **cross-border charge** is a fee Cartevo applies whenever a card is used: * on a merchant outside the United States, **or** * in a currency other than USD. **Formula:** `(transaction amount × 2.5%) + $0.50 USD`. The fee is deducted from the card balance first; if insufficient, from the company USD wallet; if still insufficient, recorded as a debt. The fee is reported via the `fee.crossborder.charged` webhook. *** ## Debt A **debt** is created when Cartevo cannot collect a fee owed at the time of the underlying event. Two scenarios trigger debt creation: 1. **Payment failure fee** — `$0.50` charged when a card transaction fails for certain reasons, and neither the card nor the wallet has the balance to cover it. 2. **Cross-border fee** — see above; if neither card nor wallet has the balance to cover the cross-border fee, the remainder becomes debt. When a debt is created, Cartevo emits the `debt.recovery.pending` webhook. Outstanding debts are recovered automatically via scheduled debit attempts against the company wallet. *** ## External ID vs. transaction ID vs. provider reference Three distinct identifiers can attach to a single payment: | ID | Generated by | Visible in | Purpose | | ------------------ | ------------------------------------------------- | ------------------------------------------ | ------------------------------------------------- | | `external_id` | You | Request body, response, webhook payload | Idempotency key — prevents duplicate processing | | `transaction_id` | Cartevo | Response, webhook payload, status endpoint | The canonical reference for any further API calls | | Provider reference | Upstream operator (MTN, Orange, AlphaSpace, etc.) | Webhook payload `provider_reference` field | Reconciliation with operator records | When you call Cartevo, always use the `transaction_id`. When you talk to an operator's support team about a specific payment, you may need the provider reference. *** ## Mode A **mode** is one of two isolated environments: * **Preproduction** — sandbox. Wallet balances capped at 50,000 XAF (\~80 USD). No real money moves. Use to validate your integration end-to-end. * **Production** — real money, real customers, real KYC. Each set of API credentials (`client_id` + `client_key`) is bound to one mode. Tokens minted from preproduction credentials cannot operate on production data and vice versa. *** ## Operator An **operator** is a mobile-money provider that Cartevo integrates with for collection (pay-in) and payout. Examples: MTN, Orange, Moov, Wave, M-Pesa, Airtel Money. The set of supported operators differs by country and by direction (some operators are pay-in only). See [Payment guidelines](/api-reference/endpoint/payment_guide_lines) for the per-country, per-currency operator matrix. *** ## Webhook A **webhook** is an HTTP `POST` request Cartevo sends to a URL you configure on your company account when a notable event occurs. Webhooks are how you learn about asynchronous outcomes (settlement, payout success, fee charges) without polling. See the [Webhooks reference](/api-reference/endpoint/webhook) for the full event catalogue, payload shapes, retry policy, and security model.