openapi: 3.0.2
info:
  title: Banking Service partner API
  version: '1.0'
servers:
  - url: 'https://api.bankingservice.ai'
  - url: 'https://sandbox.api.bankingservice.ai'
  - url: 'https://staging.api.bankingservice.ai'
  - url: 'https://acceptance.api.bankingservice.ai'
  - url: 'https://experimental.api.bankingservice.ai'
  - url: 'https://internal.api.bankingservice.ai'
paths:
  /v1/profiles:
    get:
      description: Returns a list of all the profiles
      security:
        - oAuth2: []
      parameters: null
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Profile'
  '/v1/profiles/{profileId}':
    get:
      description: Returns a profile
      security:
        - oAuth2: []
      parameters:
        - name: partnerId
          in: path
          required: true
          description: The id of the partner to retrieve
          schema:
            type: string
        - $ref: '#/components/parameters/profileId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
  '/v1/profiles/{profileId}/payments':
    post:
      description: Creates a payment flow.
      security:
        - oAuth2: []
      parameters:
        - $ref: '#/components/parameters/profileId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - method
                - description
                - amount
                - currency
              properties:
                reference:
                  type: string
                  example: b5c9d214-f408-4215-990e-f892c24a6080
                  description: 'Your internal reference, we index this reference for you to search later, not required to use. We also use this for idempotency'
                method:
                  $ref: '#/components/schemas/PaymentMethod'
                description:
                  type: string
                  example: Description of the payment shown to the PSU
                shipping:
                  $ref: '#/components/schemas/Payment/properties/billing'
                billing:
                  $ref: '#/components/schemas/Payment/properties/billing'
                currency:
                  $ref: '#/components/schemas/Currency'
                customer:
                  type: string
                  description: ID of the customer that is paying
                creditcard:
                  oneOf:
                    - type: object
                      description: 'Creditcard credentials, if you send a plain card number, or cvc, you need to be PCI DSS certified'
                      properties:
                        card:
                          type: object
                          required:
                            - number
                            - cvc
                            - expiration
                            - holder_name
                          properties:
                            number:
                              type: string
                              example: 5571050319405406
                              description: Plain card number
                            cvc:
                              type: string
                              exapmle: 301
                              description: CVC code of the card
                            holder_name:
                              type: string
                              example: FRANCES KUHIC
                              description: 'Name on the card, holder name'
                            expiration:
                              type: string
                              description: 'ISO date, with the date set to 1, hours, minutes, seconds, and miliseconds to 0'
                              example: 2024-09-25T00:00:00.000Z
                payment_method:
                  type: string
                  description: 'Payment method to be used for execution of this payment, this payment method must be one of the payment methods of the customer, required when customer is set.'
                ideal:
                  type: object
                  properties:
                    bic:
                      type: string
                      example: ABNANL2AXXX
                sepa_direct_debit:
                  type: object
                  required:
                    - sequence_type
                    - mandate
                  properties:
                    sequence_type:
                      type: string
                      enum:
                        - final
                        - first
                        - oneoff
                        - recurring
                    mandate:
                      type: object
                      required:
                        - id
                        - date
                      properties:
                        id:
                          type: string
                          example: 7f159668-b7ef-464e-84c4-089e35de4066
                          description: Free form ID of the mandate contract reference
                        date:
                          type: string
                          format: ISO 8601
                          example: 2024-09-25T12:01:00.103Z
                          description: Date of when the mandate was signed
                sepa:
                  type: object
                  required:
                    - iban
                    - bic
                    - holder_name
                  properties:
                    holder_name:
                      type: string
                      exmaple: John Doe
                    iban:
                      type: string
                      example: NL27ABNA7020127142
                    bic:
                      type: string
                      example: ABNANL2AXXX
                amount:
                  type: number
                  example: 8230
                  description: Amount of the payment in cents of the currency
                metadata:
                  $ref: '#/components/schemas/Metadata'
                user:
                  type: object
                  required:
                    - ip_address
                    - language
                  properties:
                    user_agent:
                      type: string
                      exmaple: 'Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0'
                    accept:
                      type: string
                      example: 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7'
                    accept_encoding:
                      type: string
                      example: 'gzip, deflate, br, zstd'
                    accept_language:
                      type: string
                      example: 'en-GB,en-US;q=0.9,en;q=0.8'
                    accept_charset:
                      type: string
                      example: UTF-8
                    screen_width:
                      type: number
                    screen_height:
                      type: number
                    color_depth:
                      type: number
                    java_enabled:
                      type: boolean
                    javascript_enabled:
                      type: boolean
                    ip_address:
                      type: string
                      example: 217.138.20.120
                      description: IP address of the user
                    language:
                      $ref: '#/components/schemas/Language'
                terminal:
                  type: object
                  required:
                    - id
                  properties:
                    id:
                      type: string
                      example: terminal_h82kd823
                openbanking:
                  type: object
                  required:
                    - type
                  properties:
                    type:
                      type: string
                      enum:
                        - sepa
                        - sepa_instant
                    execution:
                      type: string
                      format: ISO 8601
                      example: 2024-09-25T12:01:00.103Z
                    bic:
                      type: string
                      example: INGBNL2AXXX
                    country:
                      type: string
                session:
                  type: object
                  required:
                    - redirect_url
                  properties:
                    redirect_url:
                      type: string
                      example: 'https://www.bankingservice.ai/result'
                    webhook_url:
                      type: string
                      description: 'Additional webhook URL that is called, note that this webhook is additional to the webhook registered to the partner or profile'
                      example: 'https://www.bankingservice.ai/result'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestError'
    get:
      description: Returns a paged list of all the payments
      security:
        - oAuth2: []
      parameters:
        - $ref: '#/components/parameters/profileId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    example: 0
                    description: The current page
                  pages:
                    type: number
                    example: 620
                    description: The total number of pages
                  size:
                    type: number
                    example: 20
                    description: Size of the page returned
                  count:
                    type: number
                    example: 12383
                    description: The total count of the payments
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Payment'
  '/v1/profiles/{profileId}/payments/{paymentId}':
    get:
      description: 'Returns the status of the payment, and payment data'
      security:
        - oAuth2: []
      parameters:
        - $ref: '#/components/parameters/profileId'
        - $ref: '#/components/parameters/paymentId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
    delete:
      description: 'Cancels a payment flow, or initaited payment, whenever possible.'
      security:
        - oAuth2: []
      parameters:
        - $ref: '#/components/parameters/profileId'
        - $ref: '#/components/parameters/paymentId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestError'
  '/v1/profiles/{profileId}/customers':
    post:
      description: Creates a customer
      security:
        - oAuth2: []
      parameters:
        - $ref: '#/components/parameters/profileId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: PSU creation customer type
              properties:
                company:
                  type: string
                  description: Company name
                first_name:
                  type: string
                  description: First name of the customer
                  example: John
                last_name:
                  type: string
                  description: Last name of the customer
                  example: Doe
                email:
                  type: string
                  description: Email adderss of the customer
                  example: john.doe@gmail.com
                phone:
                  type: string
                  example: '318000201068'
                address:
                  $ref: '#/components/schemas/Address'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestError'
    get:
      description: Returns a paged list of all the customers
      security:
        - oAuth2: []
      parameters:
        - $ref: '#/paths/~1v1~1profiles~1%7BprofileId%7D/get/parameters/0'
        - $ref: '#/components/parameters/profileId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  page:
                    type: number
                    example: 0
                    description: The current page
                  pages:
                    type: number
                    example: 620
                    description: The total number of pages
                  size:
                    type: number
                    example: 20
                    description: Size of the page returned
                  count:
                    type: number
                    example: 12383
                    description: The total count of the customers
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
  '/v1/profiles/{profileId}/customers/{customerId}':
    get:
      description: Returns the data of the customer
      security:
        - oAuth2: []
      parameters:
        - $ref: '#/components/parameters/profileId'
        - $ref: '#/components/parameters/customerId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
    put:
      description: Updates a customer
      security:
        - oAuth2: []
      parameters:
        - $ref: '#/components/parameters/profileId'
        - $ref: '#/components/parameters/customerId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/paths/~1v1~1profiles~1%7BprofileId%7D~1customers/post/requestBody/content/application~1json/schema'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestError'
    delete:
      description: Deletes the customer
      security:
        - oAuth2: []
      parameters:
        - $ref: '#/components/parameters/profileId'
        - $ref: '#/components/parameters/customerId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestError'
  '/v1/profiles/{profileId}/customers/{customerId}/payment-methods':
    post:
      description: Creates a customer
      security:
        - oAuth2: []
      parameters:
        - $ref: '#/components/parameters/profileId'
        - $ref: '#/components/parameters/customerId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: PSU creation customer payment method type
              properties:
                reference:
                  type: string
                  example: b5c9d214-f408-4215-990e-f892c24a6080
                  description: 'Your internal reference, we index this reference for you to search later, not required to use. We also use this for idempotency'
                method:
                  $ref: '#/components/schemas/PaymentMethod'
                description:
                  type: string
                  example: Description of the payment shown to the PSU
                sepa:
                  type: object
                  required:
                    - iban
                    - bic
                    - holder_name
                  properties:
                    holder_name:
                      type: string
                      exmaple: John Doe
                    iban:
                      type: string
                      example: NL27ABNA7020127142
                    bic:
                      type: string
                      example: ABNANL2AXXX
                openbanking:
                  type: object
                  required: null
                  properties:
                    bic:
                      type: string
                      example: INGBNL2AXXX
                    country:
                      type: string
                    recurring:
                      type: object
                      required:
                        - amount
                        - currency
                        - frequency
                      properties:
                        amount:
                          type: number
                          example: 8230
                          description: Amount of the payment in cents of the currency
                        currency:
                          $ref: '#/components/schemas/Currency'
                        frequency:
                          type: string
                          enum:
                            - daily
                            - weekly
                            - bi_weekly
                            - monthly
                            - bi_monthly
                            - quarterly
                            - semi_annual
                            - annual
                        day_of_execution:
                          type: number
                          example: 1
                          description: 'The day that the payment should execute, must banks ingore this value and will execute the fist payment on the start date, and each subsecent payment after the frequency specified.'
                        month_of_execution:
                          type: number
                          example: 12
                          description: 'The month that the payment should execute, must banks ingore this value and will execute the fist payment on the start date, and each subsecent payment after the frequency specified.'
                        start_date:
                          type: string
                          format: ISO 8601
                          example: 2024-09-25T12:01:00.103Z
                          description: 'The date that the first recurring payment should be sent, some banks don''t allow this date to be the same, date, when this is the case, we will adjust it to the next date.'
                        end_date:
                          type: string
                          format: ISO 8601
                          example: 2024-09-25T12:01:00.103Z
                          description: 'The date that the transactions should stop, if not defined we will try the longest possible term, i.e. (indefinte, untill the year 9999, or in 100 years, depending on the issuing bank)'
                user:
                  type: object
                  required:
                    - ip_address
                    - language
                  properties:
                    user_agent:
                      type: string
                      exmaple: 'Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0'
                    accept:
                      type: string
                      example: 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7'
                    accept_encoding:
                      type: string
                      example: 'gzip, deflate, br, zstd'
                    accept_language:
                      type: string
                      example: 'en-GB,en-US;q=0.9,en;q=0.8'
                    accept_charset:
                      type: string
                      example: UTF-8
                    ip_address:
                      type: string
                      example: 217.138.20.120
                      description: IP address of the user
                    language:
                      $ref: '#/components/schemas/Language'
                metadata:
                  $ref: '#/components/schemas/Metadata'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: PSU customer type
                required:
                  - id
                  - created
                properties:
                  id:
                    type: string
                    readOnly: true
                  state:
                    type: string
                    example: null
                    enum:
                      - created
                      - failed
                      - processing
                      - succeeded
                      - expired
                  reference:
                    type: string
                    example: b5c9d214-f408-4215-990e-f892c24a6080
                    description: 'Your internal reference, we index this reference for you to search later, not required to use. We also use this for idempotency'
                  method:
                    $ref: '#/components/schemas/PaymentMethod'
                  description:
                    type: string
                    example: Description of the payment shown to the PSU
                  sepa:
                    type: object
                    properties:
                      holder_name:
                        type: string
                        exmaple: John Doe
                      last4:
                        type: string
                        example: 0394
                      bic:
                        type: string
                        example: ABNANL2AXXX
                      country:
                        type: string
                        example: NL
                  openbanking:
                    type: object
                    required: null
                    properties:
                      bic:
                        type: string
                        example: INGBNL2AXXX
                      country:
                        type: string
                      recurring:
                        type: object
                        required:
                          - amount
                          - currency
                          - frequency
                        properties:
                          amount:
                            type: number
                            example: 8230
                            description: Amount of the payment in cents of the currency
                          currency:
                            $ref: '#/components/schemas/Currency'
                          frequency:
                            type: string
                            enum:
                              - daily
                              - weekly
                              - bi_weekly
                              - monthly
                              - bi_monthly
                              - quarterly
                              - semi_annual
                              - annual
                          day_of_execution:
                            type: number
                            example: 1
                            description: 'The day that the payment should execute, must banks ingore this value and will execute the fist payment on the start date, and each subsecent payment after the frequency specified.'
                          month_of_execution:
                            type: number
                            example: 12
                            description: 'The month that the payment should execute, must banks ingore this value and will execute the fist payment on the start date, and each subsecent payment after the frequency specified.'
                          start_date:
                            type: string
                            format: ISO 8601
                            example: 2024-09-25T12:01:00.103Z
                            description: 'The date that the first recurring payment should be sent, some banks don''t allow this date to be the same, date, when this is the case, we will adjust it to the next date.'
                          end_date:
                            type: string
                            format: ISO 8601
                            example: 2024-09-25T12:01:00.103Z
                            description: 'The date that the transactions should stop, if not defined we will try the longest possible term, i.e. (indefinte, untill the year 9999, or in 100 years, depending on the issuing bank)'
                  user:
                    type: object
                    required:
                      - ip_address
                      - language
                    properties:
                      user_agent:
                        type: string
                        exmaple: 'Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0'
                      accept:
                        type: string
                        example: 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7'
                      accept_encoding:
                        type: string
                        example: 'gzip, deflate, br, zstd'
                      accept_language:
                        type: string
                        example: 'en-GB,en-US;q=0.9,en;q=0.8'
                      accept_charset:
                        type: string
                        example: UTF-8
                      ip_address:
                        type: string
                        example: 217.138.20.120
                        description: IP address of the user
                      language:
                        $ref: '#/components/schemas/Language'
                  created:
                    type: string
                    readOnly: true
                    example: 2024-09-25T12:01:00.103Z
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestError'
    get:
      description: Returns a paged list of all the customers
      security:
        - oAuth2: []
      parameters:
        - $ref: '#/components/parameters/profileId'
        - $ref: '#/components/parameters/customerId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/paths/~1v1~1profiles~1%7BprofileId%7D~1customers~1%7BcustomerId%7D~1payment-methods/post/responses/200/content/application~1json/schema'
  '/v1/profiles/{profileId}/customers/{customerId}/payment-methods/{customerPaymentMethodId}':
    get:
      description: Returns the data of the customer payment methods
      security:
        - oAuth2: []
      parameters:
        - $ref: '#/components/parameters/profileId'
        - $ref: '#/components/parameters/customerId'
        - $ref: '#/components/parameters/customerPaymentMethodId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/paths/~1v1~1profiles~1%7BprofileId%7D~1customers~1%7BcustomerId%7D~1payment-methods/post/responses/200/content/application~1json/schema'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
    delete:
      description: Deletes the customer payment method (if possible)
      security:
        - oAuth2: []
      parameters:
        - $ref: '#/components/parameters/profileId'
        - $ref: '#/components/parameters/customerId'
        - $ref: '#/components/parameters/customerPaymentMethodId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/paths/~1v1~1profiles~1%7BprofileId%7D~1customers~1%7BcustomerId%7D~1payment-methods/post/responses/200/content/application~1json/schema'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestError'
  '/v1/profiles/{profileId}/settlements':
    get:
      description: Returns a list of all the settlements
      security:
        - oAuth2: []
      parameters:
        - $ref: '#/components/parameters/profileId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Settlement'
  '/v1/profiles/{profileId}/settlements/{settlementId}':
    get:
      description: Returns a settlement
      security:
        - oAuth2: []
      parameters:
        - $ref: '#/components/parameters/profileId'
        - $ref: '#/components/parameters/settlementId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Settlement'
components:
  securitySchemes:
    oAuth2:
      type: oauth2
      description: This API uses OAuth 2 with the credentials grant flow.
      flows:
        clientCredentials:
          tokenUrl: /v1/oauth/token
          refreshUrl: /v1/oauth/token
  parameters:
    companyId:
      name: companyId
      in: path
      required: true
      description: The id of the company
      schema:
        type: string
    profileId:
      name: profileId
      in: path
      required: true
      description: The id of the profile
      schema:
        type: string
    paymentId:
      name: paymentId
      in: path
      required: true
      description: The id of the payment
      schema:
        type: string
    customerId:
      name: customerId
      in: path
      required: true
      description: The id of the customer
      schema:
        type: string
    settlementId:
      name: settlementId
      in: path
      required: true
      description: The id of the settlement
      schema:
        type: string
    terminalId:
      name: terminalId
      in: path
      required: true
      description: The id of the terminal
      schema:
        type: string
    customerPaymentMethodId:
      name: customerId
      in: path
      required: true
      description: The id of the customer payment method
      schema:
        type: string
  schemas:
    NotFoundError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          example: resource_not_found
        error_description:
          type: string
    Currency:
      type: string
      example: EUR
      description: ISO 3166-1 alpha-2 currency code
      enum:
        - AED
        - AFN
        - ALL
        - AMD
        - ANG
        - AOA
        - ARS
        - AUD
        - AWG
        - AZN
        - BAM
        - BBD
        - BDT
        - BGN
        - BHD
        - BIF
        - BMD
        - BND
        - BOB
        - BOV
        - BRL
        - BSD
        - BTN
        - BWP
        - BYN
        - BZD
        - CAD
        - CDF
        - CHE
        - CHF
        - CHW
        - CLF
        - CLP
        - CNY
        - COP
        - COU
        - CRC
        - CUP
        - CVE
        - CZK
        - DJF
        - DKK
        - DOP
        - DZD
        - EGP
        - ERN
        - ETB
        - EUR
        - FJD
        - FKP
        - GBP
        - GEL
        - GHS
        - GIP
        - GMD
        - GNF
        - GTQ
        - GYD
        - HKD
        - HNL
        - HTG
        - HUF
        - IDR
        - ILS
        - INR
        - IQD
        - IRR
        - ISK
        - JMD
        - JOD
        - JPY
        - KES
        - KGS
        - KHR
        - KMF
        - KPW
        - KRW
        - KWD
        - KYD
        - KZT
        - LAK
        - LBP
        - LKR
        - LRD
        - LSL
        - LYD
        - MAD
        - MDL
        - MGA
        - MKD
        - MMK
        - MNT
        - MOP
        - MRU
        - MUR
        - MVR
        - MWK
        - MXN
        - MXV
        - MYR
        - MZN
        - NAD
        - NGN
        - NIO
        - NOK
        - NPR
        - NZD
        - OMR
        - PAB
        - PEN
        - PGK
        - PHP
        - PKR
        - PLN
        - PYG
        - QAR
        - RON
        - RSD
        - RUB
        - RWF
        - SAR
        - SBD
        - SCR
        - SDG
        - SEK
        - SGD
        - SHP
        - SLE
        - SLL
        - SOS
        - SRD
        - SSP
        - STN
        - SVC
        - SYP
        - SZL
        - THB
        - TJS
        - TMT
        - TND
        - TOP
        - TRY
        - TTD
        - TWD
        - TZS
        - UAH
        - UGX
        - USD
        - USN
        - UYI
        - UYU
        - UYW
        - UZS
        - VED
        - VES
        - VND
        - VUV
        - WST
        - XAF
        - XAG
        - XAU
        - XBA
        - XBB
        - XBC
        - XBD
        - XCD
        - XDR
        - XOF
        - XPD
        - XPF
        - XPT
        - XSU
        - XTS
        - XUA
        - XXX
        - YER
        - ZAR
        - ZMW
        - ZWL
    Payment:
      type: object
      required:
        - id
        - method
        - description
        - amount
        - currency
        - created
      properties:
        id:
          type: string
          readOnly: true
          example: payment_282d732kd8ggjdj392jdhfi289
        reference:
          type: string
          example: b5c9d214-f408-4215-990e-f892c24a6080
          description: 'Your internal reference, we index this reference for you to search later, not required to use. We also use this for idempotency'
        method:
          $ref: '#/components/schemas/PaymentMethod'
        shipping:
          $ref: '#/components/schemas/Payment/properties/billing'
        billing:
          type: object
          description: Info about the customer
          properties:
            company:
              type: string
              description: Company name where the items are being shipped
            first_name:
              type: string
              description: First name of the receiving party
            last_name:
              type: string
              description: Last name of the receiving party
            phone:
              type: string
              description: Phone number of the receiving party
            address:
              $ref: '#/components/schemas/Address'
        openbanking:
          type: object
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - sepa
                - sepa_instant
            execution:
              type: string
              format: ISO 8601
              description: 'When the payment is scheduled to be executed, it is up to the issuinng bank to actually execute the payment.'
              example: 2024-09-25T12:01:00.103Z
            bic:
              type: string
              example: INGBNL2AXXX
            country:
              type: string
              description: Two letter ISO country code
              example: NL
        terminal:
          type: object
          properties:
            method:
              type: string
              enum:
                - point_of_sale
                - soft_pos
                - tap_to_pay_on_iphone
            emv:
              type: object
              properties:
                read_method:
                  type: string
                  description: How the card has been read
                  enum:
                    - emv
                    - magstripe
                    - contactless
                aid:
                  type: string
                  description: NFC AID version of the card i.e. A0000000043060
                  example: A0000000043060
                tsi:
                  type: string
                  description: TSI code
                tvr:
                  type: string
                  description: TVR code
                cryptogram:
                  type: string
                  description: 'Cryptogram value, i.e. FC1E8FCD740877C6'
                cryptogram_type:
                  type: string
                  enum:
                    - ARQC
                    - AAC
                    - TC
        ideal:
          type: object
          properties:
            bic:
              type: string
              example: ABNANL2AXXX
        creditcard:
          type: object
          properties:
            rrn:
              type: string
              description: 'Retrieval Reference Number, is used for identifying card transactions with acquirers, the customer is also shown this number on their statement'
            fees:
              type: object
              properties:
                interchange:
                  type: number
                  description: 'Interchange fees in cents, in the currency of the payment'
                assesment:
                  type: number
                  description: 'Total assesment ans scheme fees in cents, in the currency of the payment'
            card:
              type: object
              properties:
                scheme:
                  type: string
                  enum:
                    - visa
                    - mastercard
                    - meastro
                    - dankort
                    - interpayment
                    - unionpay
                    - vpay
                    - americanexpress
                    - diners
                    - discover
                    - jcb
                    - other
                type:
                  type: string
                  enum:
                    - debit
                    - credit
                    - commercial
                region:
                  type: string
                  enum:
                    - domestic
                    - inter
                    - intra
                last4:
                  type: string
                  description: Last 4 digits of the card number
                bin:
                  type: string
                  description: 'First 6 digits of the card number, identifying the bank'
                expiration:
                  type: string
                  description: Expiration date of the card (usually it is the month)
                holder_name:
                  type: string
                  description: The name on the card
                issuing_country:
                  type: string
                  description: Two letter ISO country code
                  example: NL
        sepa_direct_debit:
          type: object
          required:
            - sequence_type
            - mandate
          properties:
            sequence_type:
              type: string
              enum:
                - final
                - first
                - oneoff
                - recurring
            mandate:
              type: object
              required:
                - id
                - date
              properties:
                id:
                  type: string
                  example: 7f159668-b7ef-464e-84c4-089e35de4066
                  description: Free form ID of the mandate contract reference
                date:
                  type: string
                  format: ISO 8601
                  example: 2024-09-25T12:01:00.103Z
                  description: Date of when the mandate was signed
        sepa:
          type: object
          properties:
            holder_name:
              type: string
              exmaple: John Doe
            last4:
              type: string
              example: 0394
            bic:
              type: string
              example: ABNANL2AXXX
            country:
              type: string
              example: NL
        description:
          type: string
          example: Description of the payment shown to the PSU
        currency:
          $ref: '#/components/schemas/Currency'
        amount:
          type: number
          example: 8230
          description: Amount of the payment in cents of the currency
        state:
          type: string
          example: null
          enum:
            - created
            - succeeded
            - failed
            - processing
            - expired
        metadata:
          $ref: '#/components/schemas/Metadata'
        next:
          oneOf:
            - type: object
              readOnly: true
              properties:
                redirect:
                  type: string
                  readOnly: true
                  example: 'https://dashboard.bankingservice.ai/payments/payment_b6412838e2594e7eaffa28d48cfd02ee?reference=9869d4567b6d4fc49f3030c8ea4477da'
            - type: object
              readOnly: true
              properties:
                terminal:
                  type: string
                  readOnly: true
                  example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MTIzNDU2Nzg5LCJuYW1lIjoiSm9zZXBoIn0.OpOSSw7e485LOP5PrzScxHb7SR6sAOMRckfFwi4rp7o
        user:
          type: object
          required:
            - ip_address
            - language
          properties:
            user_agent:
              type: string
              exmaple: 'Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0'
            accept:
              type: string
              example: 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7'
            accept_encoding:
              type: string
              example: 'gzip, deflate, br, zstd'
            accept_language:
              type: string
              example: 'en-GB,en-US;q=0.9,en;q=0.8'
            accept_charset:
              type: string
              example: UTF-8
            ip_address:
              type: string
              example: 217.138.20.120
              description: IP address of the user
            language:
              $ref: '#/components/schemas/Language'
        session:
          type: object
          required:
            - redirect_url
          properties:
            redirect_url:
              type: string
              example: 'https://www.bankingservice.ai/result'
            webhook_url:
              type: string
              description: 'Additional webhook URL that is called, note that this webhook is additional to the webhook registered to the partner or profile'
              example: 'https://www.bankingservice.ai/result'
        created:
          type: string
          readOnly: true
          example: 2024-09-25T12:01:00.103Z
    PaymentMethod:
      type: string
      example: openbanking
      description: Payment method type ID
      enum:
        - openbanking
        - creditcard
        - terminal
        - internal
        - ideal
    Language:
      type: string
      example: en-EN
      description: Language code
      enum:
        - nl-NL
        - en-EN
    Metadata:
      type: object
      description: Free form key/ value pair
      example:
        key1: 123
        customer_id: 123object
        internal_reference: X938378B01
        debited: true
    Profile:
      type: object
      required:
        - id
        - trade_name
        - created
      properties:
        id:
          type: string
          readOnly: true
        trade_name:
          type: string
          readOnly: true
          example: NxTap
        address:
          $ref: '#/components/schemas/Address'
        created:
          type: string
          readOnly: true
          example: 2024-09-25T12:01:00.103Z
    InvalidRequestError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          example: invalid_request
        error_description:
          type: string
    Address:
      type: object
      required:
        - premise
        - thoroughfare
        - postal_code
      properties:
        premise:
          description: 'The house number, or premise number'
          type: string
          example: 58
        sub_premise:
          type: string
          description: The house number extension or premise number extension
          example: A
        building:
          type: string
          description: The building name
        postal_code:
          type: string
          description: The postal code
        thoroughfare:
          type: string
          description: 'The street name, or thoroughfare'
        locality:
          type: string
          example: Hoofddorp
          description: The city name or locality
        state:
          type: string
          example: Noord-Holland
          description: The state or province
        country:
          $ref: '#/components/schemas/Country'
    Country:
      type: string
      example: NL
      description: ISO 3166-1 alpha-2 country code
      enum:
        - AF
        - AX
        - AL
        - DZ
        - AS
        - AD
        - AO
        - AI
        - AQ
        - AG
        - AR
        - AM
        - AW
        - AU
        - AT
        - AZ
        - BS
        - BH
        - BD
        - BB
        - BY
        - BE
        - BZ
        - BJ
        - BM
        - BT
        - BO
        - BA
        - BW
        - BV
        - BR
        - IO
        - BN
        - BG
        - BF
        - BI
        - KH
        - CM
        - CA
        - CV
        - KY
        - CF
        - TD
        - CL
        - CN
        - CX
        - CC
        - CO
        - KM
        - CG
        - CD
        - CK
        - CR
        - CI
        - HR
        - CU
        - CY
        - CZ
        - DK
        - DJ
        - DM
        - DO
        - EC
        - EG
        - SV
        - GQ
        - ER
        - EE
        - ET
        - FK
        - FO
        - FJ
        - FI
        - FR
        - GF
        - PF
        - TF
        - GA
        - GM
        - GE
        - DE
        - GH
        - GI
        - GR
        - GL
        - GD
        - GP
        - GU
        - GT
        - GG
        - GN
        - GW
        - GY
        - HT
        - HM
        - VA
        - HN
        - HK
        - HU
        - IS
        - IN
        - ID
        - IR
        - IQ
        - IE
        - IM
        - IL
        - IT
        - JM
        - JP
        - JE
        - JO
        - KZ
        - KE
        - KI
        - KP
        - KR
        - KW
        - KG
        - LA
        - LV
        - LB
        - LS
        - LR
        - LY
        - LI
        - LT
        - LU
        - MO
        - MK
        - MG
        - MW
        - MY
        - MV
        - ML
        - MT
        - MH
        - MQ
        - MR
        - MU
        - YT
        - MX
        - FM
        - MD
        - MC
        - MN
        - MS
        - MA
        - MZ
        - MM
        - NA
        - NR
        - NP
        - NL
        - AN
        - NC
        - NZ
        - NI
        - NE
        - NG
        - NU
        - NF
        - MP
        - 'NO'
        - OM
        - PK
        - PW
        - PS
        - PA
        - PG
        - PY
        - PE
        - PH
        - PN
        - PL
        - PT
        - PR
        - QA
        - RE
        - RO
        - RU
        - RW
        - SH
        - KN
        - LC
        - PM
        - VC
        - WS
        - SM
        - ST
        - SA
        - SN
        - CS
        - SC
        - SL
        - SG
        - SK
        - SI
        - SB
        - SO
        - ZA
        - GS
        - ES
        - LK
        - SD
        - SR
        - SJ
        - SZ
        - SE
        - CH
        - SY
        - TW
        - TJ
        - TZ
        - TH
        - TL
        - TG
        - TK
        - TO
        - TT
        - TN
        - TR
        - TM
        - TC
        - TV
        - UG
        - UA
        - AE
        - GB
        - US
        - UM
        - UY
        - UZ
        - VU
        - VE
        - VN
        - VG
        - VI
        - WF
        - EH
        - YE
        - ZM
        - ZW
    Settlement:
      type: object
      required:
        - id
        - charges
        - charges_total
        - amount
        - payout
        - created
      properties:
        id:
          type: string
        currency:
          $ref: '#/components/schemas/Currency'
        charges:
          type: object
        charges_total:
          type: number
        amount:
          type: number
          example: 8230
          description: Amount of the payment in cents of the currency
        payout:
          type: object
          properties:
            payments:
              type: object
              properties:
                count:
                  type: number
                sum:
                  type: number
            refunds:
              type: object
              properties:
                count:
                  type: number
                sum:
                  type: number
        scheduled:
          type: string
          example: 2024-09-25T12:01:00.103Z
        created:
          type: string
          readOnly: true
          example: 2024-09-25T12:01:00.103Z
    Customer:
      type: object
      description: PSU customer type
      required:
        - id
        - created
      properties:
        id:
          type: string
          readOnly: true
        company:
          type: string
          description: Company name
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
        phone:
          type: string
          example: '318000201068'
        address:
          $ref: '#/components/schemas/Address'
        created:
          type: string
          readOnly: true
          example: 2024-09-25T12:01:00.103Z
    TerminalModel:
      type: string
      example: PAX_A35
      description: Terminal model ID
      enum:
        - PAX_A920
        - PAX_A920_PRO
        - PAX_A77
        - PAX_A35
        - PAX_IM30
    Terminal:
      type: object
      required:
        - id
        - model
        - serial
        - created
      properties:
        id:
          type: string
        name:
          type: string
          example: Client PAX A35
        model:
          $ref: '#/components/schemas/TerminalModel'
        serial:
          type: string
          example: 527291115
        profile:
          type: string
          description: Profile ID of the owner
        created:
          type: string
          readOnly: true
          example: 2024-09-25T12:01:00.103Z
    Onboarding:
      type: object
      required:
        - submitted
        - id
      properties:
        id:
          type: string
        type:
          type: string
          enum:
            - payments
            - monetary_account_person
            - monetary_account_company
        submitted:
          type: boolean
        data:
          type: object
          properties:
            company:
              type: object
              properties:
                legal_name:
                  type: string
                registration_number:
                  type: string
                registration_country:
                  $ref: '#/components/schemas/Country'
            methods:
              type: array
              items:
                $ref: '#/components/schemas/PaymentMethod'
            initial_values:
              type: object
              properties:
                company:
                  type: object
                  properties:
                    legal_name:
                      type: string
                    registration_number:
                      type: string
                    registration_country:
                      $ref: '#/components/schemas/Country'
                    registration_date: null
                    registration_address:
                      $ref: '#/components/schemas/Address'
                    type:
                      $ref: '#/components/schemas/CompanyType'
                    trade_names:
                      type: array
                      items:
                        type: string
                nature:
                  type: object
                  properties:
                    description: The description of the company
                    type: string
                  sector:
                    $ref: '#/components/schemas/CompanySector'
                  revenue:
                    type: number
                persons:
                  type: array
                  items:
                    type: object
                    properties:
                      uuid:
                        type: string
                        description: 'The UUID of the person, you are allowed to assign this value yourself'
                      company_id:
                        type: string
                        description: The UUID of the company in relation to the person
                      first_name:
                        type: string
                      middle_name:
                        type: string
                      last_name:
                        type: string
                      email:
                        type: string
                      phone:
                        type: string
                      address:
                        $ref: '#/components/schemas/Address'
                      date_of_birth:
                        type: string
                      ubo:
                        type: object
                        description: Supply this object if the person is an UBO
                        required:
                          - ownership
                          - control
                        properties:
                          ownership:
                            type: number
                            description: The percentage of economical ownership
                          control:
                            type: number
                            description: The percentage of factual control
                      director:
                        type: object
                        description: Supply this object if the person is a director
                        properties:
                          limited_authorised:
                            type: boolean
                companies:
                  type: object
                  properties:
                    uuid:
                      type: string
                      description: 'The UUID of the company, you are allowed to assign this value yourself'
                    company_id:
                      type: string
                      description: The UUID of the company in relation to the company
                    legal_name:
                      type: string
                    registration_number:
                      type: string
                    registration_country:
                      $ref: '#/components/schemas/Country'
                    registration_address:
                      $ref: '#/components/schemas/Address'
                    registration_date:
                      type: string
                    type:
                      $ref: '#/components/schemas/CompanyType'
                    trade_names:
                      type: array
                      items:
                        type: string
                    ubo:
                      type: object
                      description: Supply this object if the person is an UBO
                      required:
                        - ownership
                        - control
                      properties:
                        ownership:
                          type: number
                          description: The percentage of economical ownership
                        control:
                          type: number
                          description: The percentage of factual control
                    director:
                      type: object
                      description: Supply this object if the person is a director
                      properties:
                        limited_authorised:
                          type: boolean
          created:
            type: string
            readOnly: true
            example: 2024-09-25T12:01:00.103Z
    CompanyType:
      type: string
      description: The legal entity type
      enum:
        - sole_trader
        - nl_maatschap
        - nl_stichting
        - nl_vereniging
        - nl_cooperatie
        - nl_onderlinge_waarborgmaatschappij
        - nl_vennootschap_onder_firma
        - nl_commanditaire_vennootschap
        - nl_besloten_vennootschap
        - nl_naamloze_vennootschap
        - nl_kerkgenootschap
        - nl_vereniging_van_eigenaars
        - uk_private_unlimited
        - uk_private_limited
        - uk_public_limited
        - uk_limited_liability_partnership
        - uk_royal_charter
        - eu_public_limited_liability_company
        - eu_economic_interest_grouping
        - other
    CompanySector:
      type: string
      description: The sector of the company that the operate in
      enum:
        - accounting
        - culture
        - wholesale
        - business_services
        - social_businesses
        - training
        - healthcare
        - construction
        - it_hosting
        - legal_services
        - hotel_travel
        - marketing
        - news_media
        - real_estate
        - hospitality
        - retail
        - sports
        - logistics
        - utilities
        - events
        - financial_services
        - other
