Skip to main content
Visa Card Eligibility Service

VCES operations and APIs

Available for use by:
Issuer banks Acquirer banks Merchants Independent developers Issuer banks for small businesses

Visa Card Eligibility Service (VCES) offers API services so clients can check cardholder eligibility for benefits, offers, and promotions whether or not they have Payment Card Industry Data Security Standard (PCI DSS)-compliant access to Primary Account Number (PAN) data.

VCES API endpoints reference

All Visa Card Eligibility Service (VCES) endpoints are secured with either an x-pay-token header or Mutual Transport Layer Security (mTLS).

This table provides a comprehensive overview of all VCES endpoints. Endpoint paths are the same across all environments; only the base host changes. See Environment hosts and URL structure for base host values.

VCES API Endpoints

Service Operation Endpoint
Web Service Validate POST /visacardeligibilityservices/v1/cardeligibility/validate
Web Service Prepay POST /visacardeligibilityservices/v1/cardeligibility/prepay
Web Service Redeem POST /visacardeligibilityservices/v1/promo/redeem
iFrame iFrame Token POST /visacardeligibilityservices/v1/registeriframe/token
iFrame Validate Result POST /visacardeligibilityservices/v1/eligibility/validateresult
iFrame Prepay iFrame POST /visacardeligibilityservices/v1/eligibility/prepayiframe
iFrame iFrame Redemption POST /visacardeligibilityservices/v1/promo/iframeredemption
iFrame Validate iFrame POST /visacardeligibilityservices/v1/eligibility/validateiframe
iFrame Redeem iFrame POST /visacardeligibilityservices/v1/promo/redeemiframe

Validation operation overview

The operations are Validate, Validate Result, and Validate iFrame. They check the eligibility of a credential based on the Vendor Unique ID (VUID) and Number of Additional Redemptions (where applicable).

API requests

The request payload includes these attributes. Not all fields are required, and some are mutually exclusive of one another. Refer to VCES API Reference for more information.

  • Vendor Unique ID (VUID) – Unique ID containing eligibility requirements and custom settings for the program. Also referenced as Program ID, VUID, or Promotion ID.
  • Correlation ID – Partner-generated unique ID, 10-100 characters, for the API call.
  • Primary Account Number (PAN) – Usually the 16-digit card number. Can also accept Token Account Number if the Is PAN field is set to false. Neither TAN nor Alias ID is passed if this field is used.
  • Token Account Number (TAN) – 16-19-digit Visa Token Services issued token. Only TAN is accepted in this field. Neither PAN nor Alias ID is passed if this field is used.
  • Alias ID – Unique ID (36-character UUID/GUID) generated by Visa Card Eligibility Service (VCES) which corresponds to a credential. Neither PAN nor TAN is passed if this field is used.
  • Request Timestamp – Current timestamp in GMT.
  • Extended Data – Free form field used in offline reporting.
  • Number of Additional Redemptions – Additional redemptions submitted by the user during the eligibility check.
  • Is Pan – This field is set to true by default, so it only needs to be passed if setting it to false. False identifies the client does not know if the user has submitted a PAN or TAN.

API response

Response payload attributes are customizable for each implementation. Not every client will receive every response attribute. Some require approval from other Visa functions and need additional implementation with those functions.

Speak with your Visa representative and the VCES Product office to understand what is needed for your implementation. Refer to VCES API Reference for more information.

Response payload attributes may include:

  • Card ID – VCES generated unique numeric ID corresponding to a credential. This is not used in any API, but is a semi-permanent identifier for a specific credential.
  • Correlation ID – Partner-generated unique ID, 10-100 characters, for the API call.
  • Is Eligible – Indicates whether a credential is eligible based on the criteria and configuration of the Vendor Unique ID.
  • Eligibility Level – Indicator for the specific eligibility criteria, or tier, validated within a Vendor Unique ID. VCES returns the highest (largest number) eligibility level the credential qualifies.
  • Status Code – VCES response code indicating the result of the operation. See VCES status codes and descriptions for more information.
  • Status Description – Verbose text indicating the result of the operation. See VCES status codes and descriptions for more information.
  • Response Timestamp – Current timestamp in GMT.
  • Alias ID – Unique 36-character ID generated by VCES for a credential; usable instead of PAN or a Visa Token Services (VTS) token.
  • Issuer BID – Business ID as defined by Visa. Also called BID or User BID.
  • Rewards Program Identification Number (RPIN) – Portfolio identifier defined by Visa for issuers.
  • Country Code – Numeric ISO country code.
  • Product Type – Product type as defined at issuance or by Account Level Management.
  • Product Sub-Type – Product sub-type as defined at issuance. This value is only returned for some credentials.
  • Account Funding Source – Account funding source as defined at issuance.
  • Account Funding Source Sub-Type – Account funding source sub-type as defined at issuance. This value is only returned for some Prepaid Account Funding Source credentials.
  • Platform Code – Product platform code used for processing; the broadest categorization or family of the card product.
  • Spend Tier Spend Amount – Largest amount of eligible spend performed on a credential, qualified against configured spend tiers. Requires business justification and internal approval.
  • Spend Tier Currency Code – Currency code for the amount in Spend Tier Spend Amount. Requires business justification and internal approval.
  • Redemption Details – Object containing redemption-limit information, including allowed redemptions, used redemptions, eligible redemptions remaining, pooled status, and unlimited status.
  • Entity To Be Billed – Object detailing who to bill for redemptions, including memberCharge and additionalRedemptionCharges. Only available for Validate and Validate iFrame when configured.
  • BIN – Bank Identification Number as defined at issuance. Returned for Validate Result only. Cannot be combined with PAN Last Four Digits.
  • PAN Last Four Digits – Last four digits of the PAN validated. Returned for Validate Result only. Cannot be combined with BIN.
  • Data Token – Value used to glean spend habits from the credential. Returned in Validate Result only, when configured.

Prepay overview

The operations are Prepay and Prepay iFrame. They are used to confirm the credential matches the one validated earlier. This operation reuses the original Correlation ID except in Prepay iFrame.

API requests

The request payload includes these attributes. Refer to VCES API Reference for more information.

  • Correlation ID – Partner-generated unique ID, 10-100 characters, for the API call used in the Validation operation if using Prepay. In Prepay iFrame, this is a new Correlation ID.
  • Vendor Unique ID (VUID) – Unique ID containing eligibility requirements and custom settings for the program. Also referenced as Program ID, VUID, or Promotion ID.
  • Request Timestamp – Current timestamp in GMT.
  • Alias ID – Unique 36-character ID generated by Visa Card Eligibility Service (VCES) for a credential; usable instead of PAN or a Visa Token Services (VTS) token. Prepay iFrame requires this field instead of PAN or TAN.
  • Is Pan – This field is set to true by default, so it only needs to be passed if setting to false. False identifies the client does not know if the user has submitted a PAN or TAN. Used in Prepay, if desired.
  • Primary Account Number (PAN) – Usually the 16-digit card number. Can also accept Token Account Number if the Is PAN field is set to false. Neither TAN nor Alias ID is passed if this field is used. Used in Prepay, if desired.
  • Token Account Number (TAN) – 16-19-digit Visa Token Services issued token. Only TAN is accepted in this field. Neither PAN nor Alias ID is passed if this field is used. Used in Prepay, if desired.

API response

Response payload attributes are static except for Alias ID. Refer to VCES API Reference for more information.

Response payload attributes include:

  • Correlation ID – Partner-generated unique ID, 10-100 characters, for the API call used in the Validation operation.
  • Has PAN Matched – Indicates if a credential presented during the Prepay operation matches the credential presented during the Validate operation.
  • Response Timestamp – Current timestamp in GMT.
  • Status Code – VCES response code indicating the result of the operation. See VCES status codes and descriptions for more information.
  • Status Description – Verbose text indicating the result of the operation. See VCES status codes and descriptions for more information.
  • Alias ID – Unique 36-character ID generated by VCES for a credential; usable instead of PAN or VTS token.

Redemption overview

The operations are Redeem, iFrame Redemption, and Redeem iFrame. They notify Visa Card Eligibility Service (VCES) that a user has consumed an entitlement, using the same Correlation ID as the Validate call. This is the final step in a client's business process, after payment or entitlement consumption has been recorded.

API requests

The request payload includes these attributes. Refer to VCES API Reference for more information.

  • Correlation ID – Partner-generated unique ID, 10-100 characters, for the API call used in the Validation operation.
  • Vendor Unique ID (VUID) – Unique ID containing eligibility requirements and custom settings for the program. Also referenced as Program ID, VUID, or Promotion ID.
  • Request Timestamp – Current timestamp in GMT.
  • Mode – Informs VCES if the client is performing a redemption or reverse redemption call. Mode: 0 is set by default; there is no need to include it in redemption flows. Mode: 1 is used for a reverse redemption action.
  • Alias ID – Unique 36-character ID generated by VCES for a credential; usable instead of PAN or a Visa Token Services (VTS) token. Redeem iFrame requires this field instead of PAN or TAN.
  • Is Pan – This field is set to true by default, so it only needs to be passed if setting to false. False identifies the client does not know if the user has submitted a PAN or TAN. Used in Redeem, if desired.
  • Primary Account Number (PAN) – Usually the 16-digit card number. Can also accept Token Account Number if the Is PAN field is set to false. Neither TAN nor Alias ID is passed if this field is used. Used in Redeem, if desired.
  • Token Account Number (TAN) – 16-19-digit Visa Token Services issued token. Only TAN is accepted in this field. Neither PAN nor Alias ID is passed if this field is used. Used in Redeem, if desired.

API response

Response payload attributes are static except for Alias ID. Refer to VCES API Reference for more information.

Response attributes include:

  • Correlation ID – Partner-generated unique ID, 10-100 characters, for the API call.
  • Response Timestamp – Current timestamp in GMT.
  • Status Code – VCES response code indicating the result of the operation. See VCES status codes and descriptions for more information.
  • Status Description – Verbose text indicating the result of the operation. See VCES status codes and descriptions for more information.
  • Alias ID – Unique 36-character ID generated by VCES for a credential; usable instead of PAN or VTS token.