> ## 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.

# Simulate receiving a transfer

> Test-mode helper that simulates an inbound transfer into one of your account numbers, so you can exercise incoming-transfer flows. Only available with a `test` API key.

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


## OpenAPI

````yaml reference/pacioli-api.json POST /simulate/receive_transfer
openapi: 3.1.0
info:
  title: Fintoc API
  version: v2026-02-01
servers:
  - url: https://api.fintoc.com/v2
security: []
paths:
  /simulate/receive_transfer:
    post:
      tags:
        - Transfers
      summary: Simulate receiving a transfer
      description: >-
        Test-mode helper that simulates an inbound transfer into one of your
        account numbers, so you can exercise incoming-transfer flows. Only
        available with a `test` API key.
      operationId: transfers-simulate-receive
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                account_number_id:
                  type: string
                  description: Account number that receives the simulated transfer.
                  example: acno_2daFu0zqqDtZGJaSi2TGI2Mm1nN
                amount:
                  type: integer
                  description: >-
                    Amount to receive, in the smallest currency unit. For MXN
                    this is centavos; CLP has no minor unit. The minimum is `1`.
                  example: 1500
                currency:
                  type: string
                  enum:
                    - CLP
                    - MXN
                  description: Currency of the transfer. One of `CLP`, `MXN`.
                  example: CLP
                comment:
                  type: string
                  description: Comment to attach to the simulated transfer.
                  example: Test deposit
                reference_id:
                  type: string
                  description: >-
                    Numeric reference shown in the counterparty statement in
                    Mexico. Up to 7 digits.
                  example: '1234567'
                counterparty_account_number:
                  type: string
                  description: >-
                    Account number of the simulated sender. In Mexico, Fintoc
                    derives the sender's account type and institution from this
                    value. Use a standardized Mexican bank account number
                    (CLABE), debit card number, mobile phone number, or a
                    Chilean bank account number; defaults to a Fintoc test
                    counterparty when omitted.
                  example: '646180111800000000'
                counterparty_account_type:
                  type: string
                  description: >-
                    Type of the simulated sender account, used in Chile. One of
                    `checking_account`, `sight_account`, or `savings_account`.
                  example: checking_account
                counterparty_institution_id:
                  type: string
                  description: >-
                    Identifier of the simulated sender's financial institution,
                    used in Chile. Use a bank public ID such as
                    `cl_banco_santander`. In Mexico, Fintoc ignores this value
                    and derives the institution from
                    `counterparty_account_number`.
                  example: cl_banco_santander
                counterparty_holder_id:
                  type: string
                  description: >-
                    Tax ID of the simulated sender. Use a Chilean tax ID (RUT)
                    in Chile, or a Mexican tax ID (RFC) in Mexico.
                  example: 11.111.111-1
                counterparty_holder_name:
                  type: string
                  description: Name of the simulated sender account holder.
                  example: Test Customer 1
              required:
                - account_number_id
                - amount
                - currency
        required: true
      responses:
        '201':
          description: The simulated inbound transfer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/transfer'
        '400':
          description: 'Invalid request: a body parameter is missing or invalid.'
          content:
            application/json:
              examples:
                invalid_amount:
                  value:
                    error:
                      type: invalid_request_error
                      code: invalid_request
                      message: Amount must be greater than 0
              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'
      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

````