> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veroreceipts.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> The Vero 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.

<Note>
  Vero is built on top of the open [Digital Receipt Protocol (DRP)](https://www.digitalreceiptprotocol.org/) — the standard for end-to-end encrypted digital receipts. That's why the API is hosted at `api.digitalreceiptprotocol.org`: Vero implements the reference DRP infrastructure for key management, encryption, and receipt transmission.
</Note>

### Base URL

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

The Vero 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:

```http theme={null}
GET /api/v1/receipts/{userId}
X-API-Key: your_api_key_here
Content-Type: application/json
```

API keys are managed through the Vero 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 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

All monetary values are represented in the smallest currency unit (e.g., cents for USD).

**Example**: \$42.00 = 4200

***

## Rate Limits

Endpoints are rate limited **by IP address**. 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

```json theme={null}
{
  "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

| Code                    | HTTP Status | Description                     |
| ----------------------- | ----------- | ------------------------------- |
| `invalid_request`       | 400         | Request validation failed       |
| `unauthorized`          | 401         | Invalid or missing API key      |
| `forbidden`             | 403         | Access denied for this resource |
| `not_found`             | 404         | Resource not found              |
| `rate_limit_exceeded`   | 429         | Too many requests               |
| `internal_server_error` | 500         | Internal server error           |
| `service_unavailable`   | 503         | Service temporarily unavailable |

***

## Retry Logic

### Recommended Retry Strategy

```javascript theme={null}
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