openapi: 3.1.0
info:
  title: Adfin API
  description: >-
    Adfin uses OAuth 2.0 access tokens to authenticate all API requests.


    There are two contexts in which tokens are issued:


    - **Biller Access Tokens** — Generated via the Authorization Code flow when
    a biller connects their Adfin account. These tokens grant access to that
    biller's data (invoices, payment requests, customers, etc.).


    - **Platform Access Tokens** — Generated via the Client Credentials flow for
    Adfin's own integrations and system events. These tokens authenticate Adfin
    as the platform itself (not as a specific biller) and are required for
    endpoints like `/api/webhook`.
  version: 1.0.0
servers:
  - url: https://api.adfin.com/api
    description: Production API Server URL
  - url: https://api.staging.adfin.com/api
    description: Staging API Server URL
security:
  - Biller Access Token (Production): []
  - Biller Access Token (Staging): []
  - Adfin Bearer Token: []
tags:
  - name: Invoices
  - name: Recurring invoices
  - name: Payment requests
  - name: Recurring payment requests
  - name: Payments
  - name: oAuth2
  - name: Biller
  - name: Customers
  - name: Direct debit mandates
  - name: Tax rates
  - name: Items
  - name: Workflows
  - name: Webhooks
paths:
  /payment_requests/bulk_import:
    post:
      tags:
        - Payment requests
      summary: Bulk import payment requests
      operationId: bulkImport
      parameters:
        - name: collectionMethod
          in: query
          description: >-
            How the imported payment requests are expected to be collected.
            Currently, only NONE is supported.
          required: true
          schema:
            type: string
            description: >-
              How the imported payment requests are expected to be collected.
              Currently, only NONE is supported.
            enum:
              - AUTO_COLLECT
              - ON_DEMAND
              - NONE
            example: NONE
          example: NONE
        - name: deleteMissingPaymentRequests
          in: query
          description: >-
            Whether missing payment requests created in previous imports should
            be deleted.
          required: true
          schema:
            type: boolean
            description: >-
              Whether missing payment requests created in previous imports
              should be deleted.
            example: false
          example: false
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                inputFile:
                  type: string
                  format: binary
                  description: Input file to be processed during the bulk import.
              required:
                - inputFile
            examples:
              Bulk Import Request:
                summary: Example bulk import request
                description: >-
                  Upload a input file with payment requests along with
                  collection method and delete flag
                value: |
                  collectionMethod: NONE
                  deleteMissingPaymentRequests: false
                  inputFile: (binary file - payment_requests.csv)
        required: true
      responses:
        '202':
          description: The bulk import request has been accepted for processing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkPaymentRequestImportResponse'
              example:
                jobId: 550e8400-e29b-41d4-a716-446655440000
                type: BULK_PAYMENT_REQUEST_IMPORT
                status: PENDING
                creationTime: '2024-01-15T10:30:00Z'
                countsByItemStatus: []
        '400':
          description: >-
            There was an issue reading or understanding the request. Please
            ensure that it adheres to the required format and includes all
            necessary parameters.
        '401':
          description: Authentication is required.
        '422':
          description: A validation error occurred with the request.
        '500':
          description: The server was unable to process the request.
  /payment_requests/bulk_import/{jobId}:
    get:
      tags:
        - Payment requests
      summary: Retrieve bulk payment request import job details
      operationId: getBulkPaymentRequestImportJobDetails
      parameters:
        - name: jobId
          in: path
          description: The ID of the bulk payment request import job
          required: true
          schema:
            type: string
            format: uuid
            description: The ID of the bulk payment request import job
      responses:
        '200':
          description: >-
            The bulk payment request import job details were successfully
            retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkPaymentRequestImportResponse'
              example:
                jobId: 550e8400-e29b-41d4-a716-446655440000
                type: BULK_PAYMENT_REQUEST_IMPORT
                status: COMPLETED
                creationTime: '2024-01-15T10:30:00Z'
                countsByItemStatus:
                  - status: COMPLETED
                    count: 150
                  - status: PROCESSING
                    count: 5
        '400':
          description: >-
            There was an issue reading or understanding the request. Please
            ensure that it adheres to the required format and includes all
            necessary parameters.
        '401':
          description: Authentication is required.
        '404':
          description: Bulk payment request import job not found.
        '422':
          description: A validation error occurred with the request.
        '500':
          description: The server was unable to process the request.
  /payment_requests/bulk_import/{jobId}/items:
    get:
      tags:
        - Payment requests
      summary: Retrieve bulk payment request import job items
      operationId: getBulkPaymentRequestImportJobItems
      parameters:
        - name: jobId
          in: path
          description: The ID of the bulk payment request import job
          required: true
          schema:
            type: string
            format: uuid
            description: The ID of the bulk payment request import job
        - name: statuses
          in: query
          description: |
            The status of the bulk payment request import job item
            * PENDING: The item is still to be processed.
            * PROCESSING: The item is currently processing.
            * COMPLETED: The item has been processed.
            * FAILED: The item has failed to be processed.
          required: false
          schema:
            type: array
            description: |
              The status of the bulk payment request import job item
              * PENDING: The item is still to be processed.
              * PROCESSING: The item is currently processing.
              * COMPLETED: The item has been processed.
              * FAILED: The item has failed to be processed.
            items:
              type: string
              description: |
                The status of the bulk payment request import job item
                * PENDING: The item is still to be processed.
                * PROCESSING: The item is currently processing.
                * COMPLETED: The item has been processed.
                * FAILED: The item has failed to be processed.
              enum:
                - PENDING
                - PROCESSING
                - COMPLETED
                - FAILED
        - name: page
          in: query
          description: Zero-based page index (0..N)
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: size
          in: query
          description: The size of the page to be returned
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
        - name: sort
          in: query
          description: >-
            Sorting criteria in the format: property,(asc|desc). Default sort
            order is ascending. Multiple sort criteria are supported.
          required: false
          schema:
            type: array
            default:
              - creationTime,ASC
            items:
              type: string
      responses:
        '200':
          description: >-
            Paginated response for the list of bulk payment request import job
            items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkPaymentRequestImportItemsResponse'
              example:
                items:
                  - id: 123e4567-e89b-12d3-a456-426614174000
                    jobId: 550e8400-e29b-41d4-a716-446655440000
                    paymentRequestNo: PR-2024-001
                    bulkPrImportOperation: UPSERT
                    status: FAILED
                    statusReason: Operation has failed
                    creationTime: '2024-01-15T10:30:00Z'
                  - id: 223e4567-e89b-12d3-a456-426614174001
                    jobId: 550e8400-e29b-41d4-a716-446655440000
                    paymentRequestNo: PR-2024-002
                    bulkPrImportOperation: DELETE
                    status: PENDING
                    creationTime: '2024-01-15T10:30:01Z'
                pagination:
                  page: 0
                  size: 20
                  totalElements: 155
                  totalPages: 8
        '400':
          description: >-
            A problem reading or understanding the request. Ensure that the
            request complies with the required format and includes all necessary
            parameters.
        '401':
          description: Authentication required - Invalid or missing authorization headers.
        '404':
          description: Bulk payment request import job not found.
        '422':
          description: A request validation error.
        '500':
          description: The server could not process the request.
components:
  schemas:
    BulkPaymentRequestImportResponse:
      type: object
      description: Bulk payment request import response
      properties:
        jobId:
          type: string
          description: The internal id of the bulk import job
        type:
          type: string
          description: The type of the import job
          enum:
            - BULK_PAYMENT_REQUEST_IMPORT
        status:
          type: string
          description: The status of the import job
          enum:
            - PENDING
            - PROCESSING
            - COMPLETED
            - FAILED
            - DELETED
        creationTime:
          type: string
          format: date-time
          description: The creation time of the import job
        countsByItemStatus:
          type: array
          description: The count of items for each review session item status
          items:
            $ref: '#/components/schemas/ReviewSessionItemCountByStatus'
      required:
        - countsByItemStatus
        - creationTime
        - jobId
        - status
        - type
    ReviewSessionItemCountByStatus:
      type: object
      properties:
        status:
          type: string
          description: The status of review session item
          enum:
            - PENDING
            - PROCESSING
            - COMPLETED
            - FAILED
        count:
          type: integer
          format: int32
          description: The count of items for this status
      required:
        - count
        - status
    BulkPaymentRequestImportItemResponse:
      type: object
      description: A bulk payment request import job item
      properties:
        id:
          type: string
          format: uuid
          description: The ID of the import job item
        jobId:
          type: string
          format: uuid
          description: The ID of the import job
        paymentRequestNo:
          type: string
          description: The payment request number
        bulkPrImportOperation:
          type: string
          description: The operation to perform on the import job item
          enum:
            - UPSERT
            - DELETE
        status:
          type: string
          description: The status of the import job item
          enum:
            - PENDING
            - PROCESSING
            - COMPLETED
            - FAILED
        statusReason:
          type: string
          description: The reason behind the item's current status
        creationTime:
          type: string
          format: date-time
          description: The creation time of import job item
      required:
        - bulkPrImportOperation
        - creationTime
        - id
        - jobId
        - paymentRequestNo
        - status
        - statusReason
    BulkPaymentRequestImportItemsResponse:
      type: object
      description: Paginated bulk payment request import job items
      properties:
        items:
          type: array
          description: The bulk payment request import job items for the current page
          items:
            $ref: '#/components/schemas/BulkPaymentRequestImportItemResponse'
        pagination:
          $ref: '#/components/schemas/Pagination'
          description: Pagination metadata
    Pagination:
      type: object
      description: Contains pagination information for a set of results
      properties:
        page:
          type: integer
          format: int32
          description: The current page number One-based page index (1..N).
        size:
          type: integer
          format: int32
          description: The size of the page, i.e., the number of elements per page.
        totalPages:
          type: integer
          format: int32
          description: The total number of pages available.
        totalElements:
          type: integer
          format: int64
          description: The total number of elements across all pages.
        numberOfElements:
          type: integer
          format: int64
          description: The number of elements in the current page.
        sort:
          type: string
          description: 'Sorting criteria in the format: property,(asc|desc).'
  securitySchemes:
    Biller Access Token (Production):
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.adfin.com/api/oauth2/token
          scopes: {}
    Platform Bearer Token:
      type: http
      scheme: Bearer
    Biller Access Token (Staging):
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.staging.adfin.com/api/oauth2/token
          scopes: {}
