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

# Terminate Card

> Permanently disable a card. Any remaining balance is automatically refunded to your company USD wallet. Irreversible.

## Overview

`POST /cards/{id}/terminate` permanently disables a card. The action is **irreversible** — a terminated card cannot be reactivated. Any remaining balance on the card is automatically refunded to your company's USD wallet as part of the same call.

## When to use it

* A customer reports their card details are compromised.
* An employee leaves and their per-diem card needs to be killed.
* Cleaning up unused cards to free up your card-slot allowance.

For a temporary disable that preserves the card and balance, use [`PUT /cards/{id}/freeze`](/api-reference/endpoint/put-card-freeze) instead.

## Prerequisites

* The card must belong to your company.
* Card status must not already be `TERMINATED`.

## Request

### Headers

| Name            | Required | Description             |
| --------------- | -------- | ----------------------- |
| `Authorization` | Yes      | `Bearer <access_token>` |

### Path parameters

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

### Query parameters

| Name              | Type    | Default | Description                                                                                                                                                                                    |
| ----------------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `freezeOnFailure` | boolean | `false` | If `true` and termination fails upstream, the card is left in `FROZEN` state instead of `ACTIVE`, so it cannot be used while you investigate. Recommended for security-sensitive terminations. |

### Body

None.

## Response

### 201 — Termination successful

```json theme={null}
{
  "success": true,
  "statusCode": 201,
  "message": "Card terminated successfully",
  "data": {
    "card_id": "550e8400-e29b-41d4-a716-446655440000",
    "card_status": "TERMINATED",
    "refund_processed": true,
    "balance_before_termination": 50.0
  }
}
```

| Field                        | Type    | Description                                                                                                                             |
| ---------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `card_id`                    | string  | The terminated card.                                                                                                                    |
| `card_status`                | string  | Always `"TERMINATED"`.                                                                                                                  |
| `refund_processed`           | boolean | `true` if the remaining balance was successfully refunded to the company USD wallet, `false` otherwise (rare; investigate via support). |
| `balance_before_termination` | number  | Card balance immediately before termination. `0` for a card with no funds.                                                              |

### Error responses

| Status | `message` example                       | Trigger                                        | Recommended action                                                           |
| ------ | --------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------- |
| `400`  | `"Card already terminated"`             | The card status is already `TERMINATED`.       | No action — the card is already permanently disabled.                        |
| `404`  | `"Card not found"`                      | `id` is invalid or belongs to another company. | Verify the card ID.                                                          |
| `5xx`  | `"Termination temporarily unavailable"` | Upstream issuer transient error.               | Retry with `freezeOnFailure=true` so the card cannot be used while you wait. |

## Important notes

* Termination is **irreversible**. Once a card is `TERMINATED`, you cannot unfreeze, fund, or otherwise reactivate it.
* The remaining balance is **automatically** refunded to the company USD wallet — you do **not** need to call [`POST /cards/{id}/withdraw`](/api-reference/endpoint/post-card-withdraw) first.
* Webhook delivery failures do **not** roll back the termination. The card is terminated even if your webhook receiver is down.

## Webhooks fired

* [`card.terminated`](/api-reference/endpoint/webhook#card-terminated) — emitted with the refund amount and timestamp.
* [`transaction.terminated`](/api-reference/endpoint/webhook#transaction-terminated) — for the termination transaction record.

## Code examples

```bash cURL theme={null}
curl -X POST https://api.cartevo.co/api/v1/cards/550e8400-e29b-41d4-a716-446655440000/terminate \
  -H "Authorization: Bearer $TOKEN"
```

```js Node.js (axios) theme={null}
const { data } = await axios.post(
  `https://api.cartevo.co/api/v1/cards/${cardId}/terminate`,
  null,
  {
    headers: { Authorization: `Bearer ${token}` },
    params: { freezeOnFailure: true },
  }
);
console.log(`Refunded ${data.data.balance_before_termination} USD to wallet`);
```

## Related

* [`PUT /cards/{id}/freeze`](/api-reference/endpoint/put-card-freeze) — temporary, reversible disable.
* [`GET /cards/{id}`](/api-reference/endpoint/get-card-by-id) — verify the new status.
* [Webhooks → card.terminated](/api-reference/endpoint/webhook#card-terminated)


## OpenAPI

````yaml POST /cards/{id}/terminate
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}/terminate:
    post:
      summary: Terminate a card
      description: >-
        Permanently terminate a card. The card balance will be refunded to the
        company's USD wallet. Once terminated, the card cannot be used again.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Card ID to terminate
      responses:
        '201':
          description: >-
            Card terminated successfully. Balance refunded to company USD
            wallet.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  statusCode:
                    type: integer
                    example: 201
                  message:
                    type: string
                    example: Card terminated successfully
                  data:
                    type: object
                    properties:
                      card_id:
                        type: string
                        format: uuid
                      card_status:
                        type: string
                        example: TERMINATED
                      refund_processed:
                        type: boolean
                        example: 'true'
                      balance_before_termination:
                        type: number
                        example: 6
        '400':
          description: Bad request - card is already terminated or invalid card
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  statusCode:
                    type: integer
                    example: 400
                  message:
                    type: string
                    example: Card is already terminated
                  error:
                    type: string
                    example: Bad Request
        '404':
          description: Card not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  statusCode:
                    type: integer
                    example: 404
                  message:
                    type: string
                    example: Card not found
                  error:
                    type: string
                    example: Not Found
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````