openapi: 3.1.0
info:
  title: Spense Partner APIs
  description: ' '
  version: v1
  x-logo:
    url: http://app.spensepay.com/assets/spense-logo.svg
    altText: Spense
servers:
  - url: https://api.spensepay.com/partner
    description: Production API
paths:
  /auth/token:
    post:
      tags:
        - Authentication
      summary: Get OAuth2 access token
      operationId: login
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              allOf:
                - $ref: '#/components/schemas/Body_login'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '401':
          description: Incorrect client id or secret
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /auth/ping:
    get:
      tags:
        - Authentication
      summary: Verify that the bearer token is valid.
      operationId: ping
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Ping
        '401':
          description: Not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      security:
        - OAuth2ClientCredentials:
            - me:ping
  /auth/organizations:
    get:
      tags:
        - Authentication
      summary: Get the list of organizations you have access to.
      description: Get the list of organizations the user has access to.
      operationId: get_organizations
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/AuthOrganizationsResponseItem'
                type: array
                title: Response Get Organizations
        '401':
          description: Not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      security:
        - OAuth2ClientCredentials:
            - me:ping
  /settlements/generate_csv:
    get:
      tags:
        - Settlements
      summary: Generate Csv
      description: >-
        Generate a CSV file for the given date range and format.


        Remember: use the header `X-Organization-Id` with the organization ID if
        you are using a

        partner token which has access to multiple organizations.
      operationId: generate_csv
      security:
        - OAuth2ClientCredentials:
            - organization:accounting:read
      parameters:
        - name: X-Organization-Id
          in: header
          required: false
          schema:
            type: string
            description: >-
              Required if the account is part of multiple organizations. If the
              account only has access to one organization, this header is not
              required.
            title: X-Organization-Id
          description: >-
            Required if the account is part of multiple organizations. If the
            account only has access to one organization, this header is not
            required.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SettlementGenerateCSVRequest'
      responses:
        '200':
          description: CSV file generated successfully
          content:
            text/csv:
              examples:
                transactions:
                  summary: Transactions CSV
                  value: >
                    Date of transaction,Payment provider,Settlement
                    reference,Settlement paid at,Reference,Currency,Gross
                    amount,Fees,Net amount,Payment type,Payment method

                    2025-07-09 00:00:00+00:00,Worldline
                    Bambora,12345678-20250710,2025-07-10
                    00:00:00+00:00,100000,NOK,1200.99,,,Debit,Visa

                    2025-07-09 00:00:00+00:00,Worldline
                    Bambora,12345678-20250710,2025-07-10
                    00:00:00+00:00,100001,NOK,9000.00,,,Credit,Mastercard
                payouts:
                  summary: Payouts CSV
                  value: >-
                    Date of payout,Payment provider,Reference,Currency,Gross
                    Amount,Fees,Net Amount
                machine_readable:
                  summary: Machine Readable CSV
                  value: >-
                    A,142,142,6639578.85,66395.7885,6573183.0615,6573183.0615,0

                    R,TEST_MODE,142,142,6639578.85,66395.7885,6573183.0615,0

                    P,TEST_MODE,2025-03-13
                    08:23:09.314000+00:00,test-payout-2025-03-13,67d3e41cb549716390b54557,1,1.25,0.0125,1.2375,1.2375,0

                    P,TEST_MODE,2025-03-12
                    10:18:23.495000+00:00,test-payout-2025-03-12,67d3e41db549716390b54559,1,1250.00,12.50,1237.50,1237.50,0

                    P,TEST_MODE,2025-02-26
                    11:38:48.226000+00:00,test-payout-2025-02-26,67d3e41db549716390b5455b,1,1.25,0.0125,1.2375,1.2375,0

                    P,TEST_MODE,2025-02-25
                    10:27:41.182000+00:00,test-payout-2025-02-25,67d3e41db549716390b5455d,1,6943.75,69.4375,6874.3125,6874.3125,0

                    P,TEST_MODE,2025-02-20
                    09:38:48.861000+00:00,test-payout-2025-02-20,67d3e41db549716390b5455f,1,125.00,1.25,123.75,123.75,0

                    P,TEST_MODE,2025-02-18
                    11:25:05.330000+00:00,test-payout-2025-02-18,67d3e41db549716390b54561,1,906.25,9.0625,897.1875,897.1875,0

                    P,TEST_MODE,2025-02-18
                    09:20:47.886000+00:00,test-payout-2025-02-18,67d3e41db549716390b54563,1,125000.00,1250.00,123750.00,123750.00,0

                    T,67d2930eab66aeaa3798bda5,,test-payout-2025-03-13,2025-03-13
                    08:23:09.314000+00:00,NET,123456789,,1.25,0.0125,1.2375,SETTLED,NOK,2025-03-13
                    08:23,

                    T,67d15f3972cff55014d7db79,,test-payout-2025-03-12,2025-03-12
                    10:18:23.495000+00:00,NET,dfgds,,1250.00,12.50,1237.50,SETTLED,NOK,2025-03-12
                    10:18,

                    T,67befd119d9096a7397167b7,,test-payout-2025-02-26,2025-02-26
                    11:38:48.226000+00:00,NET,Test,,1.25,0.0125,1.2375,SETTLED,NOK,2025-02-26
                    11:38,

                    T,67bd9aed08ec2fddd8da4ac1,,test-payout-2025-02-25,2025-02-25
                    10:27:41.182000+00:00,NET,gdsgfdfg,,6943.75,69.4375,6874.3125,SETTLED,NOK,2025-02-25
                    10:27,

                    T,67b6f7ee77b06c1a9e7416de,,test-payout-2025-02-20,2025-02-20
                    09:38:48.861000+00:00,NET,qweqwewq,,125.00,1.25,123.75,SETTLED,NOK,2025-02-20
                    09:38,

                    T,67b46d815895ee63a6d6b558,,test-payout-2025-02-18,2025-02-18
                    11:25:05.330000+00:00,NET,qwewqeqwe,,906.25,9.0625,897.1875,SETTLED,NOK,2025-02-18
                    11:25,

                    T,67b45091c1fd4d79ff1264ab,,test-payout-2025-02-18,2025-02-18
                    09:20:47.886000+00:00,NET,qweqwe,,125000.00,1250.00,123750.00,SETTLED,NOK,2025-02-18
                    09:20,

                    T,67b4479ebd41a5adc588226c,,test-payout-2025-02-18,2025-02-18
                    08:41:43.831000+00:00,NET,qwewqewqe,,906.25,9.0625,897.1875,SETTLED,NOK,2025-02-18
                    08:41,

                    T,67ae173061e1970428a2610b,,test-payout-2025-02-13,2025-02-13
                    16:02:24.891000+00:00,NET,qweqwewqe,,1250.00,12.50,1237.50,SETTLED,NOK,2025-02-13
                    16:02,

                    T,67ae0f8f0841b4703d7ed577,,test-payout-2025-02-13,2025-02-13
                    15:28:51.899000+00:00,NET,123123,,1250.00,12.50,1237.50,SETTLED,NOK,2025-02-13
                    15:28,

                    T,67ac6497dd520588af6c7b95,,test-payout-2025-02-12,2025-02-12
                    09:08:03.261000+00:00,NET,1235,,125.00,1.25,123.75,SETTLED,NOK,2025-02-12
                    09:08,
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /payment-methods:
    get:
      tags:
        - Payment Methods
      summary: Get Payment Methods
      description: >-
        Get a list of available payment methods, which can be used to specify
        which payment method to use when

        creating a payment. The list of payment methods may change over time, so
        it is recommended to fetch this list

        dynamically when creating a payment, to allow the user select the
        payment method they want to use.


        The list of payment methods is not guaranteed to be exhaustive, and
        special configuration is needed for most

        of the possible methods.


        The default method which is a payment link, will always be available
        with the string ID `000000000000000000000000`.
      operationId: get_payment_methods
      security:
        - OAuth2ClientCredentials:
            - organization:payflow:create
      parameters:
        - name: test_mode
          in: query
          required: false
          schema:
            type: boolean
            default: false
            title: Test Mode
        - name: X-Organization-Id
          in: header
          required: false
          schema:
            type: string
            description: >-
              Required if the account is part of multiple organizations. If the
              account only has access to one organization, this header is not
              required.
            title: X-Organization-Id
          description: >-
            Required if the account is part of multiple organizations. If the
            account only has access to one organization, this header is not
            required.
      responses:
        '200':
          description: List of available payment methods
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PartnerPaymentMethod'
                title: Response Get Payment Methods
              examples:
                basic:
                  summary: Basic payment methods
                  value:
                    - id: '000000000000000000000000'
                      name: Payment link via SMS/Email
                      type: payment_link
                      active: true
                with_terminals:
                  summary: Payment methods with terminals
                  value:
                    - id: '000000000000000000000000'
                      name: Payment link via SMS/Email
                      type: payment_link
                      active: true
                    - id: 68551872ae7439dd2523da78
                      name: Terminal 1
                      type: terminal
                      active: true
                    - id: 68551872ae7439dd2523da79
                      name: Terminal 2
                      type: terminal
                      active: true
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /payment-methods/resend:
    post:
      tags:
        - Payment Methods
      summary: Resend To Payment Method
      description: >-
        Attempt to re-send the payment method for a payment.This will not create
        a new payment,

        but re-send the payment to the specified payment method.

        This can be used many times and have different behaviour

        depending on the type of method used.


        - If a payment link method is used, the payment link will be sent again.

        - If a terminal method is used, the payment will be sent to the
        specified terminal.

        - If a invoice method is used, we will send a invoice to the specified
        invoice type.


        Rely on webhooks to get notified about the result of the action.
      operationId: resend_to_payment_method
      security:
        - OAuth2ClientCredentials:
            - organization:payflow:create
      parameters:
        - name: X-Organization-Id
          in: header
          required: false
          schema:
            type: string
            description: >-
              Required if the account is part of multiple organizations. If the
              account only has access to one organization, this header is not
              required.
            title: X-Organization-Id
          description: >-
            Required if the account is part of multiple organizations. If the
            account only has access to one organization, this header is not
            required.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResendRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Resend To Payment Method
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    APIErrorResponse:
      properties:
        detail:
          anyOf:
            - type: string
            - items:
                type: object
              type: array
          title: Detail
      type: object
      required:
        - detail
      title: APIErrorResponse
    AuthOrganizationsResponseItem:
      properties:
        id:
          type: string
          pattern: ^[a-fA-F0-9]{24}$
          title: Id
        name:
          type: string
          title: Name
        vat_number:
          anyOf:
            - type: string
            - type: 'null'
          title: Vat Number
        country:
          anyOf:
            - type: string
            - type: 'null'
          title: Country
        payment_profiles:
          items:
            $ref: '#/components/schemas/AuthOrganizationsResponseItemPaymentProfile'
          type: array
          title: Payment Profiles
          default: []
      type: object
      required:
        - id
        - name
      title: AuthOrganizationsResponseItem
      description: Response model for the list of organizations.
    AuthOrganizationsResponseItemPaymentProfile:
      properties:
        id:
          type: string
          pattern: ^[a-fA-F0-9]{24}$
          title: Id
        name:
          type: string
          title: Name
        currency:
          anyOf:
            - $ref: '#/components/schemas/Currency'
            - type: 'null'
        department:
          allOf:
            - $ref: '#/components/schemas/PaymentDepartment'
          default: UNKNOWN
        active:
          type: boolean
          title: Active
          default: true
        test_mode:
          type: boolean
          title: Test Mode
          default: false
      type: object
      required:
        - id
        - name
      title: AuthOrganizationsResponseItemPaymentProfile
      description: Response model for the payment profile of an organization.
    Body_login:
      properties:
        grant_type:
          type: string
          pattern: ^(client_credentials|refresh_token)$
          title: Grant Type
          default: client_credentials
        scope:
          type: string
          title: Scope
          default: ''
        client_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Client Id
          examples:
            - your_client_id
        client_secret:
          anyOf:
            - type: string
            - type: 'null'
          title: Client Secret
          examples:
            - your_client_secret
      type: object
      title: Body_login
    Currency:
      type: string
      enum:
        - NOK
        - DKK
        - EUR
        - SEK
        - USD
        - GBP
        - QAR
      title: Currency
      description: >-
        Add currency here if we need to support more currencies.


        Note: Great care needs to be applied, as currently we only support
        currencies that have
              a double digit decimal point as their lowest denomination.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PartnerPaymentMethod:
      properties:
        id:
          type: string
          pattern: ^[a-fA-F0-9]{24}$
          title: Id
        name:
          type: string
          title: Name
        profile_ids:
          items:
            type: string
          type: array
          title: Profile Ids
          description: The IDs of the profiles that the payment method belongs to.
          default: []
        type:
          allOf:
            - $ref: '#/components/schemas/PartnerPaymentMethodType'
          description: >-
            The type of payment method. Can be extended to other types in the
            future.
        active:
          type: boolean
          title: Active
          description: >-
            Whether the payment method is active. Recommend to display in-active
            payments, but as disabled. Can for example be inactive if a terminal
            is turned off.
          default: true
      type: object
      required:
        - id
        - name
        - type
      title: PartnerPaymentMethod
    PartnerPaymentMethodType:
      type: string
      enum:
        - payment_link
        - terminal
        - invoice
      title: PartnerPaymentMethodType
    PaymentDepartment:
      type: string
      enum:
        - UNKNOWN
        - CARSALE
        - SERVICE
        - PARTS
        - OTHER
      title: PaymentDepartment
    ResendRequest:
      properties:
        payflow_id:
          type: string
          pattern: ^[a-fA-F0-9]{24}$
          title: Payflow Id
        payment_method_id:
          type: string
          pattern: ^[a-fA-F0-9]{24}$
          title: Payment Method Id
      type: object
      required:
        - payflow_id
        - payment_method_id
      title: ResendRequest
    SettlementCSVType:
      type: string
      enum:
        - transactions
        - payouts
        - machine_readable
      title: SettlementCSVType
    SettlementGenerateCSVRequest:
      properties:
        from_date:
          type: string
          format: date
          title: From Date
          examples:
            - '2023-01-01'
            - '2023-06-15'
        to_date:
          type: string
          format: date
          title: To Date
          examples:
            - '2023-01-31'
            - '2023-06-30'
        format:
          allOf:
            - $ref: '#/components/schemas/SettlementCSVType'
          description: The format of the CSV file to generate.
          default: transactions
          examples:
            - transactions
            - payouts
            - machine_readable
        test_mode:
          type: boolean
          title: Test Mode
          default: false
        payout_type:
          allOf:
            - $ref: '#/components/schemas/SettlementPayoutType'
          default: PSP
      type: object
      required:
        - from_date
        - to_date
      title: SettlementGenerateCSVRequest
    SettlementPayoutType:
      type: string
      enum:
        - PSP
        - SPENSE
      title: SettlementPayoutType
    TokenResponse:
      properties:
        access_token:
          type: string
          title: Access Token
          description: The access token (UUID)
          examples:
            - 123e4567-e89b-12d3-a456-426614174000
        token_type:
          type: string
          title: Token Type
          description: The type of the token, typically 'bearer'.
          default: bearer
          examples:
            - bearer
        expires_in:
          type: integer
          title: Expires In
          description: The number of seconds until the token expires.
          examples:
            - 3600
      type: object
      required:
        - access_token
        - expires_in
      title: TokenResponse
      description: An OAuth2 Token response.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    HTTPBasic:
      type: http
      scheme: basic
    OAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: /partner/auth/token
tags:
  - name: Authentication
  - name: Settlements
  - name: Payment Methods
  - name: Webhooks
