> ## 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. # Create a Pix Schedule > Create a single-shot scheduled Pix instruction. The schedule is created with status SCHEDULED and is dispatched automatically as a cashout at its scheduled fire time. **Notes:** - The destination is taken from an existing payment initiation referenced by `initiationId`. Call `POST /v1/transfers/cashout/initiate` first to obtain that id. - Provide a fresh `X-Idempotency` header to guarantee at-most-once creation per account. - `scheduledFor` must be at least 60 seconds in the future and within the 180-day window. - At fire time the schedule always executes as a manual cashout using the captured destination. - Schedules in a terminal state (EXECUTED, FAILED, CANCELLED) are immutable. ## OpenAPI ````yaml en/openapi/v3-current/indirect-pix.yaml POST /v1/schedules 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/schedules: post: tags: - Schedules API summary: Create a Pix Schedule description: >- Create a single-shot scheduled Pix instruction. The schedule is created with status SCHEDULED and is dispatched automatically as a cashout at its scheduled fire time. **Notes:** - The destination is taken from an existing payment initiation referenced by `initiationId`. Call `POST /v1/transfers/cashout/initiate` first to obtain that id. - Provide a fresh `X-Idempotency` header to guarantee at-most-once creation per account. - `scheduledFor` must be at least 60 seconds in the future and within the 180-day window. - At fire time the schedule always executes as a manual cashout using the captured destination. - Schedules in a terminal state (EXECUTED, FAILED, CANCELLED) are immutable. parameters: - $ref: '#/components/parameters/XAccountId' - name: X-Idempotency in: header description: >- Idempotency key (UUID v4 recommended); replays return the cached 201 response. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateScheduleInput' responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/ScheduleOutput' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorFormat' 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 schemas: CreateScheduleInput: properties: amount: description: >- Amount is the transfer amount in BRL with 2 decimal places (e.g. "100.50"). Format and bounds are validated when the schedule fires. example: '100.50' type: string description: description: >- Description is the optional human-readable transfer message: optional, max 140 characters; HTML or script content is rejected. Optional at the Pix / BACEN level (informacoesEntreUsuarios). example: Recurring charge installment 03/12 maxLength: 140 type: string endToEndId: description: >- EndToEndID is the optional caller-minted BACEN end-to-end identifier for the scheduled Pix. It is not header-bound and not required, so generic HTTP callers omit it. Recurring (Pix Automático) callers that mint the cashout end-to-end id up front supply it so the scheduled fire reuses the same identifier. Its format is validated when the payment is processed. example: E1234567820260815060012345678901 type: string initiationId: description: >- InitiationID anchors the schedule to an existing payment initiation that already carries the DICT-validated destination snapshot. The schedule copies that initiation's destination fields and stores the reference as an audit anchor (never reused at fire time). An initiation must exist before creating the schedule. example: 550e8400-e29b-41d4-a716-446655440010 type: string maxAttempts: description: >- MaxAttempts caps the number of fire attempts allowed for this schedule. Pix Automático payer uses 2 (first attempt at 06:00 BRT, INSUFFICIENT_FUNDS retry at 18:00 BRT). Zero or omitted falls back to the service default. example: 2 maximum: 2 minimum: 1 type: integer recurrenceId: description: |- RecurrenceID is a generic correlation anchor that groups multiple schedules created by the same upstream flow (recurring payment, subscription, installment plan, billing cycle, etc.). Optional. The schedule layer does NOT interpret this value — it is opaque metadata echoed back on GET / LIST and on the schedule.* outbound webhooks so the upstream consumer can re-aggregate. Nil for ad-hoc one-off schedules that have no parent group. example: 01988a7c-1234-7abc-8def-111122223333 type: string scheduledFor: description: >- ScheduledFor is the wall-clock fire date in ISO 8601 with timezone. The actual execution moment is resolved from this value plus the service default execution hour (BRT). Recurring callers must set this to >= D-1 of the due date. example: '2026-08-15T00:00:00Z' format: date-time type: string required: - amount - initiationId - scheduledFor type: object ScheduleOutput: properties: accountId: description: AccountID echoes the input AccountID for audit / log correlation. example: 019cf6ef-e418-7ced-80c0-7b9816faa798 type: string amount: description: Amount is the BRL amount with 2 decimal places. example: '100.50' type: string attemptCount: description: AttemptCount is the number of fire attempts made so far. example: 0 type: integer attempts: description: >- Attempts is the chronological list of failed prior fire attempts. The successful attempt is not included here; it is recorded on the schedule itself via its TransferID and EndToEndID. Empty array when no failures have been recorded. items: $ref: '#/components/schemas/ScheduleAttemptOutput' type: array cancelledAt: description: |- CancelledAt is the moment the schedule reached CANCELLED. Absent for non-CANCELLED rows. example: '2026-05-19T09:15:33Z' format: date-time type: string createdAt: description: CreatedAt is the persistence timestamp (ISO 8601 UTC). example: '2026-05-26T12:30:00Z' format: date-time type: string description: description: Description is the optional human-readable transfer message. example: Recurring charge installment 03/12 type: string destination: allOf: - $ref: '#/components/schemas/ScheduleDestination' description: Destination is the destination snapshot captured on the schedule. endToEndId: description: >- EndToEndID is the BACEN end-to-end identifier of the settled transfer (resolved via TransferID). Absent for non-EXECUTED states. example: E1234567820260815060012345678901 type: string executedAt: description: |- ExecutedAt is the moment the schedule reached EXECUTED. Absent for non-EXECUTED rows. example: '2026-08-15T06:00:04Z' format: date-time type: string failedAt: description: >- FailedAt is the moment the schedule reached the terminal FAILED state. Absent for non-FAILED rows. Symmetric with ExecutedAt / CancelledAt. example: '2026-08-15T06:00:04Z' format: date-time type: string failureMessage: description: >- FailureMessage is the free-text (PII-sanitized) human-readable failure description. Absent for non-FAILED rows. type: string failureReason: description: |- FailureReason categorizes a terminal failure. Snapshot of the latest Attempts[] entry's FailureReason. Absent for non-FAILED rows. enum: - INSUFFICIENT_FUNDS - BTG_REJECTED - MIDAZ_REJECTED - VALIDATION_FAILED - SCHEDULE_STALE_TIMEOUT - SCHEDULE_RETRIES_EXHAUSTED example: INSUFFICIENT_FUNDS type: string firedAt: description: >- FiredAt is the most recent dispatch instant. Absent until the schedule starts processing (PROCESSING / EXECUTED / FAILED). example: '2026-08-15T06:00:04Z' format: date-time type: string id: description: ID is the unique schedule identifier (UUID v7, app-generated). example: 01989f9e-6508-79f8-9540-835be49fbd0d type: string initiationId: description: >- InitiationID is the payment initiation referenced at create time (audit anchor). It is never reused at fire time; each fire attempt uses its own initiation, surfaced per attempt as Attempts[].InitiationID. example: 550e8400-e29b-41d4-a716-446655440010 type: string initiationType: description: >- InitiationType records how the destination was captured (MANUAL, KEY, QR_CODE). enum: - MANUAL - KEY - QR_CODE example: MANUAL type: string maxAttempts: description: MaxAttempts is the per-row retry cap accepted at create time. example: 2 type: integer recurrenceId: description: >- RecurrenceID echoes the parent recurrence anchor when the schedule was created from a recurring flow. Empty for direct POST /v1/schedules calls. example: 01988a7c-1234-7abc-8def-111122223333 type: string scheduledFor: description: ScheduledFor is the wall-clock fire moment (ISO 8601 UTC). example: '2026-08-15T09:00:00Z' format: date-time type: string status: description: |- Status is the schedule lifecycle status. Always SCHEDULED on create. Lifecycle: SCHEDULED -> PROCESSING -> EXECUTED | FAILED | CANCELLED. enum: - SCHEDULED - PROCESSING - EXECUTED - FAILED - CANCELLED example: SCHEDULED type: string transferId: description: >- TransferID is the identifier of the settled transfer. Populated only on EXECUTED. example: c8d27e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f type: string updatedAt: description: UpdatedAt is the last status-transition timestamp (ISO 8601 UTC). example: '2026-05-26T12:30:00Z' format: date-time type: string type: object 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. ScheduleAttemptOutput: properties: attemptedAt: description: AttemptedAt is the dispatch instant for this attempt (ISO 8601 UTC). example: '2026-08-15T06:00:02Z' format: date-time type: string endToEndId: description: |- EndToEndID is the BACEN end-to-end identifier of the attempt's SPI message. Co-present with TransferID. example: E1234567820260815060011111111111 type: string failureMessage: description: FailureMessage is the human-readable detail (PII-sanitized). example: 'Midaz error: balance below required (06:00 BRT attempt)' type: string failureReason: description: FailureReason categorizes the failure. enum: - INSUFFICIENT_FUNDS - BTG_REJECTED - MIDAZ_REJECTED - VALIDATION_FAILED - SCHEDULE_STALE_TIMEOUT example: INSUFFICIENT_FUNDS type: string initiationId: description: >- InitiationID is the payment initiation used for this attempt (created at fire time, not the create-time initiation). Absent when the attempt was rejected before a settlement was recorded. example: a1111111-1111-4111-8111-111111111111 type: string transferId: description: >- TransferID is the identifier of the transfer produced by the failed fire. Absent when the cashout was rejected before a settlement was recorded. example: f1a2b3c4-1111-4d5e-9f6a-7b8c9d0e1f23 type: string type: object ScheduleDestination: properties: account: allOf: - $ref: '#/components/schemas/ScheduleDestinationAccount' description: Account holds branch / number / participant ISPB / account type. key: description: >- Key is the Pix key associated with the destination at initiation time, when the user paid via KEY or QR_CODE. Snapshot only — not used at fire time. example: john.doe@example.com type: string owner: allOf: - $ref: '#/components/schemas/ScheduleDestinationOwner' description: |- Owner holds the document, name, and optional trade name of the destination account holder. type: object ScheduleDestinationAccount: properties: branch: description: Branch is the bank branch code (typically 4 digits, leading zeros). example: '0001' type: string number: description: Number is the account number at the destination institution. example: '123456789' type: string participant: description: Participant is the 8-digit ISPB of the destination institution. example: '12345678' type: string type: description: 'Type is the account kind: CACC, SVGS, TRAN, OTHR.' enum: - CACC - SVGS - TRAN - OTHR example: CACC type: string type: object ScheduleDestinationOwner: properties: document: description: Document is the owner's CPF (11 digits) or CNPJ (14 digits). example: '12345678901' type: string name: description: Name is the full name or registered name of the destination owner. example: John Doe type: string tradeName: description: TradeName is the optional business trade name (legal persons only). example: John's Business type: string type: object securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````