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

# Émettre une carte virtuelle

> Émettez une carte USD et débitez les frais dans la devise du portefeuille.

`idempotency_key` identifie durablement l'émission. Réutilisez la même valeur lors d'une nouvelle tentative.

```bash cURL theme={null}
curl --request POST \
  --url https://api.bizconnectpay.com/api/v1/cards \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "customer_id": "f1bdad5d-bb31-410d-869c-44a28e876ded",
    "wallet_id": "4e969910-8f06-4cd2-b92c-01765472e0e9",
    "idempotency_key": "card-issuance-2026-001",
    "debit_currency": "XAF",
    "initial_balance": "10.00",
    "category": "PERSONAL",
    "grade": "STANDARD"
  }'
```

```json Payload theme={null}
{
  "customer_id": "f1bdad5d-bb31-410d-869c-44a28e876ded",
  "wallet_id": "4e969910-8f06-4cd2-b92c-01765472e0e9",
  "idempotency_key": "card-issuance-2026-001",
  "debit_currency": "XAF",
  "initial_balance": "10.00",
  "category": "PERSONAL",
  "grade": "STANDARD"
}
```

```json 201 Created theme={null}
{
  "success": true,
  "data": {
    "card": {
      "id": "3b2c08e5-d8f2-4886-aad1-88977d455ff8",
      "virtual_card_customer_id": "f1bdad5d-bb31-410d-869c-44a28e876ded",
      "provider_reference": "38537f3f-3948-43af-fd9d-08df17dfe646",
      "issuance_reference": "card-issuance-2026-001",
      "charged_amount": "2000.00000000",
      "charged_currency": "XAF",
      "environment": "LIVE",
      "card_sequence": 1
    },
    "pricing": {
      "card_currency": "USD",
      "card_creation_fee_usd": "3.30",
      "wallet_debit": {
        "amount": "2000.00",
        "currency": "XAF"
      }
    },
    "reservation": {
      "reference": "BCP-RSV-01JACD0R",
      "status": "CAPTURED"
    }
  },
  "meta": {
    "correlation_id": "f9c35025-8a46-4238-982c-f4076c65ca47"
  }
}
```


## OpenAPI

````yaml openapi.json POST /cards
openapi: 3.1.0
info:
  title: BizConnectPay API
  version: 1.0.0
  description: >-
    API serveur-à-serveur pour les collectes, décaissements, transactions,
    remboursements, liens de paiement et cartes virtuelles.
servers:
  - url: https://api.bizconnectpay.com/api/v1
    description: Passerelle API BizConnectPay
security:
  - bearerAuth: []
tags:
  - name: Authentification
  - name: Services
  - name: Collectes
  - name: Transactions
  - name: Décaissements
  - name: Remboursements
  - name: Liens de paiement
  - name: Porteurs de carte
  - name: Cartes virtuelles
paths:
  /cards:
    post:
      tags:
        - Cartes virtuelles
      summary: Émettre une carte virtuelle
      operationId: createVirtualCard
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VirtualCardRequest'
      responses:
        '201':
          $ref: '#/components/responses/Created'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    VirtualCardRequest:
      type: object
      required:
        - customer_id
        - wallet_id
        - idempotency_key
        - debit_currency
      properties:
        customer_id:
          type: string
          format: uuid
        wallet_id:
          type: string
          format: uuid
        idempotency_key:
          type: string
          maxLength: 100
        debit_currency:
          type: string
          minLength: 3
          maxLength: 3
        initial_balance:
          type:
            - number
            - 'null'
          minimum: 0
        category:
          type:
            - string
            - 'null'
          enum:
            - PERSONAL
            - BUSINESS
            - null
        grade:
          type:
            - string
            - 'null'
          enum:
            - STANDARD
            - PREMIUM
            - null
    SuccessEnvelope:
      type: object
      properties:
        success:
          type: boolean
          const: true
        data: {}
        meta:
          $ref: '#/components/schemas/Meta'
    ErrorEnvelope:
      type: object
      properties:
        success:
          type: boolean
          const: false
        data:
          type: object
          properties:
            error:
              type: object
              properties:
                code:
                  type: string
                message:
                  type: string
                details:
                  type:
                    - object
                    - array
        meta:
          $ref: '#/components/schemas/Meta'
    Meta:
      type: object
      properties:
        correlation_id:
          type:
            - string
            - 'null'
          format: uuid
  responses:
    Created:
      description: Ressource créée
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SuccessEnvelope'
    ValidationError:
      description: Payload ou règle métier invalide
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.