Confirm a disbursement already paid to the worker

Records the gateway’s own durable fact that a client bank ALREADY paid a worker. This is NOT a Dataprev operation: no rail credential is used, no government boundary is crossed, and Dataprev publishes no disbursement-confirmation operation to proxy. The gateway records what the client asserted; it asks no downstream product whether the payment is plausible.

It accepts ORPHAN confirmations — money for a contract this deployment never registered locally — and a contract may be disbursed in MORE THAN ONE payment. The identity of a confirmation is (tenant, numero_contrato, payment_reference), so a second payment under a different reference on the same contract is a first acceptance with its own fact, never a conflict.

receipt_pdf_base64 is an optional PDF receipt of the payment, retained for five years. It can be sent only with the first acceptance of the payment: there is no late attachment, so a new key carrying a receipt over a confirmation that has none is refused. Under the same key the receipt is part of the request, absent included: a retry that adds, drops or changes it is 422 IDEMPOTENCY_KEY_REUSE. The 202 then carries receipt_digest_sha256, the SHA-256 of the decoded PDF; the file is read back from the receipt route.

X-Idempotency is mandatory, opaque, 1..128 bytes, and never defaulted. Two keys differing in one byte are two keys, and there is no X-Idempotency-Key alias.

Case	Status	X-Idempotency-Replayed
First acceptance	202	absent
Same key, same request, served from the transport cache	202, the identical bytes	true
Same key, same request, served from the durable authority	202, the identical bytes	absent
Same key, divergent request	422 — never the earlier body	whatever the shared middleware wrote
New key, same payment	202, the same body	absent
New key, same payment reference, different money	409 DISBURSEMENT_PAYMENT_CONFLICT	whatever the shared middleware wrote
New key, same payment, a receipt over a confirmation without one, or a different receipt	409 DISBURSEMENT_RECEIPT_CONFLICT	whatever the shared middleware wrote
New key, same payment, no receipt over a confirmation that has one	202, the stored body with its receipt_digest_sha256	absent

PostgreSQL is the authority on every row. The transport idempotency cache is a best-effort accelerator over it, in BOTH directions: whether that cache fails before the request is decided or after the confirmation is already committed, the answer is the durable one and the only difference on the wire is that the replay header is absent. A cache failure never turns a recorded payment into a 503. That is a different failure from a shared Redis outage, which the tenant rate limiter refuses first.

POST /v1/consignado/contracts/{numero_contrato}/disbursement-confirmation

Confirm a disbursement already paid to the worker

cURL

curl --request POST \
  --url https://br-consignado-gw.sandbox.lerian.net/v1/consignado/contracts/{numero_contrato}/disbursement-confirmation \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "amount": "2000.00",
  "paid_at": "2026-08-01T12:00:00Z",
  "payment_reference": "E32074986202608011200A1B2C3D4E5F",
  "receipt_pdf_base64": "JVBERi0xLjQKJSVFT0YK"
}
'

202

{
  "amount": "2000.00",
  "confirmation_id": "1f5b9c26-6f5a-4f77-9c1c-5d1c0f0a9b21",
  "confirmed_at": "2026-08-01T12:00:05Z",
  "numero_contrato": "99999999999AN1",
  "paid_at": "2026-08-01T12:00:00Z",
  "payment_reference": "E32074986202608011200A1B2C3D4E5F",
  "receipt_digest_sha256": "46b2310890f1ad382ef36f9bc9d0afeb7e33140b83df9d217db1944778c93bb6"
}

Autorizaciones

Authorization · string · header · requerido

JWT bearer token issued by the identity provider.

Encabezados

X-Idempotency · string · requerido

Mandatory opaque replay key, 1..128 bytes of valid UTF-8, preserved byte for byte. There is no default, no X-Idempotency-Key alias, no case folding and no normalization: two keys differing in one byte are two keys.

Required string length: 1 - 128

Ejemplo:

"idem-desembolso-0001"

Parámetros de ruta

numero_contrato · string · requerido

The rail contract number the money was paid against (Manual 004 §2.2.2 p.18: Texto, 15). Exact, control-free UTF-8, bounded in BYTES: no trimming and no case folding. Read to name the contract's originador and fund on the confirmation fact and to mark orphans on the list; it never refuses a confirmation — an orphan for a contract this deployment never registered is first-class and its fact goes out without parties.

Required string length: 1 - 15

Ejemplo:

"99999999999AN1"

Cuerpo

application/json

amount · string · requerido

The BRL amount already paid to the worker, as a canonical positive decimal string matching ^[1-9][0-9]*.[0-9]{2}$ (at most 13 bytes). A string, never a JSON number: money never passes through a float.

Maximum string length: 13

Ejemplo:

"2000.00"

paid_at · string · requerido

When the money was paid, strict RFC 3339 UTC with a literal Z (2026-08-01T12:00:00Z). Exactly one spelling per instant: a +00:00 offset, a lowercase z, fractional seconds or a missing zone are refused, never normalized.

Maximum string length: 20

Ejemplo:

"2026-08-01T12:00:00Z"

payment_reference · string · requerido

The client's opaque payment reference — a Pix EndToEndId, a TED protocol number, an internal settlement id. Valid UTF-8, 1..256 bytes, preserved byte for byte with no trimming, case folding or normalization.

Maximum string length: 256

Ejemplo:

"E32074986202608011200A1B2C3D4E5F"

receipt_pdf_base64 · string | null

Optional PDF receipt of the payment, RFC 4648 section 4 base64 with canonical padding: no line breaks, no data: prefix, no non-zero pad bits. The decoded file starts with %PDF-, ends with %%EOF and holds 1..3145728 bytes. Retained for five years; it can be sent only with the first acceptance of the payment and never attached later. Absent or null means no receipt; an empty string is refused.

Required string length: 1 - 4194304

Ejemplo:

"JVBERi0xLjQKJSVFT0YK"

Respuesta

202

application/json

The confirmation is durably recorded. A replay of the same payment — under the same key or a new one — answers with the identical body.

amount · string · requerido

The confirmed amount, echoed verbatim.

Ejemplo:

"2000.00"

confirmation_id · string · requerido

The gateway's identity for this immutable confirmation.

Ejemplo:

"1f5b9c26-6f5a-4f77-9c1c-5d1c0f0a9b21"

confirmed_at · string · requerido

When the gateway durably recorded the confirmation, strict RFC 3339 UTC.

Ejemplo:

"2026-08-01T12:00:05Z"

numero_contrato · string · requerido

The rail contract number the confirmation was addressed to, echoed from the path.

Ejemplo:

"99999999999AN1"

paid_at · string · requerido

When the money was paid, echoed verbatim.

Ejemplo:

"2026-08-01T12:00:00Z"

payment_reference · string · requerido

The client's payment reference, echoed verbatim.

Ejemplo:

"E32074986202608011200A1B2C3D4E5F"

receipt_digest_sha256 · string

Lowercase hex SHA-256 of the decoded receipt PDF. Present only when the confirmation has a receipt.

Ejemplo:

"46b2310890f1ad382ef36f9bc9d0afeb7e33140b83df9d217db1944778c93bb6"