VCN Lifecycle Walkthrough

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 `RCN` — returns only real card numbers `TEMPLATE` — returns only templates `SUPPLIER` — returns only suppliers

Example Request

GET /api/v1/vcn?companyDetail=ALL

Example Response (`CompanyResponseVO`)

{
  "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

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

{
  "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`)

{
  "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. 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`)

{
  "purchasesIds": [123456, 798465, 321546]
}

Example Response (`CancelPurchaseResponseVO`)

{
  "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

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

Example Response (`ReportResponseVO`)

{
  "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.

{
  "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`)

{
  "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"
      }
    ]
  }
}

​Overview

​Step 1: Retrieve Company Configuration

​Query Parameters

​Example Request

​Example Response (CompanyResponseVO)

​Step 2: Create a Virtual Card

​Request Body (VCNRequestVO)

​Control Types

​Example Request Body

​Example Response (VCNResponseVO)

​Step 3: Update a Virtual Card

​Path Parameter

​Step 4: Cancel a VCN

​Example Request Body (CancelPurchaseRequestVO)

​Example Response (CancelPurchaseResponseVO)

​Step 5: Reconciliation Reports (Polling Flow)

​5A. Create Report (Trigger)

​Example Request Body

​Example Response (ReportResponseVO)

​5B. Get Report Data (Poll)

​Example Request

​Example Response (ReportVO)

​Retrieve Purchase by ID

​Example Response (PurchaseResponseVO)

Overview

Step 1: Retrieve Company Configuration

Query Parameters

Example Request

Example Response (`CompanyResponseVO`)

Step 2: Create a Virtual Card

Request Body (`VCNRequestVO`)

Control Types

Example Request Body

Example Response (`VCNResponseVO`)

Step 3: Update a Virtual Card

Path Parameter

Step 4: Cancel a VCN

Example Request Body (`CancelPurchaseRequestVO`)

Example Response (`CancelPurchaseResponseVO`)

Step 5: Reconciliation Reports (Polling Flow)

5A. Create Report (Trigger)

Example Request Body

Example Response (`ReportResponseVO`)

5B. Get Report Data (Poll)

Example Request

Example Response (`ReportVO`)

Retrieve Purchase by ID

Example Response (`PurchaseResponseVO`)