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.
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.
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.
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.
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.
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).
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.
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.
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 suport 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.
- Issuer enrolls a consumer and that consumer exists on Merchant file
- Issuer updates the consumer available plan list and/or updates the eligibility expiry time
- 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. The fee information is aggregated by the Merchant Card Accepter ID.
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 suport 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.
Installment Transaction Service APIs have been enhanced to support the following features:
- Eligible Installment Plans API — API response payload has been enhanced with a field that takes in terms and conditions text for Point of Sale devices or eCommerce retailers to display with the plan details.
Installment Transaction Service APIs have been enhanced to support the following features:
- Plan Acceptance by Cardholder API — API request payload has been enhanced with an optional field taking in an external client ID to facilitate partner relationships.
- Matched Candidates API — API request and response payload have been enhanced with an optional field taking in an external client ID to facilitate partner relationships.
- Matched Candidates Batch Request API — API request and response payload have been enhanced with an optional field taking in an external client ID to facilitate partner relationships.
- Eligible Installment Plans API —API request payload has been enhanced with an optional field taking in an external client ID to facilitate partner relationships and an optional object called merchant that takes into account merchant Category Code and merchant ID; API response payload has been enhanced with an optional field taking in a promotion Code for plan identification.
- Plan Cancellation API — API request payload has been enhanced with an optional field taking in an external client ID to facilitate partner relationships; API response payload has been enhanced with new optional fields taking in an acquirer reference ID and authorization code to help facilitate issuers' matching of original installment transactions.
Disclaimer: This page is provided on an “as is, where is” basis, “with all faults” known and unknown. This page could include technical inaccuracies or typographical errors. Changes are periodically added to the information herein: these changes will be incorporated in new editions of the document. VISA may make improvements and/or changes in the product(s) and/or the program(s) described in this document at any time. Where potential future functionality is highlighted, visa does not provide any warranty on whether such functionality will be available or if it will be delivered in any particular time. To the maximum extent permitted by applicable law, visa explicitly disclaims all warranties, express or implied, regarding the information contained herein, including any implied warranty of merchantability, fitness for a particular purpose, and non-infringement.
If you have technical questions or questions regarding a Visa service or questions about this document, please contact your Visa representative.
Start a Project
API Overview
API Reference