> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Initiate a Transfer > Use this endpoint to initiate a transfer by validating sender data, checking operating hours and usage limits, detecting duplicates, and calculating the fee. No funds are held at this step. The returned initiationId is valid for 24 hours and must be confirmed via the Process Transfer endpoint. Use the `X-Idempotency` header for guaranteed deduplication. ## OpenAPI ````yaml /pt/openapi/v3-current/ted.yaml post /v1/transfers/initiate openapi: 3.0.3 info: title: Bank Transfer (TED) Plugin API description: >- Complete API for Brazilian bank transfers (TED OUT, TED IN, P2P) through the Lerian platform, including transfer initiation, processing, status tracking, cancellation, and returns. version: 3.4.0 servers: - url: https://api.example.com description: >- Replace the example host with the URL provided during environment onboarding. security: - BearerAuth: [] - OAuth2ClientCredentials: - api - OAuth2Password: - api tags: - name: Transfers API description: >- Endpoints for initiating, processing, tracking, cancelling, and returning transfers. - name: Webhooks description: >- Endpoints for registering and managing tenant-scoped webhook subscriptions for transfer events. - name: Webhook DLQ description: Endpoints for inspecting and retrying webhook dead-letter queue messages. paths: /v1/transfers/initiate: post: tags: - Transfers API summary: Initiate a Transfer description: >- Use this endpoint to initiate a transfer by validating sender data, checking operating hours and usage limits, detecting duplicates, and calculating the fee. No funds are held at this step. The returned initiationId is valid for 24 hours and must be confirmed via the Process Transfer endpoint. Use the `X-Idempotency` header for guaranteed deduplication. operationId: initiateTransfer parameters: - $ref: '#/components/parameters/XOrganizationId' - $ref: '#/components/parameters/XIdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InitiateTransferRequest' examples: tedOut: summary: TED OUT to external bank value: senderAccountId: 019c96a0-0c0c-7221-8cf3-13313fb60081 recipient: ispb: '00000000' branch: '0001' account: '1234567890' accountType: CACC holderName: João Silva holderDocument: '12345678901' amount: 1000.5 description: Payment for services metadata: invoiceId: INV-2024-001 p2p: summary: P2P (same institution) value: senderAccountId: 019c96a0-0c0c-7221-8cf3-13313fb60081 recipient: ispb: '12345678' branch: '0001' account: '9876543210' accountType: CACC holderName: Maria Santos holderDocument: '98765432100' amount: 500 description: Transfer to friend responses: '200': description: >- Indicates that the transfer was initiated successfully and is awaiting confirmation. Repeated calls with the same `X-Idempotency` key replay the cached response. See [Retries and idempotency](/pt/reference/retries-idempotency) for more details. content: application/json: schema: $ref: '#/components/schemas/InitiateTransferResponse' examples: success: summary: Initiation with fee value: initiationId: 019c96a0-aa10-7abc-d1e2-8c9d0e1f2a3b feeAmount: 1.5 totalAmount: 1002 estimatedCompletionAt: '2026-02-01T18:00:00-03:00' expiresAt: '2026-02-02T15:30:00-03:00' status: PENDING_CONFIRMATION freeTransfer: summary: No fee configured value: initiationId: 019c96a0-aa20-7bcd-e1f2-9d0e1f2a3b4c feeAmount: 0 totalAmount: 1000.5 estimatedCompletionAt: '2026-02-01T18:00:00-03:00' expiresAt: '2026-02-02T15:30:00-03:00' status: PENDING_CONFIRMATION '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/AccountNotFound' '409': description: >- BTF-0012: an identical transfer was detected inside the deduplication window. BTF-0016: a request under this `X-Idempotency` key still holds the in-flight lease, because it is still running or because it already ended 5xx and recorded no outcome. `Retry-After` carries a poll interval, not the lease. While the first request is still running, resend the identical request after that interval; the answer replays from the first request as soon as it finishes. If an earlier request under this key answered 5xx without `X-Idempotency-Fenced: true`, no answer will ever be served from it: stop resending, read the resource this route acts on, and send the work under a new `X-Idempotency` key only if it did not land. The detail also names the 15-minute bound after which the lease lapses and a resend runs the work a second time; a poll still unanswered by then ends the same way. BTF-0018: the request under this `X-Idempotency` key already completed, and its response was too large to store for replay. Read the resource. Do not resend under a new key, because that runs the work a second time. This answer carries no `Retry-After`, because no wait produces the missing receipt. headers: Retry-After: $ref: '#/components/headers/RetryAfter' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDocument' examples: duplicate: summary: Same transfer submitted twice value: type: https://errors.lerian.studio/v1/BTF-0012 title: Conflict status: 409 detail: duplicate transfer detected code: BTF-0012 category: deterministic requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f service: plugin '422': description: >- BTF-0010: the transfer was attempted outside BACEN operating hours. BTF-0002: the request failed domain validation. BTF-0013: a database constraint refused the write. BTF-0004: this tenant cannot make this internal transfer. `reason` says why: `cross_organization` (the two accounts are in different Midaz organizations), `cross_ledger_disabled` (transfers between two ledgers of one organization are not enabled for this tenant) or `cross_ledger_flag_unreadable` (that setting could not be read; a later retry can succeed). Nothing was priced, held or written. BTF-0005: a transfer between two ledgers is not available. `reason` is `fee_mode_legacy` (the fee mode is not `native`) or `ledger_platform_below_minimum` (the Midaz ledger is older than 4.2.0). BTF-0006: a ledger of the transfer does not accept postings between ledgers. `reason` is `ledger_not_enabled`, and `ledgerId` names the ledger. BTF-0007: the two accounts hold different assets. `reason` is `asset_mismatch`. BTF-3003: the fee package of the source ledger takes the fee out of the amount. A transfer between two ledgers needs a source package that charges the fee on top. `reason` is `source_fee_deductible`. Nothing was reserved or written. BTF-4003: the recipient is on the ISPB of this institution, which this tenant shares with another engine, and the ownership map of the JD Courier says that no engine holds the account. Nothing was priced, held or written. BTF-4004: the recipient account in the request cannot be keyed for the ownership map: a blank account, a blank branch on an account that is not a payment account, or a value that the JD Courier refuses to normalize. Correct the request. A retry does not help. BTF-3002: the fee package that matches this TED OUT, or the package on the cross-core out route for a cross-core TED, takes the fee out of the amount. A TED OUT charges its fee on top of the amount, so the package must be non-deductible. Nothing was held or written. BTF-2005: the fee engine of the Midaz ledger refused to preview the fee, for example a deductible fee larger than the amount or two fee packages that tie. Nothing was held or written. BTF-0008: the `feeContext` is not accepted. No fee package on the payer's ledger selects on it, enabled or not, or the ledger does not price fees natively. Nothing was priced, held or written. BTF-0014: an earlier request under this `X-Idempotency` key answered 5xx, so the key is fenced for the retention window. Read the resource and, only if the work did not land, send the identical request under a new key. BTF-0015: this service cannot read the idempotency record under this key. The remedy is the same. BTF-0017: this `X-Idempotency` key was already used for a different request. A repeat must be byte-identical, and a new request needs its own new key. BTF-0017 is decided before BTF-0014, so a fenced key resent with a changed body gets BTF-0017. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDocument' examples: outsideHours: summary: After 17:00 value: type: https://errors.lerian.studio/v1/BTF-0010 title: Unprocessable Entity status: 422 detail: >- transfers can only be initiated Monday-Friday between 06:30 and 17:00 America/Sao_Paulo time code: BTF-0010 category: deterministic closeTime: '17:00' currentTime: '2026-02-02T18:30:00-03:00' nextAvailableTime: '2026-02-03T06:30:00-03:00' openTime: '06:30' requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f service: plugin timezone: America/Sao_Paulo '429': $ref: '#/components/responses/RateLimitExceeded' '500': description: |- BTF-9000: an unexpected internal error occurred. BTF-9012: the origin ISPB configuration is missing. headers: X-Idempotency-Fenced: $ref: '#/components/headers/XIdempotencyFenced' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDocument' '502': description: >- BTF-0501, BTF-3001: the CRM or the fee service returned a response that this service could not read. BTF-4001: the ownership map of the JD Courier answered outside its contract. headers: X-Idempotency-Fenced: $ref: '#/components/headers/XIdempotencyFenced' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDocument' '503': description: >- A dependency is unavailable, for example the CRM (BTF-0502), the Midaz ledger (BTF-2000) or the fee service (BTF-3000). BTF-2000 also answers when the Midaz ledger did not answer the checks of a transfer between two ledgers. Nothing was priced, reserved or written. Retry later. BTF-4000: the ownership map of the JD Courier could not answer, or this tenant has no Courier configured. Retry later. BTF-4002: the ownership lookup was refused before it was sent. BTF-9015: the accounting routes for the ledger of this transfer could not be resolved. The document carries the `systemplaneKey` and `reason` members. BTF-9016: this tenant's database cannot record the initiation. Nothing was written and nothing was sent. Apply the pending migrations to this tenant and send the identical request again under a new `X-Idempotency` key. BTF-9018: this tenant binds more than one ISPB, so its clearing-house identity cannot be decided. Nothing was written, no hold was placed and nothing reached JD. Once the binding names exactly one ISPB, send the identical request under a new `X-Idempotency` key. BTF-9000: the idempotency store was unavailable before the handler ran, so nothing ran. Send the same request again under the same `X-Idempotency` key. BTF-0019: the work under this `X-Idempotency` key ran, and neither its response nor its outcome fence could be stored, so the key protects nothing and a resend can run the operation a second time. Read the resource before you send anything else. BTF-0020: the work under this `X-Idempotency` key ran and its response could not be stored for replay, but the key is still held. This answer is not the outcome of that work. Read the resource, and resend under a new key only if the work did not land. BTF-9017: the tenant organization list is absent or unreadable. Retry with the same idempotency key once it is configured. headers: X-Idempotency-Fenced: $ref: '#/components/headers/XIdempotencyFenced' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDocument' examples: crmUnavailable: summary: CRM service down value: type: https://errors.lerian.studio/v1/BTF-0502 title: Service Unavailable status: 503 detail: crm service unavailable code: BTF-0502 category: transient requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f service: crm feeServiceUnavailable: summary: Fee service unavailable value: type: https://errors.lerian.studio/v1/BTF-3000 title: Service Unavailable status: 503 detail: fee service unavailable code: BTF-3000 category: transient requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f service: fees components: parameters: XOrganizationId: name: X-Organization-Id in: header required: true description: >- Midaz organization scope for the request, used for downstream CRM, Fees, and Midaz calls. Required on org-scoped transfer routes in every deployment mode; a missing or non-UUID value returns 400. This is not the tenant identifier — tenantId is derived from the bearer JWT or authenticated context, never from this header. Background workers (TED IN poller, reconciliation) have no request header and, in single-tenant mode, fall back to the deployment's `ORGANIZATION_ID` env. schema: type: string format: uuid example: 019c96a0-0a98-7287-9a31-786e0809c769 XIdempotencyKey: name: X-Idempotency in: header required: true description: >- Required idempotency key for safe retries. Use a UUID v4 or a unique business identifier, made of letters, digits, `.`, `_`, and `-`. If the same key is sent again and the original request was already processed, the cached response is returned. See [Retries and idempotency](/pt/reference/retries-idempotency) for details. schema: type: string maxLength: 255 pattern: ^[a-zA-Z0-9._-]+$ example: 019c96a0-aa10-7abc-d1e2-8c9d0e1f2a3b schemas: InitiateTransferRequest: type: object required: - senderAccountId - recipient - amount - purpose properties: senderAccountId: type: string format: uuid description: The Midaz account ID of the sender. example: 019c96a0-0c0c-7221-8cf3-13313fb60081 recipient: $ref: '#/components/schemas/RecipientDetails' amount: type: number format: decimal minimum: 0.01 maximum: 999999.99 description: The transfer amount in BRL. example: 1000.5 purpose: type: string pattern: ^[0-9]{1,4}$ maxLength: 4 description: > BACEN SPB FinlddCli code identifying the transfer purpose. Must be 1–4 ASCII digits. Common FinlddCli codes: * `1` — Pagamento de Impostos, Tributos e Taxas * `3` — Pagamentos de Dividendos * `10` — Crédito em Conta * `100` — Depósito Judicial Refer to the BACEN _Dicionário de Domínios_ (`FinlddCli`) for the full table of active codes. **Note:** the plugin currently accepts FinlddCli values of up to 4 digits. 5-digit codes from the BACEN catalog (such as `99999` — _Outros_) are not yet supported and will return a validation error. example: '10' description: type: string maxLength: 140 description: A free-text description of the transfer. example: Payment for services metadata: type: object additionalProperties: true description: Custom metadata as key-value pairs. example: invoiceId: INV-2024-001 orderId: ORD-2024-123 feeContext: type: string maxLength: 50 pattern: ^[a-z][a-z0-9_]{0,49}$ description: >- A fee label that you choose. A fee package on the payer's ledger selects on it. The ledger postings of the transfer carry it. Between two ledgers, each ledger prices its own part. The label is accepted only when the ledger prices fees natively. example: ted_salario InitiateTransferResponse: type: object required: - initiationId - feeAmount - totalAmount - estimatedCompletionAt - expiresAt - status properties: initiationId: type: string format: uuid description: >- The unique initiation ID. Use this value in the Process Transfer endpoint to confirm the transfer. example: 019c96a0-aa10-7abc-d1e2-8c9d0e1f2a3b feeAmount: type: number format: decimal description: >- The calculated fee amount. Returns 0.00 if fees are disabled for this organization. example: 1.5 totalAmount: type: number format: decimal description: >- The amount debited from the sender's account: the transfer amount plus any fee charged on top. example: 1002 estimatedCompletionAt: type: string format: date-time description: The estimated time when the transfer will be completed. example: '2026-02-01T18:00:00-03:00' expiresAt: type: string format: date-time description: The time when this initiation expires, 24 hours after creation. example: '2026-02-02T15:30:00-03:00' status: $ref: '#/components/schemas/InitiationStatus' feeEntries: type: array description: >- Itemized fee breakdown. Each entry corresponds to one fee charged during the transfer. items: type: object properties: label: type: string description: Fee identifier label. example: ted_transfer_fee amount: type: number format: decimal description: Fee amount. example: 1.5 creditAccount: type: string description: Account that receives the fee credit. example: platform-fee-account sourceAccount: type: string description: Account debited for the fee. example: sender-account isDeductible: type: boolean description: >- Whether the fee is deducted from the transfer amount (true) or added on top (false). example: false packageAppliedId: type: string format: uuid nullable: true description: ID of the fee package applied to this transfer, if any. example: 019c96a0-ad10-7fab-c1d2-3b4c5d6e7f8a recipientLedgerId: type: string format: uuid description: >- The recipient's Midaz ledger on a P2P between two ledgers of one organization. Absent on a P2P inside one ledger and on every TED. example: 0190a0e2-7b1c-7d3e-9f40-5a6b7c8d9e03 ProblemDocument: type: object description: >- The RFC 9457 problem document that the service answers every error with, on `application/problem+json`. Route-specific members (for example `refusalCode`, `transactionId`, `ledgerStatus`, `systemplaneKey`) appear flat at the top level beside these. additionalProperties: true required: - type - title - status - detail - code - requestId - service - category properties: type: type: string description: >- A URI that names the error code: `https://errors.lerian.studio/v1/`. example: https://errors.lerian.studio/v1/BTF-0200 title: type: string description: The HTTP status text. example: Not Found status: type: integer description: The HTTP status code. example: 404 detail: type: string description: A human-readable explanation of this occurrence. example: transfer not found instance: type: string description: The trace ID of this request, when one was recorded. example: 4bf92f3577b34da6a3ce929d0e0e4736 errors: type: array description: Each rejected field. Present on field validation errors only. items: type: object properties: message: type: string description: Why the value was rejected. example: transferId must be a valid UUID location: type: string description: 'Where the value sits: `body.` or `query.`.' example: body.senderAccountId code: type: string description: The stable BTF error code. example: BTF-0200 upstream: type: object description: >- The error that an upstream provider (JD SPB, Midaz) reported. Absent unless surfaced. properties: code: type: string description: The provider's own error code, verbatim. example: AAC90 message: type: string description: The provider's own error message, bounded. example: Assinatura invalida requestId: type: string description: The request correlation ID. Present even when empty. example: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f service: type: string description: The system that produced the error. example: plugin category: type: string description: The machine-readable error category. example: deterministic RecipientDetails: type: object required: - ispb - account - holderDocument properties: ispb: type: string pattern: ^[0-9]{8}$ description: The 8-digit ISPB code identifying the recipient's bank. example: '00000000' branch: type: string pattern: ^[0-9]{4}$ description: The 4-digit branch code (agência). example: '0001' account: type: string pattern: ^[0-9]{1,20}$ description: The account number, from 1 to 20 digits. example: '1234567890' accountType: $ref: '#/components/schemas/AccountType' holderName: type: string minLength: 1 maxLength: 200 description: The full name of the account holder. example: Maria Santos holderDocument: type: string pattern: ^[0-9]{11}$|^[0-9]{14}$ description: >- The holder's document number. CPF (11 digits) for individuals or CNPJ (14 digits) for companies. example: '12345678901' InitiationStatus: type: string enum: - PENDING_CONFIRMATION - PROCESSED - EXPIRED description: >- The status of the initiation. PENDING_CONFIRMATION indicates the initiation is awaiting confirmation via the Process Transfer endpoint. PROCESSED indicates a transfer was created. EXPIRED indicates the initiation expired after 24 hours. example: PENDING_CONFIRMATION AccountType: type: string description: >- The account type following ISO 20022 codes. Known values include: CACC is a current account (Conta Corrente), SLRY is a salary account (Conta Salário), SVGS is a savings account (Conta Poupança), TRAN is a transactional account (Conta de Pagamento), and OTHR is any other account type. example: CACC responses: BadRequest: description: Indicates that the request contains invalid input. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDocument' examples: invalidInput: summary: Validation error value: type: https://errors.lerian.studio/v1/BTF-0001 title: Bad Request status: 400 detail: invalid request body code: BTF-0001 category: deterministic requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f service: plugin Unauthorized: description: Indicates that the request is missing a valid authentication token. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDocument' examples: unauthorized: summary: Missing authorization value: type: https://errors.lerian.studio/v1/BTF-0401 title: Unauthorized status: 401 detail: Missing Token code: BTF-0401 category: plugin requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f service: plugin Forbidden: description: >- Indicates that the caller is authenticated but lacks permission for this operation. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDocument' examples: permissionDenied: summary: Caller lacks permission value: type: https://errors.lerian.studio/v1/BTF-0405 title: Forbidden status: 403 detail: >- the credential is not allowed to perform transfers:create on this request code: BTF-0405 category: plugin requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f service: plugin AccountNotFound: description: >- BTF-0500: the sender account was not found in the CRM. BTF-0404: `X-Organization-Id` names an organization that this tenant does not operate. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDocument' examples: accountNotFound: summary: Invalid sender account value: type: https://errors.lerian.studio/v1/BTF-0500 title: Not Found status: 404 detail: sender account not found code: BTF-0500 category: deterministic requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f service: crm RateLimitExceeded: description: >- Indicates that the rate limit has been exceeded. Retry after the number of seconds specified in the Retry-After header. headers: Retry-After: description: Seconds until rate limit resets schema: type: integer example: 60 content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDocument' examples: rateLimitExceeded: summary: Too many requests value: type: https://errors.lerian.studio/v1/BTF-0429 title: Too Many Requests status: 429 detail: Rate limit exceeded code: BTF-0429 category: rate_limit requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f service: plugin description: > Rate-limit responses use the dedicated `BTF-0429` code with the `rate_limit` category. Clients should back off using the HTTP status `429` and the `Retry-After` header. headers: RetryAfter: description: The number of seconds to wait before you send the request again. schema: type: integer XIdempotencyFenced: description: >- `true` when this 5xx fenced the `X-Idempotency` key, so a resend is refused with 422 BTF-0014. `false` when the fence write itself failed and only the in-flight lease holds the key, so a resend is refused with 409 BTF-0016 until that lease lapses. On a 503 BTF-0019, `false` means the handler succeeded and both its receipt and its fence were lost. The header is absent when nothing fenced the key. On a 500 raised by a panic, the protection of the key is unknown: read the resource and reconcile before you resend. On a 503 BTF-9000 answered while the idempotency store was down before the handler, nothing ran: send the same request again under the same key. schema: type: string securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT Bearer token authentication. The tenantId is derived from the bearer token or authenticated request context and is not supplied through X-Organization-Id. OAuth2ClientCredentials: type: oauth2 flows: clientCredentials: tokenUrl: /v1/login/oauth/access_token scopes: api: TED transfer API access OAuth2Password: type: oauth2 flows: password: tokenUrl: /v1/login/oauth/access_token scopes: api: TED transfer API access ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.