Insights and Verification

Pricing
Sandbox support

The Evervault API provides several endpoints that can be used to retrieve additional information for cards and BIN ranges. This can be used for tasks such as fraud detection and payment routing.

• Use the Card Insights endpoint to perform cardholder verification checks and enrichment.
• Use the BIN Lookup endpoint to retrieve metadata for a BIN range.
• Use the PAR Lookup endpoint to retrieve the Payment Account Reference (PAR) for a card number or network token.

Card Insights

The Card Insights API provides a powerful, real-time interface for card and cardholder verification checks and enrichment. It allows you to run:

• Address verification (AVS)
• Cardholder name verification (ANI)
• CVV validation
• Email and phone verification

You can also retrieve BIN information, the Payment Account Reference (PAR), and the push and pull transaction capabilities for disbursements and collections. Checks can run against either a card or a network token. By unifying these inputs, the API provides real-time assessments of card and cardholder authenticity alongside rich card metadata—enabling precise validation and smarter routing, handling, and fraud prevention.

Creating a card insight

You can run Card Insights against either a card (PAN) or a network token. Provide exactly one of card or networkToken per request.

Card Insights is extensible - you choose the insights you need per request. Every response includes BIN data by default. You can add any of the following extensions:

1. Address Verification (AVS) – Run AVS to verify postal code and street-level elements (line1, line2, city, state, country) against issuer records.
2. Name Verification – Run ANI to verify the provided name (first, last, middle, suffix, and owner type) against issuer records.
3. Transaction Capabilities – Determine push and pull transaction eligibility, network, regulatory status, and expected funds-availability windows.
4. CVV Validation – Validate the CVV against issuer records. Not available for network tokens.
5. Email Verification – Verify the provided email address against issuer records.
6. Phone Verification – Verify the provided phone number against issuer records.
7. Payment Account Reference (PAR) – Retrieve the Payment Account Reference for the card.

This example requests all possible extensions and includes both required and optional fields. The example response includes all possible fields.

1const response = await fetch("https://api.evervault.com/insights/cards", {
2  method: "POST",
3  headers: {
4    "Content-Type": "application/json",
5    Authorization: "Basic " + btoa("<app_id>:<api_key>"),
6  },
7  body: JSON.stringify({
8    card: {
9      number: "4111111111111111",
10      cvv: "123",
11      expiry: {
12        month: "12",
13        year: "29",
14      },
15    },
16    extensions: [
17      "capabilities",
18      "address",
19      "cardholder",
20      "cvv",
21      "email",
22      "phone",
23      "paymentAccountReference",
24    ],
25    address: {
26      postalCode: "10001",
27      line1: "Main Street",
28      line2: "Anytown",
29      city: "New York",
30      state: "NY",
31      country: "us",
32    },
33    cardholder: {
34      firstName: "John",
35      lastName: "Doe",
36      middleName: "Michael",
37      suffix: "Jr",
38      ownerType: "01",
39    },
40    email: "john.doe@example.com",
41    phone: "0016505551234",
42  }),
43});

Alternatively, provide a networkToken in place of card:

1body: JSON.stringify({
2  networkToken: {
3    number: "4111111111111111",
4    cryptogram: "AgAAAAAABk4DdZzBRckAAAAA",
5    expiry: {
6      month: "12",
7      year: "29",
8    },
9    // transactionIdentifier, brand, and funding are required for Amex and Discover
10    transactionIdentifier: "1234567890",
11    brand: "visa",
12    funding: "credit",
13  },
14  extensions: ["capabilities", "address", "paymentAccountReference"],
15  address: {
16    postalCode: "10001",
17    country: "us",
18  },
19});

Extensions and required fields

Request validation rules

There are some general rules that need to be followed for all strings fields. Failure to follow these will result in an error.

• All string fields must only consist of ASCII characters.
• Consecutive periods (.) will result in an error.

The following characters are restricted for all string fields:

Card fields:

• The number must be a valid card number (either in plaintext for as an Evervault encrypted string).
• The cvv must be a valid CVV for the given card brand.
• The month and year for the expiry must be 2 digit strings.

Transaction fields

• The amount must be a number.
• The currency must be a valid ISO-4217 three digit currency code.

Cardholder fields

• firstName and lastName are required when the cardholder extension is requested.
• middleName and suffix are optional and refine the name match.
• ownerType is optional and indicates whether the cardholder is the primary (01) or secondary (02) account owner.

For name fields there are additional character restrictions. These are outlined below. Failure to remove these will result in an error.

Email and phone fields:

Email and phone verification aren't widely supported by issuers, so coverage is limited.

• The email must be a valid email address. Required when the email extension is requested.
• The phone must be in IDD-prefixed E.164 format: E.164 international format with the 00 IDD prefix substituted for + (for example 0016505551234 for a US number). Required when the phone extension is requested.

Network token fields:

• The number must be a valid network token number (either in plaintext or as an Evervault encrypted string).
• The cryptogram must be a valid cryptogram (either in plaintext or as an Evervault encrypted string).
• The month and year for the expiry must be 2 digit strings.
• transactionIdentifier, brand, and funding are required for Amex and Discover network tokens.

Address fields

• If no country is provided, then it defaults to us.
• If the country is us (United States) then the postalCode must be a 5 or 9 digit string. The hyphen must be excluded.
• If the country is ca (Canada) then the postalCode must follow the Canadian postal code format (ANA NAN) e.g. A1A 1A1. The space character must be included.
• The state must be a valid ISO-3166 subdivision code. e.g ny for New York.
• The country must be a valid ISO-3166 two character country code.

BIN Lookup

The BIN Lookup API allows you to retrieve BIN data for a card number or BIN range. You can pass a plaintext card number, an encrypted card number, or the first 6-10 digits of a card number. If the number matches a range of BINs, the response returns metadata that is common to all the BINs in that range. The API key and app ID are required to authenticate the request, and the API key needs the binLookup:create permission.

1const response = await fetch("https://api.evervault.com/payments/bin-lookups", {
2  method: "POST",
3  headers: {
4    "Content-Type": "application/json",
5    Authorization: "Basic " + btoa("<app_id>:<api_key>"),
6  },
7  body: JSON.stringify({
8    number: "4242424242424242",
9  }),
10});

The response includes the BIN metadata, such as the card brand, the funding type, the country, and other relevant details.

1{
2  "id": "bin_lookup_1234567890",
3  "brand": "visa",
4  "funding": "credit",
5  "segment": "consumer",
6  "country": "gb",
7  "currency": "gbp",
8  "issuer": "Gringotts Wizarding Bank and Trust Company",
9  "type": "card",
10  "productName": "Visa Wizard",
11  "fastFunds": {
12    "domestic": true,
13    "crossBorder": true
14  },
15  "matchPrecision": 8,
16  "threeDS": {
17    "supportedVersions": {
18      "accessControlServer": ["2.2.0"],
19      "directoryServer": ["2.2.0", "2.3.1"]
20    },
21    "acsInfoIndicators": [
22      {
23        "code": "acs-auth-available",
24        "indicator": "01",
25        "description": "Authentication Available at ACS"
26      }
27    ]
28  },
29  "createdAt": 169297262323
30}

PAR Lookup

The PAR Lookup API returns the Payment Account Reference for a card number or network token. A PAR is a stable identifier the card network assigns to a card. Unlike a card number, it stays constant when a card is reissued, renewed, or replaced, and every network token derived from the card resolves to the same PAR.

This makes PAR useful for identifying when a network token and a physical card are the same underlying payment account. You can use the PAR to track a card across reissues, and linking its activity to a single cardholder for fraud detection or lifetime-value analysis.

To look up a PAR, send a plaintext or Evervault-encrypted card number or network token to the PAR Lookup endpoint. The API key and app ID are required to authenticate the request, and the API key needs the parLookup:create permission.

1const response = await fetch("https://api.evervault.com/payments/par-lookups", {
2  method: "POST",
3  headers: {
4    "Content-Type": "application/json",
5    Authorization: "Basic " + btoa("<app_id>:<api_key>"),
6  },
7  body: JSON.stringify({
8    number: "5204248250001003",
9  }),
10});

The response includes the resolved PAR, along with an identifier for the lookup.

1{
2  "id": "par_lookup_1234567890",
3  "paymentAccountReference": "5001BN2CUZCOY2H2IJILTJJZWTEPW"
4}