Manage cards

• Cards
• Embedded model
• Stablecoin

Beta

Cards is in beta and may change as we continue to improve it. Please review the documentation and endpoints carefully, test everything in the sandbox, and reach out to the Solutions team if you need help.

This guide explains how to manage the card lifecycle and monitor transactions. You can freeze, unfreeze, or cancel cards, and retrieve transaction histories for cards and wallets.

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 due to suspected lost device"
}

BVNK freezes the card synchronously and returns a success or failure response. A card status change webhook is 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 is 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 the card ID.

You can cancel a card from any status except CANCELLED. This action cannot be undone.

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/transactions request.

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

The response includes all transactions in any state (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": "USDC",
        "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
        },
        "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 the following details:

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

---

Handle chargebacks

Chargebacks are handled through a manual process:

1. A customer disputes a transaction in your application.
2. You contact BVNK with the dispute request via email.
3. BVNK reviews and submits the dispute to the card issuer if valid.
4. The card issuer submits the dispute to the card network.
5. Upon resolution, BVNK notifies you of the outcome and sends a card credit webhook if funds are returned.

---