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

# Card Operations

> Create, fund, freeze, terminate, and replace cards. Retrieve card transactions and handle webhook events for the full card lifecycle.

# Card Operations

## Creating a Card

<Note>
  **Two prerequisites**: your business must have completed KYB verification, and the target cardholder must have `kycStatus: ACCEPTED` before a card can be issued to them.
</Note>

```mermaid theme={null}
sequenceDiagram
    participant App as Your App
    participant FYATU as FYATU API
    participant Provider as Card Provider

    App->>FYATU: POST /cards
    Note over FYATU: Validate cardholder is active
    Note over FYATU: Check business wallet balance
    FYATU->>FYATU: Debit business wallet
    FYATU->>Provider: Create card
    Provider-->>FYATU: Card details
    FYATU-->>App: Card created
    FYATU->>App: Webhook: card.created
```

```javascript theme={null}
POST /cards
{
  "cardholderId": "CH1a2b3c4d5e6f",
  "amount": 100.00,
  "name": "JOHN DOE",        // optional, defaults to cardholder name
  "productId": "MCUSD1"  // optional, defaults to default product
}
```

***

## Fund

Add money to a card from your business wallet:

```javascript theme={null}
POST /cards/{cardId}/fund
{ "amount": 50.00 }
```

* A funding fee (percentage-based) may apply — see [Card Fees](/v3/documentation/concepts/cards/fees)
* Full amount is added to the card balance; fee is debited from your wallet separately
* Can fund a frozen card

## Unload

Withdraw balance from a card back to your wallet:

```javascript theme={null}
POST /cards/{cardId}/unload
{ "amount": 25.00 }
```

* Cannot unload more than the available card balance
* An unloading fee may apply based on your pricing

## Freeze / Unfreeze

Temporarily disable a card without losing its balance:

```javascript theme={null}
POST /cards/{cardId}/freeze    // disable transactions
POST /cards/{cardId}/unfreeze  // re-enable transactions
```

* Frozen cards cannot make purchases but retain their balance
* You can still fund or unload a frozen card

## Terminate

Permanently close a card:

```javascript theme={null}
DELETE /cards/{cardId}
{
  "reason": "Customer requested closure",  // optional
  "reference": "REF123456"                  // optional
}
```

**Balance refund**: any remaining card balance is automatically returned to your business wallet on termination — no fee is charged.

```json theme={null}
{
  "status": true,
  "message": "Card terminated successfully",
  "data": {
    "id": "CRD678E4F2A1B3C9",
    "status": "TERMINATED",
    "reason": "Customer requested closure",
    "refundedBalance": 25.00,
    "terminatedAt": "2026-01-15T10:30:00+00:00",
    "reference": "REF123456"
  }
}
```

* Card cannot be reactivated after termination
* Cardholder can still have other active cards
* Provide a `reason` for record-keeping (visible in webhooks and logs)

## Replace

Issue a replacement card for a terminated card. The balance is transferred automatically:

```javascript theme={null}
POST /cards/{cardId}/replace
```

If the original product has `canIssue: false`, the default product is used as a fallback.

***

## Transactions

### Transaction Types

| Type      | Description                              |
| --------- | ---------------------------------------- |
| `debit`   | Purchase or payment (money leaves card)  |
| `credit`  | Refund or cashback (money added to card) |
| `funding` | Card funding operation                   |
| `unload`  | Card unloading operation                 |

### Transaction Statuses

| Status      | Description          |
| ----------- | -------------------- |
| `PENDING`   | Authorization hold   |
| `COMPLETED` | Successfully settled |
| `DECLINED`  | Transaction rejected |
| `REVERSED`  | Refunded or reversed |

```javascript theme={null}
GET /cards/{cardId}/transactions?page=1
```

***

## Webhook Events

### Card Lifecycle

| Event              | Trigger                                               |
| ------------------ | ----------------------------------------------------- |
| `card.created`     | New card issued                                       |
| `card.funded`      | Funds added                                           |
| `card.unloaded`    | Funds withdrawn                                       |
| `card.frozen`      | Card frozen                                           |
| `card.unfrozen`    | Card unfrozen                                         |
| `card.suspended`   | System suspension (fraud, compliance, or 15 declines) |
| `card.reactivated` | Suspension resolved                                   |
| `card.terminated`  | Card permanently closed                               |

### Transaction Events

| Event                         | Trigger              |
| ----------------------------- | -------------------- |
| `card.transaction.authorized` | Transaction approved |
| `card.transaction.declined`   | Transaction declined |
| `card.transaction.settled`    | Transaction settled  |
| `card.transaction.reversed`   | Transaction reversed |

***

## Error Codes

| Code                        | Cause                                    | Resolution                                            |
| --------------------------- | ---------------------------------------- | ----------------------------------------------------- |
| `INSUFFICIENT_BALANCE`      | Wallet balance too low                   | Top up business wallet                                |
| `INSUFFICIENT_CARD_BALANCE` | Card balance too low                     | Fund the card                                         |
| `CARD_NOT_ACTIVE`           | Card is frozen, suspended, or terminated | Check status; unfreeze if frozen                      |
| `CARD_INACTIVE`             | Physical card not yet activated          | Activate with activation code                         |
| `CARD_SUSPENDED`            | System suspension                        | Fund the card (decline suspension) or contact support |
| `CARD_TERMINATED`           | Card permanently closed                  | Issue a new card                                      |
| `CARDHOLDER_INACTIVE`       | Cardholder not active                    | Activate the cardholder first                         |
| `BUSINESS_KYB_REQUIRED`     | Business verification incomplete         | Complete KYB verification                             |
| `ALREADY_FROZEN`            | Card already frozen                      | No action needed                                      |
| `ALREADY_ACTIVE`            | Card already active                      | No action needed                                      |
| `DECLINE_LIMIT_REACHED`     | 15 insufficient funds declines           | Fund the card to reset and reactivate                 |

***

## Endpoints

* `POST /cards` — [Create card](/v3/api-reference/cards/create)
* `GET /cards` — [List cards](/v3/api-reference/cards/list)
* `GET /cards/{id}` — [Get card details](/v3/api-reference/cards/get)
* `DELETE /cards/{id}` — [Terminate card](/v3/api-reference/cards/delete)
* `POST /cards/{id}/fund` — [Fund card](/v3/api-reference/cards/fund)
* `POST /cards/{id}/unload` — [Unload card](/v3/api-reference/cards/unload)
* `POST /cards/{id}/freeze` — [Freeze card](/v3/api-reference/cards/freeze)
* `POST /cards/{id}/unfreeze` — [Unfreeze card](/v3/api-reference/cards/unfreeze)
* `POST /cards/{id}/replace` — [Replace card](/v3/api-reference/cards/replace)
* `GET /cards/{id}/transactions` — [Get transactions](/v3/api-reference/cards/transactions)