openapi: 3.1.0
info:
  title: Fintecture Account Information Services Accounts Payments API
  description: 'PSD2 Account Information Services. Authenticates a PSU at their bank using either the redirect or decoupled (mobile-app) model, then retrieves bank accounts, balances, holders, and transactions. Also exposes the AIS-backed identity verification endpoint.

    '
  version: v2
  contact:
    name: Fintecture Support
    url: https://fintecture.com/contact
servers:
- url: https://api.fintecture.com
  description: Production
- url: https://api-sandbox.fintecture.com
  description: Sandbox
security:
- BearerAuth: []
tags:
- name: Payments
  description: Create and inspect payment sessions
paths:
  /pis/v2/connect:
    post:
      summary: Create A Payment Session
      description: 'Creates a payment session for a PSU to initiate an Immediate Transfer, Smart Transfer, or Buy Now Pay Later payment. To mix them in a single session, use the Payment Hub semantics. Signature, digest, date and x-request-id headers are mandatory in production.

        '
      operationId: createPisV2Connect
      tags:
      - Payments
      parameters:
      - $ref: '#/components/parameters/SignatureHeader'
      - $ref: '#/components/parameters/DigestHeader'
      - $ref: '#/components/parameters/DateHeader'
      - $ref: '#/components/parameters/RequestIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentConnectRequest'
      responses:
        '200':
          description: Connect URL returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentConnectResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /pis/v2/payments:
    get:
      summary: Get All Payments
      description: List all payments linked to the calling application. Supports filters.
      operationId: getPisV2Payments
      tags:
      - Payments
      parameters:
      - in: query
        name: filter[status]
        schema:
          type: string
      - in: query
        name: filter[from]
        schema:
          type: string
          format: date
      - in: query
        name: filter[to]
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Payment list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentList'
  /pis/v2/payments/{payment_id}:
    get:
      summary: Get Specific Payment
      description: Detailed information for a specific payment session.
      operationId: getPaymentSession
      tags:
      - Payments
      parameters:
      - $ref: '#/components/parameters/PaymentIdPath'
      responses:
        '200':
          description: Payment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
    patch:
      summary: Update A Payment
      description: Modify information on a specific payment.
      operationId: patchPisV2PaymentSession
      tags:
      - Payments
      parameters:
      - $ref: '#/components/parameters/PaymentIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentPatch'
      responses:
        '200':
          description: Updated payment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
components:
  schemas:
    PaymentList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
        meta:
          type: object
          properties:
            count:
              type: integer
    PaymentMeta:
      type: object
      properties:
        psu_name:
          type: string
        psu_email:
          type: string
          format: email
        psu_phone:
          type: string
        psu_address:
          type: string
    Error:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              status:
                type: string
              code:
                type: string
              title:
                type: string
              detail:
                type: string
    PaymentConnectRequest:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          $ref: '#/components/schemas/PaymentMeta'
        data:
          type: object
          properties:
            type:
              type: string
              enum:
              - PIS
            attributes:
              $ref: '#/components/schemas/PaymentAttributes'
    Payment:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - PIS
        attributes:
          $ref: '#/components/schemas/PaymentAttributes'
        status:
          type: string
          enum:
          - payment_created
          - payment_pending
          - payment_initiated
          - payment_completed
          - payment_rejected
          - payment_cancelled
          - payment_failed
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    PaymentPatch:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/PaymentMeta'
        data:
          type: object
          properties:
            attributes:
              type: object
              properties:
                communication:
                  type: string
    PaymentAttributes:
      type: object
      required:
      - amount
      - currency
      - communication
      properties:
        amount:
          type: string
          description: Amount in the given currency, as a string (e.g. "12.34").
        currency:
          type: string
          enum:
          - EUR
          - GBP
          - PLN
        customer_id:
          type: string
        end_to_end_id:
          type: string
        communication:
          type: string
          description: Free-form payment communication / remittance information.
        beneficiary:
          type: object
          properties:
            name:
              type: string
            iban:
              type: string
            bic:
              type: string
        payment_method:
          type: string
          enum:
          - immediate_transfer
          - smart_transfer
          - bnpl
    PaymentConnectResponse:
      type: object
      properties:
        meta:
          type: object
          properties:
            session_id:
              type: string
            status:
              type: string
            url:
              type: string
              format: uri
            code:
              type: string
  parameters:
    RequestIdHeader:
      in: header
      name: x-request-id
      required: true
      description: Unique request identifier (UUID v4 recommended).
      schema:
        type: string
        format: uuid
    PaymentIdPath:
      in: path
      name: payment_id
      required: true
      schema:
        type: string
    SignatureHeader:
      in: header
      name: Signature
      required: true
      description: HTTP message signature (RFC draft-cavage-http-signatures).
      schema:
        type: string
    DigestHeader:
      in: header
      name: Digest
      required: true
      description: SHA-256 digest of the request body, base64-encoded, prefixed with `SHA-256=`.
      schema:
        type: string
    DateHeader:
      in: header
      name: Date
      required: true
      schema:
        type: string
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT