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).

POST /scheduled-payments

Register a scheduled Pix payment

cURL

curl --request POST \
  --url https://api.example.com/spi/v1/scheduled-payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "accountId": "019606a1-3b4c-7d8e-9f01-234567890abc",
  "amount": "150.00",
  "initiationType": "DICT",
  "scheduledDate": "2026-09-10",
  "currency": "BRL",
  "description": "Aluguel de setembro",
  "purpose": "IPAY",
  "emvPayload": "00020101021226900014br.gov.bcb.pix2568qrcodepix.exemplo.com.br/cobv/8f3a1c2d4e5b6f7a8b9c0d1e2f3a4b5c52040000530398654071500.005802BR5919Mercado Central LTDA6008BRASILIA62070503***6304A1B2"
}
'

200

Example

{
  "accountId": "019606a1-3b4c-7d8e-9f01-234567890abc",
  "amount": "150.00",
  "attempts": [
    {
      "attemptNumber": 1,
      "id": "<string>",
      "isLastAttempt": true,
      "startedAt": "2023-11-07T05:31:56Z",
      "endToEndId": "<string>",
      "finishedAt": "2023-11-07T05:31:56Z",
      "outcome": "SETTLED",
      "providerChannel": "PRIMARY"
    }
  ],
  "cancellationCutoff": "2023-11-07T05:31:56Z",
  "createdAt": "2023-11-07T05:31:56Z",
  "currency": "BRL",
  "destination": {
    "accountType": "CACC",
    "ispb": "32074986",
    "name": "Ana Souza",
    "personType": "NATURAL_PERSON",
    "taxId": "39053344705",
    "accountNumber": "123456",
    "branch": "0001"
  },
  "firstWindowOpensAt": "2023-11-07T05:31:56Z",
  "id": "019606a1-3b4c-7d8e-9f01-234567890abc",
  "initiationType": "DICT",
  "purpose": "IPAY",
  "scheduledDate": "2026-09-10",
  "source": {
    "accountType": "CACC",
    "ispb": "32074986",
    "name": "Ana Souza",
    "personType": "NATURAL_PERSON",
    "taxId": "39053344705",
    "accountNumber": "123456",
    "branch": "0001"
  },
  "status": "PENDING",
  "updatedAt": "2023-11-07T05:31:56Z",
  "cancelledReason": "USER_REQUEST",
  "description": "Aluguel de setembro",
  "transferId": "<string>"
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Headers

X-Idempotency · string · required

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.

Required string length: 1 - 64

Body

application/json

accountId · string · required

Payer account UUID.

Example:

"019606a1-3b4c-7d8e-9f01-234567890abc"

amount · string · required

Amount to settle, in BRL with two decimals. The available balance is NOT touched at creation.

Example:

"150.00"

initiationType · enum<string> · required

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).

Available options: MANUAL, DICT, QR_CODE

Example:

"DICT"

scheduledDate · string<date> · required

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.

Example:

"2026-09-10"

currency · enum<string>

Always BRL. Present for forward compatibility only.

Available options: BRL

Example:

"BRL"

description · string

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.

Example:

"Aluguel de setembro"

destination · object

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).

Show child attributes

payeeKey · object

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).

Show child attributes

purpose · enum<string>

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.

Available options: IPAY

Example:

"IPAY"

emvPayload · string

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.

Example:

"00020101021226900014br.gov.bcb.pix2568qrcodepix.exemplo.com.br/cobv/8f3a1c2d4e5b6f7a8b9c0d1e2f3a4b5c52040000530398654071500.005802BR5919Mercado Central LTDA6008BRASILIA62070503***6304A1B2"

Response

200

application/json

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.

accountId · string · required

Payer account.

Example:

"019606a1-3b4c-7d8e-9f01-234567890abc"

amount · string · required

Amount to settle, in BRL.

Example:

"150.00"

attempts · object[] | null · required

Every attempt of the scheduled day, oldest first. Empty before that date, and never null.

Show child attributes

cancellationCutoff · string<date-time> · required

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.

createdAt · string<date-time> · required

currency · string · required

Always BRL.

Example:

"BRL"

destination · object · required

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.

Show child attributes

firstWindowOpensAt · string<date-time> · required

When the first settlement window of the scheduled date opens (IN 513 art. 12 caput). Photographed at creation.

id · string · required

Schedule identifier.

Example:

"019606a1-3b4c-7d8e-9f01-234567890abc"

initiationType · enum<string> · required

How the destination was resolved.

Available options: MANUAL, DICT, QR_CODE

Example:

"DICT"

purpose · enum<string> · required

Always IPAY: REG-Art.11-P prohibits scheduling any other purpose.

Available options: IPAY

Example:

"IPAY"

scheduledDate · string<date> · required

Civil settlement date in AAAA-MM-DD, in America/Sao_Paulo.

Example:

"2026-09-10"

source · object · required

The payer as photographed at creation.

Show child attributes

status · enum<string> · required

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.

Available options: PENDING, EXECUTING, DISPATCHED_OUTCOME_UNKNOWN, AWAITING_RETRY, SETTLED, CANCELLED, FAILED

Example:

"PENDING"

updatedAt · string<date-time> · required

cancelledReason · enum<string>

Present exactly when status is CANCELLED. A cancellation the payer asked for and one the domain performed are deliberately distinguishable.

Available options: USER_REQUEST, OWNERSHIP_MISMATCH, KEY_NOT_FOUND, RECURRENCE_CANCELLED

description · string

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.

Example:

"Aluguel de setembro"

transferId · string

The transfer that settled this schedule, once it has.