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

# Generate a VCN for a Purchase

> Create a Virtual Card Number locked to a supplier and amount, use it to pay, and reconcile the resulting transaction.

Virtual Card Numbers (VCNs) are single-use or limited-use card numbers generated for a specific supplier and spending limit. They're ideal for B2B payments where you want spending controls without issuing a reusable corporate card.

This guide walks through creating a VCN, sharing it with a supplier, verifying the resulting transaction, and canceling unused VCNs.

## Prerequisites

* VCN feature enabled on your account. Contact your Clara integration team if you don't see it.
* A valid Bearer token and mTLS client certificate. See [Authentication](/authentication).

***

## Step 1: Retrieve your company configuration

Before creating a VCN, fetch the RCNs (real card numbers), suppliers, and templates available to your company. The IDs returned here are required in the create request.

```bash theme={null}
curl --request GET \
  "https://public-api.mx.clara.com/api/v1/vcn?companyDetail=ALL" \
  --header "Authorization: Bearer <TOKEN>" \
  --cert client.crt \
  --key client.key
```

Response:

```json theme={null}
{
  "rcns": [
    { "id": 38105, "alias": "Clara Card Black" }
  ],
  "suppliers": [
    { "id": 47401, "name": "Proveedor Ejemplo S.A." }
  ],
  "templates": [
    {
      "id": 50631,
      "name": "Clara Hotels",
      "description": "Restricted to hotel MCCs",
      "type": "PC",
      "purchaseTypes": [
        { "mcc": "3501", "description": "HOLIDAY INNS" }
      ]
    }
  ]
}
```

Note the `rcns[].id`, `suppliers[].id`, and `templates[].id` you'll use in the next step.

***

## Step 2: Create the VCN

Create a VCN locked to a specific supplier, amount, and validity window.

```bash theme={null}
curl --request POST \
  "https://public-api.mx.clara.com/api/v1/vcn/card" \
  --header "Authorization: Bearer <TOKEN>" \
  --header "Content-Type: application/json" \
  --cert client.crt \
  --key client.key \
  --data '{
    "rcnId": 38105,
    "supplierId": 47401,
    "templateId": 50631,
    "amount": 12500.00,
    "validFrom": "2025-06-01",
    "validTo": "2025-06-30",
    "reference": "PO-2025-00842",
    "customFields": [
      { "name": "Purchase Type", "value": "Hotel Stay" }
    ]
  }'
```

Response:

```json theme={null}
{
  "vcnId": 99201,
  "cardNumber": "5432109876543210",
  "cvv": "927",
  "expirationDate": "06/25",
  "amount": 12500.00,
  "validFrom": "2025-06-01",
  "validTo": "2025-06-30",
  "status": "ACTIVE",
  "reference": "PO-2025-00842"
}
```

The `cardNumber`, `cvv`, and `expirationDate` are the credentials you'll share with the supplier to complete the payment.

| Field                   | Description                                               |
| ----------------------- | --------------------------------------------------------- |
| `rcnId`                 | The parent card number this VCN draws from                |
| `supplierId`            | Restricts the VCN to charges from this supplier only      |
| `templateId`            | Applies MCC and rule restrictions defined in the template |
| `amount`                | Maximum amount the VCN can be charged                     |
| `validFrom` / `validTo` | The window during which the VCN is active                 |
| `reference`             | Your internal reference (PO number, project code, etc.)   |

<Note>
  VCN card details are only returned once at creation time. Store `cardNumber`, `cvv`, and `expirationDate` securely — they are not retrievable again via the API.
</Note>

***

## Step 3: Share with the supplier

Provide the supplier with the card details to process payment:

* **Card number:** `5432109876543210`
* **CVV:** `927`
* **Expiration:** `06/25`
* **Billing amount:** `$12,500.00 MXN`

The VCN is locked to the configured supplier and will be declined anywhere else.

***

## Step 4: Verify the transaction

After the supplier charges the card, confirm the transaction settled by querying your transactions filtered by the card:

```bash theme={null}
curl --request GET \
  "https://public-api.mx.clara.com/api/v3/transactions?operationDateRangeStart=2025-06-01&operationDateRangeEnd=2025-06-30&page=0&size=20" \
  --header "Authorization: Bearer <TOKEN>" \
  --cert client.crt \
  --key client.key
```

Match by `transactionLabel` (merchant name) and `amountValue` to confirm the charge. A settled VCN transaction will have `status.code: "OP"` (AUTHORIZED).

***

## Step 5: Cancel an unused VCN

If the purchase doesn't go through or the VCN was created in error, cancel it to prevent future charges.

```bash theme={null}
curl --request POST \
  "https://public-api.mx.clara.com/api/v1/vcn/card/99201/cancel" \
  --header "Authorization: Bearer <TOKEN>" \
  --cert client.crt \
  --key client.key
```

Canceling a VCN releases the reserved amount back to the parent RCN balance.

***

## Update a VCN

To extend the validity window or adjust the amount before the VCN is charged:

```bash theme={null}
curl --request PUT \
  "https://public-api.mx.clara.com/api/v1/vcn/card/99201" \
  --header "Authorization: Bearer <TOKEN>" \
  --header "Content-Type: application/json" \
  --cert client.crt \
  --key client.key \
  --data '{
    "amount": 14000.00,
    "validTo": "2025-07-15"
  }'
```

Once a VCN has been fully charged, it cannot be updated.

***

## Related

* [VCN Introduction](/vcn/introduction)
* [VCN Lifecycle reference](/vcn/lifecycle)
* [Transactions API reference](/v3/transactions)