> ## 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. # Get a Transfer > Use this endpoint to retrieve the current status and details of a transfer, including its type, status history, sender and recipient details, amounts, and timestamps. Only returns transfers belonging to the same organization. ## OpenAPI ````yaml /en/openapi/v3-current/ted.yaml get /v1/transfers/{transferId} 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.4.0 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/{transferId}: get: tags: - Transfers API summary: Get a Transfer description: >- Use this endpoint to retrieve the current status and details of a transfer, including its type, status history, sender and recipient details, amounts, and timestamps. Only returns transfers belonging to the same organization. operationId: getTransferStatus parameters: - $ref: '#/components/parameters/XOrganizationId' - name: transferId in: path required: true description: The unique identifier of the transfer. schema: type: string format: uuid responses: '200': description: Indicates that the transfer was found and its details are returned. content: application/json: schema: $ref: '#/components/schemas/Transfer' examples: tedOutCompleted: summary: TED OUT completed value: transferId: 019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d type: TED_OUT status: COMPLETED senderAccountId: 019c96a0-0c0c-7221-8cf3-13313fb60081 recipient: ispb: '00000000' branch: '0001' account: '1234567890' accountType: CACC holderName: Maria Santos holderDocument: '98765432100' amount: 1000.5 feeAmount: 1.5 totalAmount: 1002 confirmationNumber: '20260201001' controlNumber: '202602010001' createdAt: '2026-02-01T15:30:00-03:00' updatedAt: '2026-02-01T15:35:00-03:00' completedAt: '2026-02-01T15:35:00-03:00' statusHistory: - status: CREATED timestamp: '2026-02-01T15:30:00-03:00' reason: null - status: PENDING timestamp: '2026-02-01T15:30:05-03:00' reason: null - status: PROCESSING timestamp: '2026-02-01T15:30:10-03:00' reason: null - status: COMPLETED timestamp: '2026-02-01T15:35:00-03:00' reason: null tedInReceived: summary: TED IN received value: transferId: 019c96a0-ab20-7def-a1b2-1f2a3b4c5d6e type: TED_IN status: COMPLETED senderAccountId: null recipient: ispb: '12345678' branch: '0001' account: '9876543210' accountType: CACC holderName: João Silva holderDocument: '12345678901' amount: 500 feeAmount: 0 totalAmount: 500 confirmationNumber: '20260201002' controlNumber: '202602010002' createdAt: '2026-02-01T16:00:00-03:00' updatedAt: '2026-02-01T16:00:05-03:00' completedAt: '2026-02-01T16:00:05-03:00' statusHistory: - status: RECEIVED timestamp: '2026-02-01T16:00:00-03:00' reason: null - status: COMPLETED timestamp: '2026-02-01T16:00:05-03:00' reason: null '404': $ref: '#/components/responses/TransferNotFound' '429': $ref: '#/components/responses/RateLimitExceeded' 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 schemas: Transfer: type: object required: - transferId - type - status - senderAccountId - recipient - amount - feeAmount - totalAmount - createdAt - updatedAt - statusHistory properties: transferId: type: string format: uuid description: The unique identifier of the transfer. example: 019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d type: $ref: '#/components/schemas/TransferType' status: $ref: '#/components/schemas/TransferStatus' senderAccountId: type: string format: uuid nullable: true description: >- UUID of the sender account. May be null for TED_IN transfers where the sender is external. recipient: $ref: '#/components/schemas/RecipientDetails' amount: type: number format: decimal description: The transfer amount without the fee. example: 1000.5 feeAmount: type: number format: decimal description: The fee charged for this transfer. example: 1.5 totalAmount: type: number format: decimal description: The total amount, calculated as the transfer amount plus the fee. example: 1002 confirmationNumber: type: string nullable: true maxLength: 20 description: The human-readable confirmation code, if available. example: '20260201001' controlNumber: type: string nullable: true maxLength: 20 description: The JD SPB control number, present for TED OUT and TED IN transfers. example: '202602010001' midazTransactionId: type: string format: uuid nullable: true description: The corresponding Midaz ledger transaction ID. example: 019c96a0-ac10-7efa-b1c2-2a3b4c5d6e7f description: type: string nullable: true maxLength: 140 description: The purpose or description of the transfer. example: Payment for services metadata: type: object nullable: true additionalProperties: true description: Custom metadata as key-value pairs. createdAt: type: string format: date-time description: The timestamp when the transfer was created. example: '2026-02-01T15:30:00-03:00' updatedAt: type: string format: date-time description: The timestamp of the last status update. example: '2026-02-01T15:35:00-03:00' completedAt: type: string format: date-time nullable: true description: >- The timestamp when the transfer was completed. Null if not yet completed. example: '2026-02-01T15:35:00-03:00' statusHistory: type: array description: The history of status transitions for this transfer. items: $ref: '#/components/schemas/StatusHistoryEntry' TransferType: type: string enum: - TED_OUT - TED_IN - P2P description: >- The type of transfer. TED_OUT is an outgoing transfer to an external bank via JD SPB. TED_IN is an incoming transfer from an external bank. P2P is a peer-to-peer transfer within the same institution (same ISPB). example: TED_OUT 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 RecipientDetails: type: object required: - ispb - branch - account - accountType - holderName - 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' StatusHistoryEntry: type: object required: - status - timestamp properties: status: $ref: '#/components/schemas/TransferStatus' timestamp: type: string format: date-time example: '2026-02-01T15:30:00-03:00' reason: type: string nullable: true maxLength: 500 description: The reason for the status change, if applicable. example: JD timeout after 3 retries 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. AccountType: type: string enum: - CACC - SLRY - SVGS - TRAN - OTHR description: >- The account type following ISO 20022 codes. 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: TransferNotFound: description: >- Indicates that the transfer was not found or belongs to a different organization. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: transferNotFound: summary: Transfer ID invalid value: error: code: BTF-0200 title: Transfer Not Found message: Transfer not found 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. 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. ````