Just in Time Lifecycle Management API

Introduction

Spreedly's Just in time Lifecycle Management API is a feature offered under Spreedly's Advanced Vault product. This guide provides a technical overview of Spreedly's integration with Visa Account Updater (VAU) for Just-in-Time (JIT) credit card updates. VAU offers a real-time, synchronous update mechanism, distinct from both the MCABU system(a push model) and batch processing. Unlike batch updates, VAU allows for on-demand inquiries, giving Advanced Vault Customers greater control over when they request card information updates, and on which cards.

The "Card Refresher Inquiry" endpoint( PUT /v1/card_refresher/inquiry) allows merchants to request card updates at any point in their flow. This flexibility allows updates at cart load, immediately before the authorization, when retrying failed transactions, or at any other strategic moment. This approach contrasts with embedding updates solely within the authorization process which can introduce latency and complexity, or on a set batch schedule, leading to a higher chance of missed updates. The Card Refresher Inquiry is a distinct, non-billable API endpoint for Advanced Vault Customers.

Merchant Onboarding

VAU is available in five regions: NA, EU, LATAM, APAC, and Caribbean & Africa. Spreedly's initial launch will support NA, EU, and LATAM. Your organization needs to be onboarded for each region in which you operate, as inquiries must use the regional identifier associated with the card's intended processing region. This region is not determined solely by the merchant's primary physical location.

For example, updates for North American transactions must use the NA MID, while EU transactions are made under the EU MID. Since Spreedly cannot determine the card's intended region, merchants must provide the region information with each inquiry.

Spreedly will manage the onboarding process and management of the VAU MIDs, but in order to do so, merchants must provide the following:

Regions of Operation: All regions where the merchant intends to process transactions.
Merchant Acquiring Identifier(Acquirer MID): Minimum of 1 per region, can accept multiple.
Primary Card Acceptor ID: 1 per region

📘

A Card Acceptor ID is a unique identifier assigned to a merchant by their acquiring bank. It specifically identifies the merchant's location and business, associating it with the acquiring bank that processes their card transactions. Think of it as a more granular identifier than a MID. While a MID might identify the merchant at a higher level, the Card Acceptor ID pinpoints the specific location or business entity accepting card payments.

Spreedly will use this information to register the merchant with VAU for the specified regions and manage the association between regions, MIDs, and these identifiers. Merchants only need to specify the region with each inquiry; Spreedly will handle the lookup of the associated identifiers.

To begin the onboarding process for Visa JIT, which can take 3-4 weeks, please use the Advanced Vault Onboarding Form.

❗️

At this time, Spreedly can only support a single merchant profile per Spreedly Organization. This means in most cases, this service will not be suitable for those in the Merchant Aggregator category.

Understanding an Inquiry

Overview

An inquiry request can be two transactions in one, one for the inquiry request, and one for the update response.

Inquiry Request: This initial request checks Visa's ability to process the update. Failures can occur due to timeouts, inactive MIDs, or other Visa-side issues. This request has its own inquiry transaction token.

Update Response: If the inquiry is successful, the response object mirrors other update responses within the Spreedly system, including those from MCABU and Batch. This response is a separate transaction type with its own transaction token. While the result of the update is provided in the synchronous response, if enabled, a callback will also be sent for contactcardholder, closepaymentmethod and replacepaymentmethod transaction types.

Flagging and Card Enrollment

Visa JIT flagging differs from traditional Lifecycle Management. Today with Batch Lifecycle Management and MCABU, there are two levels of enablement. A card must be enrolled in Advanced Vault to use LCM, and Account updater must be on for the Organization, Environment and at the card level. Visa JIT infers intent to receive an update from the inquiry API call itself. Therefore, cards do not require pre-enablement in Account Updater at the payment method (PM) or environment (ENV) level, however Account Updater must still be enabled at the organization level.

📘

This flagging model has implications for contactcardholder management. If a card's eligible_for_card_updater flag is set to false, a VAU inquiry will still be processed. A CCH response from VAU will still count towards the two contactcardholder logic and may trigger unenrollment from batch updates.

For Advanced Vault enrollment, the organization and environment must be enabled and the payment method will need to be managed: true. However, If a card is not managed at the PM level and an inquiry is requested, the request is not rejected, but the payment method will be changed to managed:true automatically and proceed. If the organization and environment are not enabled, then the request will be rejected.

Visa JIT Configuration Matrix

Requests and Responses

When you are ready to inquire for an update on a supported payment method, simply pass in the payment method token and the region to the inquire endpoint. Spreedly will pass the card details to the updating service and provide a response synchronously in ~100ms.

Making a Request

endpoint: PUT/v1/card_refresher/inquiry

{
  "card_refresher_inquiry": {
    "payment_method_token": <token>,
    "region": <region>
  }
}

Responses

The inquiry response can have 1 of 3 high level results, denoted byinquiry status: succeeded, error or rejected.

Succeeded

Succeeded means we were able to connect successfully to the service, the merchant was fully active and the card was valid. It does not mean that the card was updated. To understand what the response from the service was, there will be a secondary transaction for the type of response received from the updating service, which can be one of the below:

While the result of the above updates will be seen in the synchronous response, we understand many customers may have built their update processing logic around a callback endpoint. As such, ReplacePaymentMethod, ClosePaymentMethod and ContactCardHolder transaction types will still be sent to your callback endpoint if this has been enabled for your environment. For more details on these three transaction types, you can visit this section of the Lifecycle Management guide.

Successful response example with replacepaymentmethod

{
  "inquiry": {
    "token": "EXYZeklIr3dkoiaqNvynL3KHSiG",
    "created_at": "2025-02-12T18:48:26Z",
    "updated_at": "2025-02-12T18:48:26Z",
    "merchant_id": "00000012345",
    "inquiry_status": "succeeded",
    "message": "Transaction successful",
    "error_code": null,
    "transaction": {
      "token": "4V75AVNWmVptWDoen3KktlC9xrM",
      ...
      "transaction_type": "ReplacePaymentMethod",
      "state": "succeeded",
      ...
      "payment_method": {
        "token": "ViKw7tt0vDZEssOal5ylcWA8GCO",
        ...
      }
    }
  }
}

Note how this response has two transaction tokens. 1 for the high level inquiry, 1 for the replacepaymentmethod.

Error

An error inquiry status will refer to a technical issues with connecting to the service, or, can be a Spreedly error in the case where a non supported card type was sent. Visa is currently the only supported card type for the inquiry endpoint. An error will always mean we did not successfully connect to Visa.

Spreedly will provide a message alongside the inquiry status indicating the specific reason for the error.

Error response example

{
  "inquiry": {
    "token": "EVHyWiH1g2Xyn2VV43XAhALhVBk",
    "created_at": "2025-02-19T14:43:40Z",
    "updated_at": "2025-02-19T14:43:40Z",
    "merchant_id": null,
    "region": "NA",
    "inquiry_status": "error",
    "message": "An internal connection error occurred when attempting to connect to Visa.",
    "error_code": "internal_connection_error",
    "payment_method_token": "BBeLLW5nUmy4ZrYdCa9nb1aglsa",
    "transaction": null
  }
}

Reject

In the case of a reject, Spreedly was able to successfully connect to Visa, however, the request was rejected by them. This could be an invalid PAN or expiration date, or, the Region MID was not yet activated for the merchant.

Spreedly will provide a message alongside the inquiry status indicating the specific reason for the rejection.

{
  "inquiry": {
    "token": "VXiBn7GWZBDiYMuFa4aPbvIEqwr",
    "created_at": "2025-02-19T14:41:41Z",
    "updated_at": "2025-02-19T14:41:41Z",
    "merchant_id": "000000676251",
    "region": "NA",
    "inquiry_status": "rejected",
    "message": "Expiration Date is invalid (must be YYMM)",
    "error_code": "5",
    "payment_method_token": "NDn2jnxgVfPWObMOClzsSkss89d",
    "transaction": null
  }
}

📘

Rejects are likely to be rare, as Spreedly's own validation will prevent the inquiry to be sent, or prevent the vaulting of an invalid payment method.

Reporting

Updates from this service can be viewed under the Lifecycle Management Reporting section in the Spreedly App. Billable update types from this service are the same as other services, so these updates will be seen under the same views. To differentiate them, updates from this service are identified by updating service: visa_au.

FAQ:

Q: When should I make an inquiry?

A: This feature is designed to give our users control over where in their flow it makes the most sense to check for an update. For example, for CITs with a stored credential, you may show your customers their stored credentials and you want to check for an update prior to loading their payment methods to ensure you display up to date PAN and EXP date. Or for MITs, you want to make sure you are using the most up to date information before proceeding with the authorization. Or, you only want to check for an update after an MIT fails.

Q: Where do i go to get my ids?

A: This information can be obtained from your acquirer(s). While you may have multiple ids, only 1 per region is sufficient.

Q: How do i request spreedly sign me up for this?

A: If you are not yet an Advanced Vault customer, signing up for AV would be the first step. If you are, then you can start the enrollment process by completing the Advanced Vault feature onboarding form. You might have already completed this for MCABU and NT, but it has been expanded for the new information required an we suggest completing it in full again.

Q: How does JIT work with Composer?

A: Because JIT is a distinct endpoint, it can easily work within your payment process using Composer. You can perform aninquiry , interrogate the response and then chose whether or not proceed with making a call to the /transactions endpoint.

Q: Should i run batch/macabu and jit?

A: We recommend you do. While the flagging allows for you to only run JIT by turning off AU at the environment or card level, this will turn off automatic updates for MC and Discover card types.

Q: Is there a sandbox?

A: This is not currently supported with our initial GA launch.