Currency API Concepts
Understand alternative currencies on the mCards platform — payment vs non-payment currencies, balance models, and how currencies participate in transaction processing.
Currency API Concepts
The Currency API enables partners to create and manage alternative currencies — loyalty points, rewards, or other value systems — associated with mCards cardholders. Currencies can optionally participate in transaction authorization as payment sources.
Currency Types
Currencies on the mCards platform fall into two categories:
Payment Currencies
Payment currencies can be used to fund card transactions. During authorization, the Dynamic Processing Engine (DPE) evaluates the currency balance and may approve transactions based on available funds.
Key characteristics:
- Balances are evaluated during transaction authorization
- mCards checks balance sufficiency directly — no real-time webhook to the currency provider
- The currency provider does not participate in real-time authorization decisioning
- Authorization decisions are made entirely by mCards
Non-Payment Currencies
Non-payment currencies exist for tracking and display purposes but do not directly fund transactions.
Key characteristics:
- Balances are not evaluated during transaction processing
- Used for loyalty tracking, rewards programs, or informational display
- Must be converted to mCash before they can be used for payment
Balance Model
Each currency maintains balances with the following components:
| Balance | Description |
|---|---|
| Available balance | Value that can be used immediately (e.g., vested points, available funds) |
| Held balance | Value temporarily unavailable (e.g., pending authorization holds, unvested points) |
This model applies to both payment and non-payment currencies.
Worked Example: Loyalty Points Balance
Consider a loyalty currency where 1 point = $0.01 USD:
| Event | Available | Held | Notes |
|---|---|---|---|
| Cardholder earns 10,000 points | 10,000 | 0 | Points credited via Currency API |
| Cardholder taps card for a $25 purchase | 7,500 | 2,500 | Authorization hold placed (2,500 points = $25) |
| A second $15 purchase is authorized | 6,000 | 4,000 | Another hold placed (1,500 points) |
| First purchase clears | 6,000 | 1,500 | Hold converted to settled debit; available unchanged |
| Second purchase is reversed | 7,500 | 0 | Hold released; points returned to available |
| Cardholder earns 500 more points | 8,000 | 0 | New points added to available balance |
Key takeaway: The available balance is what the DPE checks during authorization. If a cardholder attempts a $100 purchase but only has 6,000 points ($60) available, the currency account cannot fund the full transaction — the DPE moves to the next payment account in rank order.
Balance System of Record
Each currency is configured with a system of record that determines how balances are maintained:
Partner as System of Record
- The partner maintains the authoritative balance
- The partner updates balances using the Currency API
- mCards relies on the partner-provided balance for evaluation
- Required for payment currencies; also available for non-payment currencies
mCards as System of Record
- mCards maintains the authoritative balance
- The partner submits incremental updates (earn, burn, adjust)
- mCards calculates current, available, and held balances
- Supported only for non-payment currencies
Currency Decisioning and the DPE
Payment Currency Evaluation
During transaction authorization:
- mCards receives an authorization request from the card network
- The DPE evaluates payment accounts in rank order
- When a payment currency account is evaluated:
- mCards checks the available balance
- No webhook is sent to the currency provider
- If the balance is sufficient, the transaction is approved
- If insufficient, the DPE moves to the next payment account
Comparison: Payment Currencies vs Payment Gateways
| Payment Currencies | Payment Gateways | |
|---|---|---|
| Decisioning | Balance-based, evaluated by mCards | Gateway-based, decided by partner via webhook |
| Real-time participation | No — mCards evaluates balance directly | Yes — partner receives authorization webhook |
| Provider involvement | Provides balance data only | Actively approves or declines transactions |
Both models coexist within the DPE and are evaluated in rank order.
Operations Accounts
Currency providers are associated with operations accounts on the mCards platform, used for settlement, funds movement, and financial integrity tracking.
Related Guides
- Platform Integration Concepts — Transaction processing and the DPE
- Payments API Concepts — Gateway-based payment accounts
- Webhooks API Concepts — Transaction events for earning non-payment currencies
- API Authentication and Credentials — Authenticating API requests
- Currency API Reference — Full endpoint documentation
Updated 2 days ago