Integration Examples

Complete, production-ready code examples showing how to integrate with the DRP API using different languages and frameworks.

Node.js / JavaScript

Complete Integration Example

const axios = require('axios');

const API_BASE = 'https://api.digitalreceiptprotocol.org';
const API_KEY = 'your_api_key_here';

// Step 1: Generate keys for new user
async function generateKeys() {
  const response = await axios.post(`${API_BASE}/api/v1/onboarding/generate-keys`);
  return response.data; // { publicKey, privateKey }
}

// Step 2: Register user
async function registerUser(userId, email, publicKey) {
  const response = await axios.post(
    `${API_BASE}/api/v1/onboarding/register`,
    { userId, email, publicKey },
    { headers: { 'X-API-Key': API_KEY } }
  );
  return response.data;
}

// Step 3: Encrypt and store receipt
async function storeReceipt(userId, receiptData, transactionId) {
  // First encrypt
  const encrypted = await axios.post(
    `${API_BASE}/api/v1/receipts/encrypt`,
    { userId, receiptData },
    { headers: { 'X-API-Key': API_KEY } }
  );

  // Then store
  const stored = await axios.post(
    `${API_BASE}/api/v1/receipts`,
    {
      userId,
      encryptedReceipt: encrypted.data.encryptedData,
      transactionId,
      metadata: {
        merchantId: 'merchant_001',
        amount: receiptData.amount,
        timestamp: new Date().toISOString()
      }
    },
    { headers: { 'X-API-Key': API_KEY } }
  );

  return stored.data;
}

// Step 4: Retrieve receipt
async function getReceipt(userId, receiptId) {
  // Request access token
  const tokenResponse = await axios.post(
    `${API_BASE}/api/v1/keys/request-access`,
    { userId, receiptId },
    { headers: { 'X-API-Key': API_KEY } }
  );

  // Fetch encrypted receipt
  const receipt = await axios.get(
    `${API_BASE}/api/v1/receipts/${userId}`,
    {
      headers: {
        'X-API-Key': API_KEY,
        'X-Access-Token': tokenResponse.data.accessToken
      }
    }
  );

  return receipt.data;
}

// Usage example
async function main() {
  try {
    // Generate keys for new user
    const { publicKey, privateKey } = await generateKeys();
    console.log('Keys generated successfully');

    // Store private key securely (in production: use device secure storage)

    // Register user
    await registerUser('user123', '[email protected]', publicKey);
    console.log('User registered successfully');

    // Store a receipt
    const receipt = await storeReceipt('user123', {
      merchantName: 'Coffee Shop',
      amount: 4200,
      currency: 'USD',
      items: [{ name: 'Latte', price: 4200 }]
    }, 'txn_abc123');
    console.log('Receipt stored:', receipt);

    // Retrieve receipt
    const fetchedReceipt = await getReceipt('user123', 'receipt_xyz789');
    console.log('Receipt retrieved:', fetchedReceipt);

    // Decrypt client-side with private key
    // (In production: use crypto library with stored private key)
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

main();

Express.js API Integration

const express = require('express');
const axios = require('axios');

const app = express();
app.use(express.json());

const DRP_API_BASE = 'https://api.digitalreceiptprotocol.org';
const DRP_API_KEY = process.env.DRP_API_KEY;

// Endpoint to onboard new user
app.post('/api/users/onboard', async (req, res) => {
  try {
    const { userId, email, phoneNumber } = req.body;

    // Generate keys
    const keysResponse = await axios.post(
      `${DRP_API_BASE}/api/v1/onboarding/generate-keys`
    );

    const { publicKey, privateKey } = keysResponse.data;

    // Register user with DRP
    await axios.post(
      `${DRP_API_BASE}/api/v1/onboarding/register`,
      { userId, email, phoneNumber, publicKey },
      { headers: { 'X-API-Key': DRP_API_KEY } }
    );

    // Return private key to client (they must store it securely)
    res.json({
      success: true,
      publicKey,
      privateKey // Client stores this securely
    });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

// Endpoint to store receipt after transaction
app.post('/api/receipts/store', async (req, res) => {
  try {
    const { userId, receiptData, transactionId } = req.body;

    // Encrypt receipt
    const encrypted = await axios.post(
      `${DRP_API_BASE}/api/v1/receipts/encrypt`,
      { userId, receiptData },
      { headers: { 'X-API-Key': DRP_API_KEY } }
    );

    // Store encrypted receipt
    const stored = await axios.post(
      `${DRP_API_BASE}/api/v1/receipts`,
      {
        userId,
        encryptedReceipt: encrypted.data.encryptedData,
        transactionId,
        metadata: {
          merchantId: req.body.merchantId,
          amount: receiptData.amount,
          timestamp: new Date().toISOString()
        }
      },
      { headers: { 'X-API-Key': DRP_API_KEY } }
    );

    res.json({ success: true, receipt: stored.data });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

// Endpoint to retrieve user receipts
app.get('/api/receipts/:userId', async (req, res) => {
  try {
    const { userId } = req.params;
    const { receiptId } = req.query;

    // Request access token
    const tokenResponse = await axios.post(
      `${DRP_API_BASE}/api/v1/keys/request-access`,
      { userId, receiptId },
      { headers: { 'X-API-Key': DRP_API_KEY } }
    );

    // Fetch receipts
    const receipts = await axios.get(
      `${DRP_API_BASE}/api/v1/receipts/${userId}`,
      {
        headers: {
          'X-API-Key': DRP_API_KEY,
          'X-Access-Token': tokenResponse.data.accessToken
        }
      }
    );

    res.json(receipts.data);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

Python

Complete Integration Example

import requests
import os
from typing import Dict, Any

API_BASE = 'https://api.digitalreceiptprotocol.org'
API_KEY = os.environ.get('DRP_API_KEY')

def generate_keys() -> Dict[str, str]:
    """Generate RSA-2048 key pair for new user"""
    response = requests.post(f'{API_BASE}/api/v1/onboarding/generate-keys')
    response.raise_for_status()
    return response.json()

def register_user(user_id: str, email: str, public_key: str) -> Dict[str, Any]:
    """Register user with DRP"""
    response = requests.post(
        f'{API_BASE}/api/v1/onboarding/register',
        json={
            'userId': user_id,
            'email': email,
            'publicKey': public_key
        },
        headers={'X-API-Key': API_KEY}
    )
    response.raise_for_status()
    return response.json()

def encrypt_receipt(user_id: str, receipt_data: Dict[str, Any]) -> Dict[str, Any]:
    """Encrypt receipt data with user's public key"""
    response = requests.post(
        f'{API_BASE}/api/v1/receipts/encrypt',
        json={
            'userId': user_id,
            'receiptData': receipt_data
        },
        headers={'X-API-Key': API_KEY}
    )
    response.raise_for_status()
    return response.json()

def store_receipt(user_id: str, encrypted_receipt: str, transaction_id: str, metadata: Dict[str, Any]) -> Dict[str, Any]:
    """Store encrypted receipt"""
    response = requests.post(
        f'{API_BASE}/api/v1/receipts',
        json={
            'userId': user_id,
            'encryptedReceipt': encrypted_receipt,
            'transactionId': transaction_id,
            'metadata': metadata
        },
        headers={'X-API-Key': API_KEY}
    )
    response.raise_for_status()
    return response.json()

def get_receipt(user_id: str, receipt_id: str) -> Dict[str, Any]:
    """Retrieve receipt with access token"""
    # Request access token
    token_response = requests.post(
        f'{API_BASE}/api/v1/keys/request-access',
        json={'userId': user_id, 'receiptId': receipt_id},
        headers={'X-API-Key': API_KEY}
    )
    token_response.raise_for_status()
    access_token = token_response.json()['accessToken']

    # Fetch receipt
    receipt_response = requests.get(
        f'{API_BASE}/api/v1/receipts/{user_id}',
        headers={
            'X-API-Key': API_KEY,
            'X-Access-Token': access_token
        }
    )
    receipt_response.raise_for_status()
    return receipt_response.json()

def main():
    """Example usage"""
    try:
        # Generate keys
        keys = generate_keys()
        print('Keys generated successfully')

        # Register user
        register_user('user123', '[email protected]', keys['publicKey'])
        print('User registered successfully')

        # Encrypt and store receipt
        receipt_data = {
            'merchantName': 'Coffee Shop',
            'amount': 4200,
            'currency': 'USD',
            'items': [{'name': 'Latte', 'price': 4200}]
        }

        encrypted = encrypt_receipt('user123', receipt_data)

        stored = store_receipt(
            'user123',
            encrypted['encryptedData'],
            'txn_abc123',
            {
                'merchantId': 'merchant_001',
                'amount': 4200,
                'timestamp': '2025-12-15T10:30:00Z'
            }
        )
        print(f'Receipt stored: {stored}')

        # Retrieve receipt
        receipt = get_receipt('user123', 'receipt_xyz789')
        print(f'Receipt retrieved: {receipt}')

    except requests.exceptions.RequestException as e:
        print(f'Error: {e}')

if __name__ == '__main__':
    main()

Flask API Integration

from flask import Flask, request, jsonify
import requests
import os

app = Flask(__name__)

DRP_API_BASE = 'https://api.digitalreceiptprotocol.org'
DRP_API_KEY = os.environ.get('DRP_API_KEY')

@app.route('/api/users/onboard', methods=['POST'])
def onboard_user():
    """Onboard new user to DRP"""
    try:
        data = request.json
        user_id = data['userId']
        email = data['email']

        # Generate keys
        keys_response = requests.post(
            f'{DRP_API_BASE}/api/v1/onboarding/generate-keys'
        )
        keys_response.raise_for_status()
        keys = keys_response.json()

        # Register user
        register_response = requests.post(
            f'{DRP_API_BASE}/api/v1/onboarding/register',
            json={
                'userId': user_id,
                'email': email,
                'publicKey': keys['publicKey']
            },
            headers={'X-API-Key': DRP_API_KEY}
        )
        register_response.raise_for_status()

        return jsonify({
            'success': True,
            'publicKey': keys['publicKey'],
            'privateKey': keys['privateKey']
        })

    except Exception as e:
        return jsonify({'error': str(e)}), 500

@app.route('/api/receipts/store', methods=['POST'])
def store_receipt_endpoint():
    """Store encrypted receipt"""
    try:
        data = request.json
        user_id = data['userId']
        receipt_data = data['receiptData']
        transaction_id = data['transactionId']

        # Encrypt receipt
        encrypt_response = requests.post(
            f'{DRP_API_BASE}/api/v1/receipts/encrypt',
            json={'userId': user_id, 'receiptData': receipt_data},
            headers={'X-API-Key': DRP_API_KEY}
        )
        encrypt_response.raise_for_status()
        encrypted = encrypt_response.json()

        # Store receipt
        store_response = requests.post(
            f'{DRP_API_BASE}/api/v1/receipts',
            json={
                'userId': user_id,
                'encryptedReceipt': encrypted['encryptedData'],
                'transactionId': transaction_id,
                'metadata': {
                    'merchantId': data.get('merchantId'),
                    'amount': receipt_data['amount'],
                    'timestamp': data.get('timestamp')
                }
            },
            headers={'X-API-Key': DRP_API_KEY}
        )
        store_response.raise_for_status()

        return jsonify({'success': True, 'receipt': store_response.json()})

    except Exception as e:
        return jsonify({'error': str(e)}), 500

@app.route('/api/receipts/<user_id>', methods=['GET'])
def get_receipts(user_id):
    """Retrieve user receipts"""
    try:
        receipt_id = request.args.get('receiptId')

        # Request access token
        token_response = requests.post(
            f'{DRP_API_BASE}/api/v1/keys/request-access',
            json={'userId': user_id, 'receiptId': receipt_id},
            headers={'X-API-Key': DRP_API_KEY}
        )
        token_response.raise_for_status()
        access_token = token_response.json()['accessToken']

        # Fetch receipts
        receipts_response = requests.get(
            f'{DRP_API_BASE}/api/v1/receipts/{user_id}',
            headers={
                'X-API-Key': DRP_API_KEY,
                'X-Access-Token': access_token
            }
        )
        receipts_response.raise_for_status()

        return jsonify(receipts_response.json())

    except Exception as e:
        return jsonify({'error': str(e)}), 500

if __name__ == '__main__':
    app.run(port=3000)

Go

Complete Integration Example

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
)

const apiBase = "https://api.digitalreceiptprotocol.org"

var apiKey = os.Getenv("DRP_API_KEY")

type KeyPair struct {
    PublicKey  string `json:"publicKey"`
    PrivateKey string `json:"privateKey"`
}

type ReceiptData struct {
    MerchantName string `json:"merchantName"`
    Amount       int    `json:"amount"`
    Currency     string `json:"currency"`
}

type EncryptedReceipt struct {
    EncryptedData string `json:"encryptedData"`
}

func generateKeys() (*KeyPair, error) {
    resp, err := http.Post(apiBase+"/api/v1/onboarding/generate-keys", "application/json", nil)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var keys KeyPair
    if err := json.NewDecoder(resp.Body).Decode(&keys); err != nil {
        return nil, err
    }

    return &keys, nil
}

func registerUser(userID, email, publicKey string) error {
    payload := map[string]string{
        "userId":    userID,
        "email":     email,
        "publicKey": publicKey,
    }

    data, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST", apiBase+"/api/v1/onboarding/register", bytes.NewBuffer(data))
    req.Header.Set("X-API-Key", apiKey)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()

    return nil
}

func encryptReceipt(userID string, receiptData ReceiptData) (*EncryptedReceipt, error) {
    payload := map[string]interface{}{
        "userId":      userID,
        "receiptData": receiptData,
    }

    data, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST", apiBase+"/api/v1/receipts/encrypt", bytes.NewBuffer(data))
    req.Header.Set("X-API-Key", apiKey)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var encrypted EncryptedReceipt
    if err := json.NewDecoder(resp.Body).Decode(&encrypted); err != nil {
        return nil, err
    }

    return &encrypted, nil
}

func storeReceipt(userID, encryptedReceipt, transactionID string) error {
    payload := map[string]interface{}{
        "userId":           userID,
        "encryptedReceipt": encryptedReceipt,
        "transactionId":    transactionID,
        "metadata": map[string]interface{}{
            "merchantId": "merchant_001",
            "amount":     4200,
            "timestamp":  "2025-12-15T10:30:00Z",
        },
    }

    data, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST", apiBase+"/api/v1/receipts", bytes.NewBuffer(data))
    req.Header.Set("X-API-Key", apiKey)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close()

    return nil
}

func main() {
    // Generate keys
    keys, err := generateKeys()
    if err != nil {
        fmt.Printf("Error generating keys: %v\n", err)
        return
    }
    fmt.Println("Keys generated successfully")

    // Register user
    err = registerUser("user123", "[email protected]", keys.PublicKey)
    if err != nil {
        fmt.Printf("Error registering user: %v\n", err)
        return
    }
    fmt.Println("User registered successfully")

    // Encrypt receipt
    receiptData := ReceiptData{
        MerchantName: "Coffee Shop",
        Amount:       4200,
        Currency:     "USD",
    }

    encrypted, err := encryptReceipt("user123", receiptData)
    if err != nil {
        fmt.Printf("Error encrypting receipt: %v\n", err)
        return
    }

    // Store receipt
    err = storeReceipt("user123", encrypted.EncryptedData, "txn_abc123")
    if err != nil {
        fmt.Printf("Error storing receipt: %v\n", err)
        return
    }
    fmt.Println("Receipt stored successfully")
}

Error Handling Best Practices

Retry Logic with Exponential Backoff

async function apiCallWithRetry(apiCall, maxRetries = 3) {
  let lastError;

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await apiCall();
    } catch (error) {
      lastError = error;

      // Don't retry on client errors (except rate limiting)
      if (error.response?.status >= 400 &&
          error.response?.status < 500 &&
          error.response?.status !== 429) {
        throw error;
      }

      // Calculate backoff delay
      const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s

      console.log(`Attempt ${attempt + 1} failed. Retrying in ${delay}ms...`);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }

  throw lastError;
}

// Usage
const receipt = await apiCallWithRetry(() =>
  axios.post(`${API_BASE}/api/v1/receipts`, receiptData, {
    headers: { 'X-API-Key': API_KEY }
  })
);

Testing Examples

Unit Test Example (Jest)

const { generateKeys, registerUser } = require('./drp-client');
const axios = require('axios');

jest.mock('axios');

describe('DRP Integration', () => {
  test('should generate keys successfully', async () => {
    const mockKeys = {
      publicKey: 'mock-public-key',
      privateKey: 'mock-private-key'
    };

    axios.post.mockResolvedValue({ data: mockKeys });

    const keys = await generateKeys();

    expect(keys).toEqual(mockKeys);
    expect(axios.post).toHaveBeenCalledWith(
      'https://api.digitalreceiptprotocol.org/api/v1/onboarding/generate-keys'
    );
  });

  test('should register user successfully', async () => {
    axios.post.mockResolvedValue({ data: { success: true } });

    const result = await registerUser('user123', '[email protected]', 'public-key');

    expect(result).toEqual({ success: true });
  });
});

Next Steps

API Reference

Detailed API endpoint documentation

SDK Documentation

Language-specific SDK guides

JavaScript SDK

Full JavaScript/Node.js SDK documentation

Python SDK

Full Python SDK documentation

Overview

Server SDKs

Integration Examples

Integration Examples

Node.js / JavaScript

Complete Integration Example

Express.js API Integration

Python

Complete Integration Example

Flask API Integration

Go

Complete Integration Example

Error Handling Best Practices

Retry Logic with Exponential Backoff

Testing Examples

Unit Test Example (Jest)

Next Steps

API Reference

SDK Documentation

JavaScript SDK

Python SDK

Overview

Server SDKs

​Integration Examples

​Node.js / JavaScript

​Complete Integration Example

​Express.js API Integration

​Python

​Complete Integration Example

​Flask API Integration

​Go

​Complete Integration Example

​Error Handling Best Practices

​Retry Logic with Exponential Backoff

​Testing Examples

​Unit Test Example (Jest)

​Next Steps

API Reference

SDK Documentation

JavaScript SDK

Python SDK

Integration Examples

Node.js / JavaScript

Complete Integration Example

Express.js API Integration

Python

Complete Integration Example

Flask API Integration

Go

Complete Integration Example

Error Handling Best Practices

Retry Logic with Exponential Backoff

Testing Examples

Unit Test Example (Jest)

Next Steps