sxchnge/backend/contracts/sendico/api/payments/request/payment.yaml

components:
  schemas:
    PaymentBase:
      description: Base fields shared by payment initiation request payloads.
      type: object
      additionalProperties: false
      required:
        - idempotencyKey
      properties:
        idempotencyKey:
          description: Client-supplied key used to safely deduplicate requests.
          type: string
        metadata:
          description: Optional request metadata forwarded through payment processing.
          type: object
          additionalProperties:
            type: string

    QuotePaymentRequest:
      description: |
        Request payload to quote a single payment intent.
        For raw `card` destinations, quotation only requires `pan`.
        If the quoted payment may later be executed, include `exp_month` and `exp_year` during quotation because execution reuses the quoted endpoint snapshot.
      type: object
      additionalProperties: false
      required:
        - intent
      properties:
        idempotencyKey:
          description: Idempotency key used when persisting quote context.
          type: string
        metadata:
          description: Optional metadata associated with the quote request.
          type: object
          additionalProperties:
            type: string
        clientPaymentRef:
          description: Optional caller-side payment correlation reference to persist with the quote and reuse during execution when the execute request omits it.
          type: string
        intent:
          description: Payment intent to be priced. See `PaymentIntent.destination` for raw-card quote versus execution requirements.
          $ref: ../../../models/payment/payment.yaml#/components/schemas/PaymentIntent
        previewOnly:
          description: If true, returns a preview quote without requiring idempotency.
          type: boolean
      allOf:
        - if:
            properties:
              previewOnly:
                const: true
            required:
              - previewOnly
          then:
            not:
              required:
                - idempotencyKey
          else:
            required:
              - idempotencyKey

    QuotePaymentsRequest:
      description: |
        Request payload to quote multiple payment intents in a single call.
        For raw `card` destinations, quotation only requires `pan`.
        If quoted items may later be executed, include `exp_month` and `exp_year` during quotation because execution reuses the quoted endpoint snapshot.
      type: object
      additionalProperties: false
      required:
        - intents
      properties:
        idempotencyKey:
          description: Idempotency key used when persisting batch quote context.
          type: string
        metadata:
          description: Optional metadata associated with the quote request.
          type: object
          additionalProperties:
            type: string
        clientPaymentRef:
          description: Optional caller-side batch payment correlation reference to persist with the quote and reuse during execution when the execute request omits it.
          type: string
        intents:
          description: List of payment intents to be priced. See each intent destination for raw-card quote versus execution requirements.
          type: array
          minItems: 1
          items:
            $ref: ../../../models/payment/payment.yaml#/components/schemas/PaymentIntent
        previewOnly:
          description: If true, returns preview quotes without requiring idempotency.
          type: boolean
      allOf:
        - if:
            properties:
              previewOnly:
                const: true
            required:
              - previewOnly
          then:
            not:
              required:
                - idempotencyKey
          else:
            required:
              - idempotencyKey

    InitiatePaymentRequest:
      description: |
        Request payload to initiate a single payment.
        When executing a raw `card` destination from inline `intent`, `pan`, `exp_month`, and `exp_year` must be present.
        When executing a `cardToken` destination, only `token` is required by current logic.
      allOf:
        - $ref: ./payment.yaml#/components/schemas/PaymentBase
        - type: object
          additionalProperties: false
          oneOf:
            - required: [intent]
            - required: [quoteRef]
          properties:
            intent:
              description: Payment intent to execute directly. Raw `card` destinations require expiry at execution time.
              $ref: ../../../models/payment/payment.yaml#/components/schemas/PaymentIntent
            quoteRef:
              description: Reference to a previously generated quote to execute. If that quote contains a raw `card` destination, the original quote must already include `exp_month` and `exp_year`.
              type: string
            clientPaymentRef:
              description: Optional caller-side payment correlation reference. When omitted, execution may reuse the value stored with the quote.
              type: string

    InitiatePaymentsRequest:
      description: |
        Request payload to initiate multiple payments from a multi-quote reference.
        If any quoted item contains a raw `card` destination, that item's original quote must already include `exp_month` and `exp_year`.
      allOf:
        - $ref: ./payment.yaml#/components/schemas/PaymentBase
        - type: object
          additionalProperties: false
          required:
            - quoteRef
          properties:
            quoteRef:
              description: Reference to a previously generated multi-quote. Raw-card items execute from the stored quoted endpoint snapshot.
              type: string
            clientPaymentRef:
              description: Optional caller-side payment correlation reference. When omitted, execution may reuse the value stored with the quote.
              type: string

    InitiatePaymentByQuoteRequest:
      description: |
        Request payload to initiate one payment from an existing quote reference.
        If the quote contains a raw `card` destination, the original quote must already include `exp_month` and `exp_year`.
      allOf:
        - $ref: ./payment.yaml#/components/schemas/PaymentBase
        - type: object
          additionalProperties: false
          required:
            - quoteRef
          properties:
            quoteRef:
              description: Reference to a previously generated quote to execute. Execution reuses the stored quoted endpoint snapshot.
              type: string
            clientPaymentRef:
              description: Optional caller-side payment correlation reference. When omitted, execution may reuse the value stored with the quote.
              type: string