Skip to main content

​
Digital Receipt Protocol API Reference

The DRP API enables secure, encrypted receipt transmission between merchants, card issuers, and end users. All APIs use RESTful principles with JSON payloads and industry-standard authentication.

​
API Overview

​
Base URL

  • Production: https://api.digitalreceiptprotocol.org
  • Staging: https://staging-api.digitalreceiptprotocol.org
  • Local Development: http://localhost:3000
The DRP API provides centralized key management, receipt encryption/decryption, and transaction storage services.

​
Authentication

Most endpoints require authentication using an API key in the request header: 
GET /api/v1/receipts/{userId}
X-API-Key: your_api_key_here
Content-Type: application/json
API keys are managed through the DRP platform and provide access to the API based on your subscription tier.

​
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 DRP

​
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

All monetary values are represented in the smallest currency unit (e.g., cents for USD). Example: $42.00 = 4200

​
Rate Limits

Rate limits vary by subscription tier and endpoint. Contact support for specific limits applicable to your API key. Rate limit headers returned with each response: 
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

CodeHTTP StatusDescription
invalid_request400Request validation failed
unauthorized401Invalid or missing API key
forbidden403Access denied for this resource
not_found404Resource not found
rate_limit_exceeded429Too many requests
internal_server_error500Internal server error
service_unavailable503Service temporarily unavailable

​
Retry Logic

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);
  }
}
Retry these errors: 429, 500, 502, 503, 504, network timeouts
Don’t retry: 400, 401, 403, 404, 409

​
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

API versioned in URL path: /v1/, /v2/, etc. Backwards Compatibility Promise:
  • Breaking changes require new version
  • Previous versions supported for minimum 12 months after deprecation notice
  • Deprecation notices provided 6 months in advance
Non-breaking changes (no version change):
  • Adding new optional fields
  • Adding new endpoints
  • Adding new error codes
  • Increasing rate limits

​
Next Steps

1

Get API Access

Contact the DRP team to obtain your API key
2

Review API Endpoints

Explore the detailed endpoint documentation in the API Reference section
3

Test in Staging

Use the staging environment to test your integration
4

Implement Key Management

Set up secure key generation and storage for your users
5

Go Live

Deploy to production with your production API key