Generate a VCN for a Purchase

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.

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

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

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.

Overview

Conventions

Guides

Resources

API Reference

MCP

VCN

Generate a VCN for a Purchase

Prerequisites

Step 1: Retrieve your company configuration

Step 2: Create the VCN

Step 4: Verify the transaction

Step 5: Cancel an unused VCN

Update a VCN

​Prerequisites

​Step 1: Retrieve your company configuration

​Step 2: Create the VCN

​Step 3: Share with the supplier

​Step 4: Verify the transaction

​Step 5: Cancel an unused VCN

​Update a VCN

​Related

Prerequisites

Step 1: Retrieve your company configuration

Step 2: Create the VCN

Step 3: Share with the supplier

Step 4: Verify the transaction

Step 5: Cancel an unused VCN

Update a VCN

Related