> ## 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. # Initiate a Pix Transfer > Use this endpoint to start a Pix cash-out by creating an initiation record. This endpoint retrieves and validates destination information without moving funds. **Notes:** - This endpoint supports three initiation types: MANUAL (full account data), KEY (using a Pix key), and QR_CODE (using a QR code). - For KEY initiation, the plugin queries the DICT service to retrieve destination account information. - For QR_CODE initiation, the plugin decodes the QR code and queries the DICT service to retrieve destination account information. - The initiation does not move funds - it only validates and prepares the transfer. - After successful initiation, use the Process endpoint to complete the transfer. ## OpenAPI ````yaml en/openapi/v3-current/indirect-pix.yaml POST /v1/transfers/cashout/initiate openapi: 3.0.3 info: title: Plugin BR Pix Indirect - Complete API description: | Complete API for Brazilian Pix instant payment system including Pix key dictionary operations, QR code generation/decoding, transactions and transaction limits. version: 1.7.6 servers: - url: https://plugin-pix-indirect.api.lerian.net security: - bearerAuth: [] paths: /v1/transfers/cashout/initiate: post: tags: - Transactions API summary: Initiate a Pix Transfer description: |- Use this endpoint to start a Pix cash-out by creating an initiation record. This endpoint retrieves and validates destination information without moving funds. **Notes:** - This endpoint supports three initiation types: MANUAL (full account data), KEY (using a Pix key), and QR_CODE (using a QR code). - For KEY initiation, the plugin queries the DICT service to retrieve destination account information. - For QR_CODE initiation, the plugin decodes the QR code and queries the DICT service to retrieve destination account information. - The initiation does not move funds - it only validates and prepares the transfer. - After successful initiation, use the Process endpoint to complete the transfer. parameters: - $ref: '#/components/parameters/XAccountId' - $ref: '#/components/parameters/XIdempotency' - $ref: '#/components/parameters/XTTL' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InitiateTransferInput' examples: KEY: summary: Initiation by Pix key value: initiationType: KEY key: john.doe@example.com QR_CODE: summary: Initiation by QR code (EMV) value: initiationType: QR_CODE emv: 00020126...5802BR5913Fulano... MANUAL: summary: Manual initiation with full destination data value: initiationType: MANUAL destination: account: branch: '0001' number: '123456789' participant: '12345678' type: CACC owner: document: '12345678901' name: John Doe responses: '201': description: >- Pix cash-out initiation created successfully. The response includes the `X-Idempotency-Replayed` header. If the value is false, the transaction was just processed. If the value is true, the response is a replay of a previously processed request. See [Retries and idempotency](/en/reference/retries-idempotency) for more details. 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: Unique identifier of the Midaz Ledger Account (UUID format). required: true example: 019c96a0-0a98-7287-9a31-786e0809c769 schema: type: string XIdempotency: name: X-Idempotency in: header description: >- Optional idempotency key for safe retries. Reuse the same value only when retrying the same operation after an unknown outcome. See [Retries and idempotency](/en/reference/retries-idempotency) for details. required: false schema: type: string XTTL: name: X-TTL in: header description: >- Time-to-live in seconds for the idempotency key cache. Defines how long the system remembers a processed request. See [Retries and idempotency](/en/reference/retries-idempotency) for details. required: false schema: type: integer schemas: InitiateTransferInput: type: object required: - initiationType properties: initiationType: type: string description: |- Type of transfer initiation. Determines which additional field is required: MANUAL requires `destination`, KEY requires `key`, and QR_CODE requires `emv`. enum: - MANUAL - KEY - QR_CODE example: MANUAL destination: allOf: - $ref: '#/components/schemas/DestinationInput' description: Destination account information (required for MANUAL). key: type: string description: >- Pix key value (required for KEY type). Can be a CPF, CNPJ, email, phone, or EVP. example: john.doe@example.com emv: type: string description: QR code EMV payload (required for QR_CODE type). example: 00020126...5802BR5913Fulano... endToEndId: type: string description: >- Optional custom end-to-end ID (32-character alphanumeric string, auto-generated if not provided). example: E1234567820240101000001234567890 InitiateTransferOutput: type: object properties: id: type: string description: >- Unique identifier for this initiation (used as `initiationId` in process). example: 019c96a0-0c82-7c3d-8dcc-c180868b45c4 initiationType: type: string description: Type of initiation. enum: - MANUAL - KEY - QR_CODE example: KEY emv: type: string description: EMV payload from the QR code (only for `QR_CODE` type). example: 00020126...5802BR5913Fulano... endToEndId: type: string description: End-to-end identifier for this transfer. example: E1234567820240101000001234567890 qrCodeDetails: type: object additionalProperties: true description: |- Decoded QR code details (only for `QR_CODE` type). The shape varies by QR type (static, immediate, or due-date collection). destination: $ref: '#/components/schemas/TransferPartyObject' expiresAt: type: string format: date-time description: >- Date-time when the initiation expires and can no longer be processed. example: '2024-01-15T11:00:00Z' createdAt: type: string format: date-time example: '2024-01-15T10:30:00Z' updatedAt: type: string format: date-time example: '2024-01-15T10:30:00Z' ErrorFormat: type: object description: The response message error. required: - code - title - message properties: code: type: string description: A unique, stable identifier for the error. title: type: string description: A brief summary of the issue. message: type: string description: Detailed guidance for resolving the error. DestinationInput: type: object description: Destination account information for MANUAL initiation. required: - account - owner properties: account: type: object description: Destination account details. required: - branch - number - participant - type properties: branch: type: string description: Bank branch code (4 digits, padded with leading zeros). example: '0001' number: type: string description: Account number at the institution. example: '123456789' participant: type: string description: ISPB (bank code) of the participant institution (8 digits). example: '12345678' type: type: string description: Type of account. enum: - CACC - SVGS - TRAN - OTHR example: CACC owner: type: object description: Destination account owner details. required: - document - name properties: document: type: string description: CPF (11 digits) or CNPJ (14 digits) of the account owner. example: '12345678901' name: type: string description: Full name or legal name of the account owner. example: John Doe tradeName: type: string description: Business trade name (optional, for legal persons). example: John's Business TransferPartyObject: type: object description: Account party (source or destination) information. properties: key: type: string description: Pix key (if applicable). example: john.doe@example.com account: type: object description: Account details. properties: branch: type: string description: Bank branch code. example: '0001' number: type: string description: Account number. example: '123456789' participant: type: string description: ISPB of the participant institution (8 digits). example: '12345678' type: type: string description: Account type. enum: - CACC - SVGS - TRAN - OTHR example: CACC owner: type: object description: Owner details. properties: document: type: string description: Identification document (CPF 11 digits or CNPJ 14 digits). example: '12345678901' name: type: string description: Full name or registered name. example: John Doe tradeName: type: string description: Business trade name (optional). example: John's Business type: type: string enum: - NATURAL_PERSON - LEGAL_PERSON description: Owner type. example: NATURAL_PERSON headers: XIdempotencyReplayed: description: >- This header is only present when the response is a cached replay of a previously processed request. If the header is absent, the request was processed as new. Always check for the presence of this header to avoid processing the same operation twice on your side. See [Retries and idempotency](/en/reference/retries-idempotency) for details. 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 ````