Insights

The Evervault API provides several endpoints which 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.

• The Inspect endpoint allows you to retrieve metadata for an encrypted card number.
• The BIN Lookup endpoint allows you to retrieve metadata for a BIN range.
• The CardInsights endpoint allows you to perform cardholder verification checks and enrichment.

Inspect

The Inspect endpoint allows you to retrieve metadata for an encrypted card. This can be used to retrieve information such as the card brand, the last four digits, and more.

To retrieve metadata for an encrypted card, send the encrypted card number to the Inspect API endpoint. The API key and app ID are required to authenticate the request, and the API key needs the api:inspect permission.

1const response = await fetch("https://api.evervault.com/payments/inspect", {
2  method: "POST",
3  headers: {
4    "Content-Type": "application/json",
5    Authorization: "Basic " + btoa("<app_id>:<api_key>"),
6  },
7  body: JSON.stringify({
8    token:
9      "ev:debug:Tk9D:HBpzdbFWXbX/N2cC:AyjMY/SKO49SlkXcDPtCGs+DxnUn/F8/lAtajCYZ/xT7:KV7AUn9vJJkZDtL8PKdOc8Y11yTL2vZQasFuHqM=:$",
10  }),
11});

The API will respond with an object containing details about the encrypted data as well as the card metadata inside of the metadata field.

1{
2  "type": "string",
3  "category": "card-number",
4  "encryptedAt": 1700067122000,
5  "role": null,
6  "fingerprint": "u0ljSwrqhhUv7GykyCHB/A2bgVGXq06fnG9bOI27Sbg/tAOz3myr5zsfbasEWuMLiH6jZayu3AHGfiB7l+Bbjg",
7  "metadata": {
8    "bin": "424242",
9    "lastFour": "4242",
10    "brand": "visa",
11    "funding": "debit",
12    "segment": "consumer",
13    "country": "gb",
14    "currency": "gbp",
15    "issuer": "Gringotts Wizarding Bank and Trust Company"
16  }
17}

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-lookup", {
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  "threeDS": {
16    "supportedVersions": {
17      "accessControlServer": ["2.2.0"],
18      "directoryServer": ["2.2.0", "2.3.1"]
19    },
20    "acsInfoIndicators": [
21      {
22        "code": "acs-auth-available",
23        "indicator": "01",
24        "description": "Authentication Available at ACS"
25      }
26    ]
27  },
28  "createdAt": 169297262323
29}

BIN Lookup vs Inspect

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), and CVV validation. You can also retrieve BIN information, interchange and network fee estimates, and the push and pull transaction capabilities for disbursements and collections. 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

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 first and last name against issuer records.
3. Fees – Receive estimated network and interchange fees for specified transaction types to support transparent pricing and optimisation.
4. Transaction Capabilities – Determine push and pull transaction eligibility, network, regulatory status, and expected funds-availability windows.
5. CVV Validation – Validate the CVV against issuer records.

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/payments/bin-lookup", {
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: ["capabilities", "fees", "address", "cardholder", "cvv"],
17    transaction: {
18      amount: 2500,
19      currency: "usd",
20    },
21    address: {
22      postalCode: "10001",
23      line1: "Main Street",
24      line2: "Anytown",
25      city: "New York",
26      state: "NY",
27      country: "us",
28    },
29    cardholder: {
30      firstName: "John",
31      lastName: "Doe",
32    },
33  }),
34});

Extensions & Required fields