> ## 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) or creates an internal Midaz transaction (for P2P). Submitting the same initiationId returns the same transferId. ## OpenAPI ````yaml /en/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, and cancellation. version: 2.5.0-beta.5 servers: - url: https://plugin-br-bank-transfer.sandbox.lerian.net description: Sandbox (placeholder — not yet available for public access) security: - BearerAuth: [] tags: - name: Transfers API description: Endpoints for initiating, processing, tracking, and cancelling transfers. - name: Webhook DLQ description: Endpoints for inspecting and retrying webhook dead-letter queue messages. - name: Health API description: Endpoints for checking service liveness and readiness. 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) or creates an internal Midaz transaction (for P2P). 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](/en/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 '404': $ref: '#/components/responses/InitiationNotFound' '409': $ref: '#/components/responses/AlreadyProcessed' '410': $ref: '#/components/responses/InitiationExpired' '422': $ref: '#/components/responses/LimitExceeded' '429': $ref: '#/components/responses/RateLimitExceeded' '503': $ref: '#/components/responses/ServiceUnavailable' components: parameters: XOrganizationId: name: X-Organization-Id in: header required: true description: >- Organization ID used as the tenant identifier. All data is scoped to this organization. Must match the JWT tenantId claim when authentication is enabled. 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 unique business identifier. If the same key is sent again and the original request was already processed, the cached response is returned. See [Retries and idempotency](/en/reference/retries-idempotency) for details. schema: type: string maxLength: 255 example: 019c96a0-aa10-7abc-d1e2-8c9d0e1f2a3b schemas: ProcessTransferRequest: type: object required: - initiationId 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 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 in YYYYMMDD+sequence format. 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 total amount held or transferred, including the fee. 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 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 ErrorResponse: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string pattern: ^BTF-[0-9]{4}$ description: The error code in BTF-XXXX format. example: BTF-0010 title: type: string description: A short, human-readable title for the error. example: Operating Hours Violation message: type: string description: A detailed description of the error. example: >- Transfers can only be initiated Monday-Friday between 06:30 and 17:00 Brasília time fields: type: object additionalProperties: true description: Field-level validation errors for request body parameters. example: currentTime: '2026-02-01T18:30:00-03:00' operatingHours: Mon-Fri 06:30-17:00 UTC-3 headers: type: object additionalProperties: true description: Validation errors for request headers. paths: type: object additionalProperties: true description: Validation errors for path parameters. queryParams: type: object additionalProperties: true description: Validation errors for query parameters. responses: InitiationNotFound: description: >- Indicates that the initiation was not found or belongs to a different organization. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: initiationNotFound: summary: Invalid initiation ID value: error: code: BTF-0201 title: Initiation Not Found message: Initiation not found or belongs to different organization AlreadyProcessed: description: >- Indicates that this initiation has already been processed into a transfer. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: alreadyProcessed: summary: Initiation used value: error: code: BTF-0203 title: Already Processed message: This initiation has already been processed fields: transferId: 019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d InitiationExpired: description: >- Indicates that the initiation has expired after 24 hours. A new initiation must be created. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: expired: summary: Initiation too old value: error: code: BTF-0202 title: Initiation Expired message: Initiation expired after 24 hours. Create a new initiation. fields: expiresAt: '2026-01-31T15:30:00-03:00' LimitExceeded: description: Indicates that the transfer amount exceeds the configured usage limit. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: limitExceeded: summary: Daily limit reached value: error: code: BTF-0011 title: Limit Exceeded message: Transfer amount exceeds daily limit fields: limitType: PERIOD periodType: DAILY limitAmount: 10000 usedAmount: 8000 requestedAmount: 3000 excessAmount: 1000 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/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimitExceeded: summary: Too many requests value: error: code: BTF-0001 title: Invalid input message: >- Too many requests. Retry after the interval indicated by the `Retry-After` header. description: > Rate-limit responses share the `BTF-0001` code with other 4xx validation errors. Clients should detect rate limiting via HTTP status `429` and the `Retry-After` header rather than the error code. ServiceUnavailable: description: >- Indicates that an external service (CRM, JD SPB, Midaz, or Fees) is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: crmUnavailable: summary: CRM service down value: error: code: BTF-0502 title: CRM Service Unavailable message: >- Unable to validate account. The CRM service is temporarily unavailable. Try again later. jdUnavailable: summary: JD SPB unavailable value: error: code: TRANSPORT title: JD SPB Unavailable message: >- Unable to submit transfer. The JD SPB service is temporarily unavailable. Try again later. midazUnavailable: summary: Midaz ledger unavailable value: error: code: BTF-2000 title: Midaz Unavailable message: >- Unable to process transfer. The Midaz ledger service is temporarily unavailable. Try again later. feeServiceUnavailable: summary: Fee service unavailable (fail-closed mode) value: error: code: BTF-3000 title: Fee Service Unavailable message: >- Unable to calculate fee. The fee service is temporarily unavailable. Try again later. dlqInspectorUnavailable: summary: DLQ inspector not configured value: error: code: BTF-9005 title: DLQ Inspector Unavailable message: DLQ inspector is not configured securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT Bearer token authentication. The token must include a tenantId claim that matches the X-Organization-Id header. ````