Getting Started with Visa Card Eligibility Service

About Visa Card Eligibility Service

Visa Card Eligibility Service (VCES) APIs can be used in the Sandbox (SBX) environment by any developer. The environment includes test data to simulate request and response payloads. For more details, please reach out to [email protected].

All projects using VCES will go through a review and approval process at Visa to move to the Certification (CTE) and Production (PROD) environments. Please reach out to your Visa account representative early in the process to ensure your application meets the criteria permitted for the use of VCES in these environments and begin executing an agreement.

The product provides two APIs: The Visa Card Eligibility API can be used by partners who have access to the full 16-digit PAN as part of their use case. Partners who do not have access to the PAN must use the Visa Card Eligibility iFrame API.

Availability

The following table lists the regional availability for Visa Card Eligibility Service. To view availability of all products, refer to the Availability Matrix.

North America Asia-Pacific Europe CEMEA LAC Notes
    KEY
  • Available in entire region
  • Not available
  • See notes for available countries

Working with Visa Card Eligibility Service

Visa Card Eligibility Service (VCES) is an account eligibility verification product enabling our issuers, merchants, partners, and developers to check eligibility / access rights to exclusive benefits, offers, and promotions, subject to terms and restrictions, in real-time.

Eligibility criteria may range from broad to granular card attributes and may allow access based on number of purchases or spend amount completed. The attributes of the card (Issuer BID, Product Type, RPIN, Funding Source Type, etc.) can be returned for an eligible card meeting the qualification criterion.

'Eligibility Levels' can be configured for the same offer and returned in the response for an eligible card which could be used to create customer access levels.

The Visa Card Eligibility API is available to partners who have access to PAN data (PCI DSS compliant) while the Visa Card Eligibility iFrame API is available to partners who do not have access to PAN data as part of their use case.

How it Works, Eligibility Criteria, and Role of Each API

VCES is a card number verification product designed to promote targeted distribution of Visa card benefits. The service enables Visa clients, merchants, partners, and third-party developers to use a 16-digit card account number to check eligibility and benefit access rights available for the associated Visa cardholder. Examples of the card benefits may include access to airport lounges, invitation only events, high-end cardholder care services (such as Visa Concierge), or access to sweepstakes registration. VCES stores program access rules for each program and provides the capability to check if a particular account number has access rights to a particular program.

VCES uses various Visa back-end products, platforms, and services to retrieve card account attributes and compares these attributes against the pre-configured program eligibility criteria. Each VCES program has different eligibility criteria, which may range from simple validation of a card’s product type to more complex validations using Issuer BID, Rewards Program ID, BIN lists, card’s country of origin, or the cardholder's past spend

During the process of redeeming the card benefits, partners may need to check card eligibility multiple times. For example, a vendor may first check if a cardholder is eligible for the program and then later check to make sure that the right card is used for payment. To support this use case, VCES service has multiple types of card validation, such as initial eligibility check, pre-payment validation and post-payment redemption.

VCES provides two sets of APIs for partners. The Visa Card Eligibility API could be used by partners who have access to PAN data. The Visa Card Eligibility iFrame API could be used by partners who do not have access to PAN data. Both APIs are described in the sections below.

APIs Included

Visa Card Eligibility API

The Visa Card Eligibility API provides the Validate, PrePay, and Redeem operations. This API is used by partners who have access to PAN data (PCI DSS Compliant).

The Validate operation provides a way to check if the card meets the eligibility criteria setup for the program and is eligible to access the benefit, offer, or promotion.

The PrePay operation can be used to check if the card entered during the checkout flow is the same card used to successfully make the Validate operation call. This call could be used by the partner before they submit the card information to their payment provider.

The Redeem operation can be used by partner to notify VCES the card was used to purchase or redeem the benefit, offer, or promotion. This call would be done after all business process updates are done on the partner side. The PrePay and Redeem operations are optional.

Visa Card Eligibility iFrame API

The Visa Card Eligibility iFrame API provides the GetToken, ValidateResult, iFrameRedemption, ValidateiFrame, PrePayiFrame, and RedeemiFrame operations. This API would be used by partners who do not have access to PAN data as part of their use case.

The partner would call the GetToken operation to obtain a token, which would be used in a subsequent call to load the iFrame. After the cardholder enters the PAN on the iFrame the user is redirected to a pre-defined redirect URL setup on the partner side.

The partner would then call the ValidateResult operation to check if the card meets the qualification criteria setup for the program and is eligible to access the benefit, offer, or promotion.

The PrePayiFrame operation can be used to check if the card entered during the checkout flow is the same card used to successfully make the Validate operation call. This call could be used by the partner before they submit the card information to their payment provider.

The iFrameRedemption operation can be used by the partner to notify VCES the card was used to purchase or redeem the offer or benefit. This call would be done after all business process updates are done on the partner side.

The ValidateiFrame and RedeemiFrame operations are like the ValidateResult and iFrameRedemption operations, except they leverage an Alias ID so that a PAN does not need to be passed via the iFrame. These operations can be used to validate or redeem after an Alias ID has been generated, meaning a PAN has already been submitted and checked using ValidateResult. PrePay and Reedem operations are optional.

Eligibility Criteria

The eligibility criteria are the most important aspect of the program configuration and determines the target set of cardholders who can access the benefit, offer, or promotion and how frequently they can access.

One can use the following eligibility criteria in any possible combination in as many eligibility level rules as possible:

  • 0$ Auth Check: Performs a $0 transaction for an Issuer to verify if the card is active.
  • Region: List of Regions where the card was issued, e.g., US, CAN, LAC, AP, EU, and CEMEA
  • Country: List of Countries where the card was issued based on ISO country code
  • Product Type: List of Product Types of the card
  • Product Sub-Type: List of Product Sub Types
  • Rewards Program Identification Number (RPIN): List of RPINs
  • Issuer BID: List of Business IDs for an Issuer
  • CIR Driven: Checks data against Cardholder Information Repository (CIR) via ALM
  • Funding Source Type: List of Funding Sources
  • Funding Source Sub-Type: List of Funding Source Sub Types
  • Enhancement Type Code: VFS / VDBP enhancement type code for benefit
  • Portfolio ID: Portfolio segementation via VFS / VDBP
  • Issuer Portfolio ID: Issuer generated portfolio segementation via VFS / VDBP
  • Spend Tier Configuration ID: Spend criteria configured via VFS / VDBP
  • BIN: List of 6- or 8-digit BINs
  • Account Range: List of Account Ranges
  • Validation Limits: Number of times the card can be validated in each period (e.g., days, months, or years)
  • Redemption Limits: Number of times the card can be redeemed in each period (e.g., days, months, or years)

Please reach out to your Visa representative to learn more about eligibility criteria and for your program eligibility criteria setup.

Validation Overview

A partner would use the Validation operation initially to check if the cardnumber meets the eligibility criteria setup for the program.

You can find the technical details in the API Reference link, but the primary components of Validation operation requests are:

  • Vendor Unique ID (VUID): This is a unique identifier based on the eligibility criteria for the program. Also called a program, program ID, or promotion.
  • Correlation ID: This is a partner generated identifier. This needs to be unique for every single call, except when performing a PrePay or Redemption operation (use same correlation ID used during Validation operation).
  • PAN: The 16 digits of the card number.

A successful Validation operation response would include the following:

  • Status Code: Status of the Validation operation.
  • Status Description: Description of the status.
  • IsEligible: True or False indicator on whether the card is eligible for the program or not.
  • Eligibility Level: The level at which the card is eligible for the program. See eligibility level section for more details.
  • Card Attributes: More card level attributes returned in the response. These are configurable at the Vendor Unique ID level and may require approval from your Visa representative.

PrePay Overview

The PrePay operations are used to check if the card number submitted for payment was the same card number used to during the Validation operation. This is usually done during the checkout process before the partner submits the payment information to their payment gateway. Use of this call is optional. If used, the correlation id used in the call needs to be the same correlation id which was used to make a successful Validation operation call.

You can find the technical details in the API Reference link, but the primary components of PrePay operation requests are:

  • Vendor Unique ID (VUID): This is a unique identifier based on the eligibility criteria for the program. Also called a program, program ID, or promotion.
  • Correlation ID: This is a partner generated identifier. This needs to be unique for every single call, except when performing a PrePay or Redemption operation (use same correlation ID used during Validation operation).
  • PAN: The 16 digits of the card number.

A successful PrePay operation response would include the following:

  • Status Code: Status of the PrePay operation.
  • Status Description: Description of the status.
  • Has PAN Matched: True or False indicator on whether the card is the same one used during the Validation operation.

Redemption Overview

The Redeem operations are used to let VCES know the cardholder completed the purchase and hence redeemed the offer or benefit. This call would be made after the partner completes the payment processing in the checkout process and confirms the actual redemption of the offer or benefit by the cardholder. This call helps VCES in tracking redemptions by card number. The correlation ID used in the call must be the same correlation ID which was used to make a successful Validation call.

You can find the technical details in the API Reference link, but the primary components of Redeem operation requests are:

  • Vendor Unique ID (VUID): This is a unique identifier based on the eligibility criteria for the program. Also called a program, program ID, or promotion.
  • Correlation ID: This is a partner generated identifier. This needs to be unique for every single call, except when performing a PrePay or Redemption operation (use same correlation ID used during Validation operation).
  • PAN: The 16 digits of the card number.

A successful Redeem operation response would include the following:

  • Status Code: Status of the Redeem operation.
  • Status Description: Description of the status.

Eligibility Levels

The eligibility level determines the unique, highest level for every eligible card for the program. A program can be setup to have an eligibility level returned by VCES for every eligible card to let the partner know what particular access level needs to be provided for the card or to containerize responses based on eligibility criteria.

As an example, consider the use case where a partner decides to provide discounts for various Visa product types. The partner could also provide a different discount percentage for the card products even though both are eligible for the program. This could be handled by configuring the rules at eligibility level. For a card meeting multiple eligibility levels, the highest eligibility level is returned in the API response.

Eligibility Level Product Type Discount Percentage
1 Signature 5%
2 Signature Preferred 7%
3 Infinite 10%
4 Infinite Privelege 12%

Potential Use Cases

A partner, merchant, or service provider could work with an issuer and Visa to create custom programs for various portfolios of the issuer. Each portfolio could have different service level benefit access (percentage of discount, amount of credit applied, etc.) and the number of times it can be redeemed in each period (unlimited, twice a month, etc.). An issuer could leverage the spend by the cardholder as an eligibility criterion and thereby incentivize their cardholder to consolidate the spend on their issued card.