curl --request POST \
  --url https://api.example.com/v1/account-closures \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "account": "0007654321",
  "accountId": "019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b",
  "accountType": 0,
  "branch": "0001",
  "ispb": "12345678"
}
'

package main

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

func main() {

	url := "https://api.example.com/v1/account-closures"

	payload := strings.NewReader("{\n  \"account\": \"0007654321\",\n  \"accountId\": \"019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b\",\n  \"accountType\": 0,\n  \"branch\": \"0001\",\n  \"ispb\": \"12345678\"\n}")

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

	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: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    account: '0007654321',
    accountId: '019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b',
    accountType: 0,
    branch: '0001',
    ispb: '12345678'
  })
};

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

import requests

url = "https://api.example.com/v1/account-closures"

payload = {
    "account": "0007654321",
    "accountId": "019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b",
    "accountType": 0,
    "branch": "0001",
    "ispb": "12345678"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "deletedKeys": [
    {
      "key": "foo@bar.com",
      "reason": 1,
      "result": 1,
      "document": "82437485000140",
      "name": "Empresa de Tal",
      "resultDescription": "Falha de comunicação com DICT"
    }
  ]
}

{
  "code": "<string>",
  "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": "<string>",
  "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": "<string>",
  "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 transactional account closure

Registers the closure of a transactional account at the DICT (JDPI §8.2.04 Encerrar Conta) and, as a consequence, has the DICT DELETE EVERY PIX key bound to that account in one operation. It is a bulk key deletion addressed by ACCOUNT COORDINATES, not by key: you do not name the keys and you cannot select a subset of them.

Call it when the account itself is being closed and has stopped transacting — not to tidy up keys. Deletion at the DICT is not reversible: each key is gone from the national directory, and getting one back means registering it again, which restarts its ownership and can open a claim if another institution took the key meanwhile. To remove ONE key use the entry-deletion route; to sever one holder’s ownership while the account stays open use POST /v1/holder-removals.

⚠️ A 200 does NOT mean every deletion succeeded. The response carries one outcome row per key the DICT attempted, and each row’s result is the verdict: 1 = deleted, 0 = not deleted with resultDescription giving the reason. Only the successes are mirrored into this plugin’s own key projection, so a row with result 0 is still live at the DICT and still needs attention — iterate the rows, do not read the status code alone. The ISPB is resolved server-side from accountId and is never taken from the body; branch, accountType and account identify the account being closed, and a wrong coordinate resolves nothing rather than closing something else.

Refusals: 400 PIX-0061 when accountId or account is empty, or accountType is outside 0..4; 404 PIX-2016 when accountId does not resolve to an account; 400 PIX-1000 when the DICT rejects a field, with the offending fields named in the response; 404 PIX-1011 when the DICT knows no such account or keys; 422 PIX-1007 when the DICT refuses the closure in the account’s current state; 503 PIX-1050 when the DICT is unreachable.

Which of this deployment’s direct participants writes to the national directory is decided by ispb, by exactly the rule an order’s payerIspb follows: this deployment may act as several direct participants, each with its own ISPB and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. A key written under the wrong participant is declared to Bacen by the wrong institution, and there is no undo.

POST

account-closures

curl --request POST \
  --url https://api.example.com/v1/account-closures \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "account": "0007654321",
  "accountId": "019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b",
  "accountType": 0,
  "branch": "0001",
  "ispb": "12345678"
}
'

package main

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

func main() {

	url := "https://api.example.com/v1/account-closures"

	payload := strings.NewReader("{\n  \"account\": \"0007654321\",\n  \"accountId\": \"019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b\",\n  \"accountType\": 0,\n  \"branch\": \"0001\",\n  \"ispb\": \"12345678\"\n}")

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

	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: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    account: '0007654321',
    accountId: '019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b',
    accountType: 0,
    branch: '0001',
    ispb: '12345678'
  })
};

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

import requests

url = "https://api.example.com/v1/account-closures"

payload = {
    "account": "0007654321",
    "accountId": "019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b",
    "accountType": 0,
    "branch": "0001",
    "ispb": "12345678"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "deletedKeys": [
    {
      "key": "foo@bar.com",
      "reason": 1,
      "result": 1,
      "document": "82437485000140",
      "name": "Empresa de Tal",
      "resultDescription": "Falha de comunicação com DICT"
    }
  ]
}

{
  "code": "<string>",
  "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": "<string>",
  "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": "<string>",
  "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.

Corpo

application/json

account

string

obrigatório

The number of the account being closed.

Exemplo:

"0007654321"

accountId

string

obrigatório

The Midaz ledger account id of the caller (resolves the server-side ISPB).

Exemplo:

"019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b"

accountType

integer<int64>

obrigatório

The account type (0=Checking,1=Salary,2=Savings,3=Payment,4=PI).

Exemplo:

0

branch

string

The branch number of the account being closed.

Exemplo:

"0001"

ispb

string

The ISPB of the direct participant this operation acts as. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own DICT credential - and this field is the only thing on the request that says which of them writes to the national directory. OPTIONAL while it acts as a single participant: omit it and that one acts. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. It also selects the DICT credential the call goes out on, so a key registered under the wrong one is declared to Bacen by the wrong institution. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061.

Pattern: ^[0-9A-Z]{8}$

Exemplo:

"12345678"

Resposta

deletedKeys

object[] | null

obrigatório

The per-key deletion outcomes.

Show child attributes

APIs do participante direto

APIs de participantes indiretos

Register a transactional account closure

Autorizações

Corpo

Resposta