Skip to main content

​
Technical Flow

Complete step-by-step guide showing how all the pieces of the Digital Receipt Protocol work together, from user onboarding to receipt retrieval.

​
What Happens Behind the Scenes

1

Generate Key Pair

Create an RSA-2048 key pair for a new user
POST /api/v1/onboarding/generate-keys
Response includes public and private keys. Store the private key securely on the client device.
2

Register User

Onboard the user with their identifiers and public key
POST /api/v1/onboarding/register
X-API-Key: your_api_key
Content-Type: application/json

{
  "userId": "user123",
  "email": "[email protected]",
  "phoneNumber": "+1234567890",
  "publicKey": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
}
3

Encrypt Receipt

When a transaction occurs, encrypt the receipt data with the user’s public key
POST /api/v1/receipts/encrypt
X-API-Key: your_api_key
Content-Type: application/json

{
  "userId": "user123",
  "receiptData": {
    "merchantName": "Coffee Shop",
    "amount": 4200,
    "currency": "USD",
    "items": [...]
  }
}
Returns encrypted receipt data using AES-256-GCM with RSA key wrapping.
4

Store Receipt

Store the encrypted receipt linked to the transaction
POST /api/v1/receipts
X-API-Key: your_api_key
Content-Type: application/json

{
  "userId": "user123",
  "encryptedReceipt": "encrypted_base64_data...",
  "transactionId": "txn_abc123",
  "metadata": {
    "merchantId": "merchant_001",
    "amount": 4200,
    "timestamp": "2025-12-15T10:30:00Z"
  }
}
5

Request Access Token

User requests a short-lived access token to decrypt their receipt
POST /api/v1/keys/request-access
X-API-Key: your_api_key
Content-Type: application/json

{
  "userId": "user123",
  "receiptId": "receipt_xyz789"
}
Returns a time-limited access token (valid for 2-3 minutes).
6

Retrieve and Decrypt

Fetch the encrypted receipt and decrypt client-side
GET /api/v1/receipts/{userId}
X-API-Key: your_api_key
X-Access-Token: short_lived_token
Client receives encrypted receipt and decrypts it using their private key stored in the device’s secure enclave.

​
Security Flow Diagram

The following diagram illustrates the complete security flow from key generation through receipt decryption:

​
User Onboarding Flow

​
Initial Setup

When a new user signs up for your application:
  1. Client generates keys - Call /api/v1/onboarding/generate-keys
    • Returns RSA-2048 public/private key pair
    • Client stores private key in device secure storage (iOS Secure Enclave, Android KeyStore)
    • Never transmit private key over network
  2. Client registers user - Call /api/v1/onboarding/register
    • Send user identifiers (email, phone, card number)
    • Send public key
    • DRP API associates public key with user identifiers
  3. User is ready - User can now receive encrypted receipts

​
Key Storage Requirements

Critical: Private keys must NEVER leave the user’s device. Store them in:
  • iOS: Secure Enclave via Keychain Services
  • Android: Android KeyStore System
  • Web: IndexedDB with Web Crypto API (less secure, not recommended for sensitive data)

​
Receipt Encryption Flow

​
Merchant Workflow

When a transaction completes:
  1. Merchant identifies user - Via card token, email, or phone number
  2. Merchant encrypts receipt - Call /api/v1/receipts/encrypt
    • Provide user identifier
    • Provide receipt data (merchant name, amount, items, etc.)
    • DRP API encrypts using user’s public key (AES-256-GCM with RSA key wrapping)
  3. Merchant stores encrypted receipt - Call /api/v1/receipts
    • Store encrypted receipt data
    • Link to transaction ID
    • Add metadata (merchant ID, amount, timestamp)

​
Receipt Data Format

Receipt data should include: 
{
  "merchantName": "Coffee Shop",
  "merchantAddress": "123 Main St, San Francisco, CA",
  "amount": 4200,
  "currency": "USD",
  "timestamp": "2025-12-15T10:30:00Z",
  "items": [
    {
      "name": "Latte",
      "quantity": 2,
      "price": 2100
    }
  ],
  "tax": 336,
  "tip": 840,
  "paymentMethod": "Visa ****1234"
}
Pricing Format: All amounts are in the smallest currency unit (cents for USD).Example: $42.00 = 4200

​
Receipt Retrieval Flow

​
User/Client Workflow

When a user wants to view their receipts:
  1. Request access token - Call /api/v1/keys/request-access
    • Provide user ID and receipt ID
    • Receive short-lived access token (valid 2-3 minutes)
  2. Fetch encrypted receipt - Call /api/v1/receipts/{userId}
    • Include access token in headers
    • Receive encrypted receipt data
  3. Decrypt client-side - Use stored private key
    • Decrypt using device secure storage (Secure Enclave/KeyStore)
    • Never send private key over network
    • Display decrypted receipt to user

​
Access Token Security

Access tokens are intentionally short-lived (2-3 minutes) to minimize security risks:
  • Limits exposure window if token is intercepted
  • Forces fresh authentication for each receipt access
  • Tokens automatically expire and cannot be reused
  • New token required for each receipt retrieval

​
Error Scenarios

​
User Not Onboarded

If a user hasn’t onboarded yet, the encrypt endpoint will return an error: 
{
  "error": "user_not_found",
  "message": "User not registered with DRP",
  "suggestedAction": "Prompt user to onboard or use escrow encryption"
}
Solution: Either prompt the user to onboard, or use escrow encryption for later retrieval.

​
Access Token Expired

Access tokens expire after 2-3 minutes: 
{
  "error": "token_expired",
  "message": "Access token has expired",
  "suggestedAction": "Request a new access token"
}
Solution: Request a new access token via /api/v1/keys/request-access.

​
Private Key Lost

If a user loses their private key (e.g., device reset):
  • Cannot decrypt old receipts - This is by design for security
  • Solution: Generate new key pair and re-onboard
  • Best practice: Implement key backup mechanisms in your app

​
Security Best Practices

Key Storage

Always store private keys in device secure storage:
  • iOS: Secure Enclave
  • Android: KeyStore
  • Never in plain text or regular storage

Access Tokens

Use short-lived access tokens:
  • Request fresh token for each receipt
  • Don’t cache or reuse tokens
  • Tokens expire in 2-3 minutes

API Keys

Protect your API keys:
  • Use environment variables
  • Never commit to source control
  • Rotate regularly
  • Use different keys for dev/staging/prod

HTTPS Only

Always use HTTPS:
  • All API calls must use HTTPS
  • Verify SSL certificates
  • Don’t bypass certificate validation

​
Next Steps

Integration Examples

See complete code examples for Node.js, Python, and Go

API Endpoints

Review detailed API endpoint documentation

SDKs

Use official SDKs for faster integration

Authentication Guide

Learn about API key management