> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veromerchants.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Technical Flow

> Step-by-step API integration guide with request/response examples. Copy values from each response to use in subsequent steps.

***

**1. Generate Key Pair**

**Endpoint:** `POST /api/v1/onboarding/generate-keys`

**Caller:** Card Issuer Application (when user enables Vero)

**Request:** None

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "keyId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...",
    "privateKey": "MIIEvgIBADANBgkqhkiG9w0BAQEFAASC...",
    "algorithm": "RSA-OAEP-256"
  }
}
```

> [!TIP]
>
> **Copy these values:**
>
> * `keyId` → Steps 2, 4
> * `publicKey` → Step 2
> * `privateKey` → Step 5

**2. Register User**

**Endpoint:** `POST /api/v1/onboarding/register`

**Caller:** Card Issuer Application

**Request:**

```json theme={null}
{
  "hashedPan": "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8",
  "publicKey": "<from Step 1>",
  "keyId": "<from Step 1>"
}
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "userId": "usr_f8e7d6c5-b4a3-4c2d-1e0f-9a8b7c6d5e4f",
    "status": "active",
    "registeredAt": "2025-12-18T10:30:00Z"
  }
}
```

> [!TIP]
>
> **Copy:** `userId` → Step 4

> [!NOTE]
>
> `hashedPan` is SHA-256 hash of Primary Account Number. Card issuer application computes this—Vero never sees the actual PAN.

**3. Create Payment with Encrypted Receipt**

**Endpoint:** `POST /api/v1/payments/{gateway}/create`

**Caller:** Merchant POS (when user taps card)

**Request:**

```json theme={null}
{
  "version": "1.0",
  "receiptId": "550e8400-e29b-41d4-a716-446655440003",
  "merchantId": "550e8400-e29b-41d4-a716-446655440004",
  "merchantName": "Coffee Shop",
  "merchantStreet": "123 Main St",
  "merchantCity": "New York",
  "merchantState": "NY",
  "merchantPostalCode": "10001",
  "merchantCountry": "US",
  "transactionId": "550e8400-e29b-41d4-a716-446655440005",
  "transactionDate": "2025-12-18T12:30:00Z",
  "transactionTimezone": "America/New_York",
  "paymentMethod": "card",
  "cardLast4": "4242",
  "cardBrand": "visa",
  "currency": "USD",
  "subtotal": 420,
  "taxAmount": 34,
  "totalAmount": 454,
  "items": [
    {
      "lineItemId": "550e8400-e29b-41d4-a716-446655440006",
      "name": "Latte",
      "quantity": 1,
      "unitPrice": 420,
      "totalPrice": 420
    }
  ],
  "recipientHashedPan": "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8",
  "amount": 454,
  "cardNonce": "cnon:card-nonce-ok"
}
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "paymentId": "pi_stripe_abc123",
    "clientSecret": "pi_stripe_abc123_secret_xyz",
    "veroMetadata": {
      "receiptId": "550e8400-e29b-41d4-a716-446655440003",
      "transactionId": "550e8400-e29b-41d4-a716-446655440005"
    }
  }
}
```

> [!TIP]
>
> **Copy:** `paymentId` and gateway name (`stripe` or `square`) → Step 5

> [!WARNING]
>
> `recipientHashedPan` must match Step 2 hash

**4. Grant Decrypt Access**

**Endpoint:** `POST /api/v1/keys/grant-access`

**Caller:** Card Issuer Application (when user taps "View Receipt")

**Request:**

```json theme={null}
{
  "userId": "<from Step 2>",
  "keyId": "<from Step 1>"
}
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "tokenId": "tok_9a8b7c6d-5e4f-3a2b-1c0d-e9f8a7b6c5d4",
    "userId": "usr_f8e7d6c5-b4a3-4c2d-1e0f-9a8b7c6d5e4f",
    "keyId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "purpose": "decrypt",
    "grantedAt": "2025-12-18T10:35:00Z",
    "expiresAt": "2025-12-18T10:38:00Z",
    "sourceIp": "192.168.1.100"
  }
}
```

> [!TIP]
>
> **Copy:** `tokenId` → Step 5 as `accessTokenId`

> [!WARNING]
>
> Token expires in 2-3 minutes

**5. Decrypt Receipt**

**Endpoint:** `POST /api/v1/payments/decrypt`

**Caller:** Card Issuer Application

**Request:**

```json theme={null}
{
  "paymentId": "<from Step 3>",
  "gateway": "stripe",
  "accessTokenId": "<from Step 4>",
  "privateKey": "<from Step 1>"
}
```

**Response:**

```json theme={null}
{
  "success": true,
  "data": {
    "version": "1.0",
    "receiptId": "550e8400-e29b-41d4-a716-446655440003",
    "merchant": {
      "merchantId": "550e8400-e29b-41d4-a716-446655440004",
      "name": "Coffee Shop",
      "address": {
        "street": "123 Main St",
        "city": "New York",
        "state": "NY",
        "postalCode": "10001",
        "country": "US"
      }
    },
    "transaction": {
      "transactionId": "550e8400-e29b-41d4-a716-446655440005",
      "datetime": "2025-12-18T12:30:00Z",
      "paymentMethod": "card",
      "cardDetails": {
        "last4": "4242",
        "brand": "visa"
      }
    },
    "items": [
      {
        "lineItemId": "550e8400-e29b-41d4-a716-446655440006",
        "name": "Latte",
        "quantity": 1,
        "unitPrice": 420,
        "totalPrice": 420
      }
    ],
    "summary": {
      "subtotal": 420,
      "totalTax": 34,
      "total": 454,
      "currency": "USD",
      "itemCount": 1
    },
    "createdAt": "2025-12-18T12:30:00Z"
  }
}
```

***

## Summary

| Step | Endpoint | Caller | Input | Output |
| - | - | - | - | - |
| 1 | `POST /onboarding/generate-keys` | Card Issuer App | - | keyId, publicKey, privateKey |
| 2 | `POST /onboarding/register` | Card Issuer App | hashedPan, publicKey, keyId | userId |
| 3 | `POST /payments/{gateway}/create` | Merchant POS | receipt data, recipientHashedPan | paymentId |
| 4 | `POST /keys/grant-access` | Card Issuer App | userId, keyId | tokenId (2-3 min TTL) |
| 5 | `POST /payments/decrypt` | Card Issuer App | paymentId, tokenId, privateKey | Decrypted receipt |

***

## Security

> **End-to-End Encryption**
>
> Receipt encrypted with user's public key. Only user's private key can decrypt.

> **Zero Knowledge**
>
> Vero stores only hashed PAN. No access to account data or plaintext receipts.

> **User Consent**
>
> Decryption requires biometric/PIN. Tokens expire in 2-3 minutes.

> **Private Key Security**
>
> Stored in device secure enclave. Never transmitted over network.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.