components: schemas: AccountClosureResponse: additionalProperties: false properties: deletedKeys: description: The per-key deletion outcomes. items: $ref: "#/components/schemas/DeletedKeyView" type: - array - "null" required: - deletedKeys type: object AdditionalDataBody: additionalProperties: false properties: name: description: The additional-data entry name. examples: - order type: string value: description: The additional-data entry value. examples: - "42" type: string required: - name - value type: object AmendRecoveryRequestBody: additionalProperties: false properties: contatoEmail: description: New creator-contact email. examples: - ops@example.com type: string contatoTelefone: description: New creator-contact phone. examples: - "+5511999999999" type: string detalhes: description: New free-text detail; required when tpSituacao=4 (Outros). examples: - Updated detail. type: string idempotencyKey: description: "Client-supplied idempotency key: any stable business string. The plugin projects it deterministically into the GUID form JDPI requires (contract 6), so the same value always dedups against the same JDPI request and the raw value is never sent verbatim." examples: - med-amend-2024-0001 type: string tpSituacao: description: New situation code (0..5). examples: - 4 format: int64 type: integer required: - tpSituacao - idempotencyKey type: object AnalyzeInfractionRequestBody: additionalProperties: false properties: detalhesAnalise: description: Analysis detail. examples: - Confirmed fraud. type: string idempotencyKey: description: "Client-supplied idempotency key: any stable business string. The plugin projects it deterministically into the GUID form JDPI requires (contract 6), so the same value always dedups against the same JDPI request and the raw value is never sent verbatim." examples: - med-infraction-analyze-2024-0001 type: string resultadoAnalise: description: Infraction analysis result (0=Aceita, 1=Rejeitada). examples: - 0 format: int64 type: integer tpFraude: description: Fraud-type code (0..4); required when resultadoAnalise=0 (Aceita). examples: - 1 format: int64 type: integer required: - resultadoAnalise - idempotencyKey type: object AnalyzeRefundRequestBody: additionalProperties: false properties: detalhesAnalise: description: Analysis detail; required when rejecting with motivoRejeicao=4. examples: - Confirmed fraud. type: string endToEndIdDevolucao: description: pacs.004/008 devolucao id; required when resultadoAnalise is 0 or 1. examples: - D1234567820240101000000000000099 type: string idempotencyKey: description: "Client-supplied idempotency key: any stable business string. The plugin projects it deterministically into the GUID form JDPI requires (contract 6), so the same value always dedups against the same JDPI request and the raw value is never sent verbatim." examples: - med-analyze-2024-0001 type: string motivoRejeicao: description: Rejection reason (0,1,3,4); required when resultadoAnalise=2. examples: - 0 format: int64 type: integer resultadoAnalise: description: Analysis result (0=Aceita Totalmente, 1=Aceita Parcialmente, 2=Rejeitada). examples: - 0 format: int64 type: integer valorDevolvido: description: Amount actually refunded, in centavos; required for a partial acceptance. examples: - 10000 format: int64 type: integer required: - resultadoAnalise - idempotencyKey type: object AuthorizationAckResponse: additionalProperties: false properties: idRecorrencia: description: The recurrence id. examples: - RR0435879820240605njua7shf40o type: string idReqJdPi: description: The JDPI request id (36-char GUID; omitted by 4.3.10). examples: - 52c43361-caa1-4ddb-9152-708426a25db3 type: string requestedAt: description: JDPI request timestamp (dtHrReqJdPi, UTC). examples: - "2024-01-06T10:00:01Z" type: string status: description: The resulting local authorization status. examples: - Accepted type: string required: - idRecorrencia - requestedAt type: object AuthorizationCancellationItem: additionalProperties: false properties: cancelStatus: description: stCancelamento (0=Aceito, 1=Rejeitado; -1 when absent). examples: - 0 format: int64 type: integer cancelledAt: description: Cancellation timestamp (UTC). examples: - "2024-02-01T10:00:00Z" type: string errorCode: description: JDPI error code (codigoErro). examples: - "" type: string errorDesc: description: JDPI error description (descCodigoErro). examples: - "" type: string idCancelamento: description: The cancellation id (29-char, IC...). examples: - IC0435879820240605abcd1234567 type: string reason: description: motivoCancelamento (0..10). examples: - 0 format: int64 type: integer requesterDocument: description: Requester CPF/CNPJ (string). examples: - "04623217035" type: string requesterType: description: tpPessoaSol. examples: - 0 format: int64 type: integer required: - idCancelamento - requesterType - requesterDocument - reason - cancelledAt - cancelStatus type: object AuthorizationCancellationSituacaoBody: additionalProperties: true properties: idCancelamento: description: Unique cancellation id (29-char, IC...). examples: - IC0435879820240605bcdb1fhn43a type: string idRecorrencia: description: Unique recurrence id (29-char, RR...). examples: - RR0435879820240605njua7shf40o type: string stCancelamento: description: Cancellation status (0=Aceito, 1=Rejeitado); §4.3.6 OPTIONAL, absent => no-op. examples: - 0 format: int64 type: integer required: - idRecorrencia - idCancelamento type: object AuthorizationDebtorBody: additionalProperties: false properties: cpfCnpj: description: Debtor CPF or CNPJ (string). examples: - "04623217035" type: string name: description: Debtor name. examples: - Ciclano da Silva type: string personType: description: tpPessoa (0=Pessoa Fisica, 1=Pessoa Juridica). examples: - 0 format: int64 type: integer required: - personType - cpfCnpj - name type: object AuthorizationPayerBody: additionalProperties: false properties: account: description: Payer account number (nrConta, string). examples: - "0007654321" type: string agency: description: Payer branch (nrAgencia, 4 digits, string). examples: - "0001" type: string cpfCnpj: description: Payer CPF or CNPJ (string). examples: - "04623217035" type: string ispb: description: Payer participant ISPB (8 digits, string). examples: - "00038166" type: string personType: description: tpPessoa (0=Pessoa Fisica, 1=Pessoa Juridica). examples: - 0 format: int64 type: integer required: - ispb - personType - cpfCnpj - account type: object AuthorizationPayerView: additionalProperties: false properties: account: description: Payer account (string). examples: - "0007654321" type: string accountType: description: tpConta. examples: - 0 format: int64 type: integer agency: description: Payer branch (string). examples: - "0001" type: string cpfCnpj: description: Payer CPF/CNPJ (string). examples: - "04623217035" type: string ibgeCode: description: Municipality IBGE code. examples: - 3550308 format: int64 type: integer ispb: description: Payer participant ISPB (string). examples: - "00038166" type: string name: description: Payer name. examples: - Fulano de Tal type: string personType: description: tpPessoa. examples: - 0 format: int64 type: integer type: object AuthorizationRecipientBody: additionalProperties: false properties: cnpj: description: Recipient CNPJ (14 digits, string). examples: - "61695227000193" type: string ispb: description: Recipient participant ISPB (8 digits, string). examples: - "04358798" type: string name: description: Recipient legal/trade name. examples: - Enel type: string required: - ispb - cnpj - name type: object AuthorizationResponse: additionalProperties: false properties: amount: description: Fixed payment amount in centavos. examples: - 110001 format: int64 type: integer authorizationGiven: description: resultadoAutorizacao. examples: - true type: boolean authorizedAt: description: Authorization timestamp (UTC). examples: - "2024-01-06T10:00:00Z" type: string cancellations: description: Cancellation history (cancelamentos). items: $ref: "#/components/schemas/AuthorizationCancellationItem" type: - array - "null" contractDesc: description: Free-text contract description. examples: - Conta de energia type: string contractNumber: description: Contract/order identifier (nrContrato). examples: - 1234567890ABC type: string debtor: $ref: "#/components/schemas/AuthorizationDebtorBody" description: The recurrence devedor. endDate: description: Last payment date (aaaa-mm-dd). examples: - "2026-01-10" type: string floorMaxAmount: description: Receiver floor in centavos. examples: - 55000 format: int64 type: integer frequency: description: tpFrequencia (0..4). examples: - 1 format: int64 type: integer idRecorrencia: description: The recurrence id. examples: - RR0435879820240605njua7shf40o type: string idReqJdPi: description: The JDPI request id (GUID). examples: - 52c43361-caa1-4ddb-9152-708426a25db3 type: string idSolicitacao: description: The solicitation id (29-char, IS...). examples: - IS0435879820240605abcd1234567 type: string journey: description: jornada (1..4). examples: - 2 format: int64 type: integer localStatus: description: Local AuthorizationStatus projected from the JDPI situation. examples: - Active type: string localStatusKnown: description: False when the JDPI situation carries no projected local status. examples: - true type: boolean payer: $ref: "#/components/schemas/AuthorizationPayerView" description: The recurrence pagador. payerMaxAmount: description: Payer max cap in centavos. examples: - 200000 format: int64 type: integer recipient: $ref: "#/components/schemas/AuthorizationRecipientBody" description: The recurrence recebedor. requestedAt: description: JDPI request timestamp (UTC). examples: - "2024-01-05T10:00:01Z" type: string retry: description: retentativa (0/1). examples: - 1 format: int64 type: integer situationAt: description: Situation timestamp (dtHrSituacao, UTC). examples: - "2024-01-06T10:00:00Z" type: string stJdPi: description: JDPI overall situation (-1/0/9/10). examples: - 9 format: int64 type: integer stJdPiProc: description: JDPI intermediate situation (0..10). examples: - 9 format: int64 type: integer startDate: description: First payment date (aaaa-mm-dd). examples: - "2024-01-10" type: string updatedAt: description: Last-update timestamp (UTC). examples: - "2024-01-06T10:00:00Z" type: string required: - idRecorrencia - stJdPiProc - stJdPi - localStatus - localStatusKnown - authorizationGiven - frequency - startDate - recipient - payer - debtor type: object AuthorizationSituacaoBody: additionalProperties: true properties: idRecorrencia: description: Unique recurrence id (29-char, RR...); the projection's load key. examples: - RR0435879820240605njua7shf40o type: string stJdPi: description: Overall request situation (-1/0/9/10). examples: - 9 format: int64 type: integer stJdPiProc: description: Intermediate processing situation (0..10). examples: - 9 format: int64 type: integer required: - idRecorrencia - stJdPiProc - stJdPi type: object AvailableLimitItem: additionalProperties: false properties: availableAmount: description: The remaining headroom in centavos. examples: - 2950000 format: int64 type: integer limitType: description: eTransactionLimitType name. examples: - PERIOD type: string periodType: description: ePeriodType name. examples: - DAILY type: string totalLimit: description: The configured cap in centavos. examples: - 3000000 format: int64 type: integer usedAmount: description: The period's used amount in centavos. examples: - 50000 format: int64 type: integer required: - limitType - periodType - totalLimit - usedAmount - availableAmount type: object AvailableLimitsResponse: additionalProperties: false properties: currentPeriod: description: The active ePeriodType name. examples: - DAILY type: string limits: description: The per-limit available rows. items: $ref: "#/components/schemas/AvailableLimitItem" type: - array - "null" required: - limits - currentPeriod type: object BankIDItem: additionalProperties: false properties: ispb: description: The participant ISPB (§8.6.1 String(8); leading zeros are significant). examples: - "00000208" type: string name: description: The participant legal name (razão social). examples: - BANCO BRADESCO S.A. type: string required: - ispb - name type: object BankIDsBody: additionalProperties: false properties: data: description: The participating-PSP list, ordered by ISPB as JDPI returns it. items: $ref: "#/components/schemas/BankIDItem" type: - array - "null" required: - data type: object BlockScheduleBody: additionalProperties: true properties: codMunIbge: description: Payer IBGE municipality code (7 digits). examples: - 3550308 format: int64 type: integer cpfCnpj: description: Payer CPF or CNPJ (a v5.5.0 string). examples: - "11111111111" type: string endToEndId: description: Unique payment-instruction id (32-char). examples: - E11111111202409181500y6j6mt9l1pi type: string ispb: description: Payer participant ISPB (8 digits, a v5.5.0 string). examples: - "04358798" type: string nrAgencia: description: Payer branch (nrAgencia, 4 digits, string). examples: - "1234" type: string nrConta: description: Payer account number (nrConta, a string). examples: - "12345678" type: string tpPessoa: description: Payer person type (0=Pessoa Fisica, 1=Pessoa Juridica). examples: - 0 format: int64 type: integer valor: description: Reserve amount in reais (a JSON number; the only money field in section 5.4). examples: - 1500.25 format: double type: number required: - endToEndId - ispb - tpPessoa - cpfCnpj - nrConta - codMunIbge - valor type: object BlockScheduleResponse: additionalProperties: false properties: dtHrRespostaSgct: description: SGCT response timestamp (UTC). examples: - "2024-09-20T04:00:01.001Z" type: string endToEndId: description: Unique payment-instruction id (32-char). examples: - E11111111202409181500y6j6mt9l1pi type: string idOperacaoSgct: description: SGCT block-operation id (GUID; present only when resultado=1). examples: - 58F752C5-6376-3252-8305-A2DE3A8525D3 type: string motivo: description: Rejection reason (SGCTPIX001=insufficient funds, SGCTPIX999=other; present only when resultado=0). examples: - SGCTPIX001 type: string motivoComplemento: description: Rejection detail (present only when resultado=0). examples: - Cliente nao possui saldo suficiente para o bloqueio solicitado type: string resultado: description: Block result (0=Rejeitado, 1=Aceito). examples: - 1 format: int64 type: integer required: - endToEndId - resultado - dtHrRespostaSgct type: object CancelAuthorizationBody: additionalProperties: false properties: reason: description: motivoCancelamento (0..10). examples: - 0 format: int64 type: integer requesterDocument: description: Requester CPF/CNPJ (cpfCnpjSolCancelamento, string). examples: - "04623217035" type: string requesterType: description: tpPessoaSol (0=Pessoa Fisica, 1=Pessoa Juridica). examples: - 0 format: int64 type: integer required: - requesterType - requesterDocument - reason type: object CancelAuthorizationResponse: additionalProperties: false properties: cancelledAt: description: Cancellation timestamp (dtHrCancelamento, UTC). examples: - "2024-02-01T10:00:00Z" type: string idCancelamento: description: The cancellation id (29-char, IC...). examples: - IC0435879820240605abcd1234567 type: string idRecorrencia: description: The recurrence id. examples: - RR0435879820240605njua7shf40o type: string status: description: The resulting local authorization status. examples: - Cancelled type: string required: - idRecorrencia - idCancelamento - cancelledAt - status type: object CancelFraudMarkerRequestBody: additionalProperties: false properties: idempotencyKey: description: "Client-supplied idempotency key: any stable business string. The plugin projects it deterministically into the GUID form JDPI requires (contract 6), so the same value always dedups against the same JDPI request and the raw value is never sent verbatim." examples: - med-fraud-cancel-2024-0001 type: string required: - idempotencyKey type: object CancelInfractionRequestBody: additionalProperties: false properties: idempotencyKey: description: "Client-supplied idempotency key: any stable business string. The plugin projects it deterministically into the GUID form JDPI requires (contract 6), so the same value always dedups against the same JDPI request and the raw value is never sent verbatim." examples: - med-infraction-cancel-2024-0001 type: string required: - idempotencyKey type: object CancelRefundRequestBody: additionalProperties: false properties: idempotencyKey: description: "Client-supplied idempotency key: any stable business string. The plugin projects it deterministically into the GUID form JDPI requires (contract 6), so the same value always dedups against the same JDPI request and the raw value is never sent verbatim." examples: - med-cancel-2024-0001 type: string required: - idempotencyKey type: object CancelScheduleBody: additionalProperties: false properties: reason: description: motivoCancelamento (0..6). examples: - 0 format: int64 type: integer recipientIspb: description: Destination participant ISPB (ispbDestinatario, string). examples: - "00038166" type: string reconciliationId: description: Receiver conciliation id (idConciliacaoRecebedor). examples: - JDPI2024091700000000000000000000001 type: string requester: description: solCancelamento (0=PSP pagador, 1=PSP recebedor). examples: - 1 format: int64 type: integer requesterDocument: description: Requester CPF/CNPJ (cpfCnpjSolCancelamento, string). examples: - "04623217035" type: string requesterIspb: description: Requester participant ISPB (ispbSolicitante, string). examples: - "04358798" type: string requesterPersonType: description: tpPessoaSol (0=Pessoa Fisica, 1=Pessoa Juridica). examples: - 0 format: int64 type: integer required: - requester - requesterIspb - recipientIspb - reconciliationId - requesterPersonType - requesterDocument - reason type: object CancelScheduleResponse: additionalProperties: false properties: cancelledAt: description: Cancellation timestamp (dtHrCancelamento, UTC). examples: - "2024-10-01T10:00:00Z" type: string endToEndId: description: The payment-transaction id (echoed). examples: - E00038166202409171500y6j6mt9l0pi type: string idCancelamento: description: The cancellation id (29-char, CA...). examples: - CA0435879820240605abcd1234567 type: string reconciliationId: description: The receiver conciliation id (echoed). examples: - JDPI2024091700000000000000000000001 type: string status: description: The resulting local schedule status. examples: - Cancelled type: string required: - endToEndId - reconciliationId - idCancelamento - cancelledAt - status type: object CancellationDetailResponse: additionalProperties: false properties: cancelStatus: description: stCancelamento (0=Aceito, 1=Rejeitado; -1 absent). examples: - 0 format: int64 type: integer cancelledAt: description: Cancellation timestamp (UTC). examples: - "2024-02-01T10:00:00Z" type: string errorCode: description: JDPI error code. examples: - "" type: string errorDesc: description: JDPI error description. examples: - "" type: string idCancelamento: description: The cancellation id (IC...). examples: - IC0435879820240605abcd1234567 type: string idRecorrencia: description: The recurrence id. examples: - RR0435879820240605njua7shf40o type: string payer: $ref: "#/components/schemas/AuthorizationPayerView" description: The recurrence pagador. reason: description: motivoCancelamento (0..10). examples: - 0 format: int64 type: integer recipient: $ref: "#/components/schemas/AuthorizationRecipientBody" description: The recurrence recebedor. requesterDocument: description: Requester CPF/CNPJ (string). examples: - "04623217035" type: string requesterType: description: tpPessoaSol. examples: - 0 format: int64 type: integer situationAt: description: Situation timestamp (UTC). examples: - "2024-02-01T10:00:00Z" type: string required: - idRecorrencia - idCancelamento - requesterType - requesterDocument - reason - cancelStatus - recipient - payer type: object CashInBody: additionalProperties: true properties: chave: description: The PIX key (present for key-initiated cash-ins). examples: - recipient@bank.com type: string cnpjIniciadorPagamento: description: Payment initiator CNPJ (a v5.5.0 string). examples: - "11144477735" type: string dtContabil: description: Accounting date (optional). examples: - "2026-06-20" type: string dtHrLiquidacao: description: Settlement timestamp (optional). examples: - "2026-06-20T10:00:01Z" type: string dtHrOp: description: Operation timestamp (ISO-8601). examples: - "2026-06-20T10:00:00Z" type: string endToEndId: description: SPI end-to-end id (idempotency + dedup key). examples: - E2E-1 type: string finalidade: description: Finality (eFinality). examples: - 0 format: int64 type: integer idConciliacaoRecebedor: description: Recipient conciliation id (stamped on the row + the 24h marker). examples: - CONC-1 type: string idReqJdPi: description: JDPI request id (becomes the local row id when a UUID). examples: - JDPI-1 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. prioridadePagamento: description: Payment priority (ePaymentPriority). examples: - 0 format: int64 type: integer recebedor: $ref: "#/components/schemas/PayeeBlock" description: The receiver participant block (the credit account source). tpIniciacao: description: "Payment initiation mechanism (section 9.3.2): 0 manual, 1 chave, 2 QR Code estatico, 3 QR Code dinamico, 6 ITP, 8 Pix Automatico, 9/10 Pix por aproximacao. Both QR values (2 and 3) book the credit on the QR route pair; every other value books on the key route pair." 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: - 100.5 format: double type: number vlrDetalhe: description: Optional value-detail entries. items: $ref: "#/components/schemas/ValueDetailBlock" type: - array - "null" required: - idReqJdPi - endToEndId - tpIniciacao - pagador - recebedor - dtHrOp - valor type: object CashInResponse: additionalProperties: false properties: dtHrCreditoSgct: description: SGCT credit timestamp (ISO-8601), on a credited result. examples: - "2026-06-20T10:00:01Z" type: string dtHrReqJdPi: description: Request timestamp (ISO-8601). examples: - "2026-06-20T10:00:00Z" type: string endToEndIdDevolucao: description: Echoed return end-to-end id. examples: - E2E-1 type: string endToEndIdOriginal: description: Echoed original end-to-end id. examples: - E2E-1 type: string idCreditoSgct: description: SGCT credit lançamento id (GUID), on a credited result. examples: - SGCT-1 type: string idReqJdPi: description: Echoed JDPI request id. examples: - JDPI-1 type: string idReqSistemaCliente: description: Echoed client-system request id. examples: - JDPI-1 type: string type: object ChangeEntryBody: additionalProperties: false properties: accountId: description: The CRM account id of the key owner (resolves the server-side ISPB). examples: - acc-123 type: string accountOpeningDate: description: The new account's opening timestamp (RFC3339). examples: - "2020-01-10T11:30:17.001Z" type: string newAccount: description: The new account number to associate with the key. examples: - "0007654321" type: string newAccountType: description: The new account type (0=Checking,1=Salary,2=Savings,3=Payment,4=PI). examples: - 0 format: int64 type: integer newBranch: description: The new branch number to associate with the key. examples: - "0001" type: string newName: description: The new owner full name / legal name. examples: - Empresa Nova type: string newTradeName: description: The new owner trade name (sent only for a corporate owner). examples: - Fantasia Nova type: string reason: description: Change reason (0=Customer Request,2=Branch Transfer,6=Reconciliation,8=Receita Federal Validation). EVP keys must not use 0. examples: - 2 format: int64 type: integer required: - accountId - reason type: object ChangeEntryResponse: additionalProperties: false properties: claimOpenedAt: description: When a possession/portability claim was opened by the change (RFC3339), if any. examples: - "2026-01-03T00:00:00Z" type: string createdAt: description: When the key was created (RFC3339). examples: - "2026-01-01T00:00:00Z" type: string key: description: The PIX key (unchanged). examples: - foo@bar.com type: string ownershipStartAt: description: When ownership of the key began (RFC3339). examples: - "2026-01-02T00:00:00Z" type: string required: - key type: object ChangeLimitBody: additionalProperties: false properties: accountId: description: The account id (externalId). examples: - ext-acc-123 type: string amount: description: The new limit amount in centavos (> 0). examples: - 5000000 format: int64 type: integer limitType: description: eTransactionLimitType name (TRANSACTION/PERIOD). examples: - PERIOD type: string periodType: description: ePeriodType name (DAILY/NIGHTLY/MONTHLY). examples: - DAILY type: string required: - accountId - amount - periodType - limitType type: object ChangeLimitResponse: additionalProperties: false properties: accountId: description: The account id (externalId). examples: - ext-acc-123 type: string amount: description: The limit amount in centavos. examples: - 5000000 format: int64 type: integer id: description: The limit row id. examples: - l1f9c0a2-... type: string limitType: description: eTransactionLimitType name. examples: - PERIOD type: string periodType: description: ePeriodType name. examples: - DAILY type: string transactionType: description: eTransactionType name. examples: - PIX type: string required: - id - accountId - transactionType - periodType - limitType - amount type: object ClaimActionBody: additionalProperties: false properties: accountId: description: The CRM account id of the caller. examples: - acc-123 type: string key: description: The PIX key the claim targets. examples: - "11122233300" type: string required: - key - accountId type: object ClaimBody: additionalProperties: false properties: accountId: description: The CRM account id of the claimer. examples: - acc-123 type: string key: description: The PIX key to claim. examples: - "11122233300" type: string required: - key - accountId type: object ClaimListItem: additionalProperties: false properties: claimId: description: The claim id. examples: - claim-123 type: string ispb: description: The participant ISPB. examples: - "12345678" type: string key: description: The PIX key value. examples: - "11122233300" type: string required: - key - ispb - claimId type: object ClaimResponse: additionalProperties: false properties: claimId: description: The created/associated claim id. examples: - claim-123 type: string key: description: The PIX key value. examples: - "11122233300" type: string status: description: Numeric eKeyStatus. examples: - 5 format: int64 type: integer statusDescription: description: Human-readable eKeyStatus label. examples: - CLAIMER_PENDING_OWNER_GIVEAWAY type: string type: description: Numeric eKeyType. examples: - 0 format: int64 type: integer required: - type - status type: object ClaimResultResponse: additionalProperties: false properties: claimId: description: The claim id. examples: - claim-123 type: string ispb: description: The claim requester ISPB. examples: - "12345678" type: string key: description: The claimed PIX key. examples: - "11122233300" type: string required: - claimId - key - ispb type: object ClaimStatusResponse: additionalProperties: false properties: claimId: description: The claim id. examples: - claim-123 type: string status: description: Human-readable eKeyStatus label. examples: - DONATED type: string required: - claimId - status type: object CloseAccountBody: additionalProperties: false properties: account: description: The number of the account being closed. examples: - "0007654321" type: string accountId: description: The CRM account id of the caller (resolves the server-side ISPB). examples: - acc-123 type: string accountType: description: The account type (0=Checking,1=Salary,2=Savings,3=Payment,4=PI). examples: - 0 format: int64 type: integer branch: description: The branch number of the account being closed. examples: - "0001" type: string required: - accountId - accountType - account type: object CobvCompositeBody: additionalProperties: false properties: accountId: description: The CRM account id of the recipient (sources name + city). examples: - acc-123 type: string certificateIspb: description: Indirect-PSP certificate ISPB (ispbCertificadoJws, string). examples: - "04358798" type: string daysAfterDue: description: Days after the due date the charge can still be paid (diasAposVenc). examples: - 365 format: int64 type: integer description: description: Optional additional-data entries (dadosAdicionais). items: $ref: "#/components/schemas/CompositeAdditionalDataBody" type: - array - "null" discount: description: Discount in centavos (desconto; omit/0 to skip). examples: - 4 format: int64 type: integer dueDate: description: Due date for payment (dtVenc; aaaa-mm-dd). examples: - "2021-06-17" type: string finalAmount: description: Final charge amount in centavos (valorFinal, after adjustments). examples: - 100001 format: int64 type: integer fine: description: Fine in centavos (multa; omit/0 to skip). examples: - 20022 format: int64 type: integer interest: description: Interest in centavos (juros; omit/0 to skip). examples: - 1015 format: int64 type: integer jwkUrl: description: JWK Set URL (urlJwk; no scheme). examples: - example.com/jwks type: string key: description: The recipient PIX key the composite QR pays into. examples: - fulano.tal@provedor.com.br type: string originalAmount: description: Original charge amount in centavos (valorOriginal, before adjustments). examples: - 100116 format: int64 type: integer payer: $ref: "#/components/schemas/CompositePayerBody" description: Optional payer block. paymentPayloadUrl: description: CobV JWS host URL (urlPayloadJson; no scheme). examples: - pix.example.com/cobv/abc type: string rebate: description: Rebate in centavos (abatimento; omit/0 to skip). examples: - 111 format: int64 type: integer recipientStreet: description: Recipient street (logradouroRecebedor). examples: - Rua Pix, 123 type: string recurrence: $ref: "#/components/schemas/CompositeRecurrenceBody" description: The embedded recurrence configuration (dadosRecorrencia). recurrencePayloadUrl: description: Recurrence JWS host URL (urlPayloadJsonRec; no scheme). examples: - pix.example.com/rec/def type: string state: description: Recipient state (uf). examples: - SP type: string txId: description: Conciliation id (idConciliacaoRecebedor). examples: - JDPI2020010300000000000000000000001 type: string zipCode: description: Recipient postal code (cep). examples: - "01227200" type: string required: - key - accountId - recipientStreet - state - zipCode - finalAmount - dueDate - daysAfterDue - txId - paymentPayloadUrl - recurrencePayloadUrl - jwkUrl - recurrence type: object CompositeAdditionalDataBody: additionalProperties: false properties: name: description: The additional-data entry name. examples: - Detalhes do Pagamento type: string value: description: The additional-data entry value. examples: - Informacao Adicional type: string required: - name - value type: object CompositeDebtorBody: additionalProperties: false properties: cpfCnpj: description: Debtor CPF or CNPJ (string). examples: - "04623217035" type: string name: description: Debtor name. examples: - Ciclano da Silva type: string personType: description: Debtor person type (0=Pessoa Fisica, 1=Pessoa Juridica). examples: - 0 format: int64 type: integer required: - personType - cpfCnpj - name type: object CompositePayerBody: additionalProperties: false properties: document: description: Payer document (CPF/CNPJ, string). examples: - "04623217035" type: string name: description: Payer name (only forwarded with a document). examples: - Ciclano de Tal type: string request: description: Free-text request to the payer (solicitacaoPagador). examples: - Pesquisa de satisfacao type: string type: object CompositeRecipientBody: additionalProperties: false properties: cnpj: description: Recipient CNPJ (14 digits, string). examples: - "61695227000193" type: string ispb: description: Recipient participant ISPB (8 digits, string). examples: - "04358798" type: string name: description: Recipient legal/trade name. examples: - Enel type: string required: - ispb - cnpj - name type: object CompositeRecurrenceBody: additionalProperties: false properties: amount: description: Fixed payment amount in centavos (omit/0 for a variable recurrence). examples: - 110001 format: int64 type: integer contractDesc: description: Free-text contract description. examples: - Conta de energia type: string contractNumber: description: Contract/order identifier (nrContrato). examples: - 1234567890ABC type: string debtor: $ref: "#/components/schemas/CompositeDebtorBody" description: The recurrence devedor (authorized payer). endDate: description: Last payment date (aaaa-mm-dd). examples: - "2026-01-10" type: string frequency: description: tpFrequencia (0=Weekly,1=Monthly,2=Quarterly,3=Semiannual,4=Annual). examples: - 1 format: int64 type: integer maxFloorAmount: description: Floor amount in centavos (pisoValorMaximo; not valid with a fixed amount). examples: - 55000 format: int64 type: integer recipient: $ref: "#/components/schemas/CompositeRecipientBody" description: The recurrence recebedor (authorized charging entity). recurrenceId: description: Unique recurrence id (29-char, format RR...). examples: - RR0435879820240605njua7shf40o type: string retry: description: retentativa policy (0=none, 1=up to 3 retries within 7 days). examples: - 1 format: int64 type: integer startDate: description: First payment date (aaaa-mm-dd). examples: - "2024-01-10" type: string required: - recurrenceId - frequency - startDate - recipient - debtor - contractNumber - retry type: object CompositeRecurrenceUpdateResponse: additionalProperties: false properties: status: description: stRecorrencia (0=Created,1=Approved,2=Rejected,3=Expired,4=Cancelled). examples: - 0 format: int64 type: integer statusDateTime: description: Status update timestamp (ISO-8601). examples: - "2024-11-08T14:25:49.025Z" type: string required: - status - statusDateTime type: object CompositeResponse: additionalProperties: false properties: documentId: description: The recurrence/charge document id (idDocumento, GUID). examples: - 52c43361-caa1-4ddb-9152-708426a25db3 type: string qrCode: description: The generated EMV composite-QR payload (base64-decoded, ready to render). examples: - 00020126... type: string recurrencePayload: description: The signed recurrence JWS (payloadJwsRecorrencia). examples: - eyJhbGciOiJQUzUxMi... type: string required: - qrCode type: object CompositeUpdateResponse: additionalProperties: false properties: documentId: description: The recurrence/charge document id (idDocumento, GUID). examples: - 52c43361-caa1-4ddb-9152-708426a25db3 type: string payloadJws: description: The signed payment JWS (payloadJws; dynamic + cobv). examples: - eyJhbGciOiJQUzUxMi... type: string qrCode: description: The regenerated EMV composite-QR payload (base64-decoded, ready to render). examples: - 00020126... type: string recurrencePayload: description: The signed recurrence JWS (payloadJwsRecorrencia). examples: - eyJhbGciOiJQUzUxMi... type: string revision: description: The JDPI-computed charge revision (revisao; dynamic + cobv updates only). examples: - 2 format: int64 type: integer required: - qrCode type: object ConfirmAuthorizationBody: additionalProperties: false properties: amount: description: Fixed payment amount in centavos (valor). examples: - 110001 format: int64 type: integer authorizedAt: description: Authorization timestamp (dtHrAutorizacaoRecorrencia, UTC). examples: - "2024-01-06T10:00:00Z" type: string contractDesc: description: Free-text contract description. examples: - Conta de energia type: string contractNumber: description: Contract/order identifier (nrContrato). examples: - 1234567890ABC type: string createdDateTime: description: Recurrence creation timestamp (dtHrCriacaoRecorrencia, UTC). examples: - "2024-01-05T10:00:00Z" type: string debtor: $ref: "#/components/schemas/AuthorizationDebtorBody" description: The devedor, sent only when it differs from the payer. endDate: description: Last payment date (dtFinalRecorrencia). examples: - "2026-01-10" type: string floorMaxAmount: description: Receiver floor in centavos (pisoValorMaximo). examples: - 55000 format: int64 type: integer frequency: description: tpFrequencia (0..4). examples: - 1 format: int64 type: integer journey: description: jornada (2..4). examples: - 2 format: int64 type: integer payer: $ref: "#/components/schemas/ConfirmPayerBody" description: The recurrence pagador (incl. name, accountType, ibgeCode). payerMaxAmount: description: Payer max cap in centavos (vlrMaxPagador). examples: - 200000 format: int64 type: integer recipient: $ref: "#/components/schemas/AuthorizationRecipientBody" description: The recurrence recebedor. settlementConfirmedAt: description: Settlement confirmation timestamp (dtHrConfirmacaoLiquidacao, UTC; required for jornada=3). examples: - "2024-01-06T10:05:00Z" type: string startDate: description: First payment date (dtInicialRecorrencia; aaaa-mm-dd). examples: - "2024-01-10" type: string required: - journey - frequency - startDate - recipient - payer - contractNumber type: object ConfirmEntryBody: additionalProperties: false properties: accountId: description: The CRM account id of the key owner. examples: - acc-123 type: string token: description: The OTP ownership-confirmation code. examples: - "123456" type: string required: - token - accountId type: object ConfirmPayerBody: additionalProperties: false properties: account: description: Payer account number (nrConta, string). examples: - "0007654321" type: string accountType: description: tpConta (0..3). examples: - 0 format: int64 type: integer agency: description: Payer branch (nrAgencia, string). examples: - "0001" type: string cpfCnpj: description: Payer CPF or CNPJ (string). examples: - "04623217035" type: string ibgeCode: description: Municipality IBGE code (codMunIbge). examples: - 3550308 format: int64 type: integer ispb: description: Payer participant ISPB (8 digits, string). examples: - "00038166" type: string name: description: Payer name (nomePagador). examples: - Fulano de Tal type: string personType: description: tpPessoa (0=Pessoa Fisica, 1=Pessoa Juridica). examples: - 0 format: int64 type: integer required: - ispb - personType - cpfCnpj - name - account - accountType - ibgeCode type: object CreateEntryResponse: additionalProperties: false properties: key: description: The PIX key value. examples: - "11122233300" type: string keyType: description: Numeric eKeyType. examples: - 4 format: int64 type: integer status: description: Numeric eKeyStatus. examples: - 1 format: int64 type: integer statusDescription: description: Human-readable eKeyStatus label. examples: - ACTIVE type: string type: object CreateIndirectBody: additionalProperties: false properties: delivery: $ref: "#/components/schemas/CreateIndirectDelivery" description: Delivery endpoint + signing secret. ispb: description: The indirect PSP's own ISPB (exactly 8 digits). Required for MVP flows. examples: - "12345678" type: string messagingMode: description: Delivery mode; the MVP supports 'raw' (JD-pure passthrough). examples: - raw type: string name: description: Display name of the indirect participant (1..120 chars). examples: - Indirect PSP Ltda type: string required: - name type: object CreateIndirectDelivery: additionalProperties: false properties: endpointUrl: description: HTTPS endpoint the indirect's events are delivered to. examples: - https://indirect.example.com/pix type: string secret: description: HMAC-SHA256 signing secret; encrypted at rest; never returned. examples: - s3cr3t type: string required: - endpointUrl type: object CreateRecoveryRequestBody: additionalProperties: false properties: contatoEmail: description: Creator-contact email (required). examples: - ops@example.com type: string contatoTelefone: description: Creator-contact phone (required). examples: - "+5511999999999" type: string detalhes: description: Free-text detail; required when tpSituacao=4 (Outros). examples: - Suspected scam. type: string grafoRastreamento: $ref: "#/components/schemas/GrafoRastreamentoBody" description: Optional graph-traversal FILTER parameters; omit to use JDPI defaults. idTransacaoRaiz: description: EndToEndId of the root transaction being recovered. examples: - E1234567820240101000000000000001 type: string idempotencyKey: description: "Client-supplied idempotency key: any stable business string. The plugin projects it deterministically into the GUID form JDPI requires (contract 6), so the same value always dedups against the same JDPI request and the raw value is never sent verbatim." examples: - med-recovery-2024-0001 type: string tpSituacao: description: Situation code (0=Golpe, 1=Nao autorizada, 2=Coercao, 3=Acesso fraudulento, 4=Outros, 5=Desconhecida). examples: - 0 format: int64 type: integer required: - idTransacaoRaiz - tpSituacao - contatoEmail - contatoTelefone - idempotencyKey type: object CreateTransactionAcceptedResponse: additionalProperties: true properties: dtHrReqJdPi: description: The JD request timestamp. examples: - "2026-01-01T00:00:00.000Z" type: string endToEndId: description: The SPI end-to-end id JD assigned to the order. examples: - E1234567890 type: string idReqJdPi: description: The JD request id. Poll JDPI §8.4.2 with this id to learn the settlement outcome. examples: - 45F763C6-7487-4363-9406-A1DE2A9636D3 type: string idReqSistemaCliente: description: The client request id JD echoes back (the idempotency key, GUID). examples: - 9F4C2A10-0000-4000-8000-000000000001 type: string tpCanal: description: The JD settlement-channel discriminator, when JD sends it. examples: - 2 format: int64 type: integer required: - idReqSistemaCliente - idReqJdPi - endToEndId - dtHrReqJdPi type: object CreateTransactionBody: additionalProperties: false properties: accountId: description: The CRM account id of the payer. examples: - acc-123 type: string amount: description: Transaction amount in centavos (an integer, e.g. 10050 = R$ 100,50). examples: - 10050 format: int64 type: integer clientRequestId: description: "Optional client idempotency token. A retry carrying the same value is rejected instead of moving money twice; it also seeds the Midaz hold key and the JDPI Chave-Idempotencia. Send it on a manually-typed order: that order has no endToEndId until SPI mints it, so this token is the only thing that can dedup a retry. Omit to opt out." examples: - req-2025-01-01-abc123 type: string description: description: Free-text payment description. examples: - Invoice 42 type: string endToEndId: description: "SPI end-to-end id. Omit ONLY for a manually-typed payment order: per JDPI §8.4.1 the id does not exist yet and is generated by SPI on this call. If you obtained one from decode-QRCode (§8.3.3) or consultar-chave (§8.2.14) you MUST send it — omitting it makes SPI mint a DIFFERENT id, which will not match the payee's QR/txId conciliation." examples: - E1234567890 type: string indirectId: description: Optional registered-indirect identifier (UUID) routing this outbound order through an indirect participant's PIX position. Omit for a direct order. Validated server-side before any money moves; unknown or inactive is rejected. examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string key: description: The payer's PIX key, when paying from a key. examples: - payer@bar.com type: string payee: $ref: "#/components/schemas/PayeeBody" description: The recipient bank data. priority: description: Numeric eTransactionPriority (1=PRIMARY,2=SECONDARY). examples: - 1 format: int64 type: integer required: - accountId - amount - payee type: object CreateTransactionResponse: additionalProperties: false properties: amount: description: Transaction amount in centavos. examples: - 10050 format: int64 type: integer description: description: Payment description. examples: - Invoice 42 type: string endToEndId: description: The SPI end-to-end id. examples: - E1234567890 type: string flow: description: Numeric eTransactionFlow (2=CASH_OUT,3=INTRA_PSP). examples: - 2 format: int64 type: integer id: description: The created transaction id. examples: - d1f9c0a2-... type: string jdpiRequestId: description: The JDPI request id (external CASH_OUT). examples: - REQ-123 type: string priority: description: Numeric eTransactionPriority. examples: - 1 format: int64 type: integer status: description: eTransactionStatus name. examples: - PENDING type: string required: - id - status - amount 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 DebitScheduleBody: additionalProperties: true properties: dtContabil: description: Accounting date (aaaa-mm-dd). examples: - "2024-09-20" type: string dtHrEfetivacao: description: JDPI effectuation timestamp (UTC). examples: - "2024-09-20T04:00:01.001Z" type: string dtHrLiquidacao: description: SPI settlement timestamp (UTC). examples: - "2024-09-20T04:00:00.023Z" type: string endToEndId: description: Unique payment-instruction id (32-char). examples: - E11111111202409181500y6j6mt9l1pi type: string ispb: description: Payer participant ISPB (8 digits, a v5.5.0 string). examples: - "04358798" type: string required: - endToEndId - ispb - dtHrEfetivacao - dtContabil - dtHrLiquidacao type: object DebitScheduleResponse: additionalProperties: false properties: dtHrOperacaoSgct: description: SGCT operation timestamp (UTC). examples: - "2024-09-20T04:00:01.001Z" type: string endToEndId: description: Unique payment-instruction id (32-char). examples: - E11111111202409181500y6j6mt9l1pi type: string idOperacaoSgct: description: SGCT debit-operation id (the Midaz transaction id, a GUID). examples: - 58F752C5-6376-3252-8305-A2DE3A8525D3 type: string required: - endToEndId - idOperacaoSgct - dtHrOperacaoSgct type: object DecodeCompositeBody: additionalProperties: false properties: recurrencePayloadUrl: description: The recurrence JWS host URL to decode (urlPayloadJsonRec; no scheme). examples: - pix.example.com/rec/2353c790eefb11eaadc10242ac120004 type: string required: - recurrencePayloadUrl type: object DecodeCompositeResponse: additionalProperties: false properties: amount: description: Fixed payment amount in centavos. examples: - 0 format: int64 type: integer contractDesc: description: Free-text contract description. examples: - Conta de energia type: string contractNumber: description: Contract/order identifier (nrContrato). examples: - 1234567890ABC type: string createdDateTime: description: QR creation timestamp (dtHrCriacao). examples: - "2024-11-08T14:24:15.043Z" type: string debtor: $ref: "#/components/schemas/CompositeDebtorBody" description: The recurrence devedor. endDate: description: Last payment date (aaaa-mm-dd). examples: - "2026-01-10" type: string frequency: description: tpFrequencia. examples: - 4 format: int64 type: integer maxFloorAmount: description: Floor amount in centavos (pisoValorMaximo). examples: - 55000 format: int64 type: integer presentedDateTime: description: QR presentation timestamp (dtHrApresentacao). examples: - "2024-11-10T10:21:34.107Z" type: string recipient: $ref: "#/components/schemas/CompositeRecipientBody" description: The recurrence recebedor. recurrenceId: description: Unique recurrence id. examples: - RR0435879820240605njua7shf40o type: string retry: description: retentativa policy. examples: - 1 format: int64 type: integer startDate: description: First payment date (aaaa-mm-dd). examples: - "2024-01-10" type: string updates: description: Recurrence status history (atualizacoes). items: $ref: "#/components/schemas/CompositeRecurrenceUpdateResponse" type: - array - "null" required: - recurrenceId - frequency - startDate - recipient - debtor - contractNumber - retry type: object DecodePayeeResponse: additionalProperties: false properties: accountDigit: description: Recipient account check digit (split from the wire account). examples: - "7" type: string accountNumber: description: Recipient account number (split from the wire account). examples: - "123456" type: string accountType: description: Numeric eAccountType (0=Conta Corrente). examples: - 0 format: int64 type: integer branch: description: Recipient agency/branch. examples: - "0001" type: string document: description: Recipient document (CPF/CNPJ). examples: - "12345678909" type: string ispb: description: Recipient participant ISPB. examples: - "12345678" type: string keyType: description: Numeric eKeyType from §8.3.3 tpChave (CPF=0,CNPJ=1,EMAIL=2,PHONE=3,RANDOM=4). examples: - 2 format: int64 type: integer name: description: Recipient holder name. examples: - Jane Doe type: string type: object DecodeQRBody: additionalProperties: false properties: accountId: description: The CRM account id of the scanning payer (sources the PI-PayerID document). examples: - acc-123 type: string qrCode: description: The scanned EMV QR-code payload to decode. examples: - 00020126... type: string required: - qrCode - accountId type: object DecodeQRResponse: additionalProperties: false properties: amount: description: The decoded amount in centavos. examples: - 10050 format: int64 type: integer amountTroco: description: The Pix Troco amount in centavos (troco only). examples: - 0 format: int64 type: integer city: description: Recipient city (cidade; §8.3.3 Obrg=Sim on every block). examples: - Sao Paulo type: string createdAt: description: When the dynamic charge was created (dtHrCriacao; §8.3.3 Obrg=Sim). examples: - "2020-01-20T12:29:15.043Z" type: string description: description: Additional data (dadosAdicionais). examples: - Invoice 42 type: string dueDate: description: Due date (cobv/static optional). examples: - "2026-12-31" type: string endToEndId: description: The SPI end-to-end id. examples: - E1234567890 type: string isPixSaque: description: Whether the QR carries a Pix Saque leg. examples: - false type: boolean isPixTroco: description: Whether the QR carries a Pix Troco leg. examples: - false type: boolean ispbPss: description: The saque/troco PSS participant ISPB (a v5.5.0 string; leading zeros are significant). examples: - "00360305" type: string key: description: The recipient PIX key. examples: - recipient@bank.com type: string payee: $ref: "#/components/schemas/DecodePayeeResponse" description: The decoded recipient identity. presentedAt: description: When the payer captured the QR, i.e. the moment of this decode (dtHrApresentacao; §8.3.3 Obrg=Sim). examples: - "2020-01-23T10:21:34.107Z" type: string qrCodeType: description: The decoded QR type (STATIC or DYNAMIC; cobv folds onto DYNAMIC). examples: - DYNAMIC type: string revision: description: Charge revision counter (revisao). Always present on a DYNAMIC decode, including at its initial value 0; absent on a STATIC one, whose §8.3.3 block declares no revisao. examples: - 0 format: int64 type: integer txId: description: Conciliation id (idConciliacaoRecebedor). examples: - TX-001 type: string required: - qrCodeType - amount - payee type: object DecodeURLQRBody: additionalProperties: false properties: accountId: description: The CRM account id of the scanning payer (sources the PI-PayerID document). examples: - acc-123 type: string municipalityCode: description: Payer municipality code (codMun; cobv holiday calc). examples: - "3550308" type: string payloadUrl: description: The payee-published JWS payload URL to decode (urlPayloadJson; schema-less). examples: - example.com/pix/8b3da2f3 type: string paymentDate: description: Intended payment date (dPP; aaaa-mm-dd; cobv valorFinal calc). examples: - "2026-01-30" type: string required: - payloadUrl - accountId type: object DeleteEntryBody: additionalProperties: false properties: accountId: description: The CRM account id of the key owner. examples: - acc-123 type: string required: - accountId type: object DeleteEntryResponse: additionalProperties: false properties: key: description: The PIX key that was deleted. examples: - "11122233300" type: string required: - key type: object DeletedKeyView: additionalProperties: false properties: document: description: The key owner document (account-closure only). examples: - "82437485000140" type: string key: description: The deleted PIX key value. examples: - foo@bar.com type: string name: description: The key owner name (account-closure only). examples: - Empresa de Tal type: string reason: description: The deletion reason code. examples: - 1 format: int64 type: integer result: description: Deletion result (0=not deleted,1=deleted). examples: - 1 format: int64 type: integer resultDescription: description: The failure reason when result=0. examples: - Falha de comunicação com DICT type: string required: - key - reason - result 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 DevolverRecoveryRequestBody: additionalProperties: false properties: idempotencyKey: description: "Client-supplied idempotency key: any stable business string. The plugin projects it deterministically into the GUID form JDPI requires (contract 6), so the same value always dedups against the same JDPI request and the raw value is never sent verbatim." examples: - med-devolver-2024-0001 type: string required: - idempotencyKey type: object DynamicCompositeBody: additionalProperties: false properties: accountId: description: The CRM account id of the recipient (sources name + city). examples: - acc-123 type: string certificateIspb: description: Indirect-PSP certificate ISPB (ispbCertificadoJws, string). examples: - "04358798" type: string description: description: Optional additional-data entries (dadosAdicionais). items: $ref: "#/components/schemas/CompositeAdditionalDataBody" type: - array - "null" expirationTime: description: QR expiration in seconds (0 = JDPI default). examples: - 86400 format: int64 type: integer jwkUrl: description: JWK Set URL (urlJwk; no scheme). examples: - example.com/jwks type: string key: description: The recipient PIX key the composite QR pays into. examples: - fulano.tal@provedor.com.br type: string originalAmount: description: Original charge amount in centavos (valorOriginal). examples: - 100001 format: int64 type: integer payer: $ref: "#/components/schemas/CompositePayerBody" description: Optional payer block. paymentPayloadUrl: description: Payment JWS host URL (urlPayloadJson; no scheme). examples: - pix.example.com/cob/abc type: string recurrence: $ref: "#/components/schemas/CompositeRecurrenceBody" description: The embedded recurrence configuration (dadosRecorrencia). recurrencePayloadUrl: description: Recurrence JWS host URL (urlPayloadJsonRec; no scheme). examples: - pix.example.com/rec/def type: string txId: description: Conciliation id (idConciliacaoRecebedor). examples: - JDPI2020010300000000000000000000001 type: string zipCode: description: Recipient postal code (cep). examples: - "01227200" type: string required: - key - accountId - originalAmount - txId - paymentPayloadUrl - recurrencePayloadUrl - jwkUrl - recurrence type: object DynamicQRBody: additionalProperties: false properties: accountId: description: The CRM account id of the recipient (sources name + city). examples: - acc-123 type: string amount: description: Amount in centavos (an integer). examples: - 10050 format: int64 type: integer description: description: Optional additional-data entries (dadosAdicionais). items: $ref: "#/components/schemas/AdditionalDataBody" type: - array - "null" expirationTime: description: QR expiration in seconds (0 = JDPI default). examples: - 3600 format: int64 type: integer indirectId: description: "Optional identifier (UUID) of an indirect participant registered here. When that institution hosts its OWN dynamic-QR certificate, JDPI signs with its certificate, payloadUrl is built on its domain, and payloadJws is returned for it to host; otherwise the QR is signed and hosted by the direct participant exactly as if this were omitted. Omit for a direct QR. Validated server-side: unknown or inactive is rejected. IGNORED, without any error, while this tenant's indirect-participants feature is off." examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string key: description: The recipient PIX key the dynamic QR pays into. examples: - recipient@bank.com type: string payer: $ref: "#/components/schemas/PayerBody" description: Optional payer block. recipientConciliationId: description: Conciliation id (idConciliacaoRecebedor); §8.3.2 mandatory; 26..35 alphanumeric ([a-zA-Z0-9]); dedup gate. examples: - JDPI2020010300000000000000000000001 type: string zipCode: description: Recipient postal code (cep). examples: - "01310100" type: string required: - key - amount - accountId - recipientConciliationId type: object EffectuateRefundView: additionalProperties: false properties: effStatus: description: Debit-effectuation FSM code (0=NotStarted, 1=DebitPending, 2=Settled, 3=Failed). examples: - 1 format: int64 type: integer effStatusDescription: description: Human-readable eff_status label. examples: - DebitPending type: string idOperacaoDebito: description: The Pending Midaz debit posting id (the reconcile commit/cancel reference). examples: - 01HXYZ... type: string idReqJdPi: description: The JDPI /od request id (the debit-poll handle). examples: - f1e2d3c4-b5a6-7890-1234-567890abcdef type: string idSolDevolucao: description: The effectuated refund-request GUID. examples: - d4e5f6a7-b8c9-0123-def4-56789012345a type: string required: - idSolDevolucao - idReqJdPi - effStatus - effStatusDescription - idOperacaoDebito type: object EntryDetailsResponse: additionalProperties: false properties: endToEndId: description: The SPI end-to-end identifier. examples: - E1234567890 type: string key: description: The PIX key value. examples: - foo@bar.com type: string payee: $ref: "#/components/schemas/EntryPayee" description: The resolved recipient bank data. required: - key - endToEndId - payee type: object EntryListBody: additionalProperties: false properties: data: description: The list of key entries. items: $ref: "#/components/schemas/EntryView" type: - array - "null" required: - data type: object EntryPayee: additionalProperties: false properties: document: description: Recipient document (CPF/CNPJ). examples: - "12345678909" type: string ispb: description: Recipient participant ISPB. examples: - "12345678" type: string key: description: The resolved PIX key. examples: - foo@bar.com type: string name: description: Recipient holder name. examples: - Jane Doe type: string required: - document - name - ispb - key type: object EntryView: additionalProperties: false properties: claimId: description: Associated claim id, when the key is in a claim flow. examples: - claim-123 type: string ispb: description: ISPB of the participant holding the key, when reconstructed. examples: - "12345678" type: string key: description: The PIX key value. examples: - "11122233300" type: string status: description: Numeric eKeyStatus (-1..7). examples: - 1 format: int64 type: integer statusDescription: description: Human-readable eKeyStatus label. examples: - ACTIVE type: string type: description: Numeric eKeyType (0=CPF,1=CNPJ,2=EMAIL,3=PHONE,4=RANDOM). examples: - 0 format: int64 type: integer required: - key - status - statusDescription - type - claimId - ispb 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 ExternalRefundBody: additionalProperties: true properties: codigoDevolucao: description: Return reason code (eRefundCode). examples: - MD06 type: string endToEndIdDevolucao: description: JDPI-assigned return id (idempotency + dedup key). examples: - E2E-DEVO type: string endToEndIdOriginal: description: End-to-end id of the original CASH_OUT. examples: - E2E-ORIG type: string idReqJdPi: description: JDPI request id (GUID), echoed on the acknowledgement. examples: - JDPI-1 type: string infEntreClientes: description: Free-text inter-client info. examples: - note type: string motivoDevolucao: description: Free-text return reason. examples: - customer request type: string valor: description: Return amount in reais (a JSON number). examples: - 50.25 format: double type: number required: - idReqJdPi - endToEndIdOriginal - endToEndIdDevolucao - valor type: object ExternalRefundResponse: additionalProperties: false properties: dtHrCreditoSgct: description: SGCT credit timestamp (ISO-8601). examples: - "2026-06-20T10:00:00Z" type: string dtHrValidacao: description: Validation timestamp (ISO-8601). examples: - "2026-06-20T10:00:00Z" type: string idCreditoSgct: description: SGCT credit id. examples: - SGCT-1 type: string idReqJdPi: description: Echoed JDPI request id. examples: - JDPI-1 type: string motivo: description: Reason code (on a rejected return). examples: - BE01 type: string motivoComplemento: description: Reason complement. examples: - "..." type: string resultado: description: Validation result (0=Inválido, 1=Válido). examples: - 1 format: int64 type: integer type: object FraudMarkerListBody: additionalProperties: false properties: data: description: The list of fraud markers. items: $ref: "#/components/schemas/FraudMarkerView" type: - array - "null" dictCorrelationId: description: idCorrelacao — the DICT support identifier for this listing call; quote it to JD when disputing whether the read happened. examples: - a7f12465e19f5ca51329479a5bae60c2 type: string dictReturnedAt: description: dtHrRetornoDict — when DICT answered this listing (contract 2.19). examples: - "2025-01-02T10:30:05.025Z" type: string required: - data type: object FraudMarkerView: additionalProperties: false properties: chave: description: The flagged Pix key, when known. examples: - user@example.com type: string cpfCnpj: description: The flagged document. examples: - "12345678901" type: string dictCorrelationId: description: idCorrelacao — the DICT support identifier for this consultar call; quote it to JD when disputing whether the read happened. examples: - a7f12465e19f5ca51329479a5bae60c2 type: string dictReturnedAt: description: dtHrRetornoDict — when DICT answered this consultar (contract 2.16). examples: - "2023-08-16T10:30:05.025Z" type: string dtHrCriacao: description: JDPI creation timestamp (RFC 3339 UTC). examples: - "2024-01-01T12:00:00.000Z" type: string dtHrUltModificacao: description: JDPI last-modification timestamp (RFC 3339 UTC) — the watermark. examples: - "2024-01-01T12:05:00.000Z" type: string idMarcacaoFraude: description: Fraud-marker GUID (the natural key). examples: - c3d4e5f6-a7b8-9012-cdef-345678901234 type: string idRelatoInfracao: description: Linked infraction GUID, when the marker was auto-created from a closed infraction. examples: - a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string ispb: description: ISPB of the creator PSP. examples: - "12345678" type: string ispbRelatoInfracao: description: Linked infraction's PSP ISPB, when infraction-originated. examples: - "87654321" type: string status: description: stMarcacaoFraude lifecycle code (0=Registrada, 1=Cancelada). examples: - 0 format: int64 type: integer statusDescription: description: Human-readable stMarcacaoFraude label. examples: - Registrada type: string tpFraude: description: Fraud-type code (0..4; 4=Desconhecida is read-only). examples: - 1 format: int64 type: integer tpFraudeDescription: description: Human-readable tpFraude label. examples: - Conta laranja type: string tpPessoa: description: Person-type code (0=Pessoa Fisica, 1=Pessoa Juridica). examples: - 0 format: int64 type: integer tpPessoaDescription: description: Human-readable tpPessoa label. examples: - Pessoa Fisica type: string required: - idMarcacaoFraude - ispb - tpPessoa - tpPessoaDescription - cpfCnpj - tpFraude - tpFraudeDescription - status - statusDescription - dtHrCriacao - dtHrUltModificacao type: object GetClaimsBody: additionalProperties: false properties: claims: description: The list of claims (default branch). items: $ref: "#/components/schemas/ClaimListItem" type: - array - "null" data: description: The in-flight claims as key entries (?status=processing branch). items: $ref: "#/components/schemas/EntryView" type: - array - "null" type: object GrafoRastreamentoBody: additionalProperties: false properties: janelaTempo: description: Traversal time-window (ISO-8601 duration, max PT2H). examples: - PT2H type: string maxProfundidade: description: Traversal max depth (max 10). examples: - 2 format: int64 type: integer maxTransacoes: description: Max transactions to trace (max 5). examples: - 5 format: int64 type: integer vlrMinTransacao: description: Traversal floor (trace only downstream txns >= this), in centavos. A FILTER threshold, never a posting amount. examples: - 20000 format: int64 type: integer required: - vlrMinTransacao - maxTransacoes - janelaTempo - maxProfundidade type: object HolderRemovalBody: additionalProperties: false properties: account: description: The account number. examples: - "0007654321" type: string accountId: description: The CRM account id of the caller (resolves the server-side ISPB). examples: - acc-123 type: string accountType: description: The account type (0=Checking,1=Salary,2=Savings,3=Payment,4=PI). examples: - 0 format: int64 type: integer branch: description: The branch number of the account. examples: - "0001" type: string document: description: The target holder document (CPF/CNPJ). examples: - "82437485000140" type: string personType: description: The target holder person type (0=Person,1=Corporate). examples: - 1 format: int64 type: integer required: - accountId - accountType - account - personType - document type: object HolderRemovalResponse: additionalProperties: false properties: deletedKeys: description: The per-key deletion outcomes. items: $ref: "#/components/schemas/DeletedKeyView" type: - array - "null" required: - deletedKeys type: object InboundCreditBody: additionalProperties: true properties: codigoDevolucao: description: Refund reason code (BE08/FR01/MD06/SL02; §9.3.3 Obrg=Sim, tolerated-absent). examples: - BE08 type: string dtContabil: description: SPI accounting date (§9.3.3, Obrg=Sim, aaaa-mm-dd). examples: - "2024-09-20" type: string dtHrLiquidacao: description: SPI settlement instant (§9.3.3, Obrg=Sim, UTC). examples: - "2024-09-20T04:00:01.001Z" type: string dtHrOp: description: Recebedor-informed original instant (UTC). examples: - "2024-09-20T04:00:01.001Z" type: string endToEndIdDevolucao: description: EndToEndId of the devolucao (pacs.004; the natural key / idempotency anchor, 32-char). examples: - D1234567820240101000000000000099 type: string endToEndIdOriginal: description: EndToEndId of the original contested payment (32-char; §9.3.3 Obrg=Sim, tolerated-absent). examples: - E1234567820240101000000000000001 type: string idReqJdPi: description: The JDPI request id of the credit notification. examples: - f1e2d3c4-b5a6-7890-1234-567890abcdef type: string infEntreClientes: description: Payer-to-payee free-text information (§9.3.3, Obrg=Nao). examples: - Compra Paga type: string motivoDevolucao: description: Free-text refund detail. examples: - Devolucao MED. type: string pagador: $ref: "#/components/schemas/InboundCreditPagador" description: Payer (pagador) identity; retained for audit/observability. recebedor: $ref: "#/components/schemas/InboundCreditRecebedor" description: Recipient (recebedor) identity; the credit distribute leg target (design D2 mirror). recebedor.ispb is enforced by Validate(). valor: description: Credited refund amount, in reais (a JSON number; JDPI 9.3.3). examples: - 150.85 format: double type: number required: - idReqJdPi - endToEndIdDevolucao - valor type: object InboundCreditPagador: additionalProperties: true properties: cpfCnpj: description: Payer CPF or CNPJ (a v5.5.0 string). examples: - "11111111111" type: string ispb: description: Payer participant ISPB (8 digits, a v5.5.0 string). examples: - "04358798" type: string nome: description: Payer name/legal name (§9.3.3 pagador.nome; audit-only). examples: - Fulano de Tal type: string nrAgencia: description: Payer branch (4 digits, a string). examples: - "0001" type: string nrConta: description: Payer account number (a string). examples: - "12345678" type: string tpConta: description: Payer account type (§9.3.3, 0 CC, 1 Salário, 2 Poupança, 3 Pagamento, 4 PI; audit-only). examples: - 0 format: int64 type: integer tpPessoa: description: Payer person type (§9.3.3, 0 PF, 1 PJ; audit-only). examples: - 0 format: int64 type: integer required: - ispb type: object InboundCreditRecebedor: additionalProperties: true properties: cpfCnpj: description: Recipient CPF or CNPJ (a v5.5.0 string). examples: - "22222222222" type: string ispb: description: Recipient participant ISPB (8 digits, a v5.5.0 string). examples: - "17826860" type: string nrAgencia: description: Recipient branch (4 digits, a string). examples: - "0001" type: string nrConta: description: Recipient account number (a string). examples: - "87654321" type: string tpConta: description: "Recipient account type (§9.3.3, 0 CC, 1 Salário, 2 Poupança, 3 Pagamento, 4 PI). THIRD RAIL: disambiguates same-holder accounts." examples: - 0 format: int64 type: integer tpPessoa: description: Recipient person type (§9.3.3, 0 PF, 1 PJ). examples: - 1 format: int64 type: integer required: - ispb type: object InboundCreditView: additionalProperties: false properties: dtHrCreditoSgct: description: The SGCT credit-commit instant (UTC, RFC 3339). examples: - "2024-09-20T04:00:01.001Z" type: string idCreditoSgct: description: The plugin-minted credit-entry id (GUID). examples: - 58F752C5-6376-3252-8305-A2DE3A8525D3 type: string idReqJdPi: description: The JDPI request id (echoed). examples: - f1e2d3c4-b5a6-7890-1234-567890abcdef type: string required: - idReqJdPi - idCreditoSgct - dtHrCreditoSgct type: object InboundDebtorBlock: additionalProperties: true properties: cpfCnpj: description: Debtor CPF or CNPJ (a v5.5.0 string). examples: - "04623217035" type: string nome: description: Debtor name/razao social. examples: - Ciclano da Silva type: string tpPessoa: description: Person type (0=Pessoa Fisica, 1=Pessoa Juridica). examples: - 0 format: int64 type: integer required: - tpPessoa - cpfCnpj - nome type: object InboundPayerBlock: additionalProperties: true properties: codMunIbge: description: Payer municipality IBGE code (7 digits). Carried for wire-completeness; the spec marks it Sim on 5.2.4, but the plugin does not consume or persist payer municipality this wave (the domain has no municipality field). examples: - 3550308 format: int64 type: integer cpfCnpj: description: Payer CPF or CNPJ (a v5.5.0 string). examples: - "11111111111" type: string ispb: description: Payer participant ISPB (8 digits, a v5.5.0 string). examples: - "99999004" type: string nrAgencia: description: Payer branch (nrAgencia, 4 digits, string; the branch source). examples: - "1234" type: string nrConta: description: Payer account number (nrConta, a string; NEVER the branch). examples: - "12345678" type: string tpPessoa: description: Person type (0=Pessoa Fisica, 1=Pessoa Juridica). examples: - 0 format: int64 type: integer required: - ispb - tpPessoa - cpfCnpj - nrConta type: object InboundRecipientBlock: additionalProperties: true properties: cnpj: description: Recipient CNPJ (14 digits, a v5.5.0 string). examples: - "61695227000193" type: string ispb: description: Recipient participant ISPB (8 digits, a v5.5.0 string). examples: - "04358798" type: string nome: description: Recipient legal/trade name (razao social). examples: - Enel type: string required: - ispb - cnpj - nome type: object Indirect: additionalProperties: false properties: createdAt: description: Creation timestamp (UTC). format: date-time type: string delivery: $ref: "#/components/schemas/IndirectDelivery" description: Delivery endpoint (secret redacted). indirectId: description: The indirect participant id (routing identifier). examples: - 018f2b7c-0000-7000-8000-000000000000 type: string ispb: description: The indirect PSP's ISPB. examples: - "12345678" type: string messagingMode: description: Delivery mode. examples: - raw type: string name: description: Display name. examples: - Indirect PSP Ltda type: string piAccountAlias: description: The derived @pi_{ispb} Midaz account alias. examples: - "@pi_12345678" type: string provisioning: $ref: "#/components/schemas/IndirectProvisioning" description: Legacy provisioning state. Always present as an object; its failedStep is always null for a row registered by this service. qrCertificate: $ref: "#/components/schemas/IndirectQRCertificate" description: Own-QR-code certificate configuration. status: description: Lifecycle status. examples: - ACTIVE type: string updatedAt: description: Last-update timestamp (UTC). format: date-time type: string required: - indirectId - name - ispb - status - piAccountAlias - messagingMode - delivery - qrCertificate - provisioning - createdAt - updatedAt type: object IndirectDelivery: additionalProperties: false properties: endpointUrl: description: The HTTPS delivery endpoint. examples: - https://indirect.example.com/pix type: string secret: description: Always redacted. examples: - "***" type: string required: - endpointUrl - secret type: object IndirectPage: additionalProperties: false properties: items: description: The indirects on this page. items: $ref: "#/components/schemas/Indirect" type: - array - "null" nextCursor: description: Opaque cursor for the next page, or null when exhausted. type: string required: - items type: object IndirectProvisioning: additionalProperties: false properties: failedStep: description: "Legacy field: the registration step a PENDING_PROVISIONING row stopped at. Always null for an indirect registered by this service, since a failed registration leaves no row." examples: - createPIAccount type: - string - "null" required: - failedStep type: object IndirectQRCertificate: additionalProperties: false properties: ownCertificate: description: Whether the indirect hosts the dynamic-QR JWS/JWKS under its own certificate. False means it falls back to the direct participant. examples: - true type: boolean publicBaseUrl: description: The indirect's scheme-less public base URL for QR payload locations. Empty when ownCertificate is false. examples: - qr.indirect.example.com/pix type: string required: - ownCertificate - publicBaseUrl type: object IndirectTransaction: additionalProperties: false properties: amount: description: Movement amount, in centavos (integer). 1050 is R$ 10,50. examples: - 1050 format: int64 type: integer conciliationId: description: The QR conciliation id (txid), when the movement came from a QR code. examples: - CONC0001 type: string direction: description: CREDIT when the money entered the indirect's account, DEBIT when it left. enum: - CREDIT - DEBIT examples: - CREDIT type: string endToEndId: description: The SPI end-to-end id of the movement. examples: - E12345678202609011200000000000001 type: string occurredAt: description: When the movement was booked (UTC). It is the feed's primary sort key. format: date-time type: string payee: $ref: "#/components/schemas/IndirectTransactionParty" description: The receiving side — the indirect's own client on a credit. payer: $ref: "#/components/schemas/IndirectTransactionParty" description: The paying side. status: description: Settlement status of the movement. examples: - EXECUTED type: string required: - endToEndId - direction - amount - status - occurredAt - payer - payee type: object IndirectTransactionPage: additionalProperties: false properties: items: description: The movements on this page, oldest first. items: $ref: "#/components/schemas/IndirectTransaction" type: - array - "null" nextCursor: description: Opaque cursor for the next page, or null when the window has been walked to its end. type: - string - "null" required: - items - nextCursor type: object IndirectTransactionParty: additionalProperties: false properties: accountDigit: description: Party account check digit. examples: - "5" type: string accountNumber: description: Party account number. examples: - "9990001" type: string bankId: description: Party institution's ISPB. examples: - "12345678" type: string branch: description: Party branch (agência). examples: - "0001" type: string document: description: Party CPF/CNPJ. examples: - "12345678901" type: string key: description: PIX key the movement addressed, when it used one. examples: - payee@example.com type: string keyType: description: PIX key type (CPF, CNPJ, EMAIL, PHONE, RANDOM). examples: - EMAIL type: string name: description: Party name as captured at settlement. examples: - Acme Ltda type: string type: object InfractionListBody: additionalProperties: false properties: data: description: The list of detected infractions, newest first. items: $ref: "#/components/schemas/InfractionView" type: - array - "null" required: - data type: object InfractionView: additionalProperties: false properties: detalhes: description: Free-text detail to help the recebedor analyse. examples: - Suspected scam. type: string detalhesAnalise: description: Analysis detail. examples: - Confirmed. type: string dtHrCriacao: description: JDPI creation timestamp (RFC 3339 UTC). examples: - "2024-01-01T12:00:00.000Z" type: string dtHrUltModificacao: description: JDPI last-modification timestamp (RFC 3339 UTC) — the poll watermark. examples: - "2024-01-01T12:05:00.000Z" type: string endToEndId: description: EndToEndId of the suspect payment. examples: - E1234567820240101000000000000001 type: string idMarcacaoFraude: description: Fraud-marker GUID, when analysis produced one. examples: - c3d4e5f6-a7b8-9012-cdef-345678901234 type: string idRecValores: description: Value-recovery GUID, when the infraction came from a recovery. examples: - b2c3d4e5-f6a7-8901-bcde-f23456789012 type: string idRelatoInfracao: description: Infraction GUID (the natural key). examples: - a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string motivo: description: Infraction motivo code (1=Solicitacao de devolucao, 2=Cancelamento da devolucao). examples: - 1 format: int64 type: integer motivoDescription: description: Human-readable infraction motivo label. examples: - Solicitacao de devolucao type: string pspContraParte: description: ISPB of the counterparty. examples: - "87654321" type: string pspCriador: description: ISPB of the infraction creator. examples: - "12345678" type: string resultadoAnalise: description: Infraction analysis result (0=Aceita, 1=Rejeitada); null until analysed. examples: - 0 format: int64 type: integer resultadoAnaliseDescription: description: Human-readable infraction analysis-result label. examples: - Aceita type: string status: description: stRelatoInfracao lifecycle code (0=Aberto, 1=Recebido, 2=Cancelado, 3=Analisado). examples: - 0 format: int64 type: integer statusDescription: description: Human-readable stRelatoInfracao label. examples: - Aberto type: string tpSitOrigem: description: Situation-origin code (0..5). examples: - 0 format: int64 type: integer tpSitOrigemDescription: description: Human-readable tpSitOrigem label. examples: - Golpe/Estelionato type: string vlrInfracao: description: Amount to block on the account, in centavos; null when absent. examples: - 15000 format: int64 type: integer required: - idRelatoInfracao - endToEndId - motivo - motivoDescription - tpSitOrigem - tpSitOrigemDescription - status - statusDescription - pspCriador - pspContraParte - dtHrCriacao - dtHrUltModificacao type: object JWKSet: additionalProperties: false properties: keys: description: The JSON Web Keys, exactly as JDPI extracted them from the indirect's CERTQRC certificate. items: additionalProperties: {} type: object type: - array - "null" required: - keys type: object ListAuthorizationsResponse: additionalProperties: false properties: authorizations: description: The matching authorization snapshots. items: $ref: "#/components/schemas/AuthorizationResponse" type: - array - "null" jdPiAt: description: JDPI response timestamp (dtHrJdPi, UTC). examples: - "2024-06-19T00:00:00Z" type: string required: - jdPiAt - authorizations type: object ListQRResponse: additionalProperties: false properties: cobvQrCodes: description: The due-date dynamic QR codes (qrCodeDinamicoCobv). items: $ref: "#/components/schemas/ListedCobvQRResponse" type: - array - "null" consultedAt: description: The JDPI consult timestamp (dtHrJdPi). examples: - "2024-11-26T18:08:49.025Z" type: string dynamicQrCodes: description: The immediate-dynamic QR codes (qrCodeDinamico). items: $ref: "#/components/schemas/ListedDynamicQRResponse" type: - array - "null" recurrenceQrCodes: description: The recurrence-only composite QR codes (qrCodeRecorrencia). items: $ref: "#/components/schemas/ListedRecurrenceQRResponse" type: - array - "null" staticQrCodes: description: The static QR codes (qrCodeEstatico). items: $ref: "#/components/schemas/ListedStaticQRResponse" type: - array - "null" required: - consultedAt - staticQrCodes - dynamicQrCodes - cobvQrCodes - recurrenceQrCodes type: object ListSchedulesResponse: additionalProperties: false properties: jdPiAt: description: JDPI response timestamp (dtHrJdPi, UTC). examples: - "2024-06-08T06:00:05Z" type: string schedules: description: The matching schedule snapshots (agendamentos). items: $ref: "#/components/schemas/ScheduleResponse" type: - array - "null" required: - jdPiAt - schedules type: object ListedCobvQRResponse: additionalProperties: false properties: categoryCode: description: Recipient category code (codigoCategoria). examples: - "0000" type: string city: description: Recipient city (cidade). examples: - Sao Paulo type: string conciliationId: description: Conciliation id (idConciliacaoRecebedor). examples: - TX-001 type: string daysAfterDue: description: Days after the due date the charge stays payable (diasAposVenc). examples: - 30 format: int64 type: integer description: description: Additional-data entries (dadosAdicionais). items: $ref: "#/components/schemas/AdditionalDataBody" type: - array - "null" discount: description: Early-payment discount in centavos (desconto). examples: - 200 format: int64 type: integer documentId: description: The JDPI charge GUID (idDocumento). examples: - 52c43361-caa1-4ddb-9152-708426a25db3 type: string dueDate: description: Payment due date (dtVenc; aaaa-mm-dd). examples: - "2026-01-30" type: string finalAmount: description: Final payable amount in centavos (valorFinal). examples: - 10400 format: int64 type: integer fine: description: Late fine in centavos (multa). examples: - 400 format: int64 type: integer format: description: JDPI formato (0=image, 1=payload, 2=both). examples: - 1 format: int64 type: integer interest: description: Late interest in centavos (juros). examples: - 300 format: int64 type: integer key: description: The recipient PIX key. examples: - recipient@bank.com type: string originalAmount: description: Amount before interest/fine, in centavos (valorOriginal). examples: - 10000 format: int64 type: integer payerCnpj: description: Payer CNPJ (cnpjPagador). examples: - "01234567000199" type: string payerCpf: description: Payer CPF (cpfPagador). examples: - "01234567890" type: string payerName: description: Payer name (nomePagador). examples: - John Doe type: string payerRequest: description: Text shown to the payer (solicitacaoPagador). examples: - Informe o pedido type: string payloadUrl: description: JWS host URL (urlPayloadJson). examples: - pix.example.com/qr/abc type: string rebate: description: Rebate in centavos (abatimento). examples: - 100 format: int64 type: integer recipientCnpj: description: Recipient CNPJ (cnpjRecebedor). examples: - "61695227000193" type: string recipientCpf: description: Recipient CPF (cpfRecebedor). examples: - "01234567890" type: string recipientName: description: Recipient name (nomeRecebedor). examples: - Jane Doe type: string recipientStreet: description: Recipient street (logradouroRecebedor). examples: - Rua 1 type: string recipientTradeName: description: Recipient trade name (nomeFantasiaRecebedor). examples: - Jane ME type: string recurrence: $ref: "#/components/schemas/ListedRecurrenceResponse" description: Recurrence configuration (dadosRecorrencia; qrCodeType 17 only). reusable: description: Whether the QR can be reused (reutilizavel). examples: - false type: boolean state: description: Recipient federal unit (uf). examples: - SP type: string status: description: Charge status (0=Active..3=Removed by PSP). examples: - 0 format: int64 type: integer zipCode: description: Recipient postal code (cep). examples: - "01310100" type: string required: - documentId - format - key - recipientName - recipientStreet - city - state - zipCode - payerName - originalAmount - rebate - discount - interest - fine - finalAmount - dueDate - daysAfterDue - reusable - status type: object ListedDynamicQRResponse: additionalProperties: false properties: amount: description: Original amount in centavos (valorOriginal). examples: - 10050 format: int64 type: integer categoryCode: description: Recipient category code (codigoCategoria). examples: - "0000" type: string city: description: Recipient city (cidade). examples: - Sao Paulo type: string conciliationId: description: Conciliation id (idConciliacaoRecebedor). examples: - TX-001 type: string description: description: Additional-data entries (dadosAdicionais). items: $ref: "#/components/schemas/AdditionalDataBody" type: - array - "null" documentId: description: The JDPI charge GUID (idDocumento). examples: - 52c43361-caa1-4ddb-9152-708426a25db3 type: string expirationTime: description: QR expiration in seconds (expiracaoQR). examples: - 3600 format: int64 type: integer format: description: JDPI formato (0=image, 1=payload, 2=both). examples: - 1 format: int64 type: integer key: description: The recipient PIX key. examples: - recipient@bank.com type: string payloadUrl: description: JWS host URL (urlPayloadJson). examples: - pix.example.com/qr/abc type: string recipientName: description: Recipient name (nomeRecebedor). examples: - Jane Doe type: string recurrence: $ref: "#/components/schemas/ListedRecurrenceResponse" description: Recurrence configuration (dadosRecorrencia; qrCodeType 16 only). status: description: Charge status (0=Active..3=Removed by PSP). examples: - 0 format: int64 type: integer zipCode: description: Recipient postal code (cep). examples: - "01310100" type: string required: - documentId - format - key - recipientName - city - amount - status type: object ListedRecurrenceQRResponse: additionalProperties: false properties: amount: description: Payment amount in centavos (valor). examples: - 1050 format: int64 type: integer certificateIspb: description: Indirect PSP certificate ISPB (ispbCertificadoJws). examples: - "04358798" type: string city: description: Transaction city (cidade). examples: - Sao Paulo type: string conciliationId: description: Conciliation id (idConciliacaoRecebedor). examples: - TX-001 type: string contractDescription: description: Free-text contract note (descContrato). examples: - Conta de energia type: string contractNumber: description: Authorization object id (nrContrato). examples: - 1234567890ABC type: string debtor: $ref: "#/components/schemas/RecurrenceDebtorResponse" description: Recurrence debtor (devedor). documentId: description: The JDPI recurrence GUID (idDocumento). examples: - 52c43361-caa1-4ddb-9152-708426a25db3 type: string endDate: description: Last expected payment (dtFinalRecorrencia). examples: - "2026-01-10" type: string format: description: JDPI formato (0=image, 1=payload, 2=both). examples: - 1 format: int64 type: integer frequency: description: Payment frequency (tpFrequencia; 0=weekly..4=annual). examples: - 4 format: int64 type: integer jwkUrl: description: JWK Set URL (urlJwk). examples: - pix.example.com/jwks type: string maxFloorAmount: description: Recipient-defined floor in centavos (pisoValorMaximo). examples: - 55000 format: int64 type: integer payloadUrl: description: JWS host URL (urlPayloadJson). examples: - pix.example.com/qr/abc type: string recipient: $ref: "#/components/schemas/RecurrenceRecipientResponse" description: Recurrence recipient (recebedor). recurrenceId: description: Recurrence id (idRecorrencia). examples: - RR0435879820240605njua7shf40o type: string retryPolicy: description: Retry policy (retentativa; 0=none, 1=up to 3 retries). examples: - 1 format: int64 type: integer startDate: description: First expected payment (dtInicialRecorrencia). examples: - "2024-01-10" type: string updates: description: Recurrence status history (atualizacoes). items: $ref: "#/components/schemas/RecurrenceUpdateResponse" type: - array - "null" required: - documentId - format - city - recurrenceId - frequency - startDate - amount - maxFloorAmount - recipient - debtor - contractNumber - retryPolicy type: object ListedRecurrenceResponse: additionalProperties: false properties: amount: description: Payment amount in centavos (valor). examples: - 1050 format: int64 type: integer certificateIspb: description: Indirect PSP certificate ISPB (ispbCertificadoJws). examples: - "04358798" type: string contractDescription: description: Free-text contract note (descContrato). examples: - Conta de energia type: string contractNumber: description: Authorization object id (nrContrato). examples: - 1234567890ABC type: string debtor: $ref: "#/components/schemas/RecurrenceDebtorResponse" description: Recurrence debtor (devedor). endDate: description: Last expected payment (dtFinalRecorrencia; aaaa-mm-dd). examples: - "2026-01-10" type: string frequency: description: Payment frequency (tpFrequencia; 0=weekly..4=annual). examples: - 1 format: int64 type: integer jwkUrl: description: JWK Set URL (urlJwk). examples: - pix.example.com/jwks type: string maxFloorAmount: description: Recipient-defined floor in centavos (pisoValorMaximo). examples: - 55000 format: int64 type: integer payloadUrl: description: JWS host URL (urlPayloadJson). examples: - pix.example.com/qr/abc type: string recipient: $ref: "#/components/schemas/RecurrenceRecipientResponse" description: Recurrence recipient (recebedor). recurrenceId: description: Recurrence id (idRecorrencia). examples: - RR0435879820240605njua7shf40o type: string retryPolicy: description: Retry policy (retentativa; 0=none, 1=up to 3 retries). examples: - 1 format: int64 type: integer startDate: description: First expected payment (dtInicialRecorrencia; aaaa-mm-dd). examples: - "2024-01-10" type: string updates: description: Recurrence status history (atualizacoes). items: $ref: "#/components/schemas/RecurrenceUpdateResponse" type: - array - "null" required: - recurrenceId - frequency - startDate - amount - maxFloorAmount - recipient - debtor - contractNumber - retryPolicy type: object ListedStaticQRResponse: additionalProperties: false properties: additionalData: description: Free-text additional data (dadosAdicionais). examples: - Invoice 42 type: string amount: description: Transaction amount in centavos. examples: - 10050 format: int64 type: integer categoryCode: description: Recipient category code (codigoCategoria). examples: - "0000" type: string city: description: Recipient city (cidade). examples: - Sao Paulo type: string conciliationId: description: Conciliation id (idConciliacaoRecebedor). examples: - "***" type: string format: description: JDPI formato (0=image, 1=payload, 2=both). examples: - 0 format: int64 type: integer ispbFss: description: Pix Saque facilitator ISPB. examples: - "04358798" type: string key: description: The recipient PIX key. examples: - recipient@bank.com type: string recipientName: description: Recipient name (nomeRecebedor). examples: - Jane Doe type: string recurrence: $ref: "#/components/schemas/ListedRecurrenceResponse" description: Recurrence configuration (dadosRecorrencia; qrCodeType 15 only). zipCode: description: Recipient postal code (cep). examples: - "01310100" type: string required: - format - key - amount - recipientName - city type: object ParticipantItem: additionalProperties: false properties: cnpj: description: The participant CNPJ. examples: - "04358798000107" type: string endedAt: description: When the participant was removed from JDPI (dtHrFimPsp), yyyy-mm-ddTHH:mm:ss. examples: - "2020-12-09T22:00:00" type: string ispb: description: The participant ISPB (§8.6.1 String(8); leading zeros are significant). examples: - "04358798" type: string legalName: description: The participant legal name (razão social). examples: - Banco JDConsultores type: string modality: description: "Pix arrangement modality (modalidade): 1 = transactional-account provider, 2 = government entity, 3 = special settler, 4 = user institution." examples: - 1 format: int64 type: integer participantType: description: "SPI participation type (tpPsp): 1 = direct participant, 2 = indirect participant." examples: - 1 format: int64 type: integer shortName: description: The participant short name (nome reduzido). examples: - Banco JD type: string startedAt: description: When the participant was added to JDPI (dtHrInicioPsp), yyyy-mm-ddTHH:mm:ss. examples: - "2020-11-03T06:00:01" type: string status: description: "SPI participation status (stPsp): 1 = active, 2 = inactive, 3 = awaiting BACEN activation, 4 = activation failed." examples: - 1 format: int64 type: integer required: - ispb - shortName - participantType - status type: object ParticipantsBody: additionalProperties: false properties: data: description: The SPI participant directory, ordered by ISPB as JDPI returns it. items: $ref: "#/components/schemas/ParticipantItem" type: - array - "null" required: - data type: object PartyResponse: additionalProperties: false properties: accountDigit: description: The party's account check digit. examples: - "7" type: string accountId: description: The party's CRM account id. examples: - acc-123 type: string accountNumber: description: The party's account number. examples: - "123456" type: string accountType: description: Numeric JDPI tpConta (0=Conta Corrente, 1=Conta Salario, 2=Conta Poupanca, 3=Conta de Pagamento, 4=Conta PI). examples: - 0 format: int64 type: integer branch: description: The party's agency/branch. examples: - "0001" type: string document: description: The party's document (CPF/CNPJ). examples: - "12345678909" type: string ispb: description: The party's participant ISPB. examples: - "12345678" type: string key: description: The party's PIX key. examples: - foo@bar.com type: string keyType: description: Numeric eKeyType. examples: - 2 format: int64 type: integer name: description: The party's holder name. examples: - Jane Doe type: string 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 PayeeBody: additionalProperties: false properties: accountDigit: description: Recipient account check digit. examples: - "7" type: string accountNumber: description: Recipient account number. examples: - "123456" type: string accountType: description: "Recipient JDPI tpConta (0=Conta Corrente, 1=Conta Salario, 2=Conta Poupanca, 3=Conta de Pagamento, 4=Conta PI). REQUIRED and never defaulted: JDPI section 8.4.1 marks recebedor.tpConta mandatory and its domain has no 'unknown' member, so sending 0 for an account you have not identified asserts 'Conta Corrente' about a savings or payment account and settles the money against a false type. Take it from decode-QRCode (section 8.3.3) or consultar-chave (section 8.2.14), which both return it, or from the recipient details on a manually-typed order." examples: - 0 format: int64 type: integer branch: description: Recipient agency/branch. examples: - "0001" type: string document: description: Recipient document (CPF/CNPJ). examples: - "12345678909" type: string ispb: description: Recipient participant ISPB (equal to the plugin ISPB routes on-us). examples: - "12345678" type: string key: description: Recipient PIX key, when the payment targets a key. examples: - foo@bar.com type: string name: description: Recipient holder name. examples: - Jane Doe type: string required: - ispb - document - accountNumber - accountDigit - accountType 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 PayerBody: additionalProperties: false properties: document: description: Payer document (CPF/CNPJ). examples: - "12345678909" type: string name: description: Payer holder name (only forwarded with a document). examples: - Jane Doe type: string validate: description: Whether the payer document must be validated at settlement. examples: - false type: boolean type: object QRCodeResponse: additionalProperties: false properties: documentId: description: The JDPI charge GUID (idDocumento) addressing the update leg (dynamic only). examples: - 52c43361-caa1-4ddb-9152-708426a25db3 type: string payloadJws: description: "The signed JWS payload, returned ONLY when the QR was generated under an indirect participant's own certificate — that indirect hosts it at payloadUrl on its own infrastructure. Absent on the direct path, where the plugin self-hosts it. It is returned ONCE and never stored: if this response is lost, do NOT re-create (the same recipientConciliationId is refused as a duplicate) — read the charge's documentId from GET /v1/qrcodes/list and re-sign it via PUT /v1/qrcodes/dynamic/{documentId} with the same indirectId, which returns a fresh payloadJws on a fresh payloadUrl." examples: - eyJhbGciOiJFUzI1NiJ9.eyJyZXYiOjB9.sig type: string payloadUrl: description: The resolvable JWS host URL the dynamic QR embeds (urlPayloadJson; schema-less; dynamic only). examples: - pix.example.com/qr/cob/fzqRwuXYSweWofLD1OX2Bw type: string qrCode: description: The generated EMV QR-code payload (base64-decoded, ready to render). examples: - 00020126... type: string required: - qrCode type: object RecoveryListBody: additionalProperties: false properties: data: description: The list of value recoveries. items: $ref: "#/components/schemas/RecoveryView" type: - array - "null" required: - data type: object RecoveryView: additionalProperties: false properties: breached: description: True when the devolver deadline has been reached or passed (computed at read time); false when no deadline is set. examples: - false type: boolean contatoEmail: description: Creator-contact email. examples: - ops@example.com type: string contatoTelefone: description: Creator-contact phone. examples: - "+5511999999999" type: string detalhes: description: Free-text detail (required when tpSituacao=4 Outros). examples: - Suspected scam. type: string devolverDeadline: description: Creator-side 72h devolver deadline (RFC 3339 UTC; contract §2.22/§5), from the Analise stage close; null unless this institution is the pspCriador on an Analisada recovery. examples: - "2024-01-04T12:00:00.000Z" type: string dictCorrelationId: description: idCorrelacao — the DICT support identifier for this consultar call; quote it to JD when disputing whether the read happened. examples: - a9f13566e19f5ca51329479a5bae60c5 type: string dictReturnedAt: description: dtHrRetornoDict — when DICT answered this consultar (contract 2.21). examples: - "2025-08-27T10:30:05.025Z" type: string dtHrCriacao: description: JDPI creation timestamp (RFC 3339 UTC). examples: - "2024-01-01T12:00:00.000Z" type: string dtHrUltModificacao: description: JDPI last-modification timestamp (RFC 3339 UTC) — the watermark. examples: - "2024-01-01T12:05:00.000Z" type: string idRecValores: description: Value-recovery GUID (the natural key). examples: - b2c3d4e5-f6a7-8901-bcde-f23456789012 type: string idTransacaoRaiz: description: EndToEndId of the root transaction being recovered. examples: - E1234567820240101000000000000001 type: string pspCriador: description: ISPB of the recovery creator. examples: - "12345678" type: string status: description: stRecValores lifecycle code (0=Criada .. 6=Cancelada). examples: - 0 format: int64 type: integer statusDescription: description: Human-readable stRecValores label. examples: - Criada type: string tpSituacao: description: Situation code (0..5). examples: - 0 format: int64 type: integer tpSituacaoDescription: description: Human-readable tpSituacao label. examples: - Golpe/Estelionato type: string required: - idRecValores - idTransacaoRaiz - tpSituacao - tpSituacaoDescription - contatoEmail - contatoTelefone - pspCriador - status - statusDescription - dtHrCriacao - dtHrUltModificacao - breached type: object RecurrenceCompositeBody: additionalProperties: false properties: accountId: description: The CRM account id of the recipient (sources name + city). examples: - acc-123 type: string certificateIspb: description: Indirect-PSP certificate ISPB (ispbCertificadoJws, string). examples: - "04358798" type: string jwkUrl: description: JWK Set URL (urlJwk; no scheme). examples: - example.com/jwks type: string recurrence: $ref: "#/components/schemas/CompositeRecurrenceBody" description: The embedded recurrence configuration (dadosRecorrencia). recurrencePayloadUrl: description: Recurrence JWS host URL (urlPayloadJsonRec; no scheme). examples: - pix.example.com/rec/abc type: string txId: description: Conciliation id (idConciliacaoRecebedor). examples: - JDPI2024110800000000000000000000001 type: string required: - accountId - recurrencePayloadUrl - jwkUrl - recurrence type: object RecurrenceDebtorResponse: additionalProperties: false properties: cpfCnpj: description: Debtor CPF or CNPJ. examples: - "04623217035" type: string name: description: Debtor name. examples: - Ciclano da Silva type: string personType: description: Debtor person type (tpPessoa; 0=natural, 1=legal). examples: - 0 format: int64 type: integer required: - personType - cpfCnpj - name type: object RecurrenceRecipientResponse: additionalProperties: false properties: cnpj: description: Recipient CNPJ. examples: - "61695227000193" type: string ispb: description: Recipient participant ISPB. examples: - "04358798" type: string name: description: Recipient legal/trade name. examples: - Enel type: string required: - ispb - cnpj - name type: object RecurrenceUpdateResponse: additionalProperties: false properties: status: description: Recurrence status (stRecorrencia; 0=created..4=cancelled). examples: - 0 format: int64 type: integer statusDateTime: description: When the status was set (dtHrSituacao). examples: - "2024-11-08T14:25:49.025Z" type: string required: - status - statusDateTime type: object RefundBody: additionalProperties: false properties: accountId: description: The requesting account (the original payee). examples: - acc-123 type: string amount: description: Refund amount in centavos (must be greater than zero). examples: - 5000 format: int64 type: integer clientRequestId: description: Optional client idempotency token. A retry carrying the same value replays the existing refund instead of creating a duplicate (intra-PSP double-refund protection); omit to opt out. examples: - req-2025-01-01-abc123 type: string code: description: PIX return reason (BE08/FR01/MD06/SL02). examples: - MD06 type: string description: description: Free-text refund description. examples: - Wrong amount type: string endToEndId: description: The original transaction's end-to-end id. examples: - E1234567890 type: string transactionId: description: The original transaction id (UUID). examples: - d1f9c0a2-... type: string required: - endToEndId - accountId - transactionId - code - amount type: object RefundCreditStatusView: additionalProperties: false properties: codigoDevolucao: description: Refund code (BE08=MED iniciada pelo participante do recebedor, FR01=fundada suspeita de fraude, MD06=solicitada pelo usuario recebedor, SL02=erro/desacordo no Pix Saque ou Troco). examples: - BE08 type: string codigoErro: description: Error code, present when stJdPi is -1. examples: - AB03 type: string descCodigoErro: description: Error-code description, present when stJdPi is -1. examples: - Liquidacao interrompida type: string dtHrSituacao: description: When the refund order reached this situation in JDPI (raw JDPI instant). examples: - "2020-01-24T10:30:00.000Z" type: string ehIntraPsp: description: True when the transaction is internal to this direct PSP (both legs on the same participant). examples: - false type: boolean endToEndIdDevolucao: description: EndToEndId of the refund (pacs.004) whose credit is being consulted. examples: - D1234567820240101000000000000099 type: string stJdPi: description: "Request situation: -1=erro no processamento, 0=requisicao recebida aguardando processamento, 9=credito efetivado com sucesso." examples: - 9 format: int64 type: integer stJdPiProc: description: "CREDIT-side processing situation: 0=requisicao recebida aguardando processamento, 1=credito validado aguardando efetivacao pelo SGCT, 2=validacao de credito enviada ao SPI, 5=sem retorno terminativo do SPI, 7=devolucao recusada pelo SPI, 8=devolucao recusada pelo JDPI, 9=credito efetivado com sucesso. A DISTINCT domain from the debit poll's stJdPiProc despite the shared field name." examples: - 9 format: int64 type: integer valorDevolucao: description: Refunded amount, in centavos; omitted when JDPI did not return it (Obrg=Nao). examples: - 5010 format: int64 type: integer required: - endToEndIdDevolucao - dtHrSituacao - stJdPiProc - stJdPi - codigoDevolucao - ehIntraPsp type: object RefundRequestListBody: additionalProperties: false properties: data: description: The list of detected refund requests, newest first. items: $ref: "#/components/schemas/RefundRequestView" type: - array - "null" required: - data type: object RefundRequestView: additionalProperties: false properties: analysisDeadline: description: Contestado-side analysis deadline (RFC 3339 UTC; contract §5, 6h Fraude / 48h otherwise); null for filer-side and terminal requests. examples: - "2024-01-01T18:00:00.000Z" type: string breached: description: True when the analysis deadline has been reached or passed (computed at read time); false when no deadline is set. examples: - false type: boolean detalhes: description: Free-text detail. examples: - Operational failure. type: string detalhesAnalise: description: Analysis detail. examples: - Insufficient balance. type: string dtHrCriacao: description: JDPI creation timestamp (RFC 3339 UTC). examples: - "2024-01-01T12:00:00.000Z" type: string dtHrRegistro: description: dtHrRegistro — when the request was REGISTERED in the JDPI base (raw JDPI instant), distinct from dtHrCriacao (the DICT creation instant). Returned by the §8.2.26 JDPI-base read only. examples: - "2021-08-06T10:33:08.241Z" type: string dtHrUltModificacao: description: JDPI last-modification timestamp (RFC 3339 UTC) — the poll watermark. examples: - "2024-01-01T12:05:00.000Z" type: string endToEndId: description: EndToEndId of the contested payment or devolucao. examples: - E1234567820240101000000000000001 type: string endToEndIdDevolucao: description: pacs.004/pacs.008 devolucao reference, recorded at analysis. examples: - D1234567820240101000000000000099 type: string idRecValores: description: Value-recovery GUID, when from a recovery. examples: - b2c3d4e5-f6a7-8901-bcde-f23456789012 type: string idRelatoInfracao: description: Linked infraction GUID, when fraud. examples: - a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string idSolDevolucao: description: Refund-request GUID (the natural key). examples: - d4e5f6a7-b8c9-0123-def4-56789012345a type: string ispbContestado: description: ISPB of the contested PSP. examples: - "87654321" type: string ispbSolicitante: description: ISPB of the requesting PSP. examples: - "12345678" type: string motivo: description: Refund motivo code (0=Falha Operacional, 1=Fraude, 3=Pix Automatico). examples: - 1 format: int64 type: integer motivoDescription: description: Human-readable refund motivo label. examples: - Fraude type: string motivoRejeicao: description: Rejection reason (0,1,3,4); present only when the analysis rejected the request. examples: - 0 format: int64 type: integer motivoRejeicaoDescription: description: Human-readable rejection-reason label. examples: - Falta de saldo type: string resultadoAnalise: description: Refund analysis result (0=Aceita Totalmente, 1=Aceita Parcialmente, 2=Rejeitada); null until analysed. examples: - 0 format: int64 type: integer resultadoAnaliseDescription: description: Human-readable refund analysis-result label. examples: - Aceita Totalmente type: string status: description: stSolDevolucao lifecycle code (0=Aberta, 1=Cancelada, 2=Analisada). examples: - 0 format: int64 type: integer statusDescription: description: Human-readable stSolDevolucao label. examples: - Aberta type: string valorDevolucao: description: Requested refund amount, in centavos. examples: - 25000 format: int64 type: integer valorDevolvido: description: Amount actually refunded, in centavos; null when absent. examples: - 25000 format: int64 type: integer required: - idSolDevolucao - endToEndId - motivo - motivoDescription - valorDevolucao - status - statusDescription - ispbSolicitante - ispbContestado - dtHrCriacao - dtHrUltModificacao - breached type: object RefundResponse: additionalProperties: false properties: accountId: description: The refunding account id. examples: - ext-acc-123 type: string amount: description: Refund amount in centavos. examples: - 5000 format: int64 type: integer code: description: The PIX return reason. examples: - MD06 type: string description: description: Refund description. examples: - Wrong amount type: string endToEndId: description: The original transaction's end-to-end id. examples: - E1234567890 type: string endToEndRefundId: description: The refund's own end-to-end id. examples: - D1234567890 type: string id: description: The created refund id. examples: - a2f9c0d1-... type: string status: description: eTransactionStatus name. examples: - EXECUTED type: string required: - id - accountId - code - endToEndId - endToEndRefundId - amount - status type: object RegisterAuthorizationBody: additionalProperties: true properties: descContrato: description: Free-text contract description (35-char). examples: - Conta de energia type: string devedor: $ref: "#/components/schemas/InboundDebtorBlock" description: The devedor, sent only when it differs from the payer. dtFinalRecorrencia: description: Last payment date (aaaa-mm-dd). examples: - "2026-01-10" type: string dtHrAutorizacaoRecorrencia: description: Authorization timestamp (UTC). examples: - "2024-09-20T14:11:27.453Z" type: string dtHrCriacaoRecorrencia: description: Recurrence creation timestamp (UTC). examples: - "2024-09-20T09:25:49.025Z" type: string dtInicialRecorrencia: description: First payment date (aaaa-mm-dd). examples: - "2024-01-10" type: string idRecorrencia: description: Unique recurrence id (29-char, RR...). examples: - RR0435879820240920njua7shf40o type: string idReqJdPi: description: JDPI request id (36-char GUID). examples: - 45F763C6-7487-4363-9406-A1DE2A9636D3 type: string jornada: description: Authorization journey (2..4). examples: - 2 format: int64 type: integer motivoRejeicao: description: Rejection reason code (4-char; required when resultadoAutorizacao=false). examples: - AP13 type: string nrContrato: description: Contract/order identifier (35-char). examples: - 1234567890ABC type: string pagador: $ref: "#/components/schemas/InboundPayerBlock" description: The recurrence pagador. The spec marks pagador.codMunIbge Sim on 5.2.4, but it is accepted-not-consumed this wave (the domain has no municipality field). recebedor: $ref: "#/components/schemas/InboundRecipientBlock" description: The recurrence recebedor. resultadoAutorizacao: description: Payer analysis result (true=Aceita, false=Rejeitada). examples: - true type: boolean retentativa: description: Retry policy (0=none, 1=up to 3 in 7 days). examples: - 1 format: int64 type: integer tpFrequencia: description: Recurrence periodicity (0..4). examples: - 4 format: int64 type: integer valor: description: Fixed payment amount in reais (a JSON number). examples: - 550 format: double type: number required: - idReqJdPi - idRecorrencia - resultadoAutorizacao - retentativa - jornada - tpFrequencia - dtInicialRecorrencia - recebedor - pagador - nrContrato - dtHrCriacaoRecorrencia - dtHrAutorizacaoRecorrencia type: object RegisterAuthorizationResponse: additionalProperties: false properties: dtHrSgct: description: SGCT registration timestamp (UTC). examples: - "2024-11-27T22:10:05.025Z" type: string idReqJdPi: description: Echoed JDPI request id (36-char GUID). examples: - 45F763C6-7487-4363-9406-A1DE2A9636D3 type: string idSgct: description: Local SGCT authorization id (36-char GUID). examples: - 69F963C6-7487-4363-9406-A1DE2A9636D4 type: string required: - idReqJdPi - idSgct - dtHrSgct type: object RegisterCancellationBody: additionalProperties: true properties: codigoErro: description: JDPI error code (100-char; on a rejected cancellation). examples: - "" type: string cpfCnpjSolCancelamento: description: Requester CPF/CNPJ (a v5.5.0 string). examples: - "77379362038" type: string descCodigoErro: description: JDPI error description (1000-char). examples: - "" type: string descContrato: description: Free-text contract description (35-char). examples: - Conta de energia type: string devedor: $ref: "#/components/schemas/InboundDebtorBlock" description: The devedor, sent only when it differs from the payer. dtFinalRecorrencia: description: Last payment date (aaaa-mm-dd). examples: - "2026-01-10" type: string dtHrCancelamento: description: Cancellation timestamp (UTC). examples: - "2024-09-23T10:10:06.101Z" type: string dtHrCriacaoRecorrencia: description: Recurrence creation timestamp (UTC). examples: - "2024-09-20T09:25:49.025Z" type: string dtInicialRecorrencia: description: First payment date (aaaa-mm-dd). examples: - "2024-01-10" type: string idCancelamento: description: Unique cancellation id (29-char, IC...). examples: - IC0435879820240605bcdb1fhn43a type: string idRecorrencia: description: Unique recurrence id (29-char, RR...). examples: - RR0435879820240920njua7shf40o type: string motivoCancelamento: description: Cancellation reason (0..10). examples: - 6 format: int64 type: integer nrContrato: description: Contract/order identifier (35-char). examples: - 1234567890ABC type: string pagador: $ref: "#/components/schemas/InboundPayerBlock" description: The recurrence pagador. recebedor: $ref: "#/components/schemas/InboundRecipientBlock" description: The recurrence recebedor. stCancelamento: description: Cancellation status (0=Aceito, 1=Rejeitado). examples: - 0 format: int64 type: integer tpFrequencia: description: Recurrence periodicity (0..4). examples: - 4 format: int64 type: integer tpPessoaSol: description: Requester person type (0=PF, 1=PJ). examples: - 0 format: int64 type: integer valor: description: Fixed payment amount in reais (a JSON number). examples: - 550 format: double type: number required: - idRecorrencia - idCancelamento - stCancelamento - tpPessoaSol - cpfCnpjSolCancelamento - motivoCancelamento - tpFrequencia - dtInicialRecorrencia - recebedor - pagador - nrContrato type: object RegisterCancellationResponse: additionalProperties: false properties: dtHrSgct: description: SGCT registration timestamp (UTC). examples: - "2024-11-27T22:10:05.025Z" type: string idSgct: description: Local SGCT cancellation id (36-char GUID). examples: - 69F963C6-7487-4363-9406-A1DE2A9636D4 type: string required: - idSgct - dtHrSgct type: object RegisterEntryBody: additionalProperties: false properties: accountId: description: The CRM account id of the key owner. examples: - acc-123 type: string isValidated: description: "Ignored: the service always forces validation to start fresh." examples: - false type: boolean key: description: The PIX key value (omit for a RANDOM key). examples: - foo@bar.com type: string keyType: description: Numeric eKeyType (0=CPF,1=CNPJ,2=EMAIL,3=PHONE,4=RANDOM). examples: - 2 format: int64 type: integer required: - keyType - accountId type: object RegisterFraudMarkerRequestBody: additionalProperties: false properties: chave: description: The flagged Pix key, if known. examples: - user@example.com type: string cpfCnpj: description: The flagged document. examples: - "12345678901" type: string idempotencyKey: description: "Client-supplied idempotency key: any stable business string. The plugin projects it deterministically into the GUID form JDPI requires (contract 6), so the same value always dedups against the same JDPI request and the raw value is never sent verbatim." examples: - med-fraud-2024-0001 type: string tpFraude: description: Fraud-type code on create (0=Falsidade ideologica, 1=Conta laranja, 2=Conta do fraudador, 3=Outra; 4 Desconhecida is read-only). examples: - 1 format: int64 type: integer tpPessoa: description: Person-type code (0=Pessoa Fisica, 1=Pessoa Juridica). examples: - 0 format: int64 type: integer required: - tpPessoa - cpfCnpj - tpFraude - idempotencyKey type: object RegisterRequestBody: additionalProperties: true properties: descContrato: description: Free-text contract description (35-char). examples: - Conta de energia type: string devedor: $ref: "#/components/schemas/InboundDebtorBlock" description: The devedor, sent only when it differs from the payer. dtFinalRecorrencia: description: Last payment date (aaaa-mm-dd). examples: - "2026-01-10" type: string dtHrCriacaoRecorrencia: description: Recurrence creation timestamp (UTC). examples: - "2024-06-05T14:25:49.025Z" type: string dtHrCriacaoSolicitacao: description: Solicitation creation timestamp (UTC). examples: - "2024-06-05T14:25:49.025Z" type: string dtHrExpiracaoSolicitacao: description: Solicitation expiration timestamp (UTC). examples: - "2024-06-15T14:25:49.025Z" type: string dtInicialRecorrencia: description: First payment date (aaaa-mm-dd). examples: - "2024-01-10" type: string idRecorrencia: description: Unique recurrence id (29-char, RR...). examples: - RR0435879820240920njua7shf40o type: string idReqJdPi: description: JDPI request id (36-char GUID). examples: - 45F763C6-7487-4363-9406-A1DE2A9636D3 type: string idSolicitacaoRecorrencia: description: Confirmation-solicitation id (29-char, IS...). examples: - IS0435879820240605abcd1234567 type: string jornada: description: Authorization journey (1 only on the PSP Pagador genesis). examples: - 1 format: int64 type: integer nrContrato: description: Contract/order identifier (35-char). examples: - 1234567890ABC type: string pagador: $ref: "#/components/schemas/InboundPayerBlock" description: The recurrence pagador. pisoValorMaximo: description: Receiver floor in reais (a JSON number). examples: - 10.5 format: double type: number recebedor: $ref: "#/components/schemas/InboundRecipientBlock" description: The recurrence recebedor. retentativa: description: Retry policy (0=none, 1=up to 3 in 7 days). examples: - 1 format: int64 type: integer tpFrequencia: description: Recurrence periodicity (0..4). examples: - 4 format: int64 type: integer valor: description: Fixed payment amount in reais (a JSON number). examples: - 550 format: double type: number required: - idReqJdPi - idRecorrencia - retentativa - jornada - tpFrequencia - dtInicialRecorrencia - recebedor - pagador - nrContrato - dtHrCriacaoRecorrencia - dtHrCriacaoSolicitacao - dtHrExpiracaoSolicitacao type: object RegisterRequestResponse: additionalProperties: false properties: dtHrSgct: description: SGCT registration timestamp (UTC). examples: - "2024-11-27T22:10:05.025Z" type: string idReqJdPi: description: Echoed JDPI request id (36-char GUID). examples: - 45F763C6-7487-4363-9406-A1DE2A9636D3 type: string idSgct: description: Local SGCT authorization id (36-char GUID). examples: - 69F963C6-7487-4363-9406-A1DE2A9636D4 type: string required: - idReqJdPi - idSgct - dtHrSgct type: object RegisterScheduleBody: additionalProperties: true properties: codigoErro: description: JDPI error code (100-char; on a rejection). examples: - "" type: string descCodigoErro: description: JDPI error description (1000-char). examples: - "" type: string devedor: $ref: "#/components/schemas/ScheduleDebtorBlock" description: The devedor, sent only when it differs from the payer. dtHrRecepcaoPspRecebedor: description: PSP-receiver reception timestamp (UTC; required when finalidadeAgendamento=0). examples: - "2024-09-20T09:25:49.025Z" type: string dtVencimento: description: Recurring charge due date (aaaa-mm-dd). examples: - "2024-09-26" type: string endToEndId: description: Unique payment-instruction id (32-char). examples: - E00038166202409201500y6j6mt9l0pi type: string finalidadeAgendamento: description: Schedule purpose (0=first, 1=post-due retry, 2=settlement resend). examples: - 0 format: int64 type: integer idConciliacaoRecebedor: description: Receiver conciliation id (35-char). examples: - JDPI2024092000000000000000000000001 type: string idRecorrencia: description: Unique recurrence id (29-char, RR...). examples: - RR0435879820240919njua7shf40o type: string infEntreClientes: description: Free-text receiver-to-payer info (140-char). examples: - Cobranca da Enel type: string pagador: $ref: "#/components/schemas/SchedulePayerBlock" description: The instruction pagador. recebedor: $ref: "#/components/schemas/ScheduleRecipientBlock" description: The instruction recebedor. stAgendamento: description: Schedule status (0=Aceito, 1=Rejeitado). examples: - 0 format: int64 type: integer valor: description: Recurring payment amount in reais (a JSON number). examples: - 550 format: double type: number required: - endToEndId - idConciliacaoRecebedor - idRecorrencia - stAgendamento - dtVencimento - recebedor - pagador - finalidadeAgendamento type: object RegisterScheduleCancellationBody: additionalProperties: true properties: codigoErro: description: JDPI error code (100-char; on a rejection). examples: - "" type: string cpfCnpjSolCancelamento: description: Requester CPF/CNPJ (a v5.5.0 string). examples: - "77379362038" type: string descCodigoErro: description: JDPI error description (100-char). examples: - "" type: string dtHrCancelamento: description: Cancellation timestamp (UTC). examples: - "2024-09-20T10:10:05.025Z" type: string endToEndId: description: Unique payment-instruction id (32-char). examples: - E11111111202409201500y6j6mt9l1pi type: string idCancelamento: description: Unique cancellation id (29-char, CA...). examples: - CA0435879820240920bcdb1fhn43a type: string idConciliacaoRecebedor: description: Receiver conciliation id (35-char). examples: - JDPI2024091800000000000000000000002 type: string idRecorrencia: description: Unique recurrence id (29-char, RR...). examples: - RR0435879820240919njua7shf40o type: string ispbDestinatario: description: Destination PSP ISPB (8 digits, a v5.5.0 string). examples: - "11111111" type: string ispbSolicitante: description: Requesting PSP ISPB (8 digits, a v5.5.0 string). examples: - "04358798" type: string motivoCancelamento: description: Cancellation reason (0..6). examples: - 5 format: int64 type: integer solCancelamento: description: Requesting PSP (0=pagador, 1=recebedor). examples: - 0 format: int64 type: integer stCancelamento: description: Cancellation status (0=Aceito, 1=Rejeitado). examples: - 0 format: int64 type: integer tpPessoaSol: description: Requester person type (0=PF, 1=PJ). examples: - 0 format: int64 type: integer required: - idCancelamento - idRecorrencia - stCancelamento - solCancelamento - ispbSolicitante - ispbDestinatario - idConciliacaoRecebedor - tpPessoaSol - cpfCnpjSolCancelamento - motivoCancelamento - endToEndId - dtHrCancelamento type: object RegisterScheduleCancellationResponse: additionalProperties: false properties: dtHrSgct: description: SGCT registration timestamp (UTC). examples: - "2024-11-27T22:10:05.025Z" type: string idSgct: description: Local SGCT cancellation id (36-char GUID). examples: - 69F963C6-7487-4363-9406-A1DE2A9636D4 type: string required: - idSgct - dtHrSgct type: object RegisterScheduleResponse: additionalProperties: false properties: dtHrSgct: description: SGCT registration timestamp (UTC). examples: - "2024-11-27T22:10:05.025Z" type: string idSgct: description: Local SGCT schedule id (36-char GUID). examples: - 69F963C6-7487-4363-9406-A1DE2A9636D4 type: string required: - idSgct - dtHrSgct type: object RegisterValidationBody: additionalProperties: false properties: rejectionReason: description: "Rejection reason (motivoRejeicao; the exact 4.3.10 domain: AP01, AP02, AP04, AP05, AP06, AP07, AP08, AP11, AP12, CH16; required when result=0)." examples: - AP01 type: string result: description: resultado (0=Invalido, 1=Valido). examples: - 1 format: int64 type: integer validatedAt: description: Validation timestamp (dtHrValidacao, UTC). examples: - "2024-01-06T10:00:00Z" type: string required: - result type: object RequestAuthorizationBody: additionalProperties: false properties: amount: description: Fixed payment amount in centavos (valor; omit/0 for a variable recurrence). examples: - 110001 format: int64 type: integer contractDesc: description: Free-text contract description (descContrato). examples: - Conta de energia type: string contractNumber: description: Contract/order identifier (nrContrato). examples: - 1234567890ABC type: string createdDateTime: description: Recurrence creation timestamp (dtHrCriacaoRecorrencia, UTC). examples: - "2024-01-05T10:00:00Z" type: string debtor: $ref: "#/components/schemas/AuthorizationDebtorBody" description: The devedor, sent only when it differs from the payer. endDate: description: Last payment date (dtFinalRecorrencia; aaaa-mm-dd). examples: - "2026-01-10" type: string expirationDateTime: description: Solicitation expiration timestamp (dtHrExpiracaoSolicitacao, UTC). examples: - "2024-01-06T10:00:00Z" type: string floorMaxAmount: description: Receiver floor in centavos (pisoValorMaximo). examples: - 55000 format: int64 type: integer frequency: description: tpFrequencia (0=Weekly,1=Monthly,2=Quarterly,3=Semiannual,4=Annual). examples: - 1 format: int64 type: integer idRecorrencia: description: Unique recurrence id (29-char, format RR...). examples: - RR0435879820240605njua7shf40o type: string payer: $ref: "#/components/schemas/AuthorizationPayerBody" description: The recurrence pagador (account being authorized). recipient: $ref: "#/components/schemas/AuthorizationRecipientBody" description: The recurrence recebedor (authorized charging entity). solicitationDateTime: description: Solicitation creation timestamp (dtHrCriacaoSolicitacao, UTC). examples: - "2024-01-05T10:00:00Z" type: string startDate: description: First payment date (dtInicialRecorrencia; aaaa-mm-dd). examples: - "2024-01-10" type: string required: - idRecorrencia - frequency - startDate - recipient - payer - contractNumber type: object RequestAuthorizationResponse: additionalProperties: false properties: idRecorrencia: description: The recurrence id (echoed). examples: - RR0435879820240605njua7shf40o type: string idReqJdPi: description: The JDPI request id (36-char GUID). examples: - 52c43361-caa1-4ddb-9152-708426a25db3 type: string requestedAt: description: JDPI request timestamp (dtHrReqJdPi, UTC). examples: - "2024-01-05T10:00:01Z" type: string status: description: The resulting local authorization status. examples: - Requested type: string required: - idReqJdPi - idRecorrencia - requestedAt - status type: object RequestScheduleBody: additionalProperties: false properties: amount: description: Scheduled amount in centavos (valor). examples: - 55000 format: int64 type: integer debtor: $ref: "#/components/schemas/ScheduleDebtorBody" description: The devedor, sent only when it differs from the payer. dueDate: description: Due date (dtVencimento; aaaa-mm-dd). examples: - "2024-09-24" type: string endToEndId: description: Unique payment-transaction id (32-char natural key). examples: - E00038166202409171500y6j6mt9l0pi type: string idRecorrencia: description: Recurrence id linking the authorization (29-char, RR...). examples: - RR0435879820240605njua7shf40o type: string infoBetweenClients: description: Free-text receiver-to-payer info (infEntreClientes). examples: - "" type: string payer: $ref: "#/components/schemas/SchedulePayerBody" description: The scheduled pagador (account being charged). purpose: description: finalidadeAgendamento (0=first, 1=post-due retry, 2=settlement-error resend). examples: - 0 format: int64 type: integer recipient: $ref: "#/components/schemas/ScheduleRecipientBody" description: The scheduled recebedor (account receiving the charge). recipientReceivedAt: description: Recipient PSP reception timestamp (dtHrRecepcaoPspRecebedor, UTC; required when purpose=0). examples: - "2024-09-17T10:25:49.025Z" type: string reconciliationId: description: Receiver conciliation id (idConciliacaoRecebedor; 26..35-char). examples: - JDPI2024091700000000000000000000001 type: string required: - endToEndId - reconciliationId - idRecorrencia - purpose - dueDate - recipient - payer type: object RequestScheduleResponse: additionalProperties: false properties: endToEndId: description: The payment-transaction id (echoed). examples: - E00038166202409171500y6j6mt9l0pi type: string idRecorrencia: description: The recurrence id (echoed). examples: - RR0435879820240605njua7shf40o type: string reconciliationId: description: The receiver conciliation id (echoed). examples: - JDPI2024091700000000000000000000001 type: string requestedAt: description: JDPI request timestamp (dtHrReqJdPi, UTC). examples: - "2024-09-17T10:10:05Z" type: string status: description: The resulting local schedule status. examples: - Requested type: string required: - idRecorrencia - reconciliationId - endToEndId - requestedAt - status type: object RespondAuthorizationBody: additionalProperties: false properties: accountType: description: tpContaPagador (0..3). examples: - 0 format: int64 type: integer authorizedAt: description: Authorization timestamp (dtHrAutorizacaoRecorrencia, UTC; required when accepting). examples: - "2024-01-06T10:00:00Z" type: string ibgeCode: description: Municipality IBGE code (codMunIbge; required when accepting). examples: - 3550308 format: int64 type: integer payerMaxAmount: description: Payer max cap in centavos (vlrMaxPagador). examples: - 200000 format: int64 type: integer payerName: description: Payer name (nomePagador). examples: - Fulano de Tal type: string rejectionReason: description: Rejection reason (motivoRejeicao; AP13/AP14/AP15; required when rejecting). examples: - AP13 type: string result: description: resultadoAutorizacao (true=accept, false=reject). examples: - true type: boolean required: - result - payerName - accountType 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 ReturnReasonItem: additionalProperties: false properties: code: description: The PIX return reason code. examples: - MD06 type: string description: description: The reason description. examples: - Requested by receiver type: string required: - code - description type: object ReturnReasonsBody: additionalProperties: false properties: data: description: The list of refund reasons. items: $ref: "#/components/schemas/ReturnReasonItem" type: - array - "null" required: - data type: object ReverseDebitBody: additionalProperties: true properties: codigoErro: description: Error code (the section 8.7 generic SPI domain; NOT the section 5.3 motivoRejeicao set). examples: - AB03 type: string descCodigoErro: description: Error description (1000-char). examples: - Liquidacao da transacao interrompida devido a timeout no SPI. type: string endToEndId: description: Unique payment-instruction id (32-char; matches the path param). examples: - E11111111202409181500y6j6mt9l1pi type: string stJdPiProc: description: Negative-return classification (1=processing error, 2=JDPI validation error, 3=SPI-returned error). examples: - 3 format: int64 type: integer required: - endToEndId - stJdPiProc - codigoErro type: object ReverseDebitResponse: additionalProperties: false properties: dtHrOperacaoSgct: description: SGCT operation timestamp (UTC). examples: - "2024-09-20T04:02:00.021Z" type: string endToEndId: description: Unique payment-instruction id (32-char). examples: - E11111111202409181500y6j6mt9l1pi type: string idOperacaoSgct: description: SGCT reversal-operation id (a GUID). examples: - 58F752C5-6376-3252-8305-A2DE3A8525D4 type: string required: - endToEndId - idOperacaoSgct - dtHrOperacaoSgct type: object ScheduleCancellationItem: additionalProperties: false properties: cancelStatus: description: stCancelamento (0=Aceito, 1=Rejeitado; -1 when absent). examples: - 0 format: int64 type: integer cancelledAt: description: Cancellation timestamp (UTC). examples: - "2024-10-01T10:00:00Z" type: string errorCode: description: JDPI error code (codigoErro). examples: - "" type: string errorDesc: description: JDPI error description (descCodigoErro). examples: - "" type: string idCancelamento: description: The cancellation id (29-char, CA...). examples: - CA0435879820240605abcd1234567 type: string reason: description: motivoCancelamento (0..6). examples: - 0 format: int64 type: integer recipientIspb: description: ispbDestinatario (string). examples: - "00038166" type: string requesterDocument: description: Requester CPF/CNPJ (string). examples: - "04623217035" type: string requesterIspb: description: ispbSolicitante (string). examples: - "04358798" type: string requesterType: description: tpPessoaSol. examples: - 0 format: int64 type: integer required: - idCancelamento - requesterIspb - recipientIspb - requesterType - requesterDocument - reason - cancelledAt - cancelStatus type: object ScheduleCancellationResponse: additionalProperties: false properties: cancelStatus: description: stCancelamento (0=Aceito, 1=Rejeitado; -1 when absent). examples: - 0 format: int64 type: integer cancelledAt: description: Cancellation timestamp (UTC). examples: - "2024-10-01T10:00:00Z" type: string endToEndId: description: The payment-transaction id. examples: - E00038166202409171500y6j6mt9l0pi type: string errorCode: description: JDPI error code. examples: - "" type: string errorDesc: description: JDPI error description. examples: - "" type: string idCancelamento: description: The cancellation id (CA...). examples: - CA0435879820240605abcd1234567 type: string localStatus: description: Local ScheduleStatus projected from the JDPI situation. examples: - Cancelled type: string localStatusKnown: description: False when the JDPI situation carries no projected local status. examples: - true type: boolean reason: description: motivoCancelamento (0..6). examples: - 0 format: int64 type: integer recipientIspb: description: ispbDestinatario (string). examples: - "00038166" type: string reconciliationId: description: The receiver conciliation id. examples: - JDPI2024091700000000000000000000001 type: string requestedAt: description: JDPI request timestamp (UTC). examples: - "2024-10-01T10:00:00Z" type: string requester: description: solCancelamento (0=PSP pagador, 1=PSP recebedor). examples: - 1 format: int64 type: integer requesterDocument: description: Requester CPF/CNPJ (string). examples: - "04623217035" type: string requesterIspb: description: ispbSolicitante (string). examples: - "04358798" type: string requesterType: description: tpPessoaSol. examples: - 0 format: int64 type: integer situationAt: description: Situation timestamp (UTC). examples: - "2024-10-01T10:05:00Z" type: string stJdPi: description: JDPI overall situation. examples: - 9 format: int64 type: integer stJdPiProc: description: JDPI intermediate situation. examples: - 9 format: int64 type: integer required: - idCancelamento - endToEndId - stJdPiProc - stJdPi - localStatus - localStatusKnown - requester - requesterIspb - recipientIspb - requesterType - requesterDocument - reason - cancelStatus type: object ScheduleCancellationSituacaoBody: additionalProperties: true properties: endToEndId: description: Unique payment-instruction id (32-char). examples: - E11111111202409201500y6j6mt9l1pi type: string idCancelamento: description: Unique cancellation id (29-char, CA...). examples: - CA0435879820240605abcd1234567 type: string stCancelamento: description: Cancellation status (0=Aceito, 1=Rejeitado); §4.4.4 OPTIONAL, absent => no-op. examples: - 0 format: int64 type: integer required: - idCancelamento - endToEndId type: object ScheduleDebtorBlock: additionalProperties: true properties: cpfCnpj: description: Debtor CPF or CNPJ (a v5.5.0 string). examples: - "04623217035" type: string nome: description: Debtor name/razao social. examples: - Ciclano da Silva type: string tpPessoa: description: Person type (0=Pessoa Fisica, 1=Pessoa Juridica). examples: - 0 format: int64 type: integer required: - tpPessoa - cpfCnpj - nome type: object ScheduleDebtorBody: additionalProperties: false properties: cpfCnpj: description: Debtor CPF or CNPJ (string). examples: - "04623217035" type: string name: description: Debtor name. examples: - Ciclano da Silva type: string personType: description: tpPessoa (0=Pessoa Fisica, 1=Pessoa Juridica). examples: - 0 format: int64 type: integer required: - personType - cpfCnpj - name type: object ScheduleDebtorView: additionalProperties: false properties: cpfCnpj: description: Debtor CPF/CNPJ (string). examples: - "04623217035" type: string name: description: Debtor name. examples: - Ciclano da Silva type: string personType: description: tpPessoa. examples: - 0 format: int64 type: integer type: object ScheduleParty: additionalProperties: false properties: account: description: Account number (nrConta, string). examples: - "0007654321" type: string accountType: description: tpConta. examples: - 0 format: int64 type: integer agency: description: Branch (nrAgencia, string). examples: - "0001" type: string cnpj: description: CNPJ (string). examples: - "61695227000193" type: string cpfCnpj: description: CPF/CNPJ (string). examples: - "04623217035" type: string ispb: description: Participant ISPB (string). examples: - "04358798" type: string name: description: Legal/trade name. examples: - Enel type: string personType: description: tpPessoa. examples: - 0 format: int64 type: integer type: object SchedulePayerBlock: additionalProperties: true properties: cpfCnpj: description: Payer CPF or CNPJ (a v5.5.0 string). examples: - "11111111111" type: string ispb: description: Payer participant ISPB (8 digits, a v5.5.0 string). examples: - "99999004" type: string tpPessoa: description: Person type (0=Pessoa Fisica, 1=Pessoa Juridica). examples: - 0 format: int64 type: integer required: - ispb - tpPessoa - cpfCnpj type: object SchedulePayerBody: additionalProperties: false properties: cpfCnpj: description: Payer CPF or CNPJ (string). examples: - "04623217035" type: string ispb: description: Payer participant ISPB (8 digits, string). examples: - "00038166" type: string personType: description: tpPessoa (0=Pessoa Fisica, 1=Pessoa Juridica). examples: - 0 format: int64 type: integer required: - ispb - personType - cpfCnpj type: object ScheduleRecipientBlock: additionalProperties: true properties: cnpj: description: Recipient CNPJ (14 digits, a v5.5.0 string). examples: - "61695227000193" type: string ispb: description: Recipient participant ISPB (8 digits, a v5.5.0 string). examples: - "04358798" type: string nome: description: Recipient legal/trade name (razao social). examples: - Enel type: string nrAgencia: description: Recipient branch (nrAgencia, 4 digits, string; the branch source). examples: - "1234" type: string nrConta: description: Recipient account number (nrConta, a string; NEVER the branch). examples: - "12345678" type: string tpConta: description: Recipient account type (0=corrente, 2=poupanca, 3=pagamento). examples: - 0 format: int64 type: integer required: - ispb - cnpj - nome - tpConta - nrConta type: object ScheduleRecipientBody: additionalProperties: false properties: account: description: Recipient account number (nrConta, string). examples: - "0007654321" type: string accountType: description: tpConta (0=corrente, 2=poupanca, 3=pagamento). examples: - 0 format: int64 type: integer agency: description: Recipient branch (nrAgencia, 4 digits, string). examples: - "0001" type: string cnpj: description: Recipient CNPJ (14 digits, string). examples: - "61695227000193" type: string ispb: description: Recipient participant ISPB (8 digits, string). examples: - "04358798" type: string required: - ispb - cnpj - accountType - account type: object ScheduleResponse: additionalProperties: false properties: acceptRejectAt: description: Accept/reject timestamp (dtHrAceiteRejeite, UTC). examples: - "2024-09-17T15:10:05Z" type: string amount: description: Scheduled amount in centavos. examples: - 55000 format: int64 type: integer cancellations: description: Cancellation history (cancelamento). items: $ref: "#/components/schemas/ScheduleCancellationItem" type: - array - "null" debtor: $ref: "#/components/schemas/ScheduleDebtorView" description: The scheduled devedor. dueDate: description: Due date (aaaa-mm-dd). examples: - "2024-09-24" type: string endToEndId: description: The payment-transaction id (32-char). examples: - E00038166202409171500y6j6mt9l0pi type: string errorCode: description: JDPI error code. examples: - "" type: string errorDesc: description: JDPI error description. examples: - "" type: string idRecorrencia: description: The recurrence id (RR...). examples: - RR0435879820240605njua7shf40o type: string infoBetweenClients: description: Free-text receiver-to-payer info. examples: - "" type: string localStatus: description: Local ScheduleStatus projected from the JDPI situation. examples: - Accepted type: string localStatusKnown: description: False when the JDPI situation carries no projected local status. examples: - true type: boolean payer: $ref: "#/components/schemas/ScheduleParty" description: The scheduled pagador. purpose: description: finalidadeAgendamento. examples: - 0 format: int64 type: integer recipient: $ref: "#/components/schemas/ScheduleParty" description: The scheduled recebedor. recipientReceivedAt: description: Recipient PSP reception timestamp (UTC). examples: - "2024-09-17T10:25:49Z" type: string reconciliationId: description: The receiver conciliation id. examples: - JDPI2024091700000000000000000000001 type: string requestedAt: description: JDPI request timestamp (UTC). examples: - "2024-09-17T10:10:05Z" type: string scheduleStatus: description: stAgendamento (0=Aceito, 1=Rejeitado; -1 when absent). examples: - 0 format: int64 type: integer situationAt: description: Situation timestamp (dtHrSituacao, UTC). examples: - "2024-09-18T16:34:18Z" type: string stJdPi: description: JDPI overall situation (-1/0/9/10/11). examples: - 9 format: int64 type: integer stJdPiProc: description: JDPI intermediate situation (0/1/2/5/7/8/9/10/11). examples: - 9 format: int64 type: integer required: - endToEndId - idRecorrencia - scheduleStatus - stJdPiProc - stJdPi - localStatus - localStatusKnown - recipient - payer - debtor type: object ScheduleSituacaoBody: additionalProperties: true properties: endToEndId: description: Unique payment-instruction id (32-char); the projection's load key. examples: - E00038166202409201500y6j6mt9l0pi type: string stJdPi: description: Overall request situation (-1/0/9/10/11). examples: - 9 format: int64 type: integer stJdPiProc: description: Intermediate processing situation (0/1/2/5/7/8/9/10/11). examples: - 9 format: int64 type: integer required: - endToEndId - stJdPiProc - stJdPi type: object SolicitRefundRequestBody: additionalProperties: false properties: detalhes: description: Free-text detail; required when motivo=0 (Falha Operacional). examples: - Suspected scam. type: string endToEndId: description: EndToEndId of the contested payment (or pacs.004 id for a cancellation motivo). examples: - E1234567820240101000000000000001 type: string idempotencyKey: description: "Client-supplied idempotency key: any stable business string. The plugin projects it deterministically into the GUID form JDPI requires (contract 6), so the same value always dedups against the same JDPI request and the raw value is never sent verbatim." examples: - med-refund-2024-0001 type: string motivo: description: Refund motivo (0=Falha Operacional, 1=Fraude, 3=Pix Automatico). examples: - 1 format: int64 type: integer valorDevolucao: description: Requested refund amount, in centavos. examples: - 25000 format: int64 type: integer required: - endToEndId - motivo - valorDevolucao - idempotencyKey type: object StaticCompositeBody: additionalProperties: false properties: accountId: description: The CRM account id of the recipient (sources name + city). examples: - acc-123 type: string amount: description: Amount in centavos (0 = any-amount static QR). examples: - 110001 format: int64 type: integer certificateIspb: description: Indirect-PSP certificate ISPB (ispbCertificadoJws, string). examples: - "04358798" type: string description: description: Free-text additional data (dadosAdicionais). examples: - Conta de energia type: string jwkUrl: description: JWK Set URL (urlJwk; no scheme). examples: - example.com/pix/jwks type: string key: description: The recipient PIX key the composite QR pays into. examples: - fulano.tal@provedor.com.br type: string recurrence: $ref: "#/components/schemas/CompositeRecurrenceBody" description: The embedded recurrence configuration (dadosRecorrencia). recurrencePayloadUrl: description: Recurrence JWS host URL (urlPayloadJsonRec; no scheme). examples: - example.com/pix/rec/abc type: string txId: description: Conciliation id (idConciliacaoRecebedor). examples: - TX-1 type: string zipCode: description: Recipient postal code (cep). examples: - "01227200" type: string required: - key - accountId - recurrencePayloadUrl - jwkUrl - recurrence type: object StaticQRBody: additionalProperties: false properties: accountId: description: The CRM account id of the recipient (sources name + city). examples: - acc-123 type: string amount: description: Amount in centavos (an integer; 0 = any-amount static QR). examples: - 10050 format: int64 type: integer description: description: Free-text additional data (dadosAdicionais). examples: - Invoice 42 type: string key: description: The recipient PIX key the static QR pays into. examples: - recipient@bank.com type: string txId: description: Conciliation id (idConciliacaoRecebedor); §8.3.1 caps it at 25 characters and states no charset (default "***"). examples: - TX-001 type: string required: - key - amount - accountId type: object TransactionLimitItem: additionalProperties: false properties: accountId: description: The account id (externalId). examples: - ext-acc-123 type: string amount: description: The limit amount in centavos. examples: - 3000000 format: int64 type: integer id: description: The limit row id. examples: - l1f9c0a2-... type: string limitType: description: eTransactionLimitType name. examples: - PERIOD type: string periodType: description: ePeriodType name. examples: - DAILY type: string transactionType: description: eTransactionType name. examples: - PIX type: string required: - id - accountId - transactionType - periodType - limitType - amount type: object TransactionLimitsBody: additionalProperties: false properties: data: description: The list of transaction limits. items: $ref: "#/components/schemas/TransactionLimitItem" type: - array - "null" required: - data type: object TransactionListBody: additionalProperties: false properties: data: description: The list of transactions. items: $ref: "#/components/schemas/TransactionListItem" type: - array - "null" required: - data type: object TransactionListItem: additionalProperties: false properties: amount: description: Transaction amount in centavos. examples: - 10050 format: int64 type: integer createdAt: description: Creation timestamp (RFC 3339 UTC). examples: - "2026-06-19T12:00:00Z" type: string description: description: Payment description. examples: - Invoice 42 type: string endToEndId: description: The SPI end-to-end id. examples: - E1234567890 type: string flow: description: Numeric eTransactionFlow. examples: - 2 format: int64 type: integer id: description: The transaction id. examples: - d1f9c0a2-... type: string isRefund: description: Whether this row is a refund. examples: - false type: boolean jdpiRequestId: description: The JDPI request id. examples: - REQ-123 type: string payee: $ref: "#/components/schemas/PartyResponse" description: The payee party. payer: $ref: "#/components/schemas/PartyResponse" description: The payer party. priority: description: Numeric eTransactionPriority. examples: - 1 format: int64 type: integer status: description: eTransactionStatus name. examples: - EXECUTED type: string type: description: Numeric eTransactionType (1=PIX). examples: - 1 format: int64 type: integer updatedAt: description: Last-update timestamp (RFC 3339 UTC). examples: - "2026-06-19T12:00:00Z" type: string required: - id - status - flow - type - amount - priority - isRefund - createdAt - updatedAt type: object TransactionStatusResponse: additionalProperties: false properties: amount: description: Transaction amount in centavos. examples: - 10050 format: int64 type: integer description: description: Payment description. examples: - Invoice 42 type: string endToEndId: description: The SPI end-to-end id. examples: - E1234567890 type: string errorCode: description: JDPI error code (live branch). examples: - "" type: string errorMessage: description: JDPI error message (live branch). examples: - "" type: string flow: description: Numeric eTransactionFlow. examples: - 2 format: int64 type: integer id: description: The transaction id (or JDPI tx id on the live branch). examples: - d1f9c0a2-... type: string jdpiRequestId: description: The JDPI request id. examples: - REQ-123 type: string jdpiStatus: description: Raw JDPI eProcessingStatus (live branch only). examples: - 9 format: int64 type: integer payee: $ref: "#/components/schemas/PartyResponse" description: The payee party. payer: $ref: "#/components/schemas/PartyResponse" description: The payer party. status: description: eTransactionStatus name. examples: - EXECUTED type: string required: - id - status - amount type: object UpdateCobvCompositeBody: additionalProperties: false properties: certificateIspb: description: Indirect-PSP certificate ISPB (ispbCertificadoJws, string). examples: - "04358798" type: string city: description: Merchant city (cidade). examples: - Sao Paulo type: string daysAfterDue: description: Days after the due date the charge can still be paid (diasAposVenc). examples: - 365 format: int64 type: integer debtorName: description: Updated debtor name (dadosRecorrencia.devedor.nome). examples: - Fulano dos Santos type: string description: description: Optional additional-data entries (dadosAdicionais). items: $ref: "#/components/schemas/CompositeAdditionalDataBody" type: - array - "null" discount: description: Discount in centavos (desconto; omit/0 to skip). examples: - 4 format: int64 type: integer dueDate: description: Due date for payment (dtVenc; aaaa-mm-dd). examples: - "2021-06-17" type: string finalAmount: description: Final charge amount in centavos (valorFinal). examples: - 100001 format: int64 type: integer fine: description: Fine in centavos (multa; omit/0 to skip). examples: - 20022 format: int64 type: integer interest: description: Interest in centavos (juros; omit/0 to skip). examples: - 1015 format: int64 type: integer jwkUrl: description: JWK Set URL (urlJwk; no scheme). examples: - example.com/jwks type: string key: description: The recipient PIX key the composite QR pays into. examples: - fulano.tal@provedor.com.br type: string originalAmount: description: Original charge amount in centavos (valorOriginal). examples: - 100116 format: int64 type: integer payer: $ref: "#/components/schemas/CompositePayerBody" description: Optional payer block. paymentPayloadUrl: description: CobV JWS host URL (urlPayloadJson; no scheme). examples: - pix.example.com/cobv/abc type: string rebate: description: Rebate in centavos (abatimento; omit/0 to skip). examples: - 111 format: int64 type: integer recipientName: description: Recipient/beneficiary name (nomeRecebedor). examples: - Fulano de Tal type: string recipientStreet: description: Recipient street (logradouroRecebedor). examples: - Rua Pix, 123 type: string recurrencePayloadUrl: description: Recurrence JWS host URL (urlPayloadJsonRec; no scheme). examples: - pix.example.com/rec/def type: string recurrenceStatus: description: Recurrence stRecorrencia transition (0..4). examples: - 0 format: int64 type: integer startDate: description: Updated recurrence first payment date (dtInicialRecorrencia). examples: - "2025-03-15" type: string state: description: Recipient state (uf). examples: - SP type: string status: description: Charge situation (0=Active,1=Completed,2=Removed by recipient,3=Removed by PSP). examples: - 0 format: int64 type: integer txId: description: Conciliation id (idConciliacaoRecebedor). examples: - JDPI2020010300000000000000000000001 type: string zipCode: description: Recipient postal code (cep). examples: - "01227200" type: string required: - key - recipientName - recipientStreet - city - state - zipCode - finalAmount - dueDate - daysAfterDue - status - recurrenceStatus - txId - paymentPayloadUrl type: object UpdateDynamicCompositeBody: additionalProperties: false properties: certificateIspb: description: Indirect-PSP certificate ISPB (ispbCertificadoJws, string). examples: - "04358798" type: string city: description: Merchant city (cidade). examples: - Sao Paulo type: string debtorName: description: Updated debtor name (dadosRecorrencia.devedor.nome). examples: - Fulano dos Santos type: string description: description: Optional additional-data entries (dadosAdicionais). items: $ref: "#/components/schemas/CompositeAdditionalDataBody" type: - array - "null" expirationTime: description: QR expiration in seconds (0 = JDPI default). examples: - 86400 format: int64 type: integer jwkUrl: description: JWK Set URL (urlJwk; no scheme). examples: - example.com/jwks type: string key: description: The recipient PIX key the composite QR pays into. examples: - fulano.tal@provedor.com.br type: string originalAmount: description: Original charge amount in centavos (valorOriginal). examples: - 100001 format: int64 type: integer payer: $ref: "#/components/schemas/CompositePayerBody" description: Optional payer block. paymentPayloadUrl: description: Payment JWS host URL (urlPayloadJson; no scheme). examples: - pix.example.com/abc type: string recipientName: description: Recipient/beneficiary name (nomeRecebedor). examples: - Fulano de Tal type: string recurrencePayloadUrl: description: Recurrence JWS host URL (urlPayloadJsonRec; no scheme). examples: - pix.example.com/rec/def type: string recurrenceStatus: description: Recurrence stRecorrencia transition (0..4). examples: - 0 format: int64 type: integer startDate: description: Updated recurrence first payment date (dtInicialRecorrencia). examples: - "2025-02-10" type: string status: description: Charge situation (0=Active,1=Completed,2=Removed by recipient,3=Removed by PSP). examples: - 0 format: int64 type: integer txId: description: Conciliation id (idConciliacaoRecebedor). examples: - JDPI2020010300000000000000000000001 type: string zipCode: description: Recipient postal code (cep). examples: - "01227200" type: string required: - key - recipientName - city - originalAmount - status - recurrenceStatus - txId - paymentPayloadUrl - jwkUrl type: object UpdateDynamicQRBody: additionalProperties: false properties: accountId: description: The CRM account id of the recipient (sources name + city). examples: - acc-123 type: string amount: description: Amount in centavos (an integer). examples: - 10050 format: int64 type: integer description: description: Optional additional-data entries (dadosAdicionais). items: $ref: "#/components/schemas/AdditionalDataBody" type: - array - "null" expirationTime: description: QR expiration in seconds (0 = JDPI default). examples: - 3600 format: int64 type: integer indirectId: description: "Optional identifier (UUID) of an indirect participant registered here, mirroring the create body. Supply the SAME institution the charge was generated for: the plugin stores no indirect association for a QR, so an omitted value re-signs the charge under the DIRECT participant's certificate and moves its location onto the direct participant's domain. IGNORED, without any error, while this tenant's indirect-participants feature is off." examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string key: description: The recipient PIX key the dynamic QR pays into. examples: - recipient@bank.com type: string payer: $ref: "#/components/schemas/PayerBody" description: Optional payer block. recipientConciliationId: description: Conciliation id (idConciliacaoRecebedor); §8.3.5 mandatory; 26..35 alphanumeric ([a-zA-Z0-9]). examples: - JDPI2020010300000000000000000000001 type: string status: description: "Charge status: 0=Active, 1=Concluded, 2=Removed by recipient, 3=Removed by PSP." examples: - 0 format: int64 type: integer zipCode: description: Recipient postal code (cep). examples: - "01310100" type: string required: - key - amount - accountId - status - recipientConciliationId type: object UpdateDynamicQRResponse: additionalProperties: false properties: payloadJws: description: The re-signed JWS payload, returned ONLY when the update ran under an indirect participant's own certificate. Absent on the direct path. examples: - eyJhbGciOiJFUzI1NiJ9.eyJyZXYiOjJ9.sig type: string payloadUrl: description: The resolvable JWS host URL the dynamic QR embeds (urlPayloadJson; schema-less). examples: - pix.example.com/qr/cob/fzqRwuXYSweWofLD1OX2Bw type: string qrCode: description: The updated EMV QR-code payload (base64-decoded, ready to render). examples: - 00020126... type: string revision: description: The JDPI-computed charge revision (revisao). examples: - 2 format: int64 type: integer required: - qrCode - revision type: object UpdateIndirectBody: additionalProperties: false properties: action: description: Lifecycle transition; one of suspend, reactivate, close. examples: - suspend type: string delivery: $ref: "#/components/schemas/UpdateIndirectDelivery" description: New delivery endpoint and/or secret. name: description: New display name (1..120 chars). examples: - Indirect PSP Ltda type: string qrCertificate: $ref: "#/components/schemas/UpdateIndirectQRCertificate" description: New own-QR-code certificate configuration. Absent leaves it unchanged. Accepted only when the indirect participants feature is enabled for the tenant (422 PIX-0111 otherwise). type: object UpdateIndirectDelivery: additionalProperties: false properties: endpointUrl: description: New HTTPS delivery endpoint. examples: - https://indirect.example.com/pix type: string secret: description: New HMAC-SHA256 signing secret; encrypted at rest; never returned. examples: - s3cr3t type: string type: object UpdateIndirectQRCertificate: additionalProperties: false properties: ownCertificate: description: Whether the indirect hosts the dynamic-QR JWS/JWKS under its OWN certificate. False falls back to the direct participant's certificate and FQDN, and discards publicBaseUrl. examples: - true type: boolean publicBaseUrl: description: The indirect's SCHEME-LESS public base URL (host plus optional path) the QR payload location is built on. Required when ownCertificate is true; ignored otherwise. examples: - qr.indirect.example.com/pix type: string type: object UpdateMaxValueBody: additionalProperties: false properties: newPayerMaxAmount: description: New payer max cap in centavos (novoVlrMaxPagador; omit/0 removes the cap). examples: - 250000 format: int64 type: integer type: object UpdateMaxValueResponse: additionalProperties: false properties: idRecorrencia: description: The recurrence id. examples: - RR0435879820240605njua7shf40o type: string requestedAt: description: JDPI request timestamp (dtHrReqJdPi, UTC). examples: - "2024-03-01T10:00:00Z" type: string required: - idRecorrencia - requestedAt type: object UpdateRecurrenceCompositeBody: additionalProperties: false properties: certificateIspb: description: Indirect-PSP certificate ISPB (ispbCertificadoJws, string). examples: - "04358798" type: string debtorName: description: Updated debtor name (devedor.nome). examples: - Fulano dos Santos type: string jwkUrl: description: New JWK Set URL (urlJwk; no scheme). examples: - example.com/jwks type: string recurrencePayloadUrl: description: New recurrence JWS host URL (urlPayloadJsonRec; no scheme). examples: - pix.example.com/rec/abc type: string recurrenceStatus: description: stRecorrencia transition (0=Created,1=Approved,2=Rejected,3=Expired,4=Cancelled). examples: - 1 format: int64 type: integer startDate: description: New first payment date (dtInicialRecorrencia; aaaa-mm-dd). examples: - "2025-02-10" type: string txId: description: Conciliation id (idConciliacaoRecebedor). examples: - JDPI2024110800000000000000000000002 type: string required: - recurrenceStatus 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 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 ValidateAuthorizationBody: additionalProperties: true properties: descContrato: description: Free-text contract description (35-char). examples: - Conta de energia type: string devedor: $ref: "#/components/schemas/InboundDebtorBlock" description: The devedor, sent only when it differs from the payer. dtFinalRecorrencia: description: Last payment date (aaaa-mm-dd). examples: - "2026-01-10" type: string dtHrAutorizacaoRecorrencia: description: Authorization timestamp (UTC). examples: - "2024-09-20T14:11:27.453Z" type: string dtHrCriacaoRecorrencia: description: Recurrence creation timestamp (UTC). examples: - "2024-09-20T09:25:49.025Z" type: string dtInicialRecorrencia: description: First payment date (aaaa-mm-dd). examples: - "2024-01-10" type: string idRecorrencia: description: Unique recurrence id (29-char, RR...). examples: - RR0435879820240920njua7shf40o type: string idSolicitacaoRecorrencia: description: Confirmation-solicitation id (29-char, IS...). examples: - IS0435879820240605abcd1234567 type: string jornada: description: Authorization journey (1..4). examples: - 2 format: int64 type: integer motivoRejeicao: description: Rejection reason code (4-char; required when resultadoAutorizacao=false). examples: - AP03 type: string nrContrato: description: Contract/order identifier (35-char). examples: - 1234567890ABC type: string pagador: $ref: "#/components/schemas/InboundPayerBlock" description: The recurrence pagador. recebedor: $ref: "#/components/schemas/InboundRecipientBlock" description: The recurrence recebedor. resultadoAutorizacao: description: Payer analysis result (true=Aceita, false=Rejeitada). examples: - true type: boolean retentativa: description: Retry policy (0=none, 1=up to 3 in 7 days). examples: - 1 format: int64 type: integer tpFrequencia: description: Recurrence periodicity (0..4). examples: - 4 format: int64 type: integer valor: description: Fixed payment amount in reais (a JSON number). examples: - 550 format: double type: number required: - idRecorrencia - retentativa - jornada - tpFrequencia - dtInicialRecorrencia - recebedor - pagador - nrContrato - dtHrCriacaoRecorrencia type: object ValidateAuthorizationResponse: additionalProperties: false properties: dtHrValidacao: description: Validation timestamp (UTC). examples: - "2024-09-20T14:12:05.025Z" type: string motivoRejeicao: description: Rejection reason code (required when resultado=0). examples: - AP03 type: string resultado: description: Validation result (0=Invalido, 1=Valido); omitted on the 202 async ack. examples: - 1 format: int64 type: integer required: - dtHrValidacao type: object ValidateCancellationBody: additionalProperties: true properties: cpfCnpjSolCancelamento: description: Requester CPF/CNPJ (a v5.5.0 string). examples: - "77379362038" type: string descContrato: description: Free-text contract description (35-char). examples: - Conta de energia type: string devedor: $ref: "#/components/schemas/InboundDebtorBlock" description: The devedor, sent only when it differs from the payer. dtFinalRecorrencia: description: Last payment date (aaaa-mm-dd). examples: - "2026-01-10" type: string dtHrCancelamento: description: Cancellation timestamp (UTC). examples: - "2024-09-23T10:10:06.101Z" type: string dtHrCriacaoRecorrencia: description: Recurrence creation timestamp (UTC). examples: - "2024-09-20T09:25:49.025Z" type: string dtInicialRecorrencia: description: First payment date (aaaa-mm-dd). examples: - "2024-01-10" type: string idCancelamento: description: Unique cancellation id (29-char, IC...). examples: - IC0435879820240605bcdb1fhn43a type: string idRecorrencia: description: Unique recurrence id (29-char, RR...). examples: - RR0435879820240920njua7shf40o type: string motivoCancelamento: description: Cancellation reason (0..10). examples: - 6 format: int64 type: integer nrContrato: description: Contract/order identifier (35-char). examples: - 1234567890ABC type: string pagador: $ref: "#/components/schemas/InboundPayerBlock" description: The recurrence pagador. recebedor: $ref: "#/components/schemas/InboundRecipientBlock" description: The recurrence recebedor. tpFrequencia: description: Recurrence periodicity (0..4). examples: - 4 format: int64 type: integer tpPessoaSol: description: Requester person type (0=PF, 1=PJ). examples: - 0 format: int64 type: integer valor: description: Fixed payment amount in reais (a JSON number). examples: - 550 format: double type: number required: - idRecorrencia - idCancelamento - tpPessoaSol - cpfCnpjSolCancelamento - motivoCancelamento - tpFrequencia - dtInicialRecorrencia - recebedor - pagador - nrContrato type: object ValidateCancellationResponse: additionalProperties: false properties: dtHrValidacao: description: Validation timestamp (UTC). examples: - "2024-09-20T14:12:05.025Z" type: string motivoRejeicao: description: Rejection reason code (required when resultado=0). examples: - AP03 type: string resultado: description: Validation result (0=Invalido, 1=Valido). examples: - 1 format: int64 type: integer required: - resultado - dtHrValidacao type: object ValidateScheduleBody: additionalProperties: true properties: devedor: $ref: "#/components/schemas/ScheduleDebtorBlock" description: The devedor, sent only when it differs from the payer. dtHrRecepcaoPspRecebedor: description: PSP-receiver reception timestamp (UTC; required when finalidadeAgendamento=0). examples: - "2024-09-20T09:25:49.025Z" type: string dtVencimento: description: Recurring charge due date (aaaa-mm-dd). examples: - "2024-09-26" type: string endToEndId: description: Unique payment-instruction id (32-char). examples: - E00038166202409201500y6j6mt9l0pi type: string finalidadeAgendamento: description: Schedule purpose (0=first, 1=post-due retry, 2=settlement resend). examples: - 0 format: int64 type: integer idConciliacaoRecebedor: description: Receiver conciliation id (35-char). examples: - JDPI2024092000000000000000000000001 type: string idRecorrencia: description: Unique recurrence id (29-char, RR...). examples: - RR0435879820240919njua7shf40o type: string infEntreClientes: description: Free-text receiver-to-payer info (140-char). examples: - Cobranca da Enel type: string pagador: $ref: "#/components/schemas/SchedulePayerBlock" description: The instruction pagador. recebedor: $ref: "#/components/schemas/ScheduleRecipientBlock" description: The instruction recebedor. valor: description: Recurring payment amount in reais (a JSON number). examples: - 550 format: double type: number required: - endToEndId - idConciliacaoRecebedor - idRecorrencia - dtVencimento - recebedor - pagador - finalidadeAgendamento type: object ValidateScheduleCancellationBody: additionalProperties: true properties: cpfCnpjSolCancelamento: description: Requester CPF/CNPJ (a v5.5.0 string). examples: - "77379362038" type: string dtHrCancelamento: description: Cancellation timestamp (UTC). examples: - "2024-09-20T10:10:05.025Z" type: string endToEndId: description: Unique payment-instruction id (32-char). examples: - E11111111202409201500y6j6mt9l1pi type: string idCancelamento: description: Unique cancellation id (29-char, CA...). examples: - CA0435879820240920bcdb1fhn43a type: string idConciliacaoRecebedor: description: Receiver conciliation id (35-char). examples: - JDPI2024091800000000000000000000002 type: string idRecorrencia: description: Unique recurrence id (29-char, RR...). examples: - RR0435879820240919njua7shf40o type: string ispbDestinatario: description: Destination PSP ISPB (8 digits, a v5.5.0 string). examples: - "11111111" type: string ispbSolicitante: description: Requesting PSP ISPB (8 digits, a v5.5.0 string). examples: - "04358798" type: string motivoCancelamento: description: Cancellation reason (0..6). examples: - 5 format: int64 type: integer solCancelamento: description: Requesting PSP (0=pagador, 1=recebedor). examples: - 0 format: int64 type: integer tpPessoaSol: description: Requester person type (0=PF, 1=PJ). examples: - 0 format: int64 type: integer required: - idCancelamento - idRecorrencia - solCancelamento - ispbSolicitante - ispbDestinatario - idConciliacaoRecebedor - tpPessoaSol - cpfCnpjSolCancelamento - motivoCancelamento - endToEndId - dtHrCancelamento type: object ValidateScheduleCancellationResponse: additionalProperties: false properties: dtHrValidacao: description: Validation timestamp (UTC). examples: - "2024-09-20T14:12:05.025Z" type: string motivoRejeicao: description: Rejection reason code (required when resultado=0). examples: - CH16 type: string resultado: description: Validation result (0=Invalido, 1=Valido). examples: - 1 format: int64 type: integer required: - resultado - dtHrValidacao type: object ValidateScheduleResponse: additionalProperties: false properties: dtHrValidacao: description: Validation timestamp (UTC). examples: - "2024-09-20T14:12:05.025Z" type: string motivoRejeicao: description: Rejection reason code (required when resultado=0). examples: - AC06 type: string resultado: description: Validation result (0=Invalido, 1=Valido). examples: - 1 format: int64 type: integer required: - resultado - dtHrValidacao 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 VerifiedKeyView: additionalProperties: false properties: exists: description: Whether the key exists in DICT. examples: - true type: boolean key: description: The PIX key value. examples: - foo@bar.com type: string required: - key - exists type: object VerifyEntriesBody: additionalProperties: false properties: accountId: description: The CRM account id of the caller (resolves the server-side ISPB). examples: - acc-123 type: string keys: description: The PIX keys whose DICT existence to check (1..200). examples: - - foo@bar.com - "11122233300" items: type: string maxItems: 200 minItems: 1 type: array required: - accountId - keys type: object VerifyEntriesResponse: additionalProperties: false properties: correlationId: description: DICT support correlation id. examples: - a9f13566e19f5ca51329479a5bae60c5 type: string jdpiReturnedAt: description: When DICT returned the verification (RFC3339). examples: - "2021-04-08T10:30:05.025Z" type: string keys: description: The per-key existence results. items: $ref: "#/components/schemas/VerifiedKeyView" type: - array - "null" required: - keys type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http info: description: |- The API of a DIRECT Brazilian PIX participant, integrated with BACEN's DICT (key directory) and SPI (settlement) rails through JDPI. It covers the directory (key entries and claims), payments and devolutions over SPI or on-us, per-account limits, QR codes with self-hosted signed payloads, the inbound webhooks JDPI calls on this participant, MED 2.0 (BACEN's special return mechanism), PIX Automático (recurring payments), and the registry of INDIRECT participants served through this participant's ISPB. ## Domain map - **Entries** / **Claims** — the DICT directory: registering PIX keys, and the claim process for taking a key over from another PSP. - **Transactions** / **Refunds** / **Limits** / **Banks** — SPI payments: outbound orders (two-phase over SPI, synchronous on-us), payee-initiated devolutions, per-account outbound limits, and the live SPI participant catalog. - **QR Codes** — static and immediate dynamic QR codes, decode, and the anonymous public routes serving signed payloads to payer PSPs (documented in the tag). - **Webhooks** — the inbound mirror: cash-in, payee-bank-initiated devolução, and synchronous account validation, called BY JDPI on this participant. - **Indirects** — the institutions this direct participant serves: registry, lifecycle, settlement positions, delivery notices, reconciliation feed, and the optional own QR certificate. - **MED Infractions / Refunds / Recoveries / Fraud Markers / Inbound Credit** — MED 2.0: infraction reports, the refund-request money flow in both roles, creator-side value recoveries, DICT fraud markers, and the settlement credit webhook. - **PIX Automatico** — recurring authorizations, schedules, composite QR codes, the inbound registration/validation and settlement legs JDPI calls, and the event-stream ingress. - **Systemplane** — the operator-facing runtime-configuration surface; payment clients never need it. ## Authentication Every operation requires a bearer token minted by the platform's machine-to-machine (M2M) OAuth flow with the DIRECT participant's credentials; authorization is per resource with actions mirroring the HTTP verbs. INDIRECT participants never hold a credential: an indirect's id on a request is ROUTING DATA supplied and guaranteed by the direct participant, not an authentication principal. The exception to authentication is the public QR payload/JWKS routes described under the QR Codes tag, which are anonymous by construction — the payer's PSP, not a registered client, is their caller. ## Money: one API, two units Every money field of THIS API's contract is an **int64 count of centavos** — in JSON bodies, query, path and header alike (`110001` means R$ 1.100,01). Every money field on a body AUTHORED BY JDPI — the inbound webhook mirrors under Webhooks, MED Inbound Credit and the PIX Automático inbound/settlement/event routes — is a **JSON number in reais** (`1100.01`), because that is JD's contract on the payloads JD sends, converted to centavos at the boundary. The discriminator is WHICH SIDE AUTHORED THE BODY, never the field's language: Portuguese-named fields on this API's own write surfaces (e.g. `valorDevolucao` on MED writes) are still integer centavos. Each field's description states its unit. ## Errors Errors are RFC 9457 `application/problem+json`, and every one carries a `PIX-XXXX` taxonomy code in the `code` member — match on the code, not on the human-readable text. The status discipline is ATTRIBUTION: a 4xx means the request, or the data the request names, is what failed (the body names the field or entity); a 5xx names the failing dependency (e.g. `503 PIX-1050` — the JDPI service is temporarily unavailable) rather than hiding behind a generic error. `500 PIX-0109` is the one deliberate exception: an unattributed internal failure, whose detail is scrubbed — as is every response body with status 500 or above. ## Idempotency Three families, each protecting a different leg: - **`clientRequestId`** (optional, on payment orders) is the only identifier that exists BEFORE the JDPI call, so it is the only retry protection a manually typed order has. Reusing one — or an `endToEndId` — is refused `409 PIX-0029`. - **The JDPI `Chave-Idempotencia`**: where a write takes a client `idempotencyKey` (the MED surfaces), the value you send is a SEED — it is projected to a deterministic GUID (UUIDv5) before being forwarded, so one client key always lands in one JDPI dedup slot and a retry stays a retry. Correlate JDPI-side logs with the projection, never with the raw value. DICT writes derive their key from the full request, so a transport retry never double-applies. - **Ledger postings** are idempotent per end-to-end id, namespaced per LEG, so the two legs of one devolution (or a debit and its estorno) can never collide on one idempotency slot. Multi-tenant deployments resolve the tenant from the validated token, never from payloads or paths; the public QR routes' ISPB path segment is a routing selector for public key material, not an identity. title: plugin-br-pix-jd version: 1.0.0 openapi: 3.1.0 paths: /v1/account-closures: post: description: |- 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. operationId: closeAccount requestBody: content: application/json: schema: $ref: "#/components/schemas/CloseAccountBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/AccountClosureResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Register a transactional account closure tags: - Entries x-mint: href: /en/reference/interfaces/pix-jd/register-a-transactional-account-closure /v1/banks: get: description: |- Returns the SPI participating-PSP catalog reduced to what a payment form needs: ispb plus the participant's legal name (razão social), per §8.6.1. It takes no parameters - §8.6.1 declares none and the plugin adds no filter, page or sort - so the entire catalog arrives in one response, in the order JDPI returns it. It is a live passthrough on every call with nothing cached, so this route's latency and availability are JDPI's. Keep ispb a STRING: it is 8 characters and its leading zeros are significant (00000208), so parsing it as a number corrupts it. An empty catalog is 200 with an empty data array, not an error. JDPI unreachable or faulting is 503 PIX-1050, and a timeout is 504 PIX-1051. GET /v1/banks/participants reads the SAME §8.6.1 call and returns the full record; use it when you need cnpj, participation type, modality or status. operationId: getBankIds responses: "200": content: application/json: schema: $ref: "#/components/schemas/BankIDsBody" description: OK "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: List PIX participant bank ids tags: - Banks x-mint: href: /en/reference/interfaces/pix-jd/list-pix-participant-bank-ids /v1/banks/participants: get: description: |- Returns the full SPI participant directory from §8.6.1 - the same JDPI call GET /v1/banks makes, with every field instead of the ispb-and-name pair: ispb, cnpj, legalName, shortName, participantType (1=direct, 2=indirect), modality (1=transactional-account provider, 2=government entity, 3=special settler, 4=user institution), startedAt, endedAt and status (1=active, 2=inactive, 3=awaiting BACEN activation, 4=activation failed). Only ispb, shortName, participantType and status are mandatory in §8.6.1; the rest are omitted from a row when JDPI does not send them, so treat them as optional instead of assuming a fixed shape. status and endedAt are what say whether a participant can receive a payment today - a row can be present and inactive. The route takes no parameters and applies no filter, page or sort, and nothing is cached: the whole directory is fetched live from JDPI on every call, in JDPI's own order. JDPI unreachable or faulting is 503 PIX-1050, and a timeout is 504 PIX-1051. participantType=2 here means SPI's own classification of an institution as indirect at BACEN, and it says NOTHING about whether that institution is an indirect participant registered with THIS participant. The two are unrelated lists: this one is the national directory, and the institutions this deployment serves are read with GET /v1/indirects. A row being participantType=2 is not a reason to send its ISPB an order or a credit, and an institution registered here does not have to appear as 2 in this directory. operationId: listParticipants responses: "200": content: application/json: schema: $ref: "#/components/schemas/ParticipantsBody" description: OK "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: List SPI participants tags: - Banks x-mint: href: /en/reference/interfaces/pix-jd/list-spi-participants /v1/claims: get: description: |- Two different listings behind one route, selected by the status query parameter. With no status (the default) it returns DICT's §8.2.13 claim listing for the PARTICIPANT, not for the account: account_id only resolves the caller's ISPB, and the request body carries that ISPB and nothing else, so every claim DICT associates with the institution comes back - including claims that belong to OTHER accounts under the same ISPB. There is no filter, no paging and no local sort. Two consequences follow from the omitted fields: §8.2.13 declares that an omitted stReivindicacao defaults to situation 1 (Aguardando Resolução), so claims in other situations may not appear; and each row is only key, ispb and claimId, with no state, because DICT's situation value cannot be projected onto this API's status enum without losing cases. With status=processing it answers something else entirely - the in-flight claims of §8.2.08, filtered to the caller's own account number, projected onto the key-entry shape and returned under data instead of claims. The projected status is 5 (you are waiting for the holder), 6 (you hold the key and must decide) or 7 (the holder gave it away; conclude it). Cancelled and completed claims are dropped, and only the FIRST §8.2.08 page (100 rows) is read. Any other status value falls through to the default branch. An account the CRM cannot resolve is 404 PIX-2016. operationId: getClaims parameters: - description: The CRM account id whose claims to list. explode: false in: query name: account_id required: true schema: description: The CRM account id whose claims to list. examples: - acc-123 type: string - description: Set to 'processing' to list in-flight claims as key entries instead of claims. explode: false in: query name: status schema: description: Set to 'processing' to list in-flight claims as key entries instead of claims. examples: - processing type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/GetClaimsBody" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: List PIX key claims tags: - Claims x-mint: href: /en/reference/interfaces/pix-jd/list-claims post: description: |- Opens a DICT claim (reivindicação) on a PIX key that another participant currently holds. You are the CLAIMER - the Cliente Reivindicador of §8.2.07 - and the body carries only key and accountId, because the claim TYPE is not yours to choose: the service decides it, portability when the key's holder document at DICT equals your account document and possession otherwise, which is the rule §8.2.07 states. The precondition the body does not show is the one that fails most often. The key must ALREADY sit on this account as a claim-pending row (status 4), and the only thing that creates one is POST /v1/entries answering that DICT recognised the key as claimable. Claiming a key you never tried to register is 422 PIX-0073. For a CPF or CNPJ key your account document must equal the key value, else 422 PIX-0086. The call is idempotent: a row already carrying a claim id returns that claim instead of opening a second one. On success the row moves to status 5 - waiting for the holder to hand the key over. §8.2.07 gives the holder a deadline to read the claim and then a further deadline to accept or refuse it; this service neither enforces nor exposes those windows, so track the outcome with GET /v1/claims?status=processing or GET /v1/entries. Per §8.2.07 an EVP (RANDOM) key cannot be claimed at all - mint a new one instead. operationId: claimKey requestBody: content: application/json: schema: $ref: "#/components/schemas/ClaimBody" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/ClaimResponse" description: Created "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Open a PIX key claim tags: - Claims x-mint: href: /en/reference/interfaces/pix-jd/create-claim /v1/claims/{claimId}: delete: description: |- Abandons a claim. Either side may call it - the claimer giving up, or the holder refusing to hand the key over (§8.2.11). claimId is in the path; the body carries key and accountId. The claim must resolve to a local row for the pair (claimId, your account), else 404 PIX-0020. What reaches DICT depends on how far the claim got, and the counterparty can tell the difference. A row at status 5, 6 or 7 is live at DICT and is cancelled there. Anything else - notably status 4, recognised as claimable but never opened at DICT - is cancelled locally with NO DICT call, which is the fail-closed direction, because a spurious DICT cancel is the step that has no undo. The motivo follows the §8.2.11 matrix for the side and the claim type: a claimer (status 5 or 7) sends 0 = Solicitação do Usuário; a DONOR (status 6) sends 0 for a portability claim but 4 = Fraude for a possession claim, because 4 is the only value the Posse-Doador column accepts - so a possession refusal is recorded at Bacen as fraud rather than as a preference. Either way the key row ends CANCELLED (-1) and soft-deleted. CANCELLED is terminal - the state machine has no edge out of it - so the claim cannot be revived; start over with POST /v1/entries followed by POST /v1/claims. operationId: cancelClaim parameters: - description: The claim id. in: path name: claimId required: true schema: description: The claim id. examples: - claim-123 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ClaimActionBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ClaimStatusResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Cancel a PIX key claim tags: - Claims x-mint: href: /en/reference/interfaces/pix-jd/cancel-claim get: description: |- Reads one claim live from DICT (§8.2.15 Consultar Reivindicação). Nothing local is consulted: account_id exists only to validate the caller and to produce the ISPB §8.2.15 requires, and the plugin's own key row is deliberately ignored because it is absent for a claim this plugin never opened and gone once the row is soft-deleted. So this route serves the same universe as the default GET /v1/claims: any claim DICT associates with the caller's ISPB, including one opened by another account of the same institution. Note what the response does NOT carry - only claimId, key and ispb are serialized. DICT's situation and which side of the claim you are on are read and then dropped, so this route cannot tell you whether a claim is open, confirmed or cancelled; read state from GET /v1/claims?status=processing or GET /v1/entries instead. A claimId DICT does not know is 404 PIX-0020, and DICT being unavailable is 503 PIX-1050. operationId: getClaim parameters: - description: The claim id. in: path name: claimId required: true schema: description: The claim id. examples: - claim-123 type: string - description: The CRM account id of the caller. explode: false in: query name: account_id required: true schema: description: The CRM account id of the caller. examples: - acc-123 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ClaimResultResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Get a PIX key claim tags: - Claims x-mint: href: /en/reference/interfaces/pix-jd/retrieve-claim /v1/claims/{claimId}/conclusion: post: description: |- Finishes a claim you opened once the holder has accepted it. You are the CLAIMER, and this is where DICT binds the key to your account (§8.2.12). claimId is in the path; the body carries key and accountId. It is the point of no return - §8.2.12 offers no undo. Everything checkable is checked first. The claim must still appear in DICT's in-flight listing (§8.2.08, walked across pages so a claim past page one is still found); a local row must exist for the pair (claimId, your account); that row is projected to status 7, the holder gave it away; and a row that cannot legally reach FINALIZED is refused with 422 PIX-0073 before DICT is touched. A claim missing from the listing, or one with no local row, is 404 PIX-0020. On success your key row becomes FINALIZED (0) and the key is yours. The donor's own row is soft-deleted when it belongs to a different account: it keeps its DONATED status and simply stops appearing in that account's listing. Note that POST /v1/entries/{entryId}/confirmation also concludes a confirmed claim on the same key, so a transfer can be completed through either route. operationId: concludeClaim parameters: - description: The claim id. in: path name: claimId required: true schema: description: The claim id. examples: - claim-123 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ClaimActionBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ClaimStatusResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Conclude a PIX key claim tags: - Claims x-mint: href: /en/reference/interfaces/pix-jd/complete-claim /v1/claims/{claimId}/confirmation: post: description: |- Accepts a claim someone opened on YOUR key: you are the DONOR - the Cliente Doador - agreeing to hand it over (§8.2.10). claimId is in the path; the body carries key and accountId. Every check is local and runs BEFORE DICT, because the DICT confirmation has no undo and a refusal afterwards would leave the claim confirmed at Bacen while the caller was told the call failed. A claim row with that id must exist; your account must OWN the key named in the body, else 404 PIX-0069; and that key must be the one the claim targets, else 404 PIX-0020. The row must also stand at status 6 - I hold this key and must decide - and any other status, including a CLAIMER's own row at status 5, is 422 PIX-0073 before DICT is called. DICT is sent motivo 0 (Solicitação do Usuário), the only value §8.2.10 accepts in both donor columns. On success your key row becomes DONATED (3), which is terminal on your side: the state machine has no edge out of it, the key stops being yours, and only the claimer can finish the transfer with POST /v1/claims/{claimId}/conclusion. operationId: confirmClaim parameters: - description: The claim id. in: path name: claimId required: true schema: description: The claim id. examples: - claim-123 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ClaimActionBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ClaimStatusResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Confirm a PIX key claim tags: - Claims x-mint: href: /en/reference/interfaces/pix-jd/confirm-claim /v1/entries: get: description: |- Lists the PIX keys of the account named by account_id. The response is not a table read: it is rebuilt on every call by merging three sources - the live DICT directory listing for the account (§8.2.06, every key reported as ACTIVE), the plugin's own local key rows (whose status is only a hint), and the account's in-flight DICT claims (§8.2.08), all projected onto the same eKeyStatus enum. Rows are keyed by the key VALUE: a directory key wins over a local row for the same value, and a live claim overrides both, because claim state is authoritative at DICT. Nothing is written back, so the three sources never reconcile. A local row for a key DICT no longer holds keeps appearing with its stale status until the directory or a claim overrides it, and a key that exists only at DICT appears with no claimId and no local history. There is no filter and no pagination, and the claims source reads only the FIRST §8.2.08 page (100 rows), so an account with more in-flight claims than that is silently short. If any one of the three sources fails the whole request fails - the listing is never partial. account_id is required (omitting it is refused by schema validation; a blank value is 400 PIX-0061), and an account the CRM cannot resolve is 404 PIX-2016. operationId: getEntries parameters: - description: The CRM account id whose keys to list. explode: false in: query name: account_id required: true schema: description: The CRM account id whose keys to list. examples: - acc-123 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/EntryListBody" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: List PIX key entries tags: - Entries x-mint: href: /en/reference/interfaces/pix-jd/list-keys post: description: |- Registers a PIX key for the account named by accountId, and is also the only entry point to the claim flow. keyType must agree with the value in key (0=CPF, 1=CNPJ, 2=EMAIL, 3=PHONE, 4=RANDOM) or the call is 422 PIX-0010 naming the expected and detected types; omit key for RANDOM and DICT mints the EVP value (§8.2.01). isValidated is accepted but ignored - the service always restarts validation. An unvalidated EMAIL or PHONE key never reaches DICT on this call: the service stores it locally as awaiting ownership confirmation (status 2), sends a 6-digit code to that address, and answers with status 2. Finish it with POST /v1/entries/{entryId}/confirmation. Calling this route again for the same key re-arms the row with a NEW code and the previous one stops working. A key of those two types that the account already holds at DICT is 409 PIX-0071. CPF, CNPJ and RANDOM keys go straight to DICT. If DICT answers that the key is already registered elsewhere, the call still SUCCEEDS: the service records a claim-pending row (status 4) carrying the claim type DICT implied - portability when the current holder's document matches yours, possession otherwise (§8.2.07) - and no claim is opened yet. Opening it is POST /v1/claims, which works only on a row this call created. The whole operation is idempotent on (accountId, key): an existing live row is returned with its current status rather than registered a second time. operationId: registerEntry requestBody: content: application/json: schema: $ref: "#/components/schemas/RegisterEntryBody" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/CreateEntryResponse" description: Created "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Register a PIX key entry tags: - Entries x-mint: href: /en/reference/interfaces/pix-jd/create-key /v1/entries/verification: post: description: |- Bulk-checks whether each supplied PIX key exists in the DICT directory (§8.2.23 Verificar Existência de Chaves). accountId resolves the caller's ISPB only - it does not scope the answer - and keys carries 1 to 200 values; a batch outside those bounds is refused before any DICT call, with 400 PIX-0061 naming keys. What comes back is existence and nothing else: each row is a key plus an exists flag. It does not say who holds a key, whether YOU hold it, or whether it can be claimed, so it is not the pre-check for a claim - POST /v1/entries is, because that is what turns a key DICT already knows into the claim-pending row POST /v1/claims requires. Use this to sift a list of keys, for example before a batch payout. The response also echoes DICT's own jdpiReturnedAt and correlationId, which are the values support asks for. operationId: verifyEntries requestBody: content: application/json: schema: $ref: "#/components/schemas/VerifyEntriesBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/VerifyEntriesResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Verify PIX key existence tags: - Entries x-mint: href: /en/reference/interfaces/pix-jd/verify-pix-key-existence /v1/entries/{entryId}: delete: description: |- Removes a PIX key from the DICT directory and hides the plugin's local row. entryId is the key VALUE, URL-encoded; the body carries accountId. Two ownership gates run before anything is deleted, and both fail closed. The key must appear in the account's own §8.2.06 directory listing, and §8.2.14 must report it held by this ISPB and account number - a key held by anyone else is 403 PIX-0018, and an ownership check that could not complete refuses with the upstream cause rather than claiming the key is not yours. If DICT reports the key does not exist at all, no delete is sent: a stale local row is hidden so the listing stops advertising it, and with no local row either the call is 403 PIX-0018. Order matters for recovery. DICT is deleted FIRST, then the local row is soft-deleted (deleted_at is set and the status column is left alone, so nothing marks the row as cancelled). A failure between the two steps leaves the key gone upstream while the local row keeps surfacing in GET /v1/entries with its stale status; re-issuing this same DELETE cleans it up, because the absent-upstream branch above then applies. The DICT deletion itself cannot be undone through this API - register the key again with POST /v1/entries. operationId: deleteEntry parameters: - description: The PIX key value (URL-encoded). in: path name: entryId required: true schema: description: The PIX key value (URL-encoded). examples: - "11122233300" type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/DeleteEntryBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/DeleteEntryResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Delete a PIX key entry tags: - Entries x-mint: href: /en/reference/interfaces/pix-jd/delete-key put: description: |- Re-points an existing PIX key to a new transactional account and/or a new owner name inside the SAME participant (§8.2.02 Alterar Chave de Endereçamento). entryId is the key VALUE, URL-encoded, and it never changes - no operation in this API edits a key's value. Only the destination travels in the body: newBranch, newAccountType, newAccount, accountOpeningDate, newName and newTradeName, all optional per the spec. The owner identity (ISPB, CPF/CNPJ, person type) is derived server-side from accountId and is never read from the payload. reason is required and is DICT's motivo: 0=Customer Request, 2=Branch Transfer, 6=Reconciliation, 8=Receita Federal Validation; an EVP (RANDOM) key must not use 0. It is a pure control-plane write: the plugin does NOT touch its own key row, so GET /v1/entries reflects the change only through its DICT source and a local row keeps the old coordinates until then. DICT may open a possession or portability claim as a consequence of the change; when it does, the response carries claimOpenedAt. Failures are DICT's, translated into the PIX-1xxx family - an unknown key is 404 PIX-1011. operationId: changeEntry parameters: - description: The PIX key value (URL-encoded). in: path name: entryId required: true schema: description: The PIX key value (URL-encoded). examples: - foo@bar.com type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ChangeEntryBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ChangeEntryResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Change a PIX key entry tags: - Entries x-mint: href: /en/reference/interfaces/pix-jd/change-a-pix-key-entry /v1/entries/{entryId}/confirmation: post: description: |- Confirms ownership of an EMAIL or PHONE key with the 6-digit code POST /v1/entries delivered. entryId is the key VALUE, URL-encoded; the body carries token and accountId. On success the key is registered at DICT and the local row becomes FINALIZED (0); if that registration comes back claim-pending instead, the response carries THAT status and no key was bound. The route is dual-purpose, and the second purpose runs FIRST and ignores the code entirely: if DICT reports a CONFIRMED claim on this key - the holder has already agreed to give it away - the service concludes that claim at DICT (§8.2.12), soft-deletes the local pending row, and answers 200 with an EMPTY CreateEntryResponse - the JSON object {}, because every field is omitempty - and NOT an absent body. A generated client deserializes it normally; what it reads is every field unset, which is the signal that this branch ran and no key was bound here. That conclusion is irreversible, so a caller expecting a rejected code can find the transfer completed instead. Otherwise the code decides. It is matched by hash, so a code that fits no pending row of this account is 401 PIX-0059 - the same answer as a missing code, with nothing in the response distinguishing the two. A row that is not awaiting confirmation is 422 PIX-0073. operationId: confirmEntry parameters: - description: The PIX key value (URL-encoded). in: path name: entryId required: true schema: description: The PIX key value (URL-encoded). examples: - foo@bar.com type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ConfirmEntryBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/CreateEntryResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Confirm PIX key ownership tags: - Entries x-mint: href: /en/reference/interfaces/pix-jd/confirm-key /v1/entries/{entryId}/details: get: description: |- Resolves what DICT holds behind a PIX key - the payee document and name, the key type, the holder ISPB and an end-to-end id (§8.2.14 Consultar Chave de Endereçamento). entryId is the key VALUE, URL-encoded; account_id is the caller's CRM account. It is a SELF-lookup, not a directory search, and the shape does not show it: after the DICT read the service compares the payee document DICT returned against the caller's own account document and refuses the response with 422 PIX-0086 when they differ. A CPF or CNPJ key that is not the caller's own document is refused the same way BEFORE DICT is called. The only key this route will describe is therefore one whose holder document equals yours - it cannot be used to resolve a counterparty ahead of a payment. An account_id the CRM cannot resolve is 404 PIX-0063 here (not the PIX-2016 the sibling key routes answer), and a key DICT does not hold is 404 PIX-1011. operationId: entryDetails parameters: - description: The PIX key value (URL-encoded). in: path name: entryId required: true schema: description: The PIX key value (URL-encoded). examples: - foo@bar.com type: string - description: The CRM account id of the caller. explode: false in: query name: account_id required: true schema: description: The CRM account id of the caller. examples: - acc-123 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/EntryDetailsResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Get PIX key entry details tags: - Entries x-mint: href: /en/reference/interfaces/pix-jd/retrieve-key /v1/holder-removals: post: description: |- Severs ONE holder's ownership of a transactional account at the DICT (JDPI §8.2.05 Excluir Titular) and, as a consequence, has the DICT DELETE EVERY PIX key bound to that holder ON that account. The account itself stays open and the keys of its OTHER holders are untouched — that is the whole difference from POST /v1/account-closures, which closes the account and deletes every key on it regardless of holder. Call it when a joint holder leaves, or when a holder's link to the account ends for any other reason, after that holder has stopped transacting. Deletion at the DICT is not reversible: each key is gone from the national directory and has to be registered again to come back, which restarts its ownership and can open a claim if another institution claimed the key in the meantime. The target holder is named by personType + document and is deliberately NOT inferred from accountId: the holder being removed is frequently not the one whose credentials made the call. The ISPB is resolved server-side from accountId and never read from the body. ⚠️ A 200 does NOT mean every deletion succeeded. The response carries one outcome row per key the DICT attempted; read result on each (1 = deleted, 0 = not deleted, with resultDescription giving the reason), because only the successes are mirrored into this plugin's key projection. These rows are narrower than the account-closure ones — document and name are not populated here. Refusals: 400 PIX-0061 when accountId or account is empty, or accountType is outside 0..4; 404 PIX-2016 when accountId does not resolve; 400 PIX-1000 when the DICT rejects a field, naming it; 404 PIX-1011 when the DICT knows no such holder-and-account binding or no keys under it; 422 PIX-1007 when the DICT refuses the removal in the current state; 503 PIX-1050 when the DICT is unreachable. operationId: removeHolder requestBody: content: application/json: schema: $ref: "#/components/schemas/HolderRemovalBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/HolderRemovalResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Register a holder-ownership removal tags: - Entries x-mint: href: /en/reference/interfaces/pix-jd/register-a-holder-ownership-removal /v1/indirects: get: description: |- Lists this tenant's indirect participants, newest first, as one keyset page. Use it to find the indirectId an outbound order needs, and to see which participants are actually routable — status is the field that decides that: only ACTIVE resolves an inbound credit or may originate an outbound order. Read-only; nothing changes. The status and ispb filters are exact matches and combine with AND. Pagination is cursor-based, not offset-based: pass the previous page's nextCursor back as cursor, and a null nextCursor means that page was the last. limit defaults to 25 and is CLAMPED to 100 — a larger value is silently reduced rather than rejected, so do not read the page size you asked for as the page size you got. Every row's delivery.secret is redacted. The only refusal is 422 PIX-0098, for a status outside ACTIVE / SUSPENDED / CLOSED / PENDING_PROVISIONING: an unrecognized filter is rejected rather than silently ignored, so a typo cannot widen the result set. PENDING_PROVISIONING is still accepted as a filter but nothing is registered in it any more — it finds only rows written before registration became atomic, which are readable, not routable, and still hold their ispb. operationId: listIndirects parameters: - description: Filter by lifecycle status (ACTIVE, SUSPENDED, CLOSED, or the legacy PENDING_PROVISIONING). explode: false in: query name: status schema: description: Filter by lifecycle status (ACTIVE, SUSPENDED, CLOSED, or the legacy PENDING_PROVISIONING). examples: - ACTIVE type: string - description: Filter by exact ISPB (8 digits). explode: false in: query name: ispb schema: description: Filter by exact ISPB (8 digits). examples: - "12345678" type: string - description: Page size (default 25, max 100). explode: false in: query name: limit schema: description: Page size (default 25, max 100). examples: - 25 format: int64 type: integer - description: Opaque pagination cursor from a prior page. explode: false in: query name: cursor schema: description: Opaque pagination cursor from a prior page. type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/IndirectPage" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: List indirect participants tags: - Indirects x-mint: href: /en/reference/interfaces/pix-jd/list-indirect-participants post: description: |- Registers an indirect participant in this tenant's registry and makes it usable in one step. Call it once per indirect you onboard, before any inbound credit or outbound order names it. REGISTRATION IS ATOMIC: a 201 means the participant is READY, and a failure means nothing was created. Before writing anything the service checks the ispb is not already held by a non-CLOSED indirect, optionally checks (on a tenant with JD directory validation enabled) that it exists as an SPI participant at JD, and creates the participant's `@pi_{ispb}` settlement account in Midaz — THE PLUGIN creates that account, a client never does. Only then is the row written, and it is written ACTIVE, so there is no intermediate state to poll and no `provisioning` field to read on the response. If any of those steps fails you get a coded error naming the step, NO registry row exists, and the ispb is still free: fix the cause and POST again. There is no retry endpoint, because there is nothing half-written to resume. THIS WRITE IS PERMANENT once it succeeds. There is no DELETE on /v1/indirects: the registry's only exit is PATCH with action `close`, CLOSED is terminal (nothing leaves it), and even a close keeps the row and its `@pi` account — the account is blocked, never deleted. An indirect registered by mistake against a live tenant stays in that tenant's registry, and its ispb is held against the open-uniqueness constraint until it is closed. Verify name, ispb and the delivery endpoint before calling. Refusals, all of which leave the registry untouched: 409 PIX-0093 when a non-CLOSED indirect already holds this ispb — a CLOSED one may be re-registered and reuses its historical `@pi` account; 422 PIX-0098 for a missing or over-120-character name, an ispb that is not exactly 8 digits, a delivery.endpointUrl that is not a valid https URL, a missing delivery.secret, an unknown messagingMode, an absent ispb (the `@pi_{ispb}` alias derives from it, so the MVP requires one), or — on a tenant with JD directory validation enabled — an ispb JD does not know as an SPI participant; 502 PIX-0099 when a step failed on a retryable fault, naming the step (validateISPB or createPIAccount) so you know which dependency to check before re-POSTing; 503 PIX-4002 when the ledger could not be reached to create the settlement account; 409 PIX-0107 when no delivery-secret encryption key is provisioned for this tenant — an operator has to provision it, so re-POSTing unchanged fails identically, and the response body names the knob; 503 PIX-0123 when that key could not be READ from its key source, which is a fault on our side rather than a missing value and is safe to repeat shortly. Re-POSTing after a failure is safe: the settlement account is created by alias, so an attempt that got that far and then failed leaves an account the next attempt adopts rather than duplicating. operationId: createIndirect requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateIndirectBody" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/Indirect" description: Created "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Register an indirect participant tags: - Indirects x-mint: href: /en/reference/interfaces/pix-jd/register-an-indirect-participant /v1/indirects/{indirectId}: get: description: |- Returns one indirect participant by id with its full registry record: lifecycle status, the derived `@pi_{ispb}` settlement-account alias its money moves through, the delivery configuration, and the own-QR-certificate configuration. Call it to read back the `@pi` alias, and to see the CURRENT lifecycle status after a suspend, a reactivate or a close. Read-only, and uncached: it always reads the registry row, unlike the cached slim projection the money paths resolve against — so this is the operation that tells you the CURRENT state, while a suspend may take up to the resolution-cache TTL to be seen by every replica. delivery.secret always comes back as "***": the stored credential is write-only and no operation returns it, so a lost secret is replaced with a PATCH rather than recovered. The `provisioning` object is always present, and its `failedStep` is LEGACY: it is null for anything registered by this service, because registration is atomic and a failure leaves no row to describe. A row that does carry a failedStep, and sits in PENDING_PROVISIONING, was written before that change — it is not routable and its ispb is still held. Refusals: 404 PIX-0095 when no indirect with that id exists in this tenant — an id belonging to another tenant is deliberately indistinguishable from an unknown one; 422 PIX-0098 when indirectId is not a valid UUID. operationId: getIndirect parameters: - description: The indirect participant id. in: path name: indirectId required: true schema: description: The indirect participant id. examples: - 018f2b7c-0000-7000-8000-000000000000 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Indirect" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Get an indirect participant tags: - Indirects x-mint: href: /en/reference/interfaces/pix-jd/get-an-indirect-participant patch: description: |- Applies mutable-field changes and/or ONE lifecycle action to an indirect. Absent (null) body fields are left untouched, so a PATCH carrying only action moves the lifecycle and changes nothing else; a PATCH carrying neither a field nor an action is a no-op that returns the current row without writing anything, not an error. The lifecycle actions are suspend, reactivate and close, and each one writes the LEDGER as well as the registry. suspend disables both sending and receiving on the indirect's `@pi` account, so the ledger refuses that participant's money even if another replica's resolution cache is still stale; reactivate re-enables both. close is IRREVERSIBLE — CLOSED is terminal, nothing leaves it, and afterwards every field mutation on the row is refused too. close never deletes: the `@pi` account is permanently blocked but kept, so a later re-registration of the same ISPB reuses it. When a lifecycle action and field changes arrive together, the action is what the audit trail records. Refusals: 409 PIX-0094 when the action is illegal from the current status (any action on a legacy PENDING_PROVISIONING row or on a CLOSED one, reactivate on anything but SUSPENDED) — re-issuing an action the row already reached is illegal too, not an idempotent success; 409 PIX-0096 when close is attempted while the `@pi` account still holds an available or on-hold balance, refused so the funds cannot be stranded (settle it to zero first); 409 PIX-0007 when another writer changed the row concurrently — reload and retry; 404 PIX-0095 for an unknown id; 422 PIX-0098 for an unknown action, a name over 120 characters, a delivery.endpointUrl that is not a valid https URL, or a qrCertificate.publicBaseUrl that is absent while ownCertificate is true, carries a scheme, is not a bare host with an optional path, or does not name a publicly resolvable host; 422 PIX-0111 when the body carries qrCertificate and this tenant's indirect-participants feature is not enabled — the WHOLE patch is refused, including any name or delivery change riding alongside; 503 PIX-4002 when the ledger could not be reached to check the balance or move the account flags. operationId: updateIndirect parameters: - description: The indirect participant id. in: path name: indirectId required: true schema: description: The indirect participant id. examples: - 018f2b7c-0000-7000-8000-000000000000 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/UpdateIndirectBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/Indirect" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Update an indirect participant tags: - Indirects x-mint: href: /en/reference/interfaces/pix-jd/update-an-indirect-participant /v1/indirects/{indirectId}/jwks: get: description: |- Returns the JWK Set JDPI signs THIS indirect's dynamic-QR JWS with, as an application/jwk-set+json document, so the indirect can publish it on its own host for payer PSPs to validate signatures against. The indirect cannot produce this itself — JDPI holds the certificate and does the signing — which is why the convenience lives on the direct participant's API. Call it once when onboarding an indirect onto its own QR certificate (after qrCertificate.ownCertificate is set), and again whenever that certificate is rotated; then serve the bytes verbatim at the JWKS location under the indirect's own base URL. It is read-only and changes nothing here. It is ONLY for an indirect that hosts its own certificate: one that falls back to the direct participant has no key set of its own and is refused 422 PIX-0114, which names the direct participant's own JWKS route to publish instead. Lifecycle status is deliberately NOT a condition — a SUSPENDED or CLOSED indirect still has live QR codes in the wild, and withholding the key would break their validation. Every answer carries X-JWK-Set-Freshness: 'fresh' when the key set came from inside the cache TTL, or 'stale' when the TTL had expired, JDPI could not be reached, and a cached key set was served instead — a 200 alone does not assert freshness, since a cached document and a fresh one are the same bytes. Refusals: 422 PIX-0111 when this tenant's indirect-participants feature is not enabled (no QR is signed with any indirect certificate while it is off, so the key set would validate nothing); 404 PIX-0095 for an unknown id; 422 PIX-0114 for the fallback case above; 422 PIX-0098 when the indirect carries no ispb, which is the key §8.3.11 is looked up by; 503 PIX-1050 when JDPI is unreachable and nothing is cached — attributed to JDPI, never presented as a configuration error. operationId: getIndirectJWKS parameters: - description: The indirect participant id. in: path name: indirectId required: true schema: description: The indirect participant id. examples: - 018f2b7c-0000-7000-8000-000000000000 type: string responses: "200": content: application/jwk-set+json: schema: $ref: "#/components/schemas/JWKSet" description: OK headers: X-JWK-Set-Freshness: schema: description: "'fresh' when the key set is within its cache freshness window — fetched from JDPI for this request, or cached less than the TTL ago; 'stale' when that window had expired AND JDPI could not be reached, so a cached key set was served instead." examples: - fresh type: string "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Get an indirect participant's JWK Set tags: - Indirects x-mint: href: /en/reference/interfaces/pix-jd/get-an-indirect-participant-jwk-set /v1/indirects/{indirectId}/transactions: get: description: |- Returns the movements that actually settled on ONE indirect participant's `@pi_{ispb}` account, so that participant can reconcile its own books against this ledger. Each row carries the end-to-end id, the direction, the amount, the settlement status, the instant it was booked, and both parties as captured at settlement — the payee block being the indirect's own client on a credit. Call it whenever you need the authoritative record rather than the notice: this plugin PUSHES a message to the indirect's delivery endpoint on every movement, and that push can die permanently (the retries are exhausted, or the endpoint answers 4xx, after which the notice is parked as INVALID and never retried). The money is booked correctly either way, so a movement whose notice failed is invisible to the indirect until it is read here. Sweeping this feed on a schedule is what closes that gap; it is also the only way to re-read a window after a local outage. Read-only; nothing changes, and no notice is re-sent. **amount is in CENTAVOS, as an integer** — 1050 is R$ 10,50. It is never a decimal, and never reais. **since is REQUIRED**, as an RFC 3339 instant. The feed is always read over a bounded window: without a lower bound the query is an unbounded sweep of the money table whose answer is not reproducible between two calls, so a caller could not tell a slow response from a truncated one. The window is HALF-OPEN — `since` is inclusive, `until` is exclusive — so two adjacent sweeps neither double-count a movement nor leave one in the gap between them; passing the previous window's `until` as the next window's `since` is the correct way to walk forward. `until` is optional and, when absent, leaves the window open-ended. **Rows come back OLDEST FIRST, ordered by (occurredAt, id), and the cursor is the ONLY correct way to page.** The order is stable to the row: two movements can be booked in the same instant, and without the id as a tie-break a page boundary falling between them would return one of them and drop the other silently — which for a reconciliation is worse than returning nothing. Pass the previous page's nextCursor back as `cursor`; a null nextCursor means that page was the last one in the window. Do NOT try to page by advancing `since` past the last row's occurredAt: that skips every other movement booked in that same instant. The cursor is opaque — its content is this service's business and is free to change. `limit` defaults to 25 and is CLAMPED to 100 (a larger value is silently reduced, not rejected), so do not read the page size you asked for as the page size you got. Refusals: 404 PIX-0095 when no indirect with that id exists in this tenant — an id belonging to another tenant is deliberately indistinguishable from an unknown one, and no movement is ever read for it; 422 PIX-0098 when `indirectId` is not a valid UUID, when `since` is absent or is not an RFC 3339 instant, when `until` is not an RFC 3339 instant or is not strictly after `since`, or when `cursor` is not a token this service issued (a cursor is refused rather than silently treated as the start of the window, which would replay settled movements as if they were new). operationId: listIndirectTransactions parameters: - description: The indirect participant id. in: path name: indirectId required: true schema: description: The indirect participant id. examples: - 018f2b7c-0000-7000-8000-000000000000 type: string - description: "Window start, INCLUSIVE, as an RFC 3339 instant. Required: the feed is never read unbounded." explode: false in: query name: since required: true schema: description: "Window start, INCLUSIVE, as an RFC 3339 instant. Required: the feed is never read unbounded." examples: - "2026-09-01T00:00:00Z" type: string - description: Window end, EXCLUSIVE, as an RFC 3339 instant. Absent leaves the window open-ended. explode: false in: query name: until schema: description: Window end, EXCLUSIVE, as an RFC 3339 instant. Absent leaves the window open-ended. examples: - "2026-09-02T00:00:00Z" type: string - description: Opaque cursor from the previous page's nextCursor. explode: false in: query name: cursor schema: description: Opaque cursor from the previous page's nextCursor. type: string - description: Page size (default 25, clamped to 100). explode: false in: query name: limit schema: description: Page size (default 25, clamped to 100). examples: - 25 format: int64 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/IndirectTransactionPage" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: List an indirect participant's transactions tags: - Indirects x-mint: href: /en/reference/interfaces/pix-jd/list-indirect-participant-transactions /v1/limits: get: description: |- Lists the PIX limit rows that exist for the account named by account_id. Each row is a (transactionType, periodType, limitType) tuple plus an amount in centavos: periodType is DAILY, NIGHTLY or MONTHLY; limitType is TRANSACTION, the cap on a single payment, or PERIOD, the cap on everything inside the window; transactionType is always PIX. No endpoint in this API creates a limit row. Four of them - PERIOD and TRANSACTION for DAILY and NIGHTLY, at a deployment-configured default of 30000 reais - are seeded lazily the first time POST /v1/transactions runs the limit check for the account, and a MONTHLY row is never created by the service at all. Until that first payment attempt this route answers 200 with an empty data array rather than a 404, and PATCH /v1/limits has no row to change. An account_id the CRM cannot resolve is 404 PIX-2016. operationId: getTransactionLimits parameters: - description: The CRM account id whose limits to read. explode: false in: query name: account_id required: true schema: description: The CRM account id whose limits to read. examples: - acc-123 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/TransactionLimitsBody" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: List PIX transaction limits tags: - Limits x-mint: href: /en/reference/interfaces/pix-jd/retrieve-transaction-limits patch: description: |- Changes the amount of ONE existing limit row. The row is addressed by its natural key rather than by an id: accountId, plus periodType (DAILY, NIGHTLY or MONTHLY, case-insensitive) and limitType (TRANSACTION or PERIOD, case-insensitive); transactionType is always PIX. amount is the new cap in centavos and must be greater than zero. It is update-only. It never creates a row, and no other endpoint does either - the four default rows appear only after POST /v1/transactions first runs the limit check for the account (see GET /v1/limits). A MONTHLY row, which the service never seeds, therefore cannot be changed here. The refusals are worth knowing before you debug one: an unknown periodType, an unknown limitType, and a well-formed tuple with no matching row ALL answer 422 PIX-0036, carrying the message about a transaction status transition not being permitted, and nothing in the response tells the three apart. A non-positive amount is the one distinct case, 422 PIX-0030 naming the amount. A new cap applies from the next POST /v1/transactions; there is no scheduling and no approval window. operationId: changeTransactionLimits requestBody: content: application/json: schema: $ref: "#/components/schemas/ChangeLimitBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ChangeLimitResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Change a PIX transaction limit tags: - Limits x-mint: href: /en/reference/interfaces/pix-jd/update-transaction-limit /v1/limits/available: get: description: |- Computes what is left of each limit for the account: availableAmount = totalLimit - usedAmount, floored at zero, in exact int64 centavos with no rounding. currentPeriod names the period that is active right now. The windows are the part that surprises callers, and they are UTC calendar-day bands. DAILY is the half-open [init, end) hour range taken from the tenant's systemplane knobs transaction_limits.daily_period_init and transaction_limits.daily_period_end (6 and 20 when unset). NIGHTLY is the WHOLE complement of that band summed across the day - both [00:00, init) and [end, 24:00), not only the band the request falls in. MONTHLY is summed over a single UTC day, NOT a month, so a MONTHLY row's usedAmount reports today's usage only. usedAmount is the sum of the account's live outbound rows of the same transaction type - CASH_OUT plus on-us INTRA_PSP - created inside the window, with NO status filter, so a pending or failed payment still counts against you; outbound refunds are included too, matching what the enforcement check counts. An account with no limit rows at all is 404 PIX-0063 (see GET /v1/limits for why that is a normal state rather than a fault), and an account_id the CRM cannot resolve is 404 PIX-2016. operationId: getAvailableLimits parameters: - description: The CRM account id whose limits to read. explode: false in: query name: account_id required: true schema: description: The CRM account id whose limits to read. examples: - acc-123 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/AvailableLimitsResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Get available PIX limits tags: - Limits x-mint: href: /en/reference/interfaces/pix-jd/retrieve-available-limits /v1/med/credits/inbound: post: description: "Posts the receiving-side refund CREDIT on the local Midaz ledger when SPI settles a MED devolucao (the plugin is the SGCT server; JDPI calls this after the pacs.004 is received, contract §2.28). It posts a balanced COMMITTED double-entry (clearing credit, recipient debit-mirror) and mints the idCreditoSgct. The Authorization (Bearer) header is mandatory on this financial ingress: a missing/invalid token is a coded 401. A re-delivered credit for the same endToEndIdDevolucao echoes the prior idCreditoSgct with no second post (idempotent)." operationId: registerMedInboundRefundCredit parameters: - description: Bearer access token (the financial-ingress gate; the handler fails closed with PIX-0082 when absent). in: header name: Authorization schema: description: Bearer access token (the financial-ingress gate; the handler fails closed with PIX-0082 when absent). examples: - Bearer eyJ... type: string - description: Idempotency key (= the endToEndIdDevolucao). Mandatory per the MED SPI credit contract. in: header name: Chave-Idempotencia required: true schema: description: Idempotency key (= the endToEndIdDevolucao). Mandatory per the MED SPI credit contract. examples: - D1111111120240918150000000000099 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/InboundCreditBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/InboundCreditView" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Register a MED inbound refund credit (THIRD RAIL — moves money) tags: - MED Inbound Credit x-mint: href: /en/reference/interfaces/pix-jd/register-a-med-inbound-refund-credit /v1/med/fraud-markers: get: description: "Lists the fraud markers where this institution is the creator (JDPI marcacao-fraude/listar, contract 2.18). Read live from JDPI. At least one of cpf_cnpj or created_from must be supplied: JDPI marks each mandatory when the other is absent, and either one alone is enough. The DICT-direct listing is a separate operation." operationId: listMedFraudMarkers parameters: - description: Restrict to the markers associated with this document. Required when created_from is absent. explode: false in: query name: cpf_cnpj schema: description: Restrict to the markers associated with this document. Required when created_from is absent. examples: - "12345678901" type: string - description: dtHrCriacaoInicio — restrict to the markers created at or after this instant (aaaa-mm-ddTHH:mm:ss.sssZ). Required when cpf_cnpj is absent. explode: false in: query name: created_from schema: description: dtHrCriacaoInicio — restrict to the markers created at or after this instant (aaaa-mm-ddTHH:mm:ss.sssZ). Required when cpf_cnpj is absent. examples: - "2026-04-01T00:00:00.000Z" type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/FraudMarkerListBody" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: List MED fraud markers (local base) tags: - MED Fraud Markers x-mint: href: /en/reference/interfaces/pix-jd/list-med-fraud-markers-local-base post: description: Opens a fraud marker as the creator PSP (JDPI marcacao-fraude/incluir, contract 2.15). The creator ISPB is derived from configuration. tpFraude is validated against the create domain {0..3} before any JDPI call. operationId: registerMedFraudMarker requestBody: content: application/json: schema: $ref: "#/components/schemas/RegisterFraudMarkerRequestBody" required: true responses: "202": content: application/json: schema: $ref: "#/components/schemas/FraudMarkerView" description: Accepted "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Register a MED fraud marker tags: - MED Fraud Markers x-mint: href: /en/reference/interfaces/pix-jd/register-a-med-fraud-marker /v1/med/fraud-markers/dict: get: description: Lists the fraud markers for a document via the DICT-direct query (JDPI marcacao-fraude/listar/dict, contract 2.19). cpf_cnpj is required; chave and limit are optional filters. operationId: listMedFraudMarkersDict parameters: - description: The document to query (required for the DICT-direct listing). explode: false in: query name: cpf_cnpj required: true schema: description: The document to query (required for the DICT-direct listing). examples: - "12345678901" type: string - description: Optional key filter (must belong to cpf_cnpj if given). explode: false in: query name: chave schema: description: Optional key filter (must belong to cpf_cnpj if given). examples: - user@example.com type: string - description: DICT-mode page limit; 0 uses the JDPI default (20). explode: false in: query name: limit schema: description: DICT-mode page limit; 0 uses the JDPI default (20). examples: - 20 format: int64 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/FraudMarkerListBody" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: List MED fraud markers (DICT-direct) tags: - MED Fraud Markers x-mint: href: /en/reference/interfaces/pix-jd/list-med-fraud-markers-dict-direct /v1/med/fraud-markers/{idMarcacaoFraude}: get: description: Returns a single fraud marker by its idMarcacaoFraude GUID, read live from JDPI (contract 2.16). An unknown id returns a coded 404. operationId: getMedFraudMarker parameters: - description: The fraud-marker GUID. in: path name: idMarcacaoFraude required: true schema: description: The fraud-marker GUID. examples: - c3d4e5f6-a7b8-9012-cdef-345678901234 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/FraudMarkerView" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Get a MED fraud marker tags: - MED Fraud Markers x-mint: href: /en/reference/interfaces/pix-jd/get-a-med-fraud-marker /v1/med/fraud-markers/{idMarcacaoFraude}/cancel: post: description: Cancels a fraud marker as the creator PSP (JDPI marcacao-fraude/{id}/cancelar, contract 2.17). An unknown id returns a coded 404. operationId: cancelMedFraudMarker parameters: - description: The fraud-marker GUID. in: path name: idMarcacaoFraude required: true schema: description: The fraud-marker GUID. examples: - c3d4e5f6-a7b8-9012-cdef-345678901234 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CancelFraudMarkerRequestBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/FraudMarkerView" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Cancel a MED fraud marker tags: - MED Fraud Markers x-mint: href: /en/reference/interfaces/pix-jd/cancel-a-med-fraud-marker /v1/med/infractions: get: description: Lists the infractions detected by the worker pollers (filed by this institution or against it), filterable by status, role ISPB, and the suspect payment's endToEndId. Read projection — no JDPI round-trip. operationId: listMedInfractions parameters: - description: Filter on stRelatoInfracao (0=Aberto, 1=Recebido, 2=Cancelado, 3=Analisado). explode: false in: query name: status schema: description: Filter on stRelatoInfracao (0=Aberto, 1=Recebido, 2=Cancelado, 3=Analisado). examples: - "0" type: string - description: Filter on the counterparty ISPB (infractions filed against this institution). explode: false in: query name: psp_contraparte schema: description: Filter on the counterparty ISPB (infractions filed against this institution). examples: - "87654321" type: string - description: Filter on the creator ISPB (infractions this institution filed). explode: false in: query name: psp_criador schema: description: Filter on the creator ISPB (infractions this institution filed). examples: - "12345678" type: string - description: Filter on the suspect payment's endToEndId. explode: false in: query name: end_to_end_id schema: description: Filter on the suspect payment's endToEndId. examples: - E1234567820240101000000000000001 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/InfractionListBody" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: List MED infractions tags: - MED Infractions x-mint: href: /en/reference/interfaces/pix-jd/list-med-infractions /v1/med/infractions/{idRelatoInfracao}: get: description: Returns a single detected infraction by its idRelatoInfracao GUID from the local projection. An unknown id returns a coded 404. operationId: getMedInfraction parameters: - description: The infraction GUID. in: path name: idRelatoInfracao required: true schema: description: The infraction GUID. examples: - a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/InfractionView" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Get a MED infraction tags: - MED Infractions x-mint: href: /en/reference/interfaces/pix-jd/get-a-med-infraction /v1/med/infractions/{idRelatoInfracao}/analyze: post: description: Records the counterparty PSP's analysis result (JDPI relato-infracao/analisar, contract §2.4). The §2.4 invariants (resultadoAnalise {0=Aceita,1=Rejeitada}, tpFraude {0..4} required when Aceita) are validated before any JDPI call. Persists the JDPI response entity (the advanced watermark + minted idMarcacaoFraude) and returns it. operationId: analyzeMedInfraction parameters: - description: The infraction GUID. in: path name: idRelatoInfracao required: true schema: description: The infraction GUID. examples: - a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AnalyzeInfractionRequestBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/InfractionView" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Analyze a MED infraction tags: - MED Infractions x-mint: href: /en/reference/interfaces/pix-jd/analyze-a-med-infraction /v1/med/infractions/{idRelatoInfracao}/cancel: post: description: Cancels an infraction as the creator PSP (JDPI relato-infracao/cancelar, contract §2.3). Cancel is allowed at any time, even after Analisado. An unknown id returns a coded 404. Persists the JDPI response entity and returns it. operationId: cancelMedInfraction parameters: - description: The infraction GUID. in: path name: idRelatoInfracao required: true schema: description: The infraction GUID. examples: - a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CancelInfractionRequestBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/InfractionView" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Cancel a MED infraction tags: - MED Infractions x-mint: href: /en/reference/interfaces/pix-jd/cancel-a-med-infraction /v1/med/infractions/{idRelatoInfracao}/jdpi: get: description: Returns a single infraction by its idRelatoInfracao GUID read live from the JDPI base (JDPI relato-infracao/consultar, §8.2.18) — NOT from the local projection the sibling route serves, and NOT from the DICT-direct §8.2.38 query. The requesting ISPB is derived from the tenant binding. An unknown id returns a coded 404. Moves no money and persists nothing. operationId: getMedInfractionFromJdpi parameters: - description: The infraction GUID. in: path name: idRelatoInfracao required: true schema: description: The infraction GUID. examples: - a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/InfractionView" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Get a MED infraction from the JDPI base tags: - MED Infractions x-mint: href: /en/reference/interfaces/pix-jd/get-a-med-infraction-from-jdpi /v1/med/recoveries: post: description: Opens a value recovery as the creator PSP (JDPI recuperacao-valores/incluir, contract 2.20). The creator ISPB is derived from configuration. grafoRastreamento.vlrMinTransacao is a graph-traversal FILTER threshold, never a posting amount. operationId: createMedRecovery requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateRecoveryRequestBody" required: true responses: "202": content: application/json: schema: $ref: "#/components/schemas/RecoveryView" description: Accepted "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Create a MED value recovery tags: - MED Recoveries x-mint: href: /en/reference/interfaces/pix-jd/create-a-med-value-recovery /v1/med/recoveries/awaiting-devolver: get: description: Lists the creator-side Analisada value recoveries this institution may still trigger devolver on (contract §2.22/§5, within 72h of the Analise stage closing), ordered by devolver deadline (earliest first). The creator ISPB is config-derived. Each row surfaces devolverDeadline and a computed breached flag. Read projection — no JDPI round-trip; no action taken and no money moved. operationId: listMedRecoveriesAwaitingDevolver parameters: - description: Maximum number of rows to return; 0 uses the server default. explode: false in: query name: limit schema: description: Maximum number of rows to return; 0 uses the server default. examples: - 50 format: int64 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/RecoveryListBody" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: List MED recoveries awaiting devolver tags: - MED Recoveries x-mint: href: /en/reference/interfaces/pix-jd/list-med-recoveries-awaiting-devolver /v1/med/recoveries/{idRecValores}: get: description: Returns a single value recovery by its idRecValores GUID, read live from JDPI (contract 2.21). An unknown id returns a coded 404. operationId: getMedRecovery parameters: - description: The value-recovery GUID. in: path name: idRecValores required: true schema: description: The value-recovery GUID. examples: - b2c3d4e5-f6a7-8901-bcde-f23456789012 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RecoveryView" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Get a MED value recovery tags: - MED Recoveries x-mint: href: /en/reference/interfaces/pix-jd/get-a-med-value-recovery /v1/med/recoveries/{idRecValores}/amend: put: description: Records a field-only update to a value recovery (JDPI recuperacao-valores/{id} PUT, contract 2.23 — Alterar). It NEVER changes status. The contract 2.23 invariants are validated before any JDPI call. An unknown id returns a coded 404. operationId: amendMedRecovery parameters: - description: The value-recovery GUID. in: path name: idRecValores required: true schema: description: The value-recovery GUID. examples: - b2c3d4e5-f6a7-8901-bcde-f23456789012 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AmendRecoveryRequestBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/RecoveryView" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Amend a MED value recovery tags: - MED Recoveries x-mint: href: /en/reference/interfaces/pix-jd/amend-a-med-value-recovery /v1/med/recoveries/{idRecValores}/devolver: post: description: Starts the refund stage of a value recovery (JDPI recuperacao-valores/{id}/devolver, contract 2.22). It MOVES NO MONEY — it transitions stRecValores->4 and makes DICT emit refund requests. An unknown id returns a coded 404. operationId: devolverMedRecovery parameters: - description: The value-recovery GUID. in: path name: idRecValores required: true schema: description: The value-recovery GUID. examples: - b2c3d4e5-f6a7-8901-bcde-f23456789012 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/DevolverRecoveryRequestBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/RecoveryView" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Start a MED value recovery refund stage tags: - MED Recoveries x-mint: href: /en/reference/interfaces/pix-jd/start-a-med-value-recovery-refund-stage /v1/med/refunds: get: description: Lists the refund requests detected by the worker pollers (requested by this institution or against it), filterable by status, role ISPB, and the contested payment's endToEndId. Read projection — no JDPI round-trip. operationId: listMedRefunds parameters: - description: Filter on stSolDevolucao (0=Aberta, 1=Cancelada, 2=Analisada). explode: false in: query name: status schema: description: Filter on stSolDevolucao (0=Aberta, 1=Cancelada, 2=Analisada). examples: - "0" type: string - description: Filter on the contested ISPB (refunds requested against this institution). explode: false in: query name: ispb_contestado schema: description: Filter on the contested ISPB (refunds requested against this institution). examples: - "87654321" type: string - description: Filter on the requester ISPB (refunds this institution requested). explode: false in: query name: ispb_solicitante schema: description: Filter on the requester ISPB (refunds this institution requested). examples: - "12345678" type: string - description: Filter on the contested payment's endToEndId. explode: false in: query name: end_to_end_id schema: description: Filter on the contested payment's endToEndId. examples: - E1234567820240101000000000000001 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RefundRequestListBody" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: List MED refund requests tags: - MED Refunds x-mint: href: /en/reference/interfaces/pix-jd/list-med-refund-requests post: description: Opens a refund request as the solicitante PSP (JDPI devolucao/incluir, contract 2.7). The requesting ISPB is derived from configuration. Persists the JDPI response entity and returns it. operationId: solicitMedRefund requestBody: content: application/json: schema: $ref: "#/components/schemas/SolicitRefundRequestBody" required: true responses: "202": content: application/json: schema: $ref: "#/components/schemas/RefundRequestView" description: Accepted "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Open a MED refund request tags: - MED Refunds x-mint: href: /en/reference/interfaces/pix-jd/open-a-med-refund-request /v1/med/refunds/credits/{endToEndIdDevolucao}: get: description: Returns the CREDIT-side situation of a refund order by its pacs.004 endToEndIdDevolucao, read live from JDPI (JDPI credito-devolucao/{endToEndId}, §8.5.4). stJdPiProc here is the CREDIT domain, DISTINCT from the debit poll's despite the shared field name (§4.5). Moves no money and persists nothing — the credit itself is settled by the inbound §9.3.3 webhook, never by this read. operationId: getMedRefundCreditStatus parameters: - description: EndToEndId of the refund (pacs.004) whose credit status is being consulted. in: path name: endToEndIdDevolucao required: true schema: description: EndToEndId of the refund (pacs.004) whose credit status is being consulted. examples: - D1234567820240101000000000000099 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RefundCreditStatusView" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Get the credit status of a MED refund order tags: - MED Refunds x-mint: href: /en/reference/interfaces/pix-jd/get-a-med-refund-credit-status /v1/med/refunds/pending-analysis: get: description: Lists the OPEN refund requests this institution must analyse (contested against it), ordered by analysis deadline (earliest first). The contested ISPB is config-derived. Each row surfaces analysisDeadline (contract §5, 6h Fraude / 48h otherwise) and a computed breached flag. Read projection — no JDPI round-trip. operationId: listMedRefundsPendingAnalysis parameters: - description: Maximum number of rows to return; 0 uses the server default. explode: false in: query name: limit schema: description: Maximum number of rows to return; 0 uses the server default. examples: - 50 format: int64 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/RefundRequestListBody" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: List MED refund requests pending my analysis tags: - MED Refunds x-mint: href: /en/reference/interfaces/pix-jd/list-med-refund-requests-pending-my-analysis /v1/med/refunds/{idSolDevolucao}: get: description: Returns a single detected refund request by its idSolDevolucao GUID from the local projection. An unknown id returns a coded 404. operationId: getMedRefund parameters: - description: The refund-request GUID. in: path name: idSolDevolucao required: true schema: description: The refund-request GUID. examples: - d4e5f6a7-b8c9-0123-def4-56789012345a type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RefundRequestView" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Get a MED refund request tags: - MED Refunds x-mint: href: /en/reference/interfaces/pix-jd/get-a-med-refund-request /v1/med/refunds/{idSolDevolucao}/analyze: post: description: Records the contestado PSP's analysis result (JDPI devolucao/analisar, contract 2.12). The contract 2.12 conditional-required invariants are validated before any JDPI call. Persists the JDPI response entity (the advanced watermark) and returns it. operationId: analyzeMedRefund parameters: - description: The refund-request GUID. in: path name: idSolDevolucao required: true schema: description: The refund-request GUID. examples: - d4e5f6a7-b8c9-0123-def4-56789012345a type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AnalyzeRefundRequestBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/RefundRequestView" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Analyze a MED refund request tags: - MED Refunds x-mint: href: /en/reference/interfaces/pix-jd/analyze-a-med-refund-request /v1/med/refunds/{idSolDevolucao}/cancel: post: description: Cancels a not-yet-Analisada refund request as the solicitante PSP (JDPI devolucao/cancelar, contract 2.11). An unknown id returns a coded 404. Persists the JDPI response entity and returns it. operationId: cancelMedRefund parameters: - description: The refund-request GUID. in: path name: idSolDevolucao required: true schema: description: The refund-request GUID. examples: - d4e5f6a7-b8c9-0123-def4-56789012345a type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CancelRefundRequestBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/RefundRequestView" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Cancel a MED refund request tags: - MED Refunds x-mint: href: /en/reference/interfaces/pix-jd/cancel-a-med-refund-request /v1/med/refunds/{idSolDevolucao}/effectuate: post: description: "Effectuates the refund DEBIT at SPI for an accepted refund (JDPI POST /od, contract §2.24): posts a balanced PENDING Midaz double-entry (contestado debit, clearing credit) and generates the pacs.004. The debit commits on the settlement reconcile poll. The precondition (accepted AND not-yet-effectuated) is checked before any ledger touch; a non-accepted or already-effectuated request returns a coded 422 and a re-delivery is an idempotent no-double-post echo. An unknown id returns a coded 404." operationId: effectuateMedRefund parameters: - description: The accepted refund-request GUID to effectuate. in: path name: idSolDevolucao required: true schema: description: The accepted refund-request GUID to effectuate. examples: - d4e5f6a7-b8c9-0123-def4-56789012345a type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/EffectuateRefundView" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Effectuate a MED refund debit (THIRD RAIL — moves money) tags: - MED Refunds x-mint: href: /en/reference/interfaces/pix-jd/effectuate-a-med-refund-debit /v1/med/refunds/{idSolDevolucao}/jdpi: get: description: "Returns a single refund request by its idSolDevolucao GUID read live from the JDPI base (JDPI devolucao/consultar, §8.2.26) — NOT from the local projection the sibling route serves, and NOT from the DICT-direct §8.2.39 query. It is the only refund read that carries dtHrRegistro: §8.2.25 (the listar the pollers run) does not return that field. The requesting ISPB is derived from the tenant binding. An unknown id returns a coded 404. Moves no money and persists nothing." operationId: getMedRefundFromJdpi parameters: - description: The refund-request GUID. in: path name: idSolDevolucao required: true schema: description: The refund-request GUID. examples: - d4e5f6a7-b8c9-0123-def4-56789012345a type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RefundRequestView" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Get a MED refund request from the JDPI base tags: - MED Refunds x-mint: href: /en/reference/interfaces/pix-jd/get-a-med-refund-request-from-jdpi /v1/pix-automatico/authorizations: get: description: Lists live JDPI recurring-payment authorizations (JDPI 4.3.7), scoped by flow + update window, projecting each onto the local authorization status. operationId: listPixAutomaticoAuthorizations parameters: - description: fluxo (0=PSP Pagador, 1=PSP Recebedor). explode: false in: query name: flow schema: description: fluxo (0=PSP Pagador, 1=PSP Recebedor). examples: - 1 format: int64 type: integer - description: cnpjRecebedor filter (string). explode: false in: query name: recipientCnpj schema: description: cnpjRecebedor filter (string). examples: - "61695227000193" type: string - description: tpPessoaPagador filter (0/1; empty = no filter). explode: false in: query name: payerPersonType schema: description: tpPessoaPagador filter (0/1; empty = no filter). examples: - "0" type: string - description: cpfCnpjPagador filter (string). explode: false in: query name: payerDocument schema: description: cpfCnpjPagador filter (string). examples: - "04623217035" type: string - description: nrAgenciaPagador filter (string). explode: false in: query name: payerAgency schema: description: nrAgenciaPagador filter (string). examples: - "0001" type: string - description: nrContaPagador filter (string). explode: false in: query name: payerAccount schema: description: nrContaPagador filter (string). examples: - "0007654321" type: string - description: resultadoAutorizacao filter (true/false; empty = no filter). explode: false in: query name: authorizationOk schema: description: resultadoAutorizacao filter (true/false; empty = no filter). examples: - "true" type: string - description: stJdPiProc filter (0..10; empty = no filter). explode: false in: query name: stJdPiProc schema: description: stJdPiProc filter (0..10; empty = no filter). examples: - "9" type: string - description: dtHrAtualizacaoRecorrenciaInicio (UTC). explode: false in: query name: updatedFrom schema: description: dtHrAtualizacaoRecorrenciaInicio (UTC). examples: - "2024-01-01T00:00:00Z" type: string - description: dtHrAtualizacaoRecorrenciaFim (UTC). explode: false in: query name: updatedTo schema: description: dtHrAtualizacaoRecorrenciaFim (UTC). examples: - "2024-06-19T00:00:00Z" type: string - description: pagina (default 1). explode: false in: query name: page schema: description: pagina (default 1). examples: - 1 format: int64 type: integer - description: tamanhoPagina (default 50, max 100). explode: false in: query name: pageSize schema: description: tamanhoPagina (default 50, max 100). examples: - 50 format: int64 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/ListAuthorizationsResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: List PIX Automatico authorizations tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/list-pix-automatico-authorizations post: description: Requests a recurring-payment authorization (recorrencia) as the PSP Recebedor (JDPI 4.3.1). Persists the authorization in the Requested state and returns the JDPI request id. operationId: requestPixAutomaticoAuthorization requestBody: content: application/json: schema: $ref: "#/components/schemas/RequestAuthorizationBody" required: true responses: "202": content: application/json: schema: $ref: "#/components/schemas/RequestAuthorizationResponse" description: Accepted "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Request a PIX Automatico authorization tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/request-a-pix-automatico-authorization /v1/pix-automatico/authorizations/inbound/cancellation/register: post: description: Registers a recurring-payment cancellation outcome delivered by JDPI (section 5.2.5, the plugin is the server). An accepted cancellation (stCancelamento=0) transitions the authorization to Cancelled and soft-deletes the row; a rejected cancellation (stCancelamento=1) is acknowledged with no state change. Returns the local SGCT id. operationId: registerInboundPixAutomaticoCancellation requestBody: content: application/json: schema: $ref: "#/components/schemas/RegisterCancellationBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/RegisterCancellationResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Register an inbound PIX Automatico cancellation tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/register-an-inbound-pix-automatico-cancellation /v1/pix-automatico/authorizations/inbound/cancellation/validate: post: description: Validates an inbound recurring-payment cancellation request pushed by JDPI (section 5.2.2, the plugin is the server). The cancellation is valid iff a live authorization exists and the FSM permits a transition to Cancelled from its current status; the result is returned inline (200). operationId: validateInboundPixAutomaticoCancellation requestBody: content: application/json: schema: $ref: "#/components/schemas/ValidateCancellationBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ValidateCancellationResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Validate an inbound PIX Automatico cancellation tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/validate-an-inbound-pix-automatico-cancellation /v1/pix-automatico/authorizations/inbound/payer/register: post: description: "Registers an inbound recurring-payment solicitation delivered by JDPI to the PSP Pagador (section 5.2.3, the plugin is the server). This is payer-side genesis: it creates the payer-side authorization row in the Requested state and returns the local SGCT id. A re-delivered solicitation resolves to a 409 conflict." operationId: registerInboundPixAutomaticoPayerRequest requestBody: content: application/json: schema: $ref: "#/components/schemas/RegisterRequestBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/RegisterRequestResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Register an inbound PIX Automatico solicitation on the PSP Pagador tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/register-an-inbound-pix-automatico-solicitation-on-the-psp-pagador /v1/pix-automatico/authorizations/inbound/recipient/register: post: description: Registers the payer's authorization result delivered by JDPI to the PSP Recebedor (section 5.2.4, the plugin is the server). It loads the existing recebedor-side authorization row and transitions it to Accepted or Rejected per resultadoAutorizacao, returning the local SGCT id. operationId: registerInboundPixAutomaticoRecipientAuthorization requestBody: content: application/json: schema: $ref: "#/components/schemas/RegisterAuthorizationBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/RegisterAuthorizationResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Register an inbound PIX Automatico authorization on the PSP Recebedor tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/register-an-inbound-pix-automatico-authorization-on-the-psp-recebedor /v1/pix-automatico/authorizations/inbound/validate: post: description: Validates an inbound recurring-payment authorization request pushed by JDPI (section 5.2.1, the plugin is the server). A synchronous validation returns the result inline (200); a Jornada-3 authorization returns 202-async with the eventual result delivered via the outbound 4.3.10 validation reply. operationId: validateInboundPixAutomaticoAuthorization requestBody: content: application/json: schema: $ref: "#/components/schemas/ValidateAuthorizationBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ValidateAuthorizationResponse" description: OK "202": description: Jornada-3 async acknowledgement (dtHrValidacao only). "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error summary: Validate an inbound PIX Automatico authorization tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/validate-an-inbound-pix-automatico-authorization /v1/pix-automatico/authorizations/{idRecorrencia}: get: description: Consults the live JDPI situation of a recurring-payment authorization (JDPI 4.3.4), projecting the JDPI situation axes onto the local authorization status. operationId: getPixAutomaticoAuthorization parameters: - description: The recurrence id (29-char, RR...). in: path name: idRecorrencia required: true schema: description: The recurrence id (29-char, RR...). examples: - RR0435879820240605njua7shf40o type: string - description: The JDPI request id (GUID) fallback when the idRecorrencia consult 404s. explode: false in: query name: idReqJdPi schema: description: The JDPI request id (GUID) fallback when the idRecorrencia consult 404s. examples: - "" type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/AuthorizationResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Consult a PIX Automatico authorization situation tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/consult-a-pix-automatico-authorization-situation /v1/pix-automatico/authorizations/{idRecorrencia}/cancel: post: description: Cancels a recurring-payment authorization (JDPI 4.3.5), transitioning it to Cancelled and soft-deleting the local row. Returns the cancellation id (idCancelamento). operationId: cancelPixAutomaticoAuthorization parameters: - description: The recurrence id (29-char, RR...). in: path name: idRecorrencia required: true schema: description: The recurrence id (29-char, RR...). examples: - RR0435879820240605njua7shf40o type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CancelAuthorizationBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/CancelAuthorizationResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Cancel a PIX Automatico authorization tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/cancel-a-pix-automatico-authorization /v1/pix-automatico/authorizations/{idRecorrencia}/cancel/{idCancelamento}: get: description: Consults the live JDPI situation of an authorization cancellation (JDPI 4.3.6), keyed by (idRecorrencia, idCancelamento). operationId: getPixAutomaticoAuthorizationCancellation parameters: - description: The recurrence id (29-char, RR...). in: path name: idRecorrencia required: true schema: description: The recurrence id (29-char, RR...). examples: - RR0435879820240605njua7shf40o type: string - description: The cancellation id (29-char, IC...). in: path name: idCancelamento required: true schema: description: The cancellation id (29-char, IC...). examples: - IC0435879820240605abcd1234567 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/CancellationDetailResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Consult a PIX Automatico authorization cancellation tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/consult-a-pix-automatico-authorization-cancellation /v1/pix-automatico/authorizations/{idRecorrencia}/confirm: post: description: Confirms a recurring-payment authorization via QR journeys 2-4 (JDPI 4.3.3), transitioning it to Active (the live recurring-payment mandate). operationId: confirmPixAutomaticoAuthorization parameters: - description: The recurrence id (29-char, RR...). in: path name: idRecorrencia required: true schema: description: The recurrence id (29-char, RR...). examples: - RR0435879820240605njua7shf40o type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ConfirmAuthorizationBody" required: true responses: "202": content: application/json: schema: $ref: "#/components/schemas/AuthorizationAckResponse" description: Accepted "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Confirm a PIX Automatico authorization tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/confirm-a-pix-automatico-authorization /v1/pix-automatico/authorizations/{idRecorrencia}/max-value: put: description: Updates the payer max-value cap of an Active recurring-payment authorization (JDPI 4.3.9). This is not a status transition; an omitted/zero value removes the cap. operationId: updatePixAutomaticoAuthorizationMaxValue parameters: - description: The recurrence id (29-char, RR...). in: path name: idRecorrencia required: true schema: description: The recurrence id (29-char, RR...). examples: - RR0435879820240605njua7shf40o type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/UpdateMaxValueBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/UpdateMaxValueResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Update a PIX Automatico authorization max value tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/update-a-pix-automatico-authorization-max-value /v1/pix-automatico/authorizations/{idRecorrencia}/respond: put: description: Accepts or rejects a recurring-payment authorization as the PSP Pagador (JDPI 4.3.2). An acceptance transitions the authorization to Accepted; a rejection to Rejected. operationId: respondPixAutomaticoAuthorization parameters: - description: The recurrence id (29-char, RR...). in: path name: idRecorrencia required: true schema: description: The recurrence id (29-char, RR...). examples: - RR0435879820240605njua7shf40o type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/RespondAuthorizationBody" required: true responses: "202": content: application/json: schema: $ref: "#/components/schemas/AuthorizationAckResponse" description: Accepted "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Respond to a PIX Automatico authorization tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/respond-to-a-pix-automatico-authorization /v1/pix-automatico/authorizations/{idRecorrencia}/validation: post: description: Registers the deferred async validation reply for a recurring-payment authorization (JDPI 4.3.10), the outbound reply to an inbound 5.2.1 that returned 202-async. operationId: registerPixAutomaticoAuthorizationValidation parameters: - description: The recurrence id (29-char, RR...). in: path name: idRecorrencia required: true schema: description: The recurrence id (29-char, RR...). examples: - RR0435879820240605njua7shf40o type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/RegisterValidationBody" required: true responses: "202": content: application/json: schema: $ref: "#/components/schemas/AuthorizationAckResponse" description: Accepted "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Register a PIX Automatico authorization validation tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/register-a-pix-automatico-authorization-validation /v1/pix-automatico/composite/cobv: post: description: Generates a composite PIX QR code embedding due-date dynamic-QR data (cobrança com vencimento) and a recurring-payment authorization (PIX Automatico). The recipient name and city are CRM-sourced from the account. operationId: createCobvCompositeQRCode requestBody: content: application/json: schema: $ref: "#/components/schemas/CobvCompositeBody" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/CompositeResponse" description: Created "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Create a CobV (due-date) composite PIX Automatico QR code tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/create-a-cobv-due-date-composite-pix-automatico-qr-code /v1/pix-automatico/composite/cobv/{id}: put: description: Updates a previously generated CobV (cobrança com vencimento) composite PIX QR code, keyed by its document id (idDocumento). The response carries the JDPI-computed revision (revisao). operationId: updateCobvCompositeQRCode parameters: - description: The recurrence/charge document id (idDocumento, GUID). in: path name: id required: true schema: description: The recurrence/charge document id (idDocumento, GUID). examples: - 52c43361-caa1-4ddb-9152-708426a25db5 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/UpdateCobvCompositeBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/CompositeUpdateResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Update a CobV (due-date) composite PIX Automatico QR code tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/update-a-cobv-due-date-composite-pix-automatico-qr-code /v1/pix-automatico/composite/decode: post: description: Decodes a composite PIX QR code from its embedded recurrence URL (urlPayloadJsonRec), returning the recurring-payment authorization configuration. operationId: decodeCompositeQRCode requestBody: content: application/json: schema: $ref: "#/components/schemas/DecodeCompositeBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/DecodeCompositeResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Decode a composite PIX Automatico QR code from its URL tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/decode-a-composite-pix-automatico-qr-code-from-its-url /v1/pix-automatico/composite/dynamic: post: description: Generates a composite PIX QR code embedding immediate-dynamic-QR data and a recurring-payment authorization (PIX Automatico). The recipient name and city are CRM-sourced from the account. operationId: createDynamicCompositeQRCode requestBody: content: application/json: schema: $ref: "#/components/schemas/DynamicCompositeBody" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/CompositeResponse" description: Created "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Create an immediate dynamic composite PIX Automatico QR code tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/create-an-immediate-dynamic-composite-pix-automatico-qr-code /v1/pix-automatico/composite/dynamic/{id}: put: description: Updates a previously generated immediate-dynamic composite PIX QR code, keyed by its document id (idDocumento). The response carries the JDPI-computed revision (revisao). operationId: updateDynamicCompositeQRCode parameters: - description: The recurrence/charge document id (idDocumento, GUID). in: path name: id required: true schema: description: The recurrence/charge document id (idDocumento, GUID). examples: - 52c43361-caa1-4ddb-9152-708426a25db4 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/UpdateDynamicCompositeBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/CompositeUpdateResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Update an immediate dynamic composite PIX Automatico QR code tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/update-an-immediate-dynamic-composite-pix-automatico-qr-code /v1/pix-automatico/composite/recurrence: post: description: Generates a composite PIX QR code carrying ONLY a recurring-payment authorization (PIX Automatico), with no static or dynamic QR data. The recipient city is CRM-sourced from the account. operationId: createRecurrenceCompositeQRCode requestBody: content: application/json: schema: $ref: "#/components/schemas/RecurrenceCompositeBody" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/CompositeResponse" description: Created "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Create a recurrence-only composite PIX Automatico QR code tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/create-a-recurrence-only-composite-pix-automatico-qr-code /v1/pix-automatico/composite/recurrence/{id}: put: description: Updates a previously generated recurrence-only composite PIX QR code, keyed by its document id (idDocumento), carrying the recurrence status transition (stRecorrencia). operationId: updateRecurrenceCompositeQRCode parameters: - description: The recurrence/charge document id (idDocumento, GUID). in: path name: id required: true schema: description: The recurrence/charge document id (idDocumento, GUID). examples: - 52c43361-caa1-4ddb-9152-708426a25db3 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/UpdateRecurrenceCompositeBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/CompositeUpdateResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Update a recurrence-only composite PIX Automatico QR code tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/update-a-recurrence-only-composite-pix-automatico-qr-code /v1/pix-automatico/composite/static: post: description: Generates a composite PIX QR code embedding static-QR data and a recurring-payment authorization (PIX Automatico). The recipient name and city are CRM-sourced from the account, never the request body. operationId: createStaticCompositeQRCode requestBody: content: application/json: schema: $ref: "#/components/schemas/StaticCompositeBody" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/CompositeResponse" description: Created "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Create a static composite PIX Automatico QR code tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/create-a-static-composite-pix-automatico-qr-code /v1/pix-automatico/events/authorization-cancellation-registered: post: description: "Receives the JDPI notifica-cancelamento-autorizacao-callback push event (section 6, body section 5.2.5): an async re-delivery of the cancellation registration. It reuses the inbound 5.2.5 register use case (Aceito cancels + soft-deletes; Rejeitado is ack-only). Idempotent: a re-delivery on an already-cancelled row is a no-op. No response body." operationId: pixAutomaticoEventAuthorizationCancellationRegistered parameters: - description: Bearer access token (the financial-ingress gate; the handler fails closed with PIX-0082 when absent). in: header name: Authorization schema: description: Bearer access token (the financial-ingress gate; the handler fails closed with PIX-0082 when absent). examples: - Bearer eyJ... type: string - description: "Event registration instant (UTC: aaaa-mm-ddTHH:mm:ss.sssZ). Mandatory per §6.1." in: header name: X-DataHoraEvento required: true schema: description: "Event registration instant (UTC: aaaa-mm-ddTHH:mm:ss.sssZ). Mandatory per §6.1." examples: - "2024-06-05T10:10:05.025Z" type: string - description: Event name (see §6.3.1 catalog). Mandatory per §6.1; informational passthrough. in: header name: X-NomeEvento required: true schema: description: Event name (see §6.3.1 catalog). Mandatory per §6.1; informational passthrough. examples: - situacao-autorizacao-callback type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/RegisterCancellationBody" required: true responses: "204": description: No Content "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Receive a PIX Automatico authorization cancellation registration event tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/receive-a-pix-automatico-authorization-cancellation-registration-event /v1/pix-automatico/events/authorization-cancellation-status: post: description: "Receives the JDPI situacao-cancelamento-autorizacao-callback push event (section 6, body section 4.3.6): the plugin is the server. The pushed stCancelamento Aceito/Rejeitado outcome is projected onto the local authorization. Idempotent: a duplicate re-delivery is a clean 200 no-op. No response body." operationId: pixAutomaticoEventAuthorizationCancellationStatus parameters: - description: Bearer access token (the financial-ingress gate; the handler fails closed with PIX-0082 when absent). in: header name: Authorization schema: description: Bearer access token (the financial-ingress gate; the handler fails closed with PIX-0082 when absent). examples: - Bearer eyJ... type: string - description: "Event registration instant (UTC: aaaa-mm-ddTHH:mm:ss.sssZ). Mandatory per §6.1." in: header name: X-DataHoraEvento required: true schema: description: "Event registration instant (UTC: aaaa-mm-ddTHH:mm:ss.sssZ). Mandatory per §6.1." examples: - "2024-06-05T10:10:05.025Z" type: string - description: Event name (see §6.3.1 catalog). Mandatory per §6.1; informational passthrough. in: header name: X-NomeEvento required: true schema: description: Event name (see §6.3.1 catalog). Mandatory per §6.1; informational passthrough. examples: - situacao-autorizacao-callback type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AuthorizationCancellationSituacaoBody" required: true responses: "204": description: No Content "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Receive a PIX Automatico authorization cancellation status event tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/receive-a-pix-automatico-authorization-cancellation-status-event /v1/pix-automatico/events/authorization-payer-registered: post: description: "Receives the JDPI notifica-autorizacao-pagador-callback push event (section 6, body section 5.2.3): an async re-delivery of the payer-side solicitation registration. It reuses the inbound 5.2.3 register use case (payer-side genesis). Idempotent: a re-delivered solicitation resolves to a 409 conflict, never a 500. No response body." operationId: pixAutomaticoEventAuthorizationPayerRegistered parameters: - description: Bearer access token (the financial-ingress gate; the handler fails closed with PIX-0082 when absent). in: header name: Authorization schema: description: Bearer access token (the financial-ingress gate; the handler fails closed with PIX-0082 when absent). examples: - Bearer eyJ... type: string - description: "Event registration instant (UTC: aaaa-mm-ddTHH:mm:ss.sssZ). Mandatory per §6.1." in: header name: X-DataHoraEvento required: true schema: description: "Event registration instant (UTC: aaaa-mm-ddTHH:mm:ss.sssZ). Mandatory per §6.1." examples: - "2024-06-05T10:10:05.025Z" type: string - description: Event name (see §6.3.1 catalog). Mandatory per §6.1; informational passthrough. in: header name: X-NomeEvento required: true schema: description: Event name (see §6.3.1 catalog). Mandatory per §6.1; informational passthrough. examples: - situacao-autorizacao-callback type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/RegisterRequestBody" required: true responses: "204": description: No Content "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Receive a PIX Automatico payer-side authorization registration event tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/receive-a-pix-automatico-payer-side-authorization-registration-event /v1/pix-automatico/events/authorization-recipient-registered: post: description: "Receives the JDPI notifica-autorizacao-recebedor-callback push event (section 6, body section 5.2.4): an async re-delivery of the recipient-side authorization registration. It reuses the inbound 5.2.4 register use case (load + transition to Accepted/Rejected). Idempotent: a re-delivery converging on the same status is a no-op. No response body." operationId: pixAutomaticoEventAuthorizationRecipientRegistered parameters: - description: Bearer access token (the financial-ingress gate; the handler fails closed with PIX-0082 when absent). in: header name: Authorization schema: description: Bearer access token (the financial-ingress gate; the handler fails closed with PIX-0082 when absent). examples: - Bearer eyJ... type: string - description: "Event registration instant (UTC: aaaa-mm-ddTHH:mm:ss.sssZ). Mandatory per §6.1." in: header name: X-DataHoraEvento required: true schema: description: "Event registration instant (UTC: aaaa-mm-ddTHH:mm:ss.sssZ). Mandatory per §6.1." examples: - "2024-06-05T10:10:05.025Z" type: string - description: Event name (see §6.3.1 catalog). Mandatory per §6.1; informational passthrough. in: header name: X-NomeEvento required: true schema: description: Event name (see §6.3.1 catalog). Mandatory per §6.1; informational passthrough. examples: - situacao-autorizacao-callback type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/RegisterAuthorizationBody" required: true responses: "204": description: No Content "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Receive a PIX Automatico recipient-side authorization registration event tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/receive-a-pix-automatico-recipient-side-authorization-registration-event /v1/pix-automatico/events/authorization-status: post: description: "Receives the JDPI situacao-autorizacao-callback push event (section 6, body section 4.3.4): the plugin is the server. The pushed stJdPiProc/stJdPi situation is projected onto the local authorization keyed on idRecorrencia. Idempotent: a duplicate re-delivery is a clean 200 no-op. No response body." operationId: pixAutomaticoEventAuthorizationStatus parameters: - description: Bearer access token (the financial-ingress gate; the handler fails closed with PIX-0082 when absent). in: header name: Authorization schema: description: Bearer access token (the financial-ingress gate; the handler fails closed with PIX-0082 when absent). examples: - Bearer eyJ... type: string - description: "Event registration instant (UTC: aaaa-mm-ddTHH:mm:ss.sssZ). Mandatory per §6.1." in: header name: X-DataHoraEvento required: true schema: description: "Event registration instant (UTC: aaaa-mm-ddTHH:mm:ss.sssZ). Mandatory per §6.1." examples: - "2024-06-05T10:10:05.025Z" type: string - description: Event name (see §6.3.1 catalog). Mandatory per §6.1; informational passthrough. in: header name: X-NomeEvento required: true schema: description: Event name (see §6.3.1 catalog). Mandatory per §6.1; informational passthrough. examples: - situacao-autorizacao-callback type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AuthorizationSituacaoBody" required: true responses: "204": description: No Content "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Receive a PIX Automatico authorization status event tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/receive-a-pix-automatico-authorization-status-event /v1/pix-automatico/events/schedule-cancellation-registered: post: description: "Receives the JDPI notifica-cancelamento-agendamento-callback push event (section 6, body section 5.3.4): an async re-delivery of the schedule cancellation registration. It reuses the inbound 5.3.4 register use case (Aceito cancels + soft-deletes; Rejeitado is ack-only). Idempotent: a re-delivery on an already-cancelled row is a no-op. No response body." operationId: pixAutomaticoEventScheduleCancellationRegistered parameters: - description: Bearer access token (the financial-ingress gate; the handler fails closed with PIX-0082 when absent). in: header name: Authorization schema: description: Bearer access token (the financial-ingress gate; the handler fails closed with PIX-0082 when absent). examples: - Bearer eyJ... type: string - description: "Event registration instant (UTC: aaaa-mm-ddTHH:mm:ss.sssZ). Mandatory per §6.1." in: header name: X-DataHoraEvento required: true schema: description: "Event registration instant (UTC: aaaa-mm-ddTHH:mm:ss.sssZ). Mandatory per §6.1." examples: - "2024-06-05T10:10:05.025Z" type: string - description: Event name (see §6.3.1 catalog). Mandatory per §6.1; informational passthrough. in: header name: X-NomeEvento required: true schema: description: Event name (see §6.3.1 catalog). Mandatory per §6.1; informational passthrough. examples: - situacao-autorizacao-callback type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/RegisterScheduleCancellationBody" required: true responses: "204": description: No Content "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Receive a PIX Automatico schedule cancellation registration event tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/receive-a-pix-automatico-schedule-cancellation-registration-event /v1/pix-automatico/events/schedule-cancellation-status: post: description: "Receives the JDPI situacao-cancelamento-agendamento-callback push event (section 6, body section 4.4.4): the plugin is the server. The pushed stCancelamento Aceito/Rejeitado outcome is projected onto the local schedule. Idempotent: a duplicate re-delivery is a clean 200 no-op. No response body." operationId: pixAutomaticoEventScheduleCancellationStatus parameters: - description: Bearer access token (the financial-ingress gate; the handler fails closed with PIX-0082 when absent). in: header name: Authorization schema: description: Bearer access token (the financial-ingress gate; the handler fails closed with PIX-0082 when absent). examples: - Bearer eyJ... type: string - description: "Event registration instant (UTC: aaaa-mm-ddTHH:mm:ss.sssZ). Mandatory per §6.1." in: header name: X-DataHoraEvento required: true schema: description: "Event registration instant (UTC: aaaa-mm-ddTHH:mm:ss.sssZ). Mandatory per §6.1." examples: - "2024-06-05T10:10:05.025Z" type: string - description: Event name (see §6.3.1 catalog). Mandatory per §6.1; informational passthrough. in: header name: X-NomeEvento required: true schema: description: Event name (see §6.3.1 catalog). Mandatory per §6.1; informational passthrough. examples: - situacao-autorizacao-callback type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ScheduleCancellationSituacaoBody" required: true responses: "204": description: No Content "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Receive a PIX Automatico schedule cancellation status event tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/receive-a-pix-automatico-schedule-cancellation-status-event /v1/pix-automatico/events/schedule-registered: post: description: "Receives the JDPI notifica-agendamento-pagador-callback push event (section 6, body section 5.3.3): an async re-delivery of the payer-side schedule registration. It reuses the inbound 5.3.3 register use case (inbound genesis). Idempotent: a re-delivered instruction resolves to a 409 conflict, never a 500. No response body." operationId: pixAutomaticoEventScheduleRegistered parameters: - description: Bearer access token (the financial-ingress gate; the handler fails closed with PIX-0082 when absent). in: header name: Authorization schema: description: Bearer access token (the financial-ingress gate; the handler fails closed with PIX-0082 when absent). examples: - Bearer eyJ... type: string - description: "Event registration instant (UTC: aaaa-mm-ddTHH:mm:ss.sssZ). Mandatory per §6.1." in: header name: X-DataHoraEvento required: true schema: description: "Event registration instant (UTC: aaaa-mm-ddTHH:mm:ss.sssZ). Mandatory per §6.1." examples: - "2024-06-05T10:10:05.025Z" type: string - description: Event name (see §6.3.1 catalog). Mandatory per §6.1; informational passthrough. in: header name: X-NomeEvento required: true schema: description: Event name (see §6.3.1 catalog). Mandatory per §6.1; informational passthrough. examples: - situacao-autorizacao-callback type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/RegisterScheduleBody" required: true responses: "204": description: No Content "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Receive a PIX Automatico schedule registration event tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/receive-a-pix-automatico-schedule-registration-event /v1/pix-automatico/events/schedule-status: post: description: "Receives the JDPI situacao-agendamento-callback push event (section 6, body section 4.4.2): the plugin is the server. The pushed stJdPiProc/stJdPi situation is projected onto the local schedule keyed on endToEndId. Idempotent: a duplicate re-delivery is a clean 200 no-op. No response body." operationId: pixAutomaticoEventScheduleStatus parameters: - description: Bearer access token (the financial-ingress gate; the handler fails closed with PIX-0082 when absent). in: header name: Authorization schema: description: Bearer access token (the financial-ingress gate; the handler fails closed with PIX-0082 when absent). examples: - Bearer eyJ... type: string - description: "Event registration instant (UTC: aaaa-mm-ddTHH:mm:ss.sssZ). Mandatory per §6.1." in: header name: X-DataHoraEvento required: true schema: description: "Event registration instant (UTC: aaaa-mm-ddTHH:mm:ss.sssZ). Mandatory per §6.1." examples: - "2024-06-05T10:10:05.025Z" type: string - description: Event name (see §6.3.1 catalog). Mandatory per §6.1; informational passthrough. in: header name: X-NomeEvento required: true schema: description: Event name (see §6.3.1 catalog). Mandatory per §6.1; informational passthrough. examples: - situacao-autorizacao-callback type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ScheduleSituacaoBody" required: true responses: "204": description: No Content "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Receive a PIX Automatico schedule status event tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/receive-a-pix-automatico-schedule-status-event /v1/pix-automatico/schedules: post: description: Requests the send of a recurring-payment instruction (agendamento) as the PSP Recebedor (JDPI 4.4.1). Persists the schedule in the Requested state and returns the JDPI acknowledgement. operationId: requestPixAutomaticoSchedule requestBody: content: application/json: schema: $ref: "#/components/schemas/RequestScheduleBody" required: true responses: "202": content: application/json: schema: $ref: "#/components/schemas/RequestScheduleResponse" description: Accepted "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Request a PIX Automatico schedule send tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/request-a-pix-automatico-schedule-send /v1/pix-automatico/schedules/inbound/cancellation/register: post: description: Registers a schedule cancellation outcome delivered by JDPI (section 5.3.4, the plugin is the server). An accepted cancellation (stCancelamento=0) transitions the schedule to Cancelled and soft-deletes the row; a rejected cancellation (stCancelamento=1) is acknowledged with no state change. Returns the local SGCT id. operationId: registerInboundPixAutomaticoScheduleCancellation requestBody: content: application/json: schema: $ref: "#/components/schemas/RegisterScheduleCancellationBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/RegisterScheduleCancellationResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Register an inbound PIX Automatico schedule cancellation tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/register-an-inbound-pix-automatico-schedule-cancellation /v1/pix-automatico/schedules/inbound/cancellation/validate: post: description: Validates an inbound schedule cancellation request (camt.055) pushed by JDPI (section 5.3.2, the plugin is the server). The cancellation is valid iff a live schedule exists and the FSM permits a transition to Cancelled from its current status; the result is returned inline (200). operationId: validateInboundPixAutomaticoScheduleCancellation requestBody: content: application/json: schema: $ref: "#/components/schemas/ValidateScheduleCancellationBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ValidateScheduleCancellationResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Validate an inbound PIX Automatico schedule cancellation tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/validate-an-inbound-pix-automatico-schedule-cancellation /v1/pix-automatico/schedules/inbound/register: post: description: "Registers an inbound scheduled payment instruction delivered by JDPI to the PSP Pagador (section 5.3.3, the plugin is the server). This is inbound genesis: it creates the payer-side schedule row (Requested on an accepted registration, Rejected on a rejected one) and returns the local SGCT id. A re-delivered instruction resolves to a 409 conflict." operationId: registerInboundPixAutomaticoSchedule requestBody: content: application/json: schema: $ref: "#/components/schemas/RegisterScheduleBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/RegisterScheduleResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Register an inbound PIX Automatico payment instruction tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/register-an-inbound-pix-automatico-payment-instruction /v1/pix-automatico/schedules/inbound/validate: post: description: Validates an inbound scheduled payment instruction (pain.013) pushed by JDPI (section 5.3.1, the plugin is the server). The SGCT validates the charge data against the previously-confirmed authorization; the result is returned inline (200) as a Valido=1/Invalido=0 outcome, never an HTTP error. operationId: validateInboundPixAutomaticoSchedule requestBody: content: application/json: schema: $ref: "#/components/schemas/ValidateScheduleBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ValidateScheduleResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Validate an inbound PIX Automatico payment instruction tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/validate-an-inbound-pix-automatico-payment-instruction /v1/pix-automatico/schedules/list: get: description: Lists live JDPI scheduled payment instructions (JDPI 4.4.5), scoped by flow + due-date window, projecting each onto the local schedule status. The response is an object wrapper carrying the JDPI timestamp and the schedule snapshots. operationId: listPixAutomaticoSchedules parameters: - description: fluxo (0=Enviados/PSP Recebedor, 1=Recebidos/PSP Pagador). explode: false in: query name: flow required: true schema: description: fluxo (0=Enviados/PSP Recebedor, 1=Recebidos/PSP Pagador). examples: - 0 format: int64 type: integer - description: cnpjRecebedor filter (string). explode: false in: query name: recipientCnpj schema: description: cnpjRecebedor filter (string). examples: - "61695227000193" type: string - description: tpPessoaPagador filter (0/1; empty = no filter). explode: false in: query name: payerPersonType schema: description: tpPessoaPagador filter (0/1; empty = no filter). examples: - "0" type: string - description: cpfCnpjPagador filter (string). explode: false in: query name: payerDocument schema: description: cpfCnpjPagador filter (string). examples: - "04623217035" type: string - description: nrAgenciaPagador filter (string). explode: false in: query name: payerAgency schema: description: nrAgenciaPagador filter (string). examples: - "0001" type: string - description: nrContaPagador filter (string). explode: false in: query name: payerAccount schema: description: nrContaPagador filter (string). examples: - "0007654321" type: string - description: stAgendamento filter (0/1; empty = no filter). explode: false in: query name: scheduleStatus schema: description: stAgendamento filter (0/1; empty = no filter). examples: - "0" type: string - description: dtVencimentoInicio (aaaa-mm-dd). explode: false in: query name: dueDateFrom required: true schema: description: dtVencimentoInicio (aaaa-mm-dd). examples: - "2024-09-01" type: string - description: dtVencimentoFim (aaaa-mm-dd). explode: false in: query name: dueDateTo required: true schema: description: dtVencimentoFim (aaaa-mm-dd). examples: - "2024-09-30" type: string - description: pagina (default 1). explode: false in: query name: page schema: description: pagina (default 1). examples: - 1 format: int64 type: integer - description: tamanhoPagina (default 50, max 100). explode: false in: query name: pageSize schema: description: tamanhoPagina (default 50, max 100). examples: - 50 format: int64 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/ListSchedulesResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: List PIX Automatico schedules tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/list-pix-automatico-schedules /v1/pix-automatico/schedules/{endToEndId}: get: description: Consults the live JDPI situation of a scheduled payment instruction (JDPI 4.4.2), projecting the JDPI situation axes onto the local schedule status. operationId: getPixAutomaticoSchedule parameters: - description: The payment-transaction id (32-char). in: path name: endToEndId required: true schema: description: The payment-transaction id (32-char). examples: - E00038166202409171500y6j6mt9l0pi type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ScheduleResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Consult a PIX Automatico schedule situation tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/consult-a-pix-automatico-schedule-situation /v1/pix-automatico/schedules/{endToEndId}/cancel: post: description: Cancels a scheduled payment instruction (JDPI 4.4.3), transitioning it to Cancelled and soft-deleting the local row. Returns the cancellation id (idCancelamento). operationId: cancelPixAutomaticoSchedule parameters: - description: The payment-transaction id (32-char). in: path name: endToEndId required: true schema: description: The payment-transaction id (32-char). examples: - E00038166202409171500y6j6mt9l0pi type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CancelScheduleBody" required: true responses: "202": content: application/json: schema: $ref: "#/components/schemas/CancelScheduleResponse" description: Accepted "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Cancel a PIX Automatico schedule tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/cancel-a-pix-automatico-schedule /v1/pix-automatico/schedules/{endToEndId}/cancel/{idCancelamento}: get: description: Consults the live JDPI situation of a schedule cancellation (JDPI 4.4.4), keyed by (endToEndId, idCancelamento). operationId: getPixAutomaticoScheduleCancellation parameters: - description: The payment-transaction id (32-char). in: path name: endToEndId required: true schema: description: The payment-transaction id (32-char). examples: - E00038166202409171500y6j6mt9l0pi type: string - description: The cancellation id (29-char, CA...). in: path name: idCancelamento required: true schema: description: The cancellation id (29-char, CA...). examples: - CA0435879820240605abcd1234567 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ScheduleCancellationResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Consult a PIX Automatico schedule cancellation tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/consult-a-pix-automatico-schedule-cancellation /v1/pix-automatico/settlements/inbound/block: post: description: "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." operationId: blockInboundPixAutomaticoSettlement parameters: - description: Bearer access token (the financial-ingress gate; the handler fails closed with PIX-0082 when absent). in: header name: Authorization schema: description: Bearer access token (the financial-ingress gate; the handler fails closed with PIX-0082 when absent). examples: - Bearer eyJ... type: string - description: Idempotency key (= the endToEndId of the transaction). Mandatory per section 5.4. in: header name: Chave-Idempotencia required: true schema: description: Idempotency key (= the endToEndId of the transaction). Mandatory per section 5.4. examples: - E11111111202409181500y6j6mt9l1pi type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/BlockScheduleBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/BlockScheduleResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Reserve an inbound PIX Automatico debit hold tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/reserve-an-inbound-pix-automatico-debit-hold /v1/pix-automatico/settlements/inbound/debit: post: description: Posts the real double-entry settlement debit on the payer's local ledger for a scheduled PIX Automatico payment (section 5.4.2, the plugin is the SGCT server). JDPI calls this after it confirms SPI settlement. The amount was established at schedule/block time, so the body carries no value. Returns the SGCT debit-operation id (idOperacaoSgct). A re-delivery resolves to a clean 200 with the prior confirmation, never a double post. operationId: debitInboundPixAutomaticoSettlement parameters: - description: Bearer access token (the financial-ingress gate; the handler fails closed with PIX-0082 when absent). in: header name: Authorization schema: description: Bearer access token (the financial-ingress gate; the handler fails closed with PIX-0082 when absent). examples: - Bearer eyJ... type: string - description: Idempotency key (= the endToEndId of the transaction). Mandatory per section 5.4. in: header name: Chave-Idempotencia required: true schema: description: Idempotency key (= the endToEndId of the transaction). Mandatory per section 5.4. examples: - E11111111202409181500y6j6mt9l1pi type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/DebitScheduleBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/DebitScheduleResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Effect an inbound PIX Automatico settlement debit tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/effect-an-inbound-pix-automatico-settlement-debit /v1/pix-automatico/settlements/inbound/debit/{endToEndId}: delete: description: Reverses the prior settlement debit (or releases a still-pending hold) on a negative SPI return (section 5.4.3, the plugin is the SGCT server). The reverse is parameterizable and disabled by default. Returns the SGCT reversal-operation id (idOperacaoSgct). operationId: reverseInboundPixAutomaticoSettlement parameters: - description: Bearer access token (the financial-ingress gate; the handler fails closed with PIX-0082 when absent). in: header name: Authorization schema: description: Bearer access token (the financial-ingress gate; the handler fails closed with PIX-0082 when absent). examples: - Bearer eyJ... type: string - description: Idempotency key (= the endToEndId of the transaction). Mandatory per section 5.4. in: header name: Chave-Idempotencia required: true schema: description: Idempotency key (= the endToEndId of the transaction). Mandatory per section 5.4. examples: - E11111111202409181500y6j6mt9l1pi type: string - description: Unique payment-instruction id (32-char), the natural key. in: path name: endToEndId required: true schema: description: Unique payment-instruction id (32-char), the natural key. examples: - E11111111202409181500y6j6mt9l1pi type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ReverseDebitBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ReverseDebitResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Reverse an inbound PIX Automatico settlement debit tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/reverse-an-inbound-pix-automatico-settlement-debit /v1/qrcodes/decode: post: description: Decodes a scanned PIX QR-code payload, normalizing static / immediate-dynamic / cobv sub-types into one null-safe response. The payer document is sourced from the CRM alias for the JDPI decode header. operationId: decodeQRCode requestBody: content: application/json: schema: $ref: "#/components/schemas/DecodeQRBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/DecodeQRResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Decode a scanned PIX QR code tags: - QR Codes x-mint: href: /en/reference/interfaces/pix-jd/decode-qr-code /v1/qrcodes/decode/url: post: description: Decodes a dynamic PIX QR code by the payee-published JWS payload URL (JDPI §8.3.10), normalizing static / immediate-dynamic / cobv sub-types into one null-safe response. Unlike the scan decode it takes a urlPayloadJson the JDPI fetches; the payer document is sourced from the CRM alias for the JDPI decode header. operationId: decodeQRCodeByURL requestBody: content: application/json: schema: $ref: "#/components/schemas/DecodeURLQRBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/DecodeQRResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Decode a PIX QR code via its payload URL tags: - QR Codes x-mint: href: /en/reference/interfaces/pix-jd/decode-a-pix-qr-code-via-its-payload-url /v1/qrcodes/dynamic: post: description: |- Generates an immediate dynamic PIX QR code and persists its conciliation metadata. The plugin sends the JWS host URLs (urlPayloadJson / urlJwk) to JDPI and self-hosts the signed JWS, so the returned QR is end-to-end resolvable; the response carries the resolvable payload URL the EMV embeds. cobv (due-date) and saque/troco variants are not supported. WHAT indirectId DECIDES HERE IS WHO SERVES THE QR, and it is a decision about hosting rather than about whose charge it is. This participant may serve INDIRECT participants — institutions registered with POST /v1/indirects. Most of them need nothing here: by default a QR raised for one of them is signed with THIS participant's certificate and its payload is hosted on THIS participant's domain, which is the ordinary arrangement and the one nearly every institution wants. An institution that has opted into holding its OWN certificate is the exception, and only for it does indirectId change anything: JDPI then signs with that institution's certificate, the payload URL is built on that institution's own domain, and the signed document comes back to you to host there. Certificate and domain are ONE decision, never two — the payer's app validates the signature against the certificate published at the domain that answered, so signing with one party's certificate while hosting on another's does not validate. ⚠️ indirectId IS SILENTLY IGNORED WHILE THIS TENANT'S INDIRECT-PARTICIPANTS FEATURE IS SWITCHED OFF: the value is not parsed, not resolved and not refused, and the QR is signed and hosted by the direct participant as if you had sent none. Nothing in the response says the routing was dropped. Naming an id and getting 404 PIX-0095 back is the evidence the feature is on. Refusals specific to indirectId — every one of them PRESUPPOSES the feature is on, since with it off the value is not even parsed — all decided before JDPI is called, so a refused QR is never generated: 404 PIX-0095 for an id that addresses no institution registered in this tenant (a malformed UUID lands here too — it can address none); 422 PIX-0100 when the institution it names is not ACTIVE; 422 PIX-0113 when that institution's registered public base URL names a host a payer's app cannot resolve; 422 PIX-0112 when the composed payload URL exceeds the 77 characters BACEN allows — the path this participant is configured with spends most of that budget, so an institution's hostname must be chosen against the remaining allowance BEFORE it is registered, not after. When indirectId names an indirect that hosts its OWN certificate, the signed JWS comes back in payloadJws and the plugin does NOT store it — the indirect hosts it at payloadUrl on its own infrastructure, so THIS RESPONSE IS THE ONLY DELIVERY OF IT. If the response never reaches you (client timeout, connection reset, proxy error) the charge nevertheless exists at JDPI, and re-sending the same recipientConciliationId is refused as a duplicate (PIX-0065). Recover it, do not re-create it: call GET /v1/qrcodes/list with qrCodeType 12 over the registration window, match your own recipientConciliationId to read its documentId, then call PUT /v1/qrcodes/dynamic/{documentId} with the SAME indirectId — the update re-signs the charge and returns a fresh payloadJws (JDPI §8.3.5 returns payloadJws on every update). The update mints a NEW payloadUrl and a regenerated EMV payload, so it REPLACES the lost QR rather than reproducing it; host the new payloadJws at the new payloadUrl and distribute the new qrCode. Hosting the payload is not the whole obligation: an institution serving its own domain must ALSO publish, at that domain, the key set the payer's app validates the signature against. It cannot produce that key set itself — JDPI holds the certificate and does the signing — so read it with GET /v1/indirects/{indirectId}/jwks and serve those bytes verbatim, re-reading whenever the certificate is rotated. A payload served without a matching key set fails validation at the payer, silently: the QR scans, the app fetches the document, and the payment does not go through. operationId: createDynamicQRCode requestBody: content: application/json: schema: $ref: "#/components/schemas/DynamicQRBody" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/QRCodeResponse" description: Created "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Create an immediate dynamic PIX QR code tags: - QR Codes x-mint: href: /en/reference/interfaces/pix-jd/create-dynamic-qr-code /v1/qrcodes/dynamic/{documentId}: put: description: |- Updates an existing immediate dynamic PIX QR code (JDPI §8.3.5): the charge amount, conciliation, expiration, optional payer, and the charge status (0=Active, 1=Concluded, 2=Removed by recipient, 3=Removed by PSP). The recipient name + city are CRM-sourced (never the body). The plugin re-hosts the updated signed JWS so the QR stays end-to-end resolvable; the response carries the JDPI revision and the resolvable payload URL. It is also the RECOVERY path for an indirect-hosted payloadJws whose create response never reached the caller: the update re-signs the charge under whichever certificate the request names and returns the fresh payloadJws, so supply the SAME indirectId the charge was created with (omitting it re-signs under the DIRECT participant and moves the location onto the direct FQDN). Every update — recovery or not — mints a new payloadUrl and a regenerated EMV payload, so the previously advertised location is superseded. THE PLUGIN STORES NO INDIRECT ASSOCIATION FOR A CHARGE, so this request's indirectId — not the create's — decides who signs and where the location points, on every update. Omitting it on a charge created for an institution that hosts its own certificate is not a no-op: it MOVES the charge onto the direct participant's certificate and domain, and the institution's own domain stops serving the current location. The same rules as on create apply here, and they apply in this order: while this tenant's indirect-participants feature is off the value is silently ignored, so NONE of the refusals below can occur and the update simply re-signs under the direct participant. With the feature on, the value is validated and refused with 404 PIX-0095 (unknown or malformed id), 422 PIX-0100 (not ACTIVE), 422 PIX-0113 (registered host a payer's app cannot resolve) or 422 PIX-0112 (composed payload URL over the 77-character BACEN cap) — all before JDPI is called, so a refused update changes nothing. operationId: updateDynamicQRCode parameters: - description: The existing charge GUID to update (JDPI idDocumento). in: path name: documentId required: true schema: description: The existing charge GUID to update (JDPI idDocumento). examples: - 52c43361-caa1-4ddb-9152-708426a25db3 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/UpdateDynamicQRBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/UpdateDynamicQRResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Update an immediate dynamic PIX QR code tags: - QR Codes x-mint: href: /en/reference/interfaces/pix-jd/update-an-immediate-dynamic-pix-qr-code /v1/qrcodes/list: get: description: Lists the PIX QR codes the PSP created (JDPI §8.3.12), filtered by type and a registration window (≤90 days). Returns the static and immediate-dynamic blocks; composite / cobv / recurrence QR codes are out of this context's scope and not projected. operationId: listQRCodes parameters: - description: tpQRCode filter (11=static, 12=immediate dynamic, 13=cobv, 14=recurrence, 15-17=composite). Omit to list every type. explode: false in: query name: qrCodeType schema: description: tpQRCode filter (11=static, 12=immediate dynamic, 13=cobv, 14=recurrence, 15-17=composite). Omit to list every type. examples: - 12 format: int64 type: integer - description: Window start (dtHrInicial; aaaa-mm-ddTHH:mm:ss.sssZ). explode: false in: query name: startDateTime schema: description: Window start (dtHrInicial; aaaa-mm-ddTHH:mm:ss.sssZ). examples: - "2024-10-01T00:00:00.001Z" type: string - description: Window end (dtHrFinal; aaaa-mm-ddTHH:mm:ss.sssZ; ≤90d from start). explode: false in: query name: endDateTime schema: description: Window end (dtHrFinal; aaaa-mm-ddTHH:mm:ss.sssZ; ≤90d from start). examples: - "2024-11-25T23:59:59.999Z" type: string - description: Page number (pagina; default 1). explode: false in: query name: page schema: description: Page number (pagina; default 1). examples: - 1 format: int64 type: integer - description: Page size (tamanhoPagina; default 50, max 100). explode: false in: query name: pageSize schema: description: Page size (tamanhoPagina; default 50, max 100). examples: - 100 format: int64 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/ListQRResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: List the PSP's PIX QR codes tags: - QR Codes x-mint: href: /en/reference/interfaces/pix-jd/list-the-psp-s-pix-qr-codes /v1/qrcodes/static: post: description: Generates a static PIX QR code into the recipient's key. The recipient name and city are sourced from the CRM alias, never the request body. An amount of 0 produces an any-amount static QR. operationId: createStaticQRCode requestBody: content: application/json: schema: $ref: "#/components/schemas/StaticQRBody" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/QRCodeResponse" description: Created "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Create a static PIX QR code tags: - QR Codes x-mint: href: /en/reference/interfaces/pix-jd/create-static-qr-code /v1/refunds: post: description: |- Creates a PIX refund (devolução) against an executed transaction. Bacen makes the refund the RECIPIENT's operation, so the caller must be the party that RECEIVED the original payment: the requesting accountId's document has to equal the original payee's document. The original payer cannot refund a payment it sent — that is the MED/fraud path, not this one. Identify the original with BOTH transactionId (the local UUID) and endToEndId, and it must still be EXECUTED. Partial refunds are allowed and they ACCUMULATE: the amount is checked against the original amount minus everything already refunded, under a row lock on the original, so two concurrent refunds cannot together exceed it. An on-us original is refunded as a synchronous ledger reversal from the refunder to the original payer; a payment received from another institution is submitted to JDPI first, and the refund's own end-to-end id comes back from JD. code is the return reason and is accepted only as BE08, FR01, MD06 or SL02. ⚠️ Send clientRequestId on an on-us refund. Without it a retry posts a SECOND reversal: each attempt mints a fresh refund end-to-end id, so nothing dedups them, and the money moves twice. With it, a retry replays the existing refund as a success. The cross-institution branch is already retry-safe on its own. Refusals: 422 PIX-0036 when no EXECUTED transaction matches that (endToEndId, transactionId) pair; 400 PIX-0089 when the original is an outgoing payment (only the receiving institution can return what it received); 400 PIX-0087 when the caller is refunding its own outgoing payment; 400 PIX-0088 when the caller is not the original payee; 409 PIX-0032 when this amount plus the prior refunds would exceed the original; 422 PIX-0030 on a non-positive amount; 422 PIX-0108 when the requesting account is not bound to a ledger account; 400 PIX-0061 when accountId or endToEndId is empty, transactionId is not a UUID, or code is outside the four accepted values. operationId: createRefund requestBody: content: application/json: schema: $ref: "#/components/schemas/RefundBody" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/RefundResponse" description: Created "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Create a PIX refund tags: - Refunds x-mint: href: /en/reference/interfaces/pix-jd/create-refund /v1/refunds/reasons: get: description: |- Returns the PIX refund (devolução) reason catalog from JDPI, as code + description pairs. Fetch it before offering a refund choice to a user, rather than hard-coding a list: the catalog is JD's, not this plugin's, and it can change with no release here. Read-only, unfiltered, unpaginated, and not persisted or cached — every call reaches JDPI, so load it once per session rather than once per refund. It changes nothing. ⚠️ The catalog is JD's full list, but createRefund accepts only BE08, FR01, MD06 and SL02: a code from this response outside those four is refused with 400 PIX-0061 before the refund is attempted. There are no request-attributable refusals here (there is no request to get wrong); a failure is JDPI's and is reported as such — 503 PIX-1050 when JDPI is unavailable. operationId: getRefundReasons responses: "200": content: application/json: schema: $ref: "#/components/schemas/ReturnReasonsBody" description: OK "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: List PIX refund reasons tags: - Refunds x-mint: href: /en/reference/interfaces/pix-jd/list-refund-reasons /v1/transactions: get: description: |- Lists the transactions this plugin has persisted, most recent first. Use it to reconcile your own records against the plugin's, or to find the local transaction id of an order you know only by its end-to-end id. Read-only. Every filter is optional and they combine with AND: account_id (the CRM account id), end_to_end_id, status (the eTransactionStatus NAME, e.g. EXECUTED), and is_refund. is_refund is tri-state and parsed leniently — only "true" and "false" filter, and ANY other value (including "1" or "yes") leaves the filter unset rather than erroring, so a typo there silently widens the result set. There is no pagination and no page size: the response is the whole matching set in one array, so filter narrowly on a busy account. Amounts are integer centavos. An unknown account_id or end_to_end_id is not an error — it matches nothing and returns an empty array, so absence here means "nothing persisted under that value", never "the value is wrong". The only refusal is 400 PIX-0061 for a status that is not a known eTransactionStatus name. THIS FEED INCLUDES MOVEMENTS THAT BELONG TO INDIRECT PARTICIPANTS, and nothing here separates them. When this participant serves indirect participants (institutions registered with POST /v1/indirects), their credits and payments are persisted as ordinary transactions and come back mixed in with the direct participant's own. There is no filter on the institution — for one of them, `account_id` is its `@pi_{ispb}` settlement alias rather than a CRM account id, which is the practical way to isolate it here, and GET /v1/indirects/{indirectId}/transactions is the purpose-built feed (it is windowed, cursor-paged and ordered for reconciliation, which this one is not). operationId: getTransactions parameters: - description: Filter by the CRM account id. explode: false in: query name: account_id schema: description: Filter by the CRM account id. examples: - acc-123 type: string - description: Filter by the SPI end-to-end id. explode: false in: query name: end_to_end_id schema: description: Filter by the SPI end-to-end id. examples: - E1234567890 type: string - description: Filter by eTransactionStatus name. explode: false in: query name: status schema: description: Filter by eTransactionStatus name. examples: - EXECUTED type: string - description: Filter by refund flag ('true'/'false'). explode: false in: query name: is_refund schema: description: Filter by refund flag ('true'/'false'). examples: - "false" type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/TransactionListBody" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: List PIX transactions tags: - Transactions x-mint: href: /en/reference/interfaces/pix-jd/list-transactions post: description: |- Creates an outbound PIX payment. What happens next depends on where the payee is, and the two branches answer with different statuses and different bodies — a client has to handle both. An on-us payee (payee.ispb equal to this participant's own ISPB, on a direct order) settles SYNCHRONOUSLY as an INTRA_PSP ledger transfer and answers 201 with the transaction already EXECUTED. Any other payee settles over SPI in TWO PHASES: the amount is first HELD on the paying position as a pending ledger debit, and only then is the order submitted to JDPI (§8.4.1), which is asynchronous by design — nothing has settled when the call returns. A direct order answers 201 with the transaction PENDING; an order routed through a registered indirect (indirectId in the body) answers 202 carrying JD's own §8.4.1 acknowledgement byte-for-byte, whose idReqJdPi is the handle the outcome is read with. Either way, poll GET /v1/transactions/{transactionId}: a background reconciler consults JDPI §8.4.2 and then commits or cancels the hold, and the money is not settled until the status says so. WHAT indirectId ACTUALLY MOVES, because it is more than a label. This participant may serve INDIRECT participants — other institutions registered here with POST /v1/indirects that reach SPI through this participant's ISPB. Naming one on an order changes THREE things at once: the amount is held on that institution's `@pi_{ispb}` settlement position instead of on the payer's own, the persisted order is stamped with that institution so it appears in GET /v1/indirects/{indirectId}/transactions, and the response shape changes from 201-plus-plugin-body to 202-plus-JD-body. The identifier is ROUTING DATA, not a credential: this participant authenticates you, and guaranteeing that the order really belongs to that institution is your responsibility, not this API's. ⚠️ indirectId IS SILENTLY IGNORED WHILE THIS TENANT'S INDIRECT-PARTICIPANTS FEATURE IS SWITCHED OFF. With the feature off the value is not parsed, not resolved and not refused: the order runs as a DIRECT one, holding the amount on the direct participant's own position and answering 201. Nothing in the response says the routing was dropped. Confirm the feature is on before sending the first order for an institution — an unknown id answering 404 PIX-0095 is the evidence that it is. When the order reaches its outcome, an indirect order may ALSO push a NOTICE to the endpoint that registration carries (delivery.endpointUrl), queued by the background reconciler once JD's terminal outcome is known — an HTTPS POST forwarding JD's own result body verbatim, carrying X-Lerian-Signature ('sha256=' followed by the hex HMAC-SHA256 of the exact body bytes under the registration's shared secret) and X-Lerian-Timestamp. **Do not build on the notice arriving.** No notice is queued at all when this deployment has no outbound queue configured, and none is queued when the outcome carries no JD result body to forward — an order cancelled locally, without a JD answer, is exactly that case. Delivery of a notice that WAS queued is AT-LEAST-ONCE and can still fail permanently while the payment stands. So the institution must dedup on the end-to-end id and treat GET /v1/indirects/{indirectId}/transactions, not the notice, as the record of truth: it is the only place an outcome whose notice was never queued becomes visible. A direct order pushes no notice at all. End-to-end ids: send endToEndId only when you already hold one (from a key lookup or a QR decode), and then payee.key is mandatory with it. Omit it on a manually typed order and SPI mints one — the response carries the minted value. Idempotency: the optional clientRequestId is the only identifier that exists BEFORE the JD call, so it is what makes a retry safe on every branch, and it is the ONLY protection a manually typed order has (that order's end-to-end id does not exist yet when the retry arrives). Amounts are integer centavos. Every refusal below is decided before the hold is taken, so it moves ZERO money; when JDPI rejects the order after the hold exists, the hold is released and nothing is persisted. Refusals: 409 PIX-0029 when this endToEndId or clientRequestId was already used; 409 PIX-0076 when the paying position lacks the amount; 409 PIX-0078 on a transfer to the same account; 409 PIX-0032 when the account's period limit is exceeded; 422 PIX-0030 on a non-positive amount; 422 PIX-0037 when endToEndId arrives without payee.key; 422 PIX-0108 when the payer — or, on an indirect order, the indirect's `@pi` — resolves in the CRM but is not bound to a ledger account; 404 PIX-0095 for an unknown or malformed indirectId and 422 PIX-0100 when the indirect it names is not ACTIVE; 422 PIX-0102 when a payer.ispb is supplied on an indirect order and disagrees with that indirect's own ISPB; 400 PIX-0061 when accountId is empty or an accountType is outside the PIX domain 0..4. On an indirect order a JD business rejection is passed back with JD's own status and body instead of a problem+json. operationId: createTransaction requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateTransactionBody" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/CreateTransactionResponse" description: Created "202": content: application/json: schema: $ref: "#/components/schemas/CreateTransactionAcceptedResponse" description: "Accepted for asynchronous settlement. Returned on the arrangement (indirect-participant) path, where the body is JD's own §8.4.1 acknowledgement passed through verbatim. Nothing has settled: the amount is reserved on the ordering participant's position and the outcome is obtained by polling JDPI §8.4.2 with the returned idReqJdPi." "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Create a PIX transaction tags: - Transactions x-mint: href: /en/reference/interfaces/pix-jd/create-transaction /v1/transactions/{transactionId}: get: description: |- Resolves one transaction's status. This is the operation that closes the loop after a payment: an outbound SPI order answers 201 or 202 with nothing settled, and the verdict arrives here. The path id is resolved in three steps, in order: by JDPI request id (idReqJdPi), then — only when the value parses as a UUID — by local transaction id, and finally, when neither matched, by a LIVE lookup at JDPI (§8.4.2). Those branches do not answer the same thing. A local hit returns the status the reconciler last persisted; a live hit is a projection of JD's own processing status, is the only branch that populates jdpiStatus, and projects JD status 9 to EXECUTED. So a transaction this plugin never persisted can still answer 200 here, and a status read live is not evidence that a local row exists. Read-only: it neither commits nor releases the held amount — the background reconciler does that on its own tick, so a PENDING answer means "not decided yet", not "stuck". Refusals: 400 PIX-0061 when transactionId is empty; and on the live branch, JDPI's own outcome — 404 PIX-1027 when JD does not know the id either, 503 PIX-1050 when JDPI is unreachable — so a failure here names the dependency instead of hiding behind a generic error. operationId: getTransactionStatus parameters: - description: The transaction id (local UUID or JDPI request id). in: path name: transactionId required: true schema: description: The transaction id (local UUID or JDPI request id). examples: - d1f9c0a2-... type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/TransactionStatusResponse" description: OK "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Get a PIX transaction status tags: - Transactions x-mint: href: /en/reference/interfaces/pix-jd/retrieve-transaction-status /v1/webhooks/cash-ins: post: description: |- Registers an inbound PIX credit that JDPI has settled to this participant (JDPI section 9.3.2). JDPI calls it once per received credit, after settlement; it is idempotent on the end-to-end id (the mandatory Chave-Idempotencia header), so a redelivery of a credit already registered answers 409 PIX-0029 rather than posting the credit twice. On success the credit is posted to the receiving customer's account and the response carries the three section 9.3.2 members: idReqJdPi, idCreditoSgct (the identifier of the credit entry this participant recorded) and dtHrCreditoSgct (when it was recorded). That response is an assertion that the money was booked; there is no field in it for a refusal. NOT EVERY CREDIT LANDS ON A CUSTOMER ACCOUNT. This participant may also serve INDIRECT participants — other institutions that reach SPI through this participant's ISPB and are registered here with POST /v1/indirects. When recebedor.ispb names one of them and its registration is ACTIVE, the credit is posted to THAT institution's `@pi_{ispb}` settlement position instead of to a customer account. The destination is read from the registry row, never from the payload, and the recorded credit is stamped with the institution it belongs to. The 200 body is identical in both cases, so the response does not tell you which destination was used; that institution's own movements are read with GET /v1/indirects/{indirectId}/transactions. An indirect credit also queues a NOTICE to the endpoint that registration carries (delivery.endpointUrl): one HTTPS POST forwarding this webhook's JD body verbatim, carrying X-Lerian-Signature ('sha256=' followed by the hex HMAC-SHA256 of the exact body bytes under the registration's shared secret) and X-Lerian-Timestamp (the send time in Unix seconds, not covered by the signature). THE CREDIT IS NOT CONDITIONAL ON THE NOTICE, AND THE NOTICE IS NOT GUARANTEED BY THE CREDIT. When a notice is queued it rides the same database transaction as the credit, so a queued notice always belongs to money that was booked. The reverse does not hold: a credit posts and is answered 200 with NO notice queued at all when this deployment has no outbound queue configured, or when the verbatim JD body could not be retained for forwarding (retention is best-effort — it is skipped for an empty body and abandoned on a write failure, and the credit proceeds either way, because the money is not held hostage to the forwarding). Delivery of a notice that WAS queued is AT-LEAST-ONCE and independent of this 200: the same notice can arrive more than once, and it can also fail permanently while the money stays booked. So a receiving institution must dedup on endToEndId, and must treat GET /v1/indirects/{indirectId}/transactions — not the notice — as the record of truth. Reconciling from that feed is not a fallback for a failed notice; it is the only way to see a movement whose notice was never queued. Three ordering rules decide the destination and cannot be inferred from the payload: - A pagador.ispb identifying Bacen (99999) short-circuits FIRST, ahead of any indirect matching, so it never reaches a settlement position either. - A recebedor.ispb equal to this participant's OWN ISPB is always resolved against this participant's own customer records, never against the indirect registry. - While this tenant's indirect-participants feature is switched OFF, recebedor.ispb is not read against the registry at all: every credit is resolved ONLY against this participant's own customer records, exactly as before indirect participants existed. Two things follow, and the second is the dangerous one. PIX-0119 becomes unreachable, because nothing consults the registry to find the receiver unserved. And a credit addressed to a registered institution is normally answered 404 PIX-0115, because no customer here holds that account number — but it is NOT refused on the account number alone. Should a local customer hold the same recebedor.nrConta AND the same recebedor.cpfCnpj, the credit is POSTED TO THAT CUSTOMER and answered 200, with the institution's `@pi_{ispb}` never involved; a number that collides under a different holder is refused 409 PIX-0117 instead. Sending recebedor.nrAgencia narrows that further — it is optional in section 9.3.2, and this participant adds it to the account lookup only when you send one, so a credit that omits it is matched on the account number alone. Register the institution AND enable the feature before pointing any credit at it. A credit that CANNOT be registered is therefore answered with an HTTP error, never with a 200. Each carries a distinct code in the problem body's `code` member: - 404 PIX-0115 - the receiving account named by the credit was not found here. Check recebedor.nrAgencia/recebedor.nrConta, or recebedor.cpfCnpj when no account coordinates are sent. - 404 PIX-0119 - recebedor.ispb is neither this participant's own ISPB nor an ACTIVE indirect participant registered in this tenant. It covers both a receiver with no registration at all and one whose registration is not ACTIVE (suspended, closed, or a legacy row that never finished being set up); the two are deliberately not distinguished on the wire, because neither is something the sender can act on differently. It presupposes the indirect-participants feature is ON — with it off nothing consults the registry and this code cannot be answered at all. - 409 PIX-0116 - recebedor.cpfCnpj names more than one account here, so the destination is undeterminable. Address the credit to specific account coordinates. - 409 PIX-0117 - the account addressed by recebedor.nrAgencia/recebedor.nrConta belongs to a different holder than recebedor.cpfCnpj names. - 409 PIX-0118 - the addressed account exists here but is not set up to receive credits. - 409 PIX-0029 - this end-to-end id was already registered as a credit here. The redelivery posted nothing; the original credit stands. - 500 PIX-0120 - a provisioning fault at this participant, not a problem with the request. The credit is safe to redeliver once it is corrected. WHICH OF THOSE AN INDIRECT CREDIT CAN ACTUALLY HIT is a shorter list, because its destination comes from the registry rather than from a customer lookup — and the whole list below presupposes the indirect-participants feature is ON, since with it off there is no indirect path to be on. PIX-0119 is the one: it is what a receiver ISPB with no ACTIVE registration answers, and it exists only on this path. PIX-0115, PIX-0116, PIX-0117, PIX-0118 and PIX-0120 are all decided by the own-customer lookup and are unreachable once recebedor.ispb resolves to an ACTIVE registration — so seeing any of them means the credit was NOT treated as an indirect one. PIX-0029 behaves identically on both paths. A registry read that fails is a 500 like any other dependency failure: nothing is registered, and the credit is safe to redeliver. One outcome acknowledges 200 WITHOUT posting a credit: a pagador.ispb identifying Bacen (99999), which this participant nulls by design. Its response carries the acknowledgement echo (idReqSistemaCliente, idReqJdPi, endToEndIdOriginal, endToEndIdDevolucao) and no idCreditoSgct. Malformed payloads are rejected with 400 at the edge, before any resolution runs: 400 PIX-0061 for a body that fails schema validation, and 400 PIX-0061 for a missing endToEndId, a valor that is not a positive finite amount, or a malformed CPF/CNPJ or ISPB on either participant block. operationId: createWebhookCashIn parameters: - description: Idempotency key (= the endToEndId of the transaction). Mandatory per section 9.3.2. in: header name: Chave-Idempotencia required: true schema: description: Idempotency key (= the endToEndId of the transaction). Mandatory per section 9.3.2. examples: - E0435879820200123221500000000001 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CashInBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/CashInResponse" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error summary: Process an inbound JDPI cash-in tags: - Webhooks x-mint: href: /en/reference/interfaces/pix-jd/process-an-inbound-upstream-cash-in /v1/webhooks/refunds: post: description: |- Registers a PIX devolução that the PAYEE's bank initiated and JDPI has already executed (JDPI section 9.3.3). This participant does not initiate it and does not decide it: JDPI pushes it once the return has settled, and this call records the money coming back. It is idempotent on endToEndIdDevolucao, so a redelivery answers 409 PIX-0029 and credits nothing twice. On success the returned amount is credited back to the account that funded the ORIGINAL payment, and the response carries the section 9.3.3 acknowledgement: idReqJdPi, idCreditoSgct (the identifier of the entry this participant recorded) and dtHrCreditoSgct. The original payment is located by endToEndIdOriginal; the payer's identity and destination are read from the record written when that payment was created, never re-resolved, so a devolução always returns to where the money left from. ONE SUCCESS SHAPE IS NOT A COMPLETED CREDIT, and it is the case an integrator must plan for. When the original payment is still PENDING here (its SPI outcome has not been reconciled yet), the devolução is ACCEPTED AND OWNED rather than credited: it is recorded as awaiting the original's settlement, the acknowledgement is the same 200 shape with idCreditoSgct naming that record, and a background sweep completes the credit once the original settles. So a 200 asserts this participant has taken responsibility for the devolução, not that the money has already moved. WHEN THE ORIGINAL PAYMENT BELONGED TO AN INDIRECT PARTICIPANT, the devolução follows it. This participant may serve indirect participants — other institutions registered here with POST /v1/indirects that reach SPI through this participant's ISPB. A payment originated for one of them was debited from its `@pi_{ispb}` settlement position, so the return credits that same position and the recorded devolução is stamped with the same institution as the original. Nothing in the section 9.3.3 payload says so — the linkage comes entirely from the original payment's record — and the 200 body is identical either way. An indirect-linked devolução also queues a NOTICE to that registration's delivery.endpointUrl: one HTTPS POST forwarding this webhook's JD body verbatim, carrying X-Lerian-Signature ('sha256=' followed by the hex HMAC-SHA256 of the exact body bytes under the registration's shared secret) and X-Lerian-Timestamp. It is queued on the same conditions the cash-in notice is, and with the same asymmetry: a queued notice rides the devolução's own database transaction, but a devolução can be credited and answered 200 with NO notice queued — when this deployment has no outbound queue configured, or when the verbatim JD body could not be retained for forwarding. Delivery of a queued notice is AT-LEAST-ONCE and independent of this 200: it can repeat, and it can fail permanently while the money stays booked. The institution must dedup on endToEndIdDevolucao and read GET /v1/indirects/{indirectId}/transactions as the record of truth — which is also the only place a devolução whose notice was never queued becomes visible. A devolução that CANNOT be registered is answered with an HTTP error carrying a distinct code in the problem body's `code` member: - 404 PIX-0063 - no original payment with this endToEndIdOriginal exists here. This participant never made that payment, so there is nothing to return. - 409 PIX-0029 - this endToEndIdDevolucao was already registered. The redelivery credited nothing; the original devolução stands. - 409 PIX-0032 - the returned amounts for this payment would exceed what was originally paid. The cap is cumulative across every devolução already booked against that payment, and it is evaluated under a lock, so two devoluções arriving at once cannot both pass it. - 422 PIX-0030 - the devolução amount is not greater than zero. - 400 PIX-0061 - the body failed schema validation at the edge, before any lookup ran. None of those are specific to an indirect participant: an indirect-linked devolução is refused for exactly the same reasons as a direct one, because the linkage is read from the original payment rather than resolved from this request. operationId: createWebhookReversal requestBody: content: application/json: schema: $ref: "#/components/schemas/ExternalRefundBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ExternalRefundResponse" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error summary: Process a payee-bank-initiated PIX devolução tags: - Webhooks x-mint: href: /en/reference/interfaces/pix-jd/process-a-payee-bank-initiated-pix-devolu-o /v1/webhooks/validates: post: 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 summary: Validate a receiving account synchronously tags: - Webhooks x-mint: href: /en/reference/interfaces/pix-jd/validate-a-receiving-account-synchronously security: - BearerAuth: [] tags: - description: |- The SPI participant catalog (JDPI §8.6.1), read live from JDPI on every call with nothing cached — latency and availability here are JDPI's, and an unreachable JDPI answers 503 PIX-1050. Two projections of the same catalog: GET /v1/banks is the reduced (ispb, legal name) pair a payment form needs; GET /v1/banks/participants is the full record with participation type, modality and status. Keep ispb a STRING — it is 8 characters and its leading zeros are significant. This is the NATIONAL directory, not this deployment's own registry: a participant classified as indirect here (participantType=2) has no relation to the indirect participants registered with POST /v1/indirects, and neither list implies membership in the other. name: Banks - description: |- DICT key claims (reivindicação): the BACEN process for taking over a PIX key that is currently registered at another PSP — portability of your own key, or an ownership claim on a key someone else holds. A claim is a negotiation between two PSPs mediated by the DICT, and this surface exposes both sides of it: open a claim (POST /v1/claims), list and inspect the ones this participant is involved in, confirm (the donor side acknowledging), conclude (the claimer side completing the transfer), and cancel. Claims move no money — they move DIRECTORY state, and several steps are irreversible once the DICT records them: a concluded claim has already re-pointed the key at the claiming account. Each operation's description states which side of the claim calls it and in which claim status it is legal; a step attempted out of order is refused with a coded 4xx rather than forwarded to the DICT. name: Claims - description: |- DICT key entries (vínculo): registering, updating, listing and removing the PIX keys — CPF/CNPJ, phone, email or random key (EVP) — that bind an addressable alias to one of this participant's accounts in the BACEN directory. The surface also carries the verification call (a batch existence check against the DICT) and the two bulk-removal flows, account closure (POST /v1/account-closures) and holder removal (POST /v1/holder-removals), which drop every key bound to a coordinate at once. The rule integrators trip on: the DICT locates keys by the FULL account coordinate — ISPB, branch, account number AND account type (tpConta) — so a lookup or removal that names the wrong account type finds nothing, silently: the answer is an empty 200, indistinguishable from an account that genuinely holds no keys. Registration is idempotent at JDPI through a deterministic idempotency projection, so a transport retry of the same request does not double-register a key. name: Entries - description: |- **What this domain is.** This participant is a DIRECT PIX participant, and it can serve INDIRECT participants: other institutions that reach SPI and the DICT through this participant's ISPB. This surface is the registry of those institutions — registering one, suspending, reactivating and closing it, reading the key set its QR codes are signed with, and reading the reconciliation feed of every movement that rode its settlement position. **The credential model, because it decides how you integrate.** An indirect participant NEVER holds a credential for this API. Every call is authenticated as the direct participant, and the indirect's id on an order or a registration row is ROUTING DATA: it decides which settlement position the money moves on, and the guarantee that a request really belongs to that institution is the direct participant's responsibility, made before the request is sent — this API does not re-validate it. **Where the money moves.** Registering an institution creates a dedicated ledger settlement position for it (its `@pi_{ispb}` account), atomically with the registry row. From then on: an outbound order carrying its indirectId is HELD on that position (the debit source always comes from the registry, never from the caller's body), an inbound credit whose receiver ISPB matches it is credited to that position, and the response to an indirect order is JD's own acknowledgement passed through verbatim (202). The feed at GET /v1/indirects/{indirectId}/transactions is the record of truth for all of it: windowed (the `since` bound is required), cursor-paged, oldest first, amounts in integer centavos. **Lifecycle.** ACTIVE ⇄ SUSPENDED → CLOSED. PATCH carries at most ONE lifecycle action per request (suspend, reactivate or close) alongside ordinary field updates. Suspending flips the settlement position's send/receive flags before the registry row changes, so the ledger backstops the registry rather than trailing it. CLOSED is terminal and requires the settlement position to hold ZERO balance (409 PIX-0096); the position is blocked, never deleted, and re-registering the same ISPB later reuses it. Repeating the current state is refused 409 PIX-0094 — deliberately not a no-op, so a double-fired automation is visible. One ISPB maps to at most one non-CLOSED registration (409 PIX-0093). **Delivery notices.** When an indirect's registration carries a delivery endpoint, the plugin can push JD's own payload BYTE-FOR-BYTE to it as an HTTPS POST carrying X-Lerian-Signature ('sha256=' + the hex HMAC-SHA256 of the exact body bytes under the registration's shared secret) and X-Lerian-Timestamp. Delivery is AT-LEAST-ONCE: the institution MUST dedup on the end-to-end id, and must treat the transactions feed — not the notice — as the record of truth, because a notice can fail permanently, or never be queued at all, while the payment stands. The shared secret is write-only: PATCH replaces it, and every read renders it masked. **The QR certificate option, which is commercial, not compliance.** By default a QR raised for an indirect is signed with the DIRECT participant's certificate and hosted on the direct's domain — the ordinary arrangement, and no registration step here is needed for an indirect to transact. An institution that opts into its OWN certificate registers it via PATCH `qrCertificate`: `ownCertificate: true` plus a scheme-less, publicly resolvable `publicBaseUrl` (with the shipped path defaults the base URL may spend at most 37 of BACEN's 77-character payload-URL budget — measure the hostname BEFORE promising it). The whole sub-object is gated on this tenant's indirect-participants feature (off = 422 PIX-0111), and it should be switched on only after the certificate is live on BACEN's list — before that, payments fail silently at the payer's app, which validates a signature nothing vouches for. The institution then hosts its own signed payloads AND the key set they validate against: read that key set with GET /v1/indirects/{indirectId}/jwks (an authenticated operator read; 422 PIX-0114 when the institution has no own certificate — the direct participant's public JWKS route serves that case) and serve the bytes verbatim. A SUSPENDED institution can still read its key set: QRs already in the wild still need validating. **Refusals to know.** 404 PIX-0095 unknown (or malformed) indirect id — an id belonging to another tenant is deliberately indistinguishable from an unknown one; 422 PIX-0100 the institution is not ACTIVE; 422 PIX-0102 a payer ISPB on an indirect order disagrees with the institution's own; 409 PIX-0093/0094/0096 the lifecycle rules above; 422 PIX-0111/0112/0113/0114 the QR-certificate rules above; 404 PIX-0119 an inbound credit for a receiver this participant does not serve. name: Indirects - description: |- Per-account PIX transaction limits, enforced on OUTBOUND money only. Four limit rows exist per account — transaction and period, each in a daily and a nightly band — and the day/night boundary comes from this institution's policy (whole hours, default 06:00–20:00 UTC as the daily window), not from the request. A fresh account legitimately answers GET /v1/limits with an empty list and GET /v1/limits/available with 404: the rows are seeded with defaults by the account's FIRST outbound transaction, not at account creation. An account with no rows is therefore NOT unlimited — the enforcer seeds and then enforces, failing closed if a limit cannot be established. PATCH /v1/limits is update-only: it adjusts a row that exists, and naming a (type, period) tuple that has no row yet is refused 422 PIX-0036. A payment over the applicable limit is refused 409 PIX-0032 before any money moves. name: Limits - description: |- MED 2.0 fraud markers (marcação de fraude): the DICT records this participant creates against a person or key involved in fraud, feeding BACEN's shared fraud database. Create a marker (POST /v1/med/fraud-markers), cancel one you created, list the local working set, inspect one, and query the DICT's own view (GET /v1/med/fraud-markers/dict). Markers move no money and have a two-party lifecycle: created here, acknowledged/consolidated at the DICT. The write operations take a client `idempotencyKey`; it is projected to a deterministic GUID before reaching JDPI (see the API description's idempotency section), so a retry with the same key lands in the same JDPI dedup slot. name: MED Fraud Markers - description: |- The MED refund CREDIT leg (JDPI §9.3.3): the webhook JDPI calls on this participant when a special-return devolution settles in this participant's favor — money coming BACK after a MED refund request this participant (or its customer) won. It is called by JDPI, not by your systems; the operation is documented so you can recognize the flow and its ledger effect, and so the counterparty configuration names the right path. This is a MONEY route: a valid credit posts to the recipient customer's ledger account before the acknowledgement is returned. Direction is guarded — the credit is accepted only when the payload's recipient ISPB is this participant's own — and the amount arrives as a JSON number in REAIS (JD's contract on bodies JD authors), converted at the boundary; this mirror shape is the exception to the API-wide integer-centavos rule. A replayed delivery of an already-settled credit is acknowledged idempotently rather than posted twice. name: MED Inbound Credit - description: |- MED 2.0 infraction reports (relato de infração): the notifications that open BACEN's special return mechanism on a transaction — typically fraud reported by the payer's PSP against a payment this participant received. Inbound reports addressed to this participant are collected from JDPI by a background poller and land in the local working set automatically; this surface is where you SEE them (list, inspect, read JDPI's own view) and ACT on them (analyze — agree or disagree — and cancel one this participant created). Infractions move no money themselves; they are the predicate for MED Refunds, where the money leg lives. Analysis is subject to a BACEN SLA measured from the report's creation, and the write operations take a client `idempotencyKey` that is projected to a deterministic GUID before reaching JDPI. name: MED Infractions - description: |- MED 2.0 value recoveries (recuperação de valores): the creator-side flow this participant runs when its own customer was defrauded and the money went to another PSP — open a recovery (POST /v1/med/recoveries), amend it while the counterparty analysis allows, and, once the counterparty approves, execute the devolution step (devolver) within the 72-hour window that approval arms. GET /v1/med/recoveries/awaiting-devolver is the operator worklist of recoveries whose clock is running. The recovery API at JDPI has no pending-list poll, so open recoveries are re-synced by a background poller — local state can trail the counterparty by one poll interval. The devolver step is the money-bearing action of the flow; everything else is negotiation state. Write operations take a client `idempotencyKey`, projected to a deterministic GUID before reaching JDPI. name: MED Recoveries - description: |- MED 2.0 refund requests (solicitação de devolução): the special-return money flow itself. This participant appears in BOTH roles — as SOLICITANTE it opens a refund request against another PSP (POST /v1/med/refunds); as CONTESTADO it receives requests (collected from JDPI by a background poller — GET /v1/med/refunds/pending-analysis is the analysis worklist), analyzes them within the BACEN SLA, and, when it accepts, EFFECTUATES the devolution: POST /v1/med/refunds/{idSolDevolucao}/effectuate debits the customer who received the original payment and submits the pacs.004 over SPI. Effectuation is the money leg, and it is two-phase: the debit is HELD as a pending ledger posting when the effectuate call is accepted, and a background settlement reconciler commits it when SPI settles (or releases it on a terminal SPI error) — so an accepted effectuate is not yet settled money, and the row's state says which side of that line it is on. Direction is guarded on the participant's own ISPB: only the CONTESTADO (the PSP whose customer RECEIVED the original payment) can effectuate, refused 400 PIX-0088 otherwise, and the mirror credit of a refund this participant WON arrives on the MED Inbound Credit webhook. GET /v1/med/refunds/credits/{endToEndIdDevolucao} reads that credit's landing. Client `idempotencyKey` values on every write are projected to a deterministic GUID before reaching JDPI — correlate JDPI-side logs with the projection, not the raw value you sent. name: MED Refunds - description: |- PIX Automático: BACEN's recurring-payment arrangement, where a payer authorizes a merchant's PSP to pull scheduled payments. This surface carries the whole arrangement from this participant's seat: recurring authorizations (recorrência — create, confirm, respond, adjust the max value, cancel), the payment schedules under them (agendamento — create, list, cancel), the composite QR codes that carry a charge and a recurrence in one artifact (static, dynamic, cobv and recurrence-only, with their updates and decode), the `/inbound` registration and validation endpoints JDPI calls on this participant per annexes §5.2/§5.3, the §5.4 settlement legs (block, debit, and the compensating estorno via DELETE), and the §6 event-stream ingress (`/events/*`) through which JDPI pushes lifecycle status. Which party calls each route matters more here than anywhere else in the API: `/inbound/*`, `/events/*` and `/settlements/*` are called BY JDPI on this participant, while the rest are called by your systems. The §5.4 settlement legs move money — the debit posts against the paying customer, the estorno compensates it — and both are idempotent per end-to-end id with the estorno namespaced separately, so the two legs of one scheduled payment can never collide. Amounts on this participant's own operations are integer centavos; the inbound JDPI mirrors carry reais as JSON numbers, per the API-wide two-unit rule. name: PIX Automatico - description: |- **What this domain does.** Creates, updates, decodes and lists this participant's PIX QR codes: STATIC (a reusable key-and-optional-amount code) and IMMEDIATE DYNAMIC (a single-use charge whose payload is a signed JWS document fetched by the payer's PSP at pay time). Due-date charges (cobv), withdrawal and change (saque/troco) variants are RECOGNIZED by the decode operations but not created here; recurring composites live under PIX Automatico. **Who signs, who hosts — the part that decides your architecture.** JDPI holds the certificate and signs every dynamic payload; this plugin composes the URLs the QR carries, and by default it also STORES and SERVES the signed JWS on its own public routes, so the QR that comes back is end-to-end resolvable with no work on your side. The exception is a charge raised for an indirect participant that holds its OWN certificate: the signed JWS comes back in the create/update response and is NOT stored — that response is the ONLY delivery, and the indirect hosts the document (and the matching key set, read via GET /v1/indirects/{id}/jwks) on its own domain. If that response is lost, the charge nevertheless exists at JDPI: recover it via GET /v1/qrcodes/list (match your recipientConciliationId) and PUT /v1/qrcodes/dynamic/{documentId}, which re-signs and returns a fresh payloadJws rather than reproducing the lost one. **The dynamic-QR lifecycle.** Create validates everything BEFORE calling JDPI — the recipient's name and city come from this participant's CRM records, never from the body; the payload URL is composed first because JDPI requires it in the request; the conciliation id must be new (409 PIX-0065) — so a refused create never leaves a charge behind, and a JDPI failure after persistence is compensated by deleting the local row. Update (JDPI §8.3.5) changes the amount, conciliation, expiration, payer or charge status (0=Active, 1=Concluded, 2=Removed by recipient, 3=Removed by PSP), and REUSES the location: a printed QR keeps resolving, because the updated JWS atomically supersedes the old one at the same path id. The plugin stores no charge↔indirect association, so EACH update's indirectId decides who signs that revision — omitting it on an indirect-hosted charge moves the charge onto the direct participant's certificate and domain. **The 77-character budget.** BACEN caps the payload URL (urlPayloadJson) at 77 characters, scheme-less, and the path this deployment is configured with spends most of it. An over-budget URL is refused by ATTRIBUTION: 422 PIX-0112 when an indirect's registered base URL is what does not fit (choose the hostname against the remaining allowance BEFORE registering it), 500 PIX-0053 when the deployment's own configuration leaves no room for any charge. **Decode and list.** Decode accepts the scanned EMV payload (POST /v1/qrcodes/decode) or the payload URL itself (POST /v1/qrcodes/decode/url), per §8.3.10. GET /v1/qrcodes/list (§8.3.12) requires a bounded registration window of at most 90 days; omitting the type fans the query out across every QR type. **Public payload & JWKS routes.** Four routes exist OUTSIDE this specification — they are anonymous, they are called by the PAYER'S PSP (never by you), and they are listed here because they are part of the deployment's public contract even though no operation below describes them. Their path prefixes (the payload path and the JWK path) and their host vary per deployment; the shapes are: - `GET /{payloadPath}/cob/{id}` (single-tenant form) and `GET /{payloadPath}/{ispb}/cob/{id}` (multi-tenant form, where the ISPB segment selects the serving participant) — the signed JWS payload of one dynamic charge, returned raw with Content-Type `application/jose`. The `cob` segment is LITERAL: only immediate charges are self-hosted, and a `cobv` fetch answers 404 rather than handing the payer's PSP a resource of a type it did not ask for. - `GET /{jwkPath}` (single-tenant) and `GET /{jwkPath}/{ispb}` (multi-tenant) — the JWK Set the payloads validate against, as `application/jwk-set+json`, served from a short-lived cache (minutes) over JDPI's key material. The 22-character `{id}` is a cryptographically random token minted per charge, and it is the route's only barrier: unguessable by construction, it acts as a capability — knowing the URL is what authorizes the fetch, which is exactly the EMV model, where the URL travels inside the QR. A missing, expired or unknown payload — and an unknown ISPB — answer a UNIFORM 404 with code PIX-0063, deliberately not distinguishing absent from expired: a payer PSP must not pay an expired QR, and nothing more is anyone else's business. Server-side faults (the participant lookup unavailable, JDPI unreachable with nothing cached) answer 503. Errors on these routes are RFC 9457 problem+json like everywhere else. name: QR Codes - description: |- Devolution (devolução) of a RECEIVED PIX payment — the BACEN rule is that refunds are PAYEE-initiated, and this surface encodes it: only the party that received the money can return it. A refund never mutates the original transaction; it is a NEW transaction row (is_refund=true) whose amount is capped at the original minus every prior refund of it (409 PIX-0032 over the cap). GET /v1/refunds/reasons is the catalog of accepted devolution reason codes. Refunding a payment this participant SENT is refused 400 PIX-0089 (ask the payee's PSP instead — or, for the special return mechanism, see MED Refunds), and a requester who is not the original payee is refused 400 PIX-0088. An on-us original settles the return synchronously in the ledger; an original that arrived over SPI is returned through JDPI first, and the ledger posting follows JD's acceptance. name: Refunds - description: |- **What this domain does.** Outbound PIX payments — over SPI to any other participant, or settled on this participant's own book when the payee is on-us — plus the read surface that closes the loop on them. The Refunds and Limits tags are part of the same flow: a devolution is a new transaction row, and limits are enforced here on the way out. **The lifecycle, and which flow settles when.** A transaction's status is PENDING (0), EXECUTED (2) or ERROR (-1), and the only real edge is PENDING → EXECUTED or ERROR. An on-us (INTRA_PSP) order settles SYNCHRONOUSLY: one final ledger posting, answered 201 already EXECUTED. An external CASH_OUT is the API's only TWO-PHASE money flow: the amount is HELD on the paying position as a pending ledger debit BEFORE JDPI is called; if JDPI refuses the order the hold is released immediately and nothing persists; if JDPI accepts (§8.4.1, asynchronous by design) the order persists PENDING, and a background reconciler polls JDPI (§8.4.2) on a short tick — settlement (JD processing status 9) commits the hold and flips the row EXECUTED, a terminal SPI error (-1) releases the hold and flips it ERROR. EXECUTED and ERROR are terminal. Inbound credits (CASH_IN) appear in this feed already EXECUTED — they settled when the webhook posted them. **What that means for a client.** A 201/202 on POST /v1/transactions is an ACCEPTED order, not settled money: poll GET /v1/transactions/{transactionId} until the status is terminal. PENDING means "SPI has not decided", never "stuck" — the reconciler acts on its own tick and the status read is side-effect-free. An indirect order (indirectId in the body) answers 202 with JD's own acknowledgement verbatim instead of the 201-plus-plugin-body of a direct order; handle both shapes. **Rules you cannot guess from the schemas.** (1) Amounts are integer centavos everywhere on this surface. (2) Send endToEndId only when you already hold one — from a key lookup or a QR decode — and then payee.key is mandatory with it (422 PIX-0037 otherwise); omit it on a manually typed order and SPI mints one, returned in the response. (3) The optional clientRequestId is the only identifier that exists BEFORE the JD call, so it is the ONLY retry protection a manually typed order has; reusing one (or an endToEndId) is refused 409 PIX-0029. (4) Every refusal is decided before the hold is taken, so a refused order moves ZERO money. (5) The list endpoint has NO pagination — the whole matching set arrives in one array, so filter narrowly; and on a CASH_IN row account_id records the ledger alias credited rather than a CRM account id, so correlate inbound rows by end_to_end_id. **Errors that matter.** 409 PIX-0029 duplicate endToEndId/clientRequestId; 409 PIX-0076 insufficient balance on the paying position; 409 PIX-0032 period limit exceeded; 409 PIX-0078 transfer to the same account; 422 PIX-0030 non-positive amount; 422 PIX-0033 the payee resolves to more than one account (on-us) — refused rather than guessed; 422 PIX-0108 a party resolves in the CRM but is bound to no ledger account; 404 PIX-0095 / 422 PIX-0100 unknown / not-ACTIVE indirect; 503 PIX-1050 JDPI unreachable (the dependency is named, and the order was not placed). name: Transactions - description: |- **What this domain is — and is not.** The INBOUND mirror of the JD integration: the three endpoints JDPI calls on THIS participant. It is not client webhook management — there is nothing to subscribe to here. The callers of these routes are JDPI's systems, authenticated with the same bearer scheme as everything else; they are documented so an integrator can recognize the flows, and so the counterparty configuration names the right paths. **The three flows.** POST /v1/webhooks/cash-ins is the §9.3.2 inbound credit: money received by this participant or by an indirect it serves. POST /v1/webhooks/refunds is the §9.3.3 payee-bank-initiated devolução of a payment this participant SENT: JD has already executed the return when this arrives. POST /v1/webhooks/validates is the §9.3.1 synchronous account validation: a read-only preflight the payer's PSP runs before sending money. **Money arrives in REAIS here.** These bodies are authored by JD, so their money fields are JSON numbers in reais (converted to integer centavos at the boundary) — the mirror exception to the API-wide centavos rule. Everything this API itself answers or persists is centavos. **Acknowledged is not credited.** The §9.3.2/§9.3.3 success acknowledgement carries the triad idReqJdPi / idCreditoSgct / dtHrCreditoSgct, and the field that says money landed is idCreditoSgct. The one 200 WITHOUT it is the short-circuit for a payer settled by BACEN itself (ISPB 99999), which acknowledges without crediting. Refusals are ordinary coded HTTP errors — this surface does not hide a refusal inside a 200. **How a cash-in resolves, in order.** BACEN payer → acknowledge without credit. Receiver on this participant's OWN ISPB → own-book credit, located by the ADDRESSED coordinates (branch + account number; the receiver document is cross-checked, not used to search — a divergence refuses rather than re-routes). Receiver ISPB matching an ACTIVE indirect participant → credit to that institution's settlement position, with the delivery notice recorded in the same unit of work. Anything else — an ISPB this participant does not serve — is REFUSED 404 PIX-0119; money is never parked or blindly posted. The credit is posted to the ledger BEFORE the acknowledgement is returned, and redelivery is deduplicated on endToEndId (409 PIX-0029 names a replay of a different payload; an identical replay of a settled credit is acknowledged idempotently). Other refusals name what failed to resolve: 404 PIX-0115 no account at the addressed coordinates, 409 PIX-0116 the coordinates resolve ambiguously, 409 PIX-0117 the addressed account belongs to a different holder than the payload names, 409 PIX-0118 the account cannot be credited. **The devolução leg holds a PARK.** A returned payment whose original is already EXECUTED credits the original payer immediately. One whose original is still PENDING (the outbound settlement race) is acknowledged 200 and PARKED durably — the acknowledgement's idCreditoSgct carries the park id — and a background sweep completes the credit once the original settles, or escalates it if the original ends in ERROR. **Validation always answers 200.** Every §9.3.1 outcome is a 200 whose body carries the verdict and reason: BE17 for a duplicate payment inside the 24h window or a payer mismatch on the referenced charge, AC03 for an account that does not resolve, BE01 for a document that diverges from the account's holder. An HTTP error from this route means infrastructure, never "account invalid". name: Webhooks