> ## 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
> Pull funds from a customer's card account back to your master wallet — on-chain USDC settlement in approximately 3 minutes
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)
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 to withdraw in display units (e.g. `1`, `25.50`). Must be positive and not exceed the card's available balance.
```bash Withdraw $1 theme={null}
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
}'
```
```json 200 Initiated theme={null}
{
"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"
}
}
```
```json 400 Insufficient balance theme={null}
{
"success": false,
"error": "INSUFFICIENT_BALANCE",
"message": "Available balance is $0.50. Requested $1.00."
}
```
```json 422 Ambiguous customer theme={null}
{
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"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:
```json theme={null}
{
"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.
***
Move funds from your master wallet to a customer card.
View card spending and transaction history.