API Reference

​

Base URL

• Production: https://api.digitalreceiptprotocol.org
• Staging: https://staging-api.digitalreceiptprotocol.org
• Local Development: http://localhost:3000

​

Authentication

GET /api/v1/receipts/{userId}
X-API-Key: your_api_key_here
Content-Type: application/json

​

Core Concepts

​

User Onboarding

1. Generate key pair - Create RSA-2048 keys for new users
2. Register user - Associate keys with user identifiers (email, phone, card)
3. Store securely - Private keys stored client-side, public keys managed by Vero

​

Receipt Encryption & Decryption

1. Encrypt receipts - Encrypt receipt data with user’s public key using AES-256-GCM
2. Store encrypted - Save encrypted receipts linked to transactions
3. Request access - Generate short-lived access tokens for decryption
4. Decrypt client-side - Users decrypt receipts with their private keys

​

Cryptographic Standards

• Key Generation: RSA-2048 for asymmetric encryption
• Receipt Encryption: AES-256-GCM with RSA-OAEP-SHA256 key wrapping
• Access Tokens: Short-lived (2-3 minutes) for enhanced security
• Escrow Support: Encrypted receipts for non-onboarded users

​

Pricing Format

​

Rate Limits

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1670423400

​

Error Handling

​

Standard Error Response

{
  "error": {
    "code": "invalid_signature",
    "message": "Merchant signature verification failed",
    "details": "The provided signature does not match the receipt content",
    "timestamp": "2025-12-07T19:45:00Z",
    "request_id": "req_abc123"
  }
}

​

Common Error Codes

​

Retry Logic

​

Recommended Retry Strategy

const maxRetries = 3;
const backoffMultiplier = 2;

async function sendReceiptWithRetry(receipt, attempt = 1) {
  try {
    return await sendReceipt(receipt);
  } catch (error) {
    if (attempt >= maxRetries) throw error;

    // Don't retry client errors (4xx except 429)
    if (error.status >= 400 && error.status < 500 && error.status !== 429) {
      throw error;
    }

    const delay = Math.pow(backoffMultiplier, attempt) * 1000;
    await sleep(delay);
    return sendReceiptWithRetry(receipt, attempt + 1);
  }
}

​

Environments

​

Production Environment

• Purpose: Live production use
• Base URL: https://api.digitalreceiptprotocol.org
• Authentication: Production API keys
• Data: Real user data - handle securely

​

Staging Environment

• Purpose: Testing and integration
• Base URL: https://staging-api.digitalreceiptprotocol.org
• Authentication: Staging API keys
• Data: Test data only

​

Local Development

• Purpose: Local development and testing
• Base URL: http://localhost:3000
• Authentication: Development API keys
• Data: Local test data

​

Versioning

​

Current Version: v1

• Breaking changes require new version
• Previous versions supported for minimum 12 months after deprecation notice
• Deprecation notices provided 6 months in advance

• Adding new optional fields
• Adding new endpoints
• Adding new error codes
• Increasing rate limits

​

Next Steps