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

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.