> ## 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.

# Decrypt Receipt

> Decrypt a receipt by looking up the payment transaction on the gateway (Stripe/Square).
Requires a valid access token and the user's private key.




## OpenAPI

````yaml post /api/v1/payments/decrypt
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/payments/decrypt:
    post:
      tags:
        - Payments
      summary: Decrypt receipt by payment ID
      description: >
        Decrypt a receipt by looking up the payment transaction on the gateway
        (Stripe/Square).

        Requires a valid access token and the user's private key.
      operationId: decryptByPaymentId
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - paymentId
                - gateway
                - accessTokenId
                - privateKey
              properties:
                paymentId:
                  type: string
                  description: Payment ID from the gateway (e.g., pi_... for Stripe)
                gateway:
                  type: string
                  enum:
                    - stripe
                    - square
                accessTokenId:
                  type: string
                privateKey:
                  type: string
            example:
              paymentId: pi_stripe_abc123
              gateway: stripe
              accessTokenId: tok_9a8b7c6d-5e4f-3a2b-1c0d-e9f8a7b6c5d4
              privateKey: MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDP...
      responses:
        '200':
          description: Receipt decrypted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecryptReceiptResponse'
              example:
                success: true
                data:
                  version: '1.0'
                  receiptId: rcpt_abc123def456
                  merchant:
                    merchantId: merch_kitchenmart_001
                    name: KitchenMart
                    address:
                      street: 456 Commerce Ave
                      city: San Francisco
                      state: CA
                      postalCode: '94103'
                      country: US
                  transaction:
                    transactionId: txn_550e8400e29b41d4a716
                    datetime: '2025-12-18T10:30:00Z'
                    paymentMethod: card
                    cardDetails:
                      last4: '4242'
                      brand: visa
                  items:
                    - lineItemId: item_001
                      name: Stainless Steel Mixing Bowl Set
                      quantity: 1
                      unitPrice: 2999
                      totalPrice: 2999
                    - lineItemId: item_002
                      name: Non-Stick Frying Pan
                      quantity: 2
                      unitPrice: 3999
                      totalPrice: 7998
                  summary:
                    subtotal: 10997
                    totalTax: 962
                    total: 11959
                    currency: USD
                  createdAt: '2025-12-18T10:30:00Z'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: INVALID_REQUEST
                  message: Invalid request body
        '403':
          description: Access denied - token expired, invalid, or decryption failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: DECRYPTION_ERROR
                  message: Access token expired or invalid
        '500':
          description: Decryption failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    DecryptReceiptResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/DigitalReceipt'
    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
    DigitalReceipt:
      type: object
      required:
        - version
        - receiptId
        - merchant
        - transaction
        - items
        - summary
        - createdAt
      properties:
        version:
          type: string
          description: Receipt schema version
          example: '1.0'
        receiptId:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440003
        merchant:
          $ref: '#/components/schemas/ReceiptMerchant'
        transaction:
          $ref: '#/components/schemas/ReceiptTransaction'
        items:
          type: array
          items:
            $ref: '#/components/schemas/ReceiptLineItem'
        summary:
          $ref: '#/components/schemas/ReceiptSummary'
        notes:
          type: string
          nullable: true
          example: Thank you for shopping!
        returnPolicy:
          type: string
          nullable: true
          example: 30-day return policy
        loyaltyInfo:
          $ref: '#/components/schemas/LoyaltyInfo'
        metadata:
          type: object
          additionalProperties: true
        createdAt:
          type: string
          format: date-time
          example: '2025-12-15T12:35:00Z'
    ReceiptMerchant:
      type: object
      required:
        - merchantId
        - name
      properties:
        merchantId:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440004
        name:
          type: string
          example: Store Name
        address:
          $ref: '#/components/schemas/Address'
        taxId:
          type: string
          example: 12-3456789
        logoUrl:
          type: string
          format: uri
          example: https://example.com/logo.png
        contactPhone:
          type: string
          example: +1-555-1234
        contactEmail:
          type: string
          format: email
          example: store@example.com
    ReceiptTransaction:
      type: object
      required:
        - transactionId
        - datetime
        - paymentMethod
      properties:
        transactionId:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440005
        datetime:
          type: string
          format: date-time
          example: '2025-12-15T12:30:00Z'
        timezone:
          type: string
          example: America/New_York
        paymentMethod:
          type: string
          enum:
            - card
            - cash
            - mobile_wallet
            - bank_transfer
            - other
          example: card
        cardDetails:
          $ref: '#/components/schemas/CardDetails'
        authorizationCode:
          type: string
          example: AUTH123456
    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'
    ReceiptSummary:
      type: object
      required:
        - subtotal
        - totalTax
        - totalDiscount
        - total
        - currency
        - itemCount
      properties:
        subtotal:
          type: integer
          description: Subtotal in cents
          example: 3998
        totalTax:
          type: integer
          description: Total tax in cents
          example: 320
        totalDiscount:
          type: integer
          description: Total discount in cents
          example: 400
        tipAmount:
          type: integer
          nullable: true
          description: Tip amount in cents
          example: 100
        total:
          type: integer
          description: Grand total in cents
          example: 4018
        currency:
          type: string
          description: ISO 4217 currency code
          example: USD
        itemCount:
          type: integer
          example: 1
    LoyaltyInfo:
      type: object
      nullable: true
      properties:
        programName:
          type: string
          example: Rewards Program
        pointsEarned:
          type: integer
          example: 40
        pointsBalance:
          type: integer
          example: 1240
        memberNumber:
          type: string
          example: MEMBER123456
    Address:
      type: object
      properties:
        street:
          type: string
          example: 123 Main St
        city:
          type: string
          example: New York
        state:
          type: string
          example: NY
        postalCode:
          type: string
          example: '10001'
        country:
          type: string
          example: US
    CardDetails:
      type: object
      properties:
        last4:
          type: string
          description: Last 4 digits of the card
          example: '4242'
        brand:
          type: string
          enum:
            - visa
            - mastercard
            - amex
            - discover
            - other
          example: visa
        expiryMonth:
          type: integer
          minimum: 1
          maximum: 12
          example: 12
        expiryYear:
          type: integer
          example: 2026
    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

````