Card Withdrawal

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:

You call POST /api/card-issuer/withdraw-from-card with a customer identifier and amount
Yativo fetches EIP-712 typed data from the card network, signs it server-side using the card’s EOA, and submits the transaction
A delay relay holds the transaction for ~3 minutes — the card is temporarily frozen during this window
Once the delay elapses the transfer executes on-chain and your master wallet is credited
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)

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

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"
  }
}

{
  "success": false,
  "error": "INSUFFICIENT_BALANCE",
  "message": "Available balance is $0.50. Requested $1.00."
}

{
  "success": false,
  "error": "AMBIGUOUS_CUSTOMER",
  "message": "Multiple cards found for this email. Use yativo_card_id instead."
}

Timing

Stage	Time
API response (withdrawal accepted)	Immediate
Card frozen (delay relay active)	Immediately after submission
On-chain settlement	~3 minutes after submission
Card unfrozen	After settlement confirms
Webhooks delivered	After 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.

Overview

Wallets & Assets

Transactions

Yativo Card

Payment Gateway

Agentic Wallets

IBAN

Automation

Compliance

B2B

Developer Tools

Tutorials

SDKs

Browser Extensions (Coming Soon)

Sandbox

Card Withdrawal

How it works

API

Timing

Webhooks

`card.withdrawal.settled`

`master_wallet.withdrawal`

`master_wallet.deposit`

`card.withdrawal.failed`

`customer.balance.updated`

Notes

Fund a Customer Card

Transactions

​How it works

​API

​Timing

​Webhooks

​card.withdrawal.settled

​master_wallet.withdrawal

​master_wallet.deposit

​card.withdrawal.failed

​customer.balance.updated

​Notes

Fund a Customer Card

Transactions

How it works

API

Timing

Webhooks

`card.withdrawal.settled`

`master_wallet.withdrawal`

`master_wallet.deposit`

`card.withdrawal.failed`

`customer.balance.updated`

Notes