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

Autorizaciones

Authorization

string

header

requerido

JWT bearer token issued by the identity provider.

Encabezados

X-Idempotency

string

requerido

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

Cuerpo

application/json

accountId

string

requerido

Payer account UUID.

Ejemplo:

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

amount

string

requerido

Amount to settle, in BRL with two decimals. The available balance is NOT touched at creation (RF-07).

Ejemplo:

"150.00"

initiationType

enum<string>

requerido

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.

Opciones disponibles:

MANUAL,

DICT,

QR_CODE

Ejemplo:

"DICT"

scheduledDate

string<date>

requerido

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.

Ejemplo:

"2026-09-10"

currency

enum<string>

Always BRL. Present for forward compatibility only.

Opciones disponibles:

BRL

Ejemplo:

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

Ejemplo:

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

Opciones disponibles:

IPAY

Ejemplo:

"IPAY"

Respuesta

Created

accountId

string

requerido

Payer account.

Ejemplo:

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

amount

string

requerido

Amount to settle, in BRL.

Ejemplo:

"150.00"

attempts

object[] | null

requerido

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

Show child attributes

cancellationCutoff

string<date-time>

requerido

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>

requerido

currency

string

requerido

Always BRL.

Ejemplo:

"BRL"

destination

object

requerido

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>

requerido

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

string

requerido

Schedule identifier.

Ejemplo:

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

initiationType

enum<string>

requerido

How the destination was resolved.

Opciones disponibles:

MANUAL,

DICT,

QR_CODE

Ejemplo:

"DICT"

purpose

enum<string>

requerido

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

Opciones disponibles:

IPAY

Ejemplo:

"IPAY"

scheduledDate

string<date>

requerido

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

Ejemplo:

"2026-09-10"

source

object

requerido

The payer as photographed at creation.

Show child attributes

status

enum<string>

requerido

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.

Opciones disponibles:

PENDING,

EXECUTING,

DISPATCHED_OUTCOME_UNKNOWN,

AWAITING_RETRY,

SETTLED,

CANCELLED,

FAILED

Ejemplo:

"PENDING"

updatedAt

string<date-time>

requerido

cancelledReason

enum<string>

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

Opciones disponibles:

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.

Ejemplo:

"Aluguel de setembro"

transferId

string

The transfer that settled this schedule, once it has.

DICT y claves Pix

Cobros y códigos BR

Pagos y devoluciones

Manejo de errores

Register a scheduled Pix payment

Autorizaciones

Encabezados

Cuerpo

Respuesta