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

​
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. 
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: 
{
  "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. 
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: 
{
  "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.
FieldDescription
rcnIdThe parent card number this VCN draws from
supplierIdRestricts the VCN to charges from this supplier only
templateIdApplies MCC and rule restrictions defined in the template
amountMaximum amount the VCN can be charged
validFrom / validToThe window during which the VCN is active
referenceYour internal reference (PO number, project code, etc.)
VCN card details are only returned once at creation time. Store cardNumber, cvv, and expirationDate securely — they are not retrievable again via the API.

​
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: 
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. 
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: 
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.