# 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](https://developer.visa.com/capabilities/vces/response-codes-and-descriptions#section0).
Example: "000" |
| statusDescription
required | string non-empty
Verbose text indicating result of the operation as [defined by VCES](https://developer.visa.com/capabilities/vces/response-codes-and-descriptions#section0).
Example: "Success" |
| acctFundSrce | string or null
Account Funding Source as [defined by VCES](https://developer.visa.com/capabilities/vces/response-codes-and-descriptions#section5). 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](https://developer.visa.com/capabilities/vces/response-codes-and-descriptions#section6). 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](https://developer.visa.com/capabilities/vces/response-codes-and-descriptions#section2). 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](https://developer.visa.com/capabilities/vces/response-codes-and-descriptions#section3). 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](https://developer.visa.com/capabilities/vces/response-codes-and-descriptions#section4). For this field to be returned, vendorUniqueId needs to be configured.
Example: "AC" |
| productType | string or null
Product Type as [defined by VCES](https://developer.visa.com/capabilities/vces/response-codes-and-descriptions#section1). 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](https://developer.visa.com/capabilities/vces/response-codes-and-descriptions#section3). 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
```json
{"correlationId": "qazwsxedc123",
"vendorUniqueId": "TEST_VUID_123",
"requestTimeStamp": "2/1/2017 11:05:20 AM",
"permanentAccountNumber": "4111111111111111"
}
```
### Response samples
- 200
application/json
```json
{"cardId": "1",
"isEligible": "True",
"statusCode": "000",
"correlationId": "qazwsxedc123",
"eligibilityLevel": "1",
"responseTimeStamp": "2/1/2017 11:05:20 AM",
"statusDescription": "Success"
}
```