Cancel a scheduled Pix payment

curl --request POST \
  --url https://api.example.com/spi/v1/scheduled-payments/{schedule_id}/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Idempotency: <x-idempotency>'

package main

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

func main() {

	url := "https://api.example.com/spi/v1/scheduled-payments/{schedule_id}/cancel"

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

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")

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

fetch('https://api.example.com/spi/v1/scheduled-payments/{schedule_id}/cancel', 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/{schedule_id}/cancel"

headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, 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"
  }
}

Cancel a scheduled Pix payment

Cancels a schedule at the payer’s request, accepted right up to the cancellation cut-off recorded on it and refused AT that instant. The deadline compared against is the one photographed when the schedule was created, not whatever the configuration derives today: the deadline the payer was told is the deadline they get. Because the cut-off is strictly before the first settlement window, cancelling and executing can never both be in time. Nothing is released — nothing was held.

POST

scheduled-payments

{schedule_id}

cancel

Cancel a scheduled Pix payment

curl --request POST \
  --url https://api.example.com/spi/v1/scheduled-payments/{schedule_id}/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Idempotency: <x-idempotency>'

package main

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

func main() {

	url := "https://api.example.com/spi/v1/scheduled-payments/{schedule_id}/cancel"

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

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")

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

fetch('https://api.example.com/spi/v1/scheduled-payments/{schedule_id}/cancel', 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/{schedule_id}/cancel"

headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, 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"
  }
}

Autorizações

Authorization

string

header

obrigatório

JWT bearer token issued by the identity provider.

Cabeçalhos

X-Idempotency

string

obrigatório

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

Parâmetros de caminho

schedule_id

string

obrigatório

Schedule identifier.

Exemplo:

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

Resposta

accountId

string

obrigatório

Payer account.

Exemplo:

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

amount

string

obrigatório

Amount to settle, in BRL.

Exemplo:

"150.00"

attempts

object[] | null

obrigatório

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

Show child attributes

cancellationCutoff

string<date-time>

obrigatório

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>

obrigatório

currency

string

obrigatório

Always BRL.

Exemplo:

"BRL"

destination

object

obrigatório

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>

obrigatório

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

string

obrigatório

Schedule identifier.

Exemplo:

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

initiationType

enum<string>

obrigatório

How the destination was resolved.

Opções disponíveis:

MANUAL,

DICT,

QR_CODE

Exemplo:

"DICT"

purpose

enum<string>

obrigatório

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

Opções disponíveis:

IPAY

Exemplo:

"IPAY"

scheduledDate

string<date>

obrigatório

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

Exemplo:

"2026-09-10"

source

object

obrigatório

The payer as photographed at creation.

Show child attributes

status

enum<string>

obrigatório

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.

Opções disponíveis:

PENDING,

EXECUTING,

DISPATCHED_OUTCOME_UNKNOWN,

AWAITING_RETRY,

SETTLED,

CANCELLED,

FAILED

Exemplo:

"PENDING"

updatedAt

string<date-time>

obrigatório

cancelledReason

enum<string>

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

Opções disponíveis:

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.

Exemplo:

"Aluguel de setembro"

transferId

string

The transfer that settled this schedule, once it has.

DICT e chaves Pix

Cobranças e BR Codes

Pagamentos e devoluções

Tratamento de erros

Cancel a scheduled Pix payment

Autorizações

Cabeçalhos

Parâmetros de caminho

Resposta