Bootstrap copied BFF and local accounts with public Sendico contracts (#34)

2026-09-12 13:37:48 +02:00
1 parent 67dc5b5b1e
commit 7062672a87
@@ -0,0 +1,33 @@
+components:
+  requestBodies:
+    QuotePaymentBody:
+      description: JSON payload used to request a quote for one payment intent.
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../request/payment.yaml#/components/schemas/QuotePaymentRequest
+
+    QuotePaymentsBody:
+      description: JSON payload used to request quotes for multiple payment intents.
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../request/payment.yaml#/components/schemas/QuotePaymentsRequest
+
+    InitiatePaymentBody:
+      description: JSON payload used to initiate a single payment.
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../request/payment.yaml#/components/schemas/InitiatePaymentRequest
+
+    InitiatePaymentsBody:
+      description: JSON payload used to initiate multiple payments from a quote reference.
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../request/payment.yaml#/components/schemas/InitiatePaymentsRequest
@@ -0,0 +1,37 @@
+post:
+  tags: [Payments]
+  summary: Initiate payment batch by quote reference
+  description: |
+    Executes batch payment from a previously created multi-quote reference. If any quoted item
+    uses a raw `card` destination, that item's original quote must already include `exp_month`
+    and `exp_year`. Card-recipient AML screening occurs during execution, not quotation. An
+    unchanged payment item reuses its persisted compliance decision on idempotent execution
+    replay, avoiding a duplicate AML call. A definitive denial terminates that payment with
+    public `failureCode: failure_restriction` and `failureReason: aml_denied`.
+  operationId: paymentsInitiateBatchByQuote
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/organizations_ref.yaml#/components/parameters/OrganizationsRef
+  requestBody:
+    $ref: ./bodies/payment.yaml#/components/requestBodies/InitiatePaymentsBody
+  responses:
+    '200':
+      description: Payment batch initiated
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/payment.yaml#/components/schemas/PaymentsData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError
@@ -0,0 +1,41 @@
+post:
+  tags: [Payments]
+  summary: Initiate payment using quote reference
+  description: |
+    Executes one payment from an existing quote reference. If the quoted destination is raw
+    `card`, the original quote must already include `exp_month` and `exp_year`. Card-recipient
+    AML screening occurs during execution, not quotation. An unchanged payment reuses its
+    persisted compliance decision on idempotent execution replay, avoiding a duplicate AML call.
+    A definitive denial terminates the payment with public `failureCode: failure_restriction`
+    and `failureReason: aml_denied`.
+  operationId: paymentsInitiateByQuote
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/organizations_ref.yaml#/components/parameters/OrganizationsRef
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: ./request/payment.yaml#/components/schemas/InitiatePaymentByQuoteRequest
+  responses:
+    '200':
+      description: Payment initiated by quote
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/payment.yaml#/components/schemas/PaymentData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError
@@ -0,0 +1,47 @@
+get:
+  tags: [Payments]
+  summary: Download payment certificate
+  description: |
+    Returns a generated payment certificate as binary content.
+    The payment must be settled; the BFF resolves certificate details from the payment reference.
+  operationId: paymentsGetPaymentCertificate
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/organizations_ref.yaml#/components/parameters/OrganizationsRef
+    - name: payment_ref
+      in: query
+      required: true
+      description: Settled payment reference used to generate the payment certificate.
+      schema:
+        type: string
+  responses:
+    '200':
+      description: Payment certificate file
+      content:
+        application/pdf:
+          schema:
+            type: string
+            format: binary
+        application/octet-stream:
+          schema:
+            type: string
+            format: binary
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '404':
+      $ref: ../response/operation.yaml#/components/responses/NotFound
+    '409':
+      $ref: ../response/operation.yaml#/components/responses/Conflict
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError
+    '503':
+      description: Upstream service unavailable
+      content:
+        application/json:
+          schema:
+            $ref: ../response/response.yaml#/components/schemas/ErrorResponse
@@ -0,0 +1,40 @@
+get:
+  tags: [Payments]
+  summary: List available FX currencies
+  description: |
+    Returns the BFF startup-cached Treasury Currency Catalog projection for
+    client-visible FX currencies. `decimals`, `scale`, and `displayScale` are
+    presentation fields backed by Treasury `display_scale`.
+    `accountingScaleCandidate` is informational only and must not be used by
+    clients to determine executable payout precision, quote precision, or
+    guaranteed provider support.
+    The endpoint is authenticated and authorized by `organizations_ref`, but the
+    returned catalogue is global rather than organization-customized. If Treasury
+    was unavailable at BFF startup while this endpoint was enabled, BFF fails
+    startup; if Treasury becomes unavailable after startup, BFF continues serving
+    the cached catalog revision.
+  operationId: paymentsFXCurrencies
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/organizations_ref.yaml#/components/parameters/OrganizationsRef
+  responses:
+    '200':
+      description: FX currency catalogue projected from Treasury
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/payment.yaml#/components/schemas/FXCurrenciesData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '503':
+      $ref: ../response/operation.yaml#/components/responses/ServiceUnavailable
@@ -0,0 +1,48 @@
+get:
+  tags: [Payments]
+  summary: List available FX directions
+  description: |
+    Returns organization-level FX direction availability.
+
+    A returned direction means the organization has at least one eligible
+    direction-level route. It does not mean that every quote or payment for this
+    direction will be accepted. The actual route, gateway, limits, pricing, fees,
+    asset domain, and settlement details are resolved during quotation/payment
+    execution.
+
+    If dependencies are healthy but no organization-eligible executable
+    directions match oracle quoteable pair sides, the response contains an empty
+    `directions` array. Oracle or gateway/route registry dependency failures are
+    returned as errors and are not converted to oracle-only or empty successful
+    responses.
+  operationId: paymentsFXDirections
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/organizations_ref.yaml#/components/parameters/OrganizationsRef
+  responses:
+    '200':
+      description: Organization-level directed FX availability
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/payment.yaml#/components/schemas/FXDirectionsData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '412':
+      description: Dependency precondition failed
+      content:
+        application/json:
+          schema:
+            $ref: ../response/response.yaml#/components/schemas/ErrorResponse
+    '503':
+      $ref: ../response/operation.yaml#/components/responses/ServiceUnavailable
@@ -0,0 +1,48 @@
+post:
+  tags: [Payments]
+  summary: Initiate payment from immediate intent
+  description: |
+    Creates quote and executes a single payment in one call (request must include `intent`). For
+    raw `card` destinations, execution requires `exp_month` and `exp_year`; `cardToken`
+    destinations only require `token`. Card-recipient AML screening occurs during execution.
+    An unchanged payment reuses its persisted compliance decision on idempotent execution replay,
+    avoiding a duplicate AML call. A definitive denial terminates the payment with public
+    `failureCode: failure_restriction` and `failureReason: aml_denied`.
+  operationId: paymentsInitiateImmediate
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/organizations_ref.yaml#/components/parameters/OrganizationsRef
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          allOf:
+            - $ref: ./request/payment.yaml#/components/schemas/InitiatePaymentRequest
+            - type: object
+              required:
+                - intent
+              not:
+                required:
+                  - quoteRef
+  responses:
+    '200':
+      description: Payment initiated
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/payment.yaml#/components/schemas/PaymentData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError
@@ -0,0 +1,76 @@
+get:
+  tags: [Payments]
+  summary: List payments in organization
+  description: |
+    Returns organization payments with cursor pagination and optional filters.
+    State filters accept aliases (`accepted`, `settled`, `failed`, etc.) or canonical orchestration states.
+  operationId: paymentsList
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/organizations_ref.yaml#/components/parameters/OrganizationsRef
+    - $ref: ../parameters/cursor.yaml#/components/parameters/Cursor
+    - $ref: ../parameters/limit.yaml#/components/parameters/Limit
+    - name: quotation_ref
+      in: query
+      required: false
+      description: Filter by quotation reference used for execution.
+      schema:
+        type: string
+    - name: quote_ref
+      in: query
+      required: false
+      description: Alias of `quotation_ref`.
+      schema:
+        type: string
+    - name: created_from
+      in: query
+      required: false
+      description: Include payments created at or after this RFC3339 timestamp.
+      schema:
+        type: string
+        format: date-time
+    - name: createdFrom
+      in: query
+      required: false
+      description: Alias of `created_from`.
+      schema:
+        type: string
+        format: date-time
+    - name: created_to
+      in: query
+      required: false
+      description: Include payments created before this RFC3339 timestamp (must be after `created_from`).
+      schema:
+        type: string
+        format: date-time
+    - name: createdTo
+      in: query
+      required: false
+      description: Alias of `created_to`.
+      schema:
+        type: string
+        format: date-time
+    - $ref: ../parameters/state.yaml#/components/parameters/State
+    - $ref: ../parameters/states.yaml#/components/parameters/States
+    - $ref: ../parameters/filter_states.yaml#/components/parameters/FilterStates
+  responses:
+    '200':
+      description: Payments list
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/payment.yaml#/components/schemas/PaymentsData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError
@@ -0,0 +1,37 @@
+post:
+  tags: [Payments]
+  summary: Quote multiple payment intents
+  description: |
+    Calculates a batch quote for multiple payment intents in one request. Each item includes
+    `executable`, `state`, and optional `blockReason` so callers can skip blocked items. Raw
+    `card` destinations can omit expiry while quoting, but quoted items intended for later
+    execution should include `exp_month` and `exp_year`. Card-recipient AML screening is not
+    performed during quotation; it runs during payment execution, so an executable quote does
+    not guarantee AML acceptance.
+  operationId: paymentsMultiQuote
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/organizations_ref.yaml#/components/parameters/OrganizationsRef
+  requestBody:
+    $ref: ./bodies/payment.yaml#/components/requestBodies/QuotePaymentsBody
+  responses:
+    '200':
+      description: Quotes generated
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/payment.yaml#/components/schemas/PaymentQuotesData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError
@@ -0,0 +1,31 @@
+get:
+  tags: [Payments]
+  summary: Get payment by reference
+  description: Returns a single payment by `payments_ref`.
+  operationId: paymentsGet
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/payments_ref.yaml#/components/parameters/PaymentsRef
+  responses:
+    '200':
+      description: Payment data
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/payment.yaml#/components/schemas/PaymentData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '404':
+      $ref: ../response/operation.yaml#/components/responses/NotFound
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError
@@ -0,0 +1,37 @@
+post:
+  tags: [Payments]
+  summary: Quote single payment intent
+  description: |
+    Calculates quote for one payment intent without executing payment. The response includes
+    `quote.executable`, `quote.state`, and optional `quote.blockReason` so clients can reject
+    non-executable quotes before attempting execution. Raw `card` destinations can omit expiry
+    while quoting, but quotes intended for later execution should include `exp_month` and
+    `exp_year`. Card-recipient AML screening is not performed during quotation; it runs during
+    payment execution, so an executable quote does not guarantee AML acceptance.
+  operationId: paymentsQuote
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/organizations_ref.yaml#/components/parameters/OrganizationsRef
+  requestBody:
+    $ref: ./bodies/payment.yaml#/components/requestBodies/QuotePaymentBody
+  responses:
+    '200':
+      description: Quote generated
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    $ref: ./response/payment.yaml#/components/schemas/PaymentQuoteData
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError
@@ -0,0 +1,30 @@
+get:
+  tags: [Payments]
+  summary: Get discovery registry snapshot for payments dependencies
+  description: Returns the latest discovery lookup payload used by payments integrations.
+  operationId: paymentsRegistryList
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/organizations_ref.yaml#/components/parameters/OrganizationsRef
+  responses:
+    '200':
+      description: Discovery registry payload
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    type: object
+                    additionalProperties: true
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError
@@ -0,0 +1,32 @@
+get:
+  tags: [Payments]
+  summary: Get latest discovery refresh event for payments dependencies
+  description: Returns the latest refresh event consumed by the payments API.
+  operationId: paymentsRegistryRefreshGet
+  security:
+    - bearerAuth: []
+  parameters:
+    - $ref: ../parameters/organizations_ref.yaml#/components/parameters/OrganizationsRef
+  responses:
+    '200':
+      description: Discovery refresh payload
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: ../response/response.yaml#/components/schemas/BaseResponse
+              - type: object
+                properties:
+                  data:
+                    type:
+                      - object
+                      - 'null'
+                    additionalProperties: true
+    '400':
+      $ref: ../response/operation.yaml#/components/responses/BadRequest
+    '401':
+      $ref: ../response/operation.yaml#/components/responses/Unauthorized
+    '403':
+      $ref: ../response/operation.yaml#/components/responses/Forbidden
+    '500':
+      $ref: ../response/operation.yaml#/components/responses/InternalServerError
@@ -0,0 +1,163 @@
+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
@@ -0,0 +1,114 @@
+components:
+  schemas:
+    PaymentQuoteData:
+      description: Response payload for a single payment quote.
+      type: object
+      additionalProperties: false
+      required:
+        - accessToken
+        - quote
+      properties:
+        accessToken:
+          description: Refreshed access token to be used in subsequent API calls.
+          $ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
+        idempotencyKey:
+          description: Idempotency key associated with the quote response.
+          type: string
+        clientPaymentRef:
+          description: Caller-supplied payment correlation reference echoed from the quote request, when provided.
+          type: string
+        quote:
+          description: Generated quote data for the requested payment intent.
+          $ref: ../../../models/payment/payment.yaml#/components/schemas/PaymentQuote
+
+    PaymentQuotesData:
+      description: Response payload for a batch quote request.
+      type: object
+      additionalProperties: false
+      required:
+        - accessToken
+        - quote
+      properties:
+        accessToken:
+          description: Refreshed access token to be used in subsequent API calls.
+          $ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
+        quote:
+          description: Batch quote summary and quoted items.
+          type: object
+          additionalProperties: false
+          properties:
+            idempotencyKey:
+              description: Idempotency key associated with the batch quote response.
+              type: string
+            clientPaymentRef:
+              description: Caller-supplied payment correlation reference echoed from the batch quote request, when provided.
+              type: string
+            quoteRef:
+              description: Reference to the generated batch quote.
+              type: string
+            items:
+              description: Collection of quotes for each requested payment intent.
+              type: array
+              items:
+                $ref: ../../../models/payment/payment.yaml#/components/schemas/PaymentQuote
+
+    PaymentsData:
+      description: Response payload containing a list of payments.
+      type: object
+      additionalProperties: false
+      required:
+        - accessToken
+        - payments
+      properties:
+        accessToken:
+          description: Refreshed access token to be used in subsequent API calls.
+          $ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
+        payments:
+          description: Collection of payment records.
+          type: array
+          items:
+            $ref: ../../../models/payment/payment.yaml#/components/schemas/Payment
+        page:
+          description: Pagination cursor metadata for payment listing endpoints.
+          $ref: ../../../models/common/pagination.yaml#/components/schemas/CursorPageResponse
+
+    PaymentData:
+      description: Response payload containing a single payment record.
+      type: object
+      additionalProperties: false
+      required:
+        - accessToken
+        - payment
+      properties:
+        accessToken:
+          description: Refreshed access token to be used in subsequent API calls.
+          $ref: ../../../models/auth/token_data.yaml#/components/schemas/TokenData
+        payment:
+          description: Requested payment record.
+          $ref: ../../../models/payment/payment.yaml#/components/schemas/Payment
+
+    FXCurrenciesData:
+      description: Response payload containing the BFF startup-cached Treasury FX currency catalogue projection.
+      type: object
+      additionalProperties: false
+      required:
+        - currencies
+      properties:
+        currencies:
+          description: Client-visible currencies backed by Treasury Currency Catalog metadata.
+          type: array
+          items:
+            $ref: ../../../models/payment/fx_metadata.yaml#/components/schemas/FXCurrency
+
+    FXDirectionsData:
+      description: Response payload containing organization-level directed FX availability.
+      type: object
+      additionalProperties: false
+      required:
+        - directions
+      properties:
+        directions:
+          description: Directions with at least one eligible direction-level route for the organization.
+          type: array
+          items:
+            $ref: ../../../models/payment/fx_metadata.yaml#/components/schemas/FXDirection