Reserve an inbound PIX Automatico debit hold

curl --request POST \
  --url https://api.example.com/v1/pix-automatico/settlements/inbound/block \
  --header 'Authorization: Bearer <token>' \
  --header 'Chave-Idempotencia: <chave-idempotencia>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "codMunIbge": 3550308,
  "cpfCnpj": "11111111111",
  "endToEndId": "E11111111202409181500y6j6mt9l1pi",
  "ispb": "04358798",
  "nrConta": "12345678",
  "tpPessoa": 0,
  "valor": 1500.25,
  "nrAgencia": "1234"
}
'

package main

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

func main() {

	url := "https://api.example.com/v1/pix-automatico/settlements/inbound/block"

	payload := strings.NewReader("{\n  \"codMunIbge\": 3550308,\n  \"cpfCnpj\": \"11111111111\",\n  \"endToEndId\": \"E11111111202409181500y6j6mt9l1pi\",\n  \"ispb\": \"04358798\",\n  \"nrConta\": \"12345678\",\n  \"tpPessoa\": 0,\n  \"valor\": 1500.25,\n  \"nrAgencia\": \"1234\"\n}")

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

	req.Header.Add("Chave-Idempotencia", "<chave-idempotencia>")
	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: {
    'Chave-Idempotencia': '<chave-idempotencia>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    codMunIbge: 3550308,
    cpfCnpj: '11111111111',
    endToEndId: 'E11111111202409181500y6j6mt9l1pi',
    ispb: '04358798',
    nrConta: '12345678',
    tpPessoa: 0,
    valor: 1500.25,
    nrAgencia: '1234'
  })
};

fetch('https://api.example.com/v1/pix-automatico/settlements/inbound/block', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/pix-automatico/settlements/inbound/block"

payload = {
    "codMunIbge": 3550308,
    "cpfCnpj": "11111111111",
    "endToEndId": "E11111111202409181500y6j6mt9l1pi",
    "ispb": "04358798",
    "nrConta": "12345678",
    "tpPessoa": 0,
    "valor": 1500.25,
    "nrAgencia": "1234"
}
headers = {
    "Chave-Idempotencia": "<chave-idempotencia>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "dtHrRespostaSgct": "2024-09-20T04:00:01.001Z",
  "endToEndId": "E11111111202409181500y6j6mt9l1pi",
  "resultado": 1,
  "idOperacaoSgct": "58F752C5-6376-3252-8305-A2DE3A8525D3",
  "motivo": "SGCTPIX001",
  "motivoComplemento": "Cliente nao possui saldo suficiente para o bloqueio solicitado"
}

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

Reserve an inbound PIX Automatico debit hold

Reserves a debit HOLD on the payer’s transactional account for a scheduled PIX Automatico payment (section 5.4.1, the plugin is the SGCT server). JDPI calls this when it begins processing the scheduled payment. The reserve is parameterizable and disabled by default. On insufficient funds the result is returned inline (200) as a resultado=0 outcome with motivo SGCTPIX001, never an HTTP error. A schedule that is still in flight — registered but not yet confirmed by the section 6 situacao stream — is NOT refused: it answers 422 with code PIX-0022 and MUST be re-delivered, and the re-delivery is accepted once the confirmation lands.

POST

pix-automatico

settlements

inbound

block

Reserve an inbound PIX Automatico debit hold

curl --request POST \
  --url https://api.example.com/v1/pix-automatico/settlements/inbound/block \
  --header 'Authorization: Bearer <token>' \
  --header 'Chave-Idempotencia: <chave-idempotencia>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "codMunIbge": 3550308,
  "cpfCnpj": "11111111111",
  "endToEndId": "E11111111202409181500y6j6mt9l1pi",
  "ispb": "04358798",
  "nrConta": "12345678",
  "tpPessoa": 0,
  "valor": 1500.25,
  "nrAgencia": "1234"
}
'

package main

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

func main() {

	url := "https://api.example.com/v1/pix-automatico/settlements/inbound/block"

	payload := strings.NewReader("{\n  \"codMunIbge\": 3550308,\n  \"cpfCnpj\": \"11111111111\",\n  \"endToEndId\": \"E11111111202409181500y6j6mt9l1pi\",\n  \"ispb\": \"04358798\",\n  \"nrConta\": \"12345678\",\n  \"tpPessoa\": 0,\n  \"valor\": 1500.25,\n  \"nrAgencia\": \"1234\"\n}")

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

	req.Header.Add("Chave-Idempotencia", "<chave-idempotencia>")
	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: {
    'Chave-Idempotencia': '<chave-idempotencia>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    codMunIbge: 3550308,
    cpfCnpj: '11111111111',
    endToEndId: 'E11111111202409181500y6j6mt9l1pi',
    ispb: '04358798',
    nrConta: '12345678',
    tpPessoa: 0,
    valor: 1500.25,
    nrAgencia: '1234'
  })
};

fetch('https://api.example.com/v1/pix-automatico/settlements/inbound/block', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/pix-automatico/settlements/inbound/block"

payload = {
    "codMunIbge": 3550308,
    "cpfCnpj": "11111111111",
    "endToEndId": "E11111111202409181500y6j6mt9l1pi",
    "ispb": "04358798",
    "nrConta": "12345678",
    "tpPessoa": 0,
    "valor": 1500.25,
    "nrAgencia": "1234"
}
headers = {
    "Chave-Idempotencia": "<chave-idempotencia>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "dtHrRespostaSgct": "2024-09-20T04:00:01.001Z",
  "endToEndId": "E11111111202409181500y6j6mt9l1pi",
  "resultado": 1,
  "idOperacaoSgct": "58F752C5-6376-3252-8305-A2DE3A8525D3",
  "motivo": "SGCTPIX001",
  "motivoComplemento": "Cliente nao possui saldo suficiente para o bloqueio solicitado"
}

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

Authorization

string

Bearer access token (the financial-ingress gate; the handler fails closed with PIX-0082 when absent).

Example:

"Bearer eyJ..."

Chave-Idempotencia

string

required

Idempotency key (= the endToEndId of the transaction). Mandatory per section 5.4.

Example:

"E11111111202409181500y6j6mt9l1pi"

Body

application/json

codMunIbge

integer<int64>

required

Payer IBGE municipality code (7 digits).

Example:

3550308

cpfCnpj

string

required

Payer CPF or CNPJ (a v5.5.0 string).

Example:

"11111111111"

endToEndId

string

required

Unique payment-instruction id (32-char).

Example:

"E11111111202409181500y6j6mt9l1pi"

ispb

string

required

Payer participant ISPB (8 digits, a v5.5.0 string).

Example:

"04358798"

nrConta

string

required

Payer account number (nrConta, a string).

Example:

"12345678"

tpPessoa

integer<int64>

required

Payer person type (0=Pessoa Fisica, 1=Pessoa Juridica).

Example:

0

valor

number<double>

required

Reserve amount in reais (a JSON number; the only money field in section 5.4).

Example:

1500.25

nrAgencia

string

Payer branch (nrAgencia, 4 digits, string).

Example:

"1234"

Response

dtHrRespostaSgct

string

required

SGCT response timestamp (UTC).

Example:

"2024-09-20T04:00:01.001Z"

endToEndId

string

required

Unique payment-instruction id (32-char).

Example:

"E11111111202409181500y6j6mt9l1pi"

resultado

integer<int64>

required

Block result (0=Rejeitado, 1=Aceito).

Example:

1

idOperacaoSgct

string

SGCT block-operation id (GUID; present only when resultado=1).

Example:

"58F752C5-6376-3252-8305-A2DE3A8525D3"

motivo

string

Rejection reason (SGCTPIX001=insufficient funds, SGCTPIX999=other; present only when resultado=0).

Example:

"SGCTPIX001"

motivoComplemento

string

Rejection detail (present only when resultado=0).

Example:

"Cliente nao possui saldo suficiente para o bloqueio solicitado"

Key DICT API

Key Claims API

Banks API

Indirect participants API

Transactions API

Transaction Limits API

QR Codes API

Refunds API

Pix Automático · Authorization requests

Pix Automático · Authorization management

Pix Automático · Composite QR codes

Pix Automático · Authorization events

Pix Automático · Schedule events

Pix Automático · Schedules and payment instructions

Pix Automático · Settlement

MED · Refunds

MED · Fraud markers

MED · Infractions

MED · Value recovery

Webhooks API

Error handling

Events

Reserve an inbound PIX Automatico debit hold

Authorizations

Headers

Body

Response