Send a TED (or internal transfer)
Sends a TED to another institution or, if the recipient is in your own institution, an internal transfer. The recipient’s bank (recipient.bankId or recipient.bankCode) decides the path.
Send X-Account-Id with the debited account and X-Idempotency with a new key for each payment. The service validates the request and applies the institution policy (window, limits, fee). Then it holds the amount plus the fee and sends the TED to the STR. Settlement is asynchronous: track it with GET /v1/transfers/{transferId} or with the transfer.* events.
status in the 201 response | Meaning |
|---|---|
SUBMITTED | The rail accepted the TED and sent it to the STR. Wait for SETTLED or REJECTED |
SETTLED | Internal transfer (type=INTERNAL) already settled in the ledger, with recipient.accountId filled in |
REJECTED | Synchronous refusal from the ledger or the rail; the hold was released. Example: insufficient balance, rejection.code=TED-0031 |
AWAITING_RECONCILIATION / CREATED | Undetermined outcome (no conclusive response from the rail or the ledger); automatic reconciliation resolves it. Do not resend with another key |
Validation and policy refusals return 4xx/503 without creating a resource: fix the request and resend it with a new key. The exception is a retry whose first attempt got no answer: a refusal does not show that the first attempt created nothing. Look up the transfer before you send it with a new key: GET /v1/transfers filtered by client_reference (the clientReference you sent), or by account_id and a start_date/end_date range (UTC) that covers the first attempt. The key stays bound to the transfer it created, so a later request with the same key never creates a second transfer. If the internal recipient is not in the organization’s registry, the response is 422 TED-1021. A materially identical request sent shortly after another one can return 409 TED-0014, even with another key.
Authorizations
JWT token that the Lerian Access Manager issues for your institution. Send it in Authorization: Bearer <token> on every call (except the public health probes). The tenant never comes from the body, the query, or the path. Each operation requires a role with the matching permission (see the API overview). Without it, 403 TED-0071. Missing, invalid, or expired token: 401 TED-0070.
Headers
Identifier (UUID) of the customer account in your own institution that starts the operation: the debited account in a send request or a quote. It goes in the header, never in the body. The account must belong to the organization that the token resolves. A missing or malformed value returns 400 TED-0008; an account from another organization returns 403 TED-0009.
Idempotency key that the integrator creates (1 to 128 printable ASCII characters, no spaces; we recommend a UUID). Required on every operation with an effect. Send the SAME key again when you retry a call that failed because of a timeout or network error. Same key + same body returns the original response with X-Idempotency-Replayed: true and no new effect. Same key + different body responds 422 TED-0012. Same key still in processing responds 409 TED-0013 (retry after Retry-After). Missing or in the wrong format: 400 TED-0011.
Correlation identifier of this request (UUID). Optional: when you omit it, or when the value is not a well-formed UUID, the platform creates a UUID and returns it in the X-Request-Id header of the response. The resolved identifier goes to the logs, spans, and audit events of this request. Keep it to open a support ticket.
Body
Request to send a TED or an internal transfer. The debited account does NOT go in the body: the X-Account-Id header identifies it. The recipient's bank decides the path (TED or INTERNAL): another institution → TED through the STR; your own institution → internal transfer settled in the ledger.
Amount in BRL as a decimal string, not a JSON number: digits only, with a dot as the decimal separator, up to 16 significant integer digits and at most 2 significant decimal places, with no sign or exponent. Leading and trailing spaces are ignored (e.g., "1500.00"; "1500.000" is equal to 1500.00).
"1500.00"
Purpose code of the TED (FinlddCli Domain Dictionary, 5 digits).
^[0-9]{5}$"00001"
Recipient: bank (ISPB or COMPE), branch, account, account type, name, and document.
Requester reference (up to 64 characters). Queries and events return it, and you can use it as a filter in GET /v1/transfers?client_reference=.
64"PED-2026-000123"
Transfer description (up to 140 characters). Required when purposeCode=99999 (other).
140"Supplier payment"
Free key-value pairs from the requester, returned verbatim in queries and events. Never sent to the STR or to other external systems.
Response
Transfer recorded. Read status: SUBMITTED (TED accepted by the rail; settlement through the STR is asynchronous), SETTLED (internal transfer settled), REJECTED (synchronous refusal from the ledger or the rail; see rejection), AWAITING_RECONCILIATION (TED) or CREATED (internal transfer): undetermined outcome; automatic reconciliation resolves it. If X-Idempotency-Replayed: true, this is the replay of an earlier transfer creation.
Representation of an outgoing (TED) or internal transfer. The create, query, and list operations return it, and so do the cancel and unblock actions. Track the lifecycle through the status field and the instants reservedAt/submittedAt/settledAt. When status=REJECTED, rejection tells you who refused it and why.
Amount in BRL as a decimal string with two decimal places.
^(0\.(0[1-9]|[1-9][0-9])|[1-9][0-9]{0,11}\.[0-9]{2})$"1500.00"
Time (UTC) of creation.
Fee charged at sending, in BRL (0.00 when exempt).
^(0|[1-9][0-9]{0,11})\.[0-9]{2}$"0.00"
Purpose code given in the send request (FinlddCli, 5 digits).
^[0-9]{5}$"00001"
Recipient sent when the transfer was created. In an internal transfer it includes accountId.
Source account, always in your own institution (includes accountId).
Current state (published as a free string: handle unknown values with tolerance). Current values: CREATED, RESERVED, SUBMITTED, PENDING_STR, SETTLED, REJECTED, CANCELLED, AWAITING_RECONCILIATION, EXHAUSTED. TED: CREATED → RESERVED (amount + fee on hold) → SUBMITTED (sent to the STR) → SETTLED | REJECTED; PENDING_STR when the STR keeps the entry pending; AWAITING_RECONCILIATION and EXHAUSTED when the outcome could not be confirmed automatically; CANCELLED on a cancellation before submission or of a confirmed pending entry. INTERNAL: CREATED → SETTLED | REJECTED in the same call. Terminal: SETTLED, REJECTED, CANCELLED.
Amount + fee: the total debited (on hold) from the source account, in BRL.
^(0|[1-9][0-9]{0,11})\.[0-9]{2}$"1500.00"
Transfer identifier. Use it in queries and actions.
TED (another institution, through the STR) or INTERNAL (same institution, settled in the ledger).
TED, INTERNAL Time (UTC) of the last write to the record. This is not always a status change. ⚠️ An INTERNAL transfer can stay in CREATED because the ledger response was undetermined. In that case, the reprocessor uses updatedAt as the queue position on each new attempt, and it moves a transfer whose resend window expired one hour ahead: updatedAt CAN BE IN THE FUTURE (up to 1 h after the current time). Do not use it as a transition time.
Requester reference sent with the transfer request.
64Description given in the send request.
140Free-form key-value pairs from the requester, kept verbatim. Never sent to external systems.
Identifier of the entry assigned by the STR (20 characters, XXXAAAAMMDDnnnnnnnnn).
^[A-Za-z0-9]{20}$SPB identifier of the operation, 23 digits. It can be absent even in status=SUBMITTED. In that case, correlate by railOperationId.
^[0-9]{23}$Identifier of the operation in the rail (after acceptance).
Present only when status=REJECTED.
Instant (UTC) when the amount and fee were put on hold in the source account. Start of the 30-min regulatory deadline for submission.
Return received for this outgoing TED (credit back to the sender). Requires status=SETTLED and a LATER return from the recipient institution. For this reason it never appears in the creation response or in the list items, only in GET /v1/transfers/{transferId}.
Instant of settlement. Exists only from status=SETTLED.
Timestamp (UTC) when the rail accepted the TED for sending to the STR.