Two Settlement report API

openapi: 3.2.0
info:
  title: Two Order Settlement report API
  version: '1.0'
  description: 'This API is for creating orders connected to an online purchase through your solution.

    The API also functions as a central building block when using other Two APIs, e.g. Marketplace API, and Trade Account Onboarding API.


    Specifically, the API enables you to:


    - Check whether a buyer is accepted for credit before placing the order (Order intent)

    - Create orders

    - Fulfil orders (Send invoice from Two)

    - Edit orders

    - Cancel orders

    - Refund orders (Send credit note)

    - Download invoice


    Below you will find a description of a typical flow of how the different endpoints are called. However, you might want to deviate from this order depending on your setup.


    ### Step 0: Use the Two Company Search API to find the company

    By using the Two Company Search API, you ensure that the user places an order on behalf of the correct organization. It enables an improved user experience and lowers the friction.


    **Using Canonical IDs (Recommended):** The Company Search API returns a `canonical_id` for each company. You can use this canonical_id when creating orders and order intents instead of providing full company details. This ensures data accuracy and simplifies integration.


    Example:

    ```json

    {

    "buyer": {

    "company": {

    "company_canonical_id": "abc123def456"

    },

    "representative": { ... }

    }

    }

    ```


    ### Step 1: Check whether a buyer will be accepted for credit during checkout (Order intent)

    Use `POST /v1/order_intent` to credit check your buyers during the checkout. Only enable Two as the payment option if the credit check is approved.

    Collect the `tracking_id` from the response of the order intent in order to connect the order_intent with the actual order being placed by the buyer.


    ### Step 2: Create order

    Create an order by building a request body containing all required elements and call the `POST /v1/order` endpoint.

    1. Read the state and status of the order response.

    2. Check if the status is `APPROVED`.

    3. Check if the state is `UNVERIFIED`, and redirect the user to the `payment_url`.


    After completing the verfication, the user is redirected back to your order confirmation page.


    ### Step 3: Confirm order

    On the order confirmation page use the `POST /v1/order//confirm` endpoint to confirm that the user has arrived at the order confirmation page.


    ### Step 4: Handling orders


    #### Cancel order

    Use `POST /v1/order//cancel` to cancel a specific order.


    #### Edit order

    Use `PUT /v1/order/` with a specified request body to edit an order.


    #### Fulfil order

    Use `POST /v1/order//fulfilled` with a specified request body to fulfil all line items of an order.


    Note: Include a request body in order to do a partial fulfillment.


    #### Refund order

    Use `POST /v1/order//refund` to refund a specific order.


    Note: Include a request body in order to do a partial refund.


    ## Environments


    ### Testing


    https://api.sandbox.two.inc


    Note: Read about our sandbox environment specific behaviour.


    ### Production


    https://api.two.inc'
servers:
- url: https://api.sandbox.two.inc
  description: Testing
- url: https://api.two.inc
  description: Production
security: []
tags:
- name: Settlement report
paths:
  /v2/merchant/settlement:
    get:
      summary: Get settlements
      operationId: get_merchant_settlements_v2_handler.get
      description: Endpoint to retrieve a cursor-paginated list of settlements for the authenticated merchant. Each settlement contains payout details including the settlement date, recipient account information, payout amount and currency, and payment reference. Use the `page_cursor` from the response metadata to paginate through results.
      tags:
      - Settlement report
      parameters: []
      responses:
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '200':
          description: Cursor-paginated list of settlements
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedSettlementListCursorSchema'
        '400':
          description: Bad request
      security:
      - X-Api-Key: []
  /v2/merchant/settlement/{settlement_id}/statement:
    get:
      summary: Get settlement statement
      operationId: get_merchant_settlement_statement_handler.get
      description: 'Endpoint to download a settlement statement file for a specific settlement. The response is a binary file (`.xlsx` or `.csv`) containing the detailed breakdown of orders, refunds, and fees included in the settlement. The `Settlement Type` column shows how a line was settled: `GROSS_PAID` (paid out at the gross settlement amount), `NET_PAID` (paid out at the net settlement amount), `PAID` (paid out), `UNPAID` or `PENDING` (not paid out yet), or `IGNORE` (Two has decided not to pay this settlement out). Treat any value you do not recognise as not paid out, because new values can be added. The `Order Type` column shows who initiated the order: `BUYER_INITIATED` (the buyer started it at checkout, which is the default for orders created through the API) or `MERCHANT_INITIATED` (the merchant started it, as every order created in the Two merchant portal is). It is blank on lines that are not tied to an order, such as repayment-plan lines.'
      tags:
      - Settlement report
      parameters:
      - name: settlement_id
        in: path
        required: true
        schema:
          type: string
        description: The ID of the settlement to download the statement for
      responses:
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '200':
          description: Settlement statement file (.xlsx or .csv)
        '400':
          description: Bad request or unsupported file type
      security:
      - X-Api-Key: []
  /v2/merchant/statement:
    get:
      summary: Get settlement report
      operationId: get_merchant_statement_handler.get
      description: 'Endpoint to download a settlement report for a specified date range as `.xlsx` or `.csv`. The report contains all settlements within the given period, broken down by order with details including fees, net amounts, and payment references. The `Settlement Type` column shows how a line was settled: `GROSS_PAID` (paid out at the gross settlement amount), `NET_PAID` (paid out at the net settlement amount), `PAID` (paid out), `UNPAID` or `PENDING` (not paid out yet), or `IGNORE` (Two has decided not to pay this settlement out). Treat any value you do not recognise as not paid out, because new values can be added. The `Order Type` column shows who initiated the order: `BUYER_INITIATED` (the buyer started it at checkout, which is the default for orders created through the API) or `MERCHANT_INITIATED` (the merchant started it, as every order created in the Two merchant portal is). It is blank on lines that are not tied to an order, such as repayment-plan lines.'
      tags:
      - Settlement report
      parameters:
      - name: start_date
        in: query
        schema:
          description: The first date that should be included in the statement.
          examples:
          - '2023-01-01'
          title: Start Date
          type: string
        required: true
        description: The first date that should be included in the statement.
      - name: end_date
        in: query
        schema:
          description: The last date that should be included in the statement.
          examples:
          - '2023-01-31'
          title: End Date
          type: string
        required: true
        description: The last date that should be included in the statement.
      - name: filetype
        in: query
        schema:
          anyOf:
          - type: string
          - type: 'null'
          default: xlsx
          description: The filetype of the statement file. Two currently supports csv and xlsx as value for the filetype parameter. Default is xlsx.
          title: Filetype
        required: false
        description: The filetype of the statement file. Two currently supports csv and xlsx as value for the filetype parameter. Default is xlsx.
      - name: country_code
        in: query
        schema:
          default: 'NO'
          description: The country code of the payout account you want to extract a settlement file for. Country code in ISO 3166 alpha-2 format
          examples:
          - GB
          title: Country Code
          type: string
        required: false
        description: The country code of the payout account you want to extract a settlement file for. Country code in ISO 3166 alpha-2 format
      responses:
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '200':
          description: Settlement report file (.xlsx or .csv)
        '400':
          description: Bad request, invalid dates, or unsupported file type/country code
      security:
      - X-Api-Key: []
components:
  schemas:
    CurrencyEnum:
      enum:
      - CHF
      - CZK
      - DKK
      - EUR
      - GBP
      - INR
      - MXN
      - NOK
      - PLN
      - RON
      - SEK
      - USD
      title: CurrencyEnum
      type: string
    CursorPageMetadata:
      properties:
        previous_page_cursor:
          anyOf:
          - minLength: 1
            type: string
          - type: 'null'
          default: cursor to the previous page
          title: Previous Page Cursor
        next_page_cursor:
          anyOf:
          - minLength: 1
            type: string
          - type: 'null'
          default: cursor to the next page
          title: Next Page Cursor
        limit:
          description: The maximum number of items on a single page, ie the page size.
          minimum: 0
          title: Limit
          type: integer
      required:
      - limit
      title: CursorPageMetadata
      type: object
    ErrorResponse:
      properties:
        error_code:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: An error code related to the error.
          title: Error Code
        error_details:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: A detailed description of the error when available.
          title: Error Details
        error_message:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: A short description of the error.
          title: Error Message
        error_json:
          anyOf:
          - items:
              $ref: '#/components/schemas/ErrorJSON'
            type: array
          - type: 'null'
          default: null
          description: A list of errors when available.
          title: Error Json
        error_trace_id:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: A unique trace ID for the request that generated the error. Please quote this trace ID in any support requests.
          title: Error Trace Id
      title: ErrorResponse
      type: object
    PaginatedSettlementListCursorSchema:
      properties:
        items:
          items:
            $ref: '#/components/schemas/Settlement'
          title: Items
          type: array
        cursor_page_metadata:
          $ref: '#/components/schemas/CursorPageMetadata'
      required:
      - items
      - cursor_page_metadata
      title: PaginatedSettlementListCursorSchema
      type: object
    Settlement:
      properties:
        settlement_id:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: The global settlement ID.
          title: Settlement Id
        settlement_date:
          anyOf:
          - format: date
            type: string
          - type: 'null'
          default: null
          description: Date of the settlement payout
          title: Settlement Date
        recipient_account_number:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: Recipient account number.
          title: Recipient Account Number
        recipient_account_name:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: Recipient account name.
          title: Recipient Account Name
        recipient_iban:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: Recipient account IBAN.
          title: Recipient Iban
        recipient_bban:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: Recipient account BBAN.
          title: Recipient Bban
        funding_provider:
          description: Funding provider
          title: Funding Provider
          type: string
        funding_provider_account_holder_name:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: Funding provider account name.
          title: Funding Provider Account Holder Name
        funding_provider_account_number:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: Funding provider account number.
          title: Funding Provider Account Number
        payout_currency:
          $ref: '#/components/schemas/CurrencyEnum'
          description: Payout currency.
          examples:
          - GBP
        payout_amount:
          anyOf:
          - format: decimal
            pattern: ^-?[0-9]+(\.[0-9]{0,2})?
            type: string
          - type: 'null'
          default: null
          description: Payout amount.
          examples:
          - '10000.00'
          title: Payout Amount
        payment_reference:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: Payment reference.
          title: Payment Reference
      required:
      - funding_provider
      - payout_currency
      title: Settlement
      type: object
    ErrorJSON:
      properties:
        loc:
          anyOf:
          - items:
              anyOf:
              - type: string
              - type: integer
            type: array
          - type: 'null'
          default: null
          description: Error location.
          title: Loc
        msg:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: Error message.
          title: Msg
        type:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: Error type.
          title: Type
        ctx:
          anyOf:
          - type: string
          - additionalProperties: true
            type: object
          - type: 'null'
          default: null
          description: Error context information.
          title: Ctx
      title: ErrorJSON
      type: object
  securitySchemes:
    X-Api-Key:
      type: apiKey
      description: 'For instructions on how to obtain API keys, visit [this page](/docs/guides/getting-api-keys-page/).

        You will obtain two different keys, an initial one for testing in our sandbox environment and once ready, for production.

        Your API keys enables others to act on your behalf if they are able to obtain them, so make sure to keep them safe.

        Your API key is not to be shared with anyone, including in your version control system, client-side code, in public chatrooms and so on.

        The API key is applied in the request header. For example:

        ```

        GET /something

        X-Api-Key: secret_test_aabbccddeeff0123456789

        ```


        API Keys have the following structure: `secret_<env>_<key>` where:

        - `env` is determined by the environment (`prod` for production, `test` for test environments)

        - `key` is a random, URL-safe, 64-bit encoded text string containing 32 random bytes.'
      name: X-Api-Key
      in: header