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. No money moves; the one thing recorded is step 7’s hold. Asking again for the same order does not change its verdict, but each re-ask that holds the charge records the hold again, so a late re-ask extends that order’s hold.

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

1. When the payment carries a conciliation id, a blank recebedor.cpfCnpj is refused with motivo CH11 and a blank recebedor.ispb with motivo DS04; a QR charge already paid to the same recebedor within the last 24 hours is refused as a duplicate (motivo DUPL); a charge another payment order to the same recebedor at the receiving PSP, by CPF/CNPJ or by account, holds (step 7) is refused with motivo DUPL too, until that order’s credit lands, up to 24 hours; and a payer whose document differs from the one the charge was issued for is refused BE17 — but only when that charge was created demanding the payer be validated.
2. A pagador.ispb identifying Bacen (99999) passes unconditionally.
3. The account to check is the one on the participant block naming an ISPB the client’s catalog serves — recebedor first, the pagador only when the recebedor is not served. If neither block does, the answer is motivo AC03 (account not found).
4. That account is then looked up by its branch and account number and its holder document compared: no such account is AC03; a lookup that could NOT BE COMPLETED is a 500, never a verdict — an unreadable record establishes nothing about the account, and AC03 would tell the payer’s PSP that a live account is absent; a document that does not match the account’s holder is motivo BE01 (inconsistent data).
5. When step 3 chose the recebedor block, that account, by branch and number as the credit resolves it, is then read in the ledger: closed is motivo AC07, blocked or a default balance refusing credits is motivo AC06, and an account the ledger does not hold is AC03; a ledger that could NOT BE READ is a 500, never a verdict. Coordinates naming no account or several, and every other account status, leave the account valid.
6. A devolução (creditoDevolucao) that account would accept is refused with motivo AM09 when its valor exceeds what is left to return of the payment endToEndIdOriginal names: that payment’s amount less every devolução already settled against it, booked or still awaiting its payment’s settlement here. A payment this participant never made is not measured, and a balance that could NOT BE READ is a 500, never a verdict.
7. A payment with a conciliation id that passes every check holds that charge for that recebedor’s CPF/CNPJ and for that receiving account, at the receiving PSP. Of two orders validated at once, on this route or the asynchronous one, exactly one holds it and the other is answered DUPL.

⚠️ THIS CHECK READS ONLY THE CUSTOMER RECORDS OF THE PARTICIPANTS THE CLIENT’S CATALOG SERVES. Step 3 is the reason: an INDIRECT participant served by one of them (registered with POST /v1/indirects) has an ISPB of its own, which the catalog never names. 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 or write is unavailable — in which case nothing was validated and the call can be retried.

POST /v1/webhooks/validates

Validate a receiving account synchronously

cURL

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": "[e-mail]",
    "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
    }
  ]
}
'

200

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

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

200

application/json

OK

dtHrValidacao · string · required

Validation timestamp (aaaa-mm-ddTHH:mm:ss.sssZ, UTC).

Example:

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

resultado · integer<int64> · required

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

Example:

1

motivo · string

Reason code on an invalid result (DUPL/CH11/DS04/BE17/AC03/AC06/AC07/BE01/AM09).

Example:

"AC03"

motivoComplemento · string

Human-readable reason complement on an invalid result.

Example:

"Conta recebedora não encontrada"