Card funding (wallet & BYO)

Cards are topped up from stablecoins deposited for the cardholder (applicant). Apocor exposes one receive address and a one-click fund call. You choose the product mode per program.

How money moves

Each applicant has three balances, and funds flow through them in order:

Deposit wallet — where on-chain stablecoin deposits land (GET …/funding/deposit-address).
Spend account — the applicant’s USD balance. Deposits are swapped in automatically when a funding call needs them.
Card funds — the budget (debit programs) or per-card balance (prepaid programs) that transactions draw from. Top up with POST /v1/cards/{id}/fund-from-wallet, or move USD explicitly with POST /v1/accounts/{id}/transfers.

You never have to move money between pots 1 and 2 yourself: both fund-from-wallet and transfers (direction "in") auto-convert deposited stablecoins to USD when the spend balance is short, and report what they converted in a swapped array.

Card issuance charges an opening fee from the card funds pot. Make sure the applicant’s funding is in place before the first POST /v1/cards, or issuance fails with an issuer Balance insufficient error. The whole first-card flow is three steps: deposit stablecoins → one POST /v1/accounts/{id}/transfers with direction: "in" (auto-converts the deposit and fills the budget) → issue the card.

Mode	Who sends	Your job
`wallet_service` (default)	End-user (or you) to Apocor’s deposit address	Show deposit address → wait for balance → `fund-from-wallet`
`byo_wallet`	End-user from a wallet address you configure	Store their wallet → show deposit address → they send from that wallet → `fund-from-wallet`

Both modes use the same deposit address and the same POST /v1/cards/{id}/fund-from-wallet call. BYO only adds the configured send-from wallet on the program and on deposit-address responses.

Upstream issuer / crypto-rail names never appear in responses. You only see Apocor fields.

Testing deposits with TEST keys

The TEST environment runs on issuer testnets. Deposits are only detected for:

Currency	Chain	Testnet	Faucet
`USDC`	`ETH`	Ethereum Sepolia	faucet.circle.com

Request the deposit address with ?chain=ETH&currency=USDC, then send testnet USDC (Ethereum Sepolia) from the Circle faucet. Credits appear in funding/balances within a couple of minutes.

Other chains (Base, Arbitrum, Optimism, Polygon, Solana) generate valid addresses in TEST but deposits on them never credit — the issuer sandbox supports withdrawals only on those chains. Testnet funds sent there are unrecoverable. In LIVE, all configured chains support deposits normally.

1. Set the program funding mode

Wallet service (default)

curl -s -X PUT 'https://sandbox.apocor.ai/v1/programs/PROGRAM_ID/funding-config' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "mode": "wallet_service",
    "preferred_chain": "BASE",
    "preferred_currency": "USDC"
  }'

Bring-your-own (BYO) wallet

byo.address is required — the user’s external wallet they will send from.

curl -s -X PUT 'https://sandbox.apocor.ai/v1/programs/PROGRAM_ID/funding-config' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "mode": "byo_wallet",
    "preferred_chain": "BASE",
    "preferred_currency": "USDC",
    "byo": {
      "address": "0xUserWalletAddress",
      "chain": "BASE",
      "currency": "USDC",
      "provider": "metamask"
    }
  }'

Read back with GET /v1/programs/{id}/funding-config.

2. Get the deposit address

After the applicant has completed identity verification (status: APPROVED):

curl -s 'https://sandbox.apocor.ai/v1/applicants/APPLICANT_ID/funding/deposit-address?program_id=PROGRAM_ID&chain=BASE&currency=USDC' \
  -H 'Authorization: Bearer YOUR_TOKEN'

With TEST keys use chain=ETH — the issuer sandbox only credits deposits on Ethereum Sepolia (see Testing deposits).

Example BYO response:

{
  "data": {
    "applicant_id": "app_abc123",
    "mode": "byo_wallet",
    "address": "0xDepositReceiveAddress",
    "currency": "USDC",
    "chain": "BASE",
    "instructions": "Send from your configured external wallet to this address, then call fund-from-wallet on the card.",
    "byo_wallet": {
      "address": "0xUserWalletAddress",
      "chain": "BASE",
      "currency": "USDC",
      "provider": "metamask"
    }
  }
}

address — always the receive address (send to this).
byo_wallet.address — only in byo_wallet mode; the configured send-from wallet.

3. Check balances

curl -s 'https://sandbox.apocor.ai/v1/applicants/APPLICANT_ID/funding/balances' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Use available_to_fund_usd to know when you can fund: it is the sum of the USD spend balance plus stablecoin deposits that can still be converted. It does not include amounts already moved into budgets — check those with GET /v1/accounts/{id}/budgets.

4. Fund the card

curl -s -X POST 'https://sandbox.apocor.ai/v1/cards/CARD_ID/fund-from-wallet' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: fund-CARD_ID-25' \
  -d '{ "amount": "25.00" }'

This swaps deposited stables → USD and credits the card’s spend pot. Minimums are enforced by the rail (typically ≥ $0.50). Idempotency-Key is required on fund, fund-from-wallet, and defund — retries with the same key replay the original response for 72 hours.

Budgets (debit programs)

Debit programs spend from budgets — named pots of USD that cards draw from. Every applicant gets a default budget automatically the first time funds move or a card is issued; you can create more to ring-fence spend (e.g. “Marketing” vs “Travel”).

Top up a budget

# Fund the budget (e.g. before first issuance, to cover the opening fee).
# If the spend balance is short, deposited stablecoins are converted automatically.
curl -s -X POST 'https://sandbox.apocor.ai/v1/accounts/ACCOUNT_ID/transfers' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: topup-ACCOUNT_ID-001' \
  -d '{ "applicant_id": "APPLICANT_ID", "direction": "in", "amount": "15.00" }'

{
  "data": {
    "account_id": "acct_abc123",
    "budget_id": "bud_xyz789",
    "direction": "in",
    "amount": "15.00",
    "type": "budget",
    "swapped": [{ "currency": "USDC", "amount": "15.00" }]
  }
}

direction: "in" funds the budget (auto-converting deposits if needed); direction: "out" withdraws back to the spend account. Pass budget_id to target a specific budget — omitted, the default budget is used. If deposits plus spend balance still don’t cover the amount, you get 402 INSUFFICIENT_FUNDS. Idempotency-Key is optional here but honored — send one to make retries safe.

Named budgets

# Create an extra budget
curl -s -X POST 'https://sandbox.apocor.ai/v1/accounts/ACCOUNT_ID/budgets' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "applicant_id": "APPLICANT_ID", "name": "Marketing" }'

# List budgets with balances
curl -s 'https://sandbox.apocor.ai/v1/accounts/ACCOUNT_ID/budgets?applicant_id=APPLICANT_ID' \
  -H 'Authorization: Bearer YOUR_TOKEN'

# Rename
curl -s -X PATCH 'https://sandbox.apocor.ai/v1/budgets/BUDGET_ID' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Growth" }'

Bind a card to a budget at issuance by passing budget_id to POST /v1/cards (defaults to the default budget). The card’s spending and its fund-from-wallet top-ups then use that budget.

Flow

Errors to expect

Situation	Typical result
`byo_wallet` without `byo.address`	`400` — address required
Applicant KYC incomplete	`400` — no issuer account yet
Amount below rail minimum / insufficient deposit	`400` / issuer error
Transfer-in larger than deposits + spend balance	`402 INSUFFICIENT_FUNDS` — deposit more, wait for confirmation, retry
Wrong chain or currency	Deposit may not credit — match `preferred_*` / query params
Missing `Idempotency-Key` on `fund` / `fund-from-wallet` / `defund`	`400 IDEMPOTENCY_KEY_REQUIRED`
Card issued before funding is in place	`card.issuance.failed` event — `Balance insufficient` (opening fee). Fund, transfer in, and retry with a new `Idempotency-Key`
TEST deposit sent on an unsupported chain (e.g. Base Sepolia)	Never credits — use USDC on Ethereum Sepolia

Programs & accounts — create the program first
Cards — issue the prepaid card before funding
API reference: PUT /v1/programs/{id}/funding-config, GET …/funding/deposit-address, POST /v1/cards/{id}/fund-from-wallet

Get started

Core concepts

Webhooks & events

Reference

How money moves

Testing deposits with TEST keys

1. Set the program funding mode

Wallet service (default)

Bring-your-own (BYO) wallet

2. Get the deposit address

3. Check balances

4. Fund the card

Budgets (debit programs)

Top up a budget

Named budgets

Flow

Errors to expect

​How money moves

​Testing deposits with TEST keys

​1. Set the program funding mode

​Wallet service (default)

​Bring-your-own (BYO) wallet

​2. Get the deposit address

​3. Check balances

​4. Fund the card

​Budgets (debit programs)

​Top up a budget

​Named budgets

​Flow

​Errors to expect

​Related

How money moves

Testing deposits with TEST keys

1. Set the program funding mode

Wallet service (default)

Bring-your-own (BYO) wallet

2. Get the deposit address

3. Check balances

4. Fund the card

Budgets (debit programs)

Top up a budget

Named budgets

Flow

Errors to expect

Related