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

# VCN API: Introduction

> Virtual Card Numbers (VCNs) for controlled B2B purchasing — how they work, key concepts, and authentication.

Clara's VCN API enables companies to generate Virtual Card Numbers (VCNs) for controlled purchases, recurring subscriptions, and digital transactions. All charges made to a VCN are automatically debited from its associated Real Card Number (RCN).

## Key Concepts

| Concept                       | Description                                                                                                                                  |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **RCN (Real Card Number)**    | The actual funding card linked to your company. Required to generate VCNs.                                                                   |
| **VCN (Virtual Card Number)** | A virtual card generated from an RCN. Has its own PAN, CVV, and expiry. Intended for a specific purchase or supplier.                        |
| **Template**                  | Defines the rules and parameters for a VCN — spending limits, expiration, allowed merchant categories, currency controls, and custom fields. |
| **Supplier**                  | The vendor or merchant associated with a purchase.                                                                                           |
| **Purchase**                  | A VCN creation request tied to an RCN, template, and supplier. Identified by `purchaseId`.                                                   |

## How VCNs Work

1. **Configure**: An RCN and one or more templates are set up during the VCN onboarding process.
2. **Retrieve**: Call `GET /api/v1/vcn` to get available RCNs, templates, and suppliers for your company.
3. **Create**: Call `POST /api/v1/vcn/submit` with a template, RCN, and supplier to generate a VCN.
4. **Use**: The VCN (PAN + CVV + expiry) is used for the purchase. Charges flow back to the RCN.
5. **Update or Cancel**: Adjust limits with `POST /api/v1/vcn/{purchaseId}/update` or void with `POST /api/v1/vcn/cancel`.
6. **Reconcile**: Generate and retrieve reports via `POST/GET /api/v1/vcn/report`.

## Authentication and Security

The VCN API uses the same dual-layer authentication as all Clara APIs.

| Component             | Protocol      | Purpose                                                                             |
| --------------------- | ------------- | ----------------------------------------------------------------------------------- |
| **Mutual TLS (mTLS)** | TLS handshake | Verifies the identity of both the client and the API gateway at the transport layer |
| **OAuth 2.0 + JWT**   | Authorization | Client authenticates with the Auth Server and receives a JWT Bearer token           |

**Token Request:**

```bash theme={null}
curl --location --request POST 'https://public-api.mx.clara.com/oauth/token' \
  --header 'Authorization: Basic base64(CLIENT_ID:CLIENT_SECRET)'
```

## Endpoint Overview

| Method | Endpoint                          | Description                                       |
| ------ | --------------------------------- | ------------------------------------------------- |
| `GET`  | `/api/v1/vcn`                     | Retrieve available RCNs, templates, and suppliers |
| `POST` | `/api/v1/vcn/submit`              | Generate a new VCN for a controlled purchase      |
| `POST` | `/api/v1/vcn/{purchaseId}/update` | Update VCN parameters (limit, supplier)           |
| `POST` | `/api/v1/vcn/cancel`              | Cancel/void one or more VCNs                      |
| `POST` | `/api/v1/vcn/report`              | Trigger a reconciliation report                   |
| `GET`  | `/api/v1/vcn/report`              | Poll for report results                           |
| `GET`  | `/api/v1/vcn/{purchaseId}`        | Retrieve purchase details by ID                   |

## Sandbox

A sandbox environment is available for testing:

* `GET /api-test/v1/vcn/{path}` — Sandbox read operations
* `POST /api-test/v1/vcn/{path}` — Sandbox write operations

Contact your Clara integration support team for sandbox credentials.