Manage cards

• Embedded model
• cards
• Stablecoin

This guide covers card lifecycle management and transaction monitoring. You can freeze, unfreeze, and cancel cards, as well as retrieve card and wallet transaction history.

Freeze a card

To temporarily suspend a card, send the PATCH /card/v1/cards/{id}/status request with newStatus: FROZEN. The card must be in ACTIVE status; otherwise, the request is declined.

{
    "newStatus": "FROZEN",
    "reason": "Customer requested freeze — suspected lost device"
}

BVNK freezes the card synchronously and returns a success or failure response. A card status change webhook is also sent.

---

Unfreeze a card

To reactivate a frozen card, send the PATCH /card/v1/cards/{id}/status request with newStatus: ACTIVE.

{
    "newStatus": "ACTIVE",
    "reason": "Customer confirmed device recovered"
}

Rules:

• The card must be in FROZEN status.
• If a BVNK admin has blocked the card, the unfreeze request will be declined.

BVNK unfreezes the card synchronously. A card status change webhook is sent.

---

Cancel a card

To permanently cancel a card, send the DELETE /card/v1/cards/{id} request with a specific card ID.

A card can be cancelled from any status except CANCELLED. This action is irreversible.

BVNK cancels the card synchronously. A card status change webhook is sent.

---

View card transactions

To retrieve all card activity, including authorisations, settlements, declines, and refunds, send the GET /card/v1/card-transactions request:

You can filter by cardId, customerReference, transactionId, or timeframe.

The response contains all transactions across all states (pending, settled, declined), with amounts in USDC and local currency, fees, FX rates, merchant details, authentication method and decline reason, where applicable.

Example response

[
    {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "cardProviderTransactionId": "550e8400e29b41d4a716446655440011",
        "cardId": "123e4567-e89b-12d3-a456-426614174000",
        "cardNumberLast4Digits": "4829",
        "authorizedAmount": 4.50,
        "settledAmount": 4.50,
        "asset": "USD",
        "status": "SETTLED",
        "createdAt": "2026-05-21T14:22:00Z",
        "updatedAt": "2026-05-22T08:00:00Z",
        "metadata": {
            "merchantName": "The Daily Grind",
            "merchantCategory": "Restaurants",
            "merchantCategoryCode": "5812",
            "merchantCity": "Amsterdam",
            "merchantCountry": "NL",
            "localCurrency": "EUR",
            "localAmount": 4.15,
            "usdAmount": 4.50
        },
        "cardProviderTransactionLogs": [],
        "reportData": {
            "interchangeAmount": 0.015,
            "fxFee": 0.05,
            "tokenizationWallet": "Google Pay",
            "isThreeDSecureTransaction": false,
            "isInternationalTransaction": true
        },
        "declineReason": null,
        "formattedDeclineReason": null
    }
]

---

View wallet transactions

When you query transactions for a USDC wallet linked to a card, the response includes card-related ledger movements with:

• A type field identifying card transactions (e.g. CARD_DEBIT, CARD_CREDIT)
• A linkedCardPaymentId that correlates the wallet ledger record to the first card transaction

This allows you to present a unified view of your wallet and card activity to your customers.

For the detailed API reference, see Get wallet transactions.