Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.yativo.com/llms.txt

Use this file to discover all available pages before exploring further.

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. Two webhooks fire: card.withdrawal.settled (customer-scoped) and master_wallet.withdrawal (issuer-scoped)

​
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,
  "message": "Withdrawal submitted. Processing through delay relay (~3 min). Cards are temporarily frozen.",
  "withdrawal_id": "wth_01HXABCDEF...",
  "amount": 1,
  "currency": "USD",
  "status": "processing"
}

​
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. 
{
  "event": "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",
    "timestamp": "2026-05-28T13:10:45.000Z"
  }
}

​
master_wallet.withdrawal

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

​
card.withdrawal.failed

Fires if the on-chain transaction is rejected. 
{
  "event": "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",
    "timestamp": "2026-05-28T13:10:45.000Z"
  }
}

​
customer.balance.updated

Fires when the card balance changes — including after a withdrawal settles. 
{
  "event": "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 four events to handle the full lifecycle: 
{
  "events": [
    "card.withdrawal.settled",
    "card.withdrawal.failed",
    "master_wallet.withdrawal",
    "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.