> ## 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 una transferencia Pix

> Usa este endpoint para iniciar un cash-out Pix creando un registro de
iniciación. Este endpoint recupera y valida la información de destino
sin mover fondos.


**Notas:**

- Este endpoint admite tres tipos de iniciación: MANUAL (datos completos
de la cuenta), KEY (usando una clave Pix) y QR_CODE (usando un código QR).

- Para la iniciación KEY, el plugin consulta el servicio DICT para recuperar
la información de la cuenta de destino.

- Para la iniciación QR_CODE, el plugin decodifica el código QR y consulta el
servicio DICT para recuperar la información de la cuenta de destino.

- La iniciación no mueve fondos: solo valida y prepara
la transferencia.

- Tras una iniciación exitosa, usa el endpoint Process para completar la
transferencia.



## OpenAPI

````yaml es/openapi/v3-current/indirect-pix.yaml POST /v1/transfers/cashout/initiate
openapi: 3.0.3
info:
  title: Plugin BR Pix Indirect - API completa
  description: |
    API completa para el sistema de pagos instantáneos Pix de Brasil, que
    incluye operaciones del diccionario de claves Pix, generación/decodificación
    de códigos QR, transacciones y límites transaccionales.
  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 una transferencia Pix
      description: >-
        Usa este endpoint para iniciar un cash-out Pix creando un registro de

        iniciación. Este endpoint recupera y valida la información de destino

        sin mover fondos.



        **Notas:**


        - Este endpoint admite tres tipos de iniciación: MANUAL (datos completos

        de la cuenta), KEY (usando una clave Pix) y QR_CODE (usando un código
        QR).


        - Para la iniciación KEY, el plugin consulta el servicio DICT para
        recuperar

        la información de la cuenta de destino.


        - Para la iniciación QR_CODE, el plugin decodifica el código QR y
        consulta el

        servicio DICT para recuperar la información de la cuenta de destino.


        - La iniciación no mueve fondos: solo valida y prepara

        la transferencia.


        - Tras una iniciación exitosa, usa el endpoint Process para completar la

        transferencia.
      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: >-
            Iniciación del cash-out Pix creada correctamente.


            La respuesta incluye el encabezado `X-Idempotency-Replayed`.


            Si el valor es false, la transacción se acaba de procesar. Si el
            valor es true, la respuesta es una repetición de una solicitud
            procesada anteriormente.


            Consulta [Reintentos e
            idempotencia](/en/reference/retries-idempotency) para obtener más
            detalles.
          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 de la cuenta del Ledger de Midaz (formato UUID).
      required: true
      example: 019c96a0-0a98-7287-9a31-786e0809c769
      schema:
        type: string
    XIdempotency:
      name: X-Idempotency
      in: header
      description: >-
        Clave de idempotencia opcional para reintentos seguros. Reutiliza el
        mismo valor solo cuando reintentas la misma operación tras un resultado
        desconocido.


        Consulta [Reintentos e idempotencia](/en/reference/retries-idempotency)
        para más detalles.
      required: false
      schema:
        type: string
    XTTL:
      name: X-TTL
      in: header
      description: >-
        Tiempo de vida en segundos para la caché de la clave de idempotencia.
        Define cuánto tiempo el sistema recuerda una solicitud procesada.


        Consulta [Reintentos e idempotencia](/en/reference/retries-idempotency)
        para más detalles.
      required: false
      schema:
        type: integer
  schemas:
    InitiateTransferInput:
      type: object
      required:
        - type
        - amount
      properties:
        type:
          type: string
          description: Tipo de inicio.
          enum:
            - MANUAL
            - KEY
            - QR_CODE
          example: KEY
        amount:
          type: string
          description: Monto de la transferencia.
          example: '100.00'
        key:
          type: string
          description: Clave Pix (obligatoria para el tipo KEY).
          example: john.doe@example.com
        emv:
          type: string
          description: Payload EMV del código QR (obligatorio para el tipo QR_CODE).
        description:
          type: string
          description: Descripción de la transferencia.
          example: Payment for services
    InitiateTransferOutput:
      type: object
      properties:
        initiationId:
          type: string
          description: ID de inicio que se utilizará en el proceso.
          example: 019c96a0-0c82-7c3d-8dcc-c180868b45c4
        destination:
          type: object
          description: Información validada del destino.
    ErrorFormat:
      type: object
      description: El mensaje de error de la respuesta.
      required:
        - code
        - title
        - message
      properties:
        code:
          type: string
          description: Un identificador único y estable para el error.
        title:
          type: string
          description: Un breve resumen del problema.
        message:
          type: string
          description: Orientación detallada para resolver el error.
  headers:
    XIdempotencyReplayed:
      description: >-
        Este encabezado solo está presente cuando la respuesta es una repetición
        en caché de una solicitud procesada anteriormente. Si el encabezado está
        ausente, la solicitud se procesó como nueva. Verifica siempre la
        presencia de este encabezado para evitar procesar la misma operación dos
        veces por tu lado.


        Consulta [Reintentos e idempotencia](/en/reference/retries-idempotency)
        para más detalles.
      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

````