Validate a receiving account synchronously

curl --request POST \
  --url https://api.example.com/v1/webhooks/validates \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "dtHrOp": "2026-06-20T10:00:00Z",
  "pagador": {
    "cpfCnpj": "11144477735",
    "ispb": "12345678",
    "nome": "Jane Doe",
    "nrConta": "1234567",
    "nrAgencia": "0001",
    "tpConta": 0,
    "tpPessoa": 0
  },
  "recebedor": {
    "cpfCnpj": "11144477735",
    "ispb": "12345678",
    "nrConta": "1234567",
    "nrAgencia": "0001",
    "tpConta": 0,
    "tpPessoa": 0
  },
  "valor": 10.5,
  "creditoDevolucao": {
    "codigoDevolucao": "MD06",
    "endToEndIdDevolucao": "E2E-D",
    "endToEndIdOriginal": "E2E-O"
  },
  "creditoOrdemPagamento": {
    "chave": "key@bank.com",
    "endToEndId": "E2E-OP",
    "idConciliacaoRecebedor": "CONC-OP"
  },
  "finalidade": 0,
  "idConciliacaoRecebedor": "CONC-V",
  "infEntreClientes": "note",
  "ispbPss": "12345678",
  "modalidadeAgente": 0,
  "prioridadePagamento": 0,
  "tpIniciacao": 0,
  "tpPrioridadePagamento": 0,
  "vlrDetalhe": [
    {
      "tipo": 0,
      "vlrTarifaDinheiroCompra": 0
    }
  ]
}
'

package main

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

func main() {

	url := "https://api.example.com/v1/webhooks/validates"

	payload := strings.NewReader("{\n  \"dtHrOp\": \"2026-06-20T10:00:00Z\",\n  \"pagador\": {\n    \"cpfCnpj\": \"11144477735\",\n    \"ispb\": \"12345678\",\n    \"nome\": \"Jane Doe\",\n    \"nrConta\": \"1234567\",\n    \"nrAgencia\": \"0001\",\n    \"tpConta\": 0,\n    \"tpPessoa\": 0\n  },\n  \"recebedor\": {\n    \"cpfCnpj\": \"11144477735\",\n    \"ispb\": \"12345678\",\n    \"nrConta\": \"1234567\",\n    \"nrAgencia\": \"0001\",\n    \"tpConta\": 0,\n    \"tpPessoa\": 0\n  },\n  \"valor\": 10.5,\n  \"creditoDevolucao\": {\n    \"codigoDevolucao\": \"MD06\",\n    \"endToEndIdDevolucao\": \"E2E-D\",\n    \"endToEndIdOriginal\": \"E2E-O\"\n  },\n  \"creditoOrdemPagamento\": {\n    \"chave\": \"key@bank.com\",\n    \"endToEndId\": \"E2E-OP\",\n    \"idConciliacaoRecebedor\": \"CONC-OP\"\n  },\n  \"finalidade\": 0,\n  \"idConciliacaoRecebedor\": \"CONC-V\",\n  \"infEntreClientes\": \"note\",\n  \"ispbPss\": \"12345678\",\n  \"modalidadeAgente\": 0,\n  \"prioridadePagamento\": 0,\n  \"tpIniciacao\": 0,\n  \"tpPrioridadePagamento\": 0,\n  \"vlrDetalhe\": [\n    {\n      \"tipo\": 0,\n      \"vlrTarifaDinheiroCompra\": 0\n    }\n  ]\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({
    dtHrOp: '2026-06-20T10:00:00Z',
    pagador: {
      cpfCnpj: '11144477735',
      ispb: '12345678',
      nome: 'Jane Doe',
      nrConta: '1234567',
      nrAgencia: '0001',
      tpConta: 0,
      tpPessoa: 0
    },
    recebedor: {
      cpfCnpj: '11144477735',
      ispb: '12345678',
      nrConta: '1234567',
      nrAgencia: '0001',
      tpConta: 0,
      tpPessoa: 0
    },
    valor: 10.5,
    creditoDevolucao: {
      codigoDevolucao: 'MD06',
      endToEndIdDevolucao: 'E2E-D',
      endToEndIdOriginal: 'E2E-O'
    },
    creditoOrdemPagamento: {chave: 'key@bank.com', endToEndId: 'E2E-OP', idConciliacaoRecebedor: 'CONC-OP'},
    finalidade: 0,
    idConciliacaoRecebedor: 'CONC-V',
    infEntreClientes: 'note',
    ispbPss: '12345678',
    modalidadeAgente: 0,
    prioridadePagamento: 0,
    tpIniciacao: 0,
    tpPrioridadePagamento: 0,
    vlrDetalhe: [{tipo: 0, vlrTarifaDinheiroCompra: 0}]
  })
};

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

import requests

url = "https://api.example.com/v1/webhooks/validates"

payload = {
    "dtHrOp": "2026-06-20T10:00:00Z",
    "pagador": {
        "cpfCnpj": "11144477735",
        "ispb": "12345678",
        "nome": "Jane Doe",
        "nrConta": "1234567",
        "nrAgencia": "0001",
        "tpConta": 0,
        "tpPessoa": 0
    },
    "recebedor": {
        "cpfCnpj": "11144477735",
        "ispb": "12345678",
        "nrConta": "1234567",
        "nrAgencia": "0001",
        "tpConta": 0,
        "tpPessoa": 0
    },
    "valor": 10.5,
    "creditoDevolucao": {
        "codigoDevolucao": "MD06",
        "endToEndIdDevolucao": "E2E-D",
        "endToEndIdOriginal": "E2E-O"
    },
    "creditoOrdemPagamento": {
        "chave": "key@bank.com",
        "endToEndId": "E2E-OP",
        "idConciliacaoRecebedor": "CONC-OP"
    },
    "finalidade": 0,
    "idConciliacaoRecebedor": "CONC-V",
    "infEntreClientes": "note",
    "ispbPss": "12345678",
    "modalidadeAgente": 0,
    "prioridadePagamento": 0,
    "tpIniciacao": 0,
    "tpPrioridadePagamento": 0,
    "vlrDetalhe": [
        {
            "tipo": 0,
            "vlrTarifaDinheiroCompra": 0
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "dtHrValidacao": "2026-06-20T10:00:00Z",
  "resultado": 1,
  "motivo": "AC03",
  "motivoComplemento": "Conta recebedora não encontrada"
}

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

Validate a receiving account synchronously

Pre-checks a receiving account before a payment is sent, and answers the section 9.3.1 envelope . JDPI calls it BEFORE settlement, on behalf of the payer’s PSP, so that a payment that would fail is not sent.

EVERY VALIDATION OUTCOME IS HTTP 200, including a rejection: resultado carries the verdict and motivo the reason. Do not branch on the HTTP status here — a 200 with resultado inválido is a refusal, and treating it as success is the mistake this shape invites. It is read-only: nothing is recorded, no money moves, and calling it twice changes nothing.

The checks run in a fixed order and the FIRST one that decides, decides:

When the payment carries a conciliation id, a QR charge already paid within the last 24 hours is refused as a duplicate (motivo BE17), and so is a payer whose document differs from the one the charge was issued for — but only when that charge was created demanding the payer be validated.
A pagador.ispb identifying Bacen (99999) passes unconditionally.
The account to check is the one on WHICHEVER participant block carries THIS participant’s own ISPB — pagador first, then recebedor. If neither block does, the answer is motivo AC03 (account not found).
That account is then looked up by its account number and its holder document compared: no such account, or a lookup that fails, is AC03; a document that does not match the account’s holder is motivo BE01 (inconsistent data). Otherwise the account is valid.

⚠️ THIS CHECK READS ONLY THIS PARTICIPANT’S OWN CUSTOMER RECORDS. Step 3 is the reason: it selects a block by this participant’s own ISPB, and an INDIRECT participant served by this participant (registered with POST /v1/indirects) has an ISPB of its own, which never equals it. A payment addressed to an indirect participant therefore matches neither block and is answered AC03 here, even though POST /v1/webhooks/cash-ins would register that same credit against that institution’s @pi_{ispb} settlement position. Do NOT read an AC03 from this operation as evidence that a credit to an indirect participant would be refused, and do not use this operation to pre-check indirect destinations.

Refusals, as opposed to verdicts, are only transport-level: 400 PIX-0061 when the body fails schema validation at the edge, and 500 when a record this check has to read is unavailable — in which case nothing was validated and the call can be retried.

POST

webhooks

validates

Validate a receiving account synchronously

curl --request POST \
  --url https://api.example.com/v1/webhooks/validates \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "dtHrOp": "2026-06-20T10:00:00Z",
  "pagador": {
    "cpfCnpj": "11144477735",
    "ispb": "12345678",
    "nome": "Jane Doe",
    "nrConta": "1234567",
    "nrAgencia": "0001",
    "tpConta": 0,
    "tpPessoa": 0
  },
  "recebedor": {
    "cpfCnpj": "11144477735",
    "ispb": "12345678",
    "nrConta": "1234567",
    "nrAgencia": "0001",
    "tpConta": 0,
    "tpPessoa": 0
  },
  "valor": 10.5,
  "creditoDevolucao": {
    "codigoDevolucao": "MD06",
    "endToEndIdDevolucao": "E2E-D",
    "endToEndIdOriginal": "E2E-O"
  },
  "creditoOrdemPagamento": {
    "chave": "key@bank.com",
    "endToEndId": "E2E-OP",
    "idConciliacaoRecebedor": "CONC-OP"
  },
  "finalidade": 0,
  "idConciliacaoRecebedor": "CONC-V",
  "infEntreClientes": "note",
  "ispbPss": "12345678",
  "modalidadeAgente": 0,
  "prioridadePagamento": 0,
  "tpIniciacao": 0,
  "tpPrioridadePagamento": 0,
  "vlrDetalhe": [
    {
      "tipo": 0,
      "vlrTarifaDinheiroCompra": 0
    }
  ]
}
'

package main

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

func main() {

	url := "https://api.example.com/v1/webhooks/validates"

	payload := strings.NewReader("{\n  \"dtHrOp\": \"2026-06-20T10:00:00Z\",\n  \"pagador\": {\n    \"cpfCnpj\": \"11144477735\",\n    \"ispb\": \"12345678\",\n    \"nome\": \"Jane Doe\",\n    \"nrConta\": \"1234567\",\n    \"nrAgencia\": \"0001\",\n    \"tpConta\": 0,\n    \"tpPessoa\": 0\n  },\n  \"recebedor\": {\n    \"cpfCnpj\": \"11144477735\",\n    \"ispb\": \"12345678\",\n    \"nrConta\": \"1234567\",\n    \"nrAgencia\": \"0001\",\n    \"tpConta\": 0,\n    \"tpPessoa\": 0\n  },\n  \"valor\": 10.5,\n  \"creditoDevolucao\": {\n    \"codigoDevolucao\": \"MD06\",\n    \"endToEndIdDevolucao\": \"E2E-D\",\n    \"endToEndIdOriginal\": \"E2E-O\"\n  },\n  \"creditoOrdemPagamento\": {\n    \"chave\": \"key@bank.com\",\n    \"endToEndId\": \"E2E-OP\",\n    \"idConciliacaoRecebedor\": \"CONC-OP\"\n  },\n  \"finalidade\": 0,\n  \"idConciliacaoRecebedor\": \"CONC-V\",\n  \"infEntreClientes\": \"note\",\n  \"ispbPss\": \"12345678\",\n  \"modalidadeAgente\": 0,\n  \"prioridadePagamento\": 0,\n  \"tpIniciacao\": 0,\n  \"tpPrioridadePagamento\": 0,\n  \"vlrDetalhe\": [\n    {\n      \"tipo\": 0,\n      \"vlrTarifaDinheiroCompra\": 0\n    }\n  ]\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({
    dtHrOp: '2026-06-20T10:00:00Z',
    pagador: {
      cpfCnpj: '11144477735',
      ispb: '12345678',
      nome: 'Jane Doe',
      nrConta: '1234567',
      nrAgencia: '0001',
      tpConta: 0,
      tpPessoa: 0
    },
    recebedor: {
      cpfCnpj: '11144477735',
      ispb: '12345678',
      nrConta: '1234567',
      nrAgencia: '0001',
      tpConta: 0,
      tpPessoa: 0
    },
    valor: 10.5,
    creditoDevolucao: {
      codigoDevolucao: 'MD06',
      endToEndIdDevolucao: 'E2E-D',
      endToEndIdOriginal: 'E2E-O'
    },
    creditoOrdemPagamento: {chave: 'key@bank.com', endToEndId: 'E2E-OP', idConciliacaoRecebedor: 'CONC-OP'},
    finalidade: 0,
    idConciliacaoRecebedor: 'CONC-V',
    infEntreClientes: 'note',
    ispbPss: '12345678',
    modalidadeAgente: 0,
    prioridadePagamento: 0,
    tpIniciacao: 0,
    tpPrioridadePagamento: 0,
    vlrDetalhe: [{tipo: 0, vlrTarifaDinheiroCompra: 0}]
  })
};

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

import requests

url = "https://api.example.com/v1/webhooks/validates"

payload = {
    "dtHrOp": "2026-06-20T10:00:00Z",
    "pagador": {
        "cpfCnpj": "11144477735",
        "ispb": "12345678",
        "nome": "Jane Doe",
        "nrConta": "1234567",
        "nrAgencia": "0001",
        "tpConta": 0,
        "tpPessoa": 0
    },
    "recebedor": {
        "cpfCnpj": "11144477735",
        "ispb": "12345678",
        "nrConta": "1234567",
        "nrAgencia": "0001",
        "tpConta": 0,
        "tpPessoa": 0
    },
    "valor": 10.5,
    "creditoDevolucao": {
        "codigoDevolucao": "MD06",
        "endToEndIdDevolucao": "E2E-D",
        "endToEndIdOriginal": "E2E-O"
    },
    "creditoOrdemPagamento": {
        "chave": "key@bank.com",
        "endToEndId": "E2E-OP",
        "idConciliacaoRecebedor": "CONC-OP"
    },
    "finalidade": 0,
    "idConciliacaoRecebedor": "CONC-V",
    "infEntreClientes": "note",
    "ispbPss": "12345678",
    "modalidadeAgente": 0,
    "prioridadePagamento": 0,
    "tpIniciacao": 0,
    "tpPrioridadePagamento": 0,
    "vlrDetalhe": [
        {
            "tipo": 0,
            "vlrTarifaDinheiroCompra": 0
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "dtHrValidacao": "2026-06-20T10:00:00Z",
  "resultado": 1,
  "motivo": "AC03",
  "motivoComplemento": "Conta recebedora não encontrada"
}

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

Body

application/json

dtHrOp

string

required

Operation timestamp (ISO-8601).

Example:

"2026-06-20T10:00:00Z"

pagador

object

required

The payer participant block (ISPB drives Bacen detection).

Show child attributes

recebedor

object

required

The receiver participant block.

Show child attributes

valor

number<double>

required

Amount in reais (a JSON number).

Example:

10.5

creditoDevolucao

object

Optional return-credit block.

Show child attributes

creditoOrdemPagamento

object

Optional payment-order credit block.

Show child attributes

finalidade

integer<int64>

Finality (eFinality).

Example:

0

idConciliacaoRecebedor

string

Recipient conciliation id.

Example:

"CONC-V"

infEntreClientes

string

Free-text inter-client info.

Example:

"note"

ispbPss

string

Saque/troco PSS participant ISPB (a v5.5.0 string).

Example:

"12345678"

modalidadeAgente

integer<int64>

Agent modality (eModalityAgent).

Example:

0

prioridadePagamento

integer<int64>

Payment priority.

Example:

0

tpIniciacao

integer<int64>

Initiation type (eStartupType).

Example:

0

tpPrioridadePagamento

integer<int64>

Payment priority type.

Example:

0

vlrDetalhe

object[] | null

Optional value-detail entries.

Show child attributes

Response

dtHrValidacao

string

required

Validation timestamp (ISO-8601, UTC).

Example:

"2026-06-20T10:00:00Z"

resultado

integer<int64>

required

Validation result (0=Inválido, 1=Válido).

Example:

1

motivo

string

Reason code on an invalid result (BE17/AC03/BE01).

Example:

"AC03"

motivoComplemento

string

Human-readable reason complement on an invalid result.

Example:

"Conta recebedora não encontrada"

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

Validate a receiving account synchronously

Authorizations

Body

Response