Fipto Beneficiaries API

openapi: 3.2.0
info:
  title: Fipto - OpenAPI 3.0 Beneficiaries API
  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: Beneficiaries
  description: Manage your beneficiaries to whitelist addresses for payout.
paths:
  /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'
components:
  schemas:
    beneficiary_typed_brl_base:
      description: 'BRL / PIX shared shape. The PIX key form is the corridor (BRL_TAX_ID /

        BRL_EVP_RANDOM / BRL_EMAIL / BRL_PHONE_NUMBER). asset (BRL) and

        account_number_type are kept (pinned per key branch) for backward

        compatibility with the legacy wallet_details shape.

        '
      type: object
      required:
      - corridor
      - description
      - wallet_details
      - beneficiary_info
      properties:
        corridor:
          type: string
        description:
          $ref: '#/components/schemas/beneficiary_description'
        wallet_details:
          type: object
          required:
          - asset
          - account_number
          - account_number_type
          properties:
            asset:
              type: string
              enum:
              - BRL
            account_number:
              allOf:
              - $ref: '#/components/schemas/account_number'
              description: The PIX key — CPF/CNPJ (BRL_TAX_ID), the EVP random key (BRL_EVP_RANDOM), an email (BRL_EMAIL), or a phone in E.164 (BRL_PHONE_NUMBER).
            account_number_type:
              type: string
        beneficiary_info:
          $ref: '#/components/schemas/beneficiary_info_with_national_id'
    request_id:
      type: string
      pattern: '[0-9]-[0-9a-fA-F]{8}-[0-9a-fA-F]{24}'
      description: Request identifier.
    beneficiary_info_legal:
      description: Data about Beneficiary of type Legal.
      allOf:
      - $ref: '#/components/schemas/beneficiary_info_base'
      - type: object
        required:
        - type
        - name
        - address
        properties:
          type:
            type: string
            enum:
            - company
          name:
            type: string
            description: The company name.
            allOf:
            - $ref: '#/components/schemas/company_name'
            minLength: 1
            maxLength: 70
          address:
            allOf:
            - $ref: '#/components/schemas/address'
            - $ref: '#/components/schemas/address_required_constraint_all_fields'
          date_of_formation:
            type: string
            format: date
            description: Date the legal entity was incorporated (YYYY-MM-DD). Maps to CPN `BENEFICIARY_DATE_OF_FORMATION`.
            example: '2012-04-02'
          country_of_formation_code:
            description: ISO 3166-1 alpha-2 country of incorporation. Maps to CPN `BENEFICIARY_COUNTRY_OF_FORMATION`.
            allOf:
            - $ref: '#/components/schemas/country_code'
    beneficiary_travel_rule_custodial:
      description: Custodial travel rule information.
      type: object
      oneOf:
      - properties:
          vasp_name:
            $ref: '#/components/schemas/vasp_name'
          vasp_did:
            type: string
            pattern: ^did:[a-zA-Z0-9]*:.*$
            example: did:ethr:0x123456789abcdef
        required:
        - vasp_did
      - properties:
          vasp_name:
            $ref: '#/components/schemas/vasp_name'
          vasp_website:
            type: string
            format: url
        required:
        - vasp_website
        - vasp_name
    sanitized_string:
      type: string
      description: Allow alphanumeric, +, -, _, &, (, ), °,  space, single quote, comma, and all accented characters.
      pattern: ^[a-zA-Z0-9À-ɏ\s+'()_&,°-]*$
    beneficiary_typed_hkd_fps_account_number:
      description: HKD FPS — bank account number + HK bank (clearing) code, name, address.
      type: object
      required:
      - corridor
      - description
      - wallet_details
      - beneficiary_info
      properties:
        corridor:
          type: string
          enum:
          - HKD_FPS_ACCOUNT_NUMBER
        description:
          $ref: '#/components/schemas/beneficiary_description'
        wallet_details:
          type: object
          required:
          - asset
          - account_number
          - account_number_type
          - bank_identifier
          - bank_identifier_type
          - bank_country_code
          properties:
            asset:
              type: string
              enum:
              - HKD
            account_number:
              $ref: '#/components/schemas/account_number'
            account_number_type:
              type: string
              enum:
              - account_number
            bank_identifier:
              allOf:
              - $ref: '#/components/schemas/bank_identifier'
              description: HK bank (clearing) code.
            bank_identifier_type:
              type: string
              enum:
              - bank_code
            bank_country_code:
              type: string
              enum:
              - HK
        beneficiary_info:
          $ref: '#/components/schemas/beneficiary_info_business_choice'
    beneficiary_info_base:
      description: Shared CPN requirement fields for natural and legal beneficiaries. Not used directly; merged via allOf.
      type: object
      properties:
        phone_number:
          type: string
          description: Contact phone number for the beneficiary, in E.164 form. Maps to CPN `BENEFICIARY_PHONE_NUMBER`.
          pattern: ^\+?[1-9]\d{1,14}$
          example: '+442012345678'
        email:
          type: string
          format: email
          description: Contact email for the beneficiary. Maps to CPN `BENEFICIARY_EMAIL`.
          example: maria.gomez@example.com
        national_identification_number:
          type: string
          description: National identification document number (CURP/RFC for MX, CPF/CNPJ for BR, NRIC for SG, etc.). Maps to CPN `BENEFICIARY_NATIONAL_IDENTIFICATION_NUMBER` and `RECIPIENT_ID_NUMBER`.
          example: '98765432100'
        national_identification_expiration_date:
          type: string
          format: date
          description: Expiry date of the national-identification document (YYYY-MM-DD).
          example: '2031-08-15'
    bank_identifier:
      description: The bank's identification code, which can be either a BIC (Bank Identifier Code) for international transfers or a routing number for domestic transfers. This identifies the financial institution where the beneficiary's account is held.
      type: string
      example: BPPCFRTT
    beneficiary_wallet_details_fiat:
      description: Data about Wallet Details of type fiat for beneficiary creation.
      allOf:
      - $ref: '#/components/schemas/wallet_details_common'
      - $ref: '#/components/schemas/account_identifiers'
    beneficiary_batch_item:
      description: Beneficiary data used in batch endpoints.
      type: object
      required:
      - data
      properties:
        errors:
          readOnly: true
          description: list of blocking errors
          type: array
          items:
            $ref: '#/components/schemas/json_error'
        data:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
            - type
            - attributes
            properties:
              type:
                type: string
                enum:
                - batch_beneficiary
              attributes:
                type: object
                additionalProperties: false
                properties:
                  description:
                    allOf:
                    - $ref: '#/components/schemas/sanitized_string_with_dot'
                    minLength: 1
                    maxLength: 80
                    description: Description of the beneficiary that you want to add (e.g. "external wallet account").
                  wallet_details:
                    $ref: '#/components/schemas/wallet_details_beneficiary'
                  beneficiary_info:
                    description: Data about Beneficiary of type Legal.
                    type: object
                    required:
                    - type
                    - name
                    - address
                    properties:
                      type:
                        type: string
                        enum:
                        - company
                      name:
                        type: string
                        description: The company name.
                        allOf:
                        - $ref: '#/components/schemas/company_name'
                        minLength: 1
                        maxLength: 80
                      address:
                        $ref: '#/components/schemas/address'
                  company_address_country:
                    allOf:
                    - $ref: '#/components/schemas/sanitized_string_with_dot'
                  company_registration_number:
                    description: Company registration number
                    type: string
                    allOf:
                    - $ref: '#/components/schemas/sanitized_string'
                  date_of_incorporation:
                    description: The date the company was registered
                    allOf:
                    - $ref: '#/components/schemas/sanitized_string_with_dot'
                  legal_form_type:
                    description: Legal type of the company
                    allOf:
                    - $ref: '#/components/schemas/sanitized_string_with_dot'
                  website:
                    description: Website of the company
                    type: string
                    maxLength: 100
                  company_country_incorporation:
                    description: Country where the company were registered
                    allOf:
                    - $ref: '#/components/schemas/sanitized_string_with_dot'
                  industry:
                    description: Industry type of the company
                    allOf:
                    - $ref: '#/components/schemas/sanitized_string_with_dot'
                  industry_requires_license:
                    description: If the company needs a license to operate.
                    type: boolean
                  type_name_of_license:
                    description: If a license is required, the type of the license.
                    type: string
                    allOf:
                    - $ref: '#/components/schemas/sanitized_string'
                  country_of_license:
                    description: If a license is required, the country ruling the license.
                    allOf:
                    - $ref: '#/components/schemas/sanitized_string_with_dot'
                  license_number_link:
                    description: If a license is required, link to the license of the company
                    allOf:
                    - $ref: '#/components/schemas/sanitized_string_with_dot'
                  payment_acquisition_confirmation:
                    description: ''
                    type: boolean
                  expected_annual_volume:
                    description: The price of the quote.
                    type: string
                    enum:
                    - < 10,000
                    - 10,000 - 50,000
                    - 50,000 - 100,000
                    - 100,000 - 500,000
                    - 500,000 - 1,000,000
                    - '> 1,000,000'
                  customer_due_diligence_completed:
                    description: ''
                    type: boolean
                  directors:
                    type: array
                    items:
                      type: object
                      required:
                      - type
                      properties:
                        full_name:
                          type: string
                          description: First name of the beneficiary.
                          minLength: 1
                          maxLength: 50
                          allOf:
                          - $ref: '#/components/schemas/sanitized_name'
                        date_of_birth:
                          type: string
                          format: date
                        residency_country:
                          $ref: '#/components/schemas/sanitized_string_with_dot'
                        country_of_birth:
                          $ref: '#/components/schemas/sanitized_string_with_dot'
                        type:
                          $ref: '#/components/schemas/sanitized_string_with_dot'
                  ubos:
                    type: array
                    items:
                      type: object
                      properties:
                        full_name:
                          type: string
                          description: First name of the beneficiary.
                          minLength: 1
                          maxLength: 50
                          allOf:
                          - $ref: '#/components/schemas/sanitized_name'
                        date_of_birth:
                          type: string
                          format: date
                        residency_country:
                          type: string
                        country_of_birth:
                          type: string
                        ownership_percent:
                          description: The ownership percentage of the UBO.
                          type: string
                        type_of_ownership:
                          description: If not possible to provide ownership_percent, describe the ownership of the company.
                          allOf:
                          - $ref: '#/components/schemas/sanitized_name'
                  internal:
                    readOnly: true
                    description: True if the beneficiary's bank details match a Fipto wallet deposit address. Cannot be used as an automation payout destination.
                    type: boolean
                  warnings:
                    readOnly: true
                    description: list of non-blocking errors for the current beneficiaries.
                    type: array
                    items:
                      $ref: '#/components/schemas/json_error'
    ngn_bank_name:
      type: string
      description: Allowed Nigerian banks for NGN — CPN's BANK_NAME closed list (BANK-TRANSFER). Snapshot of CPN /requirements (2026-05-28); refresh when CPN changes it.
      example: Suntrust Bank
      enum:
      - Suntrust Bank
      - Accion MFB
      - Standard Chartered Bank
      - Nova MB
      - Citibank Nigeria
      - Wema Bank
      - Bowen MFB
      - Unity Bank
      - Premium Trust bank
      - Mint-Finex Microfinance Bank
      - United Bank for Africa
      - Access Bank (Diamond)
      - Kuda Microfinance Bank
      - Union Bank of Nigeria
      - Ecobank Nigeria
      - Providus Bank
      - PremiumTrust Bank
      - Access Bank
      - Stanbic Ibtc Bank
      - Polaris Bank
      - Taj Bank
      - Lotus Bank
      - Titan Trust Bank
      - Parallex Bank
      - PalmPay
      - Keystone Bank
      - Nomba Bank
      - Moniepoint Microfinance Bank
      - OPay
      - GoMoney
      - Optimus Bank
      - Zenith Bank
      - Fairmoney Microfinance Bank Ltd
      - Heritage Bank
      - Enterprise Bank
      - Guaranty Trust Bank
      - GT Bank
      - MoMo PSB
      - 9JAPAY MICROFINANCE
      - First City Monument Bank
      - Bellbank Microfinance
      - First Bank of Nigeria
      - Titan-Paystack
      - Mainstreet Bank
      - Sterling Bank
      - VFD Microfinance Bank
      - Nownow（Contec Global)
      - NET MFB
      - Jaiz Bank
      - Paga
      - Fidelity Bank
      - Globus Bank
      - Alternative Bank
    beneficiary_wallet_details_digital:
      description: Data about Wallet Details of type digital.
      allOf:
      - $ref: '#/components/schemas/wallet_details_common'
      - type: object
        required:
        - address
        properties:
          address:
            $ref: '#/components/schemas/wallet_address'
          travel_rule:
            $ref: '#/components/schemas/beneficiary_travel_rule'
          travel_rule_status:
            readOnly: true
            allOf:
            - $ref: '#/components/schemas/travel_rule_status'
    approval_group:
      description: An approver group whose authorization rule is still awaiting a sign-off.
      type: object
      required:
      - id
      - name
      properties:
        id:
          $ref: '#/components/schemas/uuid'
        name:
          type: string
    beneficiary_typed_hkd_account_number:
      description: HKD WIRE — account number, SWIFT/BIC, bank country, bank, name, address.
      type: object
      required:
      - corridor
      - description
      - wallet_details
      - beneficiary_info
      properties:
        corridor:
          type: string
          enum:
          - HKD_ACCOUNT_NUMBER
        description:
          $ref: '#/components/schemas/beneficiary_description'
        wallet_details:
          type: object
          required:
          - asset
          - account_number
          - account_number_type
          - bank_identifier
          - bank_identifier_type
          - bank_country_code
          - bank_name
          properties:
            asset:
              type: string
              enum:
              - HKD
            account_number:
              $ref: '#/components/schemas/account_number'
            account_number_type:
              type: string
              enum:
      

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