> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fintoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a transfer

> Creates an outbound transfer from one of your accounts, in the `live` or `test` mode of the API key used. Requirements differ by country. In Chile, the currency is `CLP` and the counterparty needs a `holder_id`, which is the Chilean tax ID (RUT), and an `institution_id`. In Mexico, the currency is `MXN` and the counterparty's `account_number` is a standardized Mexican bank account number (CLABE). Requires a JSON Web Signature (JWS) in the `Fintoc-JWS-Signature` header.

**`v2`** · Base URL `https://api.fintoc.com/v2`


## OpenAPI

````yaml reference/pacioli-api.json POST /transfers
openapi: 3.1.0
info:
  title: Fintoc API
  version: v2026-02-01
servers:
  - url: https://api.fintoc.com/v2
security: []
paths:
  /transfers:
    post:
      tags:
        - Transfers
      summary: Create a transfer
      description: >-
        Creates an outbound transfer from one of your accounts, in the `live` or
        `test` mode of the API key used. Requirements differ by country. In
        Chile, the currency is `CLP` and the counterparty needs a `holder_id`,
        which is the Chilean tax ID (RUT), and an `institution_id`. In Mexico,
        the currency is `MXN` and the counterparty's `account_number` is a
        standardized Mexican bank account number (CLABE). Requires a JSON Web
        Signature (JWS) in the `Fintoc-JWS-Signature` header.
      operationId: transfers-create
      parameters:
        - name: Fintoc-JWS-Signature
          in: header
          required: true
          schema:
            type: string
          description: >-
            JWS signature of the request body. See [Generate JWS
            keys](https://docs.fintoc.com/docs/setting-up-jws-keys) to set up
            request signing.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                account_id:
                  type: string
                  description: Identifier of the account the transfer is sent from.
                  example: acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN
                amount:
                  type: integer
                  description: >-
                    Amount to transfer, in the smallest currency unit. For MXN
                    this is centavos; CLP has no minor unit. The minimum is `1`.
                  example: 50000
                currency:
                  type: string
                  enum:
                    - CLP
                    - MXN
                  description: Currency of the transfer. One of `CLP`, `MXN`.
                  example: MXN
                counterparty:
                  type: object
                  description: Recipient of the transfer.
                  properties:
                    account_number:
                      type: string
                      description: >-
                        Counterparty account number. In Mexico, the 18-digit
                        CLABE; in Chile, the bank account number.
                      example: '132000000000000004'
                    holder_id:
                      type: string
                      description: >-
                        Tax ID of the counterparty. Required in Chile, where it
                        is the RUT.
                      example: 11111111-1
                    holder_name:
                      type: string
                      description: Name of the counterparty.
                      example: Test Customer 1
                    institution_id:
                      type: string
                      description: >-
                        Identifier of the counterparty bank. Required in Chile.
                        In Mexico, required when the `account_number` is a debit
                        card or phone number, since only a CLABE encodes the
                        bank.
                      example: '40012'
                    account_type:
                      type: string
                      description: >-
                        Type of the counterparty account, used in Chile. One of
                        `checking_account`, `sight_account`, `savings_account`.
                      example: checking_account
                    email:
                      type: string
                      description: Email of the counterparty.
                      example: jared@piedpiper.com
                  required:
                    - account_number
                comment:
                  type: string
                  description: Comment shown to the counterparty.
                  example: Payout March
                reference_id:
                  type: string
                  description: >-
                    Numeric reference shown in the counterparty statement in
                    Mexico. Up to 7 digits, with no leading zeros.
                  example: '1234567'
                metadata:
                  type: object
                  description: >-
                    Set of key-value pairs you can attach to the transfer for
                    storing additional structured information.
                  example:
                    test_key: test_value
              required:
                - account_id
                - amount
                - currency
                - counterparty
        required: true
      responses:
        '201':
          description: The created transfer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/transfer'
        '400':
          description: 'Invalid request: a body parameter is missing or invalid.'
          content:
            application/json:
              examples:
                missing_parameter:
                  value:
                    error:
                      type: invalid_request_error
                      code: missing_parameter
                      message: 'Missing required param: amount'
              schema:
                $ref: '#/components/schemas/error_object'
        '401':
          description: Invalid or missing API key.
          content:
            application/json:
              examples:
                invalid_api_key:
                  value:
                    error:
                      type: authentication_error
                      code: invalid_api_key
                      message: 'Invalid API Key: invalid-*oken'
              schema:
                $ref: '#/components/schemas/error_object'
        '409':
          description: Your account has insufficient balance.
          content:
            application/json:
              examples:
                insufficient_balance:
                  value:
                    error:
                      type: invalid_request_error
                      code: insufficient_balance
                      message: >-
                        Account acc_2daFu0zqqDtZGJaSi2TGI2Mm1nN has insufficient
                        balance
              schema:
                $ref: '#/components/schemas/error_object'
      security:
        - api_key: []
components:
  schemas:
    transfer:
      type: object
      description: >-
        A movement of money between one of your accounts and a counterparty. A
        transfer is `outbound` when you send money to a counterparty, or
        `inbound` when money arrives in one of your account numbers. Fintoc
        settles transfers over local payment rails in Chile and Mexico.
      properties:
        id:
          type: string
          description: Unique identifier of the transfer.
          example: tr_2daFu0zqqDtZGJaSi2TGI2Mm1nN
        object:
          const: transfer
          description: Type of the object. Always `transfer`.
        account_number:
          $ref: '#/components/schemas/account_number'
        amount:
          type: integer
          description: >-
            Amount of the transfer, in the smallest currency unit. For MXN this
            is centavos; CLP has no minor unit.
          example: 50000
        comment:
          type:
            - string
            - 'null'
          description: Comment shown to the counterparty, or `null`.
          example: Payout March
        counterparty:
          type: object
          description: Details of the counterparty of the transfer.
          properties:
            account_number:
              type:
                - string
                - 'null'
              description: >-
                Counterparty account number, or `null`. In Mexico, the 18-digit
                standardized bank account number (CLABE); in Chile, the bank
                account number.
              example: '132000000000000004'
            account_type:
              type:
                - string
                - 'null'
              description: Type of the counterparty account, in lowercase, or `null`.
              example: clabe
            email:
              type:
                - string
                - 'null'
              description: Counterparty email, or `null`.
              example: null
            holder_id:
              type:
                - string
                - 'null'
              description: >-
                Tax identifier of the counterparty, or `null`. The Chilean tax
                ID (RUT) in Chile, or the Mexican tax ID (RFC) in Mexico.
              example: null
            holder_name:
              type:
                - string
                - 'null'
              description: Name of the counterparty account holder, or `null`.
              example: Test Customer 1
            institution:
              type: object
              description: Counterparty financial institution.
              properties:
                id:
                  type:
                    - string
                    - 'null'
                  description: Institution identifier.
                  example: '40132'
                name:
                  type:
                    - string
                    - 'null'
                  description: Institution name.
                  example: MULTIVA BANCO
                country:
                  type: string
                  enum:
                    - cl
                    - mx
                  description: >-
                    ISO 3166-1 alpha-2 country code of the institution, in
                    lowercase. One of `cl`, `mx`.
                  example: mx
              required:
                - id
                - name
                - country
          required:
            - account_number
            - account_type
            - email
            - holder_id
            - holder_name
            - institution
        currency:
          type: string
          enum:
            - CLP
            - MXN
          description: Currency of the transfer. One of `CLP`, `MXN`.
          example: MXN
        direction:
          type: string
          enum:
            - inbound
            - outbound
          description: Whether the transfer is `inbound` or `outbound`.
          example: outbound
        entity:
          type: object
          description: >-
            Entity that owns the account involved in the transfer. For an
            `inbound` transfer this is the entity that received the money; for
            an `outbound` transfer, the entity that sent it.
          properties:
            id:
              type: string
              description: Identifier of the entity.
              example: ent_2eGhTp1rLqWnXkZbYc4JsKmAvD9
            holder_id:
              type: string
              description: >-
                Tax identifier of the owner. A Chilean tax ID (RUT) or a Mexican
                tax ID (RFC).
              example: '000000000'
            holder_name:
              type: string
              description: Legal name of the owner.
              example: Test Customer 1
            is_root:
              type: boolean
              description: Whether this entity is the root entity.
              example: true
          required:
            - id
            - holder_id
            - holder_name
            - is_root
        metadata:
          type: object
          description: Set of key-value pairs attached to the transfer.
          example:
            test_key: test_value
        mode:
          type: string
          enum:
            - live
            - test
          description: Whether the transfer is `live` or `test` data.
          example: test
        post_date:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Time the transfer was posted, as an ISO 8601 datetime in UTC, or
            `null`.
          example: null
        receipt_url:
          type:
            - string
            - 'null'
          description: URL of the transfer receipt, or `null`.
          example: null
        reference_id:
          type:
            - string
            - 'null'
          description: >-
            Numeric reference shown in the counterparty statement in Mexico, or
            `null`.
          example: null
        return_reason:
          type:
            - string
            - 'null'
          description: Reason code when the transfer was returned, or `null`.
          example: null
        status:
          type: string
          enum:
            - succeeded
            - rejected
            - failed
            - pending
            - returned
            - return_pending
            - reject_failed
          description: >-
            Lifecycle status of the transfer. One of `pending` (being
            processed), `succeeded` (settled), `rejected` (rejected before
            settling), `failed` (could not be processed), `returned` (settled,
            then returned to the sender), `return_pending` (a return is in
            progress), or `reject_failed` (the rejection could not be
            completed).
          example: succeeded
        tracking_key:
          type:
            - string
            - 'null'
          description: >-
            Interbank tracking key (clave de rastreo) of the transfer, or
            `null`.
          example: null
        transaction_date:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Time the transfer occurred, as an ISO 8601 datetime in UTC, or
            `null`.
          example: '2026-03-01T12:00:00.000Z'
      required:
        - id
        - object
        - account_number
        - amount
        - comment
        - counterparty
        - currency
        - direction
        - entity
        - metadata
        - mode
        - post_date
        - receipt_url
        - reference_id
        - return_reason
        - status
        - tracking_key
        - transaction_date
    error_object:
      type: object
      properties:
        error:
          type: object
          description: Details of the error that caused the request to fail.
          properties:
            code:
              type: string
              description: >-
                Machine-readable code identifying the specific error, for
                example `invalid_request`.
              example: invalid_request
            doc_url:
              type: string
              description: >-
                URL of a documentation page with more details about the error.
                Not returned by every error.
              example: https://docs.fintoc.com/reference/errors
            message:
              type: string
              description: Human-readable message describing the error.
              example: 'Missing required param: account_id'
            param:
              type:
                - string
                - 'null'
              description: >-
                Name of the request parameter that caused the error. Not
                returned by every error.
              example: account_id
            type:
              type: string
              description: >-
                Category of the error, for example `invalid_request_error` or
                `authentication_error`. Not returned by every error.
              example: invalid_request_error
          required:
            - code
            - message
      required:
        - error
    account_number:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the account number.
          example: acno_2daFu0zqqDtZGJaSi2TGI2Mm1nN
        object:
          const: account_number
          description: Type of the object. Always `account_number`.
        account_id:
          type: string
          description: Identifier of the account this number belongs to.
          example: acc_2hQ9vBmKpR7xLtZ3sWn1fJ4dGcA
        created_at:
          type: string
          format: date-time
          description: Time the account number was created, as an ISO 8601 datetime in UTC.
          example: '2026-03-01T12:00:00.000Z'
        deleted_at:
          type:
            - string
            - 'null'
          description: >-
            Time the account number was deleted, as an ISO 8601 datetime in UTC,
            or `null` when not deleted.
          example: null
        description:
          type:
            - string
            - 'null'
          description: >-
            Free-text description of the account number, or `null` when none is
            set.
          example: Payouts CLABE
        is_root:
          type: boolean
          description: Whether this account number is the account's default.
          example: false
        last_transfer_at:
          type:
            - string
            - 'null'
          description: >-
            Time of the last transfer received, as an ISO 8601 datetime in UTC,
            or `null` when no transfer has been received.
          example: null
        metadata:
          type: object
          description: Set of key-value pairs attached to the account number.
          example:
            invoice_id: '12345'
        mode:
          type: string
          enum:
            - live
            - test
          description: Whether the account number holds `live` or `test` data.
          example: test
        number:
          type: string
          description: >-
            Account number that receives inbound transfers. In Mexico, the
            18-digit standardized Mexican bank account number (CLABE); in Chile,
            the bank account number.
          example: '646180111800000000'
        options:
          type: object
          description: Inbound transfer constraints for this account number.
          properties:
            min_amount:
              type:
                - integer
                - 'null'
              description: Minimum inbound amount, in the smallest currency unit.
              example: 1000
            max_amount:
              type:
                - integer
                - 'null'
              description: Maximum inbound amount, in the smallest currency unit.
              example: 1000000
          required:
            - min_amount
            - max_amount
        status:
          type: string
          enum:
            - enabled
            - disabled
            - blocked
            - deleted
          description: >-
            Current state of the account number. One of `enabled` (can receive
            inbound transfers), `disabled` (you turned off inbound transfers),
            `blocked` (Fintoc blocked inbound transfers), or `deleted` (removed;
            see `deleted_at`).
          example: enabled
        updated_at:
          type: string
          format: date-time
          description: >-
            Time the account number was last updated, as an ISO 8601 datetime in
            UTC.
          example: '2026-03-01T12:00:00.000Z'
      required:
        - id
        - object
        - account_id
        - created_at
        - deleted_at
        - description
        - is_root
        - last_transfer_at
        - metadata
        - mode
        - number
        - options
        - status
        - updated_at
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header

````