> ## Documentation Index
> Fetch the complete documentation index at: https://developer.cartevo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Withdraw from Card

> Move USD from a card back to your company USD wallet.

## Overview

`POST /cards/{id}/withdraw` moves USD from the specified card back to your company's USD wallet. The card balance decreases immediately on success; the withdrawn funds are credited to the wallet.

## When to use it

* Reclaim leftover funds before terminating a card.
* Move funds between cards by withdrawing from one and funding another.
* Recover funds when a customer returns an unused per-diem allowance.

For the reverse direction (wallet → card), see [`POST /cards/{id}/fund`](/api-reference/endpoint/post-card-fund).

## Prerequisites

* Card status must be `ACTIVE` or `FROZEN` (you can withdraw from a frozen card to recover funds before terminating it).
* The card must belong to your company.
* The card balance must be ≥ `amount`.

## Request

### Headers

| Name            | Required | Description             |
| --------------- | -------- | ----------------------- |
| `Authorization` | Yes      | `Bearer <access_token>` |
| `Content-Type`  | Yes      | `application/json`      |

### Path parameters

| Name | Type   | Description     |
| ---- | ------ | --------------- |
| `id` | string | Card ID (UUID). |

### Body

| Field    | Type   | Required | Constraints | Description                                                                |
| -------- | ------ | -------- | ----------- | -------------------------------------------------------------------------- |
| `amount` | number | Yes      | ≥ `1`. USD. | Amount to withdraw from the card to the company USD wallet. Minimum 1 USD. |

```json theme={null}
{
  "amount": 30
}
```

## Response

### 200 — Success

```json theme={null}
{
  "success": true,
  "statusCode": 200,
  "message": "Card withdrawal successful",
  "data": {
    "transaction_id": "txn_nop678qrs234tuv901wxy567",
    "card_id": "550e8400-e29b-41d4-a716-446655440000",
    "amount": 30.0,
    "currency": "USD",
    "fee_amount": 0.0,
    "card_balance_before": 150.0,
    "card_balance_after": 120.0
  }
}
```

| Field                 | Type   | Description                                                 |
| --------------------- | ------ | ----------------------------------------------------------- |
| `transaction_id`      | string | Cartevo transaction ID. Use for support and reconciliation. |
| `card_id`             | string | The card the funds came from.                               |
| `amount`              | number | Net amount credited back to the USD wallet.                 |
| `currency`            | string | Always `USD`.                                               |
| `fee_amount`          | number | Withdrawal fee charged (typically `0`).                     |
| `card_balance_before` | number | Card balance before this call.                              |
| `card_balance_after`  | number | Card balance after this call.                               |

### Error responses

| Status | `message` example                      | Trigger                                        | Recommended action                                                                           |
| ------ | -------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `400`  | `"Insufficient card balance"`          | Card balance \< `amount`.                      | Fetch the current balance and adjust.                                                        |
| `400`  | `"Amount must be at least 1"`          | `amount` \< `1`.                               | Fix the request.                                                                             |
| `400`  | `"Card terminated"`                    | Card status is `TERMINATED`.                   | Cannot withdraw — terminated cards have already had their balance refunded.                  |
| `404`  | `"Card not found"`                     | `id` is invalid or belongs to another company. | Verify the card ID.                                                                          |
| `5xx`  | `"Withdrawal temporarily unavailable"` | Upstream issuer transient error.               | Retry with backoff. The webhook `card.withdraw.failed` is also emitted on permanent failure. |

## Webhooks fired

* [`card.withdraw`](/api-reference/endpoint/webhook#card-withdraw) — on success.
* [`card.withdraw.failed`](/api-reference/endpoint/webhook#card-withdraw-failed) — on permanent failure (e.g. upstream rejected).
* [`transaction.withdrawal.completed`](/api-reference/endpoint/webhook#transaction-withdrawal-completed) — once the transaction settles.

## Code examples

```bash cURL theme={null}
curl -X POST https://api.cartevo.co/api/v1/cards/550e8400-e29b-41d4-a716-446655440000/withdraw \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount": 30}'
```

```js Node.js (axios) theme={null}
await axios.post(
  `https://api.cartevo.co/api/v1/cards/${cardId}/withdraw`,
  { amount: 30 },
  { headers: { Authorization: `Bearer ${token}` } }
);
```

## Related

* [`POST /cards/{id}/fund`](/api-reference/endpoint/post-card-fund) — the reverse direction.
* [`POST /cards/{id}/terminate`](/api-reference/endpoint/post-terminate-card) — terminating a card auto-refunds the remaining balance, so you don't need to withdraw first.


## OpenAPI

````yaml POST /cards/{id}/withdraw
openapi: 3.1.0
info:
  title: Cartevo API
  description: Essential endpoints for wallets, transactions, customers and conversion.
  version: 1.0.0
servers:
  - url: https://api.cartevo.co/api/v1
security:
  - bearerAuth: []
paths:
  /cards/{id}/withdraw:
    post:
      summary: Withdraw from a card
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: number
                  minimum: 1
                  description: >-
                    Amount in USD to withdraw from the card to the company USD
                    wallet. Minimum 1 USD.
              required:
                - amount
      responses:
        '200':
          description: Withdrawal successful
        '400':
          description: Bad request - insufficient balance
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````