Fipto API

openapi: 3.0.3
info:
  title: Fipto - OpenAPI 3.0
  version: 4.3.0
  description: This is a REST API specifications based on OpenAPI 3.0 for Fipto solution.
  contact:
    url: https://www.fipto.com/
servers:
- url: https://api.fipto.app
  description: The API server on production
tags:
- name: Assets
  description: Retrieve information about assets supported by Fipto.
- name: Transactions
  description: Initiate payout and retrieve information about ongoing and completed transactions.
- name: Wallets
  description: Manage wallets and their related wallet details.
- name: Beneficiaries
  description: Manage your beneficiaries to whitelist addresses for payout.
- name: Companies
  description: Manage information and settings of a company.
- name: AISP/PISP
  description: Endpoints for AISP/PISP.
- name: Payment links
  description: Manage payment links.
- name: Conversions
  description: Manage conversions.
- name: KYC Reliance
  description: Manage KYC reliance onboardings for client onboarding via API.
paths:
  /companies/{company_id}/assets:
    get:
      summary: Get supported assets
      description: Retrieve the list of supported assets of a company.
      operationId: listAssets
      tags:
      - Assets
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/page_number'
      - $ref: '#/components/parameters/page_size'
      - name: sort
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/sort_asset_list'
      responses:
        '200':
          description: List of all assets.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/meta'
                - $ref: '#/components/schemas/pagination'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/asset_data'
  /companies/{company_id}/request-usd:
    post:
      summary: Request USD onboarding
      description: Request USD onboarding for a company.
      operationId: requestUsdOnboarding
      tags:
      - Assets
      parameters:
      - $ref: '#/components/parameters/company_id'
      responses:
        '204':
          description: Request USD onboarding initiated.
  /companies/{company_id}/quotes:
    post:
      summary: Create a new automated quote
      operationId: createAQuote
      tags:
      - Conversions
      parameters:
      - $ref: '#/components/parameters/company_id'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  oneOf:
                  - $ref: '#/components/schemas/quote_buy_sided'
                  - $ref: '#/components/schemas/quote_sell_sided'
      responses:
        '201':
          description: Quote successfully created
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/meta'
                - type: object
                  required:
                  - data
                  properties:
                    data:
                      allOf:
                      - $ref: '#/components/schemas/quote_buy_sided'
                      - $ref: '#/components/schemas/quote_sell_sided'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    required:
                    - message
                    properties:
                      message:
                        type: string
                        oneOf:
                        - pattern: '^Manual flow required: company trading limits hit\.$'
                        - pattern: '^Manual flow required: amount is below the minimum eur trading volume: \d{1,}\.$'
                        - pattern: '^Manual flow required: amount is above the maximum eur trading volume: \d{1,}\.$'
                        - pattern: '^Manual flow required: pair is forbidden'
                        - pattern: ^Manual flow required\.$
                        - pattern: ^Asset codes of buy and sell wallets must be different\.$
                        - pattern: ^Wallets not found\.$
                        - pattern: ^Buy wallet not found\.$
                        - pattern: ^Sell wallet not found\.$
                        - pattern: ^Sell amount must have \d{1,} decimals\.$
  /companies/{company_id}/quotes/{quote_id}/status:
    patch:
      summary: Confirm a quote.
      operationId: confirmQuoteStatus
      tags:
      - Conversions
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/quote_id'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  $ref: '#/components/schemas/quote_status_confirmed_data'
      responses:
        '200':
          description: Quote successfully updated
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/meta'
                - type: object
                  required:
                  - data
                  properties:
                    data:
                      $ref: '#/components/schemas/quote_status_confirmed_data'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    required:
                    - message
                    properties:
                      message:
                        type: string
                        oneOf:
                        - pattern: '^Manual flow required: company trading limits hit\.$'
                        - pattern: ^Asset codes of buy and sell wallets must be different\.$
                        - pattern: ^Quote is expired\.$
                        - pattern: ^Quote not found\.$
                        - pattern: ^Quote is not in submitted status\.$
                        - pattern: ^Insufficient funds\.$
                        - pattern: ^Quote already validated\.$
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    required:
                    - message
                    properties:
                      message:
                        type: string
                        oneOf:
                        - pattern: ^Quote not found\.$
  /companies:
    get:
      summary: Get companies
      description: Retrieve companies linked to the logged user.
      operationId: listCompaniesByUser
      tags:
      - Companies
      parameters:
      - $ref: '#/components/parameters/page_number'
      - $ref: '#/components/parameters/page_size'
      - name: sort
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/sort_company_list'
      responses:
        '200':
          description: List of all companies.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/meta'
                - $ref: '#/components/schemas/pagination'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/company_data'
  /companies/{company_id}:
    get:
      summary: Get a company
      description: Retrieve a specific company linked to the logged user.
      operationId: getCompany
      tags:
      - Companies
      parameters:
      - $ref: '#/components/parameters/company_id'
      responses:
        '200':
          description: Company details.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/meta'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/company_data'
  /companies/{company_id}/beneficiaries/file-conversion:
    post:
      summary: Validate a batch of beneficiaries
      description: Validate a CSV representation of a batch of beneficiaries.
      operationId: validateBatchBeneficiary
      tags:
      - Beneficiaries
      parameters:
      - $ref: '#/components/parameters/company_id'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  type: object
                  required:
                  - attributes
                  - type
                  properties:
                    type:
                      type: string
                      enum:
                      - batch_beneficiaries
                    attributes:
                      type: object
                      required:
                      - beneficiaries
                      properties:
                        beneficiaries:
                          type: string
                          description: The file encoded in base 64.
                          example: TODO
      responses:
        '200':
          description: CSV successfully parsed
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/meta'
                - $ref: '#/components/schemas/beneficiary_batch_item'
  /companies/{company_id}/beneficiaries/batch:
    post:
      summary: Create a batch of beneficiaries
      description: Create a batch of beneficiaries for your company. A beneficiary is necessary to initiate a payout.
      operationId: createBatchBeneficiaries
      tags:
      - Beneficiaries
      parameters:
      - $ref: '#/components/parameters/company_id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/beneficiary_batch_item'
      responses:
        '201':
          description: Beneficiaries batch successfully created.
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/meta'
                - $ref: '#/components/schemas/beneficiary_batch_item'
  /companies/{company_id}/beneficiaries:
    post:
      summary: Create a beneficiary
      description: Create a beneficiary for your company. A beneficiary is necessary to initiate a payout.
      operationId: createBeneficiary
      tags:
      - Beneficiaries
      parameters:
      - $ref: '#/components/parameters/company_id'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  oneOf:
                  - allOf:
                    - $ref: '#/components/schemas/beneficiary_raw_data'
                    - not:
                        properties:
                          attributes:
                            required:
                            - corridor
                  - $ref: '#/components/schemas/beneficiary_typed_data'
            examples:
              Digital - Natural person - Not belonging to company - dev front:
                value:
                  data:
                    type: beneficiary
                    attributes:
                      description: My beneficiary
                      wallet_details:
                        asset: BTC
                        address: bc1***
                        travel_rule_status: incomplete
                      beneficiary_info:
                        type: individual
                        firstname: Sam
                        lastname: Doe
                        address:
                          street_address: 25 rue François 1er
                          zip_code: '75008'
                          city: Paris
                          country_code: FR
              Digital - Legal person - Not belonging to company - dev front:
                value:
                  data:
                    type: beneficiary
                    attributes:
                      description: My beneficiary
                      wallet_details:
                        asset: BTC
                        address: bc1***
                        travel_rule_status: incomplete
                      beneficiary_info:
                        type: company
                        name: Acme
                        address:
                          street_address: 25 rue François 1er
                          zip_code: '75008'
                          city: Paris
                          country_code: FR
              Digital - Belonging to company - dev front:
                value:
                  data:
                    type: beneficiary
                    attributes:
                      description: My beneficiary
                      wallet_details:
                        asset: BTC
                        address: bc1***
                        travel_rule_status: incomplete
                      beneficiary_info:
                        type: self
              Digital - Natural person - Not belonging to company:
                value:
                  data:
                    type: beneficiary
                    attributes:
                      description: My beneficiary
                      wallet_details:
                        asset: BTC
                        address: bc1***
                        travel_rule_status: incomplete
                      beneficiary_info:
                        type: individual
                        firstname: Sam
                        lastname: Doe
                        address:
                          street_address: 25 rue François 1er
                          zip_code: '75008'
                          city: Paris
                          country_code: FR
              Digital - Legal person - Not belonging to company:
                value:
                  data:
                    type: beneficiary
                    attributes:
                      description: My beneficiary
                      wallet_details:
                        asset: BTC
                        address: bc1***
                        travel_rule_status: incomplete
                      beneficiary_info:
                        type: company
                        name: Acme
                        address:
                          street_address: 25 rue François 1er
                          zip_code: '75008'
                          city: Paris
                          country_code: FR
              Digital - Belonging to company:
                value:
                  data:
                    type: beneficiary
                    attributes:
                      description: My beneficiary
                      wallet_details:
                        asset: BTC
                        address: bc1***
                        travel_rule_status: incomplete
                      beneficiary_info:
                        type: self
      responses:
        '201':
          description: Beneficiary successfully created.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/meta'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/beneficiary_data'
              examples:
                Digital - Natural person - Not belonging to company:
                  value:
                    meta:
                      request_id: dba2bB95-28eD-E9E9-9ABC-7535831512bb
                    data:
                      type: beneficiary
                      id: fea2bB77-54eF-E9E9-9ABC-6535831512aa
                      attributes:
                        description: My beneficiary
                        wallet_details:
                          asset: BTC
                          address: bc1***
                          travel_rule_status: incomplete
                        beneficiary_info:
                          type: individual
                          firstname: Sam
                          lastname: Doe
                          address:
                            street_address: 25 rue François 1er
                            zip_code: '75008'
                            city: Paris
                            country_code: FR
                Digital - Legal person - Not belonging to company:
                  value:
                    meta:
                      request_id: dba2bB95-28eD-E9E9-9ABC-7535831512bb
                    data:
                      type: beneficiary
                      id: fea2bB77-54eF-E9E9-9ABC-6535831512aa
                      attributes:
                        description: My beneficiary
                        wallet_details:
                          asset: BTC
                          address: bc1***
                          travel_rule_status: incomplete
                        beneficiary_info:
                          type: company
                          name: Acme
                          address:
                            street_address: 25 rue François 1er
                            zip_code: '75008'
                            city: Paris
                            country_code: FR
                Digital - Belonging to company:
                  value:
                    meta:
                      request_id: dba2bB95-28eD-E9E9-9ABC-7535831512bb
                    data:
                      type: beneficiary
                      id: fea2bB77-54eF-E9E9-9ABC-6535831512aa
                      attributes:
                        description: My beneficiary
                        wallet_details:
                          asset: BTC
                          address: bc1***
                          travel_rule_status: incomplete
                        beneficiary_info:
                          type: self
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Invalid address:
                  value:
                    meta:
                      request_id: XXXX-XXXX-XXXX-XXXX-XXXX
                    errors:
                      code: invalid_identifier
                      source:
                        pointer: /data/attributes/wallet_details/address
                      title: Invalid Address
                      detail: This address is not valid for the selected asset network
        '403':
          description: Forbidden — user is not authorized by the company's authorization policy.
    get:
      summary: Get beneficiaries
      operationId: listBeneficiaries
      description: Retrieve all beneficiaries of a company.
      tags:
      - Beneficiaries
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/page_number'
      - $ref: '#/components/parameters/page_size'
      - $ref: '#/components/parameters/sort'
      - $ref: '#/components/parameters/filter_beneficiary_types'
      - $ref: '#/components/parameters/filter_beneficiary_assets'
      responses:
        '200':
          description: List of all beneficiaries.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/meta'
                - $ref: '#/components/schemas/pagination'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/beneficiary_data'
  /companies/{company_id}/beneficiaries/{beneficiary_id}:
    get:
      summary: Get a beneficiary
      operationId: searchBeneficiaries
      description: Retrieve a specific beneficiary by its unique identifier.
      tags:
      - Beneficiaries
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/beneficiary_id'
      responses:
        '200':
          description: Retrieve a beneficiary.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/meta'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/beneficiary_data'
    delete:
      summary: Delete a beneficiary
      operationId: deleteBeneficiary
      description: Delete a specific beneficiary.
      tags:
      - Beneficiaries
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/beneficiary_id'
      responses:
        '204':
          description: Beneficiary deleted
  /companies/{company_id}/beneficiaries/{beneficiary_id}/verify:
    post:
      summary: Verify a euro beneficiary
      operationId: verifyBeneficiary
      description: Verify a euro beneficiary using the VOP (Verification Of Payee) scheme.
      tags:
      - Beneficiaries
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/beneficiary_id'
      responses:
        '200':
          description: Verification done.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/meta'
                - type: object
                  required:
                  - data
                  properties:
                    data:
                      type: object
                      required:
                      - type
                      - id
                      - attributes
                      properties:
                        id:
                          type: string
                          description: ID of the verification that was made. This ID can be used when initiating a payout
                            to the same beneficiary.
                        type:
                          type: string
                          enum:
                          - verification_of_payee
                        attributes:
                          type: object
                          required:
                          - code
                          properties:
                            code:
                              $ref: '#/components/schemas/vop_code'
                            close_match:
                              $ref: '#/components/schemas/vop_close_match'
  /companies/{company_id}/beneficiaries/{beneficiary_id}/wallet-details/travel-rule:
    patch:
      summary: Update the travel rule of a beneficiary
      operationId: updateBeneficiaryTravelRule
      description: Update the travel rule of a beneficiary.
      tags:
      - Travel Rule
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/beneficiary_id'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  $ref: '#/components/schemas/beneficiary_travel_rule_patch_data'
      responses:
        '200':
          description: Beneficiary travel rule successfully updated.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/meta'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/beneficiary_travel_rule_patch_data'
  /companies/{company_id}/automations:
    get:
      summary: List automation rules
      description: Retrieve the list of automation rules for your company.
      operationId: listAutomations
      tags:
      - Automations
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/page_number'
      - $ref: '#/components/parameters/page_size_optional'
      - name: status
        in: query
        description: Filter by status
        required: false
        schema:
          type: string
          enum:
          - active
      - name: rule_type
        in: query
        description: Filter by rule type
        required: false
        schema:
          type: string
          enum:
          - conversion
          - payout
      responses:
        '200':
          description: List of automation rules.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/meta'
                - $ref: '#/components/schemas/pagination'
                - type: object
                  required:
                  - data
                  properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/automation_rule_data'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    required:
                    - message
                    properties:
                      message:
                        type: string
                        oneOf:
                        - pattern: ^Automation is not enabled for this company\.$
    post:
      summary: Create automation rule
      description: Create a new automation rule for automatic conversions or payouts. Requires 2FA verification.
      operationId: createAutomation
      tags:
      - Automations
      parameters:
      - $ref: '#/components/parameters/company_id'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  $ref: '#/components/schemas/automation_rule_create_raw_data'
      responses:
        '201':
          description: Automation rule successfully created.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/meta'
                - type: object
                  required:
                  - data
                  properties:
                    data:
                      $ref: '#/components/schemas/automation_rule_data'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    required:
                    - message
                    properties:
                      message:
                        type: string
                        oneOf:
                        - pattern: ^Automation is not enabled for this company\.$
                        - pattern: ^Invalid rule_type\. Must be 'conversion' or 'payout'\.$
                        - pattern: ^Invalid trigger_event\. Must be 'payin_completed' or 'conversion_completed'\.$
                        - pattern: ^Conversion rules can only be triggered by 'payin_completed'\.$
                        - pattern: ^Invalid amount_mode\. Must be 'full' or 'inherited'\.$
                        - pattern: ^Source wallet asset is not eligible for automation\. Only EUR, USD, and stablecoins are
                            supported\.$
                        - pattern: ^This wallet already has an active automation rule for this trigger event\. Only one rule
                            per trigger event per wallet is allowed\.$
                        - pattern: ^destination_wallet_id is required for conversion rules\.$
                        - pattern: ^Destination wallet must be different from source wallet\.$
                        - pattern: ^Destination wallet must have a different currency for conversions\.$
                        - pattern: ^destination_beneficiary_id is required for payout rules\.$
                        - pattern: ^Beneficiary currency must match source wallet currency for payouts\.$
                        - pattern: ^This beneficiary targets a Fipto wallet and cannot be used for automation\.$
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    required:
                    - message
                    properties:
                      message:
                        type: string
                        oneOf:
                        - pattern: ^Unknown source wallet\.$
                        - pattern: ^Unknown destination wallet\.$
                        - pattern: ^Unknown beneficiary\.$
  /companies/{company_id}/automations/{automation_id}:
    get:
      summary: Get automation rule
      description: Retrieve a specific automation rule by its unique identifier.
      operationId: getAutomation
      tags:
      - Automations
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/automation_id'
      responses:
        '200':
          description: Automation rule details.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/meta'
                - type: object
                  required:
                  - data
                  properties:
                    data:
                      $ref: '#/components/schemas/automation_rule_data'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    required:
                    - message
                    properties:
                      message:
                        type: string
                        oneOf:
                        - pattern: ^Automation is not enabled for this company\.$
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    required:
                    - message
                    properties:
                      message:
                        type: string
                        oneOf:
                        - pattern: ^Unknown automation rule\.$
    put:
      summary: Update automation rule
      description: Update an existing automation rule's configuration.
      operationId: updateAutomation
      tags:
      - Automations
      parameters:
      - $ref: '#/components/parameters/company_id'
      - $ref: '#/components/parameters/automation_id'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  $ref: 

# --- truncated at 32 KB (395 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fipto/refs/heads/main/openapi/fipto-customer-api-openapi.yml