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

# Create a new internal transfer request

> Creates a new internal transfer request for the authenticated company or a merchant company.
Internal transfers move money between bank accounts within the same provider.
The transfer will be processed by the provider and status updates will be received via webhooks.
Only organization companies may create internal transfers.
Requires the banking.create permission.




## OpenAPI

````yaml /api-spec.yaml post /v1/banking/internal-transfers
openapi: 3.1.0
info:
  title: Rinne API
  version: 1.0.0
  description: >
    **Rinne API** is a robust payment platform that offers integration with
    multiple payment providers.


    ## Authentication


    The API uses API Key authentication via the `x-api-key` header. Each company
    has a unique key to access resources.


    ## Response Format


    All responses follow a consistent format:

    - **Success**: Returns the requested data directly

    - **Error**: Returns an `error` object with detailed information


    ## Pagination


    Endpoints that return lists support pagination through parameters:

    - `page`: Page number (default: 1)

    - `limit`: Items per page (default: 20, maximum: 100)


    ## Supported Providers


    The API supports multiple payment providers:

    - **Rinne**: Internal provider

    - **Celcoin**: PIX integration and other financial services


    ## Raw Card Data (PCI Endpoints)


    Card credential fields (`card_data.number`, `card_data.cvv`,
    `card_data.network_token`,

    `card_data.cryptogram`, and the 3DS `card.number`) must always be sent
    encrypted —

    values start with the `ev:` prefix. Plaintext values are rejected with

    `400 VALIDATION_ERROR` on every host.


    There are two ways to send encrypted values:

    - **rinne-js**: card forms and wallet buttons (Apple Pay / Google Pay)
    encrypt
      credentials client-side before they leave the browser.
    - **PCI API host**: server-to-server integrations that handle raw card data
    must call
      `https://pci.api.rinne.com.br/core` (sandbox: `https://pci.api-sandbox.rinne.com.br/core`)
      instead of the regular host. This endpoint encrypts `number` and `cvv` in transit
      before the request reaches the API; all other fields pass through unchanged.

    The PCI host serves only transaction creation and 3DS session creation (both
    the

    self and merchant variants); use the regular host for everything else.
  contact:
    name: Rinne API Support
    email: suporte@rinne.com.br
servers:
  - url: https://api-sandbox.rinne.com.br/core
    description: Sandbox
  - url: https://api.rinne.com.br/core
    description: Production
security: []
tags:
  - name: System
    description: System and API health endpoints
  - name: Authentication
    description: User authentication and authorization endpoints
  - name: Management
    description: >-
      Merchant management endpoints - create, list, get specific, overview,
      update
  - name: Transactions
    description: Transaction operations for merchants - create, list, overview, refunds
  - name: Affiliations
    description: Affiliation management for merchants
  - name: Banking
    description: Banking operations for merchants - balance, cashout, statements
  - name: Bank Accounts
    description: Bank account management for merchants
  - name: Pix Keys
    description: PIX key management for merchants
  - name: Company Transactions
    description: Direct transaction management and query endpoints for companies
  - name: Companies
    description: Company management
  - name: Company Affiliations
    description: Payment provider affiliation management
  - name: Company Banking
    description: Company banking endpoints (balance, etc.)
  - name: Company Pix
    description: Company PIX key management
  - name: Company Ledger
    description: Company ledger entry query endpoints
  - name: Ledger
    description: Ledger entry query endpoints (company and merchants)
  - name: Cards
    description: Stored card management (self and merchant)
  - name: Webhooks
    description: Endpoints for receiving webhooks from external providers
  - name: Pricing
    description: Fee and cost policy management for transaction pricing
  - name: Users
    description: User management endpoints
  - name: Roles
    description: Role management endpoints
  - name: Permissions
    description: Permission management endpoints
paths:
  /v1/banking/internal-transfers:
    post:
      tags:
        - Banking
      summary: Create a new internal transfer request
      description: >
        Creates a new internal transfer request for the authenticated company or
        a merchant company.

        Internal transfers move money between bank accounts within the same
        provider.

        The transfer will be processed by the provider and status updates will
        be received via webhooks.

        Only organization companies may create internal transfers.

        Requires the banking.create permission.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInternalTransferRequest'
      responses:
        '201':
          description: Internal transfer created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalTransferResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationErrorResponse'
        '403':
          description: Insufficient permissions to access this resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CreateInternalTransferRequest:
      type: object
      description: Schema for creating a new internal transfer
      required:
        - request_id
        - origin_bank_account_id
        - destination_bank_account_id
        - amount
      properties:
        request_id:
          type: string
          description: Client-generated request ID
          example: req_123456789
        origin_bank_account_id:
          type: string
          format: uuid
          description: ID of the bank account to debit from
          example: 123e4567-e89b-12d3-a456-426614174000
        destination_bank_account_id:
          type: string
          format: uuid
          description: ID of the bank account to credit to
          example: 123e4567-e89b-12d3-a456-426614174001
        amount:
          type: integer
          minimum: 1
          description: Amount to transfer in cents
          example: 10000
        metadata:
          type: object
          additionalProperties: true
          description: Optional metadata object for storing custom key-value pairs
          example:
            custom_field: value
            transfer_reason: settlement
    InternalTransferResponse:
      type: object
      description: Internal transfer response
      required:
        - id
        - request_id
        - external_request_id
        - company_id
        - origin_bank_account_id
        - destination_bank_account_id
        - amount
        - status
        - provider_transfer_id
        - error_message
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
          description: Internal transfer ID
          example: 123e4567-e89b-12d3-a456-426614174000
        request_id:
          type: string
          description: Client-generated request ID
          example: req_123456789
        external_request_id:
          type: string
          format: uuid
          description: External provider request ID
          example: 123e4567-e89b-12d3-a456-426614174000
        company_id:
          type: string
          format: uuid
          description: Company ID
          example: 123e4567-e89b-12d3-a456-426614174000
        origin_bank_account_id:
          type: string
          format: uuid
          description: ID of the bank account to debit from
          example: 123e4567-e89b-12d3-a456-426614174000
        destination_bank_account_id:
          type: string
          format: uuid
          description: ID of the bank account to credit to
          example: 123e4567-e89b-12d3-a456-426614174001
        amount:
          type: integer
          description: Amount to transfer in cents
          example: 10000
        status:
          type: string
          enum:
            - PENDING
            - PROCESSING
            - COMPLETED
            - FAILED
          description: Transfer status
          example: PENDING
        provider_transfer_id:
          type:
            - string
            - 'null'
          description: Provider-specific transfer ID
          example: provider_tx_123456
        error_message:
          type:
            - string
            - 'null'
          description: Error message if transfer failed
          example: Insufficient funds
        metadata:
          type:
            - object
            - 'null'
          nullable: true
          additionalProperties: true
          description: Metadata object for storing custom key-value pairs
          example:
            custom_field: value
            transfer_reason: settlement
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
          example: '2023-01-01T00:00:00.000Z'
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
          example: '2023-01-01T00:00:00.000Z'
    ValidationErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: VALIDATION_ERROR
            message:
              type: string
              example: Validation error
            status:
              type: integer
              example: 400
            details:
              type: object
              properties:
                issues:
                  type: array
                  items:
                    type: object
                    properties:
                      field:
                        type: string
                        example: email
                      type:
                        type: string
                        example: REQUIRED
                      message:
                        type: string
                        example: Field 'email' is required
                      value:
                        anyOf:
                          - type: string
                          - type: number
                          - type: boolean
                        example: invalid_value
                      constraints:
                        type: object
                        example:
                          min: 18
                          max: 120
            path:
              type: string
              example: /companies
            timestamp:
              type: string
              format: date-time
              example: '2023-12-01T10:00:00.000Z'
            requestId:
              type: string
              example: req_123456789
    AuthenticationErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: AUTHENTICATION_ERROR
            message:
              type: string
              example: Authentication required to access this resource
            status:
              type: integer
              example: 401
            details:
              type: object
              properties:
                reason:
                  type: string
                  example: Invalid API key
            path:
              type: string
              example: /companies/me
            timestamp:
              type: string
              format: date-time
              example: '2023-12-01T10:00:00.000Z'
            requestId:
              type: string
              example: req_123456789
    AuthorizationErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: AUTHORIZATION_ERROR
            message:
              type: string
              example: You need 'admin' permissions to access this resource
            status:
              type: integer
              example: 403
            path:
              type: string
              example: /companies
            timestamp:
              type: string
              format: date-time
              example: '2023-12-01T10:00:00.000Z'
            requestId:
              type: string
              example: req_123456789
    InternalServerErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: INTERNAL_SERVER_ERROR
            message:
              type: string
              example: An unexpected error occurred
            status:
              type: integer
              example: 500
            path:
              type: string
              example: /companies
            timestamp:
              type: string
              format: date-time
              example: '2023-12-01T10:00:00.000Z'
            requestId:
              type: string
              example: req_123456789
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Company API key for authentication

````