> ## 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. # Process a Transfer > Use this endpoint to confirm and execute a previously initiated transfer. The system validates the initiationId, checks the sender's balance, holds funds in Midaz, and routes the transfer to JD SPB (for TED OUT), creates an internal Midaz transaction (for P2P), or sends the credit to the other core of your institution through the JD Courier (for a cross-core TED). A cross-core TED answers `COMPLETED` once the other core credits it, and `PROCESSING` while the outcome is unknown. Submitting the same initiationId returns the same transferId. ## OpenAPI ````yaml /pt/openapi/v3-current/ted.yaml post /v1/transfers/process 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/process: post: tags: - Transfers API summary: Process a Transfer description: >- Use this endpoint to confirm and execute a previously initiated transfer. The system validates the initiationId, checks the sender's balance, holds funds in Midaz, and routes the transfer to JD SPB (for TED OUT), creates an internal Midaz transaction (for P2P), or sends the credit to the other core of your institution through the JD Courier (for a cross-core TED). A cross-core TED answers `COMPLETED` once the other core credits it, and `PROCESSING` while the outcome is unknown. Submitting the same initiationId returns the same transferId. operationId: processTransfer parameters: - $ref: '#/components/parameters/XOrganizationId' - $ref: '#/components/parameters/XIdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProcessTransferRequest' examples: process: summary: Process initiated transfer value: initiationId: 019c96a0-aa10-7abc-d1e2-8c9d0e1f2a3b responses: '200': description: >- Indicates that the transfer was confirmed and processing has started. 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/ProcessTransferResponse' examples: success: summary: Transfer processing value: transferId: 019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d confirmationNumber: '20260201001' status: PROCESSING feeAmount: 1.5 totalAmount: 1002 '202': description: >- Indicates that the TED OUT advance failed but the transfer was escalated to the reconciliation worker. The Midaz hold is intact. Poll `GET /v1/transfers/{transferId}` for the terminal status. The body is a problem document, not a transfer response. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDocument' examples: escalated: summary: Escalated to reconciliation value: type: https://errors.lerian.studio/v1/BTF-9010 title: Accepted status: 202 detail: >- ted_out advance failed; transfer escalated to reconciliation — poll transfer status code: BTF-9010 category: transient hint: >- GET /v1/transfers/{transferId} will converge to the final status requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f service: plugin '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: >- BTF-0201: the initiation was not found or belongs to a different organization. BTF-1092: the signing artifact was not found. BTF-2001: the account was not found in the Midaz ledger. BTF-0404: `X-Organization-Id` names an organization that this tenant does not operate. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDocument' examples: initiationNotFound: summary: Invalid initiation ID value: type: https://errors.lerian.studio/v1/BTF-0201 title: Not Found status: 404 detail: payment initiation not found code: BTF-0201 category: deterministic requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f service: plugin '409': description: >- BTF-0012: an identical transfer was detected inside the deduplication window. BTF-0203: this initiation has already been processed into a transfer. The `transferId` member names that transfer. BTF-0112: the initiation was created before ledger-scoped routing and cannot be processed. Nothing was written. Initiate the transfer again. BTF-1094: the signing artifact was already used. BTF-1095: the signing artifact does not match the transfer. BTF-2002: the Midaz ledger reported a transaction state conflict. On a P2P between two ledgers, the ledger group is still in flight after the retries. Nothing is reverted. Send the confirmation again. 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: alreadyProcessed: summary: Initiation used value: type: https://errors.lerian.studio/v1/BTF-0203 title: Conflict status: 409 detail: this initiation has already been processed code: BTF-0203 category: deterministic requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f service: plugin transferId: 019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d legacyInitiation: summary: Initiation created before ledger-scoped routing value: type: https://errors.lerian.studio/v1/BTF-0112 title: Conflict status: 409 detail: >- this payment initiation predates ledger-scoped accounting routes and cannot be processed; initiate the transfer again code: BTF-0112 category: deterministic requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f service: plugin '410': description: >- BTF-0202: the initiation expired after 24 hours. Create a new initiation. BTF-1093: the signing artifact expired. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDocument' examples: expired: summary: Initiation too old value: type: https://errors.lerian.studio/v1/BTF-0202 title: Gone status: 410 detail: >- initiation expired after 24 hours. please create a new initiation. code: BTF-0202 category: deterministic expiresAt: '2026-01-31T15:30:00-03:00' requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f service: plugin '422': description: >- BTF-0002: the request failed domain validation. BTF-0004: the accounts of an internal transfer are now in different Midaz organizations (`reason` is `cross_organization`), or in ledgers other than the ones that the initiation recorded (no `reason`; initiate a new transfer). Nothing was posted. BTF-0005, BTF-0006, BTF-0007, BTF-3003: the P2P between two ledgers is refused, before the posting or by the Midaz ledger on the group posting. Nothing moved in either ledger. BTF-0005: the Midaz ledger is older than 4.2.0 (`reason` is `ledger_platform_below_minimum`). BTF-0006: a ledger is not enabled for postings between ledgers, or its bridge operation route is missing or invalid (`reason` is `ledger_not_enabled`, `bridge_route_missing` or `bridge_route_invalid`). BTF-0007: the two accounts hold different assets (`reason` is `asset_mismatch`). BTF-3003: the fee package of the source ledger became deductible after the initiation (`reason` is `source_fee_deductible`). BTF-0010: the transfer was attempted outside BACEN operating hours. BTF-0011: the transfer amount exceeds a configured usage limit. BTF-0013: a database constraint refused the write. BTF-1001: JD SPB rejected the transfer. The JD business-rejection code (DV*) is on `upstream.code`. BTF-1090: a TED OUT requires a signing artifact before it can be processed. BTF-1096: the digital signature failed validation. BTF-2003: the Midaz ledger rejected the transaction request. BTF-2004: the Tracer of the Midaz ledger denied the transaction under a configured limit or rule. Nothing was posted. BTF-2005: the fee engine of the Midaz ledger refused to price the transaction, for example a deductible fee larger than the amount. Nothing was posted. BTF-3002: this TED OUT or cross-core TED initiation was priced with a deductible fee package. A TED OUT must not carry one, because its fee is charged on top of the amount. Nothing reached JD, and this request leaves no hold. Make the package non-deductible, then initiate again. When the document carries `transferId`, an earlier process call of this initiation reserved that transfer, and any ledger hold it placed stays until an operator releases it. BTF-4005: the other core of your institution refused the credit of a cross-core TED, or the JD Courier reached no recipient. The hold was released, nothing moved, and the transfer is `REJECTED`. BTF-4003, BTF-4004: on a cross-core TED, the owner of the recipient account changed after the initiation, or an account cannot be keyed for the ownership map. No hold was placed, and the transfer is `FAILED`. 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: limitExceeded: summary: Daily limit reached value: type: https://errors.lerian.studio/v1/BTF-0011 title: Unprocessable Entity status: 422 detail: usage limit exceeded code: BTF-0011 attempted: '3000.00' category: deterministic current: '8000.00' limit: '10000.00' period: DAILY requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f service: plugin '429': $ref: '#/components/responses/RateLimitExceeded' '500': description: >- BTF-9000: an unexpected internal error occurred. BTF-9002: the transfer was sent, and the bookkeeping after the dispatch failed. Do not retry. BTF-9011: the TED OUT stopped before it was sent to the clearing house, and the transfer keeps a live Midaz hold. The document carries `transferId`. Reconciliation picks the transfer up within ten minutes and releases its hold once the clearing house is open again. Do not retry `/process`. No operator action is required. BTF-9014: the P2P posting completed in the Midaz ledger, and the transfer was not recorded as completed. The document carries `transferId`. Read the transfer, then send the identical request again under a new `X-Idempotency` key. The repeat completes that same transfer and cannot move money twice. Do not initiate a new transfer for it. headers: X-Idempotency-Fenced: $ref: '#/components/headers/XIdempotencyFenced' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDocument' '502': description: >- BTF-1007, BTF-1008, BTF-1009: JD SPB rejected the credentials, the signing certificate, or the configuration. The JD code is on `upstream.code`. BTF-4001: on a cross-core TED, the ownership map of the JD Courier answered outside its contract. No hold was placed. headers: X-Idempotency-Fenced: $ref: '#/components/headers/XIdempotencyFenced' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDocument' examples: jdAuthRejected: summary: JD SPB auth rejection value: type: https://errors.lerian.studio/v1/BTF-1008 title: Bad Gateway status: 502 detail: >- jd spb rejected the request's signing certificate or digital signature code: BTF-1008 upstream: code: AAC90 category: deterministic requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f service: jd_spb '503': description: >- A dependency is unavailable, for example JD SPB (BTF-1000) or Midaz (BTF-2000). On a P2P between two ledgers, BTF-2000 means that the outcome of the ledger group is unknown. Nothing is reverted. Send the confirmation again. BTF-4000, BTF-4002: on a cross-core TED, the ownership map of the JD Courier could not answer, the lookup was refused before it was sent, or the map does not show the sender's account as held by this engine. No hold was placed. Send the confirmation again later. 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 transfer. No hold was placed and nothing reached JD. 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: jdUnavailable: summary: JD SPB unavailable value: type: https://errors.lerian.studio/v1/BTF-1000 title: Service Unavailable status: 503 detail: jd spb service unavailable code: BTF-1000 category: transient requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f service: jd_spb midazUnavailable: summary: Midaz ledger unavailable value: type: https://errors.lerian.studio/v1/BTF-2000 title: Service Unavailable status: 503 detail: midaz service unavailable code: BTF-2000 category: transient requestId: 6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f service: midaz 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: ProcessTransferRequest: type: object oneOf: - required: - initiationId not: anyOf: - required: - signingArtifactId - required: - payloadHash - required: - signature - required: - initiationId - signingArtifactId - payloadHash - signature properties: initiationId: type: string format: uuid description: >- The initiation ID returned by the Initiate Transfer endpoint. Expires after 24 hours. example: 019c96a0-aa10-7abc-d1e2-8c9d0e1f2a3b signingArtifactId: type: string format: uuid description: >- Identifier of the frozen signing artifact returned by Prepare Transfer Signature. example: 019c96a0-bb10-7def-a1b2-3c4d5e6f7a8b payloadHash: type: string description: SHA-256 hash of the canonical payload that was signed. example: 8f0c7f5c1c7b4d9f2f5c7d1a0d4c9a2b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f signature: type: string description: Base64-encoded signature for tenants that sign outside the plugin. example: base64-signature-here ProcessTransferResponse: type: object required: - transferId - confirmationNumber - status - feeAmount - totalAmount properties: transferId: type: string format: uuid description: The unique transfer ID. Use this value to track the transfer status. example: 019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d confirmationNumber: type: string maxLength: 20 description: >- A human-readable confirmation number. Format is YYYYMMDD followed by a short hex suffix derived from the transfer ID (e.g. 20260201aa10bc3d4e5f). example: '20260201001' status: allOf: - $ref: '#/components/schemas/TransferStatus' description: >- The current transfer status. For TED_OUT transfers, the status immediately after processing is always PROCESSING. feeAmount: type: number format: decimal description: The fee amount as calculated during initiation. 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 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 ledgerGroupId: type: string format: uuid description: >- The Midaz ledger group that a P2P between two ledgers posted as. Absent when the expiry recovery completed the transfer. example: 0190a0e2-7b1c-7d3e-9f40-5a6b7c8d9e10 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 TransferStatus: type: string enum: - CREATED - PENDING - PROCESSING - COMPLETED - REJECTED - FAILED - CANCELLED - RECEIVED description: >- The current status of the transfer. For TED OUT: CREATED → PENDING → PROCESSING → COMPLETED, REJECTED, or FAILED. For P2P: CREATED → PROCESSING → COMPLETED or FAILED (PENDING is an SPB-specific state and does not apply to P2P). Transfers can be CANCELLED while in CREATED or PENDING status. For TED IN: RECEIVED → PROCESSING → COMPLETED or FAILED. A COMPLETED TED IN can also transition to FAILED in the event of a chargeback. example: COMPLETED 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 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.