# Managing recurring payments using ICCP Virtual Cards source: https://developer.mastercard.com/iccp/documentation/03_use-cases/manage-recurring-payments/index.md > ICCP API enables corporates to securely manage recurring payments, such as subscriptions, memberships, and vendor services by generating and controlling virtual cards. ## Scenario {#scenario} A mid-sized enterprise (ABC Tech Solutions) subscribes to multiple platforms, such as AWS, Microsoft 365, Slack, and Zoom. To manage these recurring payments securely and efficiently, the enterprise uses ICCP APIs to generate dedicated virtual cards for each vendor and reconcile transactions using ICCP's reporting and notification APIs. ## System and User Roles {#system-and-user-roles} | User | Roles | |--------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------| | Corporate Admin (ABC Tech Solutions) | Initiates virtual card creation and manages controls through ICCP APIs. | | Issuer | Registers the real card. | | Finance Team | Monitors usage, sets limits, and reviews transactions using ICCP reporting APIs. | | Subscription Vendors | Receive payments through the virtual cards. | | ICCP System | Facilitates virtual card issuance, control enforcement, and reporting through APIs. | | Reconciliation Support System | Pulls ICCP SOAP reports and REST notifications for financial validation, supporting reconciliation workflows and not serving as the primary reporting layer. | ## APIs Involved {#apis-involved} | API | Function | |----------------------------------------------|----------------------------------------------------------------| | `submitPurchaseRequest` | Initiates virtual card creation for a specific vendor payment. | | **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 the ICCP UI. Typically done by the issuer or corporate. | | 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. | | Multi-Use Card Requirement | Virtual cards used for recurring payments must not be single use. This allows the card to support multiple transactions over its validity period. Ensure that the **Single-use Virtual Card Numbers (VCN) only** setting is set as **Off** under Company Settings. | ## Recommended Controls {#recommended-controls} Any control for amounts or number of transactions if left blank or 0 means that there will be no control applied. * Controls are typically defined within a purchase template. * These templates contain control definitions that are applied automatically when a virtual card is created using the `submitPurchaseRequest` API. ## Standard Controls {#standard-controls} | Control Name | Purpose | Sample Parameters | |---------------------------|-----------------------------------------------------------|--------------------------------------------------------| | Validity Control | Defines the active duration of the virtual card. | `validFrom`: "2025-01-01" `validTo`: "2025-12-31" | | Velocity Control | Ensures spending frequency aligns with the payment cycle. | `maxTrans`: 1 `cumulativeLimit`: "200.0" `period`: "M" | | Transaction Limit Control | Caps the maximum spend per transaction. | `transactionLimit`: 200 | ## Optional Controls {#optional-controls} | Control Name | Purpose | Sample Parameters | |----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------| | MCC Control | Restricts transactions to specific Merchant Category Codes (MCCs) associated with allowed purchase types. | `mccList`: \["4816", "5734"\] | | Currency Control (Currency Type) | Defines the currency used for authorization checks -- Merchant Currency or Billing Currency. Enables restriction to specific transaction currency. | `currencyCode`: "USD" `currencyType`: "MERCHANT_CURRENCY" | ## 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-recurr-pay ### Workflow {#workflow} #### 1. Initiation {#1-initiation} The Corporate Admin submits a purchase request using the ICCP API for a recurring payment, specifying the real card, purchase template, supplier, and required controls. #### 2. Validation {#2-validation} ICCP validates the request, ensuring the funding source, template, and supplier are correctly configured. #### 3. Virtual Card Generation {#3-virtual-card-generation} ICCP issues a Virtual Card Number (VCN) with the specified controls (for example, validity, velocity, transaction limit). #### 4. Supplier Assignment {#4supplier-assignment} The VCN is linked to the supplier (vendor) and used for recurring payments. #### 5. Monitoring {#5monitoring} The finance team monitors VCN usage and reviews reports for anomalies or control failures. #### 6. Reconciliation {#6reconciliation} * Use the `getPurchaseRequestDetail` API to retrieve purchase request metadata. * Use Authorization and Clearing Reports (`GetVCNAuthsReport`, `GetVCNClearingsReport`) to validate transaction details and control outcomes. * Review the `InControlResponse` field in reports for any control failures (such as velocity, validity, merchant restrictions). * Subscribe to Event Notification APIs for near real-time updates on transaction and card status events. #### 7. Deactivation {#7deactivation} When the payment relationship ends, the virtual card can be deactivated using the Update or Cancel Purchase Request API. ## Integration notes and API usage guidance {#integration-notes-and-api-usage-guidance} ### Cancel or Block a VCN {#cancel-or-block-a-vcn} * To deactivate a virtual card when a recurring payment relationship ends, use the `Update Purchase Request API` to update the card validity. * To cancel a virtual card use the `Cancel Purchase Request API`. * A virtual card can also be blocked to temporarily not allow any activity, use the `Cancel Purchase Request API` with `blockPurchaseRequest`: "true". * Ensure any pending transactions are reconciled before canceling any VCN. ### Event Notifications {#event-notifications} Subscribe to the `Event Notification API` to receive near real-time updates on card status changes, including deactivation events. This helps maintain synchronization between ICCP and internal systems. ### Managing Spend Controls on VCN {#managing-spend-controls-on-vcn} ICCP APIs allow dynamic updates to controls (such as velocity, validity) through the `Update Purchase Request API`. This can be used to adjust card behaviour before deactivation if needed.