spending_asset: USD, USDT, USDC, BTC, GOLD, SILVER or PLATINUM, USD by default). USD, USDT and USDC are
1:1 with the dollar; BTC and GOLD convert at the price of the moment of each
event. Every purchase is authorized in real time against that asset’s
available balance and the card’s own limits, and the debit shows up
immediately in the movement history.
How many cards you can hold
spending_asset, USD by default). Fine-grained control is
per-card spending limits (per transaction, daily, monthly), always measured
in USD, which you can change at any time.
Choosing the spending balance (USD, USDT, USDC, BTC, GOLD, SILVER or PLATINUM)
Setspending_asset when creating the card or change it later with PATCH.
It only affects future purchases: in-flight authorizations keep the asset
they were debited in (and their reversal returns that same asset).
GET /v1/rates, settlement block):
- Authorization: the purchase’s equivalent in your asset is reserved
plus a small cushion (not a charge: it covers price drift until
clearing and is returned at capture). If the execution price is not
available at that moment, the purchase is declined
(
pricing_unavailable) — your balance is never converted with an untrustworthy price. - Settlement (capture): the final amount is re-converted at the price of the capture moment; the cushion’s excess returns to your balance (or the difference is debited if the price moved beyond the cushion).
- Reversal of an authorization: the EXACT reserved amount is returned, with no conversion.
- Refunds and adjustments after capture: re-converted at the price of the moment of the event. The price may move between the purchase and the refund — you receive the equivalent in your asset at that moment’s price, not the original quantity.
- BTC/GOLD/SILVER/PLATINUM purchases share your account’s volatile-asset limits (per
operation and 24h volume, visible in
GET /v1/settlement).
insufficient_funds — there is no automatic fallback to another balance.Costs (configured by your operator, can be 0)
GET /v1/rates (fees field). Every issuance charge is
automatically refunded if issuance fails.
Per-purchase fee (lifecycle)
The per-transaction fee follows the same lifecycle as the purchase:- Authorization: the estimated fee is reserved inside the hold
together with the purchase amount, in the card’s
spending_asset(the percent applies over the purchase’s USD amount; in BTC/GOLD/SILVER/PLATINUM it converts with the same event price). - Settlement: the fee is recalculated with the configuration in
force at that moment and the definitive one is charged (
card_feein your movements); the difference against the estimate is released or charged together with the cushion adjustment. - Reversals and downward adjustments: the fee is prorated back to
the refunded fraction of the purchase (
card_fee_refund).
Create a card
The flow depends on whether your account is a person or a company — pick your tab. The common rule: the cardholder is verified ONCE per account, on the first issuance; subsequent cards reuse it with no data. Theidempotency_key is always required (a retry with the same key returns
the original card and never double-charges).
Wizard decision tree
The portal should call the summary before opening the issuance form. It useshas_holder to choose the shortest safe path; this is a boolean only and never
exposes the internal holder identifier:
- Person account: if
has_holderisfalse, show the approved KYC data plus issuer fields (occupation,place_of_work,salary_usdand email). If it istrue, skip holder creation and ask only for card settings. A person account can have one live digital card and one open application; a second request returns409 card_limit_reached. - Company account: let the user choose company holder or
designated person. The company path uses the account’s KYB data. The
designated-person path must show a picker containing only approved KYC
verifications, then collect issuer fields and an explicit
pepboolean. - Card settings: show digital-only issuance (
physical: false), choose the spending asset, and optionally set USD limits. Recommend the account’ssettlement_asset; expose the other enabled assets as advanced choices. - Submit once: send the same
idempotency_keyin the body orIdempotency-Keyheader. If the network result is ambiguous, query the same request/status with that key; do not create a new key.
verification_id; never accept an arbitrary person ID.
Creation request and responses
This is a complete digital request with limits and an explicit spending asset:201:
202 and no card exists yet:
txn_review_status_changed webhook or
GET /v1/me/txn-reviews. The issuance fee is charged when the application is
held and automatically refunded if compliance rejects it. A retry with the
same idempotency key returns the same application and never charges twice.
Use these stable errors to keep the wizard actionable:
Issuance holds and tracking
An application hold is not a completed card. While it isin_review, show the
review_id, keep the form read-only, and wait for the webhook or review
endpoint. Do not create another application to poll progress. Once approved,
the original idempotency key resolves to the created card; if rejected, the
issuance fee is refunded and the response includes the final review status.
This flow is auditable as card_application.
- Person account
- Company account
409 card_limit_reached and its newly charged application fee is refunded automatically; retrying the same request with the same idempotency key returns the existing 202 review instead of charging again.
Your first card creates and verifies your holder at the issuer. Since
your account already approved its
identity verification, your data and documents
auto-fill from your verification — you only add the issuer-specific
fields (occupation, salary_usd); any field you send explicitly wins
over the autofill:occupation is a catalog code
(see below) and
salary_usd is whole US dollars. If your verification was done through
the wizard without some data or document the issuer requires, add it
explicitly to the cardholder (first_name, email, address,
id_front_url…, same format as always).A second issuance request is not available for a person account once it
already has one live card or one open application. It returns
409 card_limit_reached:400 physical_temporarily_unavailable even when
the account has no card. Use a digital card request instead.Printed name
The card’s printed name is optional in the request. Sendcardholder.first_name and cardholder.last_name when the legal name from
the approved profile is longer than the issuer’s 22-byte printing limit or
when you need a shorter display name. If you omit either field, the approved
KYC/KYB profile supplies it during autofill. An explicit field always wins
over the profile value.
After trimming surrounding whitespace, the API counts the UTF-8 bytes of both
fields together. A total above 22 is rejected with
422 cardholder_name_too_long before the issuance hold or fee. This is a
byte limit, not a Unicode-character limit.
cardholder_name:
Issuer fields and AML/CFT-derived PEP
The first issuance creates the issuer-side cardholder. The platform validates the issuer fields before charging the issuance fee or creating a hold. When an existing account holder is reused, these fields are not requested again.pep: true does not bypass 422 screening_required; once screening
exists, the value sent to the issuer is the conservative OR of the request
boolean and the screening result, so a request false never overrides a
screening true. The checklist displays the result as
Politically exposed person (screening).
Company contact and legal-representative fields are completed from KYB UBO
data when the request does not provide them. Company document URLs are
completed from the KYB file using these fallbacks:
business_license_url has no fallback. If the assembled holder is still
missing required issuer data, the API returns HTTP 422 with the missing
keys and no issuer call is made:
Catalogs
Use the live catalogs rather than typing labels or inventing codes:{"items":[{"code":"...","label":"..."}],"meta":{"retrieved":"..."}}.
Send items[].code in occupation or kind_of_business; a label such as
"Engineer" is not accepted as a code. The same code validation is used by
the firewall checklist, so a value can be present and still be marked
ok: false when it is not in the catalog.
What if the account has no AML/CFT screening yet?
What if the account has no AML/CFT screening yet?
What happens to a designated person's PEP value?
What happens to a designated person's PEP value?
cardholder.pep. It has no default.Availability and issuance errors
Occupation and business activity (catalog codes)
When designating a person,occupation must be a code from the
official catalog (not free text); for a company, so must
kind_of_business. Look them up (searchable with ?q=):
{ "code": "...", "label": "..." }. Use the code in
occupation / kind_of_business. An out-of-catalog value returns
400 invalid_occupation or 400 invalid_kind_of_business before reaching
the issuer. salary_usd is in dollars (integer).
Physical cards: activation
A physical card is bornpending_activation and travels inactive for
security. Once the holder has it in hand:
Reveal PAN and CVV (sensitive data)
Only the owning account can reveal them (never the org admin). The response is one-shot: display it to the holder and discard it.Limits and freeze/unfreeze
"0" removes a limit. To freeze (declines every purchase instantly):
Transactions and their lifecycle
spend_asset / spend_amount show which balance the purchase actually
debited and how much in that asset (amount_usd / amount_usdt remain the
USD reference value). For BTC/GOLD/SILVER/PLATINUM, an authorized transaction’s
spend_amount includes the reserve cushion; after settlement it shows the
final amount.
fee_asset / fee_amount are the asset and amount of the per-purchase fee
(definitive once settled; estimated while authorized).
fee_refunded_amount appears once a refund applies from reversals or
downward adjustments. When your operator does not configure a per-purchase
fee, the fee_* fields are not included in the transaction — the
historical behavior is unchanged.
Cancel a card
Irreversible. Billscard_cancellation when configured.
Replacing a card
There is no separate blind re-issue operation in the portal API. To replace a card, freeze it first if compromise is suspected, then cancel it and submit a new digital application with a new idempotency key. A company can issue another card immediately. A person account must have no live card or open application, so cancellation is required before the replacement request. Never reuse an old key for a genuinely new card.Webhooks
FAQ
Do I have to prefund the cards?
Do I have to prefund the cards?
What if several of my company's cards purchase at the same time?
What if several of my company's cards purchase at the same time?
In which currency are purchases debited?
In which currency are purchases debited?
spending_asset). USD, USDT and USDC are 1:1 with the dollar, with no
conversion fee; BTC and GOLD convert at the effective price of the moment
of each event (the same one in the settlement block of GET /v1/rates).Can different cards spend from different balances?
Can different cards spend from different balances?
spending_asset is per card. A company can have, for example,
corporate cards spending USDT, employee cards spending USDC and a personal
one spending BTC. Changing it with PATCH only applies to future
purchases.What is the cushion I see reserved on BTC/GOLD/SILVER/PLATINUM purchases?
What is the cushion I see reserved on BTC/GOLD/SILVER/PLATINUM purchases?
A BTC purchase of mine was refunded — why did I receive a different quantity?
A BTC purchase of mine was refunded — why did I receive a different quantity?
What happens if there is no balance for the monthly fee?
What happens if there is no balance for the monthly fee?
card_status_changed event with
reason: monthly_fee_unpaid). No debt accrues; once the balance is topped
up, unfreeze it with PATCH { "frozen": false }.Can I issue a card for someone outside my company?
Can I issue a card for someone outside my company?
verification_id in the cardholder and their data and documents
auto-fill. The card always spends from the balance of the issuing company
account.Why does the wizard ask for my occupation or the company's business activity?
Why does the wizard ask for my occupation or the company's business activity?
occupation for a person or
kind_of_business for a company. The issuer uses it to create the cardholder
and apply its compliance checks.What happens if I top up while issuance is in progress?
What happens if I top up while issuance is in progress?
Card listings, summaries, and organization feeds
GET /v1/cards is available to both an account credential (its own cards)
and an organization administrator (ops:read). Organization admins may
add account_id to narrow the result. A bank-partner credential cannot use
the /v1/cards surface; the cards section is hidden for that role.
The list accepts page (default 1) and page_size (default 50, maximum
200), plus these filters:
total and, on enriched reads, optional
account_display_name, account_email, last_txn_at, and billed_through:
GET /v1/cards/summary?account_id=... returns
aggregate fields (total, by_status, new_30d, spend_*_usdt, declined_24h).
has_holder tells the portal whether the account already has an issuer cardholder:
scoped to the requested account, best-effort, no holder ID or personal data. Use it
only to branch the wizard; the create endpoint remains the source of truth.
GET /v1/cards/transactions is the organization-wide transaction feed (card_id,
account_id, status, merchant, mcc, from, to, page, page_size;
malformed card_id returns 400 invalid_filter). Items add account and optional
cardholder context.
GET /v1/cards/{card_id} enriches the card with spent_daily and spent_monthly
(same UTC windows and authorized/settled states as JIT enforcement; declined and
reversed transactions excluded).
Can an account see another account's cards?
Can an account see another account's cards?
ops:read (scope with account_id).Does the summary expose customer information?
Does the summary expose customer information?
What happens with an invalid filter or date?
What happens with an invalid filter or date?
400 invalid_filter (bad physical/spending_asset/card_id) or 400 invalid_range (bad from/to); filters are never silently ignored.USD as the principal ledger asset
Accounts useUSD as the default for settlement_asset and
payin_settlement_asset; change it any time with PUT /v1/settlement.
In-flight operations are never re-quoted.
USD ledger amounts use cents (two decimal places). Direct credits and debits,
fees, and supported payout, checkout, POS, and card paths use USD only where
their asset field accepts it. Swaps between USD and USDT use 1:1 pricing and
do not use an FX oracle. BOB, MXN, and ARS remain separate fiat-ledger
assets; v1 money-out pricing for those assets remains unavailable.
A payin credited directly to a USD-principal account exposes
credit_asset: USD and the credited fiat amount in cents; usdt_credited
remains the USD-equivalent reporting field. A controversy hold follows the
credited asset: USD credits use hold_asset: USD. disputed and held use hold-asset units;
disputed_usdt and held_usdt are normalized equivalents.