#Cards

Crypto debit cards — holders, KYC, issuance, top-up/withdraw, reveal, and delivery

32 endpoints. Generated from docs/openapi.yaml v1.0.0.

#GET/v1/cards/holders

List your card holders · Auth: bearer API key · operationId: listCardHolders

One row per provider identity, newest first, with a card count and KYC state.

#Responses

200 response body

{
  "holders": [
    {
      "id": 1,
      "user_id": "string",
      "rail": "rail_a",
      "name": "string",
      "program": "string",
      "email": "string",
      "kyc_status": "none",
      "card_count": 1,
      "created_at": "2026-08-31T09:15:00.000Z"
    }
  ]
}

#Example request

curl -X GET 'https://api.cryptoinfra.build/v1/cards/holders' \
  -H 'Authorization: Bearer ck_live_your_key'

#POST/v1/cards/holders

Register a card holder · Auth: bearer API key · operationId: createCardHolder

The first step of the card flow: registers your user at the card provider and persists the holder. Idempotent per (user, rail) — replaying returns the existing holder untouched (still 201). Pass provider only when two enabled rails could both take the holder.

The same customer may hold a card at any number of merchants with the same email address: the rail's account is opened under a tagged copy of it, so one merchant's holder never blocks another's. 409 email_taken (with details.email) is answered only when no tag is free for that address — send a different one; it is not a retryable failure.

#Request body

application/json · required

#Responses

201 response body — CardHolder

{
  "user_id": "string",
  "rail": "rail_a",
  "email": "string",
  "kyc_status": "none",
  "kyc_remark": "string"
}

#Example request

curl -X POST 'https://api.cryptoinfra.build/v1/cards/holders' \
  -H 'Authorization: Bearer ck_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
  "user_id": "string",
  "email": "string",
  "phone": "+6591234567"
}'

#GET/v1/cards/summary

Card counts at a glance · Auth: bearer API key · operationId: cardsSummary

Totals for a dashboard header — cards by normalized status, plus how many holders exist.

#Parameters

#Responses

200 response body

{
  "cards": 1,
  "by_status": {},
  "holders": 1,
  "on_cards": "string",
  "processing": "string",
  "balances_read": 1
}

#Example request

curl -X GET 'https://api.cryptoinfra.build/v1/cards/summary' \
  -H 'Authorization: Bearer ck_live_your_key'

#GET/v1/cards/orders

Card-order ledger · Auth: bearer API key · operationId: listCardOrders

Every issue, top-up, card withdrawal and close fee on your account, newest first. card_id filters to one card, core_id to one programme.

#Parameters

#Responses

200 response body

{
  "orders": [
    {
      "id": 1,
      "kind": "topup",
      "status": "string",
      "amount": "string",
      "fee": "string",
      "amount_credited": "string",
      "card_id": 1,
      "card_last4": "string",
      "rail": "rail_a",
      "user_id": "string",
      "error": "string",
      "txid": "string",
      "created_at": "2026-08-31T09:15:00.000Z"
    }
  ]
}

#Example request

curl -X GET 'https://api.cryptoinfra.build/v1/cards/orders' \
  -H 'Authorization: Bearer ck_live_your_key'

#GET/v1/cards/kyc/countries

KYC country catalogue · Auth: bearer API key · operationId: getCardKycCountries

The provider's supported KYC countries. value is the ISO alpha-3 code to pass as nation_code / country_code in POST /v1/cards/kyc.

#Parameters

#Responses

200 response body

{
  "countries": [
    {
      "name": "string",
      "en_name": "string",
      "value": "string",
      "prof_value": "string",
      "code": "string",
      "telephone_code": "string",
      "need_certificate": true
    }
  ]
}

#Example request

curl -X GET 'https://api.cryptoinfra.build/v1/cards/kyc/countries' \
  -H 'Authorization: Bearer ck_live_your_key'

#POST/v1/cards/kyc/upload

Upload a KYC document · Auth: bearer API key · operationId: uploadCardKycDocument

Passes a KYC document through to the provider and returns its hosted URL (feed that URL into POST /v1/cards/kyc). The bytes live only in this request — never stored on disk or in the DB. Max 5 MB decoded; the extension must be .png/.jpg/.jpeg/.pdf.

#Request body

application/json · required

#Responses

201 response body

{
  "file_url": "string"
}

#Example request

curl -X POST 'https://api.cryptoinfra.build/v1/cards/kyc/upload' \
  -H 'Authorization: Bearer ck_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
  "user_id": "string",
  "provider": "rail_a",
  "filename": "string",
  "content_base64": "string"
}'

#POST/v1/cards/kyc

Submit the KYC dossier · Auth: bearer API key · operationId: submitCardKyc

Submits KYC to the provider and flips the holder to pending. We keep no PII — the fields go straight to the provider. Resubmission after a rejection is allowed; an already-approved holder is rejected (400 invalid_request). id_back_url is required for cert_type 1 (ID card) and 3 (driver's licence).

#Request body

application/json · required · schema CardKycApply

#Responses

202 response body — CardHolder

{
  "user_id": "string",
  "rail": "rail_a",
  "email": "string",
  "kyc_status": "none",
  "kyc_remark": "string"
}

#Example request

curl -X POST 'https://api.cryptoinfra.build/v1/cards/kyc' \
  -H 'Authorization: Bearer ck_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
  "user_id": "string",
  "provider": "rail_a",
  "first_name": "string",
  "last_name": "string",
  "id_no": "string",
  "email": "string",
  "nation_code": "string",
  "cert_type": 1,
  "id_url": "string",
  "birthday": "string",
  "country_code": "string",
  "area_code": "string",
  "phone": "string"
}'

#GET/v1/cards/kyc/status

Authoritative KYC status · Auth: bearer API key · operationId: getCardKycStatus

Polls the rail and syncs the holder row before answering. Pass provider only when the user holds LIVE identities on two rails at once.

#Parameters

#Responses

200 response body — CardHolder

{
  "user_id": "string",
  "rail": "rail_a",
  "email": "string",
  "kyc_status": "none",
  "kyc_remark": "string"
}

#Example request

curl -X GET 'https://api.cryptoinfra.build/v1/cards/kyc/status?user_id=string' \
  -H 'Authorization: Bearer ck_live_your_key'

#POST/v1/kyc/start

Start (or resume) identity verification · Auth: bearer API key · operationId: startKyc

cryptoinfra-owned KYC, independent of the card rail. Creates (or RESUMES) a verification session for user_id and returns the hosted URL to send the user to. approved is terminal — a verified user is never sent around again (no url, status: approved). Call this when a product's requires_kyc is true before issuing it.

Server-to-server only: authenticate with the tenant key and proxy from your backend — never expose this to a browser (the tenant key operates every card on the tenant). The verdict itself is always re-read from the provider's decision endpoint; poll GET /v1/kyc/status to observe it.

#Request body

application/json · required

#Responses

200 response body

{
  "status": "none",
  "url": "string"
}

#Example request

curl -X POST 'https://api.cryptoinfra.build/v1/kyc/start' \
  -H 'Authorization: Bearer ck_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
  "user_id": "string"
}'

#GET/v1/kyc/status

Current KYC verdict (reconciled at read time) · Auth: bearer API key · operationId: getKycStatus

The user's verdict, re-read from the provider while it can still change (pending/review); terminal states are not re-fetched. none when the user has never started verification.

#Parameters

#Responses

200 response body

{
  "status": "none"
}

#Example request

curl -X GET 'https://api.cryptoinfra.build/v1/kyc/status?user_id=string' \
  -H 'Authorization: Bearer ck_live_your_key'

#GET/v1/cards/products

Card product catalogue · Auth: bearer API key · operationId: listCardProducts

Every issuable product, across every card programme you can issue from — the source of truth for the product_code and core_id you pass to POST /v1/cards. Read both from here; never hard-code either. A programme that is closed to new cards simply does not appear, so an empty list means nothing is currently on sale rather than that the feature is broken.

Each row carries the programme it belongs to (core_id, core_name) and is PRICED FOR THAT PROGRAMME. The same BIN under two programmes can cost different amounts, so compare prices by (core_id, card_bin) — never by BIN alone.

Each row also carries what the user pays: issue_fee (our one-time issuance fee for THAT product, on THAT programme), min_opening_balance — the smallest initial_amount the issue will accept — and issue_total, everything the cardholder is debited to open the card at that minimum: our issue fee, the opening balance priced as a load (our load fee + gas), and your own fees if set. Budget from issue_total (or total on GET /v1/cards/issue-quote for another opening balance); never add issue_fee and initial_amount yourself.

The envelope's top-level issue_fee is deprecated (virtual-card fee off the default row only) — use products[].issue_fee.

#Parameters

#Responses

200 response body

{
  "asset_id": "usdt_trc20",
  "gas": "1.5",
  "gas_dynamic": true,
  "gas_priced_at": "2026-08-31T09:15:00.000Z",
  "issue_fee": "1.5",
  "issue_fee_base": "1500000000",
  "products": [
    {
      "id": 1,
      "rail": "rail_a",
      "core_id": "string",
      "core_name": "string",
      "code": "string",
      "card_nature": "VIRTUAL",
      "ccy": "string",
      "region": "string",
      "card_bin": "string",
      "card_brand": "string",
      "card_mode": "string",
      "title": "string",
      "requires_kyc": true,
      "active_min_limit": "string",
      "recharge_min_limit": "string",
      "withdraw_min_limit": "string",
      "issue_fee": "1.5",
      "issue_fee_base": "1500000000",
      "merchant_issue_fee": "1.5",
      "issue_total": "1.5",
      "issue_total_base": "1500000000",
      "charged_to": "cardholder",
      "load_fee_bps": 1,
      "load_fee_min": "1.5",
      "load_fee_flat": "1.5",
      "close_fee": "1.5",
      "close_fee_base": "1500000000",
      "cardholder_fees": {
        "per_transaction": "string",
        "three_d_secure": "string",
        "foreign_currency_pct": "string",
        "atm_flat": "string",
        "atm_pct": "string",
        "cancellation": "string",
        "dispute": "string",
        "monthly_service": "string"
      },
      "limits": {
        "per_transaction": "string",
        "daily": "string",
        "monthly": "string",
        "atm_single": "string",
        "atm_per_day": 1,
        "atm_monthly": "string",
        "cards_per_user": 1,
        "validity_years": 1
      },
      "min_opening_balance": "5.000000",
      "min_opening_balance_base": "1500000000"
    }
  ]
}

#Example request

curl -X GET 'https://api.cryptoinfra.build/v1/cards/products' \
  -H 'Authorization: Bearer ck_live_your_key'

#GET/v1/cards

List cards · Auth: bearer API key · operationId: listCards

With user_id: that user's cards across all their provider identities (404 when the user has no card holder). Without it: every card on your account, newest first — each row additionally carries user_id, cardholder_name, the holder's program, and a cached (≤60 s) live balance / pending (null when unreadable, never a fake zero), so any per-card endpoint can be called from a row. core_id narrows either form to one programme.

#Parameters

#Responses

200 response body

{
  "user_id": "string",
  "cards": [
    {
      "id": 1,
      "rail": "rail_a",
      "core_id": "string",
      "bin": "string",
      "product_id": "string",
      "product_code": "string",
      "card_nature": "VIRTUAL",
      "status": 1,
      "status_normalized": "issuing",
      "currency": "string",
      "last4": "string",
      "name_on_card": "string",
      "issued_at": "2026-08-31T09:15:00.000Z",
      "user_id": "string",
      "cardholder_name": "string",
      "program": "string",
      "balance": "string",
      "pending": "string"
    }
  ]
}

#Example request

curl -X GET 'https://api.cryptoinfra.build/v1/cards' \
  -H 'Authorization: Bearer ck_live_your_key'

#POST/v1/cards

Issue a card · Auth: bearer API key · operationId: issueCard

A card is issued FUNDED. initial_amount is required and must be at least the product's min_opening_balance from GET /v1/cards/products (read that value, do not hard-code a minimum — it tracks platform policy and the issuer's own floor, whichever is higher). The cardholder is debited total from GET /v1/cards/issue-quote — our issue fee, the opening balance priced as a load (our load fee + gas), and your own fees if set — at request time, and refunded together if the application definitively fails. Read issue_total on the shelf or total on the quote; never add the parts yourself.

Pass one of product_id / product_code, taken from GET /v1/cards/products rather than hard-coded. provider is almost never needed: the product code names its own rail. delivery_address_id (from POST /v1/cards/delivery/address) is required for PHYSICAL products. Requires an approved holder. idempotency_key is required and replay-safe. The holder pays: our issue fee, the opening balance priced as a load, gas, and your own fees if you set any — see issue_total on GET /v1/cards/products.

201 = the card exists (card populated). 202 = the application is still resolving (card is null; a card.status webhook or the reconciler links it later). Treat 202 as PENDING.

The normal answer is 202. The opening balance is sent on-chain to the rail first, so the response is 202 with order.status: funding (then requested/sent); the card is applied for once the rail shows the credit and arrives on the card.status webhook, usually within minutes.

A 201 card is not spendable yet. It is returned with status_normalized: issuing, and turns active only once the opening balance has landed at the issuer — usually minutes. An integrator that polls for active immediately after the 201 will see issuing first; that is the normal path, not an error. Watch GET /v1/cards/{id} or the card.status webhook for the flip.

#Request body

application/json · required

#Responses

201 response body — CardIssueResult

{
  "order": {
    "id": 1,
    "kind": "topup",
    "status": "funding",
    "txid": "string",
    "asset_id": "usdt_trc20",
    "amount": "1.5",
    "amount_base": "1500000000",
    "fee": "1.5",
    "fee_base": "1500000000",
    "gas": "1.5",
    "merchant_fee": "1.5",
    "total": "1.5",
    "sent_on_chain": "1.5",
    "amount_credited": "1.5",
    "amount_credited_base": "1500000000",
    "card_id": 1,
    "request_order_id": "string",
    "provider_status": "string",
    "error": "string",
    "idempotency_key": "string",
    "created_at": "2026-08-31T09:15:00.000Z"
  },
  "card": {
    "id": 1,
    "rail": "rail_a",
    "core_id": "string",
    "bin": "string",
    "product_id": "string",
    "product_code": "string",
    "card_nature": "VIRTUAL",
    "status": 1,
    "status_normalized": "issuing",
    "currency": "string",
    "last4": "string",
    "name_on_card": "string",
    "issued_at": "2026-08-31T09:15:00.000Z"
  }
}

#Example request

curl -X POST 'https://api.cryptoinfra.build/v1/cards' \
  -H 'Authorization: Bearer ck_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
  "user_id": "string",
  "idempotency_key": "string",
  "initial_amount": "string"
}'

#GET/v1/cards/topup-quote

Preview a top-up's fee and total · Auth: bearer API key · operationId: cardTopupQuote

Read-only, holds nothing. The fees are charged ON TOP of amount: the card receives exactly amount (so credited equals it), and total is what the cardholder's balance is debited — amount plus fee, gas and merchant_fee. Show total wherever you tell someone what a load will cost, and check it against the balance before you send. Pass card_id and user_id together to price a specific card (its rail, BIN and product); otherwise the rail's default row prices it.

#Parameters

#Responses

200 response body

{
  "asset_id": "usdt_trc20",
  "amount": "1.5",
  "amount_base": "1500000000",
  "fee": "1.5",
  "fee_base": "1500000000",
  "gas": "1.5",
  "gas_base": "1500000000",
  "merchant_fee": "1.5",
  "merchant_fee_base": "1500000000",
  "credited": "1.5",
  "credited_base": "1500000000",
  "total": "1.5",
  "total_base": "1500000000",
  "charged_to": "cardholder",
  "dynamic": true
}

#Example request

curl -X GET 'https://api.cryptoinfra.build/v1/cards/topup-quote?amount=string' \
  -H 'Authorization: Bearer ck_live_your_key'

#GET/v1/cards/issue-quote

Preview what issuing a card costs the cardholder · Auth: bearer API key · operationId: cardIssueQuote

Read-only, holds nothing. total is what the cardholder's balance is debited by POST /v1/cards — our issue fee, yours, initial_amount, and the load fee and gas on that opening balance, charged on top of it. The card opens with opening_credited, which is initial_amount itself. Priced by the same code that charges, so the preview and the charge cannot differ. A card is issued FOR one of your users and only from what that user holds: when their balance is short, POST /v1/cards is refused with 409 insufficient_balance before anything is charged or applied for. Read total; adding the parts yourself is how a preview ends up smaller than the charge.

#Parameters

#Responses

200 response body

{
  "asset_id": "usdt_trc20",
  "core_id": "core-1",
  "product_code": "string",
  "initial_amount": "1.5",
  "initial_amount_base": "1500000000",
  "min_opening_balance": "1.5",
  "fee": "1.5",
  "fee_base": "1500000000",
  "gas": "1.5",
  "gas_base": "1500000000",
  "merchant_fee": "1.5",
  "merchant_fee_base": "1500000000",
  "opening_credited": "1.5",
  "opening_credited_base": "1500000000",
  "total": "1.5",
  "total_base": "1500000000",
  "charged_to": "cardholder",
  "dynamic": true
}

#Example request

curl -X GET 'https://api.cryptoinfra.build/v1/cards/issue-quote?product_code=string' \
  -H 'Authorization: Bearer ck_live_your_key'

#GET/v1/cards/orders/{order_id}

Read a card order's status (the authoritative poll) · Auth: bearer API key · operationId: getCardOrder

Return a card order by its id. This is the authoritative outcome read behind a "webhooks are hints, the poll is truth" reconcile model: a top-up / withdrawal / issue-fee order is created 202 processing (status: funding, requested or sent) and reaches confirmed or failed as the platform's reconciler and provider webhooks settle it. Poll this when a card.topup / card.withdraw webhook was missed (delivery exhausted, or your endpoint was down) so a debited operation can always be resolved without a manual investigation. Tenant-scoped: another tenant's order returns 404 and is never disclosed.

Refund discipline (unchanged): refund the customer only on status: failed (definitive — the money did not move); never on requested/sent (outcome still unknown).

#Parameters

#Responses

200 response body — CardOrder

{
  "id": 1,
  "kind": "topup",
  "status": "funding",
  "txid": "string",
  "asset_id": "usdt_trc20",
  "amount": "1.5",
  "amount_base": "1500000000",
  "fee": "1.5",
  "fee_base": "1500000000",
  "gas": "1.5",
  "merchant_fee": "1.5",
  "total": "1.5",
  "sent_on_chain": "1.5",
  "amount_credited": "1.5",
  "amount_credited_base": "1500000000",
  "card_id": 1,
  "request_order_id": "string",
  "provider_status": "string",
  "error": "string",
  "idempotency_key": "string",
  "created_at": "2026-08-31T09:15:00.000Z"
}

#Example request

curl -X GET 'https://api.cryptoinfra.build/v1/cards/orders/1' \
  -H 'Authorization: Bearer ck_live_your_key'

#GET/v1/cards/{id}

Secure card details · Auth: bearer API key · operationId: getCard

Local card + live balance + a link to this card's hosted card-number page (card_pan_url — drop it into an <iframe src>; it works for about ten minutes, so fetch it fresh each time you show the number). This endpoint never returns PAN/CVV — the full number is a separate, explicit call: POST /v1/cards/{id}/reveal. A live provider read failure DEGRADES to stored state (provider_read_failed: true, null balance — never fake zeros) rather than failing the call. When the read succeeded but there is no card-number page, reveal_unavailable: true is set.

#Parameters

#Responses

200 response body — CardDetails

{
  "card": {
    "id": 1,
    "rail": "rail_a",
    "core_id": "string",
    "bin": "string",
    "product_id": "string",
    "product_code": "string",
    "card_nature": "VIRTUAL",
    "status": 1,
    "status_normalized": "issuing",
    "currency": "string",
    "last4": "string",
    "name_on_card": "string",
    "issued_at": "2026-08-31T09:15:00.000Z"
  },
  "balance": {
    "available": "string",
    "pending": "string",
    "currency": "USD"
  },
  "currency": "string",
  "card_pan_url": "string",
  "expire_date": "string",
  "masked_number": "string",
  "name_on_card": "string",
  "cardholder_name": "string",
  "bin": "string",
  "decline_count": 1,
  "decline_limit": 1,
  "otp_available": true,
  "otp_waiting": {
    "kind": "payment_3ds",
    "merchant_name": "string",
    "amount": "string",
    "currency": "string",
    "expires_in_seconds": 0
  },
  "provider_read_failed": true,
  "note": "string",
  "reveal_unavailable": true,
  "reveal_note": "string"
}

#Example request

curl -X GET 'https://api.cryptoinfra.build/v1/cards/1?user_id=string' \
  -H 'Authorization: Bearer ck_live_your_key'

#DELETE/v1/cards/{id}

Close (terminate) a card · Auth: bearer API key · operationId: closeCard

Terminates the card. One call is enough.

1. If the card still holds a balance, this call returns the residual to us (a card→wallet withdrawal order) and answers 202 card_close_in_progress with details.card_id and details.order_id. The card is not closed yet — a 202 is not a closed card. Until it is, GET /v1/cards/{id} carries close_in_progress: true.
2. Within about a minute of that order settling we finish the close ourselves: the close fee — ours plus yours, see GET /v1/cards/{id}/close-quote — is debited from the cardholder and the card is terminated. The card.status webhook confirms it, and the card reads status_normalized: closed. The fee shows up as a close_fee order. You may also call DELETE again yourself once the order is confirmed (card.withdraw webhook or GET /v1/cards/orders/{order_id}); that finishes it at once, and a DELETE on a card we already closed answers 200 with the card.

The close is always accepted: it never fails because a refund cannot be paid yet. Read close_refund.state on GET /v1/cards/{id} for where the money is (waiting → approved → sending → paid, or held with a reason).

A card holding less than the issuer's cancellation fee, or nothing at all, closes like any other (since 20 September 2026): the issuer keeps what is on the card, there is nothing to return, and 409 card_close_underfunded is no longer raised. minimum_card_balance on the close quote is always 0.

Money still pending on the card blocks the close with 409 card_state (the error names the amount) — wait for it to settle.

The card's balance goes back to the holder's own address on-chain, from a wallet cryptoinfra funds by hand, within 7 working days of the issuer releasing it. The close is never refused while that is arranged (409 card_refund_wallet_empty is retired): read close_refund.state on GET /v1/cards/{id} — waiting, approved, sending, paid, or held with a reason. Closing an already-closed or expired card also answers 409 card_state. If the balance cannot be read the close is refused (400) — an unreadable balance is never treated as zero.

Residual-on-close rails refund the residual as part of the close. The settlement that credits that residual back to the user arrives in a later release; until then close for these providers answers 400 not_supported_by_provider.

#Parameters

#Request body

application/json · required · schema CardUserRef

#Responses

200 response body

{
  "card": {
    "id": 1,
    "rail": "rail_a",
    "core_id": "string",
    "bin": "string",
    "product_id": "string",
    "product_code": "string",
    "card_nature": "VIRTUAL",
    "status": 1,
    "status_normalized": "issuing",
    "currency": "string",
    "last4": "string",
    "name_on_card": "string",
    "issued_at": "2026-08-31T09:15:00.000Z"
  }
}

#Example request

curl -X DELETE 'https://api.cryptoinfra.build/v1/cards/1' \
  -H 'Authorization: Bearer ck_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
  "user_id": "string"
}'

#GET/v1/cards/{id}/balance

Live card balance · Auth: bearer API key · operationId: getCardBalance

pending is null (not 0) when the provider does not expose holds.

While the card is still being issued (status_normalized: issuing, the minute or two after POST /v1/cards) this answers 409 card_issuing — poll GET /v1/cards/{id} or wait for the card.status webhook, then retry.

#Parameters

#Responses

200 response body — CardBalance

{
  "available": "1.5",
  "available_base": "1500000000",
  "pending": "string",
  "pending_base": "string",
  "currency": "string"
}

#Example request

curl -X GET 'https://api.cryptoinfra.build/v1/cards/1/balance?user_id=string' \
  -H 'Authorization: Bearer ck_live_your_key'

#POST/v1/cards/{id}/reveal

Reveal the full card number · Auth: bearer API key · operationId: revealCard

Full card details for the merchant that OWNS the card, on explicit request. POST (never GET) so the card id never lands in an access-log query string, and the body is the only place the secrets ever appear.

The issuer decides the shape of the answer, and exactly ONE of the two forms is populated — always branch on which:

• Raw secrets — pan, cvv and expiry (MM/YY) are filled and reveal_url is null.
• Hosted page — the issuer reveals only through its own page: pan and cvv come back null and reveal_url carries a URL to open. The link is SHORT-LIVED (about a minute) and single-purpose: hand it straight to the cardholder's browser. Do not cache it, store it, put it in an email, or re-serve it later — a stale link is simply dead, and mint a fresh one by calling this endpoint again.

A client that reads only pan will therefore show a blank card number for every card on a hosted-reveal product. Handle both.

While the card is still being issued (status_normalized: issuing) this answers 409 card_issuing instead of a body with neither form — poll GET /v1/cards/{id} or wait for the card.status webhook, then retry.

Handling rules (both forms). The response is sent with Cache-Control: no-store. Never log, persist, or forward these values — not to your database, not to analytics, not into a support ticket. Render them to the cardholder and drop them.

This is the way to show a card number. Both enabled rails answer it with raw secrets, so you can render your own card face — you do not need to embed anything. card_pan_url on GET /v1/cards/{id} remains for clients that would rather not handle a PAN at all, and reveal_url here covers the rare product whose issuer insists on showing the number itself. A rail with no reveal at all answers 400 not_supported_by_provider.

Scoped exactly like every other per-card call: the card must belong to this tenant AND to the user_id in the body, or the call 404s.

#Parameters

#Request body

application/json · required · schema CardUserRef

#Responses

200 response body — CardSecrets

{
  "pan": "string",
  "cvv": "string",
  "expiry": "string",
  "reveal_url": "string"
}

#Example request

curl -X POST 'https://api.cryptoinfra.build/v1/cards/1/reveal' \
  -H 'Authorization: Bearer ck_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
  "user_id": "string"
}'

#GET/v1/cards/{id}/otp

Fetch the card's live one-time code · Auth: bearer API key · operationId: getCardOtp

Returns the verification code the ISSUER relayed for this card — either a 3DS code that approves a payment, or a wallet code that adds the card to Apple/Google Pay.

The code never reaches the cardholder's own phone or email. For an issued-on-your-program card the issuer sends it to us, so whichever channel the wallet or checkout offers your customer, the code arrives here. This endpoint is how you hand it to them.

Three properties to build against:

• Single read. Fetching CONSUMES the code — a second call returns 404. Never poll this endpoint; call it when your user is ready to type the code. To know a code is waiting, read otp_available on GET /v1/cards/{id} (a peek that does not consume) or listen for the card.wallet_otp webhook. Your API key and your dashboard each have their own read: fetching a code from your server does not take it away from someone looking at the card in the dashboard, and the other way round.
• Short-lived. Codes expire in about ten minutes; expires_in_seconds is the remaining life at the moment of the read.
• Never stored. The code is held in memory only — not in the database, not in a webhook payload, not in a log. If it is lost, the customer must trigger a new one.

A 404 is deliberately uniform: it does not distinguish "no code arrived" from "already read", "expired", or "not your card".

#Parameters

#Responses

200 response body

{
  "card_id": 1,
  "code": "441524",
  "kind": "payment_3ds",
  "merchant_name": "EXAMPLE STORE",
  "amount": "12.50",
  "currency": "USD",
  "expires_in_seconds": 477
}

#Example request

curl -X GET 'https://api.cryptoinfra.build/v1/cards/1/otp' \
  -H 'Authorization: Bearer ck_live_your_key'

#POST/v1/cards/{id}/topup

Top up a card · Auth: bearer API key · operationId: cardTopup

Debits total from the cardholder's balance immediately (see GET /v1/cards/topup-quote: amount + our fee + gas + your fee), sends what the rail needs on-chain, and funds the card once that send is credited. Returns 202 with the order in funding; it moves to requested when the send confirms, sent when the rail is asked, confirmed when the card is funded — a card.topup webhook or the reconciler tells you. A definitive failure at any stage refunds the charge in full. Treat 202 as pending; refund your user ONLY on a definitive failure (409 provider_rejected, or a webhook with order status failed), never on the 202 itself. idempotency_key is required.

#Parameters

#Request body

application/json · required · schema CardMoneyRequest

#Responses

202 response body — CardOrder

{
  "id": 1,
  "kind": "topup",
  "status": "funding",
  "txid": "string",
  "asset_id": "usdt_trc20",
  "amount": "1.5",
  "amount_base": "1500000000",
  "fee": "1.5",
  "fee_base": "1500000000",
  "gas": "1.5",
  "merchant_fee": "1.5",
  "total": "1.5",
  "sent_on_chain": "1.5",
  "amount_credited": "1.5",
  "amount_credited_base": "1500000000",
  "card_id": 1,
  "request_order_id": "string",
  "provider_status": "string",
  "error": "string",
  "idempotency_key": "string",
  "created_at": "2026-08-31T09:15:00.000Z"
}

#Example request

curl -X POST 'https://api.cryptoinfra.build/v1/cards/1/topup' \
  -H 'Authorization: Bearer ck_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
  "user_id": "string",
  "amount": "string",
  "idempotency_key": "string"
}'

#GET/v1/cards/{id}/close-quote

What closing this card would charge the cardholder · Auth: bearer API key · operationId: cardCloseQuote

Read-only. Our flat close fee, the live network figure for the on-chain refund, plus your own fee if you set one — total is the holder's debit on DELETE /v1/cards/{id}.

#Parameters

#Responses

200 response body

{
  "asset_id": "usdt_trc20",
  "fee": "1.5",
  "fee_base": "1500000000",
  "gas": "1.5",
  "gas_base": "1500000000",
  "dynamic": true,
  "merchant_fee": "1.5",
  "merchant_fee_base": "1500000000",
  "total": "1.5",
  "total_base": "1500000000",
  "charged_to": "refund",
  "minimum_card_balance": "1.5",
  "issuer_fee": "1.5",
  "issuer_fee_base": "1500000000",
  "minimum_card_balance_base": "1500000000",
  "refund_quote": {
    "card_balance": "1.5",
    "card_balance_base": "1500000000",
    "issuer_fee": "1.5",
    "issuer_fee_base": "1500000000",
    "rail_return_fee": "1.5",
    "rail_return_fee_base": "1500000000",
    "close_fee": "1.5",
    "close_fee_base": "1500000000",
    "gas": "1.5",
    "gas_base": "1500000000",
    "merchant_fee": "1.5",
    "merchant_fee_base": "1500000000",
    "refund": "1.5",
    "refund_base": "1500000000",
    "live": true
  },
  "refund_eta_typical": "string",
  "refund_eta_max_days": 1,
  "refund_eta_working_days": 1
}

#Example request

curl -X GET 'https://api.cryptoinfra.build/v1/cards/1/close-quote?user_id=string' \
  -H 'Authorization: Bearer ck_live_your_key'

#GET/v1/merchant/card-fees

Your own card fees, on top of ours · Auth: bearer API key · operationId: merchantCardFeesGet

Ours is the floor and is always charged; what you set here is ADDED to it, charged to the cardholder, and credited to your own balance in the same journal as the charge. Nothing to move, nothing to pay out. Works with an API key or a dashboard login.

#Responses

200 response body

{
  "max_percent_bps": 1000,
  "charged_to": "cardholder",
  "ours": {
    "issue": {
      "flat": "1.5",
      "flat_physical": "1.5"
    },
    "load": {
      "percent_bps": 1,
      "min": "1.5",
      "gas": "1.5",
      "gas_dynamic": true,
      "gas_priced_at": "2026-08-31T09:15:00.000Z"
    },
    "close": {
      "flat": "1.5"
    }
  },
  "yours": [
    {
      "operation": "issue",
      "percent_bps": 1,
      "flat": "1.5",
      "updated_at": "2026-08-31T09:15:00.000Z"
    }
  ]
}

#Example request

curl -X GET 'https://api.cryptoinfra.build/v1/merchant/card-fees' \
  -H 'Authorization: Bearer ck_live_your_key'

#PUT/v1/merchant/card-fees/{operation}

Set your fee on one card operation · Auth: bearer API key · operationId: merchantCardFeeSet

A percentage of the amount (percent_bps, 100 = 1%, at most 1000), a flat amount (flat, in the card asset), or both. Omitted fields keep their current value. Refused with 409 no_own_account when your account has no balance of its own for the fee to land in.

#Parameters

#Request body

application/json · required

#Responses

200 response body

{
  "operation": "issue",
  "percent_bps": 1,
  "flat": "1.5"
}

#Example request

curl -X PUT 'https://api.cryptoinfra.build/v1/merchant/card-fees/issue' \
  -H 'Authorization: Bearer ck_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{}'

#DELETE/v1/merchant/card-fees/{operation}

Remove your fee on one card operation · Auth: bearer API key · operationId: merchantCardFeeClear

#Parameters

#Responses

#Example request

curl -X DELETE 'https://api.cryptoinfra.build/v1/merchant/card-fees/issue' \
  -H 'Authorization: Bearer ck_live_your_key'

#POST/v1/cards/{id}/withdraw

Retired — moving part of a card balance back to the wallet · Deprecated. · Auth: bearer API key · operationId: cardWithdraw

Retired on 2026-09-14. Always answers 410 card_unload_retired. The only way value leaves a card is DELETE /v1/cards/{id}, which returns the whole balance to the holder's own address on-chain. An unload would credit the holder's balance with coins that never reach their address.

#Parameters

#Request body

application/json · required · schema CardMoneyRequest

#Responses

#Example request

curl -X POST 'https://api.cryptoinfra.build/v1/cards/1/withdraw' \
  -H 'Authorization: Bearer ck_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
  "user_id": "string",
  "amount": "string",
  "idempotency_key": "string"
}'

#POST/v1/cards/{id}/freeze

Freeze a card · Auth: bearer API key · operationId: freezeCard

Freezes an active card (409 card_state otherwise). The authoritative status is confirmed by a card.status webhook.

#Parameters

#Request body

application/json · required · schema CardUserRef

#Responses

200 response body

{
  "card": {
    "id": 1,
    "rail": "rail_a",
    "core_id": "string",
    "bin": "string",
    "product_id": "string",
    "product_code": "string",
    "card_nature": "VIRTUAL",
    "status": 1,
    "status_normalized": "issuing",
    "currency": "string",
    "last4": "string",
    "name_on_card": "string",
    "issued_at": "2026-08-31T09:15:00.000Z"
  }
}

#Example request

curl -X POST 'https://api.cryptoinfra.build/v1/cards/1/freeze' \
  -H 'Authorization: Bearer ck_live_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
  "user_id": "string"
}'

#POST/v1/cards/{id}/unfreeze

Unfreeze a card · Auth: bearer API key · operationId: unfreezeCard

Unfreezes a frozen card (409 card_state otherwise).

#Parameters

#Request body

application/json · required · schema CardUserRef

#Responses