Glossary

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, 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. 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 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: 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: 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 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 for the full event catalogue, payload shapes, retry policy, and security model.