Currency API Concepts

This model applies to both payment and non-payment currencies.

Available Balance

The available balance represents the portion of the balance that can be used immediately.

Examples:

Earned points that have fully vested
Funds available for payment

Held Balance

The held balance represents value that is temporarily unavailable.

Examples:

Pending points subject to a return window
Amounts held for authorized but not yet completed transactions

Held balances ensure accurate accounting during transaction lifecycles.

Balance System of Record

Each currency operates with a defined balance system of record, which determines how balances are updated.

Partner as Balance System of Record

In this mode:

The partner maintains the authoritative balance
The partner updates balances using the Currency API
mCards relies on the partner-provided balance for evaluation

This mode is required for payment currencies and may also be used for non-payment currencies.

mCards as Balance System of Record

In this mode:

mCards maintains the authoritative balance
The partner submits incremental updates
mCards calculates current, available, and held balances

This mode is supported only for non-payment currencies.

Currency Decisioning and the DPE

Currency behavior during transaction processing depends on the currency type.

Non-Payment Currency Decisioning

Non-payment currencies do not participate in authorization
Balances are ignored during transaction processing
Conversion to mCash is required before payment

Payment Currency Decisioning

For payment currencies:

mCards receives an authorization request from the card network
The DPE evaluates available 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

In this model, mCards is fully responsible for authorization decisions.

Payment Currencies vs Payments API

It is important to distinguish between payment currencies and payment gateway accounts.

Payment Currencies

Balance-based decisioning
No real-time partner authorization
mCards evaluates balance sufficiency

Payments API Accounts

Gateway-based decisioning
Real-time authorization via webhooks
Partner actively approves or declines transactions

Both models coexist and are coordinated by the DPE.

Currency Providers and Operations Accounts

Currency providers are associated with operations accounts on the mCards platform.

Operations accounts are used to:

Support settlement and funds movement
Associate currency activity with the provider
Maintain platform-level financial integrity

Operations accounts are managed by mCards and exposed through API endpoints for visibility.

Environments and Testing

Currency integrations must be developed and tested in the sandbox environment.

In sandbox:

No real-world transactions occur
Balance updates can be tested safely
Transaction simulation can be used to validate payment currency behavior

Certification is required before promotion to production.

Related Guides

Platform Concepts
Transaction processing and the Dynamic Processing Engine.
Payments API Concepts
Gateway-based payment accounts and authorization.
Webhooks API Concepts
Transaction events used for earning non-payment currencies.
API Authentication & Credentials
Authenticating Currency API requests.

Next step

With all API Integration Concepts complete, you can now review and refine the full conceptual flow or proceed to updating API reference documentation where needed.