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

# Create Payment

> Create a payment (Stripe/Square) with encrypted receipt metadata.
This endpoint encrypts the receipt, creates a payment intent/order on the gateway,
and attaches DRP metadata for later retrieval.




## OpenAPI

````yaml post /api/v1/payments/{gateway}/create
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/{gateway}/create:
    post:
      tags:
        - Payments
      summary: Create payment with DRP
      description: >
        Create a payment (Stripe/Square) with encrypted receipt metadata.

        This endpoint encrypts the receipt, creates a payment intent/order on
        the gateway,

        and attaches DRP metadata for later retrieval.
      operationId: createPayment
      parameters:
        - name: gateway
          in: path
          required: true
          description: Payment gateway provider
          schema:
            type: string
            enum:
              - stripe
              - square
          example: stripe
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
            example:
              version: '1.0'
              receiptId: rcpt_payment_001
              merchantId: mer_001
              merchantName: Test Merchant
              merchantStreet: 123 Main St
              merchantCity: San Francisco
              merchantState: CA
              merchantPostalCode: '94105'
              merchantCountry: US
              transactionId: txn_001
              transactionDate: '2024-12-18T00:00:00Z'
              transactionTimezone: UTC
              paymentMethod: card
              currency: USD
              subtotal: 2000
              taxAmount: 0
              totalAmount: 2000
              items:
                - lineItemId: li_001
                  name: Widget
                  quantity: 1
                  unitPrice: 1000
                  totalPrice: 1000
              recipientHashedPan: 5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8
              amount: 1000
              cardNonce: cnon:card-nonce-ok
      responses:
        '200':
          description: Payment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Payment failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    PaymentRequest:
      type: object
      description: >-
        Unified payment request structure for all gateways. Uses flattened
        receipt fields at root level (same as EncryptReceiptRequest).
      allOf:
        - $ref: '#/components/schemas/FlatDigitalReceipt'
        - type: object
          required:
            - recipientHashedPan
          properties:
            recipientHashedPan:
              type: string
              description: Hashed PAN of the recipient
              example: 5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8
            amount:
              type: integer
              description: >-
                Amount in cents (required for Stripe, derived from items for
                Square)
              default: 11959
            currency:
              type: string
              description: ISO currency code (defaults to usd)
              default: usd
            cardNonce:
              type: string
              description: Card nonce for Square payments (optional)
              default: cnon:card-nonce-ok
    PaymentResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            paymentId:
              type: string
              description: Payment ID (Stripe PI or Square Payment ID)
            clientSecret:
              type: string
              description: Stripe Client Secret (Stripe only)
            orderId:
              type: string
              description: Square Order ID (Square only)
            drpMetadata:
              type: object
              additionalProperties:
                type: string
    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
    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'
    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

````