ZCard Docs
Preview API Apply for access
ZCard developer platform

Private money.
Usable infrastructure.

Build card experiences funded by shielded ZEC without exposing wallet addresses, transaction graphs, or chain metadata to the merchant layer.

i
Preview documentation

This reference describes the proposed ZCard integration surface. Endpoints and schemas may change before partner access opens.

01 Shielded deposits

Credit balances from confirmed ZEC deposits while preserving the privacy boundary.

02 Card lifecycle

Issue, freeze, unfreeze, and close virtual or physical prepaid cards.

03 Real-time events

Consume signed webhooks for deposits, authorizations, and settlements.

Get started

Make your first request

All requests use JSON and are served over HTTPS. Authenticate using a scoped bearer token in the Authorization header.

1

Request preview credentials

Partner credentials include a test API key, webhook signing secret, and an isolated sandbox account.

2

Create a cardholder session

A session initializes the card profile and returns a single-use application token.

3

Issue the card

Issue only after your session reaches eligible and the initial deposit is confirmed.

POST /v1/cards 
curl https://sandbox.api.zcard.app/v1/cards \
  -X POST \
  -H "Authorization: Bearer zc_test_••••••••" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: card_01J8..." \
  -d '{
    "type": "virtual",
    "currency": "USD",
    "spending_limit": 1000
  }'
Environments

Isolated by default

Sandbox and production use separate credentials, balances, deposit addresses, and webhook secrets. Test keys can never move real funds.

EnvironmentBase URLFunds
Sandboxhttps://sandbox.api.zcard.appSimulated ZEC
Productionhttps://api.zcard.appShielded ZEC
Core concepts

Architecture

ZCard keeps chain activity and card activity in separate trust domains. A narrow accounting boundary connects them without forwarding wallet metadata.

Private domain Shielded wallet Orchard / Sapling
proof + amount
ZCard boundary Deposit verifier Confirmation policy
ledger credit
Card domain Spend balance Authorization ledger
Authorization ZCard issuer layer Risk + balance checks
ISO 8583
Payment network Visa rails Global acceptance
purchase
Endpoint Merchant No chain data
Privacy boundary

What crosses the boundary

The verifier needs enough information to confirm value was received. The card ledger needs enough information to maintain a spendable balance. Neither requires a complete wallet history.

✓ Transferred
  • Confirmed deposit amount
  • Confirmation height
  • Internal allocation identifier
  • Asset and valuation timestamp
× Not transferred
  • Sender wallet address
  • Wallet balance or history
  • Shielded memo contents
  • Upstream transaction graph
Deposits

Deposit lifecycle

A deposit moves through deterministic states. Integrations should treat webhook delivery as a notification and retrieve the latest object before updating local state.

01detectedTransaction observed
→
02confirmingWaiting for depth
→
03creditedBalance available
→
04settledFinalized internally
Do not unlock value on detected.

Only credited deposits are available for card authorization. Confirmation requirements may increase during abnormal network conditions.

Card authorization

Decision path

Authorizations are evaluated against available balance, card state, controls, and network risk signals. A hold is created before an approval is returned.

Merchant request$42.80 · Grocery
→
Policy engineCard active · MCC allowed
→
Balance hold$42.80 reserved
→
Approved38 ms
API reference

Authentication

API keys are environment-specific and should only be used from your server. Never expose a secret key in a browser, mobile bundle, or public repository.

zc_test_...Sandbox secret key
zc_live_...Production secret key
whsec_...Webhook signing secret
Least-privilege access

Use restricted keys with explicit scopes such as cards:write, deposits:read, and transactions:read.

Cards API

Cards

Create and control virtual or physical prepaid cards.

typeenum · required

virtual or physical

currencystring · required

Three-letter settlement currency.

spending_limitinteger

Maximum monthly spend in minor units.

Response · 201
{
  "id": "card_01J8H6WQ2J9Y",
  "type": "virtual",
  "status": "active",
  "last4": "4892",
  "currency": "USD",
  "created_at": "2026-09-20T20:15:31Z"
}
Deposits API

Deposits

Generate deposit instructions and monitor shielded ZEC funding.

Transactions API

Transactions

Read authorization, reversal, refund, and settlement records.

Webhooks

Signed, retried events

Webhook payloads are signed with HMAC-SHA256. Verify the raw request body before parsing JSON, reject stale timestamps, and return a 2xx response quickly.

deposit.detected deposit.credited card.created card.updated transaction.authorized transaction.declined transaction.settled transaction.reversed
Webhook payload
{
  "id": "evt_01J8H7P4T9K2",
  "type": "deposit.credited",
  "created_at": "2026-09-20T20:18:02Z",
  "data": {
    "deposit_id": "dep_01J8H7MZ0NQ8",
    "asset": "ZEC",
    "amount": "1.25000000",
    "status": "credited"
  }
}
Errors

Predictable failure modes

Errors use standard HTTP status codes and include a stable machine-readable code, human-readable message, and request identifier.

StatusCodeMeaning
400invalid_requestMalformed or missing parameter
401authentication_failedMissing or invalid API key
409idempotency_conflictKey reused with different input
422insufficient_balanceAvailable balance is too low
429rate_limit_exceededRetry after the supplied delay
Operations

Security model

Controls are designed around separation of duties, short-lived access, auditable state transitions, and minimizing retained information.

01Scoped credentials

Separate keys by environment, service, and capability.

02Signed events

Timestamped HMAC signatures with replay protection.

03Encrypted secrets

Envelope encryption for sensitive card and account material.

04Immutable audit

Append-only records for balance and card state changes.

Limits & fees

Published operating limits

Program limits are applied at the account and card level. Limits shown here are proposed preview defaults and may vary by region.

ControlDefaultScope
Maximum card balance$2,500Per card
Monthly load$1,000Per account
Minimum ZEC deposit$25 equiv.Per deposit
API rate limit120/minPer key
Webhook attempts8Exponential backoff
End of reference

Build the private spend layer.

Partner access is limited during the preview period.

Apply for access →