Cards - CryptoMate

This guide covers the full lifecycle of a virtual card: from issuance and funding, through per-card configuration and spending controls, to fraud protection and transaction visibility. All operations are available both via the API (API key auth) and the CryptoMate Portal.

Overview

Cards is a virtual prepaid card product powered by cryptocurrency collateral. Designed for businesses, it uses stablecoins on Polygon as the backing asset: each card is linked to a stablecoin wallet, and funds are automatically converted to dollars at a 1:1 ratio, making integration with conventional payment networks seamless.

Card specifications

Brand: Visa
Acceptance: Google Wallet and e-commerce platforms
Security: Protected by 3DS to mitigate fraud

Operational models

Top Up

Users load funds directly onto the card through a dedicated deposit wallet created exclusively for this purpose.

External authorization

Your systems integrate via webhooks: for each transaction you have 1,200 ms to authorize or reject it based on your own approval logic.

How it works

Each virtual card is a prepaid Visa card backed by stablecoin collateral. At the account level, a single holding wallet on the Polygon network holds all funds. When a purchase is made, the holding wallet balance is verified and the appropriate amount is debited.

Holding wallet (USDC, Polygon)
    └── Virtual Card A  ── purchase → authorization → settled
    └── Virtual Card B  ── purchase → authorization → settled
    └── Virtual Card C  ...

Cards are issued against a card pack. Each company has a maximum number of active cards based on their contracted product. You can check available capacity via Get contracted product.

Creating a card

Use Create virtual card to issue a new card. The two required decisions at creation time are:

Approval method

Value	How purchases are approved
`TOPUP`	The cardholder pre-loads funds onto the card’s individual deposit wallet. Purchases are auto-approved against that balance.
`WEBHOOK`	Each purchase triggers a real-time webhook to your endpoint. You have 1,200 ms to respond with `"00"` / `"SUCCESS"` to approve or `"05"` to decline. Timeout = decline.

The approval_method cannot be changed after card creation. If the wrong method is set, delete the card and reissue.

Spending limits

Set daily_limit, weekly_limit, and monthly_limit (in USD) at creation. These are enforced per card independently. You can update them at any time — see Spending limits below. Omitting a limit means no limit is applied for that time window.

Funding the account

All cards draw from a shared holding wallet. Before cards can transact you must fund this wallet with USDC on Polygon. Retrieve the holding wallet deposit address via Get holding balance. The minimum deposit is 10 USD.

A minimum balance is always locked in the holding wallet to preserve capacity for at least one transaction. Withdrawals that would breach this floor are rejected.

To return funds to your treasury, use Withdraw from holding. For cards using TOPUP approval, each card also has a personal deposit wallet. Fetch those addresses with Get card top-up wallets. Deposits sent to these wallets are attributed to that specific card and used to settle its purchases.

Fees wallet

The commissions charged on card activity — the fees applied to deposits and transactions — accumulate in a dedicated fees wallet on Polygon, separate from the holding wallet that funds card spending.

You can both view the balances and make withdrawals from the CryptoMate Portal (Cards → Summary → Accumulated fees), as well as through the API described below.

Pending vs. available balance

The fees wallet tracks two balances, visible in the Portal (Cards → Summary → Accumulated fees):

Balance	Meaning
Pending to credit	Fees already charged but not yet settled on-chain into the fees wallet. A virtual balance that becomes available progressively as fees are collected from card deposits and spending.
Available (on-chain)	Fees already settled on-chain in the fees wallet. Only this balance can be withdrawn.

Withdrawing fees

Use Withdraw fees to send accumulated fees to one of your wallets. Withdrawals draw only from the available on-chain balance and are made per token (token_symbol). The destination must be a whitelisted address enabled for at least 24 hours:

A newly whitelisted address cannot receive a fees withdrawal until 24 hours after it was added. This delay is a security measure against unauthorized address changes.

Manage the whitelist from the Portal (Cards → Configuration).
List the addresses currently eligible (enabled ≥ 24 h) with Get fees wallet whitelisted addresses.

Fees withdrawals are also available from the Portal (Cards → Summary → Accumulated fees → Withdraw fees). Each withdrawal is recorded in the transaction history as a CLIENT_FEES_WITHDRAW movement.

Managing cards

Spending limits

Update per-card daily, weekly, and monthly limits independently with Update card limits. Changes take effect immediately on the next authorization.

Freeze and unfreeze

Use Freeze or unfreeze card to temporarily block a card. A frozen card declines all purchase attempts until unfrozen. The card state moves between ACTIVE and FROZEN without losing its configuration. Useful for: temporary employee suspension, suspicious activity hold, cardholder request.

Unblocking after a velocity block

If a velocity rule triggers, the card is automatically moved to BLOCKED. Manually unblock it with Unblock card. Unblocking also resets the authorization counter so the card can transact immediately.

Reissuing a card

Reissue card generates a new card number and CVV while keeping the same cardholder configuration, limits, and approval method. Use this when a card number is compromised. The old card is deactivated.

Updating contact information

What	Endpoint
Email for notifications	Update email
Phone for OTP / 3DS SMS	Update phone
Card PIN	Update PIN

Rotating the deposit wallet

If a TOPUP card’s deposit wallet address needs to be rotated (e.g. for compliance or security), use Rotate deposit wallet. A new address is generated and associated with the card. The old address stops accepting deposits.

Deleting a card

Delete card permanently deactivates the card. Any remaining balance in the card’s individual wallet is returned to the holding wallet. This action is irreversible.

3DS authentication

3DS adds cardholder verification to e-commerce purchases. Two modes are available per card:

Mode	Behavior
`sms`	A one-time code is sent to the cardholder’s registered phone.
`webhook`	A webhook is sent to your endpoint with the OTP challenge. Your system delivers it via your own channel.

Configure the mode with Set 3DS configuration. When a 3DS challenge fires, a notification_3ds_authorization webhook is delivered to your endpoint. For webhook mode, use Respond to 3DS authorization to submit the OTP entered by the cardholder.

Fraud protection

Velocity rules

Velocity rules define rate limits at the account level, applied per individual card. They protect against card probing and rapid fraudulent use. Each rule specifies:

max_authorizations — the maximum number of approved authorizations allowed
time_window_seconds — the sliding window over which the count is measured

You can configure up to 5 rules. When any rule is breached, the transaction is declined and the card is automatically blocked. Unblocking the card also resets its authorization counter, ensuring the card can resume normal operation immediately. Manage rules with:

Get velocity rules
Replace velocity rules — replaces the entire ruleset atomically
Delete velocity rules — removes all rules

Example ruleset — no more than 3 purchases per minute, or 20 per hour:

{
  "rules": [
    { "max_authorizations": 3, "time_window_seconds": 60 },
    { "max_authorizations": 20, "time_window_seconds": 3600 }
  ]
}

When a velocity block fires, a card_blocked_by_velocity webhook is sent to your endpoint so your systems can react in real time (alert the cardholder, open a fraud investigation, etc.).

Risk score engine

The risk score engine evaluates every purchase in real time. It assigns a numeric score by combining up to six signals, each weighted independently. If the score reaches or exceeds a configurable threshold, the transaction is declined.

How the score is calculated

Each signal is binary (0 or 1). The final score is the weighted sum:

score = (signal_geo × w_geo)
      + (signal_mcc × w_mcc)
      + (signal_amount × w_amount)
      + (signal_time × w_time)
      + (signal_declines × w_declines)
      + (signal_country × w_country)

A transaction is rejected when score ≥ threshold.

Signals

Signal	ID	Fires (= 1) when…	Notes
Impossible travel	`geo_distance`	Card used in a different country less than 4 hours after the previous transaction	Compares merchant country of current vs. last approved transaction
Unfamiliar MCC	`mcc_profile`	Merchant category code was never seen in the card’s 90-day history	Requires ≥ 5 historical transactions to activate
Amount above baseline	`amount_baseline`	Purchase amount exceeds the 95th percentile of the card’s historical amounts	Requires ≥ 5 historical transactions to activate
Unusual hour	`time_window`	Transaction hour appears in less than 5% of the card’s historical transactions	Requires ≥ 5 historical transactions to activate
High decline rate	`decline_rate`	3 or more transactions were declined on this card in the last 24 hours	Detects rapid retry / card probing
Foreign merchant country	`merchant_country`	Merchant’s country differs from the cardholder’s country (set via `metadata.country` at card creation)	Signal is 0 if `metadata.country` is not set

Signals that require a minimum history return 0 (no contribution) until the card has enough approved transactions. A brand-new card is only evaluated by geo_distance, decline_rate, and merchant_country.

Configuration

The engine is configured at the account level from the Portal (Cards → Configuration → Risk Score). Each weight can be set to 0 to disable that signal entirely. Setting all weights to 0 disables the engine for the whole account.

Field	Description
`threshold`	Score at or above which a transaction is rejected. Range: `0.0` – any positive value.
`geo_distance_weight`	Weight for the impossible travel signal.
`mcc_profile_weight`	Weight for the unfamiliar MCC signal.
`amount_baseline_weight`	Weight for the above-P95 amount signal.
`time_window_weight`	Weight for the unusual hour signal.
`decline_rate_weight`	Weight for the high recent decline rate signal.
`merchant_country_weight`	Weight for the foreign merchant country signal.

Examples

Conservative setup — only block clear anomalies, high threshold:

{
  "threshold": 0.8,
  "geo_distance_weight": 0.5,
  "mcc_profile_weight": 0.2,
  "amount_baseline_weight": 0.2,
  "time_window_weight": 0.1,
  "decline_rate_weight": 0.4,
  "merchant_country_weight": 0.0
}

In this configuration a transaction is rejected only if, for example, both impossible travel (0.5) and high decline rate (0.4) fire simultaneously (score = 0.9 ≥ 0.8). A single signal is not enough to reach the threshold. Strict setup — any single anomaly blocks the transaction:

{
  "threshold": 0.3,
  "geo_distance_weight": 1.0,
  "mcc_profile_weight": 0.5,
  "amount_baseline_weight": 0.5,
  "time_window_weight": 0.3,
  "decline_rate_weight": 1.0,
  "merchant_country_weight": 0.3
}

Here, impossible travel alone (1.0) exceeds the threshold. Even an unusual hour (0.3) is enough to reject. Disabled engine — all weights set to 0, no transaction is ever rejected by risk score:

{
  "threshold": 1.0,
  "geo_distance_weight": 0.0,
  "mcc_profile_weight": 0.0,
  "amount_baseline_weight": 0.0,
  "time_window_weight": 0.0,
  "decline_rate_weight": 0.0,
  "merchant_country_weight": 0.0
}

Fail-safe behavior

The engine is designed to fail open: if the transaction history cannot be fetched, or if the configuration cannot be loaded, the risk score check is skipped and the transaction proceeds normally. This ensures that a Redis or database hiccup never causes unexpected declines.

Risk score fuse

The risk score engine evaluates each purchase and may decline transactions that appear high-risk. When a trusted cardholder is incorrectly blocked (false positive), you can arm a one-shot fuse that bypasses risk evaluation for the next single purchase on that card. After that purchase fires, the fuse is automatically consumed and normal validation resumes.

The fuse bypasses only the risk score check. All other controls (spending limits, velocity rules, frozen status, holding balance) still apply.

Operation	Endpoint
Arm the fuse	Arm risk score fuse
Disarm before it fires	Disarm risk score fuse
Check fuse state	Get risk score fuse state

Blocked merchant categories

Block purchases based on the type of business the merchant runs — its merchant category. You keep a blocklist of categories, and any purchase from a merchant in one of those categories is automatically declined. Use it to keep company spending away from business types you never want your cards used for — for example, gambling and casinos, or cash advances and ATM withdrawals.

This control applies to company cards only. It is set once at the account level and enforced across every card your company issues. It does not apply to individual cards.

Manage the blocklist from the Portal (Cards → Configuration), the same place where you manage country blocking. You choose categories by name from a standard catalog — there are no codes to type in. On top of your own list, CryptoMate maintains a platform-wide list of blocked categories that always applies to every company. These platform categories are shown in the Portal for reference and cannot be removed — your list is added on top of them, never replacing them. How the block behaves:

If a purchase comes from a merchant whose category is on your blocklist — or on the platform-wide list — it is declined.
A category blocked by the platform stays blocked even when it is not on your own list.

Blocked merchant countries

Block purchases based on the country where the merchant is located. You keep a blocklist of countries, and any purchase from a merchant in one of those countries is automatically declined. Use it as a geographic fraud and security control — for example, to keep spending inside the regions where your business actually operates and shut out purchases from countries you never expect to transact in.

This control applies to company cards only. It is set once at the account level and enforced across every card your company issues. It does not apply to individual cards.

Manage the blocklist from the Portal (Cards → Configuration), the same place where you manage merchant category (MCC) blocking. Add or remove countries at any time; changes take effect on the next purchase. Countries are identified by their standard two-letter country codes (for example, US or AR). How the block behaves:

If a purchase comes from a merchant whose country is on your blocklist, it is declined — the reason reported is “merchant country blocked”.
If a purchase does not carry a merchant country, it cannot be evaluated against the list and is not blocked by this control.

Blocked countries and blocked merchant categories (MCC) are independent, additive controls. A purchase is declined if it matches either list — neither one overrides the other.

Transactions

Searching transactions

Search transactions returns the transaction history for your account with filtering by card, date range, status, and more. Get transaction returns the full detail of a single transaction by ID.

Accumulated spending

Get accumulated spending returns the total amount spent within a given period, useful for dashboards and limit management.

PDF statements

Export transactions PDF generates a downloadable statement for a date range.

Webhooks

Cards is the most event-heavy product. Register your webhook URL and webhook_key from the Portal (Settings → Webhooks) or via Subscribe webhook URL and Subscribe webhook key. All card events arrive with "product": "cards" in the envelope.

Event	When it fires
`authorization`	A purchase needs your approval (WEBHOOK mode). Respond within 1,200 ms with `"00"` / `"SUCCESS"` to approve or `"05"` to decline. Timeout = decline.
`authorized`	A purchase was approved (TOPUP / NONE mode, or your webhook approved it).
`cleared`	An authorized purchase cleared and funds settled.
`declined`	A purchase was declined (by your webhook, by velocity rules, by risk score, or by insufficient balance).
`reversal`	An authorized purchase was reversed by the merchant or network.
`refund`	A merchant refund was applied to the card.
`deposit`	Funds arrived at a card’s top-up wallet.
`visa_direct_deposit`	A Visa Direct deposit credited the card.
`warranty_withdraw`	A withdrawal from the holding balance completed.
`notification_3ds_authorization`	A 3DS challenge was triggered. Deliver the OTP to the cardholder.
`card_blocked_by_velocity`	A velocity rule triggered and blocked the card. Sent once per `ACTIVE → BLOCKED` transition.

See Webhooks for the full envelope format, authentication via X-Webhook-Key, and payload examples.

Quick reference

Goal	Endpoint
Issue a card	POST /cards/virtual-cards/create
List all cards	GET /cards/virtual-cards
Get a card	GET /cards/virtual-cards/
Update spending limits	PATCH /cards/virtual-cards//limits
Freeze / unfreeze	PATCH /cards/virtual-cards//frozen
Unblock after velocity	POST /cards/virtual-cards//unblock
Reissue card number	POST /cards/virtual-cards//reissue
Check holding balance	GET /cards/holding/balance
Withdraw from holding	POST /cards/holding/withdraw
List fees withdrawal addresses	GET /cards/account/fees-wallet/whitelisted-addresses
Withdraw fees	POST /cards/account/fees-wallet/withdraw
Configure velocity rules	PUT /cards/account/configuration/velocity-rules
Arm risk score fuse	POST /cards/virtual-cards//risk-score-fuse
Search transactions	GET /cards/transactions

Cards API reference

Explore endpoints for virtual cards, transactions, holding, and account configuration.

​Overview

​Card specifications

​Operational models

Top Up

External authorization

​How it works

​Creating a card

​Approval method

​Spending limits

​Funding the account

​Fees wallet

​Pending vs. available balance

​Withdrawing fees

​Managing cards

​Spending limits

​Freeze and unfreeze

​Unblocking after a velocity block

​Reissuing a card

​Updating contact information

​Rotating the deposit wallet

​Deleting a card

​3DS authentication

​Fraud protection

​Velocity rules

​Risk score engine

​How the score is calculated

​Signals

​Configuration

​Examples

​Fail-safe behavior

​Risk score fuse

​Blocked merchant categories

​Blocked merchant countries

​Transactions

​Searching transactions

​Accumulated spending

​PDF statements

​Webhooks

​Quick reference

Cards API reference

Overview

Card specifications

Operational models

How it works

Creating a card

Approval method

Spending limits

Funding the account

Fees wallet

Pending vs. available balance

Withdrawing fees

Managing cards

Spending limits

Freeze and unfreeze

Unblocking after a velocity block

Reissuing a card

Updating contact information

Rotating the deposit wallet

Deleting a card

3DS authentication

Fraud protection

Velocity rules

Risk score engine

How the score is calculated

Signals

Configuration

Examples

Fail-safe behavior

Risk score fuse

Blocked merchant categories

Blocked merchant countries

Transactions

Searching transactions

Accumulated spending

PDF statements

Webhooks

Quick reference