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"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/spi/v1/scheduled-payments"

	payload := strings.NewReader("{\n  \"accountId\": \"019606a1-3b4c-7d8e-9f01-234567890abc\",\n  \"amount\": \"150.00\",\n  \"initiationType\": \"DICT\",\n  \"scheduledDate\": \"2026-09-10\",\n  \"currency\": \"BRL\",\n  \"description\": \"Aluguel de setembro\",\n  \"purpose\": \"IPAY\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    accountId: '019606a1-3b4c-7d8e-9f01-234567890abc',
    amount: '150.00',
    initiationType: 'DICT',
    scheduledDate: '2026-09-10',
    currency: 'BRL',
    description: 'Aluguel de setembro',
    purpose: 'IPAY'
  })
};

fetch('https://api.example.com/spi/v1/scheduled-payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/spi/v1/scheduled-payments"

payload = {
    "accountId": "019606a1-3b4c-7d8e-9f01-234567890abc",
    "amount": "150.00",
    "initiationType": "DICT",
    "scheduledDate": "2026-09-10",
    "currency": "BRL",
    "description": "Aluguel de setembro",
    "purpose": "IPAY"
}
headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "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>"
}

{
  "code": "PIX-0030",
  "title": "Idempotency Key Required",
  "message": "The X-Idempotency header is required for this operation and must be within the accepted length."
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "PIX-0031",
  "title": "Idempotency Key Conflict",
  "message": "The X-Idempotency header was already used with a different request."
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

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 (RF-07, 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 AND resolved again on the scheduled date, which is what REG-Art.9§5 requires — a key can be reassigned in between.

POST

scheduled-payments

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"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/spi/v1/scheduled-payments"

	payload := strings.NewReader("{\n  \"accountId\": \"019606a1-3b4c-7d8e-9f01-234567890abc\",\n  \"amount\": \"150.00\",\n  \"initiationType\": \"DICT\",\n  \"scheduledDate\": \"2026-09-10\",\n  \"currency\": \"BRL\",\n  \"description\": \"Aluguel de setembro\",\n  \"purpose\": \"IPAY\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    accountId: '019606a1-3b4c-7d8e-9f01-234567890abc',
    amount: '150.00',
    initiationType: 'DICT',
    scheduledDate: '2026-09-10',
    currency: 'BRL',
    description: 'Aluguel de setembro',
    purpose: 'IPAY'
  })
};

fetch('https://api.example.com/spi/v1/scheduled-payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/spi/v1/scheduled-payments"

payload = {
    "accountId": "019606a1-3b4c-7d8e-9f01-234567890abc",
    "amount": "150.00",
    "initiationType": "DICT",
    "scheduledDate": "2026-09-10",
    "currency": "BRL",
    "description": "Aluguel de setembro",
    "purpose": "IPAY"
}
headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "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>"
}

{
  "code": "PIX-0030",
  "title": "Idempotency Key Required",
  "message": "The X-Idempotency header is required for this operation and must be within the accepted length."
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "PIX-0031",
  "title": "Idempotency Key Conflict",
  "message": "The X-Idempotency header was already used with a different request."
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

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 (RF-07).

Example:

"150.00"

initiationType

enum<string>

required

How the destination is resolved. DICT reads the directory and requires payeeKey; MANUAL requires destination. QR_CODE is published but not yet accepted on this route.

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 (RF-16).

Example:

"Aluguel de setembro"

destination

object

The payee's account and owner. Required when initiationType is MANUAL.

Show child attributes

payeeKey

object

The Pix key to resolve. Required when initiationType is DICT.

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"

Response

Created

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 the scheduled date this is compared against a fresh directory answer (REG-Art.9§6), which is why it is stored rather than re-resolved.

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.

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 (RF-16); escaping belongs to whoever renders it.

Example:

"Aluguel de setembro"

transferId

string

The transfer that settled this schedule, once it has.

DICT and Pix keys

Collections and BR Codes

Payments and refunds

Error handling

Register a scheduled Pix payment

Authorizations

Headers

Body

Response