mintfax uses a prepaid credit system. You purchase credit packages, credits are consumed per page when faxes are delivered, and the money lives in pools at the account level - not per environment.
Account-pool model
Every account has exactly two credit balance rows:
| Pool | What it holds | Funding |
|---|
live | Real credits, real money | Stripe charges to the card on file |
sandbox | Simulation credits | Seeded from a CreditPackage at registration |
balance_type field returned on wallet objects. There is no third pool, and no per-environment pool.
Environments share their type’s pool
If your account has five sandbox environments, they all draw from the same sandbox pool. The same is true for live. A credit purchase made in any live environment funds the entire account’s live activity. Likewise, a fax sent from any live environment deducts from that one shared live pool.
This is intentional: credits are a billing concern, and billing happens at the account. Environments are an organizational and isolation concern, not a wallet boundary.
A environment is a sandbox environment or a live environment for its entire life - it never crosses the wall. So each environment touches exactly one pool. There is no need to choose which pool a fax draws from; the environment type determines it.
Hold, capture, release
When you submit a fax, credits move through a three-step lifecycle against the relevant pool:
- Hold - a credit hold is placed immediately on submission, reserving the estimated cost based on page count. The held amount is deducted from
available and added to held.
- Capture - when the fax is delivered successfully, the hold is captured as a permanent charge. The held amount is removed from
held.
- Release - if delivery permanently fails, the hold is released back to
available. You are never charged for failed deliveries.
Submit fax -> available decreases, held increases
Delivery succeeds -> held decreases (captured as charge)
Delivery fails -> held decreases, available increases (released)
available and held numbers because the money is shared.
Reading balances
mintfax exposes two balance endpoints with deliberately different shapes.
GET /account/balance (account key)
Returns both balances as an array. Use this with an mfx_acct_... key when you want a complete view of the account’s money.
curl https://api.mintfax.com/v1/account/balance \
-H "Authorization: Bearer mfx_acct_qpr456stv789..."
{
"data": [
{
"type": "live",
"available": 9550,
"held": 0,
"auto_top_up": {
"enabled": true,
"threshold_pct": 20,
"package_id": 3
}
},
{
"type": "sandbox",
"available": 4550,
"held": 450,
"auto_top_up": {
"enabled": false,
"threshold_pct": 20,
"package_id": null
}
}
]
}
GET /environment/balance (environment key)
Returns the single balance for the caller’s type. Use this with mfx_test_... (sandbox) or mfx_live_... (live) when you only need the slice your environment operates against.
curl https://api.mintfax.com/v1/environment/balance \
-H "Authorization: Bearer mfx_test_abc123def456..."
{
"type": "sandbox",
"available": 4550,
"held": 450,
"auto_top_up": {
"enabled": false,
"threshold_pct": 20,
"package_id": null
}
}
| Field | Description |
|---|
type | live or sandbox - which pool this balance row belongs to |
available | Credits available for new faxes, in cents. Holds are already deducted. |
held | Credits reserved for in-flight faxes, in cents. |
auto_top_up | Per-pool auto-top-up configuration (see below) |
held value of 0 means no faxes are in flight on this pool. A non-zero held means one or more faxes are queued or transmitting; the reserved credits will be captured or released once each fax reaches a terminal state.
Reading transactions
The two transaction endpoints have a deliberate asymmetry.
GET /account/transactions (account key)
Returns the pool-wide ledger across all environments of the relevant type(s). Optionally filter with ?type=live or ?type=sandbox.
curl 'https://api.mintfax.com/v1/account/transactions?type=live' \
-H "Authorization: Bearer mfx_acct_qpr456stv789..."
GET /environment/transactions (environment key)
Returns transactions filtered to the caller’s environment only.
curl https://api.mintfax.com/v1/environment/transactions \
-H "Authorization: Bearer mfx_test_abc123def456..."
mfx_test_... key, and that key’s /environment/transactions call returns only that sibling’s activity.
The deliberate asymmetry
Balance numbers and transaction lists answer different questions.
- The balance is the same pool number across sibling environments because the pool really is shared. Two sandbox environments under one account see the same
available and held from /environment/balance. That is correct: it is one wallet.
- The transaction list from an environment key is filtered to that environment. Two sandbox environments under one account, each calling
/environment/transactions, see only their own faxes and seed events.
Why filter transactions but share the balance number? Because the balance is a single fact about the account. Transactions describe activity, and you typically do not want one environment’s API key to peek at a sibling environment’s activity log. If you want the full pool ledger, that is what /account/transactions is for - and it requires the account key.
Example:
Account: Acme Corp
Live pool: 9550 credits available
Sandbox pool: 4550 credits available
Environment A (sandbox, mfx_test_aaa...)
/environment/balance -> { type: "sandbox", available: 4550, held: 450 }
/environment/transactions -> [tx from Environment A only]
Environment B (sandbox, mfx_test_bbb...)
/environment/balance -> { type: "sandbox", available: 4550, held: 450 }
/environment/transactions -> [tx from Environment B only]
Account key (mfx_acct_...)
/account/balance -> both pools
/account/transactions -> tx from A and B (and any other live environments)
Auto-top-up
Auto-top-up is configured per balance row (per pool). When available falls below the configured threshold, mintfax tops up:
- Live pool: charges the card on file via Stripe for the configured
CreditPackage and adds those credits.
- Sandbox pool: adds simulated credits, no charge.
Configure auto-top-up from the dashboard for each pool independently. The current setting is reflected in the auto_top_up block on every balance response.
Sandbox seed
On registration, the sandbox pool is seeded automatically from a designated CreditPackage so you can send sandbox faxes immediately. The seed shows up in the ledger as a seed-type transaction. You can exhaust it deliberately to test insufficient_balance handling, or reset it from the dashboard.
See Sandbox - Sandbox balance for the details.
Insufficient balance
If available on the relevant pool is too low to cover the estimated cost of a fax, the API returns HTTP 402 with insufficient_balance:
{
"error": "insufficient_balance",
"message": "Insufficient balance to submit fax",
"action": "top_up_balance",
"docs": "https://mintfax.com/docs/errors/insufficient-balance"
}
Activation gate
Live operational endpoints require the account to be activated. Until the first successful live credit purchase, calls with an mfx_live_... key on POST /faxes, GET /environment/*, and similar return HTTP 403 with account_not_activated. Sandbox is never gated on activation.
See Activation for the buy-as-activation flow.
Per-page pricing
Credits are deducted per page transmitted. A 3-page fax costs 3x the per-page rate. The per-page rate depends on the destination country and your pricing tier.
Related pages
- Keys - which key kind to use for
/account/* vs /environment/*
- Environments - sandbox vs live environments
- Activation - what unlocks live operations
- Errors -
insufficient_balance, account_not_activated, and friends
