> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Validate a receiving account synchronously > Pre-checks a receiving account before a payment is sent, and answers the section 9.3.1 envelope {resultado, motivo, motivoComplemento, dtHrValidacao}. 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: 1. 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. 2. A pagador.ispb identifying Bacen (99999) passes unconditionally. 3. 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). 4. 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. ## OpenAPI ````yaml /en/openapi/v3-current/pix.yaml post /v1/webhooks/validates openapi: 3.1.0 info: description: Brazilian PIX Direct (DICT + SPI) plugin API. title: plugin-br-pix-jd version: 1.0.0 servers: [] security: - BearerAuth: [] paths: /v1/webhooks/validates: post: tags: - Webhooks summary: Validate a receiving account synchronously description: >- Pre-checks a receiving account before a payment is sent, and answers the section 9.3.1 envelope {resultado, motivo, motivoComplemento, dtHrValidacao}. 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: 1. 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. 2. A pagador.ispb identifying Bacen (99999) passes unconditionally. 3. 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). 4. 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. operationId: validateWebhookAccount requestBody: content: application/json: schema: $ref: '#/components/schemas/ValidateAccountBody' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/ValidateAccountResponse' description: OK '400': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Bad Request '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Internal Server Error components: schemas: ValidateAccountBody: additionalProperties: true properties: creditoDevolucao: $ref: '#/components/schemas/ReturnCredit' description: Optional return-credit block. creditoOrdemPagamento: $ref: '#/components/schemas/CreditMoneyOrder' description: Optional payment-order credit block. dtHrOp: description: Operation timestamp (ISO-8601). examples: - '2026-06-20T10:00:00Z' type: string finalidade: description: Finality (eFinality). examples: - 0 format: int64 type: integer idConciliacaoRecebedor: description: Recipient conciliation id. examples: - CONC-V type: string infEntreClientes: description: Free-text inter-client info. examples: - note type: string ispbPss: description: Saque/troco PSS participant ISPB (a v5.5.0 string). examples: - '12345678' type: string modalidadeAgente: description: Agent modality (eModalityAgent). examples: - 0 format: int64 type: integer pagador: $ref: '#/components/schemas/PayerBlock' description: The payer participant block (ISPB drives Bacen detection). prioridadePagamento: description: Payment priority. examples: - 0 format: int64 type: integer recebedor: $ref: '#/components/schemas/PayeeBlock' description: The receiver participant block. tpIniciacao: description: Initiation type (eStartupType). examples: - 0 format: int64 type: integer tpPrioridadePagamento: description: Payment priority type. examples: - 0 format: int64 type: integer valor: description: Amount in reais (a JSON number). examples: - 10.5 format: double type: number vlrDetalhe: description: Optional value-detail entries. items: $ref: '#/components/schemas/ValueDetailBlock' type: - array - 'null' required: - pagador - recebedor - dtHrOp - valor type: object ValidateAccountResponse: additionalProperties: false properties: dtHrValidacao: description: Validation timestamp (ISO-8601, UTC). examples: - '2026-06-20T10:00:00Z' type: string motivo: description: Reason code on an invalid result (BE17/AC03/BE01). examples: - AC03 type: string motivoComplemento: description: Human-readable reason complement on an invalid result. examples: - Conta recebedora não encontrada type: string resultado: description: Validation result (0=Inválido, 1=Válido). examples: - 1 format: int64 type: integer required: - resultado - dtHrValidacao type: object Detail: additionalProperties: false properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). examples: - ERR-0001 type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object ReturnCredit: additionalProperties: true properties: codigoDevolucao: description: Return reason code (eRefundCode). examples: - MD06 type: string endToEndIdDevolucao: description: Return end-to-end id. examples: - E2E-D type: string endToEndIdOriginal: description: Original CASH_OUT end-to-end id. examples: - E2E-O type: string type: object CreditMoneyOrder: additionalProperties: true properties: chave: description: The PIX key. examples: - key@bank.com type: string endToEndId: description: Payment-order end-to-end id. examples: - E2E-OP type: string idConciliacaoRecebedor: description: Recipient conciliation id (the 24h duplicate-check key). examples: - CONC-OP type: string type: object PayerBlock: additionalProperties: true properties: cpfCnpj: description: Payer document CPF/CNPJ (a v5.5.0 string). examples: - '11144477735' type: string ispb: description: Payer participant ISPB (a v5.5.0 string). examples: - '12345678' type: string nome: description: Payer name (Obrg=Sim on the pagador block). examples: - Jane Doe type: string nrAgencia: description: Agency/branch number (the participant branch source; Obrg=Nao). examples: - '0001' type: string nrConta: description: Account number (NEVER used as the branch). examples: - '1234567' type: string tpConta: description: >- Account type (eAccountType: 0=checking). §9.3.2 Obrg=Sim, but no code reads it, so it is tolerated-absent. examples: - 0 format: int64 type: integer tpPessoa: description: >- Person type (ePersonType: 0=natural, 1=legal). §9.3.2 Obrg=Sim, but no code reads it, so it is tolerated-absent. examples: - 0 format: int64 type: integer required: - ispb - cpfCnpj - nome - nrConta type: object PayeeBlock: additionalProperties: true properties: cpfCnpj: description: Receiver document CPF/CNPJ (a v5.5.0 string). examples: - '11144477735' type: string ispb: description: Receiver participant ISPB (a v5.5.0 string). examples: - '12345678' type: string nrAgencia: description: Agency/branch number (the participant branch source; Obrg=Nao). examples: - '0001' type: string nrConta: description: Account number (NEVER used as the branch). examples: - '1234567' type: string tpConta: description: >- Account type (eAccountType: 0=checking). §9.3.2 Obrg=Sim, but no code reads it, so it is tolerated-absent. examples: - 0 format: int64 type: integer tpPessoa: description: >- Person type (ePersonType: 0=natural, 1=legal). §9.3.2 Obrg=Sim, but no code reads it, so it is tolerated-absent. examples: - 0 format: int64 type: integer required: - ispb - cpfCnpj - nrConta type: object ValueDetailBlock: additionalProperties: true properties: tipo: description: Value-detail type. examples: - 0 format: int64 type: integer vlrTarifaDinheiroCompra: description: Cash-purchase fee amount (reais). examples: - 0 format: double type: number required: - vlrTarifaDinheiroCompra - tipo type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ````