Visa Card Eligibility Service API Reference
Visa Card Eligibility Service
Visa Card Eligibility Service REST API
Validate v1 - Latest
The Validate operation checks if a credential is eligible for a VUID based on the configured eligibility criteria. The response attributes vary based on each implementation.
Request
Request Body schema: application/json
| correlationId required |
string non-empty Partner generated unique ID (10-25 characters) for the API call. Example: "qazwsxedc123" |
| requestTimeStamp required |
string non-empty The current GMT timestamp in mm/dd/yyyy hh:mm:ss tt format. Example: "2/1/2017 11:05:20 AM" |
| vendorUniqueId required |
string non-empty Unique ID containing eligibility requirements and custom settings for program. Also referenced as Program ID, VUID, or Promotion ID. Example: "TEST_VUID_123" |
| aliasId | string or null Unique ID (36 characters) generated by VCES corresponding to a credential. VCES will return AliasId in the response if the vendorUniqueId is configured. AliasId can be used in subsequent calls as a credential instead of 16 digit card number or VTS token. AliasIds are PCI compliant and valid for use ONLY in the same vendorUniqueId used to generate the AliasId. This field is conditionally required, as it is mutually exclusive with PAN and VTS token (only use one). Example: "42ef1b00-6315-4868-9618-73e2839fe497" |
| expirationDate | object Month (MM) and Year (YYYY) format expiry date of 16 digit card number. This field ONLY needs to be passed if using the $0 authorization (AVS) check. |
| month | string or null Month (MM) format expiry date of 16 digit card number. This field is conditionally optional (only needs to be passed if the vendorUniqueId is configured for $0 authorization check). Example: "01" |
| year | string or null Year (YYYY) format expiry date of 16 digit card number. This field is conditionally optional (only needs to be passed if the vendorUniqueId is configured for $0 authorization check). Example: "2000" |
| extendedData | string or null Free text field available for reporting purposes. Do not use commas (,), colons (:), or semicolons (;). This field is optional; most implementations will not use it. Example: "Premium" |
| isPan | boolean or null True if permanentAccountNumber is a 16 digit card number. False if permanentAccountNumber is a 16-19 digit VTS token OR if permanentAccountNumber's credential is unknown. This field is set to true by default, so it only needs to be passed if setting to false. Example: true |
| numberOfAdditionalRedemptions | integer or null The number of additional redemptions validated for eligibility. This field is conditionally optional (only needs to be passed if using additional redemptions within the same transaction). Example: 2 |
| permanentAccountNumber | string or null 16 digit card number OR 16-19 digit VTS token. If a certain 16 digit card number is passed, use this field. If uncertain whether a card number or VTS token is passed, place the 16 digit number in this field and set isPan field to False in the API request (VCES will automatically validate both). This field is conditionally required, as it is mutually exclusive with aliasId and tokenAccountNumber (only use one). Example: "4111111111111111" |
| tokenAccountNumber | string or null 16-19 digit VTS token. If certain, a VTS token is passed, use this field. If uncertain, whether a 16 digit card number or VTS token is passed, please use the permanentAccountNumber field and set isPan field to False in the API request (VCES will automatically validate both). This field is conditionally required, as it is mutually exclusive with aliasId and PAN (only use one). Example: "4222222222222222" |
Responses
200 OK
Response Schema: application/json
| cardId required |
string non-empty VCES generated unique numeric ID corresponding to a credential. Example: "56785678" |
| correlationId required |
string non-empty Partner generated unique ID (10-25 characters) for the API call. Example: "qazwsxedc123" |
| eligibilityLevel required |
string non-empty An indicator for the specific eligibility criteria validated within a vendorUniqueId. If a card is eligible for multiple levels, VCES will always return the highest (largest) eligibility level validated. Example: "1" |
| isEligible required |
string non-empty Indicates if a credential is eligible based on the criteria and configuration of the vendorUniqueId. Example: "True" |
| responseTimeStamp required |
string non-empty The current GMT timestamp in mm/dd/yyyy hh:mm:ss tt format. Example: "2/1/2017 11:05:20 AM" |
| statusCode required |
string non-empty VCES response code indicating result of the operation as defined by VCES. Example: "000" |
| statusDescription required |
string non-empty Verbose text indicating result of the operation as defined by VCES. Example: "Success" |
| acctFundSrce | string or null Account Funding Source as defined by VCES. For this field to be returned, vendorUniqueId needs to be configured. Example: "C" |
| acctFundSrceSubTyp | string or null Account Funding Source Sub Type as defined by VCES. For this field to be returned, vendorUniqueId needs to be configured. Example: "N" |
| aliasId | string or null Unique ID (36 characters) generated by VCES corresponding to a credential. VCES will return the AliasId in the response if configured. AliasId can be used in subsequent calls as a credential instead of 16 digit card number or VTS token. AliasIds are PCI compliant and valid for use ONLY in the same vendorUniqueId used to generate the AliasId. Example: "42ef1b00-6315-4868-9618-73e2839fe497" |
| benefitIndicator | string or null Deprecated Benefit indicator as defined by Visa. For this field to be returned, vendorUniqueId needs to be configured. |
| binIndicator | string or null Deprecated BIN indicator as defined by Visa. For this field to be returned, vendorUniqueId needs to be configured. |
| cardBenefits | Array of objects or null |
| Array |
| benefitDesc | string or null Verbose text describing the CardEnhanceTypeCode from VFS/VDBP. For this field to be returned, vendorUniqueId needs to be configured. Example: "High quality emergency assistance for Visa cardholders accessible via tollfree line 24 hours a day, 7 days a week, and 365 days a year. Terms and Conditions apply." |
| benefitName | string or null Verbose name of the CardEnhanceTypeCode from VFS/VDBP. For this field to be returned, vendorUniqueId needs to be configured. Example: "(GCAS) Global Center Customer Services" |
| cardEnhanceTypeCode | string or null Benefit type code from VFS/VDBP. For this field to be returned, vendorUniqueId needs to be configured. Example: "GCAS" |
| phoneNumberDetails | string or null Phone number of service provider for given benefit. For this field to be returned, vendorUniqueId needs to be configured. Example: "1-800-847-2911" |
| countryCode | string or null Country Code as defined by VCES. For this field to be returned, vendorUniqueId needs to be configured. Example: "840" |
| entityToBeBilled | object Details of who to bill for redemptions based on vendorUniqueId setup. |
| additionalRedemptionCharges | Array of strings or null List of charge owners for guest redemptions. For this field to be returned, vendorUniqueId needs to be configured. |
| memberCharge | string or null Charge owner for cardholder redemption. For this field to be returned, vendorUniqueId needs to be configured. Example: "Issuer" |
| issuerBid | string or null Business identification (BID) as defined by Visa. For this field to be returned, vendorUniqueId needs to be configured. Example: "12345678" |
| platformCode | string or null Product platform, based on account level processing, as defined by VCES. The broadest categorization of the card product reflecting the general product platform or family that the product exists. |
| productSubType | string or null Product Sub Type as defined by VCES. For this field to be returned, vendorUniqueId needs to be configured. Example: "AC" |
| productType | string or null Product Type as defined by VCES. For this field to be returned, vendorUniqueId needs to be configured. Example: "A" |
| redemptionDetails | object Verbose text indicating redemption details based on vendorUniqueId setup. |
| allowed | object Verbose details on allowed/configured redemptions. Allowed redemptions are the counts per duration configured for the vendorUniqueId or for the corresponding eligibilityLevel. |
| additionalRedemptionsPerTransaction | integer or null Number of additional redemptions allowed per redemption. For this field to be returned, vendorUniqueId needs to be configured. Example: 2 |
| count | string or null Number of allowed redemptions configured based on the vendorUniqueId or eligibilityLevel. For this field to be returned, vendorUniqueId needs to be configured. Example: "3" |
| duration | object Details on the period in which redemptions are tracked. |
| type | string or null Indicates period type in which redemptions are tracked. For this field to be returned, vendorUniqueId needs to be configured. Example: "Years" |
| value | string or null Indicates the number of periods in which redemptions are tracked. For this field to be returned, vendorUniqueId needs to be configured. Example: "1" |
| eligibleRedemptions | object Verbose details on the eligible redemptions available. |
| count | integer Total number of eligible redemptions available for redemption for this specific validation. For this field to be returned, vendorUniqueId needs to be configured. Example: 3 |
| coveredAdditionalRedemptions | integer Number of eligible additional redemptions available for redemption for this specific validation. For this field to be returned, vendorUniqueId needs to be configured. Example: 2 |
| requestedAdditionalRedemptions | integer Total number of requested additional redemptions for this specific validation. For this field to be returned, vendorUniqueId needs to be configured. Example: 1 |
| isUnlimited | string or null True indicates unlimited redemptions are available. False indicates restrictions are redemptions. For this field to be returned, vendorUniqueId needs to be configured. Example: "False" |
| pooled | boolean or null For each redemption, if pooled is true, number of redemptions = cardholder (1) + number of additional redemptions. If pooled is false, number of redemptions = cardholder (1). For this field to be returned, vendorUniqueId needs to be configured. |
| used | object Verbose details on redemptions already used. |
| additionalRedemptionDetails | object Timestamp data for used additional redemptions. |
| timeStamp | Array of strings or null List of timestamps for additional redemptions. For this field to be returned, vendorUniqueId needs to be configured. |
| additionalRedemptions | integer or null Number of additional redemptions used. For this field to be returned, vendorUniqueId needs to be configured. Example: 1 |
| count | string or null Count of redemptions used. For this field to be returned, vendorUniqueId needs to be configured. Example: "3" |
| details | object Timestamp data for used redemptions. |
| timeStamp | Array of strings or null List of timestamps for additional redemptions. For this field to be returned, vendorUniqueId needs to be configured. |
| rpin | string or null Rewards Program Identification Number (RPIN) as defined by Visa. For this field to be returned, vendorUniqueId needs to be configured. Example: "123456" |
| spendTierCurrencyCode | string or null Currency code of amount returned in spendTierAmount as defined by VCES. For this field to be returned, vendorUniqueId needs to be configured. Example: "840" |
| spendTierSpendAmount | string or null Largest amount of eligible spend performed on a credential based qualified on configured spend tiers. For this field to be returned, vendorUniqueId needs to be configured. Example: "100.00" |
400 Bad Request
403 Forbidden Operation to requested resource
500 Temporary Downtime - retry operation after waiting
503 Temporary Downtime for maintenance - retry operation after waiting
post/visacardeligibilityservices/v1/cardeligibility/validate
Sandbox server
https://sandbox.api.visa.com/visacardeligibilityservices/v1/cardeligibility/validate
Copy
Request samples
- Payload
application/json
{"correlationId": "qazwsxedc123",
"vendorUniqueId": "TEST_VUID_123",
"requestTimeStamp": "2/1/2017 11:05:20 AM",
"permanentAccountNumber": "4111111111111111"
}
Response samples
- 200
application/json
{"cardId": "1",
"isEligible": "True",
"statusCode": "000",
"correlationId": "qazwsxedc123",
"eligibilityLevel": "1",
"responseTimeStamp": "2/1/2017 11:05:20 AM",
"statusDescription": "Success"
}