> ## 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. # Register a scheduled Pix payment > Registers a Pix payment for a future civil date, evaluated in America/Sao_Paulo. The available balance is NOT touched here (REG-Art.9 caput): nothing moves until the scheduled date, when the order is sent inside the settlement window IN 513 art. 12 fixes. Non-business days are accepted, because Pix settles every day. Pix Saque (OTHR) and Pix Troco (GSCB) are refused at creation rather than on the scheduled date: REG-Art.11-P prohibits scheduling them, and the rule is knowable now. The payee is photographed at creation. On a DICT schedule the key is resolved again on the scheduled date and compared against that photograph, which is what REG-Art.9§5 requires -- a key can be reassigned in between. A MANUAL or QR_CODE schedule is not looked up again: it is sent to the payee photographed at creation. A schedule can also be born from a BR Code: send initiationType QR_CODE with the emvPayload, including a due-date collection code, and the payee is resolved from the key the code carries. The txId it names and the payload itself are recorded with the schedule and shown on its receipt. The scheduled date you send is the one that is used -- it is NOT checked against the collection's own due date. Send only the block your initiationType reads -- payeeKey for DICT, destination for MANUAL, emvPayload for QR_CODE. The blocks are mutually exclusive: a body carrying another type's block is refused rather than resolved from one of them: a well-formed block with 422 PIX-0751; one with a missing field by request validation first (400 PIX-0002), and one with an invalid field likewise (400 PIX-0003). ## OpenAPI ````yaml /en/openapi/v3-current/pix-lerian-spi.yaml post /scheduled-payments 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.1.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 paths: /scheduled-payments: post: tags: - Scheduled Payments summary: Register a scheduled Pix payment description: >- Registers a Pix payment for a future civil date, evaluated in America/Sao_Paulo. The available balance is NOT touched here (REG-Art.9 caput): nothing moves until the scheduled date, when the order is sent inside the settlement window IN 513 art. 12 fixes. Non-business days are accepted, because Pix settles every day. Pix Saque (OTHR) and Pix Troco (GSCB) are refused at creation rather than on the scheduled date: REG-Art.11-P prohibits scheduling them, and the rule is knowable now. The payee is photographed at creation. On a DICT schedule the key is resolved again on the scheduled date and compared against that photograph, which is what REG-Art.9§5 requires -- a key can be reassigned in between. A MANUAL or QR_CODE schedule is not looked up again: it is sent to the payee photographed at creation. A schedule can also be born from a BR Code: send initiationType QR_CODE with the emvPayload, including a due-date collection code, and the payee is resolved from the key the code carries. The txId it names and the payload itself are recorded with the schedule and shown on its receipt. The scheduled date you send is the one that is used -- it is NOT checked against the collection's own due date. Send only the block your initiationType reads -- payeeKey for DICT, destination for MANUAL, emvPayload for QR_CODE. The blocks are mutually exclusive: a body carrying another type's block is refused rather than resolved from one of them: a well-formed block with 422 PIX-0751; one with a missing field by request validation first (400 PIX-0002), and one with an invalid field likewise (400 PIX-0003). operationId: createScheduledPayment 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. Replaying the same 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 requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateScheduledPaymentBody' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/ScheduledPaymentView' description: >- Idempotent replay: the same X-Idempotency key was sent with the same request, so the original creation's response is returned unchanged. The schedule was NOT created a second time. '201': content: application/json: schema: $ref: '#/components/schemas/ScheduledPaymentView' description: Created '400': content: application/json: schema: $ref: '#/components/schemas/LegacyErrorEnvelope' examples: idempotencyGate: summary: Idempotency gate refusal value: code: PIX-0030 title: Idempotency Key Required message: >- The X-Idempotency header is required for this operation and must be within the accepted length. undecodableBody: summary: >- PIX-0010 -- the body is not decodable as this operation's JSON value: code: PIX-0010 title: Client Error message: >- The request could not be processed due to a client-side error. application/problem+json: examples: invalidFieldValues: summary: PIX-0003 -- a field fails its validation rule value: type: https://errors.lerian.studio/v1/PIX-0003 title: Bad Request status: 400 detail: >- Your request contains one or more fields with an invalid data type. errors: - message: scheduledDate does not match the 2006-01-02 format location: scheduledDate code: PIX-0003 missingFields: summary: PIX-0002 -- a required field is missing value: type: https://errors.lerian.studio/v1/PIX-0002 title: Bad Request status: 400 detail: Your request is missing one or more required fields. errors: - message: payeeKey.keyType is a required field location: payeeKey.keyType - message: payeeKey.keyValue is a required field location: payeeKey.keyValue code: PIX-0002 schema: $ref: '#/components/schemas/Detail' description: >- Two shapes share this status, one per media type. application/problem+json is request validation, which refused the body before any rule of this operation was read, with errors[] naming each field: PIX-0002 a required field is missing -- what an incomplete payee block of either type answers; PIX-0003 a field fails its rule (enum, format, check digits, length) -- what a complete payee block with an invalid field answers. application/json is the legacy {code,title,message} envelope, for refusals that answer before validation runs: PIX-0010 the body is not decodable as this operation's JSON -- malformed, or a field of the wrong JSON type, such as a string where the payeeKey object belongs; and, from the idempotency gate: X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. '404': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- The payer account does not resolve to an account visible to the caller (PIX-0750). '409': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- This organization already created a scheduled payment under the same X-Idempotency key (PIX-0756). Nothing was created and nothing was charged by THIS request; the earlier schedule stands -- find it with GET /scheduled-payments filtered by account and settlement date. Which status you get depends on how long ago the first request was. While the replay record lives, an identical retry replays the original response at 200 and a divergent one is refused with PIX-0031 @ 412. Once that record is gone -- it expires, and it is absent entirely during a cache outage -- any retry of an already-used key answers this 409 instead. IMPORTANT: the key is consumed PERMANENTLY for this organization. Unlike the replay record, the durable constraint behind this status never expires. Send a fresh key for each distinct creation -- a UUID per intent is the safe pattern -- and reuse a key only to retry the creation it already identified. Do not recycle keys from a counter or a per-invoice reference that repeats across cycles. PIX-0124 is the other 409, and it is not about the key header: the payee key (for a QR_CODE schedule, the key the BR Code carries) is registered to the PAYER's own account, and a payer cannot schedule a payment to their own key. Nothing was created; do not retry. '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: >- The X-Idempotency header was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: >- X-Idempotency replayed with a divergent request -- a different method, URL (including the path parameter) or body (PIX-0031). Legacy {code,title,message} envelope, NOT problem+json. '422': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' examples: foreignBlock: summary: >- PIX-0751 -- a block another initiation type reads is present; remove it value: type: https://errors.lerian.studio/v1/PIX-0751 title: Unprocessable Entity status: 422 detail: >- The payload does not fit the declared initiation type: a field that type requires is missing or invalid, or a field that only another initiation type reads is present. errors: - message: >- destination is not allowed when initiationType is DICT: the payee is resolved from payeeKey location: destination code: PIX-0751 missingBlock: summary: >- PIX-0751 with no errors -- most often the block the initiation type requires is absent; supply it. The same bare body also answers a zero amount. value: type: https://errors.lerian.studio/v1/PIX-0751 title: Unprocessable Entity status: 422 detail: >- The payload does not fit the declared initiation type: a field that type requires is missing or invalid, or a field that only another initiation type reads is present. code: PIX-0751 description: >- The request is well formed and cannot be accepted. Read the code, not the status: PIX-0751 the payload lacks the block its initiationType requires -- supply it; this refusal carries no field detail -- or carries a block another initiationType reads -- a destination on DICT, a payeeKey on MANUAL, a payeeKey or destination on QR_CODE, an emvPayload on anything but QR_CODE -- in which case errors names each such field; remove each; PIX-0752 the date is already past in America/Sao_Paulo; PIX-0754 the date is beyond the horizon this participant configured; PIX-0755 the directory has no entry for the payee key -- for a QR_CODE schedule that is the key the BR Code carries; PIX-0304 the emvPayload was read and refused as a BR Code. '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Internal Server Error '502': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- An upstream directory could not answer, so the schedule was NOT created and nothing was charged; retrying is safe. PIX-0701: COB Hub could not be reached to decode the emvPayload -- only a QR_CODE creation can answer this. PIX-0700: DICT Hub could not resolve the payee key (unreachable, a server error, or any answer that says nothing about the key) -- a DICT or QR_CODE creation can answer this. default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error components: schemas: CreateScheduledPaymentBody: additionalProperties: false properties: accountId: description: Payer account UUID. examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string amount: description: >- Amount to settle, in BRL with two decimals. The available balance is NOT touched at creation. examples: - '150.00' type: string currency: description: Always BRL. Present for forward compatibility only. enum: - BRL examples: - BRL type: string description: description: >- Free-text memo, at most 140 characters -- the RmtInf ceiling. Stored and returned VERBATIM: markup is not interpreted, escaped or stripped, and escaping belongs to whoever renders it. examples: - Aluguel de setembro type: string destination: $ref: '#/components/schemas/DestinationBody' description: >- The payee's account and owner. Required when initiationType is MANUAL; refused on DICT and QR_CODE (422 PIX-0751; first 400 PIX-0002 if a field of it is missing, 400 PIX-0003 if one is invalid). initiationType: description: >- How the destination is resolved. DICT reads the directory and requires payeeKey; MANUAL requires destination; QR_CODE requires emvPayload and resolves the payee from the key the BR Code carries. Each type reads only its own block: a payeeKey, destination or emvPayload sent on a type that does not read it is refused rather than ignored: well formed with 422 PIX-0751, a block with a missing field by request validation first (400 PIX-0002), one with an invalid field likewise (400 PIX-0003). enum: - MANUAL - DICT - QR_CODE examples: - DICT type: string payeeKey: $ref: '#/components/schemas/PayeeKeyBody' description: >- The Pix key to resolve. Required when initiationType is DICT; refused on MANUAL and QR_CODE (422 PIX-0751; first 400 PIX-0002 if a field of it is missing, 400 PIX-0003 if one is invalid). purpose: description: >- Only IPAY can be scheduled. Pix Saque (OTHR) and Pix Troco (GSCB) are point-in-time operations and REG-Art.11-P prohibits scheduling them, so they are refused at creation rather than on the scheduled date. enum: - IPAY examples: - IPAY type: string scheduledDate: description: >- Civil settlement date in AAAA-MM-DD, evaluated in America/Sao_Paulo. Never an instant: a date that is still today in UTC can already be yesterday here. Non-business days are accepted -- Pix settles every day. examples: - '2026-09-10' format: date type: string emvPayload: description: >- The BR Code the payer scanned or pasted, sent WHOLE and unmodified. Required when initiationType is QR_CODE and rejected on any other type. It is stored verbatim and shown on the receipt: normalising or re-serialising it breaks the CRC-16 the standard embeds, and the receipt would then display a code that pays nobody. A due-date collection BR Code is accepted; the txId it carries is recorded with the schedule. examples: - >- 00020101021226900014br.gov.bcb.pix2568qrcodepix.exemplo.com.br/cobv/8f3a1c2d4e5b6f7a8b9c0d1e2f3a4b5c52040000530398654071500.005802BR5919Mercado Central LTDA6008BRASILIA62070503***6304A1B2 type: string required: - accountId - scheduledDate - amount - initiationType type: object ScheduledPaymentView: additionalProperties: false properties: accountId: description: Payer account. examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string amount: description: Amount to settle, in BRL. examples: - '150.00' type: string attempts: description: >- Every attempt of the scheduled day, oldest first. Empty before that date, and never null. items: $ref: '#/components/schemas/ScheduleAttemptView' type: - array - 'null' cancellationCutoff: description: >- The first instant a cancellation is REFUSED. Cancellation is accepted right up to it and refused AT it, and it is strictly before the first window so the two can never overlap. format: date-time type: string cancelledReason: description: >- Present exactly when status is CANCELLED. A cancellation the payer asked for and one the domain performed are deliberately distinguishable. enum: - USER_REQUEST - OWNERSHIP_MISMATCH - KEY_NOT_FOUND - RECURRENCE_CANCELLED type: string createdAt: format: date-time type: string currency: description: Always BRL. examples: - BRL type: string description: description: >- The payer's memo, returned exactly as it was stored. Markup is not interpreted here and was not escaped on the way in; escaping belongs to whoever renders it. examples: - Aluguel de setembro type: string destination: $ref: '#/components/schemas/ParticipantView' description: >- The payee as photographed at creation. On a DICT schedule it is compared on the scheduled date against a fresh directory answer (REG-Art.9§6), which is why it is stored rather than re-resolved; a MANUAL or QR_CODE schedule is sent to it as photographed, with no second lookup. firstWindowOpensAt: description: >- When the first settlement window of the scheduled date opens (IN 513 art. 12 caput). Photographed at creation. format: date-time type: string id: description: Schedule identifier. examples: - 019606a1-3b4c-7d8e-9f01-234567890abc type: string initiationType: description: How the destination was resolved. enum: - MANUAL - DICT - QR_CODE examples: - DICT type: string purpose: description: 'Always IPAY: REG-Art.11-P prohibits scheduling any other purpose.' enum: - IPAY examples: - IPAY type: string scheduledDate: description: Civil settlement date in AAAA-MM-DD, in America/Sao_Paulo. examples: - '2026-09-10' format: date type: string source: $ref: '#/components/schemas/ParticipantView' description: The payer as photographed at creation. status: description: >- Lifecycle status. DISPATCHED_OUTCOME_UNKNOWN is NOT terminal: the order is awaiting reconciliation and will resolve to SETTLED or FAILED. It does NOT assert that the order reached the rail -- it also covers an order that provably did not, whose reserved funds are still being released. enum: - PENDING - EXECUTING - DISPATCHED_OUTCOME_UNKNOWN - AWAITING_RETRY - SETTLED - CANCELLED - FAILED examples: - PENDING type: string transferId: description: The transfer that settled this schedule, once it has. type: string updatedAt: format: date-time type: string required: - id - accountId - scheduledDate - amount - currency - initiationType - purpose - source - destination - status - firstWindowOpensAt - cancellationCutoff - createdAt - updatedAt - attempts 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 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 DestinationBody: additionalProperties: false properties: account: $ref: '#/components/schemas/DestinationAccountBody' owner: $ref: '#/components/schemas/DestinationOwnerBody' required: - account - owner type: object PayeeKeyBody: additionalProperties: false properties: keyType: description: Kind of Pix key. enum: - EMAIL - PHONE - CPF - CNPJ - EVP examples: - EMAIL type: string keyValue: description: >- The key itself. Resolved at creation to photograph the payee, and resolved AGAIN on the scheduled date: REG-Art.9§5 makes the re-lookup mandatory because a key can be reassigned in between. examples: - joao.pereira@example.com type: string required: - keyType - keyValue type: object ScheduleAttemptView: additionalProperties: false properties: attemptNumber: examples: - 1 format: int64 type: integer endToEndId: description: >- The identifier the attempt dispatched under. Reconciliation of an unknown outcome happens by this value, and it is never minted twice. type: string finishedAt: description: Present exactly when outcome is. format: date-time type: string id: type: string isLastAttempt: description: >- Whether the day's window schedule allowed a further attempt after this one. type: boolean outcome: description: >- How the attempt ended. The two OPERATIONAL_FAILURE members are distinct because only the pre-dispatch one is safe to retry. enum: - SETTLED - INSUFFICIENT_FUNDS - INSUFFICIENT_LIMIT - OWNERSHIP_MISMATCH - KEY_NOT_FOUND - OPERATIONAL_FAILURE_PRE_DISPATCH - OPERATIONAL_FAILURE_POST_DISPATCH type: string providerChannel: description: >- The CSM channel the attempt went out on. UNKNOWN is a real answer from a rail that cannot report one. enum: - PRIMARY - SECONDARY - UNKNOWN type: string startedAt: format: date-time type: string required: - id - attemptNumber - isLastAttempt - startedAt type: object ParticipantView: additionalProperties: false properties: accountNumber: examples: - '123456' type: string accountType: enum: - CACC - SVGS - TRAN - SLRY examples: - CACC type: string branch: examples: - '0001' type: string ispb: description: 8-digit BACEN participant identifier. examples: - '32074986' type: string name: examples: - Ana Souza type: string personType: enum: - NATURAL_PERSON - LEGAL_PERSON examples: - NATURAL_PERSON type: string taxId: description: CPF or CNPJ, digits only. examples: - '39053344705' type: string required: - accountType - ispb - personType - taxId - name 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 DestinationAccountBody: additionalProperties: false properties: branch: description: Branch code at the receiving institution. examples: - '0001' type: string number: description: Account number at the receiving institution. examples: - '654321' type: string participant: description: 8-digit BACEN ISPB of the receiving institution. examples: - '60746948' type: string type: description: >- Account type. SLRY (salary account) is refused by request validation (400 PIX-0003): a salary account cannot receive a Pix, and the rail would refuse it only on the scheduled date. enum: - CACC - SVGS - TRAN examples: - CACC type: string required: - number - participant - type type: object DestinationOwnerBody: additionalProperties: false properties: document: description: >- Payee CPF or CNPJ, digits only. The check digits are verified, and the person type is derived from it. examples: - '11222333000181' type: string name: description: Payee name as it should appear on the receipt. examples: - Mercado Central LTDA 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.