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

# Encrypt Receipt

> Encrypt a digital receipt for a specific recipient using hybrid encryption:
- AES-256-GCM for the receipt data (symmetric)
- RSA-OAEP-SHA256 for key wrapping (asymmetric)

If the recipient is not onboarded, the receipt will be encrypted with
the escrow key instead (indicated by `isEscrowed: true` in the response).




## OpenAPI

````yaml post /api/v1/receipts/encrypt
openapi: 3.1.0
info:
  title: Digital Receipt Protocol API
  description: >
    The Digital Receipt Protocol (DRP) provides a secure, end-to-end encrypted
    digital receipt system

    for banks, merchants, and fintech applications. This API enables secure
    receipt encryption,

    decryption, and storage with robust key management and access control.


    ## Key Features

    - **End-to-End Encryption**: AES-256-GCM for receipt data with
    RSA-OAEP-SHA256 key wrapping

    - **User Onboarding**: Generate key pairs and register users with hashed PAN
    identifiers

    - **Access Control**: Short-lived access tokens (2-3 minutes) for receipt
    decryption

    - **Escrow Support**: Encrypted receipts for non-onboarded users via escrow
    keys

    - **Payment Gateway Integration**: Store receipts with transaction mappings
    for Stripe, Square, etc.

    - **Audit Logging**: Comprehensive tracking of all cryptographic operations


    ## Pricing Format

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

    Example: $42.00 = 4200
  version: 1.0.0
  contact:
    name: Digital Receipt Protocol Team
    url: https://digitalreceiptprotocol.org
    email: api@digitalreceiptprotocol.org
  license:
    name: GNU General Public License v3.0
    url: https://www.gnu.org/licenses/gpl-3.0.html
servers:
  - url: https://api.digitalreceiptprotocol.org
    description: Production server
  - url: https://staging-api.digitalreceiptprotocol.org
    description: Staging server
  - url: http://localhost:3000
    description: Local development server
security: []
tags:
  - name: Health
    description: Service health monitoring
  - name: Onboarding
    description: User registration and key generation
  - name: Keys
    description: Key management and access control
  - name: Receipts
    description: Receipt encryption and decryption
  - name: Transactions
    description: Transaction storage and retrieval
  - name: Payments
    description: Payment gateway integration (Stripe, Square)
paths:
  /api/v1/receipts/encrypt:
    post:
      tags:
        - Receipts
      summary: Encrypt receipt
      description: >
        Encrypt a digital receipt for a specific recipient using hybrid
        encryption:

        - AES-256-GCM for the receipt data (symmetric)

        - RSA-OAEP-SHA256 for key wrapping (asymmetric)


        If the recipient is not onboarded, the receipt will be encrypted with

        the escrow key instead (indicated by `isEscrowed: true` in the
        response).
      operationId: encryptReceipt
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EncryptReceiptRequest'
            example:
              version: '1.0'
              receiptId: rcpt_abc123def456
              merchantId: merch_kitchenmart_001
              merchantName: KitchenMart
              merchantStreet: 456 Commerce Ave
              merchantCity: San Francisco
              merchantState: CA
              merchantPostalCode: '94103'
              merchantCountry: US
              merchantTaxId: 98-7654321
              merchantContactEmail: support@kitchenmart.com
              transactionId: txn_550e8400e29b41d4a716
              transactionDate: '2025-12-18T10:30:00Z'
              transactionTimezone: America/Los_Angeles
              paymentMethod: card
              cardLast4: '4242'
              cardBrand: visa
              currency: USD
              subtotal: 10997
              taxAmount: 962
              totalAmount: 11959
              items:
                - lineItemId: item_001
                  name: Stainless Steel Mixing Bowl Set
                  quantity: 1
                  unitPrice: 2999
                  totalPrice: 2999
                  category: Kitchen Essentials
                  taxes:
                    - name: Sales Tax
                      rate: 0.0875
                      amount: 262
                - lineItemId: item_002
                  name: Non-Stick Frying Pan
                  quantity: 2
                  unitPrice: 3999
                  totalPrice: 7998
                  category: Cookware
                  taxes:
                    - name: Sales Tax
                      rate: 0.0875
                      amount: 700
              mockItems: false
              recipientHashedPan: 5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8
      responses:
        '200':
          description: Receipt encrypted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EncryptReceiptResponse'
              example:
                success: true
                data:
                  version: '1.0'
                  receiptId: rcpt_abc123def456
                  keyId: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
                  keyBundle:
                    encryptedAesKey: base64_encrypted_aes_key_here...
                    keyId: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
                    algorithm: RSA-OAEP-256
                  ciphertext: base64_encrypted_receipt_data_here...
                  iv: base64_initialization_vector...
                  authTag: base64_authentication_tag...
                  merchantId: merch_kitchenmart_001
                  transactionId: txn_550e8400e29b41d4a716
                  createdAt: '2025-12-18T10:30:00Z'
                  isEscrowed: false
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Encryption failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: ENCRYPTION_ERROR
                  message: Failed to encrypt receipt
components:
  schemas:
    EncryptReceiptRequest:
      type: object
      description: Flattened receipt structure with recipient identifier
      allOf:
        - $ref: '#/components/schemas/FlatDigitalReceipt'
        - type: object
          required:
            - recipientHashedPan
          properties:
            recipientHashedPan:
              type: string
              description: Hashed PAN of the recipient
              example: 5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8
    EncryptReceiptResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/EncryptedReceiptEnvelope'
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code
            message:
              type: string
              description: Human-readable error message
            details:
              type: object
              description: Additional error details
              additionalProperties: true
    FlatDigitalReceipt:
      type: object
      description: Flattened digital receipt structure
      required:
        - version
        - receiptId
        - merchantId
        - merchantName
        - transactionId
        - transactionDate
        - amount
        - currency
      properties:
        version:
          type: string
          default: '1.0'
        receiptId:
          type: string
          default: 550e8400-e29b-41d4-a716-446655440003
        merchantId:
          type: string
          default: 550e8400-e29b-41d4-a716-446655440004
        merchantName:
          type: string
          default: KitchenMart
        merchantStreet:
          type: string
          default: 456 Commerce Ave
        merchantCity:
          type: string
          default: San Francisco
        merchantState:
          type: string
          default: CA
        merchantPostalCode:
          type: string
          default: '94103'
        merchantCountry:
          type: string
          default: US
        merchantTaxId:
          type: string
          default: 98-7654321
        merchantContactEmail:
          type: string
          default: support@kitchenmart.com
        transactionId:
          type: string
          default: 550e8400-e29b-41d4-a716-446655440005
        transactionDate:
          type: string
          format: date-time
          default: '2025-12-18T10:30:00Z'
        transactionTimezone:
          type: string
          default: America/Los_Angeles
        paymentMethod:
          type: string
          default: card
        cardLast4:
          type: string
          default: '4242'
        cardBrand:
          type: string
          default: visa
        currency:
          type: string
          default: USD
        subtotal:
          type: integer
          default: 2000
        taxAmount:
          type: integer
          default: 0
        totalAmount:
          type: integer
          default: 2000
        items:
          type: array
          items:
            $ref: '#/components/schemas/ReceiptLineItem'
        mockItems:
          type: boolean
          description: If true and items are empty, generates mock line items
          default: true
    EncryptedReceiptEnvelope:
      type: object
      properties:
        version:
          type: string
          example: '1.0'
        receiptId:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440003
        keyId:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        keyBundle:
          $ref: '#/components/schemas/EncryptedKeyBundle'
        ciphertext:
          type: string
          description: Base64-encoded AES-GCM encrypted receipt
          example: encrypted_receipt_ciphertext_base64...
        iv:
          type: string
          description: Base64-encoded initialization vector
          example: initialization_vector_base64...
        authTag:
          type: string
          description: Base64-encoded GCM authentication tag
          example: auth_tag_base64...
        merchantId:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440004
        transactionId:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440005
        createdAt:
          type: string
          format: date-time
          example: '2025-12-15T12:35:00Z'
        expiresAt:
          type: string
          format: date-time
          nullable: true
          example: '2025-12-16T12:35:00Z'
        isEscrowed:
          type: boolean
          description: True if encrypted with escrow key (user not onboarded)
          example: false
        escrowKeyId:
          type: string
          format: uuid
          nullable: true
          description: Escrow key ID if isEscrowed is true
          example: null
    ReceiptLineItem:
      type: object
      required:
        - lineItemId
        - name
        - quantity
        - unitPrice
        - totalPrice
      properties:
        lineItemId:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440006
        sku:
          type: string
          nullable: true
          example: SKU-001
        name:
          type: string
          example: Widget Pro
        description:
          type: string
          nullable: true
          example: Premium widget with advanced features
        quantity:
          type: number
          example: 2
        unitPrice:
          type: integer
          description: Price in smallest currency unit (cents)
          example: 1999
        totalPrice:
          type: integer
          description: Total price in smallest currency unit (cents)
          example: 3998
        category:
          type: string
          nullable: true
          example: Electronics
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/LineItemDiscount'
        taxes:
          type: array
          items:
            $ref: '#/components/schemas/LineItemTax'
    EncryptedKeyBundle:
      type: object
      properties:
        encryptedAesKey:
          type: string
          description: Base64-encoded RSA-encrypted AES key
          example: encrypted_aes_key_base64...
        keyId:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        algorithm:
          type: string
          enum:
            - RSA-OAEP-256
          example: RSA-OAEP-256
    LineItemDiscount:
      type: object
      properties:
        name:
          type: string
          example: Holiday Sale
        type:
          type: string
          enum:
            - percentage
            - fixed
          example: percentage
        value:
          type: number
          description: Percentage (0-100) or fixed amount in cents
          example: 10
        amount:
          type: integer
          description: Discount amount in cents
          example: 400
    LineItemTax:
      type: object
      properties:
        name:
          type: string
          example: Sales Tax
        rate:
          type: number
          description: Tax rate as decimal (0.08 = 8%)
          example: 0.08
        amount:
          type: integer
          description: Tax amount in cents
          example: 288

````