Installments Transaction Service

Start a Project
API Overview
API Reference

Release Notes for Installments Transaction Service

Visa Installment Solutions has been enhanced to support the following features:

March 2025

• Updated Definition for monthlyRatePercentage field – The monthlyRatePercentage field in the Matched Eligible API Response call is expected to be displayed in decimals. Hence the definition was added to multiply the value by a hundred.
• Using Indirect Merchant Country for Cross-Border Validations– Visa will verify the accuracy of the Issuer and Merchant country data from the onboarding profile by comparing it with the transaction authorization feed.

September 2024

• Updated Phone Number Validations in Client Onboarding API – The phone field was updated to have the additional information on country-specific format allowed for Phone number.
• Updated vPlanIDRef in Matched Eligible Installment Plan API– The vPlanIDRef field in Matched Eligible Installment Plans API response was updated to a required field.

July 2024

• Debit--Elgibility, Plan Acceptance – These features allow Visa to extend Installment Plan capability to Debit Cardholders.
• Debit--Transaction Association, Plan Cancellation & Reports – VIS wants to increase cardholder base and transactions by offering installments to Debit cardholders.

May 2024

• Changes to Seller Fee Reports for Cancellations – The ACQUIRER_TO_ISSUER fee field will be added to Seller Fee Reports to enable clients to track Non-Merchant Funded plans through Issuer Fee Reports.
• Islamic Installment Plans Support – Sellers will understand the type of Installment Plan (Conventional or Islamic) associated with the presented credential from the Eligibility API Response.
• Rules Governing Bilateral Plan Hierarchy--Plan Precedence – Updated the description of plan precedence under Rules Governing Bilateral Plan Hierarchy so that the hierarchy policy is detailed clearly.

March 2024

• Bulk Onboarding of Merchants on Visa Installments – Acquirers will be able to onboard Merchants using a self-serve interface to upload Indirect Merchants.
• Automatic Terms and Conditions Updates for Merchant – This feature provides live access to the most recent Terms and Conditions via the Plan Search API, fetching them from VDP. This allows for updates/changes made to the Terms and Conditions to be conveyed to the merchant-side clients within a 24-hour timeframe.
• Updated cardBrand Enum and Description – The cardBrand field, to describe the network brand, was updated with a new NON-VISA option along with other card types. When no value is set (or the field is not returned), the cardBrand will be treated as VISA. For Non-Visa Account Range enrollment, cardBrand will be returned as NON-VISA.

January 2024

• Fee Reports for Cross-Border transactions – Cross-Border Fee Reports will be given in local currency.
• Cross-Border Identifiers– Added Cross Border identifiers on various reports.
• Updated Character Limit in Client Onboarding API– The stateProvinceCode character limit has been modified to align with different regions.

November 2023

• Updated File Format Requirements – Expanded guideline about empty lines between sections in the File Format Requirements section.
• Added JWE Encryption Clarification– Elaborated the Note to discuss opting out of encryption.
• API Updates and Additions – Added a new version of the 403 Error Message to block transaction association calls for Post-Purchase. Added a Note on PAR field for select APIs regarding LCM updates. Clarified DateTime fields on truncating the millisecond part of the timestamp.

October 2023

September 2023

• This version release includes a new note for Plan Acceptances Search Batch Request file about processing time. For Canada, Visa added a static buffer value for all installment transactions for Fee Computation to aid merchants from exposure to chargebacks or disputes. A new provision to the 403 Error Message allows disabling Indirect Merchants. Token-based Installment Plans for Account Ranges has been enabled to ensure flexibility with PAN enrollment functionality. A new capability to arrange precedence of plan display during VIS checkout allows Issuers to provide tailored solutions to customers

August 2023

• This version release includes a new Header x-message-tracking-id for notifications sent by Visa, updated documentation about Transaction Amount in the Exception Report, updated Promotion Code values in API guides, and corrected field order in Batch Files and Reports.

July 2023

• This version release includes cross-border installments functionality which is on track to launch by August-end, in addition to minor API modifications and other general enhancements. This version release includes fixes for 46 bugs in production.

February 2022

Visa Installment Solutions has been enhanced to support the following features:

• CP and CNP Filtering Enabled for VIS APIs – The V2.0 Matched Eligible Installment Plans API and the V2.0 Plan Selection API have been enhanced to include an optional field acceptanceChannel. When making a Matched Eligible Installment Plans API call, Issuers may express channel preferences for either Card Present or Card Not Present acceptance channels.

• Plan Registration System Identifier in Status Change Notifications – A new 10-digit identifier called the Plan Registration System Identifier was introduced as a unique Plan Identifier. Going forward, Plan Acceptance Status Change notifications as well as Installment Transaction Status Change notifications will include the Plan Registration System Identifier.

• Merchant Participants Allowed to Populate Token in PAN Field – Merchant Participants are now able to populate the PAN field with either encrypted PANs or Tokens. Previously, Merchant Participants were required to use a different field for Tokens. Now, the Token Account Number may be populated in either field. When a consumer uses a card for contactless transactions, the payment terminal receives a PAN. And, when a consumer uses digital wallets, such as Apple Pay, Google Pay, or Samsung Pay, the payment terminal receives a Token.

January 2022

Visa Installment Solutions has been enhanced to support the following features:

• ISO Dependency for Filtered Plans and ISO-Override Flag – The V2.0 Matched Plans API and V1.0 Eligible Plans API have been enhanced to return plans where the Merchant / Seller is flagged as ISO-capable and where the Issuer selected ISO-dependent for that card type. Therefore, if an issuer is configured as ISO-dependent for that card type, only ISO-capable Merchants / Sellers are able to receive eligible plans and use Plan Selection. The ISO / message details are required for routing the installments transaction to the proper account/ledger on the issuer side. The ISO / message details are a dependency for debit transactions and dual credit line use cases.

The Seller profile in the Digital Configuration Portal (DCP) has been enhanced to support scenarios for Seller enablers who can support the ISO flag but work with an acquirer that is not ISO-configured in DCP. Using a flag to override existing logic for ISO dependency, Seller enablers can send a flag in the V2.0 Matched Plans API and V1.0 Eligible Plans API to VIS indicating that they are capable of sending plan details in ISO and receiving eligible plans. They can also send a flag in the V2.0 Plan Selection API and V1.0 Plan Acceptance API to VIS indicating that they are capable of sending plan details in Clearing for refund and cancellation use cases.

• Plan Registration System Identifier in Seller APIs – DCP has introduced a new 10-digit identifier called the Plan Registration System Identifier. The Plan Registration System Identifier will be provided in the Matched Plans and Eligible Plans APIs so that Sellers may include it in the ISO message for an Issuer who requires the ISO flag. V1.0 and V2.0 responses for the Plan Acceptance API, Plan Cancellation API, and Transaction Search API also include the Plan Registration System Identifier so that Sellers may input the identifier in Plan Cancellation calls and for Clearing purposes.
• Adjustment of Acquirer Reference Number Object in Seller V2 APIs – The Seller V2.0 APIs have been enhanced to include the Acquirer Reference Number (ARN) in the InstallmentTran Info object. While the ARN cannot be used to identify individual clearings, it can be used to provide more information about the clearing to help VIS identify clearings more accurately based on clearing amount. The ARN has been added to the InstallmentTran Info object in all Seller V2.0 APIs and Issuer Callback Notifications.
• During-Purchase and Post-Purchase Plans Pre-Filtered for Eligibility Calls – The V1.0 and V2.0 Eligibility API calls have been enhanced to return a list of applicable Installment plans for during-purchase and post-purchase transactions. When an Issuer makes an Eligibility call, the response will only return pre- and post-purchase plans. When a Merchant / Seller makes an Eligibility call, the response will only return during-purchase plans. This enhancement will suppress plans that are irrelevant at a particular point in the purchase journey.
• Exclusion of Service Fee from SIF File - Previously, the SIF file and V1 Fee Reports had discrepancies in the Service Fee value. In order to reconcile mismatch of the Service Fee, the Service Fee value / the pre-rated rate field has now been set to null in the SIF file.
• Client Specific Enablers:
  • Code Fix for V2.0 Plan Cancellations on Mastercard Transactions – V2.0 Cancellations for Mastercard transactions were not generating the correct cancellation notification. When calling Plan Cancellation on a Mastercard transaction, the notification generated was missing the refundAmount object, which then resulted in TSYS rejecting the notification call with a 404 error. In a code fix for 22.01, when no Auth or Clearing is available, the refundAmount object will be added to the JSON response and the notification will be sent to the client.
  • Code Fix for Generation of Unique Batch GUIDs – A troubleshooting investigation found that the database for batch file processing was getting updated with the same BATCH GUID for multiple records. A permanent code fix solution for generating unique BATCH GUIDs for different scenarios has been implemented in 22.01.
  • Code Fix for V2.0 Multi-Clearing Scenarios and Notifications – Notifications to a V2.0 client were repeated every ten minutes by a scheduler. The specified transaction under investigation was a multi-clearing scenario where the auth status was partially confirmed and labeled as PENDING_CONFIRMATION. When at least one clearing is present, a bug in the code continuously triggered the notifications in an attempt to change the transaction status. A code fix solution has been implemented in 22.01.
  • Enhancement of VOP Enrollment for V2.0 Clients – Due to rate limitation in VOP calls, Enrollment for V2.0 clients was slower than expected.  Different scenarios were tested with various application properties and in 22.01, performance for VOP enrollment has been expedited.

September 2021

Visa Installment Solutions has been enhanced to support the following feature:

• Plan Cancellation API Enhancements for Partial Refunds/Multiple Clearing – The V2.0 Cancellation API, billing reports, ledger management, and notifications have been enhanced to account for partial refunds and multiple clearing.

August 2021

Installments Device Management has been enhanced to support the following features:

• Batch File Enhancements– added a new Batch Job to process Device de-registration batch files. Clients will connect to GlobalScape to send and receive Device de-registration Batch files to Visa Installments. Please see Batch File Guide for details.

July 2021

Visa Installment Solutions has been enhanced to support the following features:

• Network Agnostic: This set of enhancements extends Visa Installment Solutions capabilities to non-Visa cards for issuers that support Visa and non-Visa networks. This allows Issuing clients to enable Visa Installments for all eligible cardholders regardless of network brand and for Seller clients to display Installments plans to more customers.

• API Enhancements – Enrollment, Plan Acceptance Confirmation and Cancelation, and Notifications were enhanced to support non-Visa cards.

• Batch File Enhancements – Two new batch jobs were created in order to ingest authorization and clearing data from Issuers and Processors for non-Visa cards. Refer to Batch File Guide for details

• Plan Acceptance at Order / Cancelation: This set of features and enhancements enable Sellers support Visa Installments without impacting the way they fulfill orders and process card transactions. Sellers today have a variety of ways that they run their businesses and in order to better serve them, VIS has been updated to support the following use cases.

• API Enhancements:

• Plan Selection API – This API can now be called for multiple authorization and multiple clearing. TransactionInfo a is no longer required at time of plan selection and can be associated later.

• Associate Transactions to a Plan Acceptance API – A new API to associate a transaction to a Plan Acceptance. This API is invoked after a Plan Acceptance is created and when a new transaction or a clearing (part of a transaction) needs to be associated with it.

• Plan Cancelation API – We defined two levels of cancelations:

• Plan Acceptance (order level) – Given a vPlanAcceptanceID, a whole order can be canceled

• Installment Transaction (clearing level) – Given an Installment Transaction, remaining clearings can be canceled for that specific transaction

• Notification Enhancement - We defined two levels of notifications:

• Plan Acceptance (order level) - coarse-grained status like CREATED, CANCELLED, CONFIRMED and UPDATED.

• Installment Transactions (clearing level) - detailed status like PENDING_AUTH, PENDING_CONFIRMATION, CONFIMRED, PENDING_CANCELLATION, CANCELLED (PARTIAL_CONFIRMATION, PARTIAL_CANCELLATION).

• Use Cases:

• Delayed Authorization - Consumer selection of installment plan is done during checkout, but consumer is charged (authorization is done) just prior to shipping.

• Split Shipments with separate Authorization messages - Consumer in a single order purchases multiple items. Items ship separately and have separate Authorization and Clearing.

• Online Shipment + Order Pickup - Consumer makes a single purchase online with multiple items and selects some for online shipment and some for in-store pickup. Multiple Auth messages potentially from different merchants (eCom + Store) that add up to full order amount.

• Split Shipments with Single Authorization / Multiple Clearing - Consumer in a single order purchases multiple items. Items ship separately but have single Authorization and multiple clearing.

• Partial Shipment - Consumer makes a single purchase online with multiple items and part of order is cancelled on request of consumer before it has shipped or part of the order doesn’t ship as item is out of stock. Clearing is sent only after the shipment delivery but it doesn’t match the Auth amount.

Installment Transaction Service APIs have been enhanced to support the following features:

• Plan Cancelation API:
• refundTransactionInfo field is no longer required for Plan Cancellation workflow. This enhancement enables Sellers/Acquires not performing online refunds to submit plan cancellation details.
• Addition of 2 new properties: transactionRefundAmount and splitTransactionRefunds. These fields ensure the right cancellation amount is processed and that the Seller doesn't call the plan cancellation for the wrong orders or excess amounts. Based on the request parameters the cancellation behavior is as follows:
• Complete Plan Acceptance cancellation (all associated ISO Auth Transactions and Clearing) - if only vPlanAcceptanceID and encAccountNumber are provided. This is most common scenario of Single/Auth clearing use case.
• ISO Auth Transaction Cancellation (associated clearing) - if only transactionInfo is provided and does not contain details on  transactionRefundAmount or splitTransactionRefunds. This is used when multiple clearing exist but individual clearing level details are not provided by the seller.
• Cancellation based on refund amount at ISO Auth Transaction level - if transactionInfo is provided and contains transactionRefundAmount details. The associated clearing will be fully or partially cancelled based on transactionRefundAmount. Individual clearing level detail is provided by seller explicitly to identify which clearing the refund should be applied to.
• Batch File Enhancements – Business Reports v2.0 - Seller Fee Report and Transaction Report have been enhanced to reflect the API v2.0 structure. Only Clients who are using API v2.0 will get v2.0 Business reports and Clients on v1.0 APIs will get existing v1.0 Business Reports. Please refer to v2.0 of the Batch File Guide for report specifications and details.

February 2021

Installments Transaction Service APIs have been enhanced to support the following features:

• API Enhancements – Issuers can now provide T&Cs in up to 3 different languages on VDP. Visa will support languages but will not provide translations. API response has been enhanced to include T&Cs for multiple languages. Each T&C object will have a language code to identify T&Cs. This enhancement applies to the following APIs in v1.0 and v2.0 respectively:  Eligible Plans API, Match Plans API.
• Business Report Enhancements– All Seller reports have been enhanced to include PAR. Seller Fee and Summary Report and Seller Transaction Report now separate Plan Acceptance confirmation and cancellation when both confirmation and cancellation occur on the same day.
• Visa Token Support – Token Support integration has been completed to enable merchants to accept mobile wallets for installment transactions (eCommerce and Face to Face). The following APIs now support token-related data in request: Eligible Plans API (API v1.0), Plan Acceptance API (API v1.0 & v2.0), Plan Cancellation API (API v1.0 & v2.0), Candidates API (API v1.0), Match Plans API (API v2.0).

October 2020

Installments Transaction Service APIs have been enhanced to support the following features:

• Payment Account Reference (PAR) Support- API request payloads have been enhanced to accept PAR as an alternative identifier to the cardholder PAN, when merchants are requesting plans, capturing plan selections, or cancelling plan acceptances. Visa will provide PAR to the merchant at the first time that the merchant sends the PAN to Visa.

  • For API v1.0, PAR may be used in requests to the Eligible Installment Plans API, the Plan Selection API, and the Plan Cancellation API.
  • For API v2.0, PAR may be used in requests to the Matched Eligible Installment Plans API, the Plan Selection API, and the Plan Cancellation API.

• Asymmetric Encryption Support - API endpoints allow merchants and issuers to use asymmetric encryption algorithms for JSON Web Encryption (JWE), when sending encrypted information to Visa. Sellers and Issuers should encode their JWE content with the public encryption key that is provided to Visa during onboarding.

• (API v1.0) Sending Enrollment Date for Post-Purchase Use Case - The Matched Candidates API and Matched Candidates Batch Result API have been enhanced to optionally send the cardholder enrollment date (i.e. date that an issuer determines that the Cardholder is eligible for Installment Offers) as part of the response payload. This is only available for Issuers looking up enrollment date for their PANs, and it is not available to sellers. For example, in a Post Purchase scenario, enrollment date may be used to ensure that Issuers only offer installments for transactions that occurred after enrollment.

September 2020

Visa Installments v2.0 APIs

• With the Visa Installments v2.0 APIs, a simple and consistent approach to API design maps the API resource model to real world objects like cardHolders, enrollmentProfiles, etc. This version also delivers consistency in error handling, common shared constructs, and standard REST semantics wherever possible. Installments v2.0 APIs are designed with future use cases in mind, which will allow new features to be introduced down the line without requiring breaking changes and API version upgrades. API specifications can be received through clients’ Visa representatives.

Visa Installments v1.0 APIs are now deprecated

• With Visa Installments v2.0 APIs, Visa Installments current APIs (v1.0) are being deprecated with this release. Visa Installments API versions are supported for up to three years from the date of release. Visa Installments v1.0 APIs, originally released in September 2019, may continue to be used until their end of life in September 2022. Once a new version of the API is released, the current version is deprecated. When an API is deprecated, it continues to receive critical bug fixes, but it does not get any new feature enhancements until its end of life. Visa Installments participants will be notified six months prior to the end of life date as a reminder of this process. Once an API version is at its end of life, API calls will no longer be honored for that API version.

Device APIs enable Point-of-Sale devices to call Visa Installment APIs directly:

• In release 20.09, Visa Installments now supports devices to call Visa Installments APIs by using Business-to-Client Identity and Access Management (B2C IAM). This architecture enables authentication of devices to call APIs directly. B2C IAM improves the security, flexibility, and traceability of during-purchase installments.
• For devices to call Visa Installments APIs, Sellers must onboard each payment device using the Enroll Device API. During onboarding, Sellers will provide a device serial number, and Visa will create a unique Device ID for the device. Once onboarded, the POS device can access Visa Installments APIs to process during-purchase installment plans.

July 2020

Installment Transaction Service APIs have been enhanced to support the following features:

• Eligible Plans API and Plan Acceptance API – APIs have been enhanced to support Visa Provisioned Token Identifier for retrieving eligible plans and perform plan selection. Visa Provisioned Token Identifier is typically used by Merchants integrating with Visa Token Service for Card on File tokenization.

Installment Transaction Service Batch Files now offer support for the following features:

• Extended Eligibility – Batch File allows select Merchants to retrieve eligibility for large groups of cardholders in batch. Notifications of eligibility changes for the following enrollment scenarios will be sent to these Merchants.

1. Issuer enrolls a consumer and that consumer exists on Merchant file
2. Issuer updates the consumer available plan list and/or updates the eligibility expiry time
3. Issuer disables the consumer’s extended eligibility or unenrolls the consumer

• Summary Seller Fee Report – Report provides Merchants, Acquirers, and Technology Providers with summary level fee information from Visa Installment Services on a daily and monthly basis so that fees can be reconciled.

June 2020

Installment Transaction Service APIs have been enhanced to support the following features:

• Plan Selection API — API response payload has been enhanced to return installment fee information so that Issuers can display these and corresponding amounts in cardholder online banking and monthly statements.
• Plan Selection API — API has been enhanced to capture and use alternative transaction details (AuthID, CardID, transaction amount, transaction timestamp) so Visa Installment Solutions can match a plan acceptance to the authorization record when the Seller does not have access to the Visa transactionID.

Installment Transaction Service Batch Files now offer support for the following features:

• Seller Fee Report —  Report provides Merchants, Acquirers and Technology Providers with transaction level fee information from Visa Installment Services on a daily and monthly basis, so that fees can be calculated and transactions reconciled.