openapi: 3.0.1
info:
  title: PastPay API
  description: >
    This page describes the API for Péntech's BNPL solution, PastPay.


    Concepts:
      - **Store**: The API key user, webshop that uses PastPay. Can be a marketplace where multiple creditors sell to debtors or a single-creditor shop.
      - **Pricing**: When a creditor is created, a pricing is assigned manually. The pricing details are coming from the contract between PastPay and the shop.
  contact:
    email: support@pastpay.com
  version: 1.9.0
servers:
  - url: https://api.demo.pastpay.com
    description: Test environment
  - url: https://api.pastpay.com
    description: Production environment
tags:
  - name: creditors
    description: Supplier / Vendor actions
  - name: debtors
    description: Buyer actions
  - name: orders
    description: Buyer actions
  - name: stores
    description: Store actions
  - name: utils
    description: Technical utilities
paths:
  /healthcheck:
    get:
      summary: Utility endpoint to check if the API is available.
      tags:
        - utils
      responses:
        200:
          description: API is available. **HTTP codes other than 200 should be considered unavailable.**
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum: ['ok']
                    description: Textual description of the API status.
                  # TODO
                  # apiVersion:
                  #   type: string
                  #   example: '1.2.3'
                  #   description: Version of the deployed API description (this document)
                  # appVersion:
                  #   type: string
                  #   example: '1.2.3'
                  #   description: Version of the deployed application
                  # deployedAt:
                  #   type: string
                  #   example: '2022-11-10T12:00:11Z'
                  #   description: Time of the latest deployment in ISO datetime format.

  /debtors:
    post:
      summary: Connect a new debtor to the store
      tags:
        - debtors
      security:
        - api_key: []
      requestBody:
        $ref: '#/components/requestBodies/createDebtor'
      responses:
        '201':
          $ref: '#/components/responses/201Debtor'
        '401':
          $ref: '#/components/responses/401'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ValidationError'
                  - $ref: '#/components/schemas/AutoKoError'
                  - $ref: '#/components/schemas/InvalidApiKeyError'
                  - $ref: '#/components/schemas/CompanyNotFoundError'
                  - $ref: '#/components/schemas/StoreDoesNotExistError'
                  - $ref: '#/components/schemas/DebtorAlreadyExistsError'

    get:
      summary: List all debtors connected to the store
      tags:
        - debtors
      security:
        - api_key: []
      responses:
        '200':
          description: Request successfully processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    maxItems: 1000
                    items:
                      allOf:
                        - $ref: '#/components/schemas/DebtorResource'

  /debtors/{debtorTaxNumber}/limit:
    get:
      deprecated: true
      summary: DEPRECATED, use `/store/order` instead - Request eligibility and buying limit for a company by tax number
      tags:
        - debtors
      security:
        - api_key: []
      parameters:
        - $ref: '#/components/parameters/debtorTaxNumber'
        - in: query
          name: countryCode
          required: true
          schema:
            $ref: '#/components/schemas/CountryCode'
          description: Country of origin of the Debtor company. (ISO 3166-1 alpha-2)
        # TODO: not implemented yet
        # - in: query
        #   name: currency
        #   required: false
        #   schema:
        #     $ref: '#/components/schemas/Currency'
        #   description: >
        #     Currency in you want to display the limit's value.
        #     We give and store limits in the company's official currency,
        #     but with this parameter it is possible to display in any other supported currency.
      responses:
        '200':
          description: Request successfully processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LimitSuccess'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/LimitError'
                  - $ref: '#/components/schemas/ValidationError'
        '401':
          $ref: '#/components/schemas/InvalidApiKeyError'

  /debtors/{debtorTaxNumber}/order:
    post:
      deprecated: true
      summary: DEPRECATED, use `/store/order` instead - Creates a pending limit reservation for a webshop order
      description: DEPRECATED, use `/store/order` instead - This request priors and required by the `finalization` one. It will create a pending limit reservation for each creditors, what can be turned into final BNPL factorings one-by-one.
      tags:
        - debtors
      security:
        - api_key: []
      parameters:
        - $ref: '#/components/parameters/debtorTaxNumber'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - creditors
              properties:
                creditors:
                  type: array
                  minItems: 1
                  items:
                    description: Sub-orders shall be grouped by creditor.
                    type: object
                    required:
                      - orderId
                      - creditorsTaxNumber
                      - totalPrice
                    properties:
                      orderId:
                        type: string
                        description: Unique identifier of the order in the webshop
                      creditorTaxNumber:
                        $ref: '#/components/schemas/CreditorTaxNumber'
                      totalPrice:
                        allOf:
                          - $ref: '#/components/schemas/Money'
                          - description: Final amount of the order payable to creditor
                debtorUserData:
                  allOf:
                    - description: Debtor user data must be provided once for the first order
                    - $ref: '#/components/schemas/DebtorUserData'
      responses:
        '201':
          $ref: '#/components/responses/201CreateOrder'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/OrderError'
                  - $ref: '#/components/schemas/ValidationError'
                  - $ref: '#/components/schemas/CreditorCurrencyNotSupportedError'
                  - $ref: '#/components/schemas/NoMatchingPricingFoundError'
                  - $ref: '#/components/schemas/OutstandingFundingsError'
                  - $ref: '#/components/schemas/VerificationError'
        '401':
          $ref: '#/components/schemas/InvalidApiKeyError'

  /debtors/{debtorTaxNumber}:
    get:
      summary: Get a single debtor by tax number
      tags:
        - debtors
      security:
        - api_key: []
      parameters:
        - $ref: '#/components/parameters/debtorTaxNumber'
      responses:
        '200':
          description: Successful request
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/DebtorResource'

  /debtors/{debtorTaxNumber}/user/status:
    parameters:
      - $ref: '#/components/parameters/debtorTaxNumber'
    get:
      summary: Get debtor user registration and verification status
      description: >
        Returns whether the debtor (identified by tax number) has a registered user account in PastPay
        and whether the debtor has been verified, along with the debtor's company URN.
      tags:
        - debtors
      security:
        - api_key: []
      responses:
        '200':
          description: Request successfully processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    required:
                      - companyUrn
                      - isRegistered
                      - isVerified
                    properties:
                      companyUrn:
                        type: string
                        description: Company URN of the debtor
                        example: '123456789'
                      isRegistered:
                        type: boolean
                        description: >
                          `true` if a user account is linked to the debtor's organisation in PastPay,
                          `false` otherwise.
                        example: true
                      isVerified:
                        type: boolean
                        description: >
                          `true` if the debtor's verification status is `verified`, `false` otherwise
                          (e.g. `pending` or `rejected`).
                        example: true
              examples:
                registered_and_verified:
                  summary: Debtor has a registered user and is verified
                  value:
                    data:
                      companyUrn: '123456789'
                      isRegistered: true
                      isVerified: true
                registered_not_verified:
                  summary: Debtor has a registered user but is not yet verified
                  value:
                    data:
                      companyUrn: '123456789'
                      isRegistered: true
                      isVerified: false
                not_registered:
                  summary: Debtor exists but no user account is linked
                  value:
                    data:
                      companyUrn: '123456789'
                      isRegistered: false
                      isVerified: false
        '401':
          $ref: '#/components/responses/401'
        '404':
          description: BNPL Debtor not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - 'debtor_not_found'
                  message:
                    type: string
                    example: 'BNPL Debtor not found'
                  context:
                    type: string
                    nullable: true

  /store/order:
    post:
      summary: Initiates BNPL flow through PastPay
      description: This API endpoint facilitates the storage of customer orders in PastPay's system by receiving order details and returning a redirect URL. The webshop is expected to redirect the buyer to this URL where PastPay will perform its checks and request additional details before determining whether to authorize the request. Upon successful verification, the buyer will be redirected to the paymentRedirectUrl.success URL, while any issues with the factoring process will result in redirection to paymentRedirectUrl.failure URL. If the process is interrupted, for example, if the buyer prematurely closes their browser, none of the URLs will be immediately called. PastPay will initiate contact with the buyer to continue the process. However, if the buyer does not complete the process within a specified timeout period, PastPay will automatically invoke the failure URL.
      tags:
        - stores
      security:
        - api_key: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - debtorTaxNumber
                - orderId
                - totalPrice
                - paymentRedirectUrl
                - language
              properties:
                debtorTaxNumber:
                  type: string
                  description: The tax number of the buyer
                  example: 'PL12345678901'
                orderId:
                  type: string
                  description: Unique identifier of the order in the webshop
                  example: '123'
                totalPrice:
                  allOf:
                    - $ref: '#/components/schemas/Money'
                    - description: Final gross amount of the order payable to creditor (inc. all additional fees)
                paymentRedirectUrl:
                  type: object
                  required:
                    - success
                    - failure
                  properties:
                    success:
                      type: string
                      example: 'https://shop.example.com/order/123/success'
                    failure:
                      type: string
                      example: 'https://shop.example.com/order/123/failure'
                language:
                  type: string
                  enum:
                    - hu
                    - en
                    - de
                    - it
                  description: Language of the PastPay app where the link redirects to.
                  example: 'en'
                termDays:
                  type: integer
                  example: 30
                  enum:
                    - 15
                    - 30
                    - 45
                    - 60
                    - 90
                  description: The term of the order in days.
      responses:
        '201':
          $ref: '#/components/responses/201RedirectUrl'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/OrderError'
                  - $ref: '#/components/schemas/ValidationError'
                  - $ref: '#/components/schemas/CreditorCurrencyNotSupportedError'
                  - $ref: '#/components/schemas/NoMatchingPricingFoundError'
                  - $ref: '#/components/schemas/OutstandingFundingsError'
                  - $ref: '#/components/schemas/AutoKoError'
                  - $ref: '#/components/schemas/VerificationError'
        '401':
          $ref: '#/components/schemas/InvalidApiKeyError'

  /debtors/{debtorTaxNumber}/order/{orderId}:
    delete:
      summary: 'Storno (cancel) an order. Frees up the limit reservation without actual factoring.'
      description: 'Works when the limit is reserved but the order is **not** finalized yet.'
      tags:
        - debtors
      security:
        - api_key: []
      parameters:
        - $ref: '#/components/parameters/debtorTaxNumber'
        - $ref: '#/components/parameters/orderId'
      responses:
        '200':
          $ref: '#/components/responses/OrderSuccess'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ValidationError'
        '401':
          $ref: '#/components/schemas/InvalidApiKeyError'

  /debtors/{debtorTaxNumber}/order/{orderId}/finalize:
    post:
      summary: Converts a pending limit reservation into a BNPL factoring request.
      description: This request must be called after the limit reservation call. It will remove the pending limit reservation for the creditor and creates a final BNPL factoring request. It's invalid to call this endpoint without prior limit reservation for this specific orderId (a.k.a. `/order` call).
      tags:
        - debtors
      security:
        - api_key: []
      parameters:
        - $ref: '#/components/parameters/debtorTaxNumber'
        - $ref: '#/components/parameters/orderId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - invoiceNo
                - invoicePdf
                - totalPrice
                - currency
                - issueDate
                - dueDate
              properties:
                creditorTaxNumber:
                  $ref: '#/components/schemas/CreditorTaxNumber'
                invoiceNo:
                  type: string
                  description: Full and trimmed, official identifier of the issued invoice.
                invoicePdf:
                  type: string
                  description: Base64 encoded pdf version of the invoice
                  example: 'data:application/pdf;base64,JVBERi0xLg10cmFpbGVyPDwvUm9vdDw8L1BhZ2VzPDwvS2lkc1s8PC9NZWRpYUJveFswIDAgMyAzXT4+XT4+Pj4+Pg=='
                totalPrice:
                  allOf:
                    - $ref: '#/components/schemas/Money'
                    - description: Final amount of the invoice payable to creditor (with VAT)
                issueDate:
                  $ref: '#/components/schemas/Date'
                dueDate:
                  $ref: '#/components/schemas/Date'
      responses:
        '201':
          $ref: '#/components/responses/OrderSuccess'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/FinalizationError'
                  - $ref: '#/components/schemas/ValidationError'
                  - $ref: '#/components/schemas/VerificationError'
        '401':
          $ref: '#/components/schemas/InvalidApiKeyError'

  /debtors/{debtorTaxNumber}/orders/{orderId}/cancel:
    post:
      summary: 'Cancel an order before a credit limit reservation occurs.'
      description: 'Enables creditors to cancel an order if there was an error in the order details.'
      tags:
        - debtors
      security:
        - api_key: []
      parameters:
        - $ref: '#/components/parameters/debtorTaxNumber'
        - $ref: '#/components/parameters/orderId'
      responses:
        '200':
          $ref: '#/components/responses/OrderSuccess'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ValidationError'
        '401':
          $ref: '#/components/schemas/InvalidApiKeyError'
        '404':
          $ref: '#/components/schemas/NotFoundError'
        '409':
          $ref: '#/components/schemas/OrderStatusConflictError'

  /creditors/{creditorTaxNumber}:
    parameters:
      - $ref: '#/components/parameters/creditorTaxNumber'
    get:
      summary: Get details (status) of a creditors contract
      # description: TODO
      tags:
        - creditors
      security:
        - api_key: []
      responses:
        '200':
          description: Request successfully processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - 'pending'
                      - 'contracted'
                      - 'cancelled'
                      - 'rejected'
        '401':
          $ref: '#/components/responses/401'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/InvalidApiKeyError'
        '404':
          $ref: '#/components/responses/404'

  /orders:
    get:
      summary: List all orders
      tags:
        - 'orders'
      security:
        - api_key: []
      responses:
        '200':
          description: Request successfully processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    maxItems: 1000
                    items:
                      type: object
                      properties:
                        orderId:
                          type: string
                        creditorTaxNumber:
                          $ref: '#/components/parameters/creditorTaxNumber'
                        debtorTaxNumber:
                          $ref: '#/components/parameters/debtorTaxNumber'
                        totalPrice:
                          $ref: '#/components/schemas/Money'
                        createdAt:
                          type: string
                        issueDate:
                          type: string
                        dueDate:
                          type: string
                        invoiceNo:
                          type: string
                        status:
                          $ref: '#/components/schemas/OrderStatus'
        '401':
          $ref: '#/components/responses/401'

  /orders/{orderId}:
    parameters:
      - $ref: '#/components/parameters/orderId'
    get:
      summary: Get one order by ID
      description: >
        Retrieves a single order by its orderId. The orderId is the unqiue identifier for the order.
        Returns order details including status, amount, and invoice information (if available).

        For reserved orders or orders with submitted invoices, additional fields like issueDate, dueDate, and invoiceNo will be returned.
      tags:
        - 'orders'
      security:
        - api_key: []
      responses:
        '200':
          description: Request successfully processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    nullable: true
                    required:
                      - orderId
                      - creditorTaxNumber
                      - debtorTaxNumber
                      - totalPrice
                      - createdAt
                      - status
                    properties:
                      orderId:
                        type: string
                        description: Unique identifier of the order in the webshop
                        example: '123'
                      creditorTaxNumber:
                        type: string
                        description: Tax number of the creditor/merchant
                        example: 'DE123456789'
                      debtorTaxNumber:
                        type: string
                        description: Tax number of the debtor/buyer
                        example: '10307078'
                      totalPrice:
                        $ref: '#/components/schemas/Money'
                      createdAt:
                        type: string
                        format: date-time
                        description: ISO 8601 timestamp when the order was created
                        example: '2023-01-12T18:25:51.441743+00:00'
                      issueDate:
                        type: string
                        format: date
                        nullable: true
                        description: Invoice issue date in YYYY-MM-DD format
                        example: '2022-02-03'
                      dueDate:
                        type: string
                        format: date
                        nullable: true
                        description: Invoice due date in YYYY-MM-DD format
                        example: '2022-03-05'
                      invoiceNo:
                        type: string
                        nullable: true
                        description: Invoice number (only for submitted invoices)
                        example: 'INV-2023-001'
                      status:
                        $ref: '#/components/schemas/OrderStatus'
              examples:
                invoice_submitted:
                  summary: Invoice submitted and is being processed by PastPay
                  value:
                    data:
                      orderId: 'ORD-2025-001'
                      creditorTaxNumber: 'DE123456789'
                      debtorTaxNumber: '10307078'
                      totalPrice:
                        amount: 150000
                        currency: 'HUF'
                      createdAt: '2023-01-12T18:25:51.441743+00:00'
                      issueDate: '2023-01-15'
                      dueDate: '2023-02-14'
                      invoiceNo: 'INV-2023-001'
                      status: 'invoice_submitted'
        '401':
          $ref: '#/components/responses/401'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - 'order_not_found'
                  message:
                    type: string
                    example: 'Order not found'
                  context:
                    type: string
                    nullable: true

components:
  parameters:
    debtorTaxNumber:
      name: debtorTaxNumber
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/DebtorTaxNumber'
    creditorTaxNumber:
      name: creditorTaxNumber
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/TaxNumber'
    orderId:
      name: orderId
      in: path
      required: true
      description: Unique identifier of the order in the webshop
      schema:
        type: string

  schemas:
    TaxNumber:
      type: string
      nullable: false
      example: '28357322'
      pattern: '^(?:\d{8}|\d{10})$'
      description: >
        We accept the following formats:
          - HU: tax number base
            - Format: The [EU VAT number](https://en.wikipedia.org/wiki/VAT_identification_number) with optional check digits
            - Regex: `^(\d{8}(?:-\d-\d\d)?|\d{11})$`
            - Check number validated: yes
          - PL: 
            - Format: The [EU VAT number](https://en.wikipedia.org/wiki/VAT_identification_number) without the country code prefix
            - Regex: `^\d{10}$`
            - Check number validated: no
          - SK: 
            - Format: The [EU VAT number](https://en.wikipedia.org/wiki/VAT_identification_number) with the country code prefix
            - Regex: `^SK\d{10}$`
            - Check number validated: no
          - CZ: 
            - Format: The [EU VAT number](https://en.wikipedia.org/wiki/VAT_identification_number) with the country code prefix
            - Regex: `^CZ\d{8,10}$`
            - Check number validated: no
          - DE: 
            - Format: The [EU VAT number](https://en.wikipedia.org/wiki/VAT_identification_number) with the country code prefix
            - Regex: `^DE\w{9,12}$`
            - Check number validated: no
          - RO: 
            - Format: The [EU VAT number](https://en.wikipedia.org/wiki/VAT_identification_number) with the country code prefix
            - Regex: `^RO\d{2,10}$`
            - Check number validated: no
          - IT: 
            - Format: The [EU VAT number](https://en.wikipedia.org/wiki/VAT_identification_number) with the country code prefix
            - Regex: `^IT\d{11}$`
            - Check number validated: no
          - AT:
            - Format: The [EU VAT number](https://en.wikipedia.org/wiki/VAT_identification_number) with ATU prefix
            - Regex: `^ATU\d{8}$`
            - Check number validated: no
          - FR:
            - Format: FR + two letters/digits + 9 digits
            - Regex: `^FR([a-zA-Z]|\d){2}\d{9}$`
            - Check number validated: no
          - NL:
            - Format: NL + BTW-id (9 digits + B + two digits/O2) OR KVK number (8 digits)
            - Regex: `^NL(\d{9}B(\d{2}|O2)|\d{8})$`
            - Check number validated: no
          - BE:
            - Format: BE + 10 digits
            - Regex: `^BE\d{10}$`
            - Check number validated: no
          - ES:
            - Format: ES + char/digit + 7 digits + char/digit
            - Regex: `^ES([a-z]|\d)\d{7}([a-z]|\d)$`
            - Check number validated: no
          - DK:
            - Format: DK + 8 digits
            - Regex: `^DK\d{8}$`
            - Check number validated: no
          - SE:
            - Format: SE + 12 digits
            - Regex: `^SE\d{12}$`
            - Check number validated: no
          - PT:
            - Format: PT + 9 digits
            - Regex: `^PT\d{9}$`
            - Check number validated: no
          - LT:
            - Format: LT + 9 or 12 digits
            - Regex: `^LT(\d{9}|\d{12})$`
            - Check number validated: no
          - EE:
            - Format: EE + 9 digits
            - Regex: `^EE\d{9}$`
            - Check number validated: no
          - LV:
            - Format: LV + 11 digits
            - Regex: `^LV\d{11}$`
            - Check number validated: no
          - BG:
            - Format: BG + 9-10 digits
            - Regex: `^BG\d{9,10}$`
            - Check number validated: no
          - SI:
            - Format: SI + 8 digits
            - Regex: `^SI\d{8}$`
            - Check number validated: no
          - CH:
            - Format: CHE + 3 digits + . + 3 digits + . + 3 digits + optional MWST/TVA/IVA suffix
            - Regex: `^CHE\d{3}.\d{3}.\d{3}(?:MWST|TVA|IVA)?$`
            - Check number validated: no
          - GB:
            - Format: GB + 2 letters/digits + 6 digits
            - Regex: `^GB(\d{2}|[a-z]{2})\d{6}$`
            - Check number validated: no
          - IE:
            - Format: IE + digit + letter/digit + 4-5 digits + letter/digit + letter
            - Regex: `^IE\d{1}([a-z]|\d)\d{4,5}([a-z]|\d){1}[a-z]{1}$`
            - Check number validated: no
          - FI:
            - Format: FI + 8 digits
            - Regex: `^FI\d{8}$`
            - Check number validated: no
          - GR:
            - Format: EL + 9 digits
            - Regex: `^EL\d{9}$`
            - Check number validated: no
          - HR:
            - Format: HR + 11 digits
            - Regex: `^HR\d{11}$`
            - Check number validated: no
          - LU:
            - Format: LU + 8 digits
            - Regex: `^LU\d{8}$`
            - Check number validated: no
          - MT:
            - Format: MT + 8 digits
            - Regex: `^MT\d{8}$`
            - Check number validated: no
          - CY:
            - Format: CY + 8 digits + letter
            - Regex: `^CY\d{8}[a-z]{1}$`
            - Check number validated: no

        We validate the check number for the following countries:
          - [Hungary](https://ceginformaciosszolgalat.kormany.hu/download/4/27/02000/adoszam_adoazonosito_ellenorzes_2018.pdf).
    DebtorTaxNumber:
      type: string
      nullable: false
      example: '10307078'
      pattern: '^(?:\d{8}|\d{10})$'
      description: >
        We accept the following formats:
          - HU: tax number base
            - Format: The [EU VAT number](https://en.wikipedia.org/wiki/VAT_identification_number) with optional check digits
            - Regex: `^(\d{8}(?:-\d-\d\d)?|\d{11})$`
            - Check number validated: yes
          - PL: 
            - Format: The [EU VAT number](https://en.wikipedia.org/wiki/VAT_identification_number) without the country code prefix
            - Regex: `^\d{10}$`
            - Check number validated: no
          - SK: 
            - Format: The [EU VAT number](https://en.wikipedia.org/wiki/VAT_identification_number) with the country code prefix
            - Regex: `^SK\d{10}$`
            - Check number validated: no
          - CZ: 
            - Format: The [EU VAT number](https://en.wikipedia.org/wiki/VAT_identification_number) with the country code prefix
            - Regex: `^CZ\d{8,10}$`
            - Check number validated: no
          - DE: 
            - Format: The [EU VAT number](https://en.wikipedia.org/wiki/VAT_identification_number) with the country code prefix
            - Regex: `^DE\w{9,12}$`
            - Check number validated: no
          - RO: 
            - Format: The [EU VAT number](https://en.wikipedia.org/wiki/VAT_identification_number) with the country code prefix
            - Regex: `^RO\d{2,10}$`
            - Check number validated: no
          - IT: 
            - Format: The [EU VAT number](https://en.wikipedia.org/wiki/VAT_identification_number) with the country code prefix
            - Regex: `^IT\d{11}$`
            - Check number validated: no
          - AT:
            - Format: The [EU VAT number](https://en.wikipedia.org/wiki/VAT_identification_number) with ATU prefix
            - Regex: `^ATU\d{8}$`
            - Check number validated: no
          - FR:
            - Format: FR + two letters/digits + 9 digits
            - Regex: `^FR([a-zA-Z]|\d){2}\d{9}$`
            - Check number validated: no
          - NL:
            - Format: NL + BTW-id (9 digits + B + two digits/O2) OR KVK number (8 digits)
            - Regex: `^NL(\d{9}B(\d{2}|O2)|\d{8})$`
            - Check number validated: no
          - BE:
            - Format: BE + 10 digits
            - Regex: `^BE\d{10}$`
            - Check number validated: no
          - ES:
            - Format: ES + char/digit + 7 digits + char/digit
            - Regex: `^ES([a-z]|\d)\d{7}([a-z]|\d)$`
            - Check number validated: no
          - DK:
            - Format: DK + 8 digits
            - Regex: `^DK\d{8}$`
            - Check number validated: no
          - SE:
            - Format: SE + 12 digits
            - Regex: `^SE\d{12}$`
            - Check number validated: no
          - PT:
            - Format: PT + 9 digits
            - Regex: `^PT\d{9}$`
            - Check number validated: no
          - LT:
            - Format: LT + 9 or 12 digits
            - Regex: `^LT(\d{9}|\d{12})$`
            - Check number validated: no
          - EE:
            - Format: EE + 9 digits
            - Regex: `^EE\d{9}$`
            - Check number validated: no
          - LV:
            - Format: LV + 11 digits
            - Regex: `^LV\d{11}$`
            - Check number validated: no
          - BG:
            - Format: BG + 9-10 digits
            - Regex: `^BG\d{9,10}$`
            - Check number validated: no
          - SI:
            - Format: SI + 8 digits
            - Regex: `^SI\d{8}$`
            - Check number validated: no
          - CH:
            - Format: CHE + 3 digits + . + 3 digits + . + 3 digits + optional MWST/TVA/IVA suffix
            - Regex: `^CHE\d{3}.\d{3}.\d{3}(?:MWST|TVA|IVA)?$`
            - Check number validated: no
          - GB:
            - Format: GB + 2 letters/digits + 6 digits
            - Regex: `^GB(\d{2}|[a-z]{2})\d{6}$`
            - Check number validated: no
          - IE:
            - Format: IE + digit + letter/digit + 4-5 digits + letter/digit + letter
            - Regex: `^IE\d{1}([a-z]|\d)\d{4,5}([a-z]|\d){1}[a-z]{1}$`
            - Check number validated: no
          - FI:
            - Format: FI + 8 digits
            - Regex: `^FI\d{8}$`
            - Check number validated: no
          - GR:
            - Format: EL + 9 digits
            - Regex: `^EL\d{9}$`
            - Check number validated: no
          - HR:
            - Format: HR + 11 digits
            - Regex: `^HR\d{11}$`
            - Check number validated: no
          - LU:
            - Format: LU + 8 digits
            - Regex: `^LU\d{8}$`
            - Check number validated: no
          - MT:
            - Format: MT + 8 digits
            - Regex: `^MT\d{8}$`
            - Check number validated: no
          - CY:
            - Format: CY + 8 digits + letter
            - Regex: `^CY\d{8}[a-z]{1}$`
            - Check number validated: no

        We validate the check number for the following countries:
          - [Hungary](https://ceginformaciosszolgalat.kormany.hu/download/4/27/02000/adoszam_adoazonosito_ellenorzes_2018.pdf).
    OrderStatus:
      type: string
      nullable: true
      description: |
        Current status of the order. Possible values:

        - `unprocessed`: Order has been created and waiting for action by the debtor, so it can be reserved
        - `error`: Order processing encountered an error
        - `reserved`: Credit limit has been reserved for this order, awaiting invoice submission
        - `invoice_submitted`: Invoice has been submitted and is being processed by PastPay
        - `paid_out`: Payment has been completed to the Creditor (Merchant)
        - `cancelled`: Order was cancelled by the creditor or debtor, this can be done before the invoice is submitted
        - `rejected`: Order was rejected due to risk assessment or eligibility issues
        - `timeout`: Order processing timed out (Debtor didn't complete the process)
        - `paid_back`: Debtor has paid back the amount to PastPay
        - `rectification_requested`: Order requires data correction
      example: 'reserved'
      enum:
        - 'unprocessed'
        - 'reserved'
        - 'invoice_submitted'
        - 'paid_out'
        - 'paid_back'
        - 'rectification_requested'
        - 'cancelled'
        - 'rejected'
        - 'timeout'
        - 'error'
    CreditorTaxNumber:
      allOf:
        - $ref: '#/components/schemas/TaxNumber'
        - description: Regular (1 vendor) webshops can omit this property, as their taxNumber is fixed to the API key. Marketplaces must specify this property.
      description: >
        We accept the following formats:
          - HU: tax number base
            - Format: The [EU VAT number](https://en.wikipedia.org/wiki/VAT_identification_number) with optional check digits
            - Regex: `^(\d{8}(?:-\d-\d\d)?|\d{11})$`
            - Check number validated: yes
          - PL: 
            - Format: The [EU VAT number](https://en.wikipedia.org/wiki/VAT_identification_number) without the country code prefix
            - Regex: `^\d{10}$`
            - Check number validated: no
          - SK: 
            - Format: The [EU VAT number](https://en.wikipedia.org/wiki/VAT_identification_number) with the country code prefix
            - Regex: `^SK\d{10}$`
            - Check number validated: no
          - CZ: 
            - Format: The [EU VAT number](https://en.wikipedia.org/wiki/VAT_identification_number) with the country code prefix
            - Regex: `^CZ\d{8,10}$`
            - Check number validated: no
          - DE: 
            - Format: The [EU VAT number](https://en.wikipedia.org/wiki/VAT_identification_number) with the country code prefix
            - Regex: `^DE\w{9,12}$`
            - Check number validated: no
          - RO: 
            - Format: The [EU VAT number](https://en.wikipedia.org/wiki/VAT_identification_number) with the country code prefix
            - Regex: `^RO\d{2,10}$`
            - Check number validated: no
          - IT: 
            - Format: The [EU VAT number](https://en.wikipedia.org/wiki/VAT_identification_number) with the country code prefix
            - Regex: `^IT\d{11}$`
            - Check number validated: no
          - AT:
            - Format: The [EU VAT number](https://en.wikipedia.org/wiki/VAT_identification_number) with ATU prefix
            - Regex: `^ATU\d{8}$`
            - Check number validated: no
          - FR:
            - Format: FR + two letters/digits + 9 digits
            - Regex: `^FR([a-zA-Z]|\d){2}\d{9}$`
            - Check number validated: no
          - NL:
            - Format: NL + BTW-id (9 digits + B + two digits/O2) OR KVK number (8 digits)
            - Regex: `^NL(\d{9}B(\d{2}|O2)|\d{8})$`
            - Check number validated: no
          - BE:
            - Format: BE + 10 digits
            - Regex: `^BE\d{10}$`
            - Check number validated: no
          - ES:
            - Format: ES + char/digit + 7 digits + char/digit
            - Regex: `^ES([a-z]|\d)\d{7}([a-z]|\d)$`
            - Check number validated: no
          - DK:
            - Format: DK + 8 digits
            - Regex: `^DK\d{8}$`
            - Check number validated: no
          - SE:
            - Format: SE + 12 digits
            - Regex: `^SE\d{12}$`
            - Check number validated: no
          - PT:
            - Format: PT + 9 digits
            - Regex: `^PT\d{9}$`
            - Check number validated: no
          - LT:
            - Format: LT + 9 or 12 digits
            - Regex: `^LT(\d{9}|\d{12})$`
            - Check number validated: no
          - EE:
            - Format: EE + 9 digits
            - Regex: `^EE\d{9}$`
            - Check number validated: no
          - LV:
            - Format: LV + 11 digits
            - Regex: `^LV\d{11}$`
            - Check number validated: no
          - BG:
            - Format: BG + 9-10 digits
            - Regex: `^BG\d{9,10}$`
            - Check number validated: no
          - SI:
            - Format: SI + 8 digits
            - Regex: `^SI\d{8}$`
            - Check number validated: no
          - CH:
            - Format: CHE + 3 digits + . + 3 digits + . + 3 digits + optional MWST/TVA/IVA suffix
            - Regex: `^CHE\d{3}.\d{3}.\d{3}(?:MWST|TVA|IVA)?$`
            - Check number validated: no
          - GB:
            - Format: GB + 2 letters/digits + 6 digits
            - Regex: `^GB(\d{2}|[a-z]{2})\d{6}$`
            - Check number validated: no
          - IE:
            - Format: IE + digit + letter/digit + 4-5 digits + letter/digit + letter
            - Regex: `^IE\d{1}([a-z]|\d)\d{4,5}([a-z]|\d){1}[a-z]{1}$`
            - Check number validated: no
          - FI:
            - Format: FI + 8 digits
            - Regex: `^FI\d{8}$`
            - Check number validated: no
          - GR:
            - Format: EL + 9 digits
            - Regex: `^EL\d{9}$`
            - Check number validated: no
          - HR:
            - Format: HR + 11 digits
            - Regex: `^HR\d{11}$`
            - Check number validated: no
          - LU:
            - Format: LU + 8 digits
            - Regex: `^LU\d{8}$`
            - Check number validated: no
          - MT:
            - Format: MT + 8 digits
            - Regex: `^MT\d{8}$`
            - Check number validated: no
          - CY:
            - Format: CY + 8 digits + letter
            - Regex: `^CY\d{8}[a-z]{1}$`
            - Check number validated: no
    Date:
      description: Short ISO date (YYYY-MM-DD)
      type: string
      nullable: false
      pattern: '^(\d{4})-(\d{2})-(\d{2})$'
      example: '2022-02-03'
    Currency:
      description: >
        An [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code.


        If a currency conversion has occurred, the conversion rate at the date of the request has been used.
      type: string
      nullable: false
      enum: ['CHF', 'CZK', 'EUR', 'GBP', 'HUF', 'PLN', 'RON', 'USD']
      example: HUF
    CountryCode:
      description: 'An [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code of any supported country'
      type: string
      nullable: false
      example: HU
      enum:
        - HU
        - PL
        - SK
        - CZ
        - DE
        - RO
        - IT
    Money:
      type: object
      nullable: false
      required:
        - amount
        - currency
      properties:
        amount:
          type: number
          example: 10000
        currency:
          $ref: '#/components/schemas/Currency'
    DebtorUserData:
      type: object
      nullable: false
      required:
        - firstName
        - lastName
        - phoneNumber
        - email
      properties:
        firstName:
          type: string
          example: 'John'
        lastName:
          type: string
          example: 'Smith'
        phoneNumber:
          type: string
          example: '+36207897897'
        email:
          type: string
          example: 'testuser@example.com'
    DebtorResource:
      type: object
      properties:
        id:
          type: string
          example: '4e5fd503-543c-4ddc-97cd-e8669277c6d7'
        createdAt:
          type: string
          example: '2023-01-12T18:25:51.441743+00:00'
        taxNumber:
          $ref: '#/components/schemas/DebtorTaxNumber'
        shortName:
          type: string
          example: 'X Kft.'
        countryCode:
          $ref: '#/components/schemas/CountryCode'
        totalLimit:
          $ref: '#/components/schemas/Money'
        availableLimit:
          $ref: '#/components/schemas/Money'
        creditorTaxNumber:
          $ref: '#/components/schemas/TaxNumber'
        isEligible:
          type: boolean
          example: true
        verificationStatus:
          $ref: '#/components/schemas/VerificationStatus'
        status:
          type: string
          description: Debtor status, can be created or registered if the buyer was added successfully and their rating is positive. The buyer can also be rejected by PastPay, or suspended due to overdue debt with PastPay.
          example: 'created'
          enum:
            - 'created'
            - 'registered'
            - 'rejected'
            - 'suspended'
    VerificationStatus:
      type: string
      description: Debtor verification status, unverified debtors cannot create order (reserve limit)
      example: 'pending'
      enum:
        - verified
        - pending
        - rejected
    CompanyAddresses:
      type: array
      nullable: false
      example: ['1234 Budapest, Teszt street 1. B.']
    LimitSuccess:
      type: object
      properties:
        data:
          properties:
            availableLimit:
              allOf:
                - $ref: '#/components/schemas/Money'
                - description: Limit values are always rounded up to next round value, therefor there is no cent handling regarding the limit values.
            totalLimit:
              allOf:
                - $ref: '#/components/schemas/Money'
                - description: Maximum total amount in which the debtor can use factoring at the same time
            isEligible:
              type: boolean
            companyAddresses:
              $ref: '#/components/schemas/CompanyAddresses'
            verificationStatus:
              $ref: '#/components/schemas/VerificationStatus'

    # errors
    LimitError:
      type: object
      properties:
        status:
          type: string
          enum:
            - error
        code:
          type: string
          enum:
            - 'auto_ko'
            - 'can_not_set_limit'
        message:
          type: string
          description: Optionally we may send more human readable description of the error.
    OrderError:
      type: object
      properties:
        status:
          type: string
          enum:
            - error
        code:
          type: string
          enum:
            - 'debtor_not_found'
            - 'missing_debtor_user_data'
            - 'invalid_creditor'
            - 'unregistered_creditor'
            - 'duplicate_order'
            - 'debtor_limit_reached'
            - 'creditor_limit_reached'
            - 'debtor_contact_not_found'
            - 'bnpl/order_timeout'
            - 'bnpl/order_already_processed'
            - 'dnb/company_not_found'
            - 'debtor_not_eligible'
            - 'store_does_not_exist'
            - 'rejected_debtor'
            - 'auth/bnpl/invalid_token'
            - 'order_not_found'
        message:
          type: string
          description: Optionally we may send more human readable description of the error.
    FinalizationError:
      type: object
      properties:
        status:
          type: string
          enum:
            - error
        code:
          type: string
          enum:
            - 'order_not_found'
            - 'invalid_order_status'
            - 'currency_mismatch'
            - 'limit_reached'
        message:
          type: string
          description: Optionally we may send more human readable description of the error.
    CreditorAlreadyRegistered:
      type: string
    AutoKoError:
      type: object
      properties:
        code:
          type: string
          nullable: false
          enum:
            - 'auto_ko'
    VerificationError:
      description: 'We could not verify identity of debtor'
      type: object
      properties:
        status:
          type: string
          enum:
            - error
        code:
          type: string
          enum:
            - 'unverified_buyer'
            - 'rejected_buyer'
        message:
          type: string
          default: 'Validation error!'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationErrorObj'
        data:
          type: string
          description: Detailed human readable report of the occured validation error.
    ValidationError:
      description: 'We could not validate the request body'
      type: object
      properties:
        status:
          type: string
          enum:
            - error
        code:
          type: string
          enum:
            - validation_error
        message:
          type: string
          default: 'Validation error!'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationErrorObj'
        data:
          type: string
          description: Detailed human readable report of the occured validation error.
    StoreDoesNotExistError:
      description: 'Your store is not registered in PastPay yet. This is a manual step between the webshop and PastPay which results in an API key sent out.'
      type: object
      properties:
        status:
          type: string
          enum:
            - error
        code:
          type: string
          enum:
            - store_does_not_exist
        message:
          type: string
    MissingTokenError:
      description: 'You have to provide the API key as an X-Api-Key header.'
      type: object
      properties:
        code:
          type: string
          enum:
            - missing_token
        message:
          type: string
    DebtorAlreadyExistsError:
      description: 'The debtor is already connected to the store.'
      type: object
      properties:
        code:
          type: string
          enum:
            - debtor_already_exists
        message:
          type: string
    CreditorCurrencyNotSupportedError:
      description: "No pricing found that matches all of the orders' currencies"
      type: object
      properties:
        code:
          type: string
          enum:
            - creditor_currency_not_supported
        message:
          type: string
        context:
          type: object
          properties:
            missingCurrencies:
              description: 'Context about orders where the pricing could not be matched'
              type: array
              items:
                type: object
    NoMatchingPricingFoundError:
      description: 'The store does not have pricing in some currencies of the reservation'
      type: object
      properties:
        code:
          type: string
          enum:
            - no_matching_pricing_found
        message:
          type: string
    OutstandingFundingsError:
      description: 'Debtor has unpaid overdue, finalized orders towards PastPay'
      type: object
      properties:
        code:
          type: string
          enum:
            - debtor_has_outstanding_fundings
        message:
          type: string
    InvalidApiKeyError:
      description: 'The API key in the X-Api-Key header is invalid.'
      type: object
      properties:
        status:
          type: string
          enum:
            - error
        code:
          type: string
          enum:
            - invalid_api_key
        message:
          type: string
    DuplicateOrderError:
      description: 'Order with the given orderId was previously submitted'
      type: object
      properties:
        message:
          type: string
        code:
          type: string
          enum:
            - duplicate_order
        context:
          type: object
          properties:
            orderId:
              type: string
            creditorTaxNumber:
              $ref: '#/components/schemas/TaxNumber'
    CompanyNotFoundError:
      description: 'Company with the given tax number cannot be found in the registry.'
      type: object
      properties:
        status:
          type: string
          enum:
            - error
        code:
          type: string
          enum:
            - company_not_found
    ValidationErrorObj:
      type: object
      properties:
        fields:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ValidationErrorObjField'
    ValidationErrorObjField:
      type: object
      properties:
        message:
          type: string
          example: 'Malformatted tax number: 2835'
        validator:
          type: string
          example: 'TaxNumberBaseHu'
        got:
          type: string
          example: '2835'
    NotFoundError:
      description: No record found with the parameter(s) supplied
      type: object
      properties:
        code:
          type: string
          nullable: false
          enum:
            - 'creditor_not_found'
            - 'debtor_not_found'
            - 'order_not_found'
        message:
          type: string
        context:
          type: string
    OrderStatusConflictError:
      description: 'The order is in a state that does not allow the operation.'
      type: object
      properties:
        code:
          type: string
          enum:
            - 'order_conflict'
        message:
          type: string
    ResponseMessage:
      type: object
      properties:
        message:
          type: string
          description: Textual description of the successful operation.
        data:
          type: object
    DebtorResponse:
      type: object
      properties:
        message:
          type: string
          description: Textual description of the successful operation.
        data:
          $ref: '#/components/schemas/DebtorResource'
    ResponseCreateOrder:
      type: object
      properties:
        message:
          type: string
          description: Textual description of the successful operation.
        verificationStatus:
          $ref: '#/components/schemas/VerificationStatus'
    ResponseOrderSuccess:
      type: object
      properties:
        data:
          type: object
          properties:
            orderId:
              type: string
    ResponseRedirectUrl:
      type: object
      properties:
        data:
          type: object
          properties:
            redirectUrl:
              type: string
              example: 'https://app.pastpay.com/buy/817fac60-1da9-47aa-bdff-dff7d4839819'

  securitySchemes:
    api_key:
      type: apiKey
      name: X-Api-Key
      in: header

  responses:
    '200':
      description: Request successfully processed.
    'OrderSuccess':
      description: Request successfully processed.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/ResponseMessage'
              - $ref: '#/components/schemas/ResponseOrderSuccess'
    '201':
      description: Record successfully created.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseMessage'
    '201Debtor':
      description: Record successfully created.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DebtorResponse'
    '201CreateOrder':
      description: Record successfully created.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseCreateOrder'
    '201RedirectUrl':
      description: Order saved.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseRedirectUrl'
    '400':
      description: This legal entity is refused to be served due to failing risk assessment.
    '401':
      description: Missing API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MissingTokenError'
    '404':
      description: No record found with the parameter supplied.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFoundError'

  requestBodies:
    creditorRegistration:
      required: true
      content:
        application/json:
          schema:
            required:
              - taxNumber
              - countryCode
              - email
              - phone
              - firstName
              - lastName
            properties:
              taxNumber:
                $ref: '#/components/schemas/TaxNumber'
              countryCode:
                $ref: '#/components/schemas/CountryCode'
              email:
                type: string
                example: 'testuser@example.com'
              phoneNumber:
                type: string
                example: '+36207897897'
                description: Phone number, ideally starting with the [country calling code](https://en.wikipedia.org/wiki/List_of_country_calling_codes).
              firstName:
                type: string
                example: 'John'
              lastName:
                type: string
                example: 'Smith'
              kycVideo:
                type: string
                example: 'https://optional.video.url'
                format: uri
                description: Download link of the KYC video recording. This is optional.
    createDebtor:
      required: true
      content:
        application/json:
          schema:
            required:
              - taxNumber
              - countryCode
              - email
              - phone
              - firstName
              - lastName
            properties:
              taxNumber:
                $ref: '#/components/schemas/DebtorTaxNumber'
              countryCode:
                $ref: '#/components/schemas/CountryCode'
              email:
                type: string
                example: 'testdebtor@example.com'
              phoneNumber:
                type: string
                example: '+36201111111'
                description: Phone number, ideally starting with the [country calling code](https://en.wikipedia.org/wiki/List_of_country_calling_codes).
              firstName:
                type: string
                example: 'John'
              lastName:
                type: string
                example: 'Debtor'
