# Managing multi-invoice payments using ICCP Virtual Cards
source: https://developer.mastercard.com/iccp/documentation/03_use-cases/manage-multi-invoice-pay/index.md

> ICCP API enables corporates to generate multi-use virtual cards with invoice addenda attached. It supports consolidated payments to suppliers while maintaining granular visibility and control over individual invoice records.

## Scenario {#scenario}

A cosmetic company in New Zealand procures cosmetic products in bulk from its supplier ABC. Instead of using a corporate card, the company allocates a multi-use virtual card with a specified cumulative limit and validity to ABC.

* The supplier attaches invoices for each batch of materials produced.
* Invoice details, such as invoice number and invoice amount, are added using ICCP APIs.
* Upto 5,000 invoice records can be linked to a single Purchase Request (PR).
* These details are included as an attachment in the VCN email sent to the supplier.

## System and User Roles {#system-and-user-roles}

|                User                |                                                        Roles                                                        |
|------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| Corporate Admin (Cosmetic Company) | Issues multi-use virtual cards and attaches invoice data.                                                           |
| Supplier (ABC)                     | Receives virtual card and submits invoice details for payment.                                                      |
| ICCP System                        | Facilitates virtual card issuance, control enforcement, invoice addenda, reporting, and notifications through APIs. |

## APIs Involved {#apis-involved}

|                     API                      |                                   Function                                    |
|----------------------------------------------|-------------------------------------------------------------------------------|
| `Submit Purchase Request API`                | Used to create multi-use virtual cards with cumulative limits and controls.   |
| `Add Invoice Addenda API`                    | Used to attach invoice-level data to the virtual card.                        |
| `GET Purchase Request API`                   | Used to retrieve details of the virtual card and confirm invoice linkage.     |
| `GET Purchase Templates API`                 | Used to retrieve available purchase templates for invoice-based transactions. |
| `GET Purchase Template Details API`          | Used to fetch configuration details of a selected purchase template.          |
| **Reporting APIs** (SOAP)                    |                                                                               |
| `getPurchaseRequestDetail`                   | Tracks PR metadata and status.                                                |
| `GetVCNAuthsReport`, `GetVCNClearingsReport` | Details transaction-level data for reconciliation.                            |
| **Event Notification APIs** (REST)           |                                                                               |
| `POST /subscriptions`                        | Registers for event types.                                                    |
| `GET /notifications`                         | Retrieves near real-time transaction and card status events.                  |

## Pre-requisites {#pre-requisites}

|               Item                |                                                                        Description                                                                         |
|-----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Real Card Registration            | Register a valid real card within ICCP UI. Typically done by the issuer.                                                                                   |
| Purchase Template Setup           | Configure by providing the controls and CDF values. This can be enabled either by the issuer or the corporate.                                             |
| Auto-Approve Purchase Group Setup | Configure an auto-approve purchase group by linking eligible real cards and purchase templates. This can be enabled either by the issuer or the corporate. |
| Supplier Setup                    | Vendor profiles must be correctly configured by the issuer or corporate.                                                                                   |

## Mandatory Controls {#mandatory-controls}

|   Control Name   |                              Purpose                               |                     Sample Parameters                     |
|------------------|--------------------------------------------------------------------|-----------------------------------------------------------|
| Validity Control | Defines the active duration of the virtual card.                   | `validFrom`: "2025-10-01" `validTo`: "2025-12-31"         |
| Velocity Control | Ensures spending frequency aligns with invoice processing cadence. | `maxTrans`: "10" `cumulativeLimit`: "500.0" `period`: "C" |

## Optional Controls {#optional-controls}

|       Control Name        |                        Purpose                         |        Sample Parameters         |
|---------------------------|--------------------------------------------------------|----------------------------------|
| Geography Control         | Restricts card usage to specific regions or countries. | `allowedCountries`: \["NZ"\]     |
| Transaction Limit Control | Caps the maximum spend per transaction.                | `transactionLimit`: "10000"      |
| Merchant ID Control       | Restricts usage to a specific supplier or merchant.    | `merchantId`: "ABC_SUPPLIER_001" |

## Reconciliation Options {#reconciliation-options}

To ensure accurate tracking and validation of payments made through the virtual cards, corporates can leverage ICCP's reporting and notification APIs for reconciliation:

### Purchase Request Detail {#purchase-request-detail}

Use the `getPurchaseRequestDetail` API to retrieve information about a purchase requests, including metadata, such as card number, supplier, amount, and status. This API will also provide the available number of transactions, balance, and limits on the virtual card.

### Authorization and Clearing Reports {#authorization-and-clearing-reports}

ICCP provides detailed reports on transaction-level data, including timestamps, merchant information, and the results of control validations. These reports (`GetVCNAuthsReport`, `GetVCNClearingsReport`) are used to reconcile virtual card transactions against invoices and vendor billing cycles.

### Exception and Control Failure Reporting {#exception-and-control-failure-reporting}

ICCP's Authorization and Clearing Reports include fields such as `InControlResponse` that indicate when a transaction has breached a configured control (such as velocity, validity, merchant restrictions). These control failure indicators help quickly identify and address anomalies. The `GetVCNClearingExceptionReport` API further highlights cases where clearing amounts exceed cumulative limits.  

Reports must be requested; they are not automatically sent. Alternatively, commercial event notifications can push relevant events as they happen.

### Event Notification APIs {#event-notification-apis}

Near real-time notifications are available for transaction events, card status changes, and control triggers, enabling automated reconciliation workflows by subscribing to relevant event types.

## Process Flow {#process-flow}

Diagram manage-multi-invoice-pay

### Workflow {#workflow}

#### 1. Card Creation {#1-card-creation}

* Corporate Admin uses `GET Purchase Templates API` and `GET Purchase Template Details API` to select and configure the appropriate template.
* Submits a PR through `Submit Purchase Request API` to generate a multi-use virtual card.
* Mandatory and optional controls are applied.

#### 2. Invoice Attachment {#2-invoice-attachment}

* Supplier uses `Add Invoice Addenda API` to attach invoice records to the PR.
* Up to 5,000 invoices can be added, each with its own number and amount.

#### 3. Card Usage {#3-card-usage}

* Supplier charges the virtual card for each invoice.
* ICCP validates controls and processes transactions.

#### 4. Reconciliation {#4-reconciliation}

* Pull Purchase Request Report to confirm invoice metadata.
* Pull Transaction Report to validate actual spend.
* Review the `InControlResponse` field in the Authorization and Clearing Reports (`GetVCNAuthsReport`, `GetVCNClearingsReport`) to identify any control violations, such as validity, geography, or merchant restrictions.
* Subscribe to `Event Notification API` for near real-time updates.

#### 5. Card Lifecycle Management {#5-card-lifecycle-management}

* Use `GET Purchase Request API` to audit card and invoice details.
* Card can be updated or deactivated as needed using `Update Purchase Request API` (if applicable).

## Integration notes and API usage guidance {#integration-notes-and-api-usage-guidance}

### Invoice Addenda {#invoice-addenda}

* Use the `Add Invoice Addenda API` to attach invoice records to the PR.
* Ensure each invoice includes required fields, such as `invoiceNumber` and `invoiceAmount`.

### Card Configuration {#card-configuration}

* Use the `Submit Purchase Request API` to create multi-use cards with cumulative limits.
* Apply controls to ensure secure and compliant usage.

### Template Setup {#template-setup}

Use `GET Purchase Templates API` and `GET Purchase Template Details API` to configure the correct template for invoice-based transactions.

### Event Notifications {#event-notifications}

Subscribe to the `Event Notification API` to receive near real-time updates on card status changes and invoice-related transactions.

### Reporting and Audit {#reporting-and-audit}

Use `Purchase Request Report` and `GET Purchase Request API` to validate invoice linkage and payment status.