Reconcile charge

Admin-only endpoint that concludes a charge from a settlement receipt the rail could not attribute on its own. The receipt’s endToEndId and valor are required.

POST /api/v1/brcode/charges/reconcile

Reconcile charge

cURL

curl --request POST \
  --url https://spi.sandbox.lerian.net/api/v1/brcode/charges/reconcile \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "endToEndId": "E46026562202608201345ABCDEF12345",
  "txId": "txid-cobv-001",
  "valor": "199.90",
  "cnpj": "12ABC34501DE35",
  "cpf": "12345678901"
}
'

200

{
  "amount": "250.00",
  "chargeType": "COB",
  "createdAt": "2025-03-07T14:30:00Z",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "merchantCity": "São Paulo",
  "merchantName": "Lerian Studio",
  "pixKey": "12345678901",
  "status": "ATIVA",
  "txId": "txid-cobv-001",
  "updatedAt": "2025-03-07T14:30:00Z",
  "dueAt": "2025-03-15T23:59:59Z",
  "expiresAt": "2025-03-08T23:59:59Z",
  "paidAt": "2025-03-08T10:15:00Z",
  "payloadLocation": "pix.example.com/qr/v2/txid-cobv-001",
  "rawPayload": "00020126580014br.gov.bcb.pix..."
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Body

application/json

endToEndId · string · required

End-to-end id of the settled Pix, read off the receipt being reconciled. Obligatory: a conclusion that names no payment cannot appear on the Febraban settlement statement, whose record identity is this id.

Pattern: ^E[0-9A-Z]{8}\d{12}[a-zA-Z0-9]{11}$

Example:

"E46026562202608201345ABCDEF12345"

txId · string · required

Transaction identifier of the charge to mark as paid, shaped as BACEN's TxIdType ([a-zA-Z0-9]{1,35}). It accepts the 1..35 form, not only the 26..35 form a cobrança is created with.

Pattern: ^[a-zA-Z0-9]{1,35}$

Example:

"txid-cobv-001"

valor · string · required

Amount that settled, in BRL as a decimal string with scale 2, as shown on the receipt. Shaped as BACEN's monetary pattern \d{1,10}.\d{2}, with a dot separator and no thousands separator. The service checks the 0.01..9999999999.99 range. Recorded verbatim and never compared against the charge amount (any-value Pix concludes a charge).

Pattern: ^[0-9]{1,10}\.[0-9]{2}$

Example:

"199.90"

cnpj · string

Recebedor qualifier (CNPJ), required only when txId is shared by more than one recebedor.

Pattern: ^[0-9A-Z]{14}$

Example:

"12ABC34501DE35"

cpf · string

Recebedor qualifier (CPF), required only when txId is shared by more than one recebedor.

Pattern: ^\d{11}$

Example:

"12345678901"

Response

200

application/json

OK

amount · string · required

Original charge amount in BRL as a decimal string, scale 2.

Example:

"250.00"

chargeType · string · required

Charge type: COB (immediate), COBV (due-date), or LoteCobV batch item.

Example:

"COB"

createdAt · string · required

Creation timestamp in RFC3339 UTC.

Example:

"2025-03-07T14:30:00Z"

id · string · required

Server-assigned charge identifier (UUID).

Example:

"550e8400-e29b-41d4-a716-446655440000"

merchantCity · string · required

Merchant city on the charge.

Example:

"São Paulo"

merchantName · string · required

Merchant legal/trade name on the charge.

Example:

"Lerian Studio"

pixKey · string · required

Pix key of the receiver settling the charge.

Example:

"12345678901"

status · string · required

Charge lifecycle status (ATIVA, CONCLUIDA, REMOVIDA_PELO_USUARIO_RECEBEDOR, REMOVIDA_PELO_PSP).

Example:

"ATIVA"

txId · string · required

Merchant transaction identifier for the charge.

Example:

"txid-cobv-001"

updatedAt · string · required

Last-update timestamp in RFC3339 UTC.

Example:

"2025-03-07T14:30:00Z"

dueAt · string

Due date for due-date charges (COBV) as an RFC3339 UTC timestamp; null for immediate charges.

Example:

"2025-03-15T23:59:59Z"

expiresAt · string

Immediate-charge (COB) expiry as an RFC3339 UTC timestamp; null when not applicable.

Example:

"2025-03-08T23:59:59Z"

paidAt · string

Settlement timestamp as an RFC3339 UTC timestamp; null until the charge is reconciled as paid.

Example:

"2025-03-08T10:15:00Z"

payloadLocation · string

Payload location carried by the dynamic charge QR, without protocol prefix; resolvable over HTTPS only. Empty when unavailable.

Example:

"pix.example.com/qr/v2/txid-cobv-001"

rawPayload · string

Raw EMV copy-and-paste payload string for the charge (empty when unavailable).

Example:

"00020126580014br.gov.bcb.pix..."