Installment Management Service

Start a Project Start a Project API Overview API Overview API Reference API Reference
Navigate to...
keyboard_arrow_down

Release Notes for Installment Management Service

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.

October 2021

 

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

  • Plan Cancellation API Enhancement to Calculate Elapsed Time - For pro-rated refunds (cancellation between 30 – 60 days), clients need to know the number of elapsed days to effectively compute the prorated funding fees being refunded. The Issuer Fee Report, notification payloads, and the Plan Acceptance Search API have been enhanced to include clearing dates and last refund dates. Therefore, when a Plan Acceptance or Installment Transaction is partially or fully cancelled, Issuers may be able to calculate elapsed time and prorated funding fee amounts so that they do not need to wait for billing reports to compute applicable funding fees. The Issuer Fee Report has two new columns: Cancelled Date Time and Clearing Date Time.
  • Clearing Transaction IDs Matched for Post-Purchase Transactions - In 21.10, the Post-Purchase functionality has been enhanced to have the Issuer-provided Clearing Transaction IDs matched. For During-Purchase, the fallback to use Auth Code to obtain a Clearing match was already in place in case the Authorization Transaction ID is not matched. Based on the Clearing Transaction ID match, the Authorization matching step is skipped and Issuers should expect to see Post-Purchase Plan Acceptances to be marked as Confirmed after the Clearing is matched.
  • Enhancement to Installment Transaction Notifications - External Client ID has been added to V2.0 Plan Acceptance and Installment Transaction status change notifications, which addresses a gap for the Issuers on behalf of relationships with Processors in V2.0 Push Notifications. Installment Transaction status change notifications have been enhanced to include additional transaction-level information so that Issuers may refer to the notifications for information related to multiple-clearing use cases. Additional details include Transaction ID, Auth Code, Transaction Amount, Clearing Amount (after clearing), and Currency Code (after clearing).
  • New Issuer Exception Report - Visa Installment Solutions has been enhanced to provide a daily exception report which currently covers three exception scenarios. The first exception scenario is for notification failures of Plan Acceptance and Cancellation notifications. The second exception scenario is for Installment Transaction confirmations where the Clearing is received after a time period where the Authorization has dropped off on the Issuer side. The maximum time period is specified on the Issuer profile. The third exception scenario is when the status of the notification is unknown and we do not know whether the client received the notification.
  • PGP Encryption Support for Batch File Flows - The V2.0 Issuer Fee Report and Exception Reports have been enhanced to support both PGP and JWE encryption. When configured in DCP, clients will need to select at least one form of encryption but will have the option of selecting their preferred form of encryption for files from Visa Installment Solutions. For example, clients may select CSV with JWE encrypted PANs or PGP for PGP encrypted files with clear PANs.

 

September 2021

 

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

  • Encryption Enhancement for V2.0 Batch Enrollment and Unenrollment Files - V2.0 batch enrollment and unenrollment files have been enhanced to support both PGP and JWE encryption. When configured in DCP, clients will need to select at least one form of encryption but will have the option of selecting either or both of PGP and JWE encryption for files from Visa Installments.
  • Enhancement to V2.0 Business Reports – The Seller Fee Report, Issuer Fee Report, and Seller Transaction Report have been enhanced to support Plan Acceptance eCommerce scenarios and partial refunds.

 

August 2021

 
Installment Management Service has been enhanced to support the following features:
  • Post-Purchase Enhancement for V1.0 – V1.0 APIs have been enhanced to support post-purchase Installments on split-shipment transactions by allowing a single transaction ID to map to multiple clearing items. For V1.0 post-purchase Installments only, the amount passed in Plan Selection is now the clearing amount, not the authorization amount. Issuers must create a new a Plan Acceptance for each (any) clearing. 
  • Updates to ledger management - Clearing Sequence number is added along with Transaction ID in LAAF file to uniquely identity the Ledger Entry however this change is off by default to ensure Issuer backward compatibility.

 

July 2021

 
Visa Installments 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 to 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 use cases below.
  • 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 Management Service APIs have been enhanced to support the following features: 

  • Irregular Payments API – Irregular Payments API was converted to a Batch API for V2 to process payments asynchronously.
  • Retrieve Plan Acceptance Batch Results API – New API to get the result of Irregular Payments Batch.
  • Batch File Enhancements – Business Reports v2.0 - Issuer Fee Report has 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.

 

March 2021

 
  • Post-Purchase Enhancements – Both API v1.0 and API v2.0 have been updated to utilize determine Cardholder eligibility and installment payment amounts for Cardholders participating in Post Purchase Installment Plans will be billed according to settlement currency (Issuer’s currency and Cardholder billing currency), rather than authorization currency (Merchant’s currency) for Post Purchase Installment Plan purposes, for the transaction amount of all purchases placed on Post Purchase Installment Plans. As the settlement currency is the domestic currency for issuer, Tthis means that cross-border purchase transactions can beare expands the scope of transactions eligible for Post -Purchase Installment Plans to include transactions that were cross-border at the time of purchase.  Both API v1.0 and API v2.0 have been updated to utilize settlement currency enabled to include cross-border transactions for Post-Purchase installments as a result of enhancementsin to the Eligible Plans Match API, the Plan Selection API, and internal Visa processes that determine the Bbilling cCurrency (currency with which customer is billed) from transaction processing messages. This enhancement does not enable Cross-Border transactions for During Purchase.
  • Batch File Enhancements –Batch files have been enhanced to support API v2.0 format for Cardholder Enrollment and Un-Enrollment APIs. Once issuers configure an Enrollment Profile in Visa Developer, issuer determines eligibility criteria for cardholder participation in Installment Plans. Issuer can then add and remove eligible cardholders from enrollment in specific Installment Plans through a batch process that pairs batch files with specific Enrollment/Unenrollment APIs.

 

February 2021

 

  • Post-Purchase Enhancements – Post-purchase API calls have been enhanced to enable recreation of a Plan Acceptance for a given transaction within 60 days of cancelling plan via Plan Cancellation API. This allows installments plans that have been cancelled to be restored.
  • Batch File Enhancements – Enrollment Batch process has been enhanced to improve ability to recover from failures and improve enrollment performance for large batch sizes. Issuer Fee and Summary Report now separates Plan Acceptance confirmation and cancellation when both confirmation and cancellation occur on the same day.

 

October 2020

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

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

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 the launch of Visa Installments v2.0 APIs, the 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.

Card Lifecycle Management has been enhanced:

  • Release 20.09 integrates Visa Installments with Visa Shared Card Services (SCS), allowing Visa Installments to get card lifecycle updates made by Issuers. Issuers will continue to utilize the PAN LCM APIs they use today as part of Visa Token Service to inform Visa of card updates. Visa Installments will get notified with lifecycle updates for all cards enrolled in Visa Installments.
  • Upon notification that a card number has changed, Visa Installments will remove the old PAN and assign the account eligibility to the new PAN. For clients using Ledger Management functionality, Visa Installments will also ensure that payments continue to be scheduled with the new card.

Enrollment Profiles enhance cardholder enrollment:

  • API 2.0 simplifies the enrollment process by enabling Issuers to create enrollment profiles for groups of cardholders (e.g., Signature, Infinite, etc). Through a VDP self-service interface, Issuers will be able to access a form for creating new enrollment profiles and a dashboard for editing, duplicating, and deleting existing profiles.
  • An enrollment profile can be assigned to one or more cardholders (PANs). Issuers will be able to set the following plan configuration fields for a single enrollment profile:
    • Allowed Installment Modes (pre-purchase, during-purchase, or post-purchase)
    • Extended Eligibility Enablement
    • Allowed Installment Plans
    • Allowed Credit Amount
    • Number of Allowed Plan Acceptances per Time Period

August 2020

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

  • Irregular Installments Payments API - API has been enhanced with new scheduling statuses for installment plans to ensure that plans are cancelled without error regardless of when the Plan Cancellation API is called. Note, this enhancement is only relevant for Issuers who are subscribed to the Ledger Management feature set.
  • Plan Acceptance API - API has been enhanced by mapping Plan Acceptances to Ledger Account Activity Files. Issuers will be able to receive information on applicable fees and APR.

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

  • All Batch Files - Batch Request Files have been enhanced with a new naming scheme to eliminate the dependency on Issuers to remember the previous sequence number. The new format is defined for any given day and includes a sequence number along with the current date in YYYYMMDD format. 

July 2020

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

  • Enrollment API – API has been enhanced to perform additional validation checks that will ensure cardholders are successfully enrolled in plans. Issuers who enroll cardholders to an invalid PlanID or PromotionID will receive an error message in the API response payload. 
  • Get Plan Acceptance API – API response payload has been enhanced with the addition of Plan Acceptance acceptedDateTime. Because a plan acceptance can occur weeks after a transaction takes place, Issuers will be able to filter plans on the date the plan was accepted. 

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

  • Summary Issuer Fee Report –  Report provides Issuers 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 Issuer ID. 

Ledger Account Activity File (LAAF) has been enhanced to support the following features

  • Charge Codes  – LAAF has been enhanced with a charge codes field so Issuers subscribed to Ledger Management Service can match received charge codes to their backend processing systems. 
    • "PRIN001": Principal
    • "FEE004": Variable Fee
    • "FEE003": Upfront Fee
    • "FEE001": Fixed Fee 

June 2020

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

  • Issuer Fee Report — Report provides Issuers with fee level information from Visa Installment Services on a daily and monthly basis, so that fees can be calculated and transactions reconciled.

April 2020

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

  • Enrollment API — API has been enhanced with an added validation check for "availablePlans” to filter the plans shown to the cardholder during Eligible Plans API. “availablePlans“ is an optional field that accepts a list of plan ids or promotion ids.
  • Plan Acceptance API — API has been enhanced to capture authorization code and acquirer reference number during clearing to ensure accurate transaction matching in plan acceptance and plan cancellation; API response payload has been enhanced with the addition of the Seller_To_Lender_Installment_Fee (non-Market Plan configuration).
  • Irregular Payments API — API has been enhanced with two new event types ("CANCEL" and "DELINQUENT") so that when cardholders cancel or have delinquent payments on an active plan, Issuers can utilize the Irregular Payments API to update Visa on status change. 
  • Unenrollment Batch File Request — API request payload has been enhanced with the field “EnrollmentEndDate”, which will be used to update enrollment end dates for each consumer.

February 2020

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

  • Plan Acceptance Callback API — When a Plan Acceptance takes place this API automatically pushes a notification to the issuer-provided URL informing them of the plan acceptance details.
  • Plan Cancellation Callback API — When a Plan Cancellation takes place this API automatically pushes a notification to the issuer-provided URL informing them of the plan cancellation details.
  • Post-Purchase Eligibility Callback API — This API automatically pushes a notification to the issuer-provided URL if a cardholder is eligible for post-purchase installments while providing eligible plan details in the push. 

Various batch file parameter names within the Enrollments Batch Request File, Plan Acceptance Confirmation Batch Files, and Plan Cancellation Batch Files have been modified to enhance functionality and clarity: 

Plan Acceptance Confirmation Batch Files and Plan Cancellation Batch Files Enrollments Batch Request File
  • feeAmount → purchaseAmount.amount
  • feeCurrencyCode → purchaseAmount.currencyCode
  • interestAmount → fixedFeeAmount.amount
  • interestCurrencyCode → fixedFeeAmount.currencyCode
  • principleAmount→ variableFeeAmount.amount
  • principleCurrencyCode→ variableFeeAmount.currencyCode
  • settings.installmentPaymentOptions → settings.availablePlans
  • settings.availableCredit → settings.availableCredit.amount
  • settings.currencyCode → settings.availableCredit.currencyCode

January 2020

Installment Management Service APIs now offer support for the following features:

  • Plan Acceptance API — this API provides Issuers the ability to get details of a plan acceptance utilizing various filters [GET  /installments/planAcceptances]

Installment Management 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.
  • Cardholder Enrollment API —  API request payload has been enhanced with optional fields tracking for extended eligibility and velocity
    •  In the Batch File, optional fields have been added to track for the same functionality
  • 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 Installments transactions 

Batch file names have been enchanced for further clarity. Examples are shown below:

  • VIS_Enrollments_PROD_1e406568b001_000001_REQ_20191111.csv
  • VIS_GetConfPlanAccept_PROD_1e406568b001_000221_REQ_20191002.csv
  • VIS_GetCxlPlanAccept_PROD_1e406568b001_100101_REQ_20191002.csv

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.