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: contactEmail: description: New creator-contact email. examples: - ops@example.com type: string contactPhone: description: New creator-contact phone. examples: - "+5511999999999" type: string details: description: New free-text detail; required when situationType=4 (Outros). examples: - Updated detail. type: string situationType: description: New situation code (0..5). examples: - 4 format: int64 type: integer required: - situationType type: object AnalyzeInfractionRequestBody: additionalProperties: false properties: analysisDetails: description: Analysis detail. examples: - Confirmed fraud. type: string analysisResult: description: Infraction analysis result (0=Aceita, 1=Rejeitada). examples: - 0 format: int64 type: integer tpFraude: description: Fraud-type code (0..4); required when analysisResult=0 (Aceita). examples: - 1 format: int64 type: integer required: - analysisResult type: object AnalyzeRefundRequestBody: additionalProperties: false properties: analysisDetails: description: Analysis detail; required when rejecting with rejectionReason=4. examples: - Confirmed fraud. type: string analysisResult: description: Analysis result (0=Aceita Totalmente, 1=Aceita Parcialmente, 2=Rejeitada). examples: - 0 format: int64 type: integer refundEndToEndId: description: pacs.004/008 refund id; required when analysisResult is 0 or 1. examples: - D1234567820240101000000000000099 type: string refundedAmount: description: Amount actually refunded, in centavos; required for a partial acceptance. examples: - 10000 format: int64 type: integer rejectionReason: description: Rejection reason (0,1,3,4); required when analysisResult=2. examples: - 0 format: int64 type: integer required: - analysisResult type: object AsyncValidationBody: additionalProperties: true properties: creditos: description: The credits to validate. items: $ref: "#/components/schemas/AsyncValidationCredit" maxItems: 500 minItems: 1 type: array tpCanal: description: Channel the payment came from (1 = CSM); not read. examples: - 1 format: int64 type: integer required: - creditos type: object AsyncValidationCredit: additionalProperties: true properties: creditoOrdemPagamento: $ref: "#/components/schemas/AsyncValidationOrder" description: The payment order's identifiers. pagador: $ref: "#/components/schemas/PayerBlock" description: The payer participant block. recebedor: $ref: "#/components/schemas/PayeeBlock" description: The receiver participant block; its account is the one validated. required: - pagador - recebedor - creditoOrdemPagamento type: object AsyncValidationOrder: additionalProperties: true properties: endToEndId: description: Payment end-to-end id. examples: - E0435879820200123221500000000002 maxLength: 32 minLength: 1 type: string idConciliacaoRecebedor: description: Recipient conciliation id (the QR charge it pays). examples: - REC00000000000000000000000000000001 type: string required: - endToEndId type: object AsyncValidationResponse: additionalProperties: false properties: dtHrAvisoSgct: description: When this participant received the call (aaaa-mm-ddTHH:mm:ss.sssZ, UTC). examples: - "2023-08-07T22:10:05.025Z" type: string idValidacaoSgct: description: Identifies this validation; every result registered for it carries it. examples: - 58F963C6-7487-4363-9406-A1DE1A8525D1 type: string required: - idValidacaoSgct - dtHrAvisoSgct type: object AuthorizationAckResponse: additionalProperties: false properties: idReqJdPi: description: The JDPI request id (36-char GUID; omitted by 4.3.10). examples: - 52c43361-caa1-4ddb-9152-708426a25db3 type: string recurrenceId: description: The recurrence id. examples: - RR0435879820240605njua7shf40o 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: - recurrenceId - requestedAt type: object AuthorizationCancellationItem: additionalProperties: false properties: cancelStatus: description: stCancelamento (0=Aceito, 1=Rejeitado). Absent when JDPI did not report it. examples: - 0 format: int64 type: integer cancellationId: description: The cancellation id (29-char, IC...). examples: - IC0435879820240605abcd1234567 type: string 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 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: - cancellationId - requesterType - requesterDocument - reason - cancelledAt 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 (string). examples: - "0007654321" pattern: \S patternDescription: non-blank type: string agency: description: Payer branch (nrAgencia, 4 digits, string). examples: - "0001" type: string cpfCnpj: description: Payer CPF or CNPJ (string). examples: - "04623217035" pattern: \S patternDescription: non-blank type: string ispb: description: Payer participant ISPB (8 digits, string). examples: - "00038166" pattern: ^[0-9]{8}$ 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 (0=Conta Corrente, 1=Conta Salario, 2=Conta Poupanca, 3=Conta de Pagamento). Absent when JDPI did not report it; 0 is Conta Corrente, never absence. 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 (0=Pessoa Fisica, 1=Pessoa Juridica). Always present, including 0. examples: - 0 format: int64 type: integer required: - personType type: object AuthorizationRecipientBody: additionalProperties: false properties: cnpj: description: Recipient CNPJ (14 characters, string). examples: - "61695227000193" pattern: \S patternDescription: non-blank type: string ispb: description: Recipient participant ISPB (8 digits, string). examples: - "04358798" pattern: ^[0-9]{8}$ type: string name: description: Recipient legal/trade name. examples: - Enel pattern: \S patternDescription: non-blank 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; absent when the debtor is the payer. 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 idReqJdPi: description: The JDPI request id (GUID). examples: - 52c43361-caa1-4ddb-9152-708426a25db3 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. recurrenceId: description: The recurrence id. examples: - RR0435879820240605njua7shf40o type: string requestId: description: The solicitation id (29-char, IS...). examples: - IS0435879820240605abcd1234567 type: string requestedAt: description: JDPI request timestamp (UTC). examples: - "2024-01-05T10:00:01Z" type: string retry: description: retentativa (0=no retries, 1=up to 3 retries). Always present, including 0. examples: - 1 format: int64 type: integer situationAt: description: Situation timestamp (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: - recurrenceId - stJdPiProc - stJdPi - localStatus - localStatusKnown - authorizationGiven - retry - frequency - startDate - recipient - payer 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. 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: cancellationId: description: The cancellation id (29-char, IC...). examples: - IC0435879820240605abcd1234567 type: string cancelledAt: description: Cancellation timestamp (dtHrCancelamento, UTC). examples: - "2024-02-01T10:00:00Z" type: string recurrenceId: description: The recurrence id. examples: - RR0435879820240605njua7shf40o type: string status: description: The resulting local authorization status. examples: - Cancelled type: string required: - recurrenceId - cancellationId - cancelledAt - status type: object CancelFraudMarkerRequestBody: additionalProperties: false properties: ispb: description: "The ISPB of the direct participant this operation acts as. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own JDPI credential - and this field is the only thing on the request that says which of them acts. OPTIONAL while it acts as a single participant: omit it and that one acts. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. It also selects the JDPI channel the call goes out on, so a MED write made under the wrong one reaches a JD that has never heard of this institution. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061." examples: - "12345678" pattern: ^[0-9]{8}$ type: string 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=payer's PSP, 1=recipient's PSP). examples: - 1 format: int64 type: integer requesterDocument: description: Requester CPF/CNPJ (cpfCnpjSolCancelamento, string). examples: - "04623217035" type: string requesterIspb: description: Requester participant ISPB (string). The schedule row this cancellation signs for has to be booked in this participant's books, or the cancellation is refused 404 PIX-0147 before JDPI is asked; an ISPB this deployment does not act as is 422 PIX-0128. 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: cancellationId: description: The cancellation id (29-char, CA...). examples: - CA0435879820240605abcd1234567 type: string 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 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 - cancellationId - cancelledAt - status type: object CancellationDetailResponse: additionalProperties: false properties: cancelStatus: description: stCancelamento (0=Aceito, 1=Rejeitado). Absent when JDPI did not report it. examples: - 0 format: int64 type: integer cancellationId: description: The cancellation id (IC...). examples: - IC0435879820240605abcd1234567 type: string 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 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. recurrenceId: description: The recurrence id. examples: - RR0435879820240605njua7shf40o type: string 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: - recurrenceId - cancellationId - requesterType - requesterDocument - reason - 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 (aaaa-mm-ddTHH:mm:ss.sssZ, UTC), on a credited result. examples: - "2026-06-20T10:00:01.000Z" 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 ispb: description: "The ISPB of the direct participant this operation acts as. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own DICT credential - and this field is the only thing on the request that says which of them writes to the national directory. OPTIONAL while it acts as a single participant: omit it and that one acts. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. It also selects the DICT credential the call goes out on, so a key registered under the wrong one is declared to Bacen by the wrong institution. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061." examples: - "12345678" pattern: ^[0-9]{8}$ 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 CRM account id whose limit to change. examples: - 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 payerIspb: description: "The ISPB of the direct participant whose limits these are. This deployment may act as SEVERAL direct SPI participants — one ISPB each, each with its own books — and the account id is an alias that is unique only inside ONE of them, so this field is what says whose rows to read or write. OPTIONAL while it acts as a single participant: omit it and that one answers. REQUIRED once it acts as several — omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on an order: never a credential, never read from a header or a path, and it never widens what your token can reach. Use the SAME participant you pay as, or the headroom you read is not the headroom that gets enforced. Send it absent, not empty; an empty string is refused 400 PIX-0061." examples: - "12345678" pattern: ^[0-9]{8}$ 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 ledger account alias the limit is kept for. examples: - "@pagador" 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 ispb: description: "The ISPB of the direct participant this operation acts as. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own DICT credential - and this field is the only thing on the request that says which of them writes to the national directory. OPTIONAL while it acts as a single participant: omit it and that one acts. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. It also selects the DICT credential the call goes out on, so a key registered under the wrong one is declared to Bacen by the wrong institution. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061." examples: - "12345678" pattern: ^[0-9]{8}$ 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 ispb: description: "The ISPB of the direct participant this operation acts as. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own DICT credential - and this field is the only thing on the request that says which of them writes to the national directory. OPTIONAL while it acts as a single participant: omit it and that one acts. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. It also selects the DICT credential the call goes out on, so a key registered under the wrong one is declared to Bacen by the wrong institution. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061." examples: - "12345678" pattern: ^[0-9]{8}$ 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 ispb: description: "The ISPB of the direct participant this operation acts as. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own DICT credential - and this field is the only thing on the request that says which of them writes to the national directory. OPTIONAL while it acts as a single participant: omit it and that one acts. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. It also selects the DICT credential the call goes out on, so a key registered under the wrong one is declared to Bacen by the wrong institution. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061." examples: - "12345678" pattern: ^[0-9]{8}$ 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 characters, 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, an RFC 3339 date-time). No row stores it, so a retry must resend the same value for JD to replay the confirmation. examples: - "2024-01-06T10:00:00.000Z" format: date-time pattern: \S patternDescription: non-blank type: string contractDesc: description: Free-text contract description. examples: - Conta de energia type: string contractNumber: description: Contract/order identifier (nrContrato). Blank is 400 PIX-0061. examples: - 1234567890ABC type: string createdDateTime: description: Recurrence creation timestamp (dtHrCriacaoRecorrencia, an RFC 3339 date-time). No row stores it, so a retry must resend the same value for JD to replay the confirmation. examples: - "2024-01-05T10:00:00.000Z" format: date-time pattern: \S patternDescription: non-blank 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, an RFC 3339 date-time). Required when journey=3 and not allowed otherwise; either violation is 400 PIX-0061. examples: - "2024-01-06T10:05:00.000Z" type: string startDate: description: First payment date (dtInicialRecorrencia; aaaa-mm-dd). examples: - "2024-01-10" type: string required: - journey - frequency - startDate - recipient - payer - contractNumber - createdDateTime - authorizedAt type: object ConfirmEntryBody: additionalProperties: false properties: accountId: description: The CRM account id of the key owner. examples: - acc-123 type: string ispb: description: "The ISPB of the direct participant this operation acts as. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own DICT credential - and this field is the only thing on the request that says which of them writes to the national directory. OPTIONAL while it acts as a single participant: omit it and that one acts. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. It also selects the DICT credential the call goes out on, so a key registered under the wrong one is declared to Bacen by the wrong institution. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061." examples: - "12345678" pattern: ^[0-9]{8}$ 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 (string). Blank is 400 PIX-0061. 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). Blank is 400 PIX-0061. examples: - "04623217035" type: string ibgeCode: description: Municipality IBGE code (codMunIbge). examples: - 3550308 format: int64 type: integer ispb: description: Payer participant ISPB (8 digits, string). When the payer row of this recurrence already exists here, it has to be booked in this participant's books, or the confirmation is refused 404 PIX-0147 before JDPI is asked - including a replay of an already-confirmed mandate. An ISPB this deployment does not act as is 422 PIX-0128. examples: - "00038166" type: string name: description: Payer name (nomePagador). Blank is 400 PIX-0061. 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 CourierOwnershipOutputBody: additionalProperties: false properties: chargerRecurrences: $ref: "#/components/schemas/CourierSyncReport" description: The charger side of the Pix Automático recurrences this engine opened as the recipient's PSP. legs: $ref: "#/components/schemas/CourierSyncReport" description: Open debit blocks and schedules, as leg:endToEndId. recurrences: $ref: "#/components/schemas/CourierSyncReport" description: Pix Automático recurrences this engine authorized as the payer's PSP. required: - recurrences - chargerRecurrences - legs type: object CourierSyncReport: additionalProperties: false properties: alreadyHeld: description: Keys the Courier already held for this engine. format: int64 type: integer heldElsewhere: description: Keys the Courier gives to another engine; only an operator resolves them. items: type: string type: - array - "null" recorded: description: Keys the Courier recorded for this engine on this call. format: int64 type: integer required: - recorded - alreadyHeld - heldElsewhere 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. directIspb: description: "ISPB of the DIRECT participant of this tenant the indirect mounts on — the institution whose ISPB and credential its Pix travels on, and in whose books its @pi position account is created. OPTIONAL: omit it and the tenant's default participant is used, which is where every indirect lived before this deployment could act as several. Must be a participant this deployment actually acts as (422 PIX-0128 otherwise). It is ROUTING DATA you supply and guarantee, never a credential. IMMUTABLE after registration: the @pi account exists in exactly one ledger, so PATCH cannot re-point it. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061." examples: - "12345678" pattern: ^[0-9]{8}$ type: string 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: contactEmail: description: Creator-contact email (required). examples: - ops@example.com type: string contactPhone: description: Creator-contact phone (required). examples: - "+5511999999999" type: string details: description: Free-text detail; required when situationType=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 ispb: description: "The ISPB of the direct participant this operation acts as. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own JDPI credential - and this field is the only thing on the request that says which of them acts. OPTIONAL while it acts as a single participant: omit it and that one acts. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. It also selects the JDPI channel the call goes out on, so a MED write made under the wrong one reaches a JD that has never heard of this institution. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061." examples: - "12345678" pattern: ^[0-9]{8}$ type: string situationType: 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 - situationType - contactEmail - contactPhone 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 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 from GET /v1/entries/{entryId}/lookup (§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, and on a payment by key it makes the order go out as manually typed." 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. Refused 422 PIX-0111, naming the setting to enable, while this deployment's indirect-participants feature is off — the order is never executed as a direct one, which would hold the funds on the payer's own account instead of the indirect's PIX position. examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string payee: $ref: "#/components/schemas/PayeeBody" description: The recipient bank data. payerIspb: description: "The ISPB of the institution the money leaves from. This deployment may act as SEVERAL direct SPI participants — one ISPB each, each with its own books — and this field is the only thing on the order that says which of them pays. OPTIONAL while it acts as a single participant: omit it and that one pays. REQUIRED once it acts as several — omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like indirectId: never a credential, never read from a header or a path, and it never widens what your token can reach. It also decides what counts as on-us — a payee on the PAYING institution ISPB settles as an internal transfer, a payee on a sibling institution of this same deployment is an ordinary Pix over SPI. On an order carrying indirectId it must be blank or the participant recorded at that indirect's registration, which is not necessarily the deployment default one (422 PIX-0102). Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061." examples: - "12345678" pattern: ^[0-9]{8}$ type: string 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: ispb: description: "The ISPB of the direct participant this decode is asked AS. OPTIONAL: omit it and the decode is made on the default credential, exactly as before. Named, JDPI is asked with that participant's credential. An ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here." examples: - "12345678" pattern: ^[0-9]{8}$ type: string 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. 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 tpConta (0=Conta Corrente, 1=Conta Salario, 2=Conta Poupanca, 3=Conta de Pagamento). Always present, including 0. 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). Always present, including 0. examples: - 2 format: int64 type: integer name: description: Recipient holder name. examples: - Jane Doe type: string required: - accountType - keyType 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 ispb: description: "The ISPB of the direct participant this decode asks as. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own JDPI credential - and this field is the only thing on the request that says which of them acts. OPTIONAL while it acts as a single participant: omit it and that one acts. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. It selects the JDPI credential the decode goes out on and nothing else - the decoded charge belongs to the payee, not to you. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061." examples: - "12345678" pattern: ^[0-9]{8}$ 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 (§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 ispb: description: "The ISPB of the direct participant this decode asks as. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own JDPI credential - and this field is the only thing on the request that says which of them acts. OPTIONAL while it acts as a single participant: omit it and that one acts. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. It selects the JDPI credential the decode goes out on and nothing else - the decoded charge belongs to the payee, not to you. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061." examples: - "12345678" pattern: ^[0-9]{8}$ 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 ispb: description: "The ISPB of the direct participant this operation acts as. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own DICT credential - and this field is the only thing on the request that says which of them writes to the national directory. OPTIONAL while it acts as a single participant: omit it and that one acts. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. It also selects the DICT credential the call goes out on, so a key registered under the wrong one is declared to Bacen by the wrong institution. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061." examples: - "12345678" pattern: ^[0-9]{8}$ 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: true properties: code: description: "Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN)." 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 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. Refused 422 PIX-0111, naming the setting to enable, while this tenant's indirect-participants feature is off: routing you supply is never silently dropped." examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string ispb: description: "The ISPB of the direct participant that mints this QR. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own JDPI credential - and this field is the only thing on the request that says which of them acts. OPTIONAL while it acts as a single participant: omit it and that one acts. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. The published payloadUrl and its JWKS location are built under this participant's ISPB, so a QR minted as the wrong one points every payer's PSP at a key set that cannot validate its signature. When indirectId is supplied this must be blank or the participant recorded at that indirect's registration, which is NOT necessarily this deployment's default one; naming any other is 422 PIX-0102. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061." examples: - "12345678" pattern: ^[0-9]{8}$ 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 refundRequestId: description: The effectuated refund-request GUID. examples: - d4e5f6a7-b8c9-0123-def4-56789012345a type: string required: - refundRequestId - 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 EntryLookupPayee: additionalProperties: false properties: accountDigit: description: "Always empty: the check digit, when the account has one, is already inside accountNumber. See accountNumber." examples: - "" type: string accountNumber: description: "The key's account exactly as DICT returns it (1 to 20 characters), check digit included when the account has one. DICT carries the account as ONE string and does not say where a check digit is, so it is never split here: send it back unchanged, with accountDigit empty, and the payment hands JD the same string." examples: - "0007654321" type: string accountType: description: "JDPI tpConta of the key's account: 0=Conta Corrente, 1=Conta Salario, 2=Conta Poupanca, 3=Conta de Pagamento, 4=Conta PI." examples: - 0 format: int64 type: integer branch: description: Branch of the key's account, without check digit (DICT nrAgencia). Empty when DICT holds none, which is normal for a payment account. examples: - "0001" type: string document: description: The key holder's CPF or CNPJ (DICT cpfCnpj). It is the recipient of the payment, not you. examples: - "11222333000181" type: string ispb: description: ISPB of the institution that holds the key's account (DICT ispb). examples: - "87654321" type: string key: description: The key as DICT holds it (CPF/CNPJ keys come back without punctuation). Send it as payee.key with endToEndId to have the payment initiated by key. examples: - payee@example.com type: string name: description: The key holder's full name or company name (DICT nome). examples: - Payee Comercio Ltda type: string required: - ispb - document - name - branch - accountNumber - accountDigit - key - accountType type: object EntryLookupResponse: additionalProperties: false properties: accountNumber: description: The account number as DICT returns it, the same value payee.accountNumber carries. examples: - "0007654321" type: string endToEndId: description: "The end-to-end id DICT minted for THIS lookup. Send it on POST /v1/transactions together with payee.key: that pair is what makes the payment one initiated by key (JDPI tpIniciacao=1). One lookup, one payment." examples: - E87654321202610061200abcdefghijk type: string keyType: description: Numeric eKeyType of the key (0=CPF,1=CNPJ,2=EMAIL,3=PHONE,4=RANDOM). examples: - 2 format: int64 type: integer payee: $ref: "#/components/schemas/EntryLookupPayee" description: The recipient, ready to be sent as the payee of POST /v1/transactions. personType: description: "The holder's person type (DICT tpPessoa): 0=Pessoa Fisica, 1=Pessoa Juridica." examples: - 1 format: int64 type: integer tradeName: description: The holder's trade name (DICT nomeFantasia), when DICT holds one. examples: - Payee type: string required: - endToEndId - keyType - personType - accountNumber - payee 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..8). 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 pagador: description: "The payer participant block (the party returning the money): ispb, cpfCnpj, nome, nrAgencia, nrConta. Read only when this engine never made the original payment." recebedor: description: "The receiver participant block: the account credited when this engine never made the original payment, which requires ispb (8 digits), cpfCnpj and nrConta, with nrAgencia optional." 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 (aaaa-mm-ddTHH:mm:ss.sssZ, UTC). examples: - "2026-06-20T10:00:00.000Z" 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: createdAt: description: JDPI creation timestamp (RFC 3339 UTC). examples: - "2024-01-01T12: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: - a7f12465e19f5ca51329479a5bae60c2 type: string dictReturnedAt: description: dtHrRetornoDict — when DICT answered this consultar (contract 2.16). examples: - "2023-08-16T10:30:05.025Z" type: string fraudMarkerId: description: Fraud-marker GUID (the natural key). examples: - c3d4e5f6-a7b8-9012-cdef-345678901234 type: string infractionId: description: Linked infraction GUID, when the marker was auto-created from a closed infraction. examples: - a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string infractionIspb: description: Linked infraction's PSP ISPB, when infraction-originated. examples: - "87654321" type: string ispb: description: ISPB of the creator PSP. examples: - "12345678" type: string key: description: The flagged Pix key, when known. examples: - user@example.com type: string status: description: stMarcacaoFraude lifecycle code (0=registered, 1=cancelled). examples: - 0 format: int64 type: integer statusDescription: description: Human-readable stMarcacaoFraude label. examples: - Registrada type: string taxId: description: The flagged document. examples: - "12345678901" 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 updatedAt: description: JDPI last-modification timestamp (RFC 3339 UTC) — the watermark. examples: - "2024-01-01T12:05:00.000Z" type: string required: - fraudMarkerId - ispb - tpPessoa - tpPessoaDescription - taxId - tpFraude - tpFraudeDescription - status - statusDescription - createdAt - updatedAt 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 ispb: description: "The ISPB of the direct participant this operation acts as. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own DICT credential - and this field is the only thing on the request that says which of them writes to the national directory. OPTIONAL while it acts as a single participant: omit it and that one acts. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. It also selects the DICT credential the call goes out on, so a key registered under the wrong one is declared to Bacen by the wrong institution. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061." examples: - "12345678" pattern: ^[0-9]{8}$ 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 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 characters, 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). directIspb: description: ISPB of the direct participant this indirect mounts on — recorded at registration and never changed. examples: - "12345678" type: string 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 ledgerId: description: The Midaz ledger inside that organization the @pi account was created in. Read-only. examples: - 019fb9b6-8ed1-7964-86e6-b421f711e62a type: string messagingMode: description: Delivery mode. examples: - raw type: string name: description: Display name. examples: - Indirect PSP Ltda type: string organizationId: description: "The Midaz organization of that direct participant: the books this indirect's @pi account lives in. Read-only." examples: - 019fb9b6-7593-7667-abe9-3b087192747b 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 - directIspb - organizationId - ledgerId - 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. EXECUTED is money that landed. PENDING is an inbound credit that has been claimed but not yet settled; it becomes EXECUTED on a later read, or stays PENDING if the credit never landed. 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. 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: analysisDetails: description: Analysis detail. examples: - Confirmed. type: string analysisResult: description: Infraction analysis result (0=Aceita, 1=Rejeitada); null until analysed. examples: - 0 format: int64 type: integer analysisResultDescription: description: Human-readable infraction analysis-result label. examples: - Aceita type: string counterpartIspb: description: ISPB of the counterparty. examples: - "87654321" type: string createdAt: description: JDPI creation timestamp (RFC 3339 UTC). examples: - "2024-01-01T12:00:00.000Z" type: string creatorIspb: description: ISPB of the infraction creator. examples: - "12345678" type: string details: description: Free-text detail to help the receiving PSP analyse. examples: - Suspected scam. type: string endToEndId: description: EndToEndId of the suspect payment. examples: - E1234567820240101000000000000001 type: string fraudMarkerId: description: Fraud-marker GUID, when analysis produced one. examples: - c3d4e5f6-a7b8-9012-cdef-345678901234 type: string infractionId: description: Infraction GUID (the natural key). examples: - a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string reason: description: Infraction reason code (1=refund request, 2=refund cancellation). examples: - 1 format: int64 type: integer reasonDescription: description: Human-readable infraction reason label. examples: - Solicitacao de refund type: string recoveryId: description: Value-recovery GUID, when the infraction came from a recovery. examples: - b2c3d4e5-f6a7-8901-bcde-f23456789012 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 updatedAt: description: JDPI last-modification timestamp (RFC 3339 UTC) — the poll watermark. examples: - "2024-01-01T12:05:00.000Z" type: string vlrInfracao: description: Amount to block on the account, in centavos; null when absent. examples: - 15000 format: int64 type: integer required: - infractionId - endToEndId - reason - reasonDescription - tpSitOrigem - tpSitOrigemDescription - status - statusDescription - creatorIspb - counterpartIspb - createdAt - updatedAt 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. 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 ledger account alias of a party this institution holds. examples: - "@pagador" type: string accountNumber: description: The party's account number. examples: - "123456" type: string 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 (0=CPF, 1=CNPJ, 2=EMAIL, 3=PHONE, 4=RANDOM). Absent when the party addressed no PIX key. examples: - 2 format: int64 type: integer name: description: The party's holder name. examples: - Jane Doe type: string personType: description: Numeric person type derived from the party's document (0=PERSON for a CPF, 1=CORPORATE for a document longer than a CPF). examples: - 0 format: int64 type: integer required: - personType 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 from GET /v1/entries/{entryId}/lookup (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 return deadline has been reached or passed (computed at read time); false when no deadline is set. examples: - false type: boolean contactEmail: description: Creator-contact email. examples: - ops@example.com type: string contactPhone: description: Creator-contact phone. examples: - "+5511999999999" type: string createdAt: description: JDPI creation timestamp (RFC 3339 UTC). examples: - "2024-01-01T12:00:00.000Z" type: string creatorIspb: description: ISPB of the recovery creator. examples: - "12345678" type: string details: description: Free-text detail (required when situationType=4 Outros). examples: - Suspected scam. 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 idTransacaoRaiz: description: EndToEndId of the root transaction being recovered. examples: - E1234567820240101000000000000001 type: string recoveryId: description: Value-recovery GUID (the natural key). examples: - b2c3d4e5-f6a7-8901-bcde-f23456789012 type: string returnDeadline: description: Creator-side 72h return deadline (RFC 3339 UTC; contract §2.22/§5), from the analysis stage close; null unless this institution is the creatorIspb on an analyzed recovery. examples: - "2024-01-04T12:00:00.000Z" type: string situationType: description: Situation code (0..5). examples: - 0 format: int64 type: integer situationTypeDescription: description: Human-readable situationType label. examples: - Golpe/Estelionato type: string status: description: stRecValores lifecycle code (0=created .. 6=cancelled). examples: - 0 format: int64 type: integer statusDescription: description: Human-readable stRecValores label. examples: - Criada type: string updatedAt: description: JDPI last-modification timestamp (RFC 3339 UTC) — the watermark. examples: - "2024-01-01T12:05:00.000Z" type: string required: - recoveryId - idTransacaoRaiz - situationType - situationTypeDescription - contactEmail - contactPhone - creatorIspb - status - statusDescription - createdAt - updatedAt - 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. 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 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 indirectId: description: "The registered indirect participant (UUID) that received the original Pix on its PIX position, required exactly then and debited for the refund: absent is 422 PIX-0135. Named, the original has to be held by that indirect, or the refund is refused 404 PIX-0147 before anything is read, held or sent - another indirect's Pix, and a Pix received on a direct account, are not the named indirect's to return, and a token confined to one indirect has to name it here. It then passes the checks of a payment order's indirectId (422 PIX-0111 feature off, 404 PIX-0095 unknown, 422 PIX-0100 not ACTIVE)." examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string payerIspb: description: "The ISPB of the direct participant paying this refund back - the one that received the original Pix. OPTIONAL: omit it and the original is refunded by whichever participant holds it, exactly as before. Named, the original has to be booked in that participant's books, or the refund is refused 404 PIX-0147 before anything is read, held or sent - the same original named under another participant is not refunded. An ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here; on a Pix received by an indirect, name the direct participant it rides alongside indirectId. Send it as an absent key, not an empty string." examples: - "12345678" pattern: ^[0-9]{8}$ type: string transactionId: description: The original transaction id (UUID). examples: - d1f9c0a2-7b3e-4c51-9a6d-2f8e0b4c1a37 type: string required: - endToEndId - accountId - transactionId - code - amount type: object RefundCreditStatusView: additionalProperties: false properties: 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 isIntraPsp: description: True when the transaction is internal to this direct PSP (both legs on the same participant). examples: - false type: boolean refundAmount: description: Refunded amount, in centavos; omitted when JDPI did not return it (Obrg=Nao). examples: - 5010 format: int64 type: integer refundCode: description: Refund code (BE08=MED started by the recipient's PSP, FR01=well-founded suspicion of fraud, MD06=requested by the recipient, SL02=error or disagreement on a Pix Saque or Pix Troco). examples: - BE08 type: string refundEndToEndId: 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=request received, awaiting processing, 1=credit validated, awaiting settlement by the SGCT, 2=credit validation sent to SPI, 5=no final answer from SPI, 7=refund refused by SPI, 8=refund refused by JDPI, 9=credit settled. A DISTINCT domain from the debit poll's stJdPiProc despite the shared field name." examples: - 9 format: int64 type: integer statusAt: description: When the refund order reached this situation in JDPI (raw JDPI instant). examples: - "2020-01-24T10:30:00.000Z" type: string required: - refundEndToEndId - statusAt - stJdPiProc - stJdPi - refundCode - isIntraPsp 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: Contested-side analysis deadline (RFC 3339 UTC; contract §5, 6h for fraud / 48h otherwise); null for filer-side and terminal requests. examples: - "2024-01-01T18:00:00.000Z" type: string analysisDetails: description: Analysis detail. examples: - Insufficient balance. type: string analysisResult: description: Refund analysis result (0=Aceita Totalmente, 1=Aceita Parcialmente, 2=Rejeitada); null until analysed. examples: - 0 format: int64 type: integer analysisResultDescription: description: Human-readable refund analysis-result label. examples: - Aceita Totalmente 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 contestedIspb: description: ISPB of the contested PSP. examples: - "87654321" type: string createdAt: description: JDPI creation timestamp (RFC 3339 UTC). examples: - "2024-01-01T12:00:00.000Z" type: string details: description: Free-text detail. examples: - Operational failure. type: string endToEndId: description: EndToEndId of the contested payment or refund. examples: - E1234567820240101000000000000001 type: string infractionId: description: Linked infraction GUID, when fraud. examples: - a1b2c3d4-e5f6-7890-abcd-ef1234567890 type: string reason: description: Refund reason code (0=operational failure, 1=fraud, 3=Pix Automatico). examples: - 1 format: int64 type: integer reasonDescription: description: Human-readable refund reason label. examples: - Fraude type: string recoveryId: description: Value-recovery GUID, when from a recovery. examples: - b2c3d4e5-f6a7-8901-bcde-f23456789012 type: string refundAmount: description: Requested refund amount, in centavos. examples: - 25000 format: int64 type: integer refundEndToEndId: description: pacs.004/pacs.008 refund reference, recorded at analysis. examples: - D1234567820240101000000000000099 type: string refundRequestId: description: Refund-request GUID (the natural key). examples: - d4e5f6a7-b8c9-0123-def4-56789012345a type: string refundedAmount: description: Amount actually refunded, in centavos; null when absent. examples: - 25000 format: int64 type: integer registeredAt: description: When the request was REGISTERED in the JDPI base (raw JDPI instant), distinct from createdAt (the DICT creation instant). Returned by the §8.2.26 JDPI-base read only. examples: - "2021-08-06T10:33:08.241Z" type: string rejectionReason: description: Rejection reason (0,1,3,4); present only when the analysis rejected the request. examples: - 0 format: int64 type: integer rejectionReasonDescription: description: Human-readable rejection-reason label. examples: - Falta de saldo type: string requesterIspb: description: ISPB of the requesting PSP. examples: - "12345678" type: string status: description: stSolDevolucao lifecycle code (0=open, 1=cancelled, 2=analyzed). examples: - 0 format: int64 type: integer statusDescription: description: Human-readable stSolDevolucao label. examples: - Aberta type: string updatedAt: description: JDPI last-modification timestamp (RFC 3339 UTC) — the poll watermark. examples: - "2024-01-01T12:05:00.000Z" type: string required: - refundRequestId - endToEndId - reason - reasonDescription - refundAmount - status - statusDescription - requesterIspb - contestedIspb - createdAt - updatedAt - breached type: object RefundResponse: additionalProperties: false properties: accountId: description: "The Midaz alias of the account the refund debits: the one the original credited, or the indirect's @pi_{ispb} on an indirect refund." examples: - "@recebedor" 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, filled when JD supplies it; may be empty while PENDING, which is not a failure. examples: - D1234567890 type: string id: description: The created refund id. examples: - a2f9c0d1-... type: string status: description: eTransactionStatus name. A refund sent over SPI answers PENDING until SPI settles it. 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 ispb: description: "The ISPB of the direct participant this operation acts as. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own DICT credential - and this field is the only thing on the request that says which of them writes to the national directory. OPTIONAL while it acts as a single participant: omit it and that one acts. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. It also selects the DICT credential the call goes out on, so a key registered under the wrong one is declared to Bacen by the wrong institution. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061." examples: - "12345678" pattern: ^[0-9]{8}$ type: string 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: ispb: description: "The ISPB of the direct participant this operation acts as. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own JDPI credential - and this field is the only thing on the request that says which of them acts. OPTIONAL while it acts as a single participant: omit it and that one acts. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. It also selects the JDPI channel the call goes out on, so a MED write made under the wrong one reaches a JD that has never heard of this institution. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061." examples: - "12345678" pattern: ^[0-9]{8}$ type: string key: description: The flagged Pix key, if known. examples: - user@example.com type: string taxId: description: The flagged document. examples: - "12345678901" 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 - taxId - tpFraude 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: ispb: description: "The ISPB of the direct participant this reply is sent AS. It is ROUTING DATA you supply and guarantee - never a credential, never read from a header or a path, and it never widens what your token can reach. It is IGNORED when this deployment holds the authorization: a recorded mandate already names the direct participant whose books it lives in, and that is authoritative. It DECIDES when it does not - on jornada 3 the inbound 5.2.1 that obliges this reply writes no local row, so nothing but this field can say which of several participants is answering Bacen. OPTIONAL while this deployment acts as a single direct participant: omit it and that one replies. REQUIRED once it acts as several and no local row exists - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. Sending one that contradicts a recorded authorization is 400 PIX-0061. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061." examples: - "12345678" pattern: ^[0-9]{8}$ type: string rejectionReason: description: "Rejection reason (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, an RFC 3339 date-time). No row stores it, so a retry must resend the same value for JD to replay the reply. examples: - "2024-01-06T10:00:00.000Z" format: date-time pattern: \S patternDescription: non-blank type: string required: - result - validatedAt 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 pattern: \S patternDescription: non-blank type: string createdDateTime: description: Recurrence creation timestamp (dtHrCriacaoRecorrencia, an RFC 3339 date-time). No row stores it, so a retry must resend the same value for JD to replay the request. examples: - "2024-01-05T10:00:00.000Z" format: date-time pattern: \S patternDescription: non-blank 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, an RFC 3339 date-time; at most 30 days after solicitationDateTime). examples: - "2024-01-06T10:00:00.000Z" format: date-time pattern: \S patternDescription: non-blank 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 payer: $ref: "#/components/schemas/AuthorizationPayerBody" description: The recurrence pagador (account being authorized). recipient: $ref: "#/components/schemas/AuthorizationRecipientBody" description: The recurrence recebedor (authorized charging entity). recurrenceId: description: Unique recurrence id (29-char, format RR...). examples: - RR0435879820240605njua7shf40o pattern: \S patternDescription: non-blank type: string solicitationDateTime: description: Solicitation creation timestamp (dtHrCriacaoSolicitacao, an RFC 3339 date-time). No row stores it, so a retry must resend the same value for JD to replay the request. examples: - "2024-01-05T10:00:00.000Z" format: date-time pattern: \S patternDescription: non-blank type: string startDate: description: First payment date (dtInicialRecorrencia; aaaa-mm-dd). examples: - "2024-01-10" pattern: \S patternDescription: non-blank type: string required: - recurrenceId - frequency - startDate - recipient - payer - contractNumber - createdDateTime - solicitationDateTime - expirationDateTime type: object RequestAuthorizationResponse: additionalProperties: false properties: idReqJdPi: description: The JDPI request id (36-char GUID). examples: - 52c43361-caa1-4ddb-9152-708426a25db3 type: string recurrenceId: description: The recurrence id (echoed). examples: - RR0435879820240605njua7shf40o 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 - recurrenceId - 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" pattern: \S patternDescription: non-blank type: string endToEndId: description: Unique payment-transaction id (32-char natural key). examples: - E00038166202409171500y6j6mt9l0pi pattern: \S patternDescription: non-blank 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, an RFC 3339 date-time). Required when purpose=0; omitted or blank there is 400 PIX-0061. Sent with purpose 1 or 2 is 400 PIX-0061. examples: - "2024-09-17T10:25:49.025Z" type: string reconciliationId: description: Receiver conciliation id (idConciliacaoRecebedor; 26..35-char). examples: - JDPI2024091700000000000000000000001 pattern: \S patternDescription: non-blank type: string recurrenceId: description: Recurrence id linking the authorization (29-char, RR...). examples: - RR0435879820240605njua7shf40o pattern: \S patternDescription: non-blank type: string required: - endToEndId - reconciliationId - recurrenceId - purpose - dueDate - recipient - payer type: object RequestScheduleResponse: additionalProperties: false properties: endToEndId: description: The payment-transaction id (echoed). examples: - E00038166202409171500y6j6mt9l0pi type: string reconciliationId: description: The receiver conciliation id (echoed). examples: - JDPI2024091700000000000000000000001 type: string recurrenceId: description: The recurrence id (echoed). examples: - RR0435879820240605njua7shf40o 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: - recurrenceId - 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, an RFC 3339 date-time). Required when result=true, so a retry resends the same value for JD to replay the response; omitted, blank or not a date-time on an acceptance is 400 PIX-0061. Not sent on a rejection. examples: - "2024-01-06T10:00:00.000Z" 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). Blank is 400 PIX-0061. examples: - Fulano de Tal type: string rejectionReason: description: Rejection reason (AP13/AP14/AP15). Required when result=false; omitted or blank there is 400 PIX-0061. 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). Absent when JDPI did not report it. examples: - 0 format: int64 type: integer cancellationId: description: The cancellation id (29-char, CA...). examples: - CA0435879820240605abcd1234567 type: string 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 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: Requester participant ISPB (string). examples: - "04358798" type: string requesterType: description: tpPessoaSol. examples: - 0 format: int64 type: integer required: - cancellationId - requesterIspb - recipientIspb - requesterType - requesterDocument - reason - cancelledAt type: object ScheduleCancellationResponse: additionalProperties: false properties: cancelStatus: description: stCancelamento (0=Aceito, 1=Rejeitado). Absent when JDPI did not report it. examples: - 0 format: int64 type: integer cancellationId: description: The cancellation id (CA...). examples: - CA0435879820240605abcd1234567 type: string 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 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=payer's PSP, 1=recipient's PSP). examples: - 1 format: int64 type: integer requesterDocument: description: Requester CPF/CNPJ (string). examples: - "04623217035" type: string requesterIspb: description: Requester participant ISPB (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: - cancellationId - endToEndId - stJdPiProc - stJdPi - localStatus - localStatusKnown - requester - requesterIspb - recipientIspb - requesterType - requesterDocument - reason 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 (0=Pessoa Fisica, 1=Pessoa Juridica). examples: - 0 format: int64 type: integer required: - personType type: object ScheduleParty: additionalProperties: false properties: account: description: Account number (string). examples: - "0007654321" type: string accountType: description: tpConta (0=Conta Corrente, 1=Conta Salario, 2=Conta Poupanca, 3=Conta de Pagamento). Present on the recipient; on the payer only when JDPI reports it (the list does, a single consult does not). 0 is Conta Corrente, never absence. 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 (0=Pessoa Fisica, 1=Pessoa Juridica). Present on the payer; absent on the recipient, whose block carries none. 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" pattern: \S patternDescription: non-blank type: string ispb: description: Payer participant ISPB (8 digits, string). examples: - "00038166" pattern: ^[0-9]{8}$ 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 characters, 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 (string). examples: - "0007654321" pattern: \S patternDescription: non-blank 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 characters, string). examples: - "61695227000193" pattern: \S patternDescription: non-blank type: string ispb: description: Recipient participant ISPB (8 digits, string). examples: - "04358798" pattern: ^[0-9]{8}$ 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; absent when the debtor is the payer. 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 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 (0=first attempt, 1=post-due retry, 2=resend after a settlement error). Always present, including 0. 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 recurrenceId: description: The recurrence id (RR...). examples: - RR0435879820240605njua7shf40o type: string requestedAt: description: JDPI request timestamp (UTC). examples: - "2024-09-17T10:10:05Z" type: string scheduleStatus: description: stAgendamento (0=Aceito, 1=Rejeitado). Absent when JDPI did not report it. examples: - 0 format: int64 type: integer situationAt: description: Situation timestamp (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 - recurrenceId - stJdPiProc - stJdPi - localStatus - localStatusKnown - recipient - payer - purpose 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: details: description: Free-text detail; required when reason=0 (Falha Operacional). examples: - Suspected scam. type: string endToEndId: description: EndToEndId of the contested payment (or pacs.004 id for a cancellation reason). examples: - E1234567820240101000000000000001 type: string ispb: description: "The ISPB of the direct participant this operation acts as. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own JDPI credential - and this field is the only thing on the request that says which of them acts. OPTIONAL while it acts as a single participant: omit it and that one acts. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. It also selects the JDPI channel the call goes out on, so a MED write made under the wrong one reaches a JD that has never heard of this institution. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061." examples: - "12345678" pattern: ^[0-9]{8}$ type: string reason: description: Refund reason (0=operational failure, 1=fraud, 3=Pix Automatico). examples: - 1 format: int64 type: integer refundAmount: description: Requested refund amount, in centavos. examples: - 25000 format: int64 type: integer required: - endToEndId - reason - refundAmount 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 ispb: description: "The ISPB of the direct participant that mints this QR. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own JDPI credential - and this field is the only thing on the request that says which of them acts. OPTIONAL while it acts as a single participant: omit it and that one acts. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061." examples: - "12345678" pattern: ^[0-9]{8}$ 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 ledger account alias the limit is kept for. examples: - "@pagador" 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: a charge records the indirect it was generated for, and naming ANOTHER indirect - or naming one on a charge generated for the direct participant - is refused 404 PIX-0147 before JDPI is called, and the charge is not changed. A charge generated before that record existed is not checked. An omitted value is not checked either, and re-signs the charge under the DIRECT participant's certificate and moves its location onto the direct participant's domain. Refused 422 PIX-0111, naming the setting to enable, while this tenant's indirect-participants feature is off: routing you supply is never silently dropped." examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string ispb: description: "The ISPB of the direct participant that mints this QR. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own JDPI credential - and this field is the only thing on the request that says which of them acts. OPTIONAL while it acts as a single participant: omit it and that one acts. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. The published payloadUrl and its JWKS location are built under this participant's ISPB, so a QR minted as the wrong one points every payer's PSP at a key set that cannot validate its signature. When indirectId is supplied this must be blank or the participant recorded at that indirect's registration, which is NOT necessarily this deployment's default one; naming any other is 422 PIX-0102. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061." examples: - "12345678" pattern: ^[0-9]{8}$ 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: recurrenceId: description: The recurrence id. examples: - RR0435879820240605njua7shf40o type: string requestedAt: description: JDPI request timestamp (dtHrReqJdPi, UTC). examples: - "2024-03-01T10:00:00Z" type: string required: - recurrenceId - 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 (aaaa-mm-ddTHH:mm:ss.sssZ, UTC). examples: - "2026-06-20T10:00:00.000Z" type: string motivo: description: Reason code on an invalid result (BE17/AC03/AC06/AC07/BE01/AM09). 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 ispb: description: "The ISPB of the direct participant this operation acts as. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own DICT credential - and this field is the only thing on the request that says which of them writes to the national directory. OPTIONAL while it acts as a single participant: omit it and that one acts. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. It also selects the DICT credential the call goes out on, so a key registered under the wrong one is declared to Bacen by the wrong institution. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061." examples: - "12345678" pattern: ^[0-9]{8}$ 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. ⚠️ **BREAKING**: the payer's PIX key is gone from payment orders, so a `POST /v1/transactions` body still carrying the top-level `key` is refused `400 PIX-0061` (the payee's `payee.key` is unchanged). - **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 refund, 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** — MED 2.0: infraction reports, the refund-request money flow in both roles, creator-side value recoveries and DICT fraud markers. A MED settlement credit arrives on the §9.3.3 refund webhook under Webhooks. - **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 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: every money field on this API's own write surfaces, MED writes included, is 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: - **The `X-Idempotency` header** is REQUIRED on payment orders (`POST /v1/transactions`), on refunds (`POST /v1/refunds`) and on the ten MED write operations, and it is the SAME header, by the same name, that the Midaz ledger takes on its transaction routes — one integration, one header. Send any stable business string; omitting it is refused `400 PIX-0061` before any ledger or JDPI call. On a payment order it is the only identifier that exists BEFORE the JDPI call, so it protects every branch, on-us included: a resend of an order already recorded under the key — or under its `endToEndId` — is refused `409 PIX-0029` and moves no money, and so is a resend of a refund already recorded under its key. Payment and refund keys are scoped to the payer: the organization, plus the indirect participant on an indirect order or refund. ⚠️ **BREAKING**: payment orders and refunds took the value as the optional body field `clientRequestId` and MED writes as the body field `idempotencyKey`; both fields are gone, and three MED writes (cancel a refund request, cancel an infraction, return a recovery) now take no request body at all. - **The JDPI `Chave-Idempotencia`**: the value you send on `X-Idempotency` 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 inside JD's 24h window. 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 order, namespaced per LEG, so the two legs of one devolution (or a debit and its reversal) 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. Which of this deployment's direct participants writes to the national directory is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own ISPB and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. A key written under the wrong participant is declared to Bacen by the wrong institution, and there is no undo. 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 "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 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, 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 faulting is 503 PIX-1050, JDPI unreachable is 503 PIX-1054, 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 faulting is 503 PIX-1050, JDPI unreachable is 503 PIX-1054, 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 (awaiting resolution), 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. Which participant's DICT mailbox is read is decided by ispb, by exactly the rule an order's payerIspb follows - and here it decides WHOSE claims come back, not merely which credential signs the call, because §8.2.13 and §8.2.15 answer for a PARTICIPANT. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. Sending it empty (ispb=) reads the same as omitting it. 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 - description: "The ISPB of the direct participant whose directory answers. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own DICT credential - and this field is the only thing on the request that says which of them is read. OPTIONAL while it acts as a single participant: omit it and that one answers. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. Read the participant that holds the keys, or the listing comes back empty for an account that has them. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant whose directory answers. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own DICT credential - and this field is the only thing on the request that says which of them is read. OPTIONAL while it acts as a single participant: omit it and that one answers. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. Read the participant that holds the keys, or the listing comes back empty for an account that has them. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/GetClaimsBody" 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 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 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. Which of this deployment's direct participants writes to the national directory is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own ISPB and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. A key written under the wrong participant is declared to Bacen by the wrong institution, and there is no undo. 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 "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 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 reason follows the §8.2.11 matrix for the side and the claim type: a claimer (status 5 or 7) sends 0 = user request; a DONOR (status 6) sends 0 for a portability claim but 4 = fraud 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. Which of this deployment's direct participants writes to the national directory is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own ISPB and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. A key written under the wrong participant is declared to Bacen by the wrong institution, and there is no undo. 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 "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 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. Which participant's DICT mailbox is read is decided by ispb, by exactly the rule an order's payerIspb follows - and here it decides WHOSE claims come back, not merely which credential signs the call, because §8.2.13 and §8.2.15 answer for a PARTICIPANT. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. Sending it empty (ispb=) reads the same as omitting it. 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 - description: "The ISPB of the direct participant whose directory answers. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own DICT credential - and this field is the only thing on the request that says which of them is read. OPTIONAL while it acts as a single participant: omit it and that one answers. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. Read the participant that holds the keys, or the listing comes back empty for an account that has them. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant whose directory answers. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own DICT credential - and this field is the only thing on the request that says which of them is read. OPTIONAL while it acts as a single participant: omit it and that one answers. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. Read the participant that holds the keys, or the listing comes back empty for an account that has them. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ClaimResultResponse" 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 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. Which of this deployment's direct participants writes to the national directory is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own ISPB and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. A key written under the wrong participant is declared to Bacen by the wrong institution, and there is no undo. 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 "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 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 reason 0 (user request), 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. Which of this deployment's direct participants writes to the national directory is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own ISPB and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. A key written under the wrong participant is declared to Bacen by the wrong institution, and there is no undo. 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 "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 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. Which of this deployment's direct participants answers is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own customers and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. Sending it empty (ispb=) reads the same as omitting it. Read the participant that holds the keys: another one's directory answers for its own customers, not yours. 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 - description: "The ISPB of the direct participant whose directory answers. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own DICT credential - and this field is the only thing on the request that says which of them is read. OPTIONAL while it acts as a single participant: omit it and that one answers. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. Read the participant that holds the keys, or the listing comes back empty for an account that has them. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant whose directory answers. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own DICT credential - and this field is the only thing on the request that says which of them is read. OPTIONAL while it acts as a single participant: omit it and that one answers. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. Read the participant that holds the keys, or the listing comes back empty for an account that has them. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/EntryListBody" 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 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. The service records the registration as pending (status 8) BEFORE it asks DICT. If DICT does not answer in time the call is 504 PIX-1051, and if DICT cannot be reached it is 503 PIX-1054 - never 500 - and the pending record stays: DICT may still have registered the key. Retrying the same CPF, CNPJ, EMAIL or PHONE key re-sends the same request, which DICT deduplicates. For RANDOM, whose value only DICT knows, the next RANDOM request for the account first reads the account's DICT keys: when DICT lists exactly ONE EVP that this deployment never recorded, it is adopted and returned as ACTIVE instead of minting another; when it lists none, or several unrecorded EVPs (there is then no telling which one was this account's), a new RANDOM request is 409 PIX-0007 for up to 10 minutes after the unanswered one, after which the pending record is released and a new EVP is registered. Which of this deployment's direct participants writes to the national directory is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own ISPB and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. A key written under the wrong participant is declared to Bacen by the wrong institution, and there is no undo. 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 "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 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. Which of this deployment's direct participants writes to the national directory is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own ISPB and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. A key written under the wrong participant is declared to Bacen by the wrong institution, and there is no undo. 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 "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 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 every live local row of the key in this participant, whichever account of the holder it names, except another holder's pending ownership confirmation. 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: stale local rows are hidden so the listing stops advertising the key, and with no local row on this account either the call is 403 PIX-0018. A key whose registration never got an answer (a pending record at status 8) that the account's directory listing does not show was never registered: once that registration is older than its own time limit (about one minute), the pending record is released, this account's other local rows of the key are hidden as stale (a claim in progress is left to the claim flow), and the call succeeds; before that the registration may still land, and the call is 409 PIX-0007 - retry it a minute later. Order matters for recovery. DICT is deleted FIRST, then the local rows are 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 a local row keeps surfacing in GET /v1/entries with its stale status; re-issuing the DELETE through the same account finishes that account's cleanup: §8.2.14 reports the key gone, so the account's stale rows are hidden (a claim in progress is left to the claim flow) and the call succeeds. Another account's stale row of the key is cleaned by a DELETE through that account. A row still pending registration follows its own rule: once its time limit passes, the retry releases it and succeeds, as described above. The DICT deletion itself cannot be undone through this API - register the key again with POST /v1/entries. Which of this deployment's direct participants writes to the national directory is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own ISPB and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. A key written under the wrong participant is declared to Bacen by the wrong institution, and there is no undo. 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 "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 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 reason code: 0=Customer Request, 2=Branch Transfer, 6=Reconciliation, 8=Receita Federal Validation; an EVP (RANDOM) key must not use 0. When the change moves the key to another account (newAccount or newAccountType differs from accountId's own), the plugin clears the account link on the holder's local rows of the key, so every account of the holder lists it until it is deleted; a change that keeps the key on its account leaves the rows alone. 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. Which of this deployment's direct participants writes to the national directory is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own ISPB and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. A key written under the wrong participant is declared to Bacen by the wrong institution, and there is no undo. 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 "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 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. Which of this deployment's direct participants writes to the national directory is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own ISPB and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. A key written under the wrong participant is declared to Bacen by the wrong institution, and there is no undo. 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 "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 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. Which of this deployment's direct participants answers is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own customers and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. Sending it empty (ispb=) reads the same as omitting it. Read the participant that holds the keys: another one's directory answers for its own customers, not yours. 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 - description: "The ISPB of the direct participant whose directory answers. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own DICT credential - and this field is the only thing on the request that says which of them is read. OPTIONAL while it acts as a single participant: omit it and that one answers. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. Read the participant that holds the keys, or the listing comes back empty for an account that has them. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant whose directory answers. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own DICT credential - and this field is the only thing on the request that says which of them is read. OPTIONAL while it acts as a single participant: omit it and that one answers. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. Read the participant that holds the keys, or the listing comes back empty for an account that has them. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/EntryDetailsResponse" 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 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/entries/{entryId}/lookup: get: description: |- Resolves a PIX key you are about to PAY - anyone's key, at any institution - into the recipient a payment needs (§8.2.14 Consultar Chave de Endereçamento). entryId is the key value, URL-encoded; account_id is YOUR account, the one the payment will leave from. Call it right before POST /v1/transactions: copy payee into that body as it stands and send endToEndId with it. payee.key plus endToEndId is what makes the payment one initiated by key (JDPI tpIniciacao=1); a payment by key without the endToEndId goes out as a manually typed one. The endToEndId belongs to this lookup: one lookup, one payment, and a new lookup before every payment. The answer is what DICT holds now: the holder's document, name and person type, the institution (ispb), branch, account and account type. DICT returns the account as ONE string and does not say where a check digit is, so it is never split: payee.accountNumber carries it whole and payee.accountDigit is empty, and the payment hands JD the same string. Unlike GET /v1/entries/{entryId}/details, the holder is NOT compared against you: resolving someone else's key is the purpose of this route. Nothing is written here, but the call is not free. DICT counts every lookup against the payer (PI-PayerId, your account holder's CPF/CNPJ) and against this institution, and a lookup that is not followed by a payment still spends that budget (§8.2.14, §8.2.31). This deployment therefore limits lookups per payer account before DICT is asked, always, whether or not its general request limits are switched on: by default 100 lookups per payer account per 60 seconds, which the operator tunes apart from every other limit. Past it the call is 429 PIX-0009 with Retry-After, and DICT itself refusing is 429 PIX-1008. Look a key up when the payer is about to pay it, never to browse or to validate a list - POST /v1/entries/verification is the batch existence check. Refusals: 400 PIX-0061 when account_id is missing or blank, or ispb is not 8 digits; 404 PIX-2016 when account_id does not resolve to an account; 404 PIX-1011 when DICT holds no such key; 429 PIX-0009 (this deployment's per-payer limit) or PIX-1008 (DICT's); 503 PIX-1050 when JDPI is unavailable and 503 PIX-1054 when it cannot be reached; 504 PIX-1051 when JDPI does not answer in time. Which of this deployment's direct participants asks DICT is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own customers and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. Send the participant the payment will be paid by: the endToEndId carries the ISPB of the participant that asked. Paying through an INDIRECT participant: send indirectId, the same one the payment order will carry. The lookup then asks DICT on that indirect's behalf, so the endToEndId names the indirect - the institution the payment originates from - rather than the direct participant it rides (JDPI §8.2.14 PI-RequestingParticipant). Without it the endToEndId names the direct participant and does not match the order's payer. indirectId is validated before DICT is asked, by the rules the order applies: 404 PIX-0095 unknown to this tenant, 422 PIX-0100 not ACTIVE, 422 PIX-0111 while the indirect-participants feature is off. The lookup acts as the direct participant that indirect is mounted on: omit ispb, or send that participant's ISPB; any other is 422 PIX-0102. operationId: lookupEntry parameters: - description: The PIX key to resolve, URL-encoded. in: path name: entryId required: true schema: description: The PIX key to resolve, URL-encoded. examples: - payee@example.com type: string - description: The CRM account id of the PAYER - the account the payment will leave from. Its holder's CPF/CNPJ is the identity DICT counts the lookup against. explode: false in: query name: account_id required: true schema: description: The CRM account id of the PAYER - the account the payment will leave from. Its holder's CPF/CNPJ is the identity DICT counts the lookup against. examples: - acc-123 type: string - description: "The ISPB of the direct participant the payer banks at, and therefore the one that asks DICT. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own DICT credential - and this field is the only thing on the request that says which of them asks. OPTIONAL while it acts as a single participant: omit it and that one asks. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. Send the same participant as the payment's payerIspb: the endToEndId DICT mints carries the ISPB of the participant that asked. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant the payer banks at, and therefore the one that asks DICT. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own DICT credential - and this field is the only thing on the request that says which of them asks. OPTIONAL while it acts as a single participant: omit it and that one asks. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. Send the same participant as the payment's payerIspb: the endToEndId DICT mints carries the ISPB of the participant that asked. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string - description: "The registered indirect participant (UUID) the payment will be paid through - send the SAME indirectId the payment order will carry. DICT then mints the endToEndId under that indirect's ISPB, which is the institution the payment originates from; without it the endToEndId names the direct participant, and a payment by key ordered with an indirectId would go out naming the wrong institution. Omit it for a payment the direct participant pays. Validated before DICT is asked, exactly as the order validates it: 404 PIX-0095 unknown to this tenant, 422 PIX-0100 not ACTIVE, 422 PIX-0111 while this deployment's indirect-participants feature is off - the lookup is never made as a direct one instead. The lookup then acts as the direct participant the indirect is mounted on: omit ispb, or send that participant's ISPB; any other is 422 PIX-0102. A token confined to one indirect has to name it here, and may name no other." explode: false in: query name: indirectId schema: description: "The registered indirect participant (UUID) the payment will be paid through - send the SAME indirectId the payment order will carry. DICT then mints the endToEndId under that indirect's ISPB, which is the institution the payment originates from; without it the endToEndId names the direct participant, and a payment by key ordered with an indirectId would go out naming the wrong institution. Omit it for a payment the direct participant pays. Validated before DICT is asked, exactly as the order validates it: 404 PIX-0095 unknown to this tenant, 422 PIX-0100 not ACTIVE, 422 PIX-0111 while this deployment's indirect-participants feature is off - the lookup is never made as a direct one instead. The lookup then acts as the direct participant the indirect is mounted on: omit ispb, or send that participant's ISPB; any other is 422 PIX-0102. A token confined to one indirect has to name it here, and may name no other." examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/EntryLookupResponse" 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 default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Look up a PIX key before paying it tags: - Entries x-mint: href: /en/reference/interfaces/pix-jd/look-up-a-pix-key-before-paying-it /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. Which of this deployment's direct participants writes to the national directory is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own ISPB and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. A key written under the wrong participant is declared to Bacen by the wrong institution, and there is no undo. 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 "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 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. directIspb filters by the DIRECT participant the indirects ride, and is not ispb: ispb is the indirect's own. A token confined to one direct participant has to name it in directIspb, and then sees only the indirects mounted on that participant. 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 the INDIRECT's own exact ISPB (8 digits). explode: false in: query name: ispb schema: description: Filter by the INDIRECT's own 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 - description: "Filter by the DIRECT participant the indirects ride (8 digits) - not to be confused with ispb, which is the indirect's own. OPTIONAL: omit it and every direct participant's indirects are listed, exactly as before. Named, only the indirects mounted on that participant come back; an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply, never a credential, and a token confined to one direct participant has to name it here. Sending it empty (directIspb=) reads the same as omitting it." explode: false in: query name: directIspb schema: description: "Filter by the DIRECT participant the indirects ride (8 digits) - not to be confused with ispb, which is the indirect's own. OPTIONAL: omit it and every direct participant's indirects are listed, exactly as before. Named, only the indirects mounted on that participant come back; an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply, never a credential, and a token confined to one direct participant has to name it here. Sending it empty (directIspb=) reads the same as omitting it." examples: - "87654321" pattern: ^[0-9]{8}$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/IndirectPage" 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 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. WHICH DIRECT PARTICIPANT THE INDIRECT RIDES IS DECIDED HERE AND NEVER AGAIN. This deployment may act as several direct SPI participants, and an indirect reaches SPI through exactly ONE of them: `directIspb` names it, and the registry records that participant together with the Midaz organization and default ledger its `@pi` settlement account belongs to. Omit `directIspb` and the deployment's default participant is used, which is where every indirect lived before this deployment could act as several. An ISPB this deployment does not act as is 422 PIX-0128. The chosen participant, organization and ledger come back on the response as `directIspb`, `organizationId` and `ledgerId`, and PATCH cannot change them — an account exists in exactly one ledger, so re-pointing would orphan the position rather than move it. 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-0128 when directIspb names a direct participant this deployment does not act as; 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 "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 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. Optional directIspb names the direct participant the indirect is read as; a token confined to one direct participant has to name it. 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-0128 when directIspb names a direct participant this deployment does not act as, before the indirect is read; 404 PIX-0147 when directIspb names a direct participant the indirect is not mounted on; 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 - description: "The ISPB of the direct participant this indirect is addressed as - the one it rides. OPTIONAL: omit it and the indirect is addressed whichever participant it rides, exactly as before. Named, the indirect has to be mounted on that participant, or the answer is 404 PIX-0147 and nothing is read or changed; an ISPB this deployment does not act as is 422 PIX-0128, whether or not the indirect exists. It is ROUTING DATA you supply, never a credential, and a token confined to one direct participant has to name it here. Sending it empty (directIspb=) reads the same as omitting it." explode: false in: query name: directIspb schema: description: "The ISPB of the direct participant this indirect is addressed as - the one it rides. OPTIONAL: omit it and the indirect is addressed whichever participant it rides, exactly as before. Named, the indirect has to be mounted on that participant, or the answer is 404 PIX-0147 and nothing is read or changed; an ISPB this deployment does not act as is 422 PIX-0128, whether or not the indirect exists. It is ROUTING DATA you supply, never a credential, and a token confined to one direct participant has to name it here. Sending it empty (directIspb=) reads the same as omitting it." examples: - "87654321" pattern: ^[0-9]{8}$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/Indirect" 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 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. Optional directIspb names the direct participant the indirect is changed as, checked before anything is changed; a token confined to one direct participant has to name it. Refusals: 422 PIX-0128 when directIspb names a direct participant this deployment does not act as, before the indirect is read — nothing is changed; 404 PIX-0147 when directIspb names a direct participant the indirect is not mounted on — nothing is changed; 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 - description: "The ISPB of the direct participant this indirect is addressed as - the one it rides. OPTIONAL: omit it and the indirect is addressed whichever participant it rides, exactly as before. Named, the indirect has to be mounted on that participant, or the answer is 404 PIX-0147 and nothing is read or changed; an ISPB this deployment does not act as is 422 PIX-0128, whether or not the indirect exists. It is ROUTING DATA you supply, never a credential, and a token confined to one direct participant has to name it here. Sending it empty (directIspb=) reads the same as omitting it." explode: false in: query name: directIspb schema: description: "The ISPB of the direct participant this indirect is addressed as - the one it rides. OPTIONAL: omit it and the indirect is addressed whichever participant it rides, exactly as before. Named, the indirect has to be mounted on that participant, or the answer is 404 PIX-0147 and nothing is read or changed; an ISPB this deployment does not act as is 422 PIX-0128, whether or not the indirect exists. It is ROUTING DATA you supply, never a credential, and a token confined to one direct participant has to name it here. Sending it empty (directIspb=) reads the same as omitting it." examples: - "87654321" pattern: ^[0-9]{8}$ 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 "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 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. Optional directIspb names the direct participant the indirect is read as; a token confined to one direct participant has to name it. Refusals: 422 PIX-0128 when directIspb names a direct participant this deployment does not act as, before the indirect is read; 404 PIX-0147 when directIspb names a direct participant the indirect is not mounted on; 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 - description: "The ISPB of the direct participant this indirect is addressed as - the one it rides. OPTIONAL: omit it and the indirect is addressed whichever participant it rides, exactly as before. Named, the indirect has to be mounted on that participant, or the answer is 404 PIX-0147 and nothing is read or changed; an ISPB this deployment does not act as is 422 PIX-0128, whether or not the indirect exists. It is ROUTING DATA you supply, never a credential, and a token confined to one direct participant has to name it here. Sending it empty (directIspb=) reads the same as omitting it." explode: false in: query name: directIspb schema: description: "The ISPB of the direct participant this indirect is addressed as - the one it rides. OPTIONAL: omit it and the indirect is addressed whichever participant it rides, exactly as before. Named, the indirect has to be mounted on that participant, or the answer is 404 PIX-0147 and nothing is read or changed; an ISPB this deployment does not act as is 422 PIX-0128, whether or not the indirect exists. It is ROUTING DATA you supply, never a credential, and a token confined to one direct participant has to name it here. Sending it empty (directIspb=) reads the same as omitting it." examples: - "87654321" pattern: ^[0-9]{8}$ 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 "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 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 booked 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 booking — the payee block being the indirect's own client on a credit. **Reconcile on `status`, not on presence.** An inbound credit is booked `PENDING` the moment it is claimed and turns `EXECUTED` once the ledger credit landed, in the same row; a row can therefore appear `PENDING` in one sweep and `EXECUTED` in the next, and a row that stays `PENDING` is a credit that never landed (RUNBOOK §2.6). The feed does not hide claims, because it is ordered by booking time and a status filter would drop a row that settles after its booking instant has already been swept past. 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. Optional `directIspb` names the direct participant the indirect is read as; a token confined to one direct participant has to name it. 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-0128 when `directIspb` names a direct participant this deployment does not act as, before the indirect is read; 404 PIX-0147 when `directIspb` names a direct participant the indirect is not mounted on, and no movement is read; 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 - description: "The ISPB of the direct participant this indirect is read as - the one it rides. OPTIONAL: omit it and the indirect is read whichever participant it rides, exactly as before. Named, the indirect has to be mounted on that participant, or the answer is 404 PIX-0147 and nothing of it is returned; an ISPB this deployment does not act as is 422 PIX-0128, whether or not the indirect exists. It is ROUTING DATA you supply, never a credential, and a token confined to one direct participant has to name it here. Sending it empty (directIspb=) reads the same as omitting it." explode: false in: query name: directIspb schema: description: "The ISPB of the direct participant this indirect is read as - the one it rides. OPTIONAL: omit it and the indirect is read whichever participant it rides, exactly as before. Named, the indirect has to be mounted on that participant, or the answer is 404 PIX-0147 and nothing of it is returned; an ISPB this deployment does not act as is 422 PIX-0128, whether or not the indirect exists. It is ROUTING DATA you supply, never a credential, and a token confined to one direct participant has to name it here. Sending it empty (directIspb=) reads the same as omitting it." examples: - "87654321" pattern: ^[0-9]{8}$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/IndirectTransactionPage" 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 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, and one the ledger holds no account for (unbound, or absent from the ledger) is 422 PIX-0108, one held in a ledger that is not configured for Pix on that participant is 422 PIX-0137, one whose record does not say which ledger holds it is 422 PIX-0138, and one whose record names a different institution is 422 PIX-0139. Whose limits these are is decided by payer_ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, the account id is an alias that is unique only inside one of them, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. Read the headroom of the SAME participant you pay as. 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 - description: "The ISPB of the direct participant whose limits these are. This deployment may act as SEVERAL direct SPI participants — one ISPB each, each with its own books — and the account id is an alias that is unique only inside ONE of them, so this field is what says whose rows to read or write. OPTIONAL while it acts as a single participant: omit it and that one answers. REQUIRED once it acts as several — omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on an order: never a credential, never read from a header or a path, and it never widens what your token can reach. Use the SAME participant you pay as, or the headroom you read is not the headroom that gets enforced. Sending it empty (payer_ispb=) reads the same as omitting it." explode: false in: query name: payer_ispb schema: description: "The ISPB of the direct participant whose limits these are. This deployment may act as SEVERAL direct SPI participants — one ISPB each, each with its own books — and the account id is an alias that is unique only inside ONE of them, so this field is what says whose rows to read or write. OPTIONAL while it acts as a single participant: omit it and that one answers. REQUIRED once it acts as several — omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on an order: never a credential, never read from a header or a path, and it never widens what your token can reach. Use the SAME participant you pay as, or the headroom you read is not the headroom that gets enforced. Sending it empty (payer_ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/TransactionLimitsBody" 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 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. An accountId the CRM cannot resolve is 404 PIX-2016, and one the ledger holds no account for (unbound, or absent from the ledger) is 422 PIX-0108, one held in a ledger that is not configured for Pix on that participant is 422 PIX-0137, one whose record does not say which ledger holds it is 422 PIX-0138, and one whose record names a different institution is 422 PIX-0139. A new cap applies from the next POST /v1/transactions; there is no scheduling and no approval window. Which participant's row is changed is decided by payerIspb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, the accountId is an alias that is unique only inside one of them, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. A row of a participant you did not name is not reachable here. 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 "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 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), an account_id the CRM cannot resolve is 404 PIX-2016, and one the ledger holds no account for (unbound, or absent from the ledger) is 422 PIX-0108, one held in a ledger that is not configured for Pix on that participant is 422 PIX-0137, one whose record does not say which ledger holds it is 422 PIX-0138, and one whose record names a different institution is 422 PIX-0139. Whose limits these are is decided by payer_ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, the account id is an alias that is unique only inside one of them, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. Read the headroom of the SAME participant you pay as. 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 - description: "The ISPB of the direct participant whose limits these are. This deployment may act as SEVERAL direct SPI participants — one ISPB each, each with its own books — and the account id is an alias that is unique only inside ONE of them, so this field is what says whose rows to read or write. OPTIONAL while it acts as a single participant: omit it and that one answers. REQUIRED once it acts as several — omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on an order: never a credential, never read from a header or a path, and it never widens what your token can reach. Use the SAME participant you pay as, or the headroom you read is not the headroom that gets enforced. Sending it empty (payer_ispb=) reads the same as omitting it." explode: false in: query name: payer_ispb schema: description: "The ISPB of the direct participant whose limits these are. This deployment may act as SEVERAL direct SPI participants — one ISPB each, each with its own books — and the account id is an alias that is unique only inside ONE of them, so this field is what says whose rows to read or write. OPTIONAL while it acts as a single participant: omit it and that one answers. REQUIRED once it acts as several — omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on an order: never a credential, never read from a header or a path, and it never widens what your token can reach. Use the SAME participant you pay as, or the headroom you read is not the headroom that gets enforced. Sending it empty (payer_ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/AvailableLimitsResponse" 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 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/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 taxId 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: taxId 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 taxId 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 taxId is absent. examples: - "2026-04-01T00:00:00.000Z" type: string - description: "The ISPB of the direct participant this read is made as. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own JDPI credential - and a fraud marker names no row this deployment holds, so this field is the only thing that says which JD instance to ask. OPTIONAL while it acts as a single participant: omit it and that one answers. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payer_ispb on the limits routes: never a credential, never read from a header or a path, and it never widens what your token can reach. Read as the SAME participant that created the marker, or the JD you ask has never heard of it. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant this read is made as. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own JDPI credential - and a fraud marker names no row this deployment holds, so this field is the only thing that says which JD instance to ask. OPTIONAL while it acts as a single participant: omit it and that one answers. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payer_ispb on the limits routes: never a credential, never read from a header or a path, and it never widens what your token can reach. Read as the SAME participant that created the marker, or the JD you ask has never heard of it. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/FraudMarkerListBody" 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 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 parameters: - description: "Idempotency key for this write: any stable business string you choose, sent as the X-Idempotency request header - the same header, by the same name, that the Midaz ledger takes, so one integration sends one thing by one name. Send the SAME value again to retry safely: the plugin projects it deterministically into the GUID form JDPI requires (contract 6), so a repeat lands in the same JDPI dedup slot inside JD's 24h window and the operation is applied once. The raw value is never forwarded verbatim, so correlate JDPI-side logs with the projection rather than with what you sent. The header is REQUIRED: omitting it is refused 400 PIX-0061 before any JDPI call. BREAKING CHANGE: this value used to be the body field idempotencyKey, which no longer exists." in: header name: X-Idempotency required: true schema: description: "Idempotency key for this write: any stable business string you choose, sent as the X-Idempotency request header - the same header, by the same name, that the Midaz ledger takes, so one integration sends one thing by one name. Send the SAME value again to retry safely: the plugin projects it deterministically into the GUID form JDPI requires (contract 6), so a repeat lands in the same JDPI dedup slot inside JD's 24h window and the operation is applied once. The raw value is never forwarded verbatim, so correlate JDPI-side logs with the projection rather than with what you sent. The header is REQUIRED: omitting it is refused 400 PIX-0061 before any JDPI call. BREAKING CHANGE: this value used to be the body field idempotencyKey, which no longer exists." examples: - med-fraud-2024-0001 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/RegisterFraudMarkerRequestBody" required: true responses: "202": content: application/json: schema: $ref: "#/components/schemas/FraudMarkerView" description: Accepted "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 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). taxId is required; key and limit are optional filters. operationId: listMedFraudMarkersDict parameters: - description: The document to query (required for the DICT-direct listing). explode: false in: query name: taxId 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 taxId if given). explode: false in: query name: key schema: description: Optional key filter (must belong to taxId 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 - description: "The ISPB of the direct participant this read is made as. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own JDPI credential - and a fraud marker names no row this deployment holds, so this field is the only thing that says which JD instance to ask. OPTIONAL while it acts as a single participant: omit it and that one answers. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payer_ispb on the limits routes: never a credential, never read from a header or a path, and it never widens what your token can reach. Read as the SAME participant that created the marker, or the JD you ask has never heard of it. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant this read is made as. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own JDPI credential - and a fraud marker names no row this deployment holds, so this field is the only thing that says which JD instance to ask. OPTIONAL while it acts as a single participant: omit it and that one answers. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payer_ispb on the limits routes: never a credential, never read from a header or a path, and it never widens what your token can reach. Read as the SAME participant that created the marker, or the JD you ask has never heard of it. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/FraudMarkerListBody" 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 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 - description: "The ISPB of the direct participant this read is made as. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own JDPI credential - and a fraud marker names no row this deployment holds, so this field is the only thing that says which JD instance to ask. OPTIONAL while it acts as a single participant: omit it and that one answers. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payer_ispb on the limits routes: never a credential, never read from a header or a path, and it never widens what your token can reach. Read as the SAME participant that created the marker, or the JD you ask has never heard of it. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant this read is made as. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own JDPI credential - and a fraud marker names no row this deployment holds, so this field is the only thing that says which JD instance to ask. OPTIONAL while it acts as a single participant: omit it and that one answers. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payer_ispb on the limits routes: never a credential, never read from a header or a path, and it never widens what your token can reach. Read as the SAME participant that created the marker, or the JD you ask has never heard of it. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/FraudMarkerView" 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 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 - description: "Idempotency key for this write: any stable business string you choose, sent as the X-Idempotency request header - the same header, by the same name, that the Midaz ledger takes, so one integration sends one thing by one name. Send the SAME value again to retry safely: the plugin projects it deterministically into the GUID form JDPI requires (contract 6), so a repeat lands in the same JDPI dedup slot inside JD's 24h window and the operation is applied once. The raw value is never forwarded verbatim, so correlate JDPI-side logs with the projection rather than with what you sent. The header is REQUIRED: omitting it is refused 400 PIX-0061 before any JDPI call. BREAKING CHANGE: this value used to be the body field idempotencyKey, which no longer exists." in: header name: X-Idempotency required: true schema: description: "Idempotency key for this write: any stable business string you choose, sent as the X-Idempotency request header - the same header, by the same name, that the Midaz ledger takes, so one integration sends one thing by one name. Send the SAME value again to retry safely: the plugin projects it deterministically into the GUID form JDPI requires (contract 6), so a repeat lands in the same JDPI dedup slot inside JD's 24h window and the operation is applied once. The raw value is never forwarded verbatim, so correlate JDPI-side logs with the projection rather than with what you sent. The header is REQUIRED: omitting it is refused 400 PIX-0061 before any JDPI call. BREAKING CHANGE: this value used to be the body field idempotencyKey, which no longer exists." examples: - med-fraud-cancel-2024-0001 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 "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 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. The role ISPBs name the DIRECT participant, and the indirect participants riding it share its infractions; indirectId narrows the listing to ONE indirect — only the infractions over a payment this deployment recorded for that indirect (the payment's own indirectId, as GET /v1/transactions?indirectId= reads it), never another indirect's, never one over the direct participant's own payment, and never one over a payment this deployment did not book. A token confined to one indirect has to name it. A malformed indirectId is 400 PIX-0061; an empty match is a 200 with an empty data array. 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: counterpartIspb 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: creatorIspb 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 - description: "The registered indirect participant (UUID) whose infractions are listed. OPTIONAL: omit it and the listing is not narrowed by indirect. Named, only the infractions over a payment this deployment recorded for that indirect come back - never another indirect's, never one over a payment of the direct participant itself, and never one over a payment this deployment did not book. A token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061." explode: false in: query name: indirectId schema: description: "The registered indirect participant (UUID) whose infractions are listed. OPTIONAL: omit it and the listing is not narrowed by indirect. Named, only the infractions over a payment this deployment recorded for that indirect come back - never another indirect's, never one over a payment of the direct participant itself, and never one over a payment this deployment did not book. A token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061." examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/InfractionListBody" 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 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. Optional ispb names the direct participant the request acts for: named, the record has to be one that participant is a party to, or the answer is 404 PIX-0147 before anything is read from JDPI or changed; an ISPB this deployment does not act as is 422 PIX-0128 before any record is read; a token confined to one participant has to name it. Optional indirectId names the registered indirect participant the request acts for: named, the infraction has to be over a payment this deployment recorded for that indirect — the rule GET /v1/med/infractions?indirectId= lists by — or the answer is 404 PIX-0147 before anything is read from JDPI or changed; a token confined to one indirect has to name it; a malformed indirectId is 400 PIX-0061." 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 - description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the record has to be one that participant is a party to - either side of a dispute, the creator of a value recovery, the participant a refund credit was booked for - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed. A record this deployment does not hold is 404 PIX-0147 too when an ispb is named. An ISPB this deployment does not act as is 422 PIX-0128, before any record is read. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the record has to be one that participant is a party to - either side of a dispute, the creator of a value recovery, the participant a refund credit was booked for - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed. A record this deployment does not hold is 404 PIX-0147 too when an ispb is named. An ISPB this deployment does not act as is 422 PIX-0128, before any record is read. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string - description: "The registered indirect participant (UUID) this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the infraction has to be over a payment this deployment recorded for that indirect - the rule GET /v1/med/infractions?indirectId= lists by - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed; an infraction this deployment does not hold is 404 PIX-0147 too when an indirectId is named. It is ROUTING DATA you supply, never a credential, and a token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061. Sending it empty (indirectId=) reads the same as omitting it." explode: false in: query name: indirectId schema: description: "The registered indirect participant (UUID) this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the infraction has to be over a payment this deployment recorded for that indirect - the rule GET /v1/med/infractions?indirectId= lists by - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed; an infraction this deployment does not hold is 404 PIX-0147 too when an indirectId is named. It is ROUTING DATA you supply, never a credential, and a token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061. Sending it empty (indirectId=) reads the same as omitting it." examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/InfractionView" 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 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 (analysisResult {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. Optional ispb names the direct participant the request acts for: named, the record has to be one that participant is a party to, or the answer is 404 PIX-0147 before anything is read from JDPI or changed; an ISPB this deployment does not act as is 422 PIX-0128 before any record is read; a token confined to one participant has to name it. Optional indirectId names the registered indirect participant the request acts for: named, the infraction has to be over a payment this deployment recorded for that indirect — the rule GET /v1/med/infractions?indirectId= lists by — or the answer is 404 PIX-0147 before anything is read from JDPI or changed; a token confined to one indirect has to name it; a malformed indirectId is 400 PIX-0061." 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 - description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the record has to be one that participant is a party to - either side of a dispute, the creator of a value recovery, the participant a refund credit was booked for - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed. A record this deployment does not hold is 404 PIX-0147 too when an ispb is named. An ISPB this deployment does not act as is 422 PIX-0128, before any record is read. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the record has to be one that participant is a party to - either side of a dispute, the creator of a value recovery, the participant a refund credit was booked for - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed. A record this deployment does not hold is 404 PIX-0147 too when an ispb is named. An ISPB this deployment does not act as is 422 PIX-0128, before any record is read. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string - description: "The registered indirect participant (UUID) this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the infraction has to be over a payment this deployment recorded for that indirect - the rule GET /v1/med/infractions?indirectId= lists by - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed; an infraction this deployment does not hold is 404 PIX-0147 too when an indirectId is named. It is ROUTING DATA you supply, never a credential, and a token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061. Sending it empty (indirectId=) reads the same as omitting it." explode: false in: query name: indirectId schema: description: "The registered indirect participant (UUID) this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the infraction has to be over a payment this deployment recorded for that indirect - the rule GET /v1/med/infractions?indirectId= lists by - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed; an infraction this deployment does not hold is 404 PIX-0147 too when an indirectId is named. It is ROUTING DATA you supply, never a credential, and a token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061. Sending it empty (indirectId=) reads the same as omitting it." examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string - description: "Idempotency key for this write: any stable business string you choose, sent as the X-Idempotency request header - the same header, by the same name, that the Midaz ledger takes, so one integration sends one thing by one name. Send the SAME value again to retry safely: the plugin projects it deterministically into the GUID form JDPI requires (contract 6), so a repeat lands in the same JDPI dedup slot inside JD's 24h window and the operation is applied once. The raw value is never forwarded verbatim, so correlate JDPI-side logs with the projection rather than with what you sent. The header is REQUIRED: omitting it is refused 400 PIX-0061 before any JDPI call. BREAKING CHANGE: this value used to be the body field idempotencyKey, which no longer exists." in: header name: X-Idempotency required: true schema: description: "Idempotency key for this write: any stable business string you choose, sent as the X-Idempotency request header - the same header, by the same name, that the Midaz ledger takes, so one integration sends one thing by one name. Send the SAME value again to retry safely: the plugin projects it deterministically into the GUID form JDPI requires (contract 6), so a repeat lands in the same JDPI dedup slot inside JD's 24h window and the operation is applied once. The raw value is never forwarded verbatim, so correlate JDPI-side logs with the projection rather than with what you sent. The header is REQUIRED: omitting it is refused 400 PIX-0061 before any JDPI call. BREAKING CHANGE: this value used to be the body field idempotencyKey, which no longer exists." examples: - med-infraction-analyze-2024-0001 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 "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 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. Optional ispb names the direct participant the request acts for: named, the record has to be one that participant is a party to, or the answer is 404 PIX-0147 before anything is read from JDPI or changed; an ISPB this deployment does not act as is 422 PIX-0128 before any record is read; a token confined to one participant has to name it. Optional indirectId names the registered indirect participant the request acts for: named, the infraction has to be over a payment this deployment recorded for that indirect — the rule GET /v1/med/infractions?indirectId= lists by — or the answer is 404 PIX-0147 before anything is read from JDPI or changed; a token confined to one indirect has to name it; a malformed indirectId is 400 PIX-0061." 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 - description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the record has to be one that participant is a party to - either side of a dispute, the creator of a value recovery, the participant a refund credit was booked for - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed. A record this deployment does not hold is 404 PIX-0147 too when an ispb is named. An ISPB this deployment does not act as is 422 PIX-0128, before any record is read. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the record has to be one that participant is a party to - either side of a dispute, the creator of a value recovery, the participant a refund credit was booked for - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed. A record this deployment does not hold is 404 PIX-0147 too when an ispb is named. An ISPB this deployment does not act as is 422 PIX-0128, before any record is read. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string - description: "The registered indirect participant (UUID) this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the infraction has to be over a payment this deployment recorded for that indirect - the rule GET /v1/med/infractions?indirectId= lists by - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed; an infraction this deployment does not hold is 404 PIX-0147 too when an indirectId is named. It is ROUTING DATA you supply, never a credential, and a token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061. Sending it empty (indirectId=) reads the same as omitting it." explode: false in: query name: indirectId schema: description: "The registered indirect participant (UUID) this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the infraction has to be over a payment this deployment recorded for that indirect - the rule GET /v1/med/infractions?indirectId= lists by - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed; an infraction this deployment does not hold is 404 PIX-0147 too when an indirectId is named. It is ROUTING DATA you supply, never a credential, and a token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061. Sending it empty (indirectId=) reads the same as omitting it." examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string - description: "Idempotency key for this write: any stable business string you choose, sent as the X-Idempotency request header - the same header, by the same name, that the Midaz ledger takes, so one integration sends one thing by one name. Send the SAME value again to retry safely: the plugin projects it deterministically into the GUID form JDPI requires (contract 6), so a repeat lands in the same JDPI dedup slot inside JD's 24h window and the operation is applied once. The raw value is never forwarded verbatim, so correlate JDPI-side logs with the projection rather than with what you sent. The header is REQUIRED: omitting it is refused 400 PIX-0061 before any JDPI call. BREAKING CHANGE: this value used to be the body field idempotencyKey, which no longer exists." in: header name: X-Idempotency required: true schema: description: "Idempotency key for this write: any stable business string you choose, sent as the X-Idempotency request header - the same header, by the same name, that the Midaz ledger takes, so one integration sends one thing by one name. Send the SAME value again to retry safely: the plugin projects it deterministically into the GUID form JDPI requires (contract 6), so a repeat lands in the same JDPI dedup slot inside JD's 24h window and the operation is applied once. The raw value is never forwarded verbatim, so correlate JDPI-side logs with the projection rather than with what you sent. The header is REQUIRED: omitting it is refused 400 PIX-0061 before any JDPI call. BREAKING CHANGE: this value used to be the body field idempotencyKey, which no longer exists." examples: - med-infraction-cancel-2024-0001 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/InfractionView" 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 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. Optional ispb names the direct participant the request acts for: named, the record has to be one that participant is a party to, or the answer is 404 PIX-0147 before anything is read from JDPI or changed; an ISPB this deployment does not act as is 422 PIX-0128 before any record is read; a token confined to one participant has to name it. Optional indirectId names the registered indirect participant the request acts for: named, the infraction has to be over a payment this deployment recorded for that indirect — the rule GET /v1/med/infractions?indirectId= lists by — or the answer is 404 PIX-0147 before anything is read from JDPI or changed; a token confined to one indirect has to name it; a malformed indirectId is 400 PIX-0061." 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 - description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the record has to be one that participant is a party to - either side of a dispute, the creator of a value recovery, the participant a refund credit was booked for - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed. A record this deployment does not hold is 404 PIX-0147 too when an ispb is named. An ISPB this deployment does not act as is 422 PIX-0128, before any record is read. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the record has to be one that participant is a party to - either side of a dispute, the creator of a value recovery, the participant a refund credit was booked for - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed. A record this deployment does not hold is 404 PIX-0147 too when an ispb is named. An ISPB this deployment does not act as is 422 PIX-0128, before any record is read. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string - description: "The registered indirect participant (UUID) this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the infraction has to be over a payment this deployment recorded for that indirect - the rule GET /v1/med/infractions?indirectId= lists by - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed; an infraction this deployment does not hold is 404 PIX-0147 too when an indirectId is named. It is ROUTING DATA you supply, never a credential, and a token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061. Sending it empty (indirectId=) reads the same as omitting it." explode: false in: query name: indirectId schema: description: "The registered indirect participant (UUID) this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the infraction has to be over a payment this deployment recorded for that indirect - the rule GET /v1/med/infractions?indirectId= lists by - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed; an infraction this deployment does not hold is 404 PIX-0147 too when an indirectId is named. It is ROUTING DATA you supply, never a credential, and a token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061. Sending it empty (indirectId=) reads the same as omitting it." examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/InfractionView" 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 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 parameters: - description: "Idempotency key for this write: any stable business string you choose, sent as the X-Idempotency request header - the same header, by the same name, that the Midaz ledger takes, so one integration sends one thing by one name. Send the SAME value again to retry safely: the plugin projects it deterministically into the GUID form JDPI requires (contract 6), so a repeat lands in the same JDPI dedup slot inside JD's 24h window and the operation is applied once. The raw value is never forwarded verbatim, so correlate JDPI-side logs with the projection rather than with what you sent. The header is REQUIRED: omitting it is refused 400 PIX-0061 before any JDPI call. BREAKING CHANGE: this value used to be the body field idempotencyKey, which no longer exists." in: header name: X-Idempotency required: true schema: description: "Idempotency key for this write: any stable business string you choose, sent as the X-Idempotency request header - the same header, by the same name, that the Midaz ledger takes, so one integration sends one thing by one name. Send the SAME value again to retry safely: the plugin projects it deterministically into the GUID form JDPI requires (contract 6), so a repeat lands in the same JDPI dedup slot inside JD's 24h window and the operation is applied once. The raw value is never forwarded verbatim, so correlate JDPI-side logs with the projection rather than with what you sent. The header is REQUIRED: omitting it is refused 400 PIX-0061 before any JDPI call. BREAKING CHANGE: this value used to be the body field idempotencyKey, which no longer exists." examples: - med-recovery-2024-0001 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateRecoveryRequestBody" required: true responses: "202": content: application/json: schema: $ref: "#/components/schemas/RecoveryView" description: Accepted "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 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-return: get: description: Lists the creator-side analyzed value recoveries this institution may still return (contract §2.22/§5, within 72h of the analysis stage closing), ordered by return deadline (earliest first). The creator ISPB is config-derived. Each row surfaces returnDeadline and a computed breached flag. Read projection — no JDPI round-trip; no action taken and no money moved. Optional ispb narrows the queue to that one direct participant (an ISPB this deployment does not act as is 422 PIX-0128); a token confined to one participant has to name it. The role and queue ISPBs name the DIRECT participant, and the indirect participants riding it share its value recoveries; indirectId narrows the listing to ONE indirect — only the value recoveries over a payment this deployment recorded for that indirect (the payment's own indirectId, as GET /v1/transactions?indirectId= reads it), never another indirect's, never one over the direct participant's own payment, and never one over a payment this deployment did not book. A token confined to one indirect has to name it. A malformed indirectId is 400 PIX-0061; an empty match is a 200 with an empty data array. operationId: listMedRecoveriesAwaitingReturn 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 - description: "The ISPB of the direct participant whose queue is listed. OPTIONAL: omit it and every participant of this deployment is listed, exactly as before. Named, only that participant's rows come back, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant whose queue is listed. OPTIONAL: omit it and every participant of this deployment is listed, exactly as before. Named, only that participant's rows come back, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string - description: "The registered indirect participant (UUID) whose recoveries are listed. OPTIONAL: omit it and the listing is not narrowed by indirect. Named, only the recoveries over a payment this deployment recorded for that indirect come back - never another indirect's, never one over a payment of the direct participant itself, and never one over a payment this deployment did not book. A token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061." explode: false in: query name: indirectId schema: description: "The registered indirect participant (UUID) whose recoveries are listed. OPTIONAL: omit it and the listing is not narrowed by indirect. Named, only the recoveries over a payment this deployment recorded for that indirect come back - never another indirect's, never one over a payment of the direct participant itself, and never one over a payment this deployment did not book. A token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061." examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RecoveryListBody" 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 default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: List MED recoveries awaiting return tags: - MED Recoveries x-mint: href: /en/reference/interfaces/pix-jd/list-med-recoveries-awaiting-return /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. Optional ispb names the direct participant the request acts for: named, the record has to be one that participant is a party to, or the answer is 404 PIX-0147 before anything is read from JDPI or changed; an ISPB this deployment does not act as is 422 PIX-0128 before any record is read; a token confined to one participant has to name it. Optional indirectId names the registered indirect participant the request acts for: named, the value recovery has to be over a root payment this deployment recorded for that indirect — the rule GET /v1/med/recoveries/awaiting-return?indirectId= lists by — or the answer is 404 PIX-0147 before anything is read from JDPI or changed; a token confined to one indirect has to name it; a malformed indirectId is 400 PIX-0061." 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 - description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the record has to be one that participant is a party to - either side of a dispute, the creator of a value recovery, the participant a refund credit was booked for - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed. A record this deployment does not hold is 404 PIX-0147 too when an ispb is named. An ISPB this deployment does not act as is 422 PIX-0128, before any record is read. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the record has to be one that participant is a party to - either side of a dispute, the creator of a value recovery, the participant a refund credit was booked for - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed. A record this deployment does not hold is 404 PIX-0147 too when an ispb is named. An ISPB this deployment does not act as is 422 PIX-0128, before any record is read. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string - description: "The registered indirect participant (UUID) this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the value recovery has to be over a root payment this deployment recorded for that indirect - the rule GET /v1/med/recoveries/awaiting-return?indirectId= lists by - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed; a record this deployment does not hold is 404 PIX-0147 too when an indirectId is named. It is ROUTING DATA you supply, never a credential, and a token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061. Sending it empty (indirectId=) reads the same as omitting it." explode: false in: query name: indirectId schema: description: "The registered indirect participant (UUID) this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the value recovery has to be over a root payment this deployment recorded for that indirect - the rule GET /v1/med/recoveries/awaiting-return?indirectId= lists by - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed; a record this deployment does not hold is 404 PIX-0147 too when an indirectId is named. It is ROUTING DATA you supply, never a credential, and a token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061. Sending it empty (indirectId=) reads the same as omitting it." examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RecoveryView" 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 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. Optional ispb names the direct participant the request acts for: named, the record has to be one that participant is a party to, or the answer is 404 PIX-0147 before anything is read from JDPI or changed; an ISPB this deployment does not act as is 422 PIX-0128 before any record is read; a token confined to one participant has to name it. Optional indirectId names the registered indirect participant the request acts for: named, the value recovery has to be over a root payment this deployment recorded for that indirect — the rule GET /v1/med/recoveries/awaiting-return?indirectId= lists by — or the answer is 404 PIX-0147 before anything is read from JDPI or changed; a token confined to one indirect has to name it; a malformed indirectId is 400 PIX-0061." 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 - description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the record has to be one that participant is a party to - either side of a dispute, the creator of a value recovery, the participant a refund credit was booked for - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed. A record this deployment does not hold is 404 PIX-0147 too when an ispb is named. An ISPB this deployment does not act as is 422 PIX-0128, before any record is read. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the record has to be one that participant is a party to - either side of a dispute, the creator of a value recovery, the participant a refund credit was booked for - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed. A record this deployment does not hold is 404 PIX-0147 too when an ispb is named. An ISPB this deployment does not act as is 422 PIX-0128, before any record is read. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string - description: "The registered indirect participant (UUID) this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the value recovery has to be over a root payment this deployment recorded for that indirect - the rule GET /v1/med/recoveries/awaiting-return?indirectId= lists by - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed; a record this deployment does not hold is 404 PIX-0147 too when an indirectId is named. It is ROUTING DATA you supply, never a credential, and a token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061. Sending it empty (indirectId=) reads the same as omitting it." explode: false in: query name: indirectId schema: description: "The registered indirect participant (UUID) this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the value recovery has to be over a root payment this deployment recorded for that indirect - the rule GET /v1/med/recoveries/awaiting-return?indirectId= lists by - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed; a record this deployment does not hold is 404 PIX-0147 too when an indirectId is named. It is ROUTING DATA you supply, never a credential, and a token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061. Sending it empty (indirectId=) reads the same as omitting it." examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string - description: "Idempotency key for this write: any stable business string you choose, sent as the X-Idempotency request header - the same header, by the same name, that the Midaz ledger takes, so one integration sends one thing by one name. Send the SAME value again to retry safely: the plugin projects it deterministically into the GUID form JDPI requires (contract 6), so a repeat lands in the same JDPI dedup slot inside JD's 24h window and the operation is applied once. The raw value is never forwarded verbatim, so correlate JDPI-side logs with the projection rather than with what you sent. The header is REQUIRED: omitting it is refused 400 PIX-0061 before any JDPI call. BREAKING CHANGE: this value used to be the body field idempotencyKey, which no longer exists." in: header name: X-Idempotency required: true schema: description: "Idempotency key for this write: any stable business string you choose, sent as the X-Idempotency request header - the same header, by the same name, that the Midaz ledger takes, so one integration sends one thing by one name. Send the SAME value again to retry safely: the plugin projects it deterministically into the GUID form JDPI requires (contract 6), so a repeat lands in the same JDPI dedup slot inside JD's 24h window and the operation is applied once. The raw value is never forwarded verbatim, so correlate JDPI-side logs with the projection rather than with what you sent. The header is REQUIRED: omitting it is refused 400 PIX-0061 before any JDPI call. BREAKING CHANGE: this value used to be the body field idempotencyKey, which no longer exists." examples: - med-amend-2024-0001 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 "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 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}/return: 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. Optional ispb names the direct participant the request acts for: named, the record has to be one that participant is a party to, or the answer is 404 PIX-0147 before anything is read from JDPI or changed; an ISPB this deployment does not act as is 422 PIX-0128 before any record is read; a token confined to one participant has to name it. Optional indirectId names the registered indirect participant the request acts for: named, the value recovery has to be over a root payment this deployment recorded for that indirect — the rule GET /v1/med/recoveries/awaiting-return?indirectId= lists by — or the answer is 404 PIX-0147 before anything is read from JDPI or changed; a token confined to one indirect has to name it; a malformed indirectId is 400 PIX-0061." operationId: returnMedRecovery 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 - description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the record has to be one that participant is a party to - either side of a dispute, the creator of a value recovery, the participant a refund credit was booked for - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed. A record this deployment does not hold is 404 PIX-0147 too when an ispb is named. An ISPB this deployment does not act as is 422 PIX-0128, before any record is read. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the record has to be one that participant is a party to - either side of a dispute, the creator of a value recovery, the participant a refund credit was booked for - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed. A record this deployment does not hold is 404 PIX-0147 too when an ispb is named. An ISPB this deployment does not act as is 422 PIX-0128, before any record is read. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string - description: "The registered indirect participant (UUID) this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the value recovery has to be over a root payment this deployment recorded for that indirect - the rule GET /v1/med/recoveries/awaiting-return?indirectId= lists by - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed; a record this deployment does not hold is 404 PIX-0147 too when an indirectId is named. It is ROUTING DATA you supply, never a credential, and a token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061. Sending it empty (indirectId=) reads the same as omitting it." explode: false in: query name: indirectId schema: description: "The registered indirect participant (UUID) this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the value recovery has to be over a root payment this deployment recorded for that indirect - the rule GET /v1/med/recoveries/awaiting-return?indirectId= lists by - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed; a record this deployment does not hold is 404 PIX-0147 too when an indirectId is named. It is ROUTING DATA you supply, never a credential, and a token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061. Sending it empty (indirectId=) reads the same as omitting it." examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string - description: "Idempotency key for this write: any stable business string you choose, sent as the X-Idempotency request header - the same header, by the same name, that the Midaz ledger takes, so one integration sends one thing by one name. Send the SAME value again to retry safely: the plugin projects it deterministically into the GUID form JDPI requires (contract 6), so a repeat lands in the same JDPI dedup slot inside JD's 24h window and the operation is applied once. The raw value is never forwarded verbatim, so correlate JDPI-side logs with the projection rather than with what you sent. The header is REQUIRED: omitting it is refused 400 PIX-0061 before any JDPI call. BREAKING CHANGE: this value used to be the body field idempotencyKey, which no longer exists." in: header name: X-Idempotency required: true schema: description: "Idempotency key for this write: any stable business string you choose, sent as the X-Idempotency request header - the same header, by the same name, that the Midaz ledger takes, so one integration sends one thing by one name. Send the SAME value again to retry safely: the plugin projects it deterministically into the GUID form JDPI requires (contract 6), so a repeat lands in the same JDPI dedup slot inside JD's 24h window and the operation is applied once. The raw value is never forwarded verbatim, so correlate JDPI-side logs with the projection rather than with what you sent. The header is REQUIRED: omitting it is refused 400 PIX-0061 before any JDPI call. BREAKING CHANGE: this value used to be the body field idempotencyKey, which no longer exists." examples: - med-devolver-2024-0001 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RecoveryView" 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 default: content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Error summary: Start a MED value recovery return stage tags: - MED Recoveries x-mint: href: /en/reference/interfaces/pix-jd/start-a-med-value-recovery-return-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. The role and queue ISPBs name the DIRECT participant, and the indirect participants riding it share its refund requests; indirectId narrows the listing to ONE indirect — only the refund requests over a payment this deployment recorded for that indirect (the payment's own indirectId, as GET /v1/transactions?indirectId= reads it), never another indirect's, never one over the direct participant's own payment, and never one over a payment this deployment did not book. A token confined to one indirect has to name it. A malformed indirectId is 400 PIX-0061; an empty match is a 200 with an empty data array. operationId: listMedRefunds parameters: - description: Filter on stSolDevolucao (0=open, 1=cancelled, 2=analyzed). explode: false in: query name: status schema: description: Filter on stSolDevolucao (0=open, 1=cancelled, 2=analyzed). examples: - "0" type: string - description: Filter on the contested ISPB (refunds requested against this institution). explode: false in: query name: contestedIspb 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: requesterIspb 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 - description: "The registered indirect participant (UUID) whose refund requests are listed. OPTIONAL: omit it and the listing is not narrowed by indirect. Named, only the refund requests over a payment this deployment recorded for that indirect come back - never another indirect's, never one over a payment of the direct participant itself, and never one over a payment this deployment did not book. A token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061." explode: false in: query name: indirectId schema: description: "The registered indirect participant (UUID) whose refund requests are listed. OPTIONAL: omit it and the listing is not narrowed by indirect. Named, only the refund requests over a payment this deployment recorded for that indirect come back - never another indirect's, never one over a payment of the direct participant itself, and never one over a payment this deployment did not book. A token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061." examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RefundRequestListBody" 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 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 requesting PSP (JDPI devolucao/incluir, contract 2.7). The requesting ISPB is derived from configuration. Persists the JDPI response entity and returns it. operationId: solicitMedRefund parameters: - description: "Idempotency key for this write: any stable business string you choose, sent as the X-Idempotency request header - the same header, by the same name, that the Midaz ledger takes, so one integration sends one thing by one name. Send the SAME value again to retry safely: the plugin projects it deterministically into the GUID form JDPI requires (contract 6), so a repeat lands in the same JDPI dedup slot inside JD's 24h window and the operation is applied once. The raw value is never forwarded verbatim, so correlate JDPI-side logs with the projection rather than with what you sent. The header is REQUIRED: omitting it is refused 400 PIX-0061 before any JDPI call. BREAKING CHANGE: this value used to be the body field idempotencyKey, which no longer exists." in: header name: X-Idempotency required: true schema: description: "Idempotency key for this write: any stable business string you choose, sent as the X-Idempotency request header - the same header, by the same name, that the Midaz ledger takes, so one integration sends one thing by one name. Send the SAME value again to retry safely: the plugin projects it deterministically into the GUID form JDPI requires (contract 6), so a repeat lands in the same JDPI dedup slot inside JD's 24h window and the operation is applied once. The raw value is never forwarded verbatim, so correlate JDPI-side logs with the projection rather than with what you sent. The header is REQUIRED: omitting it is refused 400 PIX-0061 before any JDPI call. BREAKING CHANGE: this value used to be the body field idempotencyKey, which no longer exists." examples: - med-refund-2024-0001 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/SolicitRefundRequestBody" required: true responses: "202": content: application/json: schema: $ref: "#/components/schemas/RefundRequestView" description: Accepted "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 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. Optional ispb names the direct participant the request acts for: named, the record has to be one that participant is a party to, or the answer is 404 PIX-0147 before anything is read from JDPI or changed; an ISPB this deployment does not act as is 422 PIX-0128 before any record is read; a token confined to one participant has to name it. Optional indirectId names the registered indirect participant the request acts for: named, the refund credit has to be booked against a payment this deployment recorded for that indirect, or the answer is 404 PIX-0147 before anything is read from JDPI; a token confined to one indirect has to name it; a malformed indirectId is 400 PIX-0061." 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 - description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the record has to be one that participant is a party to - either side of a dispute, the creator of a value recovery, the participant a refund credit was booked for - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed. A record this deployment does not hold is 404 PIX-0147 too when an ispb is named. An ISPB this deployment does not act as is 422 PIX-0128, before any record is read. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the record has to be one that participant is a party to - either side of a dispute, the creator of a value recovery, the participant a refund credit was booked for - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed. A record this deployment does not hold is 404 PIX-0147 too when an ispb is named. An ISPB this deployment does not act as is 422 PIX-0128, before any record is read. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string - description: "The registered indirect participant (UUID) this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the refund credit has to be booked against a payment this deployment recorded for that indirect - the payment's own indirectId, as GET /v1/transactions?indirectId= reads it - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed; a record this deployment does not hold is 404 PIX-0147 too when an indirectId is named. It is ROUTING DATA you supply, never a credential, and a token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061. Sending it empty (indirectId=) reads the same as omitting it." explode: false in: query name: indirectId schema: description: "The registered indirect participant (UUID) this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the refund credit has to be booked against a payment this deployment recorded for that indirect - the payment's own indirectId, as GET /v1/transactions?indirectId= reads it - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed; a record this deployment does not hold is 404 PIX-0147 too when an indirectId is named. It is ROUTING DATA you supply, never a credential, and a token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061. Sending it empty (indirectId=) reads the same as omitting it." examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RefundCreditStatusView" 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 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 for fraud / 48h otherwise) and a computed breached flag. Read projection — no JDPI round-trip. Optional ispb narrows the queue to that one direct participant (an ISPB this deployment does not act as is 422 PIX-0128); a token confined to one participant has to name it. The role and queue ISPBs name the DIRECT participant, and the indirect participants riding it share its refund requests; indirectId narrows the listing to ONE indirect — only the refund requests over a payment this deployment recorded for that indirect (the payment's own indirectId, as GET /v1/transactions?indirectId= reads it), never another indirect's, never one over the direct participant's own payment, and never one over a payment this deployment did not book. A token confined to one indirect has to name it. A malformed indirectId is 400 PIX-0061; an empty match is a 200 with an empty data array. 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 - description: "The ISPB of the direct participant whose queue is listed. OPTIONAL: omit it and every participant of this deployment is listed, exactly as before. Named, only that participant's rows come back, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant whose queue is listed. OPTIONAL: omit it and every participant of this deployment is listed, exactly as before. Named, only that participant's rows come back, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string - description: "The registered indirect participant (UUID) whose refund requests are listed. OPTIONAL: omit it and the listing is not narrowed by indirect. Named, only the refund requests over a payment this deployment recorded for that indirect come back - never another indirect's, never one over a payment of the direct participant itself, and never one over a payment this deployment did not book. A token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061." explode: false in: query name: indirectId schema: description: "The registered indirect participant (UUID) whose refund requests are listed. OPTIONAL: omit it and the listing is not narrowed by indirect. Named, only the refund requests over a payment this deployment recorded for that indirect come back - never another indirect's, never one over a payment of the direct participant itself, and never one over a payment this deployment did not book. A token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061." examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RefundRequestListBody" 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 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. Optional ispb names the direct participant the request acts for: named, the record has to be one that participant is a party to, or the answer is 404 PIX-0147 before anything is read from JDPI or changed; an ISPB this deployment does not act as is 422 PIX-0128 before any record is read; a token confined to one participant has to name it. Optional indirectId names the registered indirect participant the request acts for: named, the refund request has to be over a payment this deployment recorded for that indirect — the rule GET /v1/med/refunds?indirectId= lists by — or the answer is 404 PIX-0147 before anything is read from JDPI or changed; a token confined to one indirect has to name it; a malformed indirectId is 400 PIX-0061." 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 - description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the record has to be one that participant is a party to - either side of a dispute, the creator of a value recovery, the participant a refund credit was booked for - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed. A record this deployment does not hold is 404 PIX-0147 too when an ispb is named. An ISPB this deployment does not act as is 422 PIX-0128, before any record is read. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the record has to be one that participant is a party to - either side of a dispute, the creator of a value recovery, the participant a refund credit was booked for - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed. A record this deployment does not hold is 404 PIX-0147 too when an ispb is named. An ISPB this deployment does not act as is 422 PIX-0128, before any record is read. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string - description: "The registered indirect participant (UUID) this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the refund request has to be over a payment this deployment recorded for that indirect - the rule GET /v1/med/refunds?indirectId= lists by - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed; a record this deployment does not hold is 404 PIX-0147 too when an indirectId is named. It is ROUTING DATA you supply, never a credential, and a token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061. Sending it empty (indirectId=) reads the same as omitting it." explode: false in: query name: indirectId schema: description: "The registered indirect participant (UUID) this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the refund request has to be over a payment this deployment recorded for that indirect - the rule GET /v1/med/refunds?indirectId= lists by - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed; a record this deployment does not hold is 404 PIX-0147 too when an indirectId is named. It is ROUTING DATA you supply, never a credential, and a token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061. Sending it empty (indirectId=) reads the same as omitting it." examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RefundRequestView" 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 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 contested 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. Optional ispb names the direct participant the request acts for: named, the record has to be one that participant is a party to, or the answer is 404 PIX-0147 before anything is read from JDPI or changed; an ISPB this deployment does not act as is 422 PIX-0128 before any record is read; a token confined to one participant has to name it. Optional indirectId names the registered indirect participant the request acts for: named, the refund request has to be over a payment this deployment recorded for that indirect — the rule GET /v1/med/refunds?indirectId= lists by — or the answer is 404 PIX-0147 before anything is read from JDPI or changed; a token confined to one indirect has to name it; a malformed indirectId is 400 PIX-0061." 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 - description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the record has to be one that participant is a party to - either side of a dispute, the creator of a value recovery, the participant a refund credit was booked for - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed. A record this deployment does not hold is 404 PIX-0147 too when an ispb is named. An ISPB this deployment does not act as is 422 PIX-0128, before any record is read. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the record has to be one that participant is a party to - either side of a dispute, the creator of a value recovery, the participant a refund credit was booked for - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed. A record this deployment does not hold is 404 PIX-0147 too when an ispb is named. An ISPB this deployment does not act as is 422 PIX-0128, before any record is read. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string - description: "The registered indirect participant (UUID) this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the refund request has to be over a payment this deployment recorded for that indirect - the rule GET /v1/med/refunds?indirectId= lists by - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed; a record this deployment does not hold is 404 PIX-0147 too when an indirectId is named. It is ROUTING DATA you supply, never a credential, and a token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061. Sending it empty (indirectId=) reads the same as omitting it." explode: false in: query name: indirectId schema: description: "The registered indirect participant (UUID) this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the refund request has to be over a payment this deployment recorded for that indirect - the rule GET /v1/med/refunds?indirectId= lists by - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed; a record this deployment does not hold is 404 PIX-0147 too when an indirectId is named. It is ROUTING DATA you supply, never a credential, and a token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061. Sending it empty (indirectId=) reads the same as omitting it." examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string - description: "Idempotency key for this write: any stable business string you choose, sent as the X-Idempotency request header - the same header, by the same name, that the Midaz ledger takes, so one integration sends one thing by one name. Send the SAME value again to retry safely: the plugin projects it deterministically into the GUID form JDPI requires (contract 6), so a repeat lands in the same JDPI dedup slot inside JD's 24h window and the operation is applied once. The raw value is never forwarded verbatim, so correlate JDPI-side logs with the projection rather than with what you sent. The header is REQUIRED: omitting it is refused 400 PIX-0061 before any JDPI call. BREAKING CHANGE: this value used to be the body field idempotencyKey, which no longer exists." in: header name: X-Idempotency required: true schema: description: "Idempotency key for this write: any stable business string you choose, sent as the X-Idempotency request header - the same header, by the same name, that the Midaz ledger takes, so one integration sends one thing by one name. Send the SAME value again to retry safely: the plugin projects it deterministically into the GUID form JDPI requires (contract 6), so a repeat lands in the same JDPI dedup slot inside JD's 24h window and the operation is applied once. The raw value is never forwarded verbatim, so correlate JDPI-side logs with the projection rather than with what you sent. The header is REQUIRED: omitting it is refused 400 PIX-0061 before any JDPI call. BREAKING CHANGE: this value used to be the body field idempotencyKey, which no longer exists." examples: - med-analyze-2024-0001 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 "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 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-analyzed refund request as the requesting PSP (JDPI devolucao/cancelar, contract 2.11). An unknown id returns a coded 404. Persists the JDPI response entity and returns it. Optional ispb names the direct participant the request acts for: named, the record has to be one that participant is a party to, or the answer is 404 PIX-0147 before anything is read from JDPI or changed; an ISPB this deployment does not act as is 422 PIX-0128 before any record is read; a token confined to one participant has to name it. Optional indirectId names the registered indirect participant the request acts for: named, the refund request has to be over a payment this deployment recorded for that indirect — the rule GET /v1/med/refunds?indirectId= lists by — or the answer is 404 PIX-0147 before anything is read from JDPI or changed; a token confined to one indirect has to name it; a malformed indirectId is 400 PIX-0061." 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 - description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the record has to be one that participant is a party to - either side of a dispute, the creator of a value recovery, the participant a refund credit was booked for - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed. A record this deployment does not hold is 404 PIX-0147 too when an ispb is named. An ISPB this deployment does not act as is 422 PIX-0128, before any record is read. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the record has to be one that participant is a party to - either side of a dispute, the creator of a value recovery, the participant a refund credit was booked for - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed. A record this deployment does not hold is 404 PIX-0147 too when an ispb is named. An ISPB this deployment does not act as is 422 PIX-0128, before any record is read. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string - description: "The registered indirect participant (UUID) this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the refund request has to be over a payment this deployment recorded for that indirect - the rule GET /v1/med/refunds?indirectId= lists by - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed; a record this deployment does not hold is 404 PIX-0147 too when an indirectId is named. It is ROUTING DATA you supply, never a credential, and a token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061. Sending it empty (indirectId=) reads the same as omitting it." explode: false in: query name: indirectId schema: description: "The registered indirect participant (UUID) this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the refund request has to be over a payment this deployment recorded for that indirect - the rule GET /v1/med/refunds?indirectId= lists by - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed; a record this deployment does not hold is 404 PIX-0147 too when an indirectId is named. It is ROUTING DATA you supply, never a credential, and a token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061. Sending it empty (indirectId=) reads the same as omitting it." examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string - description: "Idempotency key for this write: any stable business string you choose, sent as the X-Idempotency request header - the same header, by the same name, that the Midaz ledger takes, so one integration sends one thing by one name. Send the SAME value again to retry safely: the plugin projects it deterministically into the GUID form JDPI requires (contract 6), so a repeat lands in the same JDPI dedup slot inside JD's 24h window and the operation is applied once. The raw value is never forwarded verbatim, so correlate JDPI-side logs with the projection rather than with what you sent. The header is REQUIRED: omitting it is refused 400 PIX-0061 before any JDPI call. BREAKING CHANGE: this value used to be the body field idempotencyKey, which no longer exists." in: header name: X-Idempotency required: true schema: description: "Idempotency key for this write: any stable business string you choose, sent as the X-Idempotency request header - the same header, by the same name, that the Midaz ledger takes, so one integration sends one thing by one name. Send the SAME value again to retry safely: the plugin projects it deterministically into the GUID form JDPI requires (contract 6), so a repeat lands in the same JDPI dedup slot inside JD's 24h window and the operation is applied once. The raw value is never forwarded verbatim, so correlate JDPI-side logs with the projection rather than with what you sent. The header is REQUIRED: omitting it is refused 400 PIX-0061 before any JDPI call. BREAKING CHANGE: this value used to be the body field idempotencyKey, which no longer exists." examples: - med-cancel-2024-0001 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RefundRequestView" 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 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 (contested-side 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 request returns a coded 422, and an already-effectuated one echoes its recorded ids with no second post. A failed request is not safe to retry blindly: its reserve may have landed, and the ledger deduplicates a retry only within 300 seconds, so past that window an operator reconciles the request before it is sent again. An unknown id returns a coded 404. Optional ispb names the direct participant the request acts for: named, the record has to be one that participant is a party to, or the answer is 404 PIX-0147 before anything is read from JDPI or changed; an ISPB this deployment does not act as is 422 PIX-0128 before any record is read; a token confined to one participant has to name it. Optional indirectId names the registered indirect participant the request acts for: named, the refund request has to be over a payment this deployment recorded for that indirect — the rule GET /v1/med/refunds?indirectId= lists by — or the answer is 404 PIX-0147 before anything is read from JDPI or changed; a token confined to one indirect has to name it; a malformed indirectId is 400 PIX-0061." 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 - description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the record has to be one that participant is a party to - either side of a dispute, the creator of a value recovery, the participant a refund credit was booked for - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed. A record this deployment does not hold is 404 PIX-0147 too when an ispb is named. An ISPB this deployment does not act as is 422 PIX-0128, before any record is read. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the record has to be one that participant is a party to - either side of a dispute, the creator of a value recovery, the participant a refund credit was booked for - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed. A record this deployment does not hold is 404 PIX-0147 too when an ispb is named. An ISPB this deployment does not act as is 422 PIX-0128, before any record is read. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string - description: "The registered indirect participant (UUID) this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the refund request has to be over a payment this deployment recorded for that indirect - the rule GET /v1/med/refunds?indirectId= lists by - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed; a record this deployment does not hold is 404 PIX-0147 too when an indirectId is named. It is ROUTING DATA you supply, never a credential, and a token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061. Sending it empty (indirectId=) reads the same as omitting it." explode: false in: query name: indirectId schema: description: "The registered indirect participant (UUID) this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the refund request has to be over a payment this deployment recorded for that indirect - the rule GET /v1/med/refunds?indirectId= lists by - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed; a record this deployment does not hold is 404 PIX-0147 too when an indirectId is named. It is ROUTING DATA you supply, never a credential, and a token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061. Sending it empty (indirectId=) reads the same as omitting it." examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/EffectuateRefundView" 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 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 registeredAt: §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. Optional ispb names the direct participant the request acts for: named, the record has to be one that participant is a party to, or the answer is 404 PIX-0147 before anything is read from JDPI or changed; an ISPB this deployment does not act as is 422 PIX-0128 before any record is read; a token confined to one participant has to name it. Optional indirectId names the registered indirect participant the request acts for: named, the refund request has to be over a payment this deployment recorded for that indirect — the rule GET /v1/med/refunds?indirectId= lists by — or the answer is 404 PIX-0147 before anything is read from JDPI or changed; a token confined to one indirect has to name it; a malformed indirectId is 400 PIX-0061." 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 - description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the record has to be one that participant is a party to - either side of a dispute, the creator of a value recovery, the participant a refund credit was booked for - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed. A record this deployment does not hold is 404 PIX-0147 too when an ispb is named. An ISPB this deployment does not act as is 422 PIX-0128, before any record is read. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the record has to be one that participant is a party to - either side of a dispute, the creator of a value recovery, the participant a refund credit was booked for - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed. A record this deployment does not hold is 404 PIX-0147 too when an ispb is named. An ISPB this deployment does not act as is 422 PIX-0128, before any record is read. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string - description: "The registered indirect participant (UUID) this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the refund request has to be over a payment this deployment recorded for that indirect - the rule GET /v1/med/refunds?indirectId= lists by - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed; a record this deployment does not hold is 404 PIX-0147 too when an indirectId is named. It is ROUTING DATA you supply, never a credential, and a token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061. Sending it empty (indirectId=) reads the same as omitting it." explode: false in: query name: indirectId schema: description: "The registered indirect participant (UUID) this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the refund request has to be over a payment this deployment recorded for that indirect - the rule GET /v1/med/refunds?indirectId= lists by - or the answer is 404 PIX-0147 and nothing is read from JDPI or changed; a record this deployment does not hold is 404 PIX-0147 too when an indirectId is named. It is ROUTING DATA you supply, never a credential, and a token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061. Sending it empty (indirectId=) reads the same as omitting it." examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RefundRequestView" 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 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. Optional ispb makes the listing AS that direct participant: JDPI answers only for what it holds." operationId: listPixAutomaticoAuthorizations parameters: - description: fluxo (0=payer's PSP, 1=recipient's PSP). explode: false in: query name: flow schema: description: fluxo (0=payer's PSP, 1=recipient's PSP). examples: - 1 format: int64 type: integer - description: "The ISPB of the direct participant this listing is made AS. OPTIONAL: omit it and the listing is made on the default credential, exactly as before. Named, JDPI is asked with that participant's credential, and it answers only for what that participant holds. An ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant this listing is made AS. OPTIONAL: omit it and the listing is made on the default credential, exactly as before. Named, JDPI is asked with that participant's credential, and it answers only for what that participant holds. An ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string - 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 (an RFC 3339 date-time). explode: false in: query name: updatedFrom required: true schema: description: dtHrAtualizacaoRecorrenciaInicio (an RFC 3339 date-time). examples: - "2024-01-01T00:00:00.000Z" format: date-time type: string - description: dtHrAtualizacaoRecorrenciaFim (an RFC 3339 date-time). explode: false in: query name: updatedTo required: true schema: description: dtHrAtualizacaoRecorrenciaFim (an RFC 3339 date-time). examples: - "2024-06-19T00:00:00.000Z" format: date-time 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 "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 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 as the recipient's PSP (JDPI 4.3.1). Persists the authorization in the Requested state and returns the JDPI request id. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. The recipient is resolved by the document, or by branch and account: 422 PIX-0143 when they match more than one account, and 422 PIX-0144 when the branch and account belong to a different holder than the document." 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 "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 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 "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 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 "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 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 "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 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 "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 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). "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 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 - description: "The ISPB of the direct participant this consult is made AS. It is ROUTING DATA you supply and guarantee - never a credential, never read from a header or a path, and it never widens what your token can reach. While exactly ONE participant of this deployment holds this recurrence, the recorded row names the direct participant whose books it lives in, and that is authoritative: naming that one changes nothing, naming another is refused. It DECIDES when TWO do - this deployment can be both PSPs of one recurrence inside its own economic group, and then it holds one row per side, in two participants' books, with no way to choose between them. OPTIONAL in every other case: omit it and the row, or the tenant default when there is no row, answers. Omitting it with a row on each side is 422 PIX-0127, an ISPB this deployment does not act as is 422 PIX-0128, and one that holds none of the recorded rows is 400 PIX-0061. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant this consult is made AS. It is ROUTING DATA you supply and guarantee - never a credential, never read from a header or a path, and it never widens what your token can reach. While exactly ONE participant of this deployment holds this recurrence, the recorded row names the direct participant whose books it lives in, and that is authoritative: naming that one changes nothing, naming another is refused. It DECIDES when TWO do - this deployment can be both PSPs of one recurrence inside its own economic group, and then it holds one row per side, in two participants' books, with no way to choose between them. OPTIONAL in every other case: omit it and the row, or the tenant default when there is no row, answers. Omitting it with a row on each side is 422 PIX-0127, an ISPB this deployment does not act as is 422 PIX-0128, and one that holds none of the recorded rows is 400 PIX-0061. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/AuthorizationResponse" 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 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). Optional ispb names the direct participant this write acts for: named, the recurrence row has to be booked in that participant's books, or the answer is 404 PIX-0147 before JDPI is asked; an ISPB this deployment does not act as is 422 PIX-0128, before the row is read." 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 - description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the recurrence row this write addresses has to be booked in that participant's books, or the answer is 404 PIX-0147 and nothing is sent to JDPI or changed. An ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the recurrence row this write addresses has to be booked in that participant's books, or the answer is 404 PIX-0147 and nothing is sent to JDPI or changed. An ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ 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 "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 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 - description: "The ISPB of the direct participant this consult is made AS. It is ROUTING DATA you supply and guarantee - never a credential, never read from a header or a path, and it never widens what your token can reach. While exactly ONE participant of this deployment holds this recurrence, the recorded row names the direct participant whose books it lives in, and that is authoritative: naming that one changes nothing, naming another is refused. It DECIDES when TWO do - this deployment can be both PSPs of one recurrence inside its own economic group, and then it holds one row per side, in two participants' books, with no way to choose between them. OPTIONAL in every other case: omit it and the row, or the tenant default when there is no row, answers. Omitting it with a row on each side is 422 PIX-0127, an ISPB this deployment does not act as is 422 PIX-0128, and one that holds none of the recorded rows is 400 PIX-0061. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant this consult is made AS. It is ROUTING DATA you supply and guarantee - never a credential, never read from a header or a path, and it never widens what your token can reach. While exactly ONE participant of this deployment holds this recurrence, the recorded row names the direct participant whose books it lives in, and that is authoritative: naming that one changes nothing, naming another is refused. It DECIDES when TWO do - this deployment can be both PSPs of one recurrence inside its own economic group, and then it holds one row per side, in two participants' books, with no way to choose between them. OPTIONAL in every other case: omit it and the row, or the tenant default when there is no row, answers. Omitting it with a row on each side is 422 PIX-0127, an ISPB this deployment does not act as is 422 PIX-0128, and one that holds none of the recorded rows is 400 PIX-0061. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/CancellationDetailResponse" 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 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, as the payer's PSP, a recurring-payment authorization read from a QR (JDPI 4.3.3, journeys 2-4). An existing payer-side authorization moves to Active; with none, the confirmation creates it, Active, once the payer agency/account is proved to belong to the payer document and to be bound to a ledger account; contractNumber, payer.cpfCnpj and payer.account are required on every confirmation. createdDateTime and authorizedAt are required on every confirmation, so a retry sends JD the same body. When the payer row already exists here, payer.ispb has to name the participant it is booked under, or the answer is 404 PIX-0147 before JDPI is asked — a replay included; an ISPB this deployment does not act as is 422 PIX-0128, before the row is read. 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 "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 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. Optional ispb names the direct participant this write acts for: named, the recurrence row has to be booked in that participant's books, or the answer is 404 PIX-0147 before JDPI is asked; an ISPB this deployment does not act as is 422 PIX-0128, before the row is read." 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 - description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the recurrence row this write addresses has to be booked in that participant's books, or the answer is 404 PIX-0147 and nothing is sent to JDPI or changed. An ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the recurrence row this write addresses has to be booked in that participant's books, or the answer is 404 PIX-0147 and nothing is sent to JDPI or changed. An ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ 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 "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 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 payer's PSP (JDPI 4.3.2). An acceptance transitions the authorization to Accepted; a rejection to Rejected. Accepting a payer-side authorization first resolves the payer account its recurring debits will draw on, and an account that cannot be resolved refuses the acceptance before anything is sent to JDPI. Optional ispb names the direct participant this write acts for: named, the recurrence row has to be booked in that participant's books, or the answer is 404 PIX-0147 before JDPI is asked; an ISPB this deployment does not act as is 422 PIX-0128, before the row is read." 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 - description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the recurrence row this write addresses has to be booked in that participant's books, or the answer is 404 PIX-0147 and nothing is sent to JDPI or changed. An ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant this request acts for. OPTIONAL: omit it and the request is answered exactly as before. Named, the recurrence row this write addresses has to be booked in that participant's books, or the answer is 404 PIX-0147 and nothing is sent to JDPI or changed. An ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ 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 "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 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 "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 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 (due-date charge) and a recurring-payment authorization (PIX Automatico). The recipient name and city are CRM-sourced from the account. 422 PIX-0139 when the account's record names a different institution than the one minting the QR code; nothing is sent to JDPI. 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 "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 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 (due-date charge) 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 "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 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. Optional ispb makes the decode AS that direct participant. Call it on the paying side, after the payer scans a composite QR and before the authorization is requested; it reads and changes nothing. JDPI fetches the URL from the server of the institution receiving the payment, so the answer depends on that server as well as on JDPI. Refusals: 400 PIX-0061 when recurrencePayloadUrl is blank; 422 PIX-1065 when JDPI answered that the payload could not be fetched from the URL's host — the detail names the host and carries JDPI's reason, and the failure is that host's, not JDPI's, so retrying only helps once the receiving institution serves it; 404 PIX-1005 when JDPI found no payload at the URL; 422 PIX-1047 when JDPI refused the URL; 400 PIX-1001 when what the URL served is not a valid recurrence payload; 503 PIX-1050 when JDPI is unavailable, 503 PIX-1054 when it cannot be reached, and 504 PIX-1051 when it does not answer in time. 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 "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 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. 422 PIX-0139 when the account's record names a different institution than the one minting the QR code; nothing is sent to JDPI. 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 "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 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 "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 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. 422 PIX-0139 when the account's record names a different institution than the one minting the QR code; nothing is sent to JDPI. 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 "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 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 "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 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. 422 PIX-0139 when the account's record names a different institution than the one minting the QR code; nothing is sent to JDPI. 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 "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 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/courier-ownership: post: description: "Operator backfill for the Pix cutover, idempotent and safe to repeat. Claims on the Courier every recurrence this engine authorized as the payer's PSP (retrying those another engine held), then declares every debit block not yet reversed (a debited one for a day, as its reversal can still follow) and every schedule that can still be cancelled. Last, it claims the charger side of every live recurrence this engine opened as the recipient's PSP, retrying those another engine held. Run it again after the vendor is repointed at the Courier, so legs opened in between are declared too. heldElsewhere lists the keys the Courier gives to another engine; an operator resolves each one. 503 PIX-0130: the Courier is not configured for this tenant or could not be reached; run it again." operationId: syncCourierOwnership responses: "200": content: application/json: schema: $ref: "#/components/schemas/CourierOwnershipOutputBody" 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: Tell the JD Courier which Pix Automático traffic is this engine's tags: - PIX Automatico x-mint: href: /en/reference/interfaces/pix-jd/tell-the-jd-courier-which-pix-automatico-traffic-is-this-engine-s /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 "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 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 "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 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 "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 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 "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 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 "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 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 "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 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 "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 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 "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 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 "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 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 as the recipient's PSP (JDPI 4.4.1). Persists the schedule in the Requested state and returns the JDPI acknowledgement. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. The recipient is resolved by the document, or by branch and account: 422 PIX-0143 when they match more than one account, and 422 PIX-0144 when the branch and account belong to a different holder than the document." 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 "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 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 "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 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 "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 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 "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 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 "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 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. Optional ispb makes the listing AS that direct participant: JDPI answers only for what it holds." operationId: listPixAutomaticoSchedules parameters: - description: fluxo (0=sent, as the recipient's PSP; 1=received, as the payer's PSP). explode: false in: query name: flow required: true schema: description: fluxo (0=sent, as the recipient's PSP; 1=received, as the payer's PSP). examples: - 0 format: int64 type: integer - description: "The ISPB of the direct participant this listing is made AS. OPTIONAL: omit it and the listing is made on the default credential, exactly as before. Named, JDPI is asked with that participant's credential, and it answers only for what that participant holds. An ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant this listing is made AS. OPTIONAL: omit it and the listing is made on the default credential, exactly as before. Named, JDPI is asked with that participant's credential, and it answers only for what that participant holds. An ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string - 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 "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 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 - description: "The ISPB of the direct participant this consult is made AS. It is ROUTING DATA you supply and guarantee - never a credential, never read from a header or a path, and it never widens what your token can reach. While exactly ONE participant of this deployment holds this recurrence, the recorded row names the direct participant whose books it lives in, and that is authoritative: naming that one changes nothing, naming another is refused. It DECIDES when TWO do - this deployment can be both PSPs of one recurrence inside its own economic group, and then it holds one row per side, in two participants' books, with no way to choose between them. OPTIONAL in every other case: omit it and the row, or the tenant default when there is no row, answers. Omitting it with a row on each side is 422 PIX-0127, an ISPB this deployment does not act as is 422 PIX-0128, and one that holds none of the recorded rows is 400 PIX-0061. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant this consult is made AS. It is ROUTING DATA you supply and guarantee - never a credential, never read from a header or a path, and it never widens what your token can reach. While exactly ONE participant of this deployment holds this recurrence, the recorded row names the direct participant whose books it lives in, and that is authoritative: naming that one changes nothing, naming another is refused. It DECIDES when TWO do - this deployment can be both PSPs of one recurrence inside its own economic group, and then it holds one row per side, in two participants' books, with no way to choose between them. OPTIONAL in every other case: omit it and the row, or the tenant default when there is no row, answers. Omitting it with a row on each side is 422 PIX-0127, an ISPB this deployment does not act as is 422 PIX-0128, and one that holds none of the recorded rows is 400 PIX-0061. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ScheduleResponse" 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 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). requesterIspb has to name the participant the schedule row is booked under, or the answer is 404 PIX-0147 before JDPI is asked; an ISPB this deployment does not act as is 422 PIX-0128, before the row is read. 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 "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 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 - description: "The ISPB of the direct participant this consult is made AS. It is ROUTING DATA you supply and guarantee - never a credential, never read from a header or a path, and it never widens what your token can reach. While exactly ONE participant of this deployment holds this recurrence, the recorded row names the direct participant whose books it lives in, and that is authoritative: naming that one changes nothing, naming another is refused. It DECIDES when TWO do - this deployment can be both PSPs of one recurrence inside its own economic group, and then it holds one row per side, in two participants' books, with no way to choose between them. OPTIONAL in every other case: omit it and the row, or the tenant default when there is no row, answers. Omitting it with a row on each side is 422 PIX-0127, an ISPB this deployment does not act as is 422 PIX-0128, and one that holds none of the recorded rows is 400 PIX-0061. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant this consult is made AS. It is ROUTING DATA you supply and guarantee - never a credential, never read from a header or a path, and it never widens what your token can reach. While exactly ONE participant of this deployment holds this recurrence, the recorded row names the direct participant whose books it lives in, and that is authoritative: naming that one changes nothing, naming another is refused. It DECIDES when TWO do - this deployment can be both PSPs of one recurrence inside its own economic group, and then it holds one row per side, in two participants' books, with no way to choose between them. OPTIONAL in every other case: omit it and the row, or the tenant default when there is no row, answers. Omitting it with a row on each side is 422 PIX-0127, an ISPB this deployment does not act as is 422 PIX-0128, and one that holds none of the recorded rows is 400 PIX-0061. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ScheduleCancellationResponse" 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 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 "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 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 "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 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 "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 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. Which of this deployment's direct participants acts is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own customers and its own JDPI credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. It selects the JDPI credential the decode goes out on and nothing else. 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 "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 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. Which of this deployment's direct participants acts is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own customers and its own JDPI credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. It selects the JDPI credential the decode goes out on and nothing else. 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 "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 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 REFUSED 422 PIX-0111 WHILE THIS TENANT'S INDIRECT-PARTICIPANTS FEATURE IS SWITCHED OFF, and the refusal names the setting an operator has to turn on. It is never dropped: a QR minted as if you had sent none would be signed with THIS participant's certificate and published on THIS participant's domain, so you would have asked for one institution's QR and silently received another's. Send no indirectId and the QR is generated exactly as it always was. Refusals specific to indirectId — all decided before JDPI is called, so a refused QR is never generated: 422 PIX-0111 when this tenant's indirect-participants feature is off (the value is refused rather than parsed, so none of the others can be reached); 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. Which of this deployment's direct participants acts is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own customers and its own JDPI credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. For an indirect participant: 422 PIX-0141 when the account is not in the ledger the indirect is mounted on, and 409 PIX-0140 when the indirect is mounted on books that are no longer configured for Pix (an operator setting). The published payloadUrl and its JWKS location carry THAT participant's ISPB, so a QR minted as the wrong participant sends every payer's PSP to a key set that cannot validate its signature — and by then the QR is already in the wild. An indirect's QR is minted, signed and published by the participant recorded at that indirect's registration - the one direct participant it mounts on, which is NOT necessarily this deployment's default one - so supplying indirectId together with any other ispb, the default one included, is 422 PIX-0102; leaving ispb blank on an indirect request resolves to that same recorded participant rather than to the default. 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 "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 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. A CHARGE STAYS WITH THE INDIRECT IT WAS CREATED FOR. Every charge created records which indirect it was created for (none, for the direct participant's own), and an update naming a different one is refused 404 PIX-0147 — after the indirectId checks below and before JDPI is called, so the charge, its revision and its hosted payload are not changed. That covers naming indirect A on a charge created for indirect B, and naming any indirect on a charge created for the direct participant. A charge created before this record existed is not checked, and neither is an update that names no indirect. The record decides only WHO MAY update; this request's indirectId — not the create's — still 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 refused 422 PIX-0111 naming the setting, so none of the refusals below can be reached and nothing is re-signed — an update that silently reverted to the direct participant would move a LIVE charge onto another certificate and domain, and its refreshed QR would stop validating at the payer's app. 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. Which of this deployment's direct participants acts is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own customers and its own JDPI credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. For an indirect participant: 422 PIX-0141 when the account is not in the ledger the indirect is mounted on, and 409 PIX-0140 when the indirect is mounted on books that are no longer configured for Pix (an operator setting). The published payloadUrl and its JWKS location carry THAT participant's ISPB, so a QR minted as the wrong participant sends every payer's PSP to a key set that cannot validate its signature — and by then the QR is already in the wild. An indirect's QR is minted, signed and published by the participant recorded at that indirect's registration - the one direct participant it mounts on, which is NOT necessarily this deployment's default one - so supplying indirectId together with any other ispb, the default one included, is 422 PIX-0102; leaving ispb blank on an indirect request resolves to that same recorded participant rather than to the default. 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 "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 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 this participant created at JD (JDPI §8.3.12) whose registration falls inside a date window. Call it to reconcile or audit the charges you generated; it only reads, and changes nothing. The response always carries all four blocks: staticQrCodes, dynamicQrCodes (immediate), cobvQrCodes (dynamic with due date) and recurrenceQrCodes. A block with no match is an empty array, and a window with no QR code is a 200, never a 404. qrCodeType filters by JD type: 11 static, 12 immediate dynamic, 13 dynamic with due date, 14 QRCode Composto, and 15-17 QRCode Composto carrying static, immediate-dynamic or due-date data. Omit it to list every type: the plugin asks JD once per type and merges the answers, so page and pageSize apply to each type's answer. startDateTime and endDateTime are required. Send any RFC 3339 date-time, with or without milliseconds and with any offset (2026-01-01T00:00:00Z, 2026-01-01T00:00:00-03:00); the plugin converts both to UTC in JD's format. The window may span at most 90 days, counted to the millisecond. pageSize is 1-100 (default 50); page defaults to 1. JD lists every charge of the DIRECT participant whose credential signs the call, and the indirect participants riding it share that listing. indirectId narrows it to ONE indirect: only the immediate dynamic charges created for that indirect come back - never another indirect's and never the direct participant's own - and the static, due-date and recurrence blocks come back empty, because none of them is created for an indirect. A charge created before this deployment recorded which indirect a charge belongs to is not returned to a listing that names an indirect. The narrowing is applied to each page JD answers, so a page may hold fewer entries than pageSize. A token confined to one indirect has to name it. What goes wrong. Every refusal below except the JD answers is decided before JD is called: - 400 PIX-0061, errors[] naming the field: startDateTime or endDateTime missing or not an RFC 3339 date-time; startDateTime later than endDateTime (startDateTime); a window over 90 days (endDateTime); pageSize outside 1-100 (pageSize). - 400 PIX-0061: indirectId is not a valid UUID. - 422 PIX-0127 / PIX-0128: the participant rule for ispb, below. - 400 PIX-1001: JD refused the filters; detail carries JD's reason when JD gave one. 400 PIX-1000 when JD named the fields, with errors[] per field. - 404 PIX-1005: JD answered not found. 429 PIX-1008: JD's rate limit; retry later. - 503 PIX-1050 / 504 PIX-1051: JD unavailable or timing out; retry. 409 PIX-0092: the participant's JD credential is not provisioned, an operator setting. Which of this deployment's direct participants answers is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own customers and its own JDPI credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. Sending it empty (ispb=) reads the same as omitting it. §8.3.12 answers for the participant whose credential signs the call, so reading as another one lists that institution's charges, not yours. operationId: listQRCodes parameters: - description: "tpQRCode filter: 11 static, 12 immediate dynamic, 13 dynamic with due date, 14 QRCode Composto, 15-17 QRCode Composto carrying static, immediate-dynamic or due-date data. Omit to list every type." explode: false in: query name: qrCodeType schema: description: "tpQRCode filter: 11 static, 12 immediate dynamic, 13 dynamic with due date, 14 QRCode Composto, 15-17 QRCode Composto carrying static, immediate-dynamic or due-date data. Omit to list every type." examples: - 12 format: int64 type: integer - description: Window start (dtHrInicial), an RFC 3339 date-time with any offset; milliseconds optional. Sent to JD in UTC as aaaa-mm-ddTHH:mm:ss.sssZ. explode: false in: query name: startDateTime required: true schema: description: Window start (dtHrInicial), an RFC 3339 date-time with any offset; milliseconds optional. Sent to JD in UTC as aaaa-mm-ddTHH:mm:ss.sssZ. examples: - "2024-10-01T00:00:00Z" format: date-time type: string - description: Window end (dtHrFinal), an RFC 3339 date-time, not before startDateTime and at most 90 days after it. explode: false in: query name: endDateTime required: true schema: description: Window end (dtHrFinal), an RFC 3339 date-time, not before startDateTime and at most 90 days after it. examples: - "2024-11-25T23:59:59.999Z" format: date-time 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): 1-100; omit it for the default of 50. Sent outside 1-100 (0 included) is 400 PIX-0061." explode: false in: query name: pageSize schema: description: "Page size (tamanhoPagina): 1-100; omit it for the default of 50. Sent outside 1-100 (0 included) is 400 PIX-0061." examples: - 100 format: int64 maximum: 100 minimum: 1 type: integer - description: "The registered indirect participant (UUID) whose charges are listed. OPTIONAL: omit it and the listing is not narrowed by indirect. Named, only the immediate dynamic charges created for that indirect come back - never another indirect's, never the direct participant's own, and never a charge created before this deployment recorded which indirect a charge belongs to; staticQrCodes, cobvQrCodes and recurrenceQrCodes come back empty, because none of them is created for an indirect. A token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061." explode: false in: query name: indirectId schema: description: "The registered indirect participant (UUID) whose charges are listed. OPTIONAL: omit it and the listing is not narrowed by indirect. Named, only the immediate dynamic charges created for that indirect come back - never another indirect's, never the direct participant's own, and never a charge created before this deployment recorded which indirect a charge belongs to; staticQrCodes, cobvQrCodes and recurrenceQrCodes come back empty, because none of them is created for an indirect. A token confined to one indirect has to name it here. Not a valid UUID is 400 PIX-0061." examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string - description: "The ISPB of the direct participant whose QR codes are listed. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own JDPI credential - and this field is the only thing on the request that says which of them acts. OPTIONAL while it acts as a single participant: omit it and that one acts. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. JDPI answers this listing for the participant whose credential signs the call, so reading as another one lists that institution's charges, not yours. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant whose QR codes are listed. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own JDPI credential - and this field is the only thing on the request that says which of them acts. OPTIONAL while it acts as a single participant: omit it and that one acts. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. JDPI answers this listing for the participant whose credential signs the call, so reading as another one lists that institution's charges, not yours. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ListQRResponse" 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 "429": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Too Many Requests "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable "504": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Gateway Timeout 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. Which of this deployment's direct participants acts is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own customers and its own JDPI credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. 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 "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 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 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 returned over SPI: the amount is first reserved on the refunding account, then the refund is submitted to JDPI, and it answers PENDING with the money held until SPI settles it (EXECUTED, the reserve committed) or refuses it (ERROR, the reserve released) — poll GET /v1/transactions. A Pix received from an account that banks at this participant but is held in other books is returned to those books, never over SPI: the amount is held on the refunding account and the refund relayed, answering EXECUTED once those books credited the original payer, PENDING while their answer is unknown (the reconcile worker completes it — poll GET /v1/transactions), 422 PIX-0145 when they refused it and 503 PIX-0146 when they could not be reached; both release the hold, so nothing moved; 409 PIX-0149 when any fee in the package priced on the cross-core return route (this refund to the other core of the same participant, priced like a refund sent to another bank) is configured to deduct from the amount instead of being charged on top (an operator setting) — the applied package is known only once the hold is posted, so this refusal comes after the hold and before anything is relayed: the hold is released, by the reconcile worker when the ledger does not confirm the release at once, and nothing moved. The refund's own end-to-end id (endToEndRefundId) is filled when JD supplies it and may be empty while the refund is PENDING; an empty value is not a failure, the outcome arrives as transaction.refunded or transaction.failed. An on-us original that itself moved between two ledgers of this institution is returned the same way it was paid — a reserve in the ledger that received it, a credit in the ledger that paid, then a commit — so that one branch reports EXECUTED only after both legs landed; a refund whose credit that ledger has not yet confirmed delivered is ACCEPTED and still settling, reported PENDING with the money held, and the reconcile worker completes it — poll GET /v1/transactions rather than retrying it as a fresh refund. The exception is the same one the payment route carries: once the credit has landed, a settlement outcome the ledger leaves unknown while CLOSING the reserve still answers 5xx and still leaves the transaction PENDING, so a 5xx here never means nothing happened — poll it rather than sending a new refund under a new key. code is the return reason and is accepted only as BE08, FR01, MD06 or SL02. Idempotency: the X-Idempotency header is REQUIRED, and it is what makes a resend safe on every branch, on-us included: once a refund is recorded under a key, a resend under that key is refused 409 PIX-0029 and moves no money — read its outcome with GET /v1/transactions. Keys are scoped to the payer (the organization, plus the indirect participant on an indirect refund); a new refund needs a new key. A Pix received on an indirect participant's PIX position is returned by that indirect: send its indirectId, and the refund debits that indirect's position. A Pix received on a direct account is returned without one. payerIspb optionally names the direct participant paying the refund back. Named, the original has to be booked in that participant's books, checked before the idempotency key is read and before anything is held or sent; a token confined to one participant has to name it. Refusals: 422 PIX-0036 when no EXECUTED payment matches that (endToEndId, transactionId) pair, which is also the answer when the pair names a refund (a refund is never the original of another); 404 PIX-0147 when payerIspb names a participant, or indirectId an indirect, that does not hold the original (checked before eligibility, so it never tells the caller whether another participant's original exists or which way it went); 422 PIX-0128 for a payerIspb this deployment does not act as; 400 PIX-0087 when the original is a payment sent to another institution, or to an account held in other books of this one, and the caller is its sender; 400 PIX-0089 when it is such a payment and the caller is anyone else (only the receiving institution can return what it received); 400 PIX-0088 when the original is any other payment and the caller is not its payee; 422 PIX-0135 when indirectId is absent on a Pix received on an indirect's position; 422 PIX-0111 when the indirect-participants feature is off, 404 PIX-0095 when the indirect is not registered and 422 PIX-0100 when it is not ACTIVE, as on a payment order; 409 PIX-0075 when this amount plus the prior refunds would exceed the original; 409 PIX-0076 when the available balance of the account the refund debits (the indirect's position, for a Pix it received) is below the amount of a refund sent over SPI or to other books (nothing is reserved or sent); 409 PIX-0029 when this X-Idempotency key already names a refund of the payer, and while another refund of the same payment sent over SPI or to other books is still PENDING, or when JD answers with an earlier refund of it; 422 PIX-0030 on a non-positive amount; 409 PIX-0105 when a ledger the refund has to post in does not declare the reversal accounting routes (nothing is posted and no refund is recorded); 409 PIX-0142 when the ledger the original was booked in — or, for an on-us payment between two ledgers, the ledger it was credited in — is no longer configured for Pix on this deployment (nothing is posted and no refund is recorded; an operator has to restore that ledger to the Pix setup); 400 PIX-0061 when the X-Idempotency header is absent, blank or over 255 bytes, accountId or endToEndId is empty, transactionId is not a UUID, or code is outside the four accepted values. operationId: createRefund parameters: - description: "Idempotency key for this refund: any stable string you choose, up to 255 bytes, sent as the X-Idempotency request header (the same header, by the same name, that payment orders, MED writes and the Midaz ledger take). REQUIRED: omitting it, sending only whitespace, or sending more than 255 bytes is refused 400 PIX-0061 before anything is read, held or sent. Send the SAME value again to retry the SAME refund: once a refund is recorded under the key, a resend is answered 409 PIX-0029 and moves no money, whether it went to SPI or settled on-us, so read its outcome with GET /v1/transactions. Keys are scoped to the payer: the organization, plus the indirect participant on an indirect refund. A new refund needs a new key. BREAKING CHANGE: this replaces the optional body field clientRequestId, which no longer exists." in: header name: X-Idempotency required: true schema: description: "Idempotency key for this refund: any stable string you choose, up to 255 bytes, sent as the X-Idempotency request header (the same header, by the same name, that payment orders, MED writes and the Midaz ledger take). REQUIRED: omitting it, sending only whitespace, or sending more than 255 bytes is refused 400 PIX-0061 before anything is read, held or sent. Send the SAME value again to retry the SAME refund: once a refund is recorded under the key, a resend is answered 409 PIX-0029 and moves no money, whether it went to SPI or settled on-us, so read its outcome with GET /v1/transactions. Keys are scoped to the payer: the organization, plus the indirect participant on an indirect refund. A new refund needs a new key. BREAKING CHANGE: this replaces the optional body field clientRequestId, which no longer exists." examples: - refund-2026-09-29-0001 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/RefundBody" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/RefundResponse" description: Created "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 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 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 Midaz alias the row carries: the payer's ledger account on a payment, the credited one on a cash-in, the debited one on a refund), 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. Name the institution to separate them: `indirectId` lists only one indirect's transactions, and `ispb` only one direct participant's books (its indirects included). GET /v1/indirects/{indirectId}/transactions remains the purpose-built feed for reconciling an indirect (it is windowed, cursor-paged and ordered for reconciliation, which this one is not). A token confined to one participant or one indirect has to name it in `ispb` or `indirectId`; the listing then holds only what that one holds, and naming another is refused before anything is read. Naming neither lists every participant's transactions, exactly as before. Refusals: 422 PIX-0128 for an `ispb` this deployment does not act as; 400 for an `indirectId` that is not a UUID or an `ispb` that is not 8 digits. operationId: getTransactions parameters: - description: Filter by the Midaz alias the row carries (the debited account on a refund, @pi_{ispb} for an indirect). explode: false in: query name: account_id schema: description: Filter by the Midaz alias the row carries (the debited account on a refund, @pi_{ispb} for an indirect). examples: - "@pagador" 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 - description: "The ISPB of the direct participant whose transactions are listed. OPTIONAL: omit it and the listing is not narrowed by participant, exactly as before. Named, only transactions booked in that participant's books come back - which includes those of the indirect participants it serves. An ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply: it narrows what comes back and never widens what your token can reach, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant whose transactions are listed. OPTIONAL: omit it and the listing is not narrowed by participant, exactly as before. Named, only transactions booked in that participant's books come back - which includes those of the indirect participants it serves. An ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply: it narrows what comes back and never widens what your token can reach, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string - description: "The registered indirect participant (UUID) whose transactions are listed. OPTIONAL: omit it and the listing is not narrowed by indirect. Named, only transactions recorded for that indirect come back - never the direct participant's own. A token confined to one indirect has to name it here." explode: false in: query name: indirectId schema: description: "The registered indirect participant (UUID) whose transactions are listed. OPTIONAL: omit it and the listing is not narrowed by indirect. Named, only transactions recorded for that indirect come back - never the direct participant's own. A token confined to one indirect has to name it here." examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/TransactionListBody" 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 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. The account credited is the one payee.branch, payee.accountNumber and payee.accountDigit name, and it must belong to payee.document (422 PIX-0134). On a payment by key (payee.key) those coordinates are first checked against DICT (§8.2.14, asked as the payer; JDPI answers a key of this institution from its own base): a field the order states differently from the account DICT binds the key to is refused 422 PIX-0033 naming that field (the branch is compared by value, so "1" and "0001" name the same branch, here and in the paying participant's records), a key DICT does not hold is 404 PIX-1011, and JDPI unavailable is 503 PIX-1050 — all before anything is held. Send the payee object GET /v1/entries/{entryId}/lookup answered and it matches. 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 when JDPI returns one, whose idReqJdPi is the handle the outcome is read with, and 201 PENDING with this plugin's body when JDPI's answer proves nothing. 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 whenever JDPI acknowledges the order. 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 REFUSED 422 PIX-0111 WHILE THIS TENANT'S INDIRECT-PARTICIPANTS FEATURE IS SWITCHED OFF, and the refusal names the setting an operator has to turn on. The order is never quietly executed as a DIRECT one: that would hold the amount on the payer's own position instead of the institution's `@pi_{ispb}`, so the money would leave an account you never named, behind a 201. The refusal is decided before the payer is read, so nothing is held and no order is persisted. An order carrying NO indirectId is unaffected. 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 X-Idempotency header is REQUIRED, and it is what makes a retry safe on every branch, on-us included: once an order is recorded under a key, a resend under that key is refused 409 PIX-0029 and moves no money. Keys are scoped to the payer (the organization, plus the indirect participant on an indirect order); a new order needs a new key. Amounts are integer centavos. Every refusal below is decided before the hold is taken, so it moves ZERO money, except the cross-core answers PIX-0145, PIX-0146 and PIX-0149, which come after the hold and release it; when JDPI refuses the order after the hold exists, the call answers the refusal, the hold is released and the order stays in GET /v1/transactions with status ERROR — or PENDING, when the ledger does not confirm the release, until the background reconciler resolves it; when JDPI's answer does not prove a refusal (a timeout, a 5xx, a 408, 409 or 422 — except JD's payment-signature refusals JDPISPI017 and JDPISPI018, which prove one whatever status carries them and are never re-sent), the hold is kept and the order answers 201 PENDING with this plugin's body, an indirect order included, its final status coming later. The same release follows 409 PIX-0136, refused before JDPI is called when the paying participant's payment-order signing settings are written but cannot sign (a setting missing, an algorithm this plugin does not sign with, a key that does not fit it, or a certificate that is not the key's own); the message names the setting, and nothing reaches JDPI unsigned. Refusals: 409 PIX-0029 when this endToEndId or X-Idempotency key was already used by an order that may have moved money, and 409 PIX-0133 when that order was refused and moved none (send a new order under a new key); 409 PIX-0076 when the paying position lacks the amount; 409 PIX-0078 on a transfer to the same account; 409 PIX-0075 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; 422 PIX-0111 when an indirectId is supplied while this deployment's indirect-participants feature is off (naming the setting to enable — the order is refused, never quietly paid from the payer's own account), 404 PIX-0095 for an unknown or malformed indirectId and 422 PIX-0100 when the indirect it names is not ACTIVE; 422 PIX-0127 when this deployment acts as SEVERAL direct participants and the order names none of them in payerIspb, and 422 PIX-0128 when the one it names is not among them; when the payee banks at the PAYING participant — the order would normally settle internally, never touching SPI — and that participant has declared its ISPB shared with another core, the ownership map says which books hold the account the order names (payee.branch, payee.accountNumber and payee.accountDigit; a payment account, accountType 3, by its account alone), asked before the payee is looked up. When the OTHER core holds it, the order is a cross-core transfer, never sent over SPI: the amount is held on the payer's account and the order is relayed to that core, answering 201 EXECUTED once it credited the payee, 201 PENDING while its answer is unknown (the hold stays and the background worker resends and settles it; poll GET /v1/transactions), 422 PIX-0145 when it refused the credit and 503 PIX-0146 when the order never reached it — both release the hold, so nothing was debited, and the order stays in GET /v1/transactions with status ERROR (send it again under a new X-Idempotency key); and 409 PIX-0149 when any fee in the package priced on the cross-core route (this leg to the other core of the same participant, priced like a Pix sent to another bank) is configured to deduct from the amount instead of being charged on top (an operator setting) — the applied package is known only once the hold is posted, so this refusal comes after the hold and before anything is relayed: the hold is released and the order stays ERROR, or PENDING until the background worker finishes a release the ledger did not confirm; nothing was debited. Otherwise: 422 PIX-0129 when the map holds that account nowhere, 422 PIX-0132 when the order's account cannot be used to ask (a blank account, a blank branch on anything but a payment account, or one the map refuses as malformed — a retry changes nothing), 503 PIX-0130 when it could not answer (safe to retry: nothing was created) and 502 PIX-0131 when it answered in a form that cannot be acted on; each of these four is refused before anything is held and is NOT rerouted over SPI; an on-us payment WITHOUT payee.key is a payment by bank details, and it is credited on the account payee.branch, payee.accountNumber and payee.accountDigit name — number and digit together, exactly the account an interbank Pix carries — which must belong to payee.document, as the receiving institution checks on an interbank Pix: 404 PIX-2016 when the paying participant holds no such account, 422 PIX-0134 when it belongs to someone else, 422 PIX-0033 when no account is typed, 422 PIX-0108 when it is not bound to a ledger account (a payment account, accountType 3, is looked up by its account alone); an on-us payment WITH payee.key is credited on the account payee.branch, payee.accountNumber and payee.accountDigit name once DICT has confirmed them, checked exactly as a payment by bank details (404 PIX-2016, 422 PIX-0134), while an order naming no account is 422 PIX-0033; 422 PIX-0108 when that payee is not bound to a ledger account; 422 PIX-0102 when payerIspb is supplied on an indirect order and is not the participant recorded at that indirect's registration; 409 PIX-0105 when the ledger the money leaves from declares no accounting route for the direction; when the payer or the on-us payee cannot be used as the order addresses it, nothing is reserved and the answer names what refused: 422 PIX-0137 when the account is held in a ledger that is not configured for Pix on the paying participant (pay from or to an account on a configured ledger, or have the operator add that ledger to the Pix setup), 422 PIX-0138 when the account's record does not say which ledger holds it, 422 PIX-0139 when the payer's record names a different institution than the one paying, 422 PIX-0141 when, on an indirect order, the payer account is not in the ledger the indirect is mounted on, and 409 PIX-0140 when the indirect is mounted on books no longer configured for Pix (an operator setting); a refusal of the payer names the payer account (accountId) in its message, while a refusal of the on-us payee — PIX-0137 or PIX-0138 — names no account, because on a payment by key the payee's account is one you never saw, so read it as the payee the order addressed; 400 PIX-0061 when the X-Idempotency header is missing, blank or over 255 bytes, when accountId is empty or when an accountType is outside the PIX domain 0..4. Called with a partner credential, the order is also decided by that partner's own rules for the ledger and the CRM this plugin calls to serve it: 403 PIX-4019 when Midaz refuses the partner and 403 PIX-2025 when the CRM does, the message naming the reason (other_tenant, suspended, no_longer_valid or not_allowed) — grant the partner the missing permission on that service; a partner holding no grant for those services is decided by its Pix grant alone. On an indirect order a JD refusal is passed back with JD's own status and body instead of a problem+json. An on-us payee who banks at the paying participant but in a DIFFERENT ledger of it is served rather than refused: the amount is reserved on the payer's ledger, credited on the payee's ledger, and the reserve is then committed — so the order answers EXECUTED only once both legs landed. Both on-us shapes persist their transaction before the first posting, so their failures are not invisible: an order the ledger refuses answers an error AND leaves a transaction you will find in GET /v1/transactions with status ERROR (it does not count against the account's period limit: only a hold that reached the ledger does); a same-ledger order whose posting the ledger leaves unknown answers 5xx and stays PENDING until the reconcile worker finds the posting and settles it EXECUTED — a posting the ledger does not show yet never fails the order, because the ledger may record a posting after answering for it; and a cross-ledger order whose credit the payee's ledger has not yet confirmed delivered is ACCEPTED and still settling: it answers 201 with status PENDING, the money stays held, and the reconcile worker completes it — poll GET /v1/transactions rather than retrying it as a fresh payment. NOT every failure on that branch became a 201, and the exception matters because the money has already moved: when the credit HAS landed and the ledger then leaves the outcome of CLOSING the hold unknown — the settle failed, or a release could not be proved — the order still answers 5xx AND still leaves the transaction PENDING. So a 5xx here never means nothing happened. Poll GET /v1/transactions; if you retry, retry with the SAME X-Idempotency key, because a fresh key is a second payment. operationId: createTransaction parameters: - description: "Idempotency key for this payment order: any stable string you choose, up to 255 bytes, sent as the X-Idempotency request header (the same header, by the same name, that MED writes and the Midaz ledger take). REQUIRED: omitting it, sending only whitespace, or sending more than 255 bytes is refused 400 PIX-0061 before anything is read, held or sent. Send the SAME value again to retry the SAME order: once an order is recorded under the key, a resend is answered 409 PIX-0029 and moves no money, whether that order went to SPI or settled on-us, so read its outcome with GET /v1/transactions. Keys are scoped to the payer: the organization, plus the indirect participant on an indirect order. A new order needs a new key. BREAKING CHANGE: this replaces the optional body field clientRequestId, which no longer exists." in: header name: X-Idempotency required: true schema: description: "Idempotency key for this payment order: any stable string you choose, up to 255 bytes, sent as the X-Idempotency request header (the same header, by the same name, that MED writes and the Midaz ledger take). REQUIRED: omitting it, sending only whitespace, or sending more than 255 bytes is refused 400 PIX-0061 before anything is read, held or sent. Send the SAME value again to retry the SAME order: once an order is recorded under the key, a resend is answered 409 PIX-0029 and moves no money, whether that order went to SPI or settled on-us, so read its outcome with GET /v1/transactions. Keys are scoped to the payer: the organization, plus the indirect participant on an indirect order. A new order needs a new key. BREAKING CHANGE: this replaces the optional body field clientRequestId, which no longer exists." examples: - order-2026-09-25-0001 type: string 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 when JDPI acknowledges the order, the body being JD's own §8.4.1 acknowledgement passed through verbatim; an indirect order whose JDPI answer proves nothing answers 201 PENDING instead. 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." "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 "502": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: The ownership map answered in a form that cannot be acted on (PIX-0131). Nothing was reserved. "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: A dependency could not answer. Only PIX-0130 (the ownership map could not answer) and PIX-0146 (a cross-core order never reached the payee's core, and its hold was released) guarantee nothing was debited. Any other 503 may leave the transaction PENDING with money already moved — poll GET /v1/transactions, and retry only with the SAME X-Idempotency key, because a fresh key is a second payment. 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". Optional `ispb` and `indirectId` name who the transaction is read as: named, it has to be held by that direct participant or indirect, or the answer is 404 PIX-0147 and nothing about it is returned — a token confined to one participant or indirect has to name it. Refusals: 400 PIX-0061 when transactionId is empty; 404 PIX-0147 when the transaction is held by another participant or indirect than the one named; 422 PIX-0128 for an `ispb` this deployment does not act as; 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 - description: "The ISPB of the direct participant this transaction is read as. OPTIONAL: omit it and the transaction is read whoever holds it, exactly as before. Named, the transaction has to be booked in that participant's books, or the answer is 404 PIX-0147 - the same id named under another participant is not served. When this deployment holds no such transaction, the live lookup at JDPI is made with that participant's credential, so JD answers only for what that participant holds. An ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." explode: false in: query name: ispb schema: description: "The ISPB of the direct participant this transaction is read as. OPTIONAL: omit it and the transaction is read whoever holds it, exactly as before. Named, the transaction has to be booked in that participant's books, or the answer is 404 PIX-0147 - the same id named under another participant is not served. When this deployment holds no such transaction, the live lookup at JDPI is made with that participant's credential, so JD answers only for what that participant holds. An ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply, never a credential, and a token confined to one participant has to name it here. Sending it empty (ispb=) reads the same as omitting it." examples: - "12345678" pattern: ^[0-9]{8}$ type: string - description: "The registered indirect participant (UUID) this transaction is read as. OPTIONAL. Named, the transaction has to be recorded for that indirect, or the answer is 404 PIX-0147 - a direct participant's own transaction is not the indirect's. A transaction this deployment does not hold is 404 PIX-0147 too: an indirect's movements are always booked here, so JDPI is not asked. A token confined to one indirect has to name it here." explode: false in: query name: indirectId schema: description: "The registered indirect participant (UUID) this transaction is read as. OPTIONAL. Named, the transaction has to be recorded for that indirect, or the answer is 404 PIX-0147 - a direct participant's own transaction is not the indirect's. A transaction this deployment does not hold is 404 PIX-0147 too: an indirect's movements are always booked here, so JDPI is not asked. A token confined to one indirect has to name it here." examples: - 3f2504e0-4f89-41d3-9a0c-0305e82c3301 format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/TransactionStatusResponse" 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 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). A redelivery of a credit already settled here, carrying the same amount, receiving account and organization/ledger, answers 200 with the acknowledgement the first delivery got (the same idCreditoSgct and dtHrCreditoSgct) and posts nothing. 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 here for a DIFFERENT credit: another amount, another receiving account or another organization/ledger. Nothing was posted for this delivery; the original registration stays unchanged, and its settlement may still be in progress. - 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. - 500 PIX-4011 - whether the credit landed is not settled yet, typically because an earlier delivery of this end-to-end id is still being credited. Nothing more was posted; redeliver, and the redelivery that finds the credit settled gets its acknowledgement. - 500 with a dependency code - a service this participant reads through to register the credit did not answer. Section 9.3.2 lists no 503 or 504, so an outage the rest of this API answers 503/504 is answered 500 here, keeping the code and a detail that names the dependency: PIX-3007 (Access Manager timed out) and PIX-3008 (Access Manager unavailable), which authenticate the customer lookup; PIX-2020, PIX-2021 and PIX-2022 (CRM unreachable, timed out, unavailable); PIX-4000, PIX-4001, PIX-4002 and PIX-4010 (Midaz unreachable, timed out, unavailable, balance unreadable). Nothing was posted; redeliver once the dependency recovers. 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. Besides the redelivery of a settled credit above, one outcome acknowledges 200 WITHOUT any credit ever being posted: 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 "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "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: a redelivery of a devolução already registered, carrying the same amount against the same endToEndIdOriginal, answers 200 and credits nothing twice. While the devolução still awaits the original's settlement (below) that 200 is the acknowledgement the first delivery got; once the credit is booked it names that credit (its idCreditoSgct and dtHrCreditoSgct). 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. The one exception is an indirect participant's payment: its destination is that indirect's `@pi_{ispb}` settlement position, read from the indirects registry (below). A MED devolução (codigoDevolucao BE08 or FR01) is the same call: it credits the same original payer, or, when this engine never made the original payment, the account the recebedor block names, booked on the MED clearing account rather than the ordinary refund one. WHEN THIS PARTICIPANT NEVER MADE THE ORIGINAL PAYMENT — the account moved here after paying it — the devolução is still credited, because SPI has already settled it. It goes to the account the recebedor block names, resolved exactly as a cash-in to it would be, and books the amount SPI settled; it is neither capped nor parked. This is the only case that reads pagador and recebedor: a devolução of a payment made here never does, so neither block can refuse it. 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 from the original payment's record, or, when this participant never made that payment, from the recebedor resolved as a cash-in's would be — 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: - 409 PIX-0029 - this endToEndIdDevolucao was already registered here for a DIFFERENT devolução: another amount or another endToEndIdOriginal. Nothing was credited for this delivery; the original registration stays unchanged. - 422 PIX-0030 - the devolução amount is not greater than zero. - 500 PIX-4011 - whether the credit landed is not settled yet: an earlier delivery of this endToEndIdDevolucao is still being credited, or the ledger could not answer whether its credit landed. Nothing more was credited; redeliver, and the redelivery that finds the credit gets its acknowledgement. - 503 / 504 - the ledger was unreachable or timed out on the credit. Redeliver: the redelivery adopts a credit that landed rather than posting it twice. - 400 PIX-0061 - the body failed schema validation at the edge, before any lookup ran. When this participant never made the original payment, the recebedor can also refuse the credit, with the codes a cash-in to that account would get. Nothing is credited on any of them: - 400 PIX-0061 - recebedor is missing, is not a participant block, carries a malformed CPF/CNPJ or ISPB, or does not name recebedor.ispb, recebedor.cpfCnpj and recebedor.nrConta. - 404 PIX-0115 - the account the recebedor names was not found here, or pagador.ispb identifies Bacen (99999). - 404 PIX-0119 - recebedor.ispb is neither this participant's own ISPB nor an ACTIVE indirect participant registered in this tenant. - 409 PIX-0116 - recebedor.cpfCnpj names more than one account here. - 409 PIX-0117 - the addressed account 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. - 500 PIX-0120 - a provisioning fault at this participant; redeliver once it is corrected. A customer or registry lookup that fails answers 500 with nothing credited, and the devolução is safe to redeliver. For a devolução of a payment made here, none of the refusals are specific to an indirect participant: the linkage is read from the original payment rather than resolved from this request. operationId: createWebhookReversal parameters: - description: Idempotency key; JDPI sends the endToEndIdDevolucao, the key the devolução is deduplicated on. in: header name: Chave-Idempotencia schema: description: Idempotency key; JDPI sends the endToEndIdDevolucao, the key the devolução is deduplicated on. examples: - D1111111120240918150000000000099 type: string 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 "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "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 "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable "504": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Gateway Timeout 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 branch and account number and its holder document compared: no such account is AC03; a lookup that could NOT BE COMPLETED is a 500, never a verdict — an unreadable record establishes nothing about the account, and AC03 would tell the payer's PSP that a live account is absent; a document that does not match the account's holder is motivo BE01 (inconsistent data). 5. The RECEBEDOR's account, by branch and number as the credit resolves it, is then read in the ledger (even when step 3 chose the pagador block): closed is motivo AC07, blocked is motivo AC06, and an account the ledger does not hold is AC03; a ledger that could NOT BE READ is a 500, never a verdict. Coordinates naming no account or several, and every other account status, leave the account valid. 6. A devolução (creditoDevolucao) that account would accept is refused with motivo AM09 when its valor exceeds what is left to return of the payment endToEndIdOriginal names: that payment's amount less every devolução already settled against it, booked or still awaiting its payment's settlement here. A payment this participant never made is not measured, and a balance that could NOT BE READ is a 500, never a verdict. ⚠️ 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 "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "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 /v1/webhooks/validates/async: post: description: |- Receives a section 9.3.4 asynchronous validation: up to 500 credits, each a payment order JD holds on the CSM channel until this participant says whether the receiving account may take it. This operation only stores the call and answers 202 with {idValidacaoSgct, dtHrAvisoSgct}; each credit is then validated with the section 9.3.1 checks and its result registered on JD through section 8.4.12. A credit whose idConciliacaoRecebedor another order to the same receiving account holds with a Válido is answered DUPL. A Válido JD has not answered holds until it expires unsent, 45 minutes after its receipt. A Válido JD accepted holds until its credit lands, up to 24 hours. Chave-Idempotencia is the call's identity: a redelivery under the same key and the same body answers the first 202 again without a second validation, and the same key with a different body is 409. A body the edge rejects is 400; a call that could not be stored is 500 and is safe to redeliver. operationId: validateWebhookAccountAsync parameters: - description: Idempotency key of the call (section 6). in: header name: Chave-Idempotencia required: true schema: description: Idempotency key of the call (section 6). examples: - 69F963C6-7487-4363-9406-A1DE2A9636D4 maxLength: 36 minLength: 36 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AsyncValidationBody" required: true responses: "202": content: application/json: schema: $ref: "#/components/schemas/AsyncValidationResponse" description: Accepted "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Forbidden "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: Receive an asynchronous account validation tags: - Webhooks x-mint: href: /en/reference/interfaces/pix-jd/receive-an-asynchronous-account-validation 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: 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: 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 names anything but the direct participant that institution is mounted on (blank, or that participant's own ISPB, are the two accepted values — an indirect's own ISPB is never one of them); 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-0075 before any money moves. name: Limits - description: |- MED 2.0 fraud markers: 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 the client idempotency key on the `X-Idempotency` request header (required; it was a body field `idempotencyKey` until this version, and the cancel operation now takes no body at all). It is projected to a deterministic GUID before reaching JDPI (see the API description's idempotency section), so a retry with the same header value lands in the same JDPI dedup slot. name: MED Fraud Markers - description: |- MED 2.0 infraction reports: 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 the client idempotency key on the `X-Idempotency` request header (required; it was a body field `idempotencyKey` until this version, and the cancel operation now takes no body at all), projected to a deterministic GUID before reaching JDPI. name: MED Infractions - description: |- MED 2.0 value recoveries: 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 return step (POST /v1/med/recoveries/{idRecValores}/return) within the 72-hour window that approval arms. GET /v1/med/recoveries/awaiting-return 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 return step is the money-bearing action of the flow; everything else is negotiation state. Write operations take the client idempotency key on the `X-Idempotency` request header (required; it was a body field `idempotencyKey` until this version, and the return operation now takes no body at all), projected to a deterministic GUID before reaching JDPI. name: MED Recoveries - description: |- MED 2.0 refund requests: the special-return money flow itself. This participant appears in BOTH roles — as the REQUESTING PSP it opens a refund request against another PSP (POST /v1/med/refunds); as the CONTESTED PSP 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 CONTESTED PSP (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 §9.3.3 refund webhook (POST /v1/webhooks/refunds, codes BE08 and FR01) and credits the original payer. GET /v1/med/refunds/credits/{endToEndIdDevolucao} reads that credit's landing. Every write except effectuate takes the client idempotency key on the `X-Idempotency` request header — the same header the Midaz ledger takes — required, and projected to a deterministic GUID before reaching JDPI, so correlate JDPI-side logs with the projection, not the raw value you sent. It was a body field `idempotencyKey` until this version, and the cancel operation now takes no body at all. 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 (create, confirm, respond, adjust the max value, cancel), the payment schedules under them (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 reversal 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. Only JD's credential (sourceService jd-consultores) or the JD Courier's (sourceService jd-courier) may call those; any other caller is 403 PIX-0005. The §5.4 settlement legs move money — the debit posts against the paying customer, the reversal compensates it — and both are idempotent per end-to-end id with the reversal 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: |- Refund 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-0075 over the cap). GET /v1/refunds/reasons is the catalog of accepted devolution reason codes. Refunding a payment sent to another institution is refused 400 PIX-0089, or 400 PIX-0087 when the requester is the customer who sent it (ask the payee's PSP instead — or, for the special return mechanism, see MED Refunds); for any other original, a requester who is not its 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. To pay a PIX key, look it up first with GET /v1/entries/{entryId}/lookup (§8.2.14) and send its payee object and its endToEndId on the order: that pair is what makes the payment one initiated by key. A payment by key whose payee banks at the paying institution is checked against DICT before it settles: coordinates that are not the key's account are refused 422 PIX-0033 naming the field, and JDPI unavailable is 503 PIX-1050. (3) The X-Idempotency header is REQUIRED (400 PIX-0061 without it) and is the only identifier that exists BEFORE the JD call, so it is what makes a retry safe on every branch, on-us included; a resend under a key already recorded (or a reused endToEndId) is refused 409 PIX-0029 and moves no money. (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.** 400 PIX-0061 missing X-Idempotency header; 409 PIX-0029 duplicate endToEndId/X-Idempotency key; 409 PIX-0076 insufficient balance on the paying position; 409 PIX-0075 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. Only JD's credential (sourceService jd-consultores) or the JD Courier's (sourceService jd-courier) may call these routes; any other caller is 403 PIX-0005. **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 refund of a payment this participant SENT: JD has already executed the return when this arrives. A MED refund (codes BE08 and FR01) arrives on the same route and credits the same original payer, booked on the MED clearing account. 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 refund 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, AC07 / AC06 for an account its ledger holds closed / blocked. An HTTP error from this route means infrastructure, never "account invalid". name: Webhooks