> ## 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 Lifecycle Walkthrough

> Step-by-step guide to creating, using, updating, canceling, and reconciling VCNs — with full request and response examples.

## Overview

A VCN goes through a predictable lifecycle: retrieve company configuration → create the VCN → optionally update it → cancel if unused → reconcile at month end. Each step maps to a specific endpoint.

***

## Step 1: Retrieve Company Configuration

Before creating a VCN, fetch the available RCNs, templates, and suppliers for your company. The IDs returned here are required in subsequent requests.

**Endpoint:** `GET /api/v1/vcn`

### Query Parameters

| Parameter       | Type   | Values                                                                                                                                                                       |
| --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `companyDetail` | string | `ALL` — returns rcns, suppliers, and templates<br />`RCN` — returns only real card numbers<br />`TEMPLATE` — returns only templates<br />`SUPPLIER` — returns only suppliers |

### Example Request

```bash theme={null}
GET /api/v1/vcn?companyDetail=ALL
```

### Example Response (`CompanyResponseVO`)

```json theme={null}
{
  "rcns": [
    {
      "id": 38105,
      "alias": "Clara Card Black"
    }
  ],
  "suppliers": [
    {
      "id": 47401,
      "name": "Clara Supplier"
    }
  ],
  "templates": [
    {
      "id": 50631,
      "name": "Clara Hotels",
      "description": "Group for hotels",
      "type": "PC",
      "icmpEnabled": false,
      "purchaseTypes": [
        {
          "mcc": "3501",
          "description": "HOLIDAY INNS"
        }
      ],
      "rules": [
        {
          "name": null,
          "type": null,
          "controls": [
            { "code": "VA", "description": "Validity" },
            { "code": "VL", "description": "Velocity" }
          ]
        }
      ],
      "customFields": [
        {
          "name": "Purchase Type",
          "maxLength": 69,
          "displayType": "Text",
          "dataType": "Alphanumeric",
          "required": "Y"
        }
      ]
    }
  ]
}
```

***

## Step 2: Create a Virtual Card

Generate a new VCN for a controlled purchase. The VCN (PAN + AVV + expiry) is returned immediately and is ready for use.

**Endpoint:** `POST /api/v1/vcn/submit`

### Request Body (`VCNRequestVO`)

| Field          | Type    | Required    | Notes                                                                |
| -------------- | ------- | ----------- | -------------------------------------------------------------------- |
| `rcnId`        | integer | Yes         | Real Card Number ID — query from `GET /api/v1/vcn`                   |
| `templateId`   | integer | Yes         | Template ID — query from `GET /api/v1/vcn`                           |
| `supplierId`   | integer | Yes         | Supplier ID — query from `GET /api/v1/vcn`                           |
| `description`  | string  | Yes         | Description of the purchase                                          |
| `validFor`     | integer | No          | VCN validity in months                                               |
| `customFields` | list    | Conditional | Required if the template has required custom fields                  |
| `rule`         | object  | No          | Spending controls for this VCN (see [Control Types](#control-types)) |

### Control Types

Controls inside `rule` must match the controls configured in the template. Sending an unsupported control returns `400 Invalid rule control {}`.

| Code | Control                   |
| ---- | ------------------------- |
| `AR` | Amount range control      |
| `CU` | Curfew control            |
| `GE` | Geography control         |
| `MI` | Merchant ID control       |
| `TD` | Time of day control       |
| `TL` | Transaction limit control |
| `VA` | Validity period control   |
| `VG` | Aging velocity control    |
| `VL` | Velocity control          |

### Example Request Body

```json theme={null}
{
  "rcnId": 13800,
  "validFor": 12,
  "description": "My Purchase Request",
  "templateId": 21680,
  "supplierId": 14100,
  "customFields": [
    {
      "name": "Invoice Number",
      "value": "1231456"
    }
  ],
  "rule": {
    "name": "My rule",
    "type": "A",
    "velocityControl": [
      {
        "maxTrans": 1,
        "cumulativeLimit": 500.10,
        "period": "C",
        "currencyType": "B",
        "currencyCode": "840"
      }
    ],
    "agingVelocityControl": {
      "authorizationHoldDays": 10,
      "cumulativeLimit": 1,
      "timeZone": "Europe/London",
      "negate": false,
      "availableBalance": 651.10,
      "currencyType": "B",
      "currencyCode": "840"
    },
    "validityPeriodControl": {
      "from": "20150504",
      "to": "20150531",
      "timeZone": "Europe/Luxembourg",
      "strictPreAuthCheck": false,
      "negate": false
    },
    "transactionLimitControl": {
      "amount": 1000.55,
      "negate": false
    },
    "timeOfDayControl": {
      "days": [
        {
          "day": "Tue",
          "fromTime": "0800",
          "toTime": "1300"
        }
      ],
      "negate": true,
      "timeZone": "Europe/Luxembourg"
    },
    "merchantIdControl": {
      "negate": false
    },
    "geographyControl": {
      "countryCode": ["AFG", "USA"],
      "negate": true
    },
    "curfewControl": {
      "fromTime": "0830",
      "toTime": "1800",
      "timeZone": "Europe/Luxembourg",
      "negate": false,
      "daysOfWeek": ["MON", "WED"]
    },
    "amountRangeControl": [
      {
        "minAmount": 300,
        "maxAmount": 500,
        "strictPreAuthCheck": false,
        "negate": false,
        "currencyType": "B",
        "currencyCode": "840"
      }
    ]
  }
}
```

### Example Response (`VCNResponseVO`)

```json theme={null}
{
  "id": 12345678,
  "status": "ACTIVE",
  "vcn": {
    "id": 0,
    "pan": "546920XXXXXX1234",
    "avv": "664",
    "status": "ACTIVE",
    "expiry": "12/28"
  },
  "merchants": {
    "merchantId": "1234",
    "acquirerId": 0
  }
}
```

Save the `id` (this is the `purchaseId`) — it is required for update, cancel, and lookup operations.

***

## Step 3: Update a Virtual Card

Adjust VCN parameters such as the spending limit or supplier. The entire `VCNRequestVO` must be sent, including all unchanged fields.

**Endpoint:** `POST /api/v1/vcn/{purchaseId}/update`

### Path Parameter

| Parameter    | Type    | Description                        |
| ------------ | ------- | ---------------------------------- |
| `purchaseId` | integer | ID returned in the submit response |

The request body and response follow the same structure as [Step 2](#step-2-create-a-virtual-card). All fields must be included even if not changing.

***

## Step 4: Cancel a VCN

Void one or more purchases that were created in error or are no longer needed. Supports batch cancellation.

**Endpoint:** `POST /api/v1/vcn/cancel`

### Example Request Body (`CancelPurchaseRequestVO`)

```json theme={null}
{
  "purchasesIds": [123456, 798465, 321546]
}
```

### Example Response (`CancelPurchaseResponseVO`)

```json theme={null}
{
  "purchases": [
    {
      "id": 564565,
      "cancelled": true,
      "errorMessage": "Error when cancelling"
    }
  ]
}
```

Each purchase in the response includes a `cancelled` boolean and an `errorMessage` if the cancellation failed.

***

## Step 5: Reconciliation Reports (Polling Flow)

Reconciliation is a two-step polling flow: trigger the report, then poll for results.

### 5A. Create Report (Trigger)

**Endpoint:** `POST /api/v1/vcn/report`

| Field             | Type   | Notes                                                                   |
| ----------------- | ------ | ----------------------------------------------------------------------- |
| `fromDate`        | string | Start date — format `YYYYMMDD`                                          |
| `toDate`          | string | End date — format `YYYYMMDD`                                            |
| `fromTime`        | string | Start time — format `HHMM` (optional)                                   |
| `toTime`          | string | End time — format `HHMM` (optional)                                     |
| `timeZone`        | string | IANA time zone (e.g., `Europe/Luxembourg`)                              |
| `reportType`      | string | Enum: `Authorization` \| `Clearing` \| `ClearingExceptions`             |
| `transactionType` | string | Mastercard transaction type enum. Not required for `ClearingExceptions` |
| `pan`             | string | Filter to a specific VCN PAN (optional)                                 |

#### Example Request Body

```json theme={null}
{
  "fromDate": "20220822",
  "toDate": "20220822",
  "fromTime": "1415",
  "toTime": "1515",
  "timeZone": "Europe/Luxembourg",
  "transactionType": "ALL",
  "pan": "5582351302749637",
  "reportType": "Authorization"
}
```

#### Example Response (`ReportResponseVO`)

```json theme={null}
{
  "reportId": 1055,
  "systemMessage": "Create VCN authorizations report has been submitted"
}
```

Save the `reportId` to poll for results.

***

### 5B. Get Report Data (Poll)

Poll until `status` is `Completed`. The `from`/`to` range controls pagination — the difference must not exceed 100.

**Endpoint:** `GET /api/v1/vcn/report`

| Parameter  | Type       | Description                             |
| ---------- | ---------- | --------------------------------------- |
| `reportId` | BigInteger | ID from the create response             |
| `from`     | BigInteger | Start index for pagination              |
| `to`       | BigInteger | End index (max diff of 100 from `from`) |

#### Example Request

```
GET /api/v1/vcn/report?reportId=12345&from=0&to=50
```

#### Example Response (`ReportVO`)

The `transactions` array is populated for `Authorization` and `Clearing` reports. The `accountSummary` array is populated for `ClearingExceptions` reports.

```json theme={null}
{
  "hasMore": false,
  "from": 0,
  "to": 99,
  "status": "Completed",
  "transactions": [
    {
      "purchaseRequestId": 100,
      "purchaseRequestStatus": "Approved",
      "realCardAlias": "20230510",
      "realCardNumber": "XXXX XXXX XXXX 3847",
      "virtualCardNumber": "XXXX XXXX XXXX 1132",
      "vcnExpiry": "2505",
      "requestorName": "AnitaCPA2",
      "billingAmount": 11.00,
      "billingCurrencyCode": "GBP",
      "billingCurrencyCodeDescription": "POUND STERLING",
      "merchantAmount": 11.00,
      "merchantCurrencyCode": "USD",
      "merchantCurrencyCodeDescription": "U.S. DOLLAR",
      "clearingType": "Debit",
      "txnExchangeRate": "1",
      "txnDateTime": "0510",
      "txnDateTimeWithTime": "1028T094103.000Z",
      "settlementDate": "20150610",
      "txnType": "FirstPresentment",
      "txnSubType": "Regular",
      "txnEnvironment": "ECOM",
      "issuerResponse": "Approved or completed successfully",
      "avsResponseCode": "1300",
      "inControlResponse": "Approval",
      "approvalCode": "111111",
      "mcc": "3000",
      "mccDescription": "UNITED AIRLINES",
      "merchantId": "111111999674",
      "merchantTerminalId": "98123456",
      "merchantName": "PaulsPikes",
      "additionalMerchantName": "Smith",
      "merchantStreetAddress": "STREET",
      "merchantCity": "CITY",
      "merchantState": "MO",
      "merchantPostalCode": "462354",
      "merchantCountryCode": "008",
      "merchantCountry": "UNITED STATES",
      "acquirerICA": "111111",
      "processorICA": "322222",
      "terminalId": "98123456",
      "settled": "Settled",
      "incontrolIssuerId": "2",
      "companyName": "AnitaCompany1",
      "companyNumber": "146781",
      "acquirerReferenceData": "003822995070071000114810",
      "messageType": "1240",
      "functionCode": "200",
      "messageReasonCode": "1401",
      "settlementAmount": 100.50,
      "settlementCurrencyCode": "826",
      "settlementCurrencyDescription": "POUND STERLING",
      "icmpUserFirstName": "first",
      "icmpUserLastName": "last",
      "icmpUserEmail": "first.last@domain.com",
      "icmpUserPhoneCountryCode": "11",
      "icmpUserMobileNumber": "111111111",
      "tokenPan": "XXXX XXXX XXXX 1234"
    }
  ],
  "accountSummary": [
    {
      "cpnPan": "5582351753081639",
      "currencyCode": "840",
      "cpnType": "MA",
      "lastAuthDate": "20230510T072239.00Z",
      "settledUsage": 1,
      "settledAmount": 10,
      "lastSettledDate": "20230510T072239.00Z",
      "preAuthUsage": 1,
      "createdDate": "20230510",
      "updatedDate": "20230510",
      "createdBy": "AnitaCPA2",
      "issuerId": "3245623",
      "cpnState": "Approved",
      "authAmount": 10,
      "authUsage": 1,
      "corporateId": "9764",
      "purchaseId": 5274604,
      "cumulativeLimit": 100,
      "periodType": "C",
      "company": "ICCP Company",
      "supplier": "ICCP Supplier",
      "spendVLimit": 80,
      "cdf1Label": "Purchase Type",
      "cdf1Value": "P0000167671Airlines",
      "icmpUserFirstName": "first",
      "icmpUserLastName": "last",
      "icmpUserEmail": "first.last@domain.com",
      "tokenPan": "XXXX XXXX XXXX 1234"
    }
  ]
}
```

***

## Retrieve Purchase by ID

Fetch the full details of a specific VCN purchase, including the VCN itself and all applied rules.

**Endpoint:** `GET /api/v1/vcn/{purchaseId}`

| Parameter    | Type       | Description        |
| ------------ | ---------- | ------------------ |
| `purchaseId` | BigInteger | ID of the purchase |

### Example Response (`PurchaseResponseVO`)

```json theme={null}
{
  "id": 165464,
  "status": "Approved",
  "merchantId": 5465464,
  "acquirerId": 5441324,
  "rcnId": 123123,
  "supplierId": 32134,
  "templateId": 132134,
  "validFor": 12,
  "description": "My Purchase Request",
  "customFields": [
    {
      "name": "Invoice Number",
      "value": "1231456"
    }
  ],
  "vcn": {
    "id": 4651231,
    "pan": "5412753456999975",
    "expiry": "2601",
    "avv": "664",
    "status": "S"
  },
  "rule": {
    "name": "My rule",
    "type": "A",
    "velocityControl": [
      {
        "maxTrans": 1,
        "cumulativeLimit": 500.10,
        "period": "C",
        "currencyType": "B",
        "currencyCode": "840"
      }
    ]
  }
}
```