# Managing platform-specific payments using ICCP Virtual Cards source: https://developer.mastercard.com/iccp/documentation/03_use-cases/manage-platform-spec-pay/index.md > ICCP API enables corporates to manage and update virtual cards for platform-specific payments. It supports dynamic budget adjustments, secure allocation of funds, control enforcement, and automated reconciliation across multiple vendors or platforms. ## Scenario {#scenario} A corporate (AdBoost Media) manages platform-specific payments for digital advertising campaigns across Google Ads, Facebook Ads, LinkedIn Ads, and TikTok Ads. Instead of using a single corporate card, AdBoost Media creates multiple virtual cards with predefined spending limits for each platform: * Google Ads: $20,000 * Facebook Ads: $15,000 * LinkedIn Ads: $10,000 * TikTok Ads: $5,000 Each virtual card is restricted to its respective platform to prevent misuse. When the client, TechGear Inc., increases the campaign budget from $50,000 to $100,000, AdBoost Media uses the `Update Purchase Request API` to adjust the cumulative limits of the existing virtual cards. ## System and User Roles {#system-and-user-roles} | User | Roles | |------------------------------------------------------|-------------------------------------------------------------------------------------------------------------| | Corporate Admin (AdBoost Media) | Creates and updates virtual cards for platform-specific payments. | | Client (TechGear Inc.) | Provides budget and approves allocation. | | ICCP System | Facilitates virtual card issuance, control enforcement, updates, reporting, and notifications through APIs. | | Platform Vendor (Google, Facebook, LinkedIn, TikTok) | Receives payments through virtual cards. | ## APIs Involved {#apis-involved} | API | Function | |----------------------------------------------|---------------------------------------------------------------------------------------------------------| | `Submit Purchase Request API` | Used to create virtual cards for each platform with initial limits and controls. | | `GET Purchase Request Detail API` | Used to retrieve details of an existing virtual card before performing updates. | | `Update Purchase Request API` | Used to modify existing virtual cards, such as increasing cumulative spend limits or updating controls. | | **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, however, it can also be performed by the corporate when allowed 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. | ## Standard Controls {#standard-controls} | Control Name | Purpose | Sample Parameters | |---------------------------|---------------------------------------------------------|-----------------------------------------------------------------| | Validity Control | Defines the active duration of the virtual card. | `validFrom`: "2025-09-01" `validTo`: "2025-09-30" | | Velocity Control | Ensures spending frequency aligns with campaign pacing. | `maxTransactions`: "2" `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 | |----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------| | Geography Control | Restricts card usage to specific regions or countries. | `allowedCountries`: \["US", "UK"\] | | Transaction Limit Control | Caps the maximum spend per transaction. | `transactionLimit`: 5000 | | 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, such as Merchant Currency or Billing Currency. Enables restriction to specific transaction currency. | `currencyCode`: "USD" `currencyType`: "MERCHANT_CURRENCY" | | Amount Range Control | Defines an acceptable transaction amount range. | `minAmount`: 1000 `maxAmount`: 20000 | ## Reconciliation Options {#reconciliation-options} To ensure accurate tracking and validation of payments made through 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 all submitted purchase requests, including metadata, such as card number, supplier, amount, and status. This information can be used to match purchase requests with actual transaction events and support reconciliation workflows. ### 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, providing additional visibility into control breaches. Note: 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-platform-spec ### Workflow {#workflow} #### 1. Initiation and Setup {#1-initiation-and-setup} * The corporate admin submits Purchase Requests (PRs) through the `submitPurchaseRequest API` to create Virtual Card Numbers (VCNs) for each advertising platform, such as Google Ads, Facebook Ads, and so on. * Each VCN is configured with platform-specific spending limits and controls, such as validity, velocity, and transaction limits. #### 2. Payment Execution {#2-payment-execution} * VCNs are used to pay platform vendors for campaign services. * The finance team monitors card usage and reviews event notifications for anomalies or control triggers by subscribing to relevant event types through the `POST /subscriptions` and `GET /notifications APIs`. #### 3. Budget Adjustment {#3-budget-adjustment} * When the client increases the campaign budget, the corporate admin uses the `getPurchaseRequestDetail API` to retrieve current VCN configurations. * The corporate admin then uses the updatePurchaseRequest API to modify cumulative spend limits and controls on existing VCNs. #### 4. Reconciliation Support {#4-reconciliation-support} * Use the Purchase Request Report to confirm updated PR metadata including card limits and supplier details. * Use the Transaction Report to validate actual spend against platform invoices. * Review the `InControlResponse` field in the Authorization and Clearing Reports (`GetVCNAuthsReport`, `GetVCNClearingsReport`) to identify any control failures, such as velocity, and geography. * Subscribe to `Event Notification APIs` for near real-time updates on transaction events and card status changes. #### 5. Card Lifecycle Management {#5-card-lifecycle-management} VCNs can be updated post-campaign using the `updatePurchaseRequest API` to set an expiry date or change the card status to Blocked or Cancelled. ## Integration notes and API usage guidance {#integration-notes-and-api-usage-guidance} ### Card Updates {#card-updates} * Use the `getPurchaseRequestDetail API` to retrieve the current configuration of a Virtual Card Number (VCN) before making any changes. * Use the `updatePurchaseRequest API` to modify VCN attributes such as cumulative spend limits, control parameters, or validity dates. * Ensure that the VCN is active and compliant with mandatory controls, such as validity, velocity, before initiating updates. ### Event Notifications {#event-notifications} * Subscribe the `Event Notification APIs` using `POST /subscriptions` to register for relevant event types, such as transaction status, control triggers. * Use `GET /notifications` to retrieve near real-time updates on VCN activity, including spend alerts and card status changes. ### Control Management {#control-management} * ICCP supports dynamic control updates through the `updatePurchaseRequest API`, enabling flexible campaign management and budget adjustments. * Controls such as validity, velocity, transaction limits, and geography restrictions can be configured and modified as needed to align with platform-specific requirements.