Skip to main content
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

ConceptDescription
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.
TemplateDefines the rules and parameters for a VCN — spending limits, expiration, allowed merchant categories, currency controls, and custom fields.
SupplierThe vendor or merchant associated with a purchase.
PurchaseA 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.
ComponentProtocolPurpose
Mutual TLS (mTLS)TLS handshakeVerifies the identity of both the client and the API gateway at the transport layer
OAuth 2.0 + JWTAuthorizationClient authenticates with the Auth Server and receives a JWT Bearer token
Token Request: 
curl --location --request POST 'https://public-api.mx.clara.com/oauth/token' \
  --header 'Authorization: Basic base64(CLIENT_ID:CLIENT_SECRET)'

​
Endpoint Overview

MethodEndpointDescription
GET/api/v1/vcnRetrieve available RCNs, templates, and suppliers
POST/api/v1/vcn/submitGenerate a new VCN for a controlled purchase
POST/api/v1/vcn/{purchaseId}/updateUpdate VCN parameters (limit, supplier)
POST/api/v1/vcn/cancelCancel/void one or more VCNs
POST/api/v1/vcn/reportTrigger a reconciliation report
GET/api/v1/vcn/reportPoll 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.