> ## Documentation Index
> Fetch the complete documentation index at: https://docs.digitalreceiptprotocol.org/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.

***

<Steps>
  <Step title="Generate Key Pair">
    **Endpoint:** `POST /api/v1/onboarding/generate-keys`

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

    **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
    </Tip>
  </Step>

  <Step title="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
    </Tip>

    <Note>
      `hashedPan` is SHA-256 hash of Primary Account Number. Card issuer application computes this—DRP never sees the actual PAN.
    </Note>
  </Step>

  <Step title="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",
        "drpMetadata": {
          "receiptId": "550e8400-e29b-41d4-a716-446655440003",
          "transactionId": "550e8400-e29b-41d4-a716-446655440005"
        }
      }
    }
    ```

    <Tip>
      **Copy:** `paymentId` and gateway name (`stripe` or `square`) → Step 5
    </Tip>

    <Warning>
      `recipientHashedPan` must match Step 2 hash
    </Warning>
  </Step>

  <Step title="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`
    </Tip>

    <Warning>
      Token expires in 2-3 minutes
    </Warning>
  </Step>

  <Step title="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"
      }
    }
    ```
  </Step>
</Steps>

***

## 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

<CardGroup cols={2}>
  <Card title="End-to-End Encryption" icon="lock">
    Receipt encrypted with user's public key. Only user's private key can decrypt.
  </Card>

  <Card title="Zero Knowledge" icon="eye-slash">
    DRP stores only hashed PAN. No access to account data or plaintext receipts.
  </Card>

  <Card title="User Consent" icon="fingerprint">
    Decryption requires biometric/PIN. Tokens expire in 2-3 minutes.
  </Card>

  <Card title="Private Key Security" icon="shield">
    Stored in device secure enclave. Never transmitted over network.
  </Card>
</CardGroup>