> ## 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 (step 1) > Creates a transfer initiation in PENDING state and validates the source account. The amount is supplied at process time. ## OpenAPI ````yaml /pt/openapi/v3-current/pix-lerian-spi.yaml post /transfers/cashout/initiate openapi: 3.1.0 info: contact: name: Lerian Studio url: https://lerian.studio description: Public API for outbound Pix transfers, refunds, and scheduled payments. license: name: Lerian Studio General License title: Pix Lerian — Payments version: 1.2.0 servers: - url: https://api.example.com/spi/v1 description: >- Replace the example host with the URL provided during environment onboarding. security: - BearerAuth: [] tags: - description: Create, list, and retrieve Pix refunds. name: Refunds - name: Scheduled Payments description: Register, list, retrieve, and cancel scheduled Pix payments. - description: Initiate, process, list, and retrieve outbound Pix transfers. name: Transfers - description: >- Register, list, retrieve, and cancel recurring series of scheduled Pix payments. name: Scheduled Payment Recurrences - description: >- Hold the funds of a received Pix in a cautionary block (MED 2.0), return them to the payer, or give them back to the account holder. name: Balance Locks paths: /transfers/cashout/initiate: post: tags: - Transfers summary: Initiate a Pix transfer (step 1) description: >- Creates a transfer initiation in PENDING state and validates the source account. The amount is supplied at process time. operationId: initiateTransfer parameters: - description: >- REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. An identical resend within 1 hour returns the original response, status included, with X-Idempotency-Replayed: true. Reusing the key with a divergent method, URL or body is PIX-0031 @ 412. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Source account UUID in: header name: X-Account-Id required: true schema: description: Source account UUID examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/InitiateTransferBody' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/InitiateTransferOutput' description: Created '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: >- The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0300 title: Bad Request status: 400 detail: Missing or malformed required fields for transfer initiation. code: PIX-0300 schema: $ref: '#/components/schemas/Detail' description: >- Missing, duplicated, or malformed request headers/body fields, an initiation-type mismatch, or an invalid source account (PIX-0001-0003, PIX-0010, PIX-0017, PIX-0300-0302). X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. Route-guard refusals (PIX-0001, PIX-0010) answer in the legacy {code,title,message} envelope too. '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: >- The X-Idempotency header is held by a request still running or whose receipt could not be stored, or was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: >- Refused under this X-Idempotency (PIX-0031): the first request under it is still running (with Retry-After: 1), its receipt could not be stored and the key is held for the hour, or the request differs from the first (method, URL, body or identity header). An earlier request under this key may already have executed. Legacy {code,title,message} envelope, NOT problem+json. '415': content: application/json: example: code: PIX-0016 title: Unsupported Media Type message: >- The request body must be sent with Content-Type: application/json. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: >- The non-empty request body is missing an accepted JSON Content-Type (PIX-0016), answered in the legacy {code,title,message} envelope over application/json, NOT problem+json. '422': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0303 title: Unprocessable Entity status: 422 detail: DICT key lookup returned no results. code: PIX-0303 schema: $ref: '#/components/schemas/Detail' description: >- The DICT key cannot be resolved, the QR Code cannot be decoded, or the source ledger account is blocked (PIX-0303, PIX-0304, PIX-0328). '500': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0000 title: Internal Server Error status: 500 detail: >- The server could not complete the request. Please try again later. code: PIX-0000 schema: $ref: '#/components/schemas/Detail' description: Unexpected server error (PIX-0000). '502': content: application/problem+json: example: type: https://errors.lerian.studio/v1/PIX-0700 title: Bad Gateway status: 502 detail: >- The server could not complete the request. Please try again later. code: PIX-0700 schema: $ref: '#/components/schemas/Detail' description: >- A required upstream service is unavailable (PIX-0700-0702, PIX-0705); PIX-0701 also answers a dynamic QR whose receiver gave no answer on the charge, and the call can be tried again. default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error components: schemas: InitiateTransferBody: additionalProperties: false properties: description: description: >- Free-form payment description. U+0000 is refused (400 PIX-0010); U+FFFE, U+FFFF or U+0001-U+001F other than tab, line feed or carriage return is refused (400 PIX-0003). examples: - Pagamento de aluguel type: string destination: $ref: '#/components/schemas/DestinationReq' description: Manual destination (MANUAL initiation only) emv: description: EMV BR Code payload (QR_CODE initiation only) examples: - >- 00020101021126360014br.gov.bcb.pix0114+5511999998888520400005303986540510.005802BR5913JOAO DA SILVA6008BRASILIA62070503***63045B56 type: string endToEndId: description: >- Optional caller-supplied 32-char BACEN endToEndId (E-prefixed). DICT and QR_CODE only: the key is looked up in DICT under it and the transfer is later sent under the same id; omit it to let SPI generate one, returned as endToEndId. Ignored for MANUAL. examples: - E12345678202605061030abcdef12345 type: string initiationType: description: Resolution strategy for the destination examples: - DICT type: string key: description: DICT key (DICT initiation only) examples: - '+5511999998888' type: string required: - initiationType type: object InitiateTransferOutput: additionalProperties: false properties: amount: examples: - '10.00' type: string createdAt: examples: - '2026-05-06T10:30:00Z' format: date-time type: string description: examples: - Pagamento de aluguel type: string destination: $ref: '#/components/schemas/DestinationOutput' emv: examples: - >- 00020101021126360014br.gov.bcb.pix0114+5511999998888520400005303986540510.005802BR5913JOAO DA SILVA6008BRASILIA62070503***63045B56 type: string endToEndId: examples: - E12345678202605061030abcdef12345 type: string description: >- BACEN end-to-end id fixed at initiate for DICT and QR_CODE: the id the DICT lookup was made under, reused automatically by process as the transfer's id (do not send X-End-To-End-Id at process: it is refused for DICT and QR_CODE). Absent for MANUAL. expiresAt: examples: - '2026-05-06T10:35:00Z' format: date-time type: string id: examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string initiationType: examples: - DICT type: string qrCodeDetails: {} source: $ref: '#/components/schemas/SourceDestination' updatedAt: examples: - '2026-05-06T10:30:00Z' format: date-time type: string required: - id - initiationType - expiresAt - createdAt - updatedAt type: object LegacyErrorEnvelope: additionalProperties: false properties: code: description: PIX-XXXX error code type: string message: description: Human-readable error message type: string title: description: Short error title type: string fields: additionalProperties: type: string description: Per-field detail, keyed by the field or header the refusal names type: object headers: additionalProperties: type: string description: Per-header detail, keyed by the request header the refusal names type: object required: - code - title - message type: object Detail: additionalProperties: true properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object DestinationReq: additionalProperties: false properties: account: $ref: '#/components/schemas/DestinationAccountReq' owner: $ref: '#/components/schemas/DestinationOwnerReq' required: - account - owner type: object DestinationOutput: additionalProperties: false properties: account: $ref: '#/components/schemas/DestinationAccountOutput' key: examples: - '+5511999998888' type: string owner: $ref: '#/components/schemas/DestinationOwnerOutput' required: - account - owner type: object SourceDestination: additionalProperties: false properties: account: $ref: '#/components/schemas/AccountDetails' key: examples: - '+5511999998888' type: string owner: $ref: '#/components/schemas/OwnerDetails' type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object DestinationAccountReq: additionalProperties: false properties: branch: examples: - '0001' type: string number: examples: - '0007654321' type: string participant: examples: - '87654321' type: string type: examples: - CACC type: string required: - branch - number - participant - type type: object DestinationOwnerReq: additionalProperties: false properties: document: examples: - '12345678901' type: string name: examples: - João da Silva type: string tradeName: examples: - Empresa Exemplo LTDA type: string required: - document - name type: object DestinationAccountOutput: additionalProperties: false properties: branch: examples: - '0001' type: string number: examples: - '0007654321' type: string participant: examples: - '87654321' type: string type: examples: - CACC type: string required: - branch - number - participant - type type: object DestinationOwnerOutput: additionalProperties: false properties: document: examples: - '12345678901' type: string name: examples: - João da Silva type: string tradeName: examples: - Empresa Exemplo LTDA type: string type: examples: - NATURAL_PERSON type: string required: - document - name type: object AccountDetails: additionalProperties: false properties: branch: examples: - '0001' type: string number: examples: - '0007654321' type: string participant: examples: - '87654321' type: string type: examples: - CACC type: string required: - branch - number - participant - type type: object OwnerDetails: additionalProperties: false properties: document: examples: - '12345678901' type: string name: examples: - João da Silva type: string tradeName: examples: - Empresa Exemplo LTDA type: string type: examples: - NATURAL_PERSON type: string required: - document - name type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.