Pix

Register a Pix key via the sponsor's DICT access

Register a Pix key (EMAIL/PHONE/CPF/CNPJ, or sponsor-minted EVP) for a CUSTOMER account. A sponsor rejection still returns 201 with the key row in REGISTRATION_FAILED — portability starts from that row.

Requires an Idempotency-Key header.

Parâmetros

Corpo da requisição

PixKeyRegisterRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Exclude a Pix key from the DICT

Exclude an ACTIVE key (idempotent: re-DELETE of an EXCLUDED key returns 200). The ledger identity row is released — the same normalized key can be registered again on a fresh key row.

Parâmetros

Respostas

Cancel the key's active claim

Cancel the active claim on this key (either role).

Parâmetros

Respostas

Open a portability claim (we are the claimer)

Start portability for a key whose registration failed because the key is owned elsewhere (REGISTRATION_FAILED row). Requires Idempotency-Key.

Parâmetros

Respostas

Confirm the key's active claim

Confirm the active claim on this key. Serves both roles — as DONOR it lets the claim proceed; the record's role field disambiguates.

Parâmetros

Respostas

Sponsor DICT key-event ingest

Ingest provider key events (KEY_* / CLAIM_*). Authenticated by the verification strategy the `{provider_id}` binding selects, against that provider's own secret (LaaS-39 D4 — this route previously used a static body HMAC with no timestamp and therefore no replay bound at all). Redelivery-idempotent via a DEDUPE# row; out-of-order events no-op on the state guards (AC4).

Parâmetros

Respostas

Pre-payment DICT lookup

Look up a Pix key in the DICT via the sponsor: recipient display name, masked tax id, participant, and fraud markers (D8). Persists nothing — no database dependency at all; sponsor unreachable or unset → 503 (a directory read has no meaningful stub).

Parâmetros

Respostas

Authorize a Pix Automático mandate (relayed to the sponsor)

Parâmetros

Respostas

Cancel a pending mandate charge pre-debit (relayed to the sponsor)

Parâmetros

Respostas

Reject a pending Pix Automático mandate

Parâmetros

Respostas

Revoke an ACTIVE mandate (releases holds, cancels pending charges)

Parâmetros

Respostas

Sponsor Pix Automático mandate/charge event ingest

Ingest provider mandate events (MANDATE_* / CHARGE_*). Authenticated by the verification strategy the `{provider_id}` binding selects, against that provider's own secret (LaaS-39 D4 — this route previously used a static body HMAC with no timestamp and therefore no replay bound at all). Redelivery-idempotent via a DEDUPE# row; out-of-order events no-op on the state guards.

Parâmetros

Respostas

File a MED infraction with the sponsor

Open an OUTBOUND MED case for our customer's claim and file it with the sponsor synchronously (LaaS-16 D10). A sponsor timeout leaves the case FILING and returns 503 — the Idempotency-Key retry re-files the same case_id, which the sponsor dedupes.

Parâmetros

Corpo da requisição

MedCaseCreateRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Resolve a MED case (RETURN or RELEASE)

RETURN executes the devolução: the block is captured to the clearing account and the capture obligation rides the deferred-dispatch lifecycle to the sponsor's return API (D8). RELEASE answers the sponsor and lifts the block. Single-shot per block — concurrent resolvers lose with 409.

Parâmetros

Corpo da requisição

MedCaseResolveRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Sponsor MED case-event receiver (infractions)

Authenticated receiver for provider MED infraction/case notifications (LaaS-16 D2; per-provider since LaaS-39). Case events are NOT evidence — an infraction moves nothing at ingest — so they land here instead of the evidence pipe. Authenticated by the verification strategy the `{provider_id}` binding selects, against that provider's own secret; 2xx-on-applied.

Parâmetros

Respostas

Create a dynamic Pix QR (sponsor-hosted single-use charge)

Create a single-use dynamic charge: Core mints the txid, the sponsor creates + hosts the JWS location document, Core persists the PIXQR# row and composes the EMV envelope locally (D3). Requires an ACTIVE Ticket-14 key owned by the account (defaulted when there is exactly one).

Requires an Idempotency-Key header.

Parâmetros

Corpo da requisição

PixQrDynamicCreateRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Decode a scanned BR Code payload

Parse + validate any scanned BR Code locally (TLV + CRC); dynamic payloads are resolved through the sponsor — Core never fetches scanned URLs (D7). Persists nothing; malformed input -> 422 INVALID_BRCODE with a structured reason.

Corpo da requisição

PixQrDecodeRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Initiate a devolução of a received Pix credit

Return (part of) a Pix credit this account received (LaaS-16 D4): a new counter-obligation on the deferred-dispatch lifecycle, referencing the original's E2EID. Partial and multiple returns are allowed, cumulatively capped at the original amount. Requires an Idempotency-Key header.

Parâmetros

Corpo da requisição

PixReturnRequest — obrigatório. Os campos estão listados em Esquemas, abaixo.

Respostas

Sponsor Pix inbound webhook receiver

Authenticated receiver for provider Pix webhooks (LaaS-12; per-provider since LaaS-39).

Unauthenticated at the API Gateway (authorization_type=NONE — providers cannot do Cognito client-credentials); authenticated in-handler by the verification strategy the `{provider_id}` binding selects, against that provider's own secret. The default strategy is `timestamped_hmac_v1` — LaaS-12's D6 contract, unchanged — inside a ±300 s freshness window. Routes the raw provider payload through the same in-process pipeline as ``POST /v1/evidence`` and returns a minimal ack; obligation internals never leak to the provider, and a rejection never says which check failed.

Parâmetros

Respostas