Confirm a disbursement already paid to the worker

curl --request POST \
  --url https://consignado.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"
}
'

import requests

url = "https://consignado.sandbox.lerian.net/v1/consignado/contracts/{numero_contrato}/disbursement-confirmation"

payload = {
    "amount": "2000.00",
    "paid_at": "2026-08-01T12:00:00Z",
    "payment_reference": "E32074986202608011200A1B2C3D4E5F"
}
headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: '2000.00',
    paid_at: '2026-08-01T12:00:00Z',
    payment_reference: 'E32074986202608011200A1B2C3D4E5F'
  })
};

fetch('https://consignado.sandbox.lerian.net/v1/consignado/contracts/{numero_contrato}/disbursement-confirmation', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://consignado.sandbox.lerian.net/v1/consignado/contracts/{numero_contrato}/disbursement-confirmation",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => '2000.00',
    'paid_at' => '2026-08-01T12:00:00Z',
    'payment_reference' => 'E32074986202608011200A1B2C3D4E5F'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-Idempotency: <x-idempotency>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://consignado.sandbox.lerian.net/v1/consignado/contracts/{numero_contrato}/disbursement-confirmation"

	payload := strings.NewReader("{\n  \"amount\": \"2000.00\",\n  \"paid_at\": \"2026-08-01T12:00:00Z\",\n  \"payment_reference\": \"E32074986202608011200A1B2C3D4E5F\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://consignado.sandbox.lerian.net/v1/consignado/contracts/{numero_contrato}/disbursement-confirmation")
  .header("X-Idempotency", "<x-idempotency>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": \"2000.00\",\n  \"paid_at\": \"2026-08-01T12:00:00Z\",\n  \"payment_reference\": \"E32074986202608011200A1B2C3D4E5F\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://consignado.sandbox.lerian.net/v1/consignado/contracts/{numero_contrato}/disbursement-confirmation")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Idempotency"] = '<x-idempotency>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": \"2000.00\",\n  \"paid_at\": \"2026-08-01T12:00:00Z\",\n  \"payment_reference\": \"E32074986202608011200A1B2C3D4E5F\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

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.

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	whatever the shared middleware wrote

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

consignado

contracts

{numero_contrato}

disbursement-confirmation

Confirm a disbursement already paid to the worker

curl --request POST \
  --url https://consignado.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"
}
'

import requests

url = "https://consignado.sandbox.lerian.net/v1/consignado/contracts/{numero_contrato}/disbursement-confirmation"

payload = {
    "amount": "2000.00",
    "paid_at": "2026-08-01T12:00:00Z",
    "payment_reference": "E32074986202608011200A1B2C3D4E5F"
}
headers = {
    "X-Idempotency": "<x-idempotency>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency': '<x-idempotency>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: '2000.00',
    paid_at: '2026-08-01T12:00:00Z',
    payment_reference: 'E32074986202608011200A1B2C3D4E5F'
  })
};

fetch('https://consignado.sandbox.lerian.net/v1/consignado/contracts/{numero_contrato}/disbursement-confirmation', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://consignado.sandbox.lerian.net/v1/consignado/contracts/{numero_contrato}/disbursement-confirmation",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => '2000.00',
    'paid_at' => '2026-08-01T12:00:00Z',
    'payment_reference' => 'E32074986202608011200A1B2C3D4E5F'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-Idempotency: <x-idempotency>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://consignado.sandbox.lerian.net/v1/consignado/contracts/{numero_contrato}/disbursement-confirmation"

	payload := strings.NewReader("{\n  \"amount\": \"2000.00\",\n  \"paid_at\": \"2026-08-01T12:00:00Z\",\n  \"payment_reference\": \"E32074986202608011200A1B2C3D4E5F\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency", "<x-idempotency>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://consignado.sandbox.lerian.net/v1/consignado/contracts/{numero_contrato}/disbursement-confirmation")
  .header("X-Idempotency", "<x-idempotency>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": \"2000.00\",\n  \"paid_at\": \"2026-08-01T12:00:00Z\",\n  \"payment_reference\": \"E32074986202608011200A1B2C3D4E5F\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://consignado.sandbox.lerian.net/v1/consignado/contracts/{numero_contrato}/disbursement-confirmation")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Idempotency"] = '<x-idempotency>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": \"2000.00\",\n  \"paid_at\": \"2026-08-01T12:00:00Z\",\n  \"payment_reference\": \"E32074986202608011200A1B2C3D4E5F\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "ERR-0001",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Authorizations

Authorization

string

header

required

JWT bearer token issued by the identity provider.

Headers

X-Idempotency

string

required

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

Example:

"idem-desembolso-0001"

Path Parameters

numero_contrato

string

required

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. Nothing looks it up — an orphan confirmation for a contract this deployment never registered is first-class.

Required string length: 1 - 15

Example:

"99999999999AN1"

Body

application/json

amount

string

required

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

Example:

"2000.00"

paid_at

string

required

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

Example:

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

payment_reference

string

required

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

Example:

"E32074986202608011200A1B2C3D4E5F"

Response

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

required

The confirmed amount, echoed verbatim.

Example:

"2000.00"

confirmation_id

string

required

The gateway's identity for this immutable confirmation.

Example:

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

confirmed_at

string

required

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

Example:

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

numero_contrato

string

required

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

Example:

"99999999999AN1"

paid_at

string

required

When the money was paid, echoed verbatim.

Example:

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

payment_reference

string

required

The client's payment reference, echoed verbatim.

Example:

"E32074986202608011200A1B2C3D4E5F"

⌘I

Pix — Lerian SPI (native messaging)

Pix — JD (interface, direct)

Pix — BTG (interface, indirect)

TED — Lerian SPB (native messaging)

TED — JD (interface)

Boletos — BTG (interface)

Lerian SILOC (native messaging)

Lerian SLC (native messaging)

Lerian STA (native messaging)

Lerian SISBAJUD (native messaging)

Lerian Consignado — Dataprev

Confirm a disbursement already paid to the worker

Authorizations

Headers

Path Parameters

Body

Response