Visa Card Eligibility Service Documentation

Ready to start coding?

Things to Know

The Visa Card Eligibility Service (VCES) APIs can be used in sandbox by any developer.

The sandbox includes an environment and test data to enable using the API for testing. For more details, please reach out to developer@visa.com.

All projects using VCES will go through a review and approval process at Visa. Please reach out to your Visa account representative early in the process to ensure that your application meets the criteria permitted for the use of VCES.

The service provides two APIs. The Visa Card Eligibility API could be used by partners who have access to the cardnumber as part of the usecase. Partners who do not have access to the cardnumber could use the Visa Card Eligibility iFrame API to check for eligibility.

Availability

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

Available in entire region

Limited availability in region

Not available

Product Name Availability Notes
Visa Card Eligibility Service
Product Name Availability Notes
Visa Card Eligibility Service
Product Name Availability Notes
Visa Card Eligibility Service
Product Name Availability Notes
Visa Card Eligibility Service
Product Name Availability Notes
Visa Card Eligibility Service

Getting Started

Visa Card Eligibility Service (VCES) can enable Visa client, merchants and developers to check for eligibility to offers and benefits based on the card number subject to terms and restrictions. The eligibility criteria may range from broad to more granular card attributes and could include access based on number of purchases of the offer or benefit done in the past. The attributes of the card (issuer BID, card product etc. ) could be returned for an eligible card meeting the qualification criteria of the offer or benefit. Multiple 'Eligibility Level' could 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 first step in getting started with Visa Card Eligibility Service (VCES) is to understand how it works, the criteria available as part of eligibility and the role of each APIs in checking the card eligibility. 

VCES is a card number verification service designed to promote targeted distribution of Visa card benefits. VCES service enables Visa clients, merchants and third-party developers to use a 16 digit card account number to check eligibility and access rights to the benefits and enhancement privileges available for the associated Visa cardholders. Examples of the card benefits may include access to discounts at movie theaters or access to the high-end cardholder care service (such as Visa Concierge) or access to the sweepstakes registrations. More specifically, access to the Visa Concierge program is only available to Visa Signature cardholders, while access to discounts at movie theaters is only available to card issued by certain issuers. 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 platforms and services to retrieve card account attributes and to compare these attributes against the pre-configured program eligibility criteria. Each VCES program has different eligibility criteria, which may range from simple validation of 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, merchants 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, prepayment validation and post-payment redemption.

VCES provides two sets of APIs for partners. The Visa Card Eligibilty 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 of these APIs are described in the sections below.

How Does it Work?

VCES is a card number verification service designed to promote targeted distribution of Visa card benefits. The service enables Visa clients, merchants and third-party developers to use a 16 digit card account number to check eligibility and benefits access rights available for the associated Visa cardholders.

The below provides the steps involved in, how a merchant partner could use the service. 

  • The merchant onboarding is done to capture the basic details. This would be done in collaboration with your Visa representative.
  • A program for the merchant is created and a set of eligibility criteria is assigned to the program. More details on the eligibility criteria are available in Getting Started section.
  • A merchant having access to the PAN data as part of the use case would use the Visa Card Eligibility API and follow the below steps:
    • The mechant calls the Validate operation to check if the cardholder has access to the privileged offer or benefit.
    • A success response is returned if the card is eligible for the offer or benefit. If ineligible, a status code is returned indicating the reason (does not meet the qualification criteria and/or does not meet the redemption access criteria).
    • If eligible, the cardholder is shown the offer or benefit details. The cardholder goes through the purchase flow and enters their card details in the merchant checkout page.
    • The merchant would call the PrePay operation to check if the card entered by the cardholder is the same one which was used initially to check the access privilege. Based on the success of this call, the merchant would submit the card information to their payment provider.
    • After the payment has been processed successfully, the final Redeem operation call would be made to notify VCES that the cardholder completed the purchase. The Redeem operation call would be made as a final step after the completion of all business processes on the merchant side.
  • A merchant not having access to the PAN data as part of the use case would use the Visa Card Eligibility iFrame API and follow the below steps:
    • The mechant calls the GetToken operation to obtain a token which is valid for 60 seconds.
    • The token obtained in the prior step would be sent as a parameter to load the VCES iframe. The partner can customize the look-tone-feel of the iframe through CSS hosted on their side. The externally hosted CSS file line would need to be provided as part of on-boarding.
    • The cardholder enters their full 16 digits of the card on the iframe and submits the iframe.
    • VCES validates the card based on the eligibility criteria setup for the program and redirects to a pre-defined URL configured on the merchant side. This pre-defined redirect URL would need to be provided as part of on-boarding process.
    • The merchant calls the ValidateResult operation to check the eligibility status of the card. The response of this operation lets the merchant know whether the card is eligible for the offer or benefit. If ineligible, a status code is returned indicating the reason (does not meet the qualification criteria and/or does not meet the redemption access criteria).
    • If eligible, the cardholder is shown the offer or benefit details. The cardholder goes through the purchase flow and enters their card details in the merchant checkout page.
    • The merchant would submit the card information to their payment provider.
    • After the payment has been processed successfully, the final iFrameRedemption operation call would be made to notify VCES that the cardholder completed the purchase. This operation call would be made as a final step after the completion of all business processes on the merchant side.

Why Use It?

Provides an easy and elegant way to check if the card meets a complex eligibility criteria before providing access to premium offers or benefits.

Helps issuers and merchants to create portfolio specific benefit or service offering and thereby enabling them to track the impact of engagement on spend and loyalty.

API Included

Visa Card Eligibility API

The Visa Card Eligibility API provides operations to validate the card, check during the prepayment and to track redemption post purchase. This API would be used by partners who have access to PAN data. The Validate operation provides a way to check if the card meets the qualification criteria setup for the program and is eligible to access the offer or benefit. The Prepay operation provides a way to check if the card entered during the checkout flow is the same card used to successfully make the Validate operation call. This call would be used by the merchant before they submit the card information to their payment provider. The Redeem operation can be used by merchant to notify VCES that 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 merchant side.

Visa Card Eligibility iFrame API

The Visa Card Eligibility iFrame API provides operations to validate the card and to track redemption post purchase. This API would be used by partners who do not have access to PAN data as part of the usecase. The partner would call the GetToken operation to obtain a token which would be used in subsequent calls 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 need to call the ValidateResult operation to check if the card meets the qualification criteria setup for the program and is eligible to access the offer or benefit. The iframeRedemption operation can be used by partner to notify VCES that 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 merchant side.

Eligibility Criteria

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

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

  • Visa Region: Region where the card was issued, e.g. US, LAC, AP, CEMEA
  • Country: Country where the card was issued
  • Card Product Type: Product Type of the card. More information can be found here
  • Issuer BID: List of issuer specific BIDs
  • BIN: List of BINs
  • Account Range: List of Account Ranges
  • Rewards Programd Identifier (RPIN): List of RPINs
  • Product Sub-Type
  • Funding Source Type
  • Funding Source Sub-Type
  • Individual Card Account
  • Past Spend
  • Number of times the card can be validated in a given period (days)
  • Number of times the card can be redeemed in a given period (days or calendar months)

Please reach out to your Visa representative for your program eligibility criteria setup.

Checking for Eligibility Criteria

A merchant 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 the Validation operation are:

  • Vendor Unique ID: This is a unique identifier based on the eligibilty criteria for the program.
  • Correlation ID: This is a merchant generated identifier. This needs to be unique for every single call.
  • PAN: The 16 digits of the card number.

A successful Validation operation response would include the following:

  • Status Code: Status of the Validation operation. List of status codes are available in the API Reference link.
  • Status Description: Descritpion 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.

Checking for Eligibility before Payment Processing

The PrePay operation would be used to check if the cardnumber submitted for payment was the same cardnumber used to check the eligibility criteria setup for the program. This is usually done during the checkout process before the merchant 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.

Tracking Purchase or Redemption of the Offer

The Redeem operation would be used finally to let VCES know that the cardholder completed the purchase and hence redeemed the offer or benefit. This call would be made after the merchant 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 the cardnumber. The correlation id used in the call must be the same correlation id which was used to make a successful Validation call.

Eligibility Level

The eligibility level determines the unique highest level for every eligible card for the program. A program can be setup to have an eligibilty level returned by VCES for every eligible card to let the merchant partner know what particular access level needs to be provided for the card.

As an example, consider the use case where a merchant decides to provide discount for both Signature and Infinite cards. The merchant 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 Card Product Discount Percentage
1 Signature
10%
2 Infinite
15%

Potential Use Cases

A merchant or service provider could work with an issuer and Visa to create custom programs for the 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 could be redeemed in a given period (unlimited, twice a month etc.). An issuer could use the spend done by the cardholder as an eligibility criteria and thereby incentivize their cardholder to consolidate the spend on their issued card.