Skip to main content
Card withdrawal is only available for issuers using the master wallet funding structure. The funds are settled on-chain directly to your issuer master wallet.

​
How it works

A card withdrawal moves USDC from a customer’s card account (their on-chain Safe) back to your issuer master wallet in a single API call:
  1. You call POST /api/card-issuer/withdraw-from-card with a customer identifier and amount
  2. Yativo fetches EIP-712 typed data from the card network, signs it server-side using the card’s EOA, and submits the transaction
  3. A delay relay holds the transaction for ~3 minutes — the card is temporarily frozen during this window
  4. Once the delay elapses the transfer executes on-chain and your master wallet is credited
  5. Three webhooks fire: card.withdrawal.settled (customer-scoped), master_wallet.withdrawal (issuer-scoped), and master_wallet.deposit (master wallet balance credited)

​
API

POST /api/card-issuer/withdraw-from-card
Authentication: Bearer token (your issuer API key)
​
id
string
required
Identifies the customer’s card. Accepts any of:
  • yativo_card_id — e.g. yativo_card_customer_...
  • external_id — the ID you assigned during onboarding
  • customer_id — the Yativo internal customer ObjectId
  • email — only valid when the customer has exactly one card; returns 422 if ambiguous
​
amount
number
required
Amount to withdraw in display units (e.g. 1, 25.50). Must be positive and not exceed the card’s available balance.
curl -X POST 'https://crypto-api.yativo.com/api/v1/card-issuer/withdraw-from-card' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "yativo_card_customer_abc123...",
    "amount": 1
  }'

{
  "success": true,
  "data": {
    "withdrawal_id": "cwd_1748012345678_x7k2qp",
    "yativo_card_id": "yativo_card_customer_...",
    "amount": 1.00,
    "amount_minor": 100,
    "currency": "USD",
    "status": "initiated",
    "message": "Withdrawal initiated. Funds will arrive in your master wallet shortly.",
    "estimated_settlement_at": "2026-05-23T14:35:00.000Z"
  }
}

​
Timing

StageTime
API response (withdrawal accepted)Immediate
Card frozen (delay relay active)Immediately after submission
On-chain settlement~3 minutes after submission
Card unfrozenAfter settlement confirms
Webhooks deliveredAfter settlement confirms
The 3-minute delay is enforced by the card network’s on-chain delay relay module and cannot be shortened.

​
Webhooks

Subscribe to these events to track withdrawal lifecycle:

​
card.withdrawal.settled

Fires when the withdrawal confirms on-chain. Scoped to the customer’s card account. 
{
  "type": "card.withdrawal.settled",
  "data": {
    "withdrawal_id": "wth_01HXABCDEF...",
    "yativo_card_id": "yativo_card_customer_...",
    "amount": 1.00,
    "amount_minor": 100,
    "currency": "USD",
    "card_balance": 10.87,
    "card_balance_minor": 1087,
    "tx_hash": "0xabc123...",
    "status": "settled",
    "settled_at": "2026-05-28T13:10:45.000Z"
  }
}
card_balance and card_balance_minor are present when the settlement notification arrives directly from the card network. They are absent when settlement is confirmed via the on-chain fallback path — handle both shapes defensively.

​
master_wallet.withdrawal

Fires at the same time as card.withdrawal.settled. Scoped to your issuer master wallet — confirms your wallet has been credited. 
{
  "type": "master_wallet.withdrawal",
  "data": {
    "withdrawal_id": "wth_01HXABCDEF...",
    "yativo_card_id": "yativo_card_customer_...",
    "amount": 1.00,
    "amount_minor": 100,
    "currency": "USD",
    "destination_address": "0x920abe21a7eb39DF5f5A42AE97F4Cd061d5AdD9b",
    "tx_hash": "0xabc123...",
    "status": "settled",
    "settled_at": "2026-05-28T13:10:45.000Z"
  }
}

​
master_wallet.deposit

Also fires when the withdrawal settles — the master wallet balance increase from the returned funds is treated as a deposit credit. This event carries the on-chain tx_hash and includes withdrawal_id and yativo_card_id so you can correlate it back to the originating withdrawal.
You will receive both master_wallet.withdrawal and master_wallet.deposit for each settled withdrawal. master_wallet.withdrawal is the semantic event for a withdrawal completing. master_wallet.deposit reflects the master wallet balance increasing and is the event that carries the confirmed on-chain transaction hash. Use withdrawal_id to join them.
{
  "type": "master_wallet.deposit",
  "data": {
    "settlement_id": "6a294844e71b09a046f28103",
    "withdrawal_id": "wth_01HXABCDEF...",
    "yativo_card_id": "yativo_card_customer_...",
    "deposit_amount": 1.00,
    "deposit_amount_minor": 100,
    "wallet_balance": 101.00,
    "wallet_balance_minor": 10100,
    "currency": "USD",
    "tx_hash": "0xabc123...",
    "solana_tx_hash": null,
    "status": "settled"
  }
}

​
card.withdrawal.failed

Fires if the on-chain transaction is rejected. No funds are moved. 
{
  "type": "card.withdrawal.failed",
  "data": {
    "withdrawal_id": "wth_01HXABCDEF...",
    "yativo_card_id": "yativo_card_customer_...",
    "amount": 1.00,
    "amount_minor": 100,
    "currency": "USD",
    "reason": "Transaction reverted",
    "status": "failed"
  }
}

​
customer.balance.updated

Fires when the card balance changes — including after a withdrawal settles. 
{
  "type": "customer.balance.updated",
  "data": {
    "yativo_card_id": "yativo_card_customer_...",
    "ledger_balance": 10.87,
    "ledger_balance_minor": 1087,
    "available_balance": 10.87,
    "available_balance_minor": 1087,
    "pending_balance": 0,
    "pending_balance_minor": 0,
    "currency": "USD",
    "timestamp": "2026-05-28T13:10:45.000Z"
  }
}
Subscribe to all five events to handle the full lifecycle: 
{
  "events": [
    "card.withdrawal.settled",
    "card.withdrawal.failed",
    "master_wallet.withdrawal",
    "master_wallet.deposit",
    "customer.balance.updated"
  ]
}

​
Notes

  • Card is frozen during processing. From submission until on-chain confirmation (~3 min), the card cannot be used for purchases.
  • Settlement is on-chain and irreversible. Once submitted the transaction cannot be cancelled. Verify the amount and customer before calling the endpoint.
  • Master wallet receives USDC on Gnosis Chain. The credited token matches the customer’s card denomination. For USD cards this is USDC (0x2a22f9c3b484c3629090FeED35F17Ff8F88f76F0).
  • amount_minor is in cents (1 USD = 100 minor units), regardless of the on-chain token decimals.

Fund a Customer Card

Move funds from your master wallet to a customer card.

Transactions

View card spending and transaction history.