> ## 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.

# Fund Card

> Move USD from your company wallet onto a card so the cardholder can spend it.

## Overview

`POST /cards/{id}/fund` moves USD from your company's USD wallet onto the specified card. The card balance increases immediately on success, and the cardholder can use the funds for online payments.

## When to use it

* Top up a card before the cardholder makes a purchase.
* Move savings/payroll/per-diem funds onto an active card.

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

## Prerequisites

* Card status must be `ACTIVE` (not `PENDING`, `FROZEN`, `SUSPENDED`, `TERMINATED`, or `FAILED`).
* The card must belong to your company.
* The company **USD wallet** must have enough balance to cover `amount` plus any funding fees configured on your account.

## 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 move from the USD wallet onto the card. |

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

> **Idempotency:** This endpoint does not currently accept an idempotency key. To avoid double-funding on network retries, store the resulting `transaction_id` after the first call returns and check before retrying.

## Response

### 200 — Success

```json theme={null}
{
  "success": true,
  "statusCode": 200,
  "message": "Card funded successfully",
  "data": {
    "transaction_id": "txn_5b7c9d2e4f6a8b1c3d5e7f9a",
    "card_id": "550e8400-e29b-41d4-a716-446655440000",
    "amount": 50.0,
    "currency": "USD",
    "fee_amount": 0.0,
    "card_balance_before": 100.0,
    "card_balance_after": 150.0
  }
}
```

| Field                 | Type   | Description                                                 |
| --------------------- | ------ | ----------------------------------------------------------- |
| `transaction_id`      | string | Cartevo transaction ID. Use for support and reconciliation. |
| `card_id`             | string | The funded card.                                            |
| `amount`              | number | Net amount added to the card.                               |
| `currency`            | string | Always `USD`.                                               |
| `fee_amount`          | number | Funding fee charged to the wallet (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 wallet balance"`     | USD wallet balance \< `amount + fee`.          | Top up the USD wallet, then retry.                                                              |
| `400`  | `"Card not active"`                 | Card status is not `ACTIVE`.                   | Unfreeze the card or check it is not terminated.                                                |
| `400`  | `"Amount must be at least 1"`       | `amount` \< `1`.                               | Fix the request.                                                                                |
| `404`  | `"Card not found"`                  | `id` is invalid or belongs to another company. | Verify the card ID.                                                                             |
| `5xx`  | `"Funding temporarily unavailable"` | Upstream issuer transient error.               | Retry with exponential backoff. Check the card balance before retrying to avoid double-funding. |

## Webhooks fired

* [`card.fund`](/api-reference/endpoint/webhook#card-fund) — emitted on success.
* [`transaction.funding.completed`](/api-reference/endpoint/webhook#transaction-funding-completed) — emitted once the underlying transaction settles.

## Code examples

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

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

```python Python (requests) theme={null}
requests.post(
    f"https://api.cartevo.co/api/v1/cards/{card_id}/fund",
    headers={"Authorization": f"Bearer {token}"},
    json={"amount": 50},
).raise_for_status()
```

## Related

* [`POST /cards/{id}/withdraw`](/api-reference/endpoint/post-card-withdraw) — move funds back to the wallet.
* [`GET /cards/{id}`](/api-reference/endpoint/get-card-by-id) — verify the new balance.
* [`GET /cards/{id}/transactions`](/api-reference/endpoint/get-card-transactions) — see this funding in the card's history.


## OpenAPI

````yaml POST /cards/{id}/fund
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}/fund:
    post:
      summary: Fund 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
              required:
                - amount
      responses:
        '200':
          description: Card funded successfully
        '400':
          description: Bad request - insufficient funds or invalid amount
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````