> ## Documentation Index
> Fetch the complete documentation index at: https://yn-c9bb3266.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Card Fingerprint

> Identify unique cards across transactions without storing sensitive card data.

## Overview

Card fingerprinting generates a unique, deterministic identifier for each physical card used in your system. This fingerprint remains consistent across transactions, allowing you to identify when the same card is used multiple times -- without storing or exposing the actual card number. Card fingerprints are essential for fraud detection, loyalty programs, and analytics.

## How It Works

When a card is used in a transaction or stored in Yuno's vault, a **card fingerprint** is generated using a one-way hash of the card's PAN and other identifying attributes. The same card always produces the same fingerprint, regardless of which merchant or transaction it is used with.

```
Card PAN: 4242 4242 4242 4242
    │
    └── Hash function ──> Fingerprint: "fp_a1b2c3d4e5f6g7h8"
```

<Info>
  Card fingerprints are irreversible. You cannot derive the card number from a fingerprint. This makes fingerprints safe to store and use in your application without PCI compliance concerns.
</Info>

## Fingerprint in API Responses

Card fingerprints are automatically included in payment and tokenization responses:

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "id": "pay_abc123",
  "status": "APPROVED",
  "payment_method": {
    "type": "CARD",
    "card": {
      "last_four": "4242",
      "brand": "VISA",
      "fingerprint": "fp_a1b2c3d4e5f6g7h8"
    }
  }
}
```

## Use Cases

| Use Case                 | How Fingerprint Helps                                   |
| ------------------------ | ------------------------------------------------------- |
| **Fraud detection**      | Detect the same card used across multiple accounts      |
| **Duplicate prevention** | Prevent the same card from being enrolled twice         |
| **Loyalty programs**     | Track rewards across transactions for the same card     |
| **Velocity checks**      | Count transactions per unique card within a time window |
| **Analytics**            | Understand unique card usage patterns                   |
| **Account linking**      | Identify when multiple accounts share a payment method  |

## Fraud Detection Example

Detect if a single card is being used across multiple customer accounts:

```javascript theme={"theme":{"light":"github-dark","dark":"github-dark"}}
// When a payment is processed, check the fingerprint
const fingerprint = paymentResponse.payment_method.card.fingerprint;

// Query your database for other accounts using this fingerprint
const existingAccounts = await db.query(
  "SELECT customer_id FROM payment_methods WHERE fingerprint = ? AND customer_id != ?",
  [fingerprint, currentCustomerId]
);

if (existingAccounts.length > 0) {
  // Flag for review: same card used across multiple accounts
  await flagForReview({
    reason: "SHARED_CARD",
    fingerprint: fingerprint,
    accounts: existingAccounts
  });
}
```

## Velocity Check Example

Limit the number of transactions from a single card within a time window:

```javascript theme={"theme":{"light":"github-dark","dark":"github-dark"}}
const fingerprint = paymentRequest.card.fingerprint;
const oneHourAgo = new Date(Date.now() - 3600000);

const recentTransactions = await db.query(
  "SELECT COUNT(*) as count FROM transactions WHERE fingerprint = ? AND created_at > ?",
  [fingerprint, oneHourAgo]
);

if (recentTransactions.count >= 5) {
  // Block: too many transactions from this card in 1 hour
  throw new Error("VELOCITY_LIMIT_EXCEEDED");
}
```

<Warning>
  Card fingerprints are consistent within the Yuno ecosystem but may differ from fingerprints generated by other payment processors. Do not compare Yuno fingerprints with those from external systems.
</Warning>

## Fingerprint Properties

| Property       | Value                                            |
| -------------- | ------------------------------------------------ |
| Format         | String (alphanumeric, prefixed with `fp_`)       |
| Uniqueness     | One fingerprint per unique physical card         |
| Deterministic  | Same card always produces the same fingerprint   |
| Reversible     | No -- cannot derive card number from fingerprint |
| Cross-merchant | Same fingerprint across all merchants on Yuno    |
| PCI sensitive  | No -- safe to store in your database             |

<Note>
  A card fingerprint is tied to the physical card PAN, not the cardholder. If a card is reissued with a new number, it will generate a different fingerprint. Use [Network Tokens](/features/network-tokens) to maintain continuity across card reissuances.
</Note>

## Best Practices

* **Store fingerprints**: Save fingerprints in your database alongside transaction records for analysis.
* **Index for queries**: Create database indexes on the fingerprint column for fast lookups.
* **Combine with device data**: Use fingerprints alongside device fingerprinting for stronger fraud detection.
* **Respect privacy**: While fingerprints are not PCI-sensitive, they are still personal data. Handle according to your privacy policy.