Create cards

This guide walks you through the full cards integration. By the end, you will be able to issue virtual cards, securely display card details, manage the card lifecycle, and receive transaction webhooks.

Prerequisites

Before you begin, ensure the following requirements are met:

Your customers must already be onboarded so we can issue the cards agreements session.
The Cards feature is enabled for your account by BVNK.
You have API credentials (see Generate API keys).
Your customers are onboarded and verified by BVNK.
Each customer has a USDC wallet created.
Each customer has a verified phone number and email address on file.
You are PCI-compliant (not PCI-certified).

Create cards agreements signing session

Before issuing a card, the customer must accept the card's terms and conditions, including terms of a card issuer. The customer must already be onboarded and verified by BVNK before you can create a cards agreements session.

UI approval required

Your onboarding and card issuance UI must be approved by BVNK. Submit your designs early in the process to avoid potential rework.

Send the POST platform/v2/agreements request to create an agreement signing session with the Cards use case:

{
    "reference": "4f2a76a4-0954-4999-b555-f9f2bec78c50",
    "useCase": "CARDS"
}

BVNK returns the agreements signing session details. Present the terms to the customer in your UI. After the customer accepts, submit the customer's decision by sending the POST platform/v2/agreements/actions request.

{
    "reference": "4f2a76a4-0954-4999-b555-f9f2bec78c50",
    "actions": [
        {
            "agreementId": "06d119bc-64f6-46b2-aea2-3ff94c4c616f",
            "type": "ACCEPT"
        }
    ]
}

BVNK records consent to the Cards and card issuer's terms. Signed agreements are stored with the customer record.

Jurisdiction check

The customer must reside in a jurisdiction that supports cards and be associated with a BVNK entity authorized to issue cards.

Issue a card

After the customer signs the Cards agreements, issue a virtual card linked to their USDC wallet, by sending the POST /card/v1/cards request.

POST /card/v1/cards
{
    "reference": "card-ref-001",
    "customerId": "4f2a76a4-0954-4999-b555-f9f2bec78c50",
    "ledger": {
        "type": "BVNK_EPC_WALLET",
        "mainWalletId": "acc:22101919109000:wYzI5:0"
    },
    "assetCode": "USDC",
    "limit": {
        "type": "DAILY",
        "value": 5000
    },
    "termsAccepted": true
}

Validation rules:

The customer must have signed the Cards agreements.
Each customer may have only one active card or pending application.
The card must be linked to a USDC wallet.
Customer must have phone number and email on file.

BVNK responds synchronously with a PENDING status:

Response
{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "customerId": "4f2a76a4-0954-4999-b555-f9f2bec78c50",
    "assetCode": "USDC",
    "last4Digits": "4829",
    "status": "PENDING",
    "createdAt": "2026-05-21T10:30:00Z",
    "updatedAt": "2026-05-21T10:30:00Z",
    "expiresAt": "2029-05",
    "ledger": {
        "id": "acc:22101919109000:wYzI5:0",
        "type": "BVNK_EPC_WALLET"
    },
    "limit": {
        "configured": {
            "type": "DAILY",
            "value": 5000
        },
        "available": 5000,
        "nextResetAt": "2026-05-22T00:00:00Z"
    },
    "cardTransactionStats": null,
    "provisionedWallets": [],
    "audit": []
}

Once the card issuer confirms the application, BVNK sends a card application status change webhook with the final status (ACTIVE or DECLINED).

tip

BVNK does not provide the decline reason. If the application is declined, the customer may reapply.

Add card branding

Card branding is managed offline directly with BVNK. Before designing your card artwork, consult BVNK first. Card schemes enforce specific rules on card design and layout.

Submit your card designs to BVNK for approval before production. Scheme rules govern what can appear on the card face.
Once your design is approved, it is applied to all cards automatically. You do not need to pass any branding value in the API call.
The approval process typically takes 2–4 weeks.

View cards

To retrieve a list of all cards, including pending applications, send the GET /card/v1/cards request.

You can filter by card ID or customer reference.

The response includes each card's

Status
Asset currency
Creation, update, and expiry dates
Spend limit (configured value, available balance, and next reset time)
Last four digits
Last authorisation date
Provisioned digital wallets.

Example response
[
    {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "customerId": "4f2a76a4-0954-4999-b555-f9f2bec78c50",
        "assetCode": "USD",
        "last4Digits": "4829",
        "status": "ACTIVE",
        "createdAt": "2026-05-21T10:30:00Z",
        "updatedAt": "2026-05-21T12:00:00Z",
        "expiresAt": "2029-05",
        "ledger": {
            "id": "acc:22101919109000:wYzI5:0",
            "type": "BVNK_EPC_WALLET"
        },
        "limit": {
            "configured": {
                "type": "DAILY",
                "value": 5000
            },
            "available": 4250.00,
            "nextResetAt": "2026-05-22T00:00:00Z"
        },
        "cardTransactionStats": {
            "latestAuthorizedAt": "2026-05-21T14:22:00Z"
        },
        "provisionedWallets": [],
        "audit": [
            {
                "id": "a1b2c3d4-5678-90ab-cdef-111222333444",
                "metadata": {
                    "type": "STATUS_CHANGE",
                    "newStatus": "ACTIVE"
                },
                "reason": "Card activated after provisioning",
                "actorName": "System",
                "actorType": "SYSTEM",
                "createdAt": "2026-05-21T10:35:00Z"
            }
        ]
    }
]

One card per customer

Only one card or application is returned per customer. If a customer has multiple applications, only the most recent record is provided.

View sensitive card details

Sensitive card data (PAN, CVC, expiry, cardholder name) is displayed securely through the BVNK Card Details SDK. The SDK renders data inside a sandboxed iframe — your application never touches the sensitive values.

See Display sensitive card details for the full integration guide.

Receive status webhook

Subscribe to the following webhook events to keep your system synchronized:

Event	Trigger
Card application status change	Card moves from `PENDING` to `ACTIVE` or `DECLINED`
Card status change	Card is frozen, unfrozen, blocked, unblocked, or cancelled
Card transaction created	New authorisation, refund, or credit on the card
Card transaction status update	Transaction status changes (e.g. auth → settled, pending → declined)

For more information about webhook configuration, see Configure webhooks.

Test in sandbox

All Cards APIs are available in the sandbox environment. You can also use the simulation endpoint to generate test transactions:

POST /cards/simulate
{
    "cardId": "123e4567-e89b-12d3-a456-426614174000",
    "scenario": "SIMPLE_SUCCESS"
}

Available scenarios:

Scenario	Description
`SIMPLE_SUCCESS`	Authorised amount equals settled amount
`COMPLEX_SUCCESS`	Authorised amount is greater than settled amount (partial settlement)
`DECLINED`	Transaction is declined

For the detailed API reference, see Simulate Pay-In.

Handle chargebacks

Chargebacks are managed through a manual process:

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

What's next?

Once your cards are live, see Manage Cards for freezing, unfreezing, cancelling cards, and viewing transaction history.

Prerequisites​

Create cards agreements signing session​

Issue a card​

Add card branding​

View cards​

View sensitive card details​

Receive status webhook​

Test in sandbox​

Handle chargebacks​