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

# Iniciar uma Transferência Pix

> Use este endpoint para iniciar um cash-out Pix criando um registro de
iniciação. Este endpoint recupera e valida as informações de destino
sem movimentar fundos.


**Notas:**

- Este endpoint suporta três tipos de iniciação: MANUAL (dados completos
da conta), KEY (usando uma chave Pix) e QR_CODE (usando um QR Code).

- Para a iniciação KEY, o plugin consulta o serviço DICT para recuperar
as informações da conta de destino.

- Para a iniciação QR_CODE, o plugin decodifica o QR Code e consulta o
serviço DICT para recuperar as informações da conta de destino.

- A iniciação não movimenta fundos - ela apenas valida e prepara
a transferência.

- Após a iniciação bem-sucedida, use o endpoint Process para concluir a
transferência.



## OpenAPI

````yaml pt/openapi/v3-current/indirect-pix.yaml POST /v1/transfers/cashout/initiate
openapi: 3.0.3
info:
  title: Plugin BR Pix Indireto - API Completa
  description: |
    API completa para o sistema brasileiro de pagamentos instantâneos Pix,
    incluindo operações de dicionário de chaves Pix, geração/decodificação de
    QR Code, transações e limites de transações.
  version: 1.0.0
servers:
  - url: https://plugin-pix-indirect.api.lerian.net
security:
  - bearerAuth: []
paths:
  /v1/transfers/cashout/initiate:
    post:
      tags:
        - Transactions API
      summary: Iniciar uma Transferência Pix
      description: |-
        Use este endpoint para iniciar um cash-out Pix criando um registro de
        iniciação. Este endpoint recupera e valida as informações de destino
        sem movimentar fundos.


        **Notas:**

        - Este endpoint suporta três tipos de iniciação: MANUAL (dados completos
        da conta), KEY (usando uma chave Pix) e QR_CODE (usando um QR Code).

        - Para a iniciação KEY, o plugin consulta o serviço DICT para recuperar
        as informações da conta de destino.

        - Para a iniciação QR_CODE, o plugin decodifica o QR Code e consulta o
        serviço DICT para recuperar as informações da conta de destino.

        - A iniciação não movimenta fundos - ela apenas valida e prepara
        a transferência.

        - Após a iniciação bem-sucedida, use o endpoint Process para concluir a
        transferência.
      parameters:
        - $ref: '#/components/parameters/XAccountId'
        - $ref: '#/components/parameters/XIdempotency'
        - $ref: '#/components/parameters/XTTL'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiateTransferInput'
            example:
              type: KEY
              amount: '100.00'
              key: john.doe@example.com
              description: Payment for services
      responses:
        '201':
          description: >-
            Iniciação de cash-out Pix criada com sucesso.


            A resposta inclui o cabeçalho `X-Idempotency-Replayed`.


            Se o valor for false, a transação acabou de ser processada. Se o
            valor for true, a resposta é uma reprodução de uma requisição
            processada anteriormente.


            Consulte [Retentativas e
            idempotência](/en/reference/retries-idempotency) para mais detalhes.
          headers:
            X-Idempotency-Replayed:
              $ref: '#/components/headers/XIdempotencyReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitiateTransferOutput'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorFormat'
              examples:
                ErrorPIX0001:
                  $ref: '#/components/examples/ErrorPIX0001'
                ErrorPIX0003:
                  $ref: '#/components/examples/ErrorPIX0003'
                ErrorPIX0004:
                  $ref: '#/components/examples/ErrorPIX0004'
                ErrorPIX0400:
                  $ref: '#/components/examples/ErrorPIX0400'
                ErrorPIX0401:
                  $ref: '#/components/examples/ErrorPIX0401'
                ErrorPIX0402:
                  $ref: '#/components/examples/ErrorPIX0402'
                ErrorPIX0403:
                  $ref: '#/components/examples/ErrorPIX0403'
                ErrorPIX0406:
                  $ref: '#/components/examples/ErrorPIX0406'
                ErrorPIX0414:
                  $ref: '#/components/examples/ErrorPIX0414'
                ErrorPIX0415:
                  $ref: '#/components/examples/ErrorPIX0415'
                ErrorPIX0416:
                  $ref: '#/components/examples/ErrorPIX0416'
                ErrorPIX0417:
                  $ref: '#/components/examples/ErrorPIX0417'
                ErrorPIX0418:
                  $ref: '#/components/examples/ErrorPIX0418'
                ErrorPIX0450:
                  $ref: '#/components/examples/ErrorPIX0450'
                ErrorPIX0451:
                  $ref: '#/components/examples/ErrorPIX0451'
                ErrorPIX0452:
                  $ref: '#/components/examples/ErrorPIX0452'
                ErrorPIX0453:
                  $ref: '#/components/examples/ErrorPIX0453'
                ErrorPIX0454:
                  $ref: '#/components/examples/ErrorPIX0454'
                ErrorPIX0455:
                  $ref: '#/components/examples/ErrorPIX0455'
                ErrorPIX0456:
                  $ref: '#/components/examples/ErrorPIX0456'
                ErrorPIX0457:
                  $ref: '#/components/examples/ErrorPIX0457'
                ErrorPIX0458:
                  $ref: '#/components/examples/ErrorPIX0458'
                ErrorPIX0459:
                  $ref: '#/components/examples/ErrorPIX0459'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorFormat'
              examples:
                ErrorPIX0431:
                  $ref: '#/components/examples/ErrorPIX0431'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorFormat'
              examples:
                ErrorPIX0430:
                  $ref: '#/components/examples/ErrorPIX0430'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorFormat'
              examples:
                ErrorPIX0000:
                  $ref: '#/components/examples/ErrorPIX0000'
                ErrorPIX0500:
                  $ref: '#/components/examples/ErrorPIX0500'
                ErrorPIX0599:
                  $ref: '#/components/examples/ErrorPIX0599'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorFormat'
              examples:
                ErrorPIX1000:
                  $ref: '#/components/examples/ErrorPIX1000'
                ErrorPIX1007:
                  $ref: '#/components/examples/ErrorPIX1007'
                ErrorPIX1099:
                  $ref: '#/components/examples/ErrorPIX1099'
      deprecated: false
      security:
        - bearerAuth: []
components:
  parameters:
    XAccountId:
      name: X-Account-Id
      in: header
      description: Identificador único da Conta do Ledger Midaz (formato UUID).
      required: true
      example: 019c96a0-0a98-7287-9a31-786e0809c769
      schema:
        type: string
    XIdempotency:
      name: X-Idempotency
      in: header
      description: >-
        Chave de idempotência opcional para repetições seguras. Reutilize o
        mesmo valor apenas ao repetir a mesma operação após um resultado
        desconhecido.


        Consulte [Repetições e idempotência](/en/reference/retries-idempotency)
        para mais detalhes.
      required: false
      schema:
        type: string
    XTTL:
      name: X-TTL
      in: header
      description: >-
        Tempo de vida (time-to-live), em segundos, para o cache da chave de
        idempotência. Define por quanto tempo o sistema lembra de uma requisição
        processada.


        Consulte [Repetições e idempotência](/en/reference/retries-idempotency)
        para mais detalhes.
      required: false
      schema:
        type: integer
  schemas:
    InitiateTransferInput:
      type: object
      required:
        - type
        - amount
      properties:
        type:
          type: string
          description: Tipo de iniciação.
          enum:
            - MANUAL
            - KEY
            - QR_CODE
          example: KEY
        amount:
          type: string
          description: Valor da transferência.
          example: '100.00'
        key:
          type: string
          description: Chave Pix (obrigatória para o tipo KEY).
          example: john.doe@example.com
        emv:
          type: string
          description: Payload EMV do QR Code (obrigatório para o tipo QR_CODE).
        description:
          type: string
          description: Descrição da transferência.
          example: Pagamento por serviços
    InitiateTransferOutput:
      type: object
      properties:
        initiationId:
          type: string
          description: ID de iniciação a ser usado no processamento.
          example: 019c96a0-0c82-7c3d-8dcc-c180868b45c4
        destination:
          type: object
          description: Informações validadas do destino.
    ErrorFormat:
      type: object
      description: A mensagem de erro da resposta.
      required:
        - code
        - title
        - message
      properties:
        code:
          type: string
          description: Um identificador único e estável para o erro.
        title:
          type: string
          description: Um breve resumo do problema.
        message:
          type: string
          description: Orientação detalhada para resolver o erro.
  headers:
    XIdempotencyReplayed:
      description: >-
        Este cabeçalho só está presente quando a resposta é uma repetição em
        cache de uma requisição processada anteriormente. Se o cabeçalho estiver
        ausente, a requisição foi processada como nova. Sempre verifique a
        presença deste cabeçalho para evitar processar a mesma operação duas
        vezes do seu lado.


        Consulte [Repetições e idempotência](/en/reference/retries-idempotency)
        para mais detalhes.
      schema:
        type: boolean
      example: false
  examples:
    ErrorPIX0001:
      summary: Missing Headers in Request
      value:
        code: PIX-0001
        title: Missing Headers in Request
        message: >-
          Your request is missing one or more required header params. Please
          refer to the documentation to ensure all necessary header params are
          included in your request.
    ErrorPIX0003:
      summary: Missing Fields in Request
      value:
        code: PIX-0003
        title: Missing Fields in Request
        message: >-
          Your request is missing one or more required fields. Please refer to
          the documentation to ensure all necessary fields are included in your
          request.
    ErrorPIX0004:
      summary: Invalid Field Values in Request
      value:
        code: PIX-0004
        title: Invalid Field Values in Request
        message: >-
          Your request contains one or more fields with invalid values. Please
          refer to the documentation to verify that all fields have the correct
          values.
    ErrorPIX0400:
      summary: Description Too Long
      value:
        code: PIX-0400
        title: Description Too Long
        message: >-
          The description field exceeds the maximum allowed length of 140
          characters.
    ErrorPIX0401:
      summary: Description Contains HTML
      value:
        code: PIX-0401
        title: Description Contains HTML
        message: The description contains invalid HTML characters.
    ErrorPIX0402:
      summary: Invalid Amount Format
      value:
        code: PIX-0402
        title: Invalid Amount Format
        message: >-
          The amount must be in format 0.00 with exactly 2 decimal places (1-10
          digits before decimal).
    ErrorPIX0403:
      summary: Amount Must Be Positive
      value:
        code: PIX-0403
        title: Amount Must Be Positive
        message: The amount must be greater than zero.
    ErrorPIX0406:
      summary: Intra PSP Not Supported
      value:
        code: PIX-0406
        title: Intra PSP Not Supported
        message: >-
          INTRA PSP transfers (same participant) are not supported. The
          destination bank ISPB cannot be the same as the source PSP.
    ErrorPIX0414:
      summary: Destination Required
      value:
        code: PIX-0414
        title: Destination Required
        message: Destination is required for MANUAL initiation type.
    ErrorPIX0415:
      summary: Invalid Initiation Type
      value:
        code: PIX-0415
        title: Invalid Initiation Type
        message: The initiation type is invalid.
    ErrorPIX0416:
      summary: Key Required
      value:
        code: PIX-0416
        title: Key Required
        message: Key is required for KEY initiation type.
    ErrorPIX0417:
      summary: EMV Required
      value:
        code: PIX-0417
        title: EMV Required
        message: EMV is required for QR_CODE initiation type.
    ErrorPIX0418:
      summary: Invalid Destination
      value:
        code: PIX-0418
        title: Invalid Destination
        message: The destination is invalid for MANUAL initiation type.
    ErrorPIX0450:
      summary: Destination Bank Required
      value:
        code: PIX-0450
        title: Destination Bank Required
        message: The destination bank is required.
    ErrorPIX0451:
      summary: Destination Bank Invalid
      value:
        code: PIX-0451
        title: Destination Bank Invalid
        message: The destination bank must be 8 digits.
    ErrorPIX0452:
      summary: Destination Branch Required
      value:
        code: PIX-0452
        title: Destination Branch Required
        message: The destination branch is required.
    ErrorPIX0453:
      summary: Destination Account Required
      value:
        code: PIX-0453
        title: Destination Account Required
        message: The destination account is required.
    ErrorPIX0454:
      summary: Destination Account Type Invalid
      value:
        code: PIX-0454
        title: Destination Account Type Invalid
        message: The destination account type is invalid.
    ErrorPIX0455:
      summary: Destination Document Required
      value:
        code: PIX-0455
        title: Destination Document Required
        message: The destination document is required.
    ErrorPIX0456:
      summary: Destination Document Invalid
      value:
        code: PIX-0456
        title: Destination Document Invalid
        message: >-
          The destination document is invalid: must be CPF (11 digits) or CNPJ
          (14 digits).
    ErrorPIX0457:
      summary: Destination Name Required
      value:
        code: PIX-0457
        title: Destination Name Required
        message: The destination name is required.
    ErrorPIX0458:
      summary: Destination Person Type Invalid
      value:
        code: PIX-0458
        title: Destination Person Type Invalid
        message: The destination person type is invalid.
    ErrorPIX0459:
      summary: Destination Person Type Mismatch
      value:
        code: PIX-0459
        title: Destination Person Type Mismatch
        message: >-
          Person type does not match document: CPF requires NATURAL_PERSON, CNPJ
          requires LEGAL_PERSON.
    ErrorPIX0431:
      summary: Account Blocked
      value:
        code: PIX-0431
        title: Account Blocked
        message: The account is blocked and cannot perform transactions.
    ErrorPIX0430:
      summary: Account Not Found
      value:
        code: PIX-0430
        title: Account Not Found
        message: The account was not found in ledger.
    ErrorPIX0000:
      summary: Internal Server Error
      value:
        code: PIX-0000
        title: Internal Server Error
        message: The server encountered an unexpected error. Please try again later.
    ErrorPIX0500:
      summary: CRM Connection Error
      value:
        code: PIX-0500
        title: CRM Connection Error
        message: Failed to connect to CRM service.
    ErrorPIX0599:
      summary: CRM Bad Request
      value:
        code: PIX-0599
        title: CRM Bad Request
        message: CRM returned a bad request error.
    ErrorPIX1000:
      summary: Provider Connection Error
      value:
        code: PIX-1000
        title: Provider Connection Error
        message: Failed to connect to provider.
    ErrorPIX1007:
      summary: Provider Internal Error
      value:
        code: PIX-1007
        title: Provider Internal Error
        message: Provider returned an internal error.
    ErrorPIX1099:
      summary: Provider Unmapped Error
      value:
        code: PIX-1099
        title: Provider Unmapped Error
        message: Provider returned an unmapped error.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````