openapi: 3.2.0
info:
  title: Billie Direct Front-end Order Creation API
  description: '# Introduction


    With PayAfterDelivery (PAD) / "Rechnungskauf" Billie offers a convenient, secure and simple way to allow your

    B2B-customers to pay on invoice.'
  termsOfService: https://www.billie.io/agb/
  license:
    name: © Billie GmbH, 2020
    url: https://www.billie.io/agb/
  version: v2025.11
  x-logo:
    url: data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPCEtLSBHZW5lcmF0b3I6IEFkb2JlIElsbHVzdHJhdG9yIDIyLjAuMSwgU1ZHIEV4cG9ydCBQbHVnLUluIC4gU1ZHIFZlcnNpb246IDYuMDAgQnVpbGQgMCkgIC0tPgo8c3ZnIHZlcnNpb249IjEuMSIgaWQ9IkViZW5lXzJfS29waWUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHg9IjBweCIKCSB5PSIwcHgiIHZpZXdCb3g9IjAgMCA0OC41IDY3LjYiIHN0eWxlPSJlbmFibGUtYmFja2dyb3VuZDpuZXcgMCAwIDQ4LjUgNjcuNjsiIHhtbDpzcGFjZT0icHJlc2VydmUiPgo8c3R5bGUgdHlwZT0idGV4dC9jc3MiPgoJLnN0MHtkaXNwbGF5Om5vbmU7ZmlsbDpub25lO3N0cm9rZTojMDAwMDAwO3N0cm9rZS13aWR0aDo3O3N0cm9rZS1taXRlcmxpbWl0OjEwO30KCS5zdDF7ZmlsbDojMUYyNTMwO30KCS5zdDJ7ZmlsbDpub25lO30KCS5zdDN7ZGlzcGxheTpub25lO2VuYWJsZS1iYWNrZ3JvdW5kOm5ldyAgICA7fQoJLnN0NHtmb250LWZhbWlseTonQXZlbmlyTmV4dC1EZW1pQm9sZCc7fQoJLnN0NXtmb250LXNpemU6My4wMzAzcHg7fQoJLnN0NntsZXR0ZXItc3BhY2luZzoyO30KPC9zdHlsZT4KPHBhdGggY2xhc3M9InN0MCIgZD0iTTkuOCw0Ni4xYy0wLjUsMCwyNS4xLTEyLjYsMjUuMS0zMi43YzAtNi45LTUuNi0xMi42LTEyLjYtMTIuNlM5LjcsNi41LDkuNywxMy40TDkuOCw0Ni4xaDE4LjUKCWM2LjksMCwxMi42LTUuNiwxMi42LTEyLjZTMzUuMiwyMSwyOC4yLDIxSDkuNyIvPgo8Zz4KCTxwYXRoIGNsYXNzPSJzdDEiIGQ9Ik0yOC4yLDQ3SDguOHYtMC44YzAtMC4xLDAtMC4yLDAtMC4zVjEzLjVDOC44LDYsMTQuOSwwLDIyLjMsMHMxMy41LDYsMTMuNSwxMy41YzAsMi44LTAuNSw1LjUtMS40LDguMgoJCWM0LjMsMi4yLDcuMyw2LjcsNy4zLDExLjlDNDEuNyw0MSwzNS42LDQ3LDI4LjIsNDd6IE0xMi45LDQ1LjJoMTUuM2M2LjQsMCwxMS43LTUuMywxMS43LTExLjdjMC00LjQtMi41LTguMy02LjEtMTAuMwoJCWMtMS44LDQuNC00LjgsOC43LTksMTIuOEMyMC40LDQwLjQsMTUuOCw0My41LDEyLjksNDUuMnogTTEwLjYsMjEuOXYyMi43YzEzLTcuNywxOC45LTE1LjYsMjEuNS0yMmMtMS4yLTAuNC0yLjUtMC43LTMuOS0wLjdIMTAuNgoJCXogTTEwLjYsMjAuMWgxNy42YzEuNiwwLDMuMSwwLjMsNC41LDAuOGMxLTIuOSwxLjMtNS41LDEuMy03LjRDMzQsNywyOC44LDEuOCwyMi4zLDEuOFMxMC42LDcsMTAuNiwxMy41VjIwLjF6Ii8+CjwvZz4KPHJlY3QgeD0iLTExLjEiIHk9Ii01OC43IiBjbGFzcz0ic3QyIiB3aWR0aD0iODUuNCIgaGVpZ2h0PSI0OS41Ii8+Cjx0ZXh0IHRyYW5zZm9ybT0ibWF0cml4KDEgMCAwIDEgLTEuMDQyNCA2Ny41NzcyKSIgY2xhc3M9InN0MyBzdDQgc3Q1IHN0NiI+QklMTElFPC90ZXh0Pgo8Zz4KCTxwYXRoIGNsYXNzPSJzdDEiIGQ9Ik0wLDU4LjFoMy43YzAuNCwwLDAuNywwLjEsMS4xLDAuMWMwLjQsMC4xLDAuNywwLjIsMC45LDAuNGMwLjMsMC4yLDAuNSwwLjQsMC43LDAuN2MwLjIsMC4zLDAuMywwLjcsMC4zLDEuMQoJCWMwLDAuNS0wLjIsMS0wLjUsMS4zYy0wLjMsMC40LTAuNywwLjYtMS4yLDAuOHYwYzAuNiwwLjEsMS4xLDAuMywxLjUsMC43QzYuOCw2My42LDcsNjQuMiw3LDY0LjhjMCwwLjUtMC4xLDEtMC4zLDEuMwoJCWMtMC4yLDAuNC0wLjUsMC42LTAuOCwwLjljLTAuMywwLjItMC43LDAuNC0xLjIsMC41Yy0wLjQsMC4xLTAuOSwwLjItMS4zLDAuMkgwQzAsNjcuNiwwLDU4LjEsMCw1OC4xeiBNMS43LDYyaDEuNQoJCWMwLjYsMCwxLTAuMSwxLjMtMC4zYzAuMy0wLjIsMC40LTAuNSwwLjQtMWMwLTAuNC0wLjItMC43LTAuNS0wLjljLTAuMy0wLjItMC44LTAuMy0xLjQtMC4zSDEuN0wxLjcsNjJMMS43LDYyeiBNMS43LDY2LjFoMS41CgkJYzAuMiwwLDAuNSwwLDAuNy0wLjFzMC41LTAuMSwwLjctMC4yYzAuMi0wLjEsMC40LTAuMywwLjUtMC40YzAuMS0wLjIsMC4yLTAuNCwwLjItMC44YzAtMC41LTAuMi0wLjktMC41LTEKCQljLTAuMy0wLjItMC45LTAuMy0xLjUtMC4zSDEuN1Y2Ni4xeiIvPgoJPHBhdGggY2xhc3M9InN0MSIgZD0iTTExLjEsNTguMWgxLjd2OS41aC0xLjdWNTguMXoiLz4KCTxwYXRoIGNsYXNzPSJzdDEiIGQ9Ik0xNy4zLDU4LjFoMS43djhoNHYxLjVoLTUuN1Y1OC4xeiIvPgoJPHBhdGggY2xhc3M9InN0MSIgZD0iTTI2LjUsNTguMWgxLjd2OGg0djEuNWgtNS43TDI2LjUsNTguMUwyNi41LDU4LjF6Ii8+Cgk8cGF0aCBjbGFzcz0ic3QxIiBkPSJNMzUuNyw1OC4xaDEuN3Y5LjVoLTEuN1Y1OC4xeiIvPgoJPHBhdGggY2xhc3M9InN0MSIgZD0iTTQxLjksNTguMWg2LjN2MS41aC00LjZWNjJINDh2MS40aC00LjNWNjZoNC44djEuNWgtNi41VjU4LjF6Ii8+CjwvZz4KPC9zdmc+Cg==
    href: '#'
servers:
- url: https://paella-sandbox.billie.io/api/v2
  description: Test Sandbox API
- url: https://paella.billie.io/api/v2
  description: Production API
tags:
- name: Front-end Order Creation
  description: '## To integrate the Billie checkout widget, the following steps are required:


    1.'
paths:
  /checkout-sessions:
    post:
      tags:
      - Front-end Order Creation
      summary: Checkout Session Create
      description: '**Purpose:**


        Creates a session ID that is used to initiate the widget for a dedicated checkout session with a customer.


        **Preconditions:**


        - n/a


        **Success:**


        - Response Code: HTTP 200

        - response body: `id` → session ID for the checkout session


        **Attention:**


        - The session has an expiry time of 48 hours.'
      operationId: create_checkout_session_v2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                merchant_customer_id:
                  $ref: '#/components/schemas/TinyText'
              type: object
      responses:
        '200':
          description: Checkout session created.
          content:
            application/json:
              schema:
                required:
                - id
                properties:
                  id:
                    $ref: '#/components/schemas/UUID'
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
      - oauth2: []
  /checkout-sessions/{sessionId}/authorization:
    get:
      tags:
      - Front-end Order Creation
      summary: Get Authorization
      description: Return last authorization for the given checkout session.
      operationId: get_checkout_session_authorization_v2
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
      responses:
        '200':
          description: Authorization
          content:
            application/json:
              schema:
                required:
                - state
                - decline_reason
                - amount
                - debtor
                properties:
                  state:
                    $ref: '#/components/schemas/OrderState'
                  decline_reason:
                    $ref: '#/components/schemas/OrderDeclineReason'
                  amount:
                    $ref: '#/components/schemas/AuthorizationAmount'
                  debtor:
                    description: Identified company
                    properties:
                      name:
                        type:
                        - string
                        - 'null'
                        example: Billie GmbH
                      company_address:
                        properties:
                          address_house_number:
                            type:
                            - string
                            - 'null'
                            example: '4'
                          address_street:
                            type:
                            - string
                            - 'null'
                            example: Charlottenstr.
                          address_postal_code:
                            type:
                            - string
                            - 'null'
                            maxLength: 5
                            example: '10969'
                          address_city:
                            type:
                            - string
                            - 'null'
                            example: Berlin
                          address_country:
                            type:
                            - string
                            - 'null'
                            maxLength: 2
                        type: object
                    type: object
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
  /checkout-sessions/{sessionId}/confirm:
    put:
      tags:
      - Front-end Order Creation
      summary: Checkout Session Confirm
      description: '**Purpose**


        Confirms the creation of an authorization where the buyer gave consent to the purchase and was accepted by Billie.


        **Preconditions:**


        - Session `id` of the Session Create Call

        - Request body created with the response values received in the widget.


        **Success**


        - Response Code: `HTTP 202`

        - response body: `state` -> `created`

        - response body: `uuid` -> ID of the created order


        **Attention**


        - The `duration` and the objects `delivery_address` and `amount` you can copy from the widget response to the new request object.

        - The `amount` must be the same as submitted via the widget.

        - The `debtor_company` object from the widget response needs to be rebuilt to an object hierarchy `debtor` with `company_address`'
      operationId: confirm_authorization_v2
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - amount
              - debtor
              properties:
                amount:
                  title: Amount
                  description: The amount object with split values for net, gross and tax
                  required:
                  - gross
                  - tax
                  properties:
                    gross:
                      description: Value greater than 0, with max. 2 decimals. It should equal to tax + net.
                      type: number
                      format: float
                      minimum: 0.01
                      example: 260.27
                    tax:
                      description: Value greater than or equal to 0, with max. 2 decimals.
                      type: number
                      format: float
                      minimum: 0
                      example: 60.15
                    net:
                      description: Value greater than or equal to 0, with max. 2 decimals.
                      type: number
                      format: float
                      minimum: 0
                      example: 200.12
                  type: object
                debtor:
                  description: Debtor company
                  required:
                  - name
                  - company_address
                  properties:
                    name:
                      type: string
                      maxLength: 255
                      example: Billie GmbH
                    company_address:
                      title: Address
                      required:
                      - street
                      - city
                      - postal_code
                      - country
                      properties:
                        street:
                          description: Street can be with house number together or provide house number in the dedicated field.
                          type: string
                          maxLength: 255
                          example: Charlottenstr. 4
                        house_number:
                          description: House number. Leave empty if it is provided as part of the street
                          type: string
                          maxLength: 255
                          example: '4'
                        city:
                          description: City, district, suburb, town, or village.
                          type: string
                          maxLength: 255
                          example: Berlin
                        postal_code:
                          description: ZIP or postal code.
                          type: string
                          maxLength: 5
                          pattern: ^[0-9]{5}$
                          example: '10969'
                        country:
                          title: Country Code
                          description: 'ISO 3166-1 alpha-2 country code (two letters: DE, AT, etc.). See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2'
                          type: string
                          maxLength: 2
                          minLength: 2
                          example: DE
                      type: object
                  type: object
                duration:
                  description: Order Duration
                  type: integer
                  example: '30'
                delivery_address:
                  title: Address
                  required:
                  - street
                  - city
                  - postal_code
                  - country
                  properties:
                    street:
                      description: Street can be with house number together or provide house number in the dedicated field.
                      type: string
                      maxLength: 255
                      example: Charlottenstr. 4
                    house_number:
                      description: House number. Leave empty if it is provided as part of the street
                      type: string
                      maxLength: 255
                      example: '4'
                    city:
                      description: City, district, suburb, town, or village.
                      type: string
                      maxLength: 255
                      example: Berlin
                    postal_code:
                      description: ZIP or postal code.
                      type: string
                      maxLength: 5
                      pattern: ^[0-9]{5}$
                      example: '10969'
                    country:
                      title: Country Code
                      description: 'ISO 3166-1 alpha-2 country code (two letters: DE, AT, etc.). See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2'
                      type: string
                      maxLength: 2
                      minLength: 2
                      example: DE
                  type: object
                external_code:
                  description: Order external code
                  type: string
                  maxLength: 255
                  example: DE123456-1
              type: object
      responses:
        '202':
          description: Order data successfully confirmed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
      - oauth2: []
  /hpp-checkout-sessions:
    post:
      tags:
      - Front-end Order Creation
      summary: Hpp Checkout Session Create
      description: '**Purpose**


        Creates a session ID and redirect URL that are used to initiate a Hosted Payment Page.


        **Preconditions:**


        - All the authorization related data is present.

        - Accept and decline URL are present to redirect the buyer from the hosted payment page after the authorization attempt.


        **Success**


        - Response Code: `HTTP 201`

        - Response body: `session_id` -> Session ID for the checkout session which will be used to get the authorization detail and also confirm the checkout session.

        - Response body: `hpp_url` -> URL to redirect or send to buyer to access the hosted payment page.

        - Response body: `expires_at` -> Expiration time of the checkout session.


        **Attention:**


        - The session has an expiry time of 48 hours.'
      operationId: create_hpp_checkout_session_v2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              discriminator:
                propertyName: channel
                mapping:
                  ecommerce: '#/components/schemas/HppCheckoutSessionECommerce'
                  telesales: '#/components/schemas/HppCheckoutSessionTelesales'
                  instore: '#/components/schemas/HppCheckoutSessionInstore'
              anyOf:
              - $ref: '#/components/schemas/HppCheckoutSessionECommerce'
              - $ref: '#/components/schemas/HppCheckoutSessionTelesales'
              - $ref: '#/components/schemas/HppCheckoutSessionInstore'
      responses:
        '201':
          description: HPP session created
          content:
            application/json:
              schema:
                required:
                - session_id
                - expires_at
                - hpp_url
                properties:
                  session_id:
                    $ref: '#/components/schemas/UUID'
                  expires_at:
                    description: Expires at datetime
                    type: string
                    format: Y-m-d\TH:i:sP
                  hpp_url:
                    description: Hosted payment page URL
                    type: string
                    example: https://hpp.billie.io/6b63fca4-6765-43f2-aee5-96ee9554befc
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
      - oauth2: []
components:
  schemas:
    HppCheckoutSessionTelesales:
      title: Hpp Checkout Session Create Request
      required:
      - channel
      - amount
      - duration
      - debtor_company
      - debtor_person
      - line_items
      properties:
        channel:
          type: string
          enum:
          - telesales
        amount:
          $ref: '#/components/schemas/AuthorizationAmount'
        comment:
          $ref: '#/components/schemas/TinyText'
        duration:
          $ref: '#/components/schemas/OrderDuration'
        order_id:
          $ref: '#/components/schemas/TinyText'
        delivery_address:
          $ref: '#/components/schemas/CreateOrderAddressRequest'
        billing_address:
          $ref: '#/components/schemas/CreateOrderAddressRequest'
        debtor_company:
          $ref: '#/components/schemas/LegacyCreateOrderDebtorCompanyRequest'
        debtor_person:
          title: Debtor Person
          description: Debtor Person desc
          required:
          - email
          properties:
            email:
              $ref: '#/components/schemas/AuthorizationStrictEmail'
            salutation:
              type: string
              maxLength: 1
              enum:
              - m
              - f
            first_name:
              type: string
              maxLength: 255
              example: James
            last_name:
              type: string
              maxLength: 255
              example: Smith
            phone_number:
              $ref: '#/components/schemas/AuthorizationPhoneNumber'
          type: object
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/CreateOrderLineItemRequest'
        merchant_urls:
          title: object <accept_url, decline_url>
          properties:
            accept_url:
              description: Merchant URL the buyer will be redirected to after the purchase was successfully authorized.
              type: string
              maximum: 255
              minimum: 1
              example: https://example.org/success/page
            decline_url:
              description: Merchant URL the buyer will be redirected to after the purchase was declined.
              type: string
              maximum: 255
              minimum: 1
              example: https://example.org/error/page
          type: object
      type: object
    OrderState:
      title: Order State
      type: string
      enum:
      - pre_waiting
      - authorized
      - waiting
      - created
      - declined
      - shipped
      - paid_out
      - late
      - complete
      - canceled
      example: created
    CreateOrderLineItemRequest:
      title: Order Line Item
      required:
      - external_id
      - title
      - quantity
      - amount
      properties:
        external_id:
          $ref: '#/components/schemas/TinyText'
        title:
          $ref: '#/components/schemas/TinyText'
        description:
          type: string
        quantity:
          type: number
          minimum: 1
        category:
          $ref: '#/components/schemas/TinyText'
        brand:
          $ref: '#/components/schemas/TinyText'
        gtin:
          $ref: '#/components/schemas/TinyText'
        mpn:
          $ref: '#/components/schemas/TinyText'
        product_url:
          $ref: '#/components/schemas/TinyText'
        image_url:
          $ref: '#/components/schemas/TinyText'
        type:
          $ref: '#/components/schemas/TinyText'
        quantity_unit:
          $ref: '#/components/schemas/TinyText'
        tax_rate:
          description: Tax rate of the order line. Non-negative value. The percentage value is represented with two implicit decimals and two i.e. 1900 = 19%
          type: number
          format: float
          minimum: 0
        total_discount_amount:
          description: Value greater than or equal to 0, with max. 2 decimals.
          type: number
          format: float
          minimum: 0
        unit_price:
          description: Value greater than or equal to 0, with max. 2 decimals.
          type: number
          format: float
          minimum: 0
        amount:
          $ref: '#/components/schemas/AmountDTO'
      type: object
    OrderDuration:
      title: Order Duration
      type: integer
      maximum: 120
      minimum: 1
      example: 30
    OrderInvoiceResponse:
      title: Order Entity
      properties:
        uuid:
          $ref: '#/components/schemas/UUID'
        invoice_number:
          type:
          - string
          - 'null'
        state:
          type:
          - string
          - 'null'
        payout_amount:
          type:
          - number
          - 'null'
          format: float
        amount:
          type: number
          format: float
        amount_net:
          type: number
          format: float
        amount_tax:
          type: number
          format: float
        outstanding_amount:
          type:
          - number
          - 'null'
          format: float
        pending_merchant_payment_amount:
          type:
          - number
          - 'null'
          format: float
        pending_cancellation_amount:
          type:
          - number
          - 'null'
          format: float
        fee_amount:
          type:
          - number
          - 'null'
          format: float
        fee_rate:
          type:
          - number
          - 'null'
          format: float
        due_date:
          type: string
          format: date
          example: '2019-03-20'
        created_at:
          type: string
          format: date
          example: '2019-03-20'
      type: object
    TaxedMoney:
      title: Amount with split values for net, gross and tax.
      required:
      - net
      - gross
      - tax
      properties:
        gross:
          description: Value greater than 0, with max. 2 decimals. It should equal to net + tax.
          type: number
          format: float
          minimum: 1
          example: 260.27
        net:
          description: Value greater than 0, with max. 2 decimals.
          type: number
          format: float
          minimum: 1
          example: 200.12
        tax:
          description: Value greater than or equal to 0, with max. 2 decimals.
          type: number
          format: float
          minimum: 0
          example: 60.15
      type: object
    PaymentMethodCollection:
      title: Eligible Payment Methods
      type: array
      items:
        $ref: '#/components/schemas/PaymentMethod'
    OrderDeclineReason:
      title: Order Decline Reason
      type: string
      enum:
      - risk_policy
      - risk_scoring_failed
      - debtor_not_identified
      - debtor_address
      - risk_scoring_failed
      - debtor_limit_exceeded
      example: debtor_not_identified
    Order:
      title: Order Entity
      properties:
        external_code:
          type:
          - string
          - 'null'
          example: C-10123456789-0001
        uuid:
          $ref: '#/components/schemas/UUID'
        state:
          $ref: '#/components/schemas/OrderStateV2'
        decline_reason:
          $ref: '#/components/schemas/OrderDeclineReason'
        amount:
          $ref: '#/components/schemas/TaxedMoney'
        unshipped_amount:
          $ref: '#/components/schemas/TaxedMoney'
        duration:
          $ref: '#/components/schemas/OrderDuration'
        created_at:
          $ref: '#/components/schemas/DateTime'
        delivery_address:
          $ref: '#/components/schemas/Address'
        debtor:
          $ref: '#/components/schemas/Debtor'
        invoices:
          type: array
          items:
            $ref: '#/components/schemas/OrderInvoiceResponse'
        selected_payment_method:
          type:
          - string
          - 'null'
          enum:
          - bank_transfer
          - direct_debit
          example: bank_transfer
        payment_methods:
          $ref: '#/components/schemas/PaymentMethodCollection'
      type: object
    HppCheckoutSessionECommerce:
      title: Hpp Checkout Session Create Request
      required:
      - channel
      - amount
      - duration
      - debtor_company
      - debtor_person
      - merchant_urls
      - line_items
      properties:
        channel:
          type: string
          enum:
          - ecommerce
        amount:
          $ref: '#/components/schemas/AuthorizationAmount'
        comment:
          $ref: '#/components/schemas/TinyText'
        duration:
          $ref: '#/components/schemas/OrderDuration'
        order_id:
          $ref: '#/components/schemas/TinyText'
        delivery_address:
          $ref: '#/components/schemas/CreateOrderAddressRequest'
        billing_address:
          $ref: '#/components/schemas/CreateOrderAddressRequest'
        debtor_company:
          $ref: '#/components/schemas/LegacyCreateOrderDebtorCompanyRequest'
        debtor_person:
          title: Debtor Person
          description: Debtor Person desc
          required:
          - email
          properties:
            email:
              $ref: '#/components/schemas/AuthorizationStrictEmail'
            salutation:
              type: string
              maxLength: 1
              enum:
              - m
              - f
            first_name:
              type: string
              maxLength: 255
              example: James
            last_name:
              type: string
              maxLength: 255
              example: Smith
            phone_number:
              $ref: '#/components/schemas/AuthorizationPhoneNumber'
          type: object
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/CreateOrderLineItemRequest'
        merchant_urls:
          title: object <accept_url, decline_url>
          required:
          - accept_url
          - decline_url
          properties:
            accept_url:
              description: Merchant URL the buyer will be redirected to after the purchase was successfully authorized.
              type: string
              maximum: 255
              minimum: 1
              example: https://example.org/success/page
            decline_url:
              description: Merchant URL the buyer will be redirected to after the purchase was declined.
              type: string
              maximum: 255
              minimum: 1
              example: https://example.org/error/page
          type: object
      type: object
    CreateOrderAddressRequest:
      title: Address
      required:
      - street
      - city
      - postal_code
      - country
      properties:
        addition:
          $ref: '#/components/schemas/TinyText'
        house_number:
          $ref: '#/components/schemas/TinyText'
        street:
          $ref: '#/components/schemas/TinyText'
        city:
          $ref: '#/components/schemas/TinyText'
        postal_code:
          $ref: '#/components/schemas/TinyText'
        country:
          $ref: '#/components/schemas/CountryCode'
        organization_name:
          $ref: '#/components/schemas/TinyText'
      type: object
    LegalForm:
      title: Legal Form
      description: One of the legal form codes available in the `GET /legal-forms` API endpoint.
      type: string
      example: '10001'
    AuthorizationStrictEmail:
      title: Email
      description: Email address with strict formatting rules
      type: string
      example: foo@example.org
    Address:
      title: Address data are all required except house number.
      required:
      - street
      - postal_code
      - city
      - country
      properties:
        house_number:
          $ref: '#/components/schemas/TinyText'
        street:
          $ref: '#/components/schemas/TinyText'
        postal_code:
          $ref: '#/components/schemas/TinyText'
        city:
          $ref: '#/components/schemas/TinyText'
        country:
          $ref: '#/components/schemas/CountryCode'
      type: object
    ErrorsObject:
      title: API Errors
      properties:
        errors:
          type: array
          items:
            required:
            - title
            - code
            properties:
              title:
                description: Error message
                type: string
              code:
                description: Error code
                type:
                - string
                - 'null'
              source:
                description: Property path where the error occurred, if applicable
                type:
                - string
                - 'null'
            type: object
      type: object
    DateTime:
      title: Date-Time
      type: string
      format: date-time
      example: '2019-01-20 14:00:00'
    AuthorizationPhoneNumber:
      title: PhoneNumber
      type: string
      maxLength: 21
      minLength: 5
      pattern: ^(\+|\d|\()[ \-\/0-9()]{5,20}$
      example: 030 31199251
    AuthorizationAmount:
      title: object <net, gross, tax>
      description: The amount object with split values for net, gross and tax
      required:
      - net
      - gross
      - tax
      properties:
        gross:
          description: Value greater than 0, with max. 2 decimals. It should equal to net + tax.
          type: number
          format: float
          minimum: 0.01
          example: 260.27
        net:
          description: Value greater than 0, with max. 2 decimals.
          type: number
          format: float
          minimum: 0.01
          example: 200.12
        tax:
          description: Value greater than or equal to 0, with max. 2 decimals.
          type: number
          format: float
          minimum: 0
          example: 60.15
      type: object
    DebtorExternalData:
      title: Debtor External Data
      properties:
        merchant_customer_id:
          $ref: '#/components/schemas/TinyText'
        name:
          $ref: '#/components/schemas/TinyText'
        industry_sector:
          type:
          - string
          - 'null'
        address:
          $ref: '#/components/schemas/Address'
      type: object
    Debtor:
      title: Order Debtor
      properties:
        name:
          type: string
          example: C-10123456789-0001
        company_address:
          $ref: '#/components/schemas/Address'
        billing_address:
          $ref: '#/components/schemas/Address'
        bank_account:
          $ref: '#/components/schemas/BankAccount'
        external_data:
          $ref: '#/components/schemas/DebtorExternalData'
      type: object
    TinyText:
      title: string
      type: string
      maxLength: 255
    BankAccount:
      title: Simple representation of a bank account
      properties:
        iban:
          $ref: '#/components/schemas/TinyText'
        bic:
          $ref: '#/components/schemas/TinyText'
      type: object
    HppCheckoutSessionInstore:
      title: Hpp Checkout Session Create Request
      required:
      - channel
      - amount
      - duration
      - debtor_company
      - debtor_person
      - line_items
      properties:
        channel:
          type: string
          enum:
          - instore
        amount:
          $ref: '#/components/schemas/AuthorizationAmount'
        comment:
          $ref: '#/components/schemas/TinyText'
        duration:
          $ref: '#/components/schemas/OrderDuration'
        order_id:
          $ref: '#/components/schemas/TinyText'
        delivery_address:
          $ref: '#/components/schemas/CreateOrderAddressRequest'
        billing_address:
          $ref: '#/components/schemas/CreateOrderAddressRequest'
        debtor_company:
          $ref: '#/components/schemas/LegacyCreateOrderDebtorCompanyRequest'
        debtor_person:
          title: Debtor Person
          description: Debtor Person desc
          required:
          - email
          properties:
            email:
              $ref: '#/components/schemas/AuthorizationStrictEmail'
            salutation:
              type: string
              maxLength: 1
              enum:
              - m
              - f
            first_name:
              type: string
              maxLength: 255
              example: James
            last_name:
              type: string
              maxLength: 255
              example: Smith
            phone_number:
              $ref: '#/components/schemas/AuthorizationPhoneNumber'
          type: object
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/CreateOrderLineItemRequest'
        merchant_urls:
          title: object <accept_url, decline_url>
          properties:
            accept_url:
              description: Merchant URL the buyer will be redirected to after the purchase was successfully authorized.
              type: string
              maximum: 255
              minimum: 1
              example: https://example.org/success/page
            decline_url:
              description: Merchant URL the buyer will be redirected to after the purchase was declined.
              type: string
              maximum: 255
              minimum: 1
              example: https://example.org/error/page
          type: object
      type: object
    PaymentMethodType:
      title: Payment Method Type
      type: string
      enum:
      - bank_transfer
      - direct_debit
      example: bank_transfer
    LegacyCreateOrderDebtorCompanyRequest:
      title: Debtor Company
      required:
      - merchant_customer_id
      - name
      - legal_form
      - address_street
      - address_city
      - address_postal_code
      - address_country
      properties:
        merchant_customer_id:
          $ref: '#/components/schemas/TinyText'
        name:
          $ref: '#/components/schemas/TinyText'
        tax_id:
          $ref: '#/components/schemas/TinyText'
        tax_number:
          $ref: '#/components/schemas/TinyText'
        registration_court:
          $ref: '#/components/schemas/TinyText'
        registration_number:
          $ref: '#/components/schemas/TinyText'
        industry_sector:
          $ref: '#/components/schemas/TinyText'
        subindustry_sector:
          $ref: '#/components/schemas/TinyText'
        employees_number:
          $ref: '#/components/schemas/TinyText'
        legal_form:
          $ref: '#/components/schemas/LegalForm'
        established_customer:
          type: boolean
        address_addition:
          $ref: '#/components/schemas/TinyText'
        address_house_number:
          $ref: '#/components/schemas/TinyText'
        address_street:
          $ref: '#/components/schemas/TinyText'
        address_city:
          $ref: '#/components/schemas/TinyText'
        address_postal_code:
          $ref: '#/components/schemas/PostalCode'
        address_country:
          $ref: '#/components/schemas/CountryCode'
        organisation_type:
          type: string
          example: other
      type: object
    CountryCode:
      title: Country Code
      description: 'ISO 3166-1 alpha-2 country code (two letters: DE, AT, etc.). See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2'
      type: string
      maxLength: 2
      minLength: 2
      example: DE
    PaymentMethod:
      title: Payment Method
      properties:
        type:
          $ref: '#/components/schemas/PaymentMethodType'
        data:
          description: Payment method details
          properties:
            iban:
              $ref: '#/components/schemas/TinyText'
            bic:
              $ref: '#/components/schemas/TinyText'
            bank_name:
              description: Name of the Bank entity
              type:
              - string
              - 'null'
            bank_giro:
              description: Bank giro number (Sweden only)
              type:
              - string
              - 'null'
            sort_code:
              description: Bank sort code (GB only)
              type:
              - string
              - 'null'
            account_number:
              description: Bank account number (GB, NL and NO)
              type:
              - string
              - 'null'
            bank_account_owner:
              description: Bank account owner entity
              type: string
            mandate_reference:
              description: Direct Debit SEPA Mandate Reference (for Direct Debit only)
              type:
              - string
              - 'null'
            mandate_execution_date:
              $ref: '#/components/schemas/DateTime'
            creditor_identification:
              description: Creditor Identification Code (for Direct Debit only)
              type:
              - string
              - 'null'
          type: object
      type: object
    PostalCode:
      title: Postal Code
      type: string
      maxLength: 5
      minLength: 5
      pattern: ^[0-9]{5}$
      example: '10969'
    OrderStateV2:
      title: Order State
      type: string
      enum:
      - pre_waiting
      - authorized
      - waiting
      - created
      - declined
      - shipped
      - partially_shipped
      - complete
      - canceled
      example: created
    UUID:
      type: string
      format: uuid
      maxLength: 36
      minLength: 36
      example: 12345667-890a-bcde-f123-34567890abcd
    AmountDTO:
      title: object <net, gross, tax>
      description: The amount object with split values for net, gross and tax
      required:
      - net
      - gross
      - tax
      properties:
        gross:
          description: Value greater than 0, with max. 2 decimals. It should equal to net + tax.
          type: number
          format: float
          minimum: 0.01
          example: 260.27
        net:
          description: Value greater than 0, with max. 2 decimals.
          type: number
          format: float
          minimum: 0.01
          example: 200.12
        tax:
          description: Value greater than or equal to 0, with max. 2 decimals.
          type: number
          format: float
          minimum: 0
          example: 60.15
      type: object
  responses:
    ServerError:
      description: Unexpected Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorsObject'
    Unauthorized:
      description: Unauthorized request or invalid credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorsObject'
    BadRequest:
      description: Invalid Request Data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorsObject'
    NotFound:
      description: Resource Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorsObject'
  securitySchemes:
    oauth2:
      type: oauth2
      description: 'This authentication mechanism is based on the OAuth 2.0 prototocol and requires a Client ID, a Client Secret Key and

        in some cases also a user and password.


        With these credentials, the client should request a token using the `POST /api/v1/oauth/token` endpoint,

        which should be used in the `Authorization` header together with the `Bearer` challenge to authenticate all the requests.


        > Example: `Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c`.'
      flows:
        password:
          tokenUrl: /oauth/token
          scopes:
            default: default
x-provenance:
  method: searched
  source: https://docs.billie.io/reference
  harvested: '2026-10-14'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.billie.io/reference/confirm_authorization_v2.md
  - https://docs.billie.io/reference/create_checkout_session_v2.md
  - https://docs.billie.io/reference/create_credit_note.md
  - https://docs.billie.io/reference/create_hpp_checkout_session_v2.md
  - https://docs.billie.io/reference/get_checkout_session_authorization_v2.md
  - https://docs.billie.io/reference/get_invoice.md
  - https://docs.billie.io/reference/get_legal_forms.md
  - https://docs.billie.io/reference/invoice_cancel_v2.md
  - https://docs.billie.io/reference/invoice_create.md
  - https://docs.billie.io/reference/invoice_payment_confirm.md
  - https://docs.billie.io/reference/invoice_update.md
  - https://docs.billie.io/reference/oauth_token_create.md
  - https://docs.billie.io/reference/oauth_token_revoke.md
  - https://docs.billie.io/reference/oauth_token_validate.md
  - https://docs.billie.io/reference/order_cancel_v2.md
  - https://docs.billie.io/reference/order_create_v2.md
  - https://docs.billie.io/reference/order_get_details_v2.md
  - https://docs.billie.io/reference/order_update_v2.md
  merge:
    pages: 18
    deduped: 152
    conflicts_kept_first: 0