Send TED (TED OUT)

TED OUT allows your clients to send funds to accounts at other financial institutions. The process follows a two-step flow: initiation (with fee calculation) and confirmation.

Prerequisites

Before initiating a transfer:

The source account must be registered in the CRM
The sender must have sufficient balance (amount + fee)
The operation must occur on a business day, between 06:30 and 17:00 (Brasília)

Step 1: Initiate the transfer

The first step validates the data, calculates the fee, and creates a transfer intent valid for 24 hours. No funds are moved in this step. Endpoint: POST /v1/transfers/initiate

What happens

The client sends the transfer details (recipient, amount)
The system validates business rules: operating hours, limits, and duplicates
The fees service (plugin-fees) calculates the transaction cost
A PaymentInitiation entity is created with 24-hour expiration
The system returns the initiationId along with calculated values

Headers

Header	Required	Description
`X-Organization-Id`	Yes	Organization UUID
`Authorization`	Conditional	Bearer token (if authentication enabled)
`X-Idempotency-Key`	No	Idempotency key (UUID v4 recommended)

Request body

{
  "senderAccountId": "550e8400-e29b-41d4-a716-446655440000",
  "recipient": {
    "ispb": "12345678",
    "branch": "0001",
    "account": "123456",
    "accountType": "CHECKING",
    "taxId": "12345678901",
    "name": "João Silva"
  },
  "amount": 1000.00,
  "description": "Supplier payment"
}

Recipient fields

Field	Type	Required	Description
`ispb`	String	Yes	Bank ISPB code (8 digits)
`branch`	String	Yes	Branch (4 digits)
`account`	String	Yes	Account number (1-20 digits)
`accountType`	Enum	Yes	CHECKING, SAVINGS, SALARY, PAYMENT
`taxId`	String	Yes	CPF (11 digits) or CNPJ (14 digits)
`name`	String	Yes	Account holder name (1-200 characters)

Response (200 OK)

{
  "initiationId": "660e8400-e29b-41d4-a716-446655440001",
  "feeAmount": 1.50,
  "totalAmount": 1001.50,
  "estimatedCompletionAt": "2026-02-05T18:00:00-03:00",
  "expiresAt": "2026-02-06T15:30:00-03:00",
  "status": "PENDING_CONFIRMATION"
}

The initiation expires in 24 hours. After this period, a new initiation must be created.

Step 2: Confirm the transfer

After the user reviews the fee, confirm the transfer to start processing. Endpoint: POST /v1/transfers/process

What happens

The system validates the initiationId and checks if it hasn’t expired
Validates the sender’s balance and provisions the funds (amount + fee) in Midaz
The STR0008 message is sent to JD Consultores system with digital signature
The transfer status changes to PROCESSING
In the background, the worker awaits confirmation (STR0008R2) from JD

Request body

{
  "initiationId": "660e8400-e29b-41d4-a716-446655440001"
}

Response (200 OK)

{
  "transferId": "770e8400-e29b-41d4-a716-446655440002",
  "confirmationNumber": "TED-2026-000123",
  "status": "PROCESSING",
  "type": "TED_OUT",
  "amount": 1000.00,
  "feeAmount": 1.50,
  "totalAmount": 1001.50,
  "createdAt": "2026-02-05T15:30:00-03:00",
  "estimatedCompletionAt": "2026-02-05T18:00:00-03:00"
}

Timeline

The typical flow of a TED OUT transfer:

T+0s:    POST /v1/transfers/process
         ├─ Validate balance
         ├─ Provision funds (Midaz, pending: true)
         └─ Send STR0008 to JD

T+2s:    JD Response: ACS99 (message received)
         ├─ Store NumCabSeq
         └─ Status: PROCESSING

T+30s:   Polling RecebeMensagem #1
         └─ ALS01 (no messages yet)

T+60s:   Polling RecebeMensagem #2
         └─ ALS01 (no messages yet)

T+90s:   Polling RecebeMensagem #3
         └─ ALS99 (has message!)
             ├─ Parse STR0008R2
             ├─ CommitTransaction (Midaz)
             └─ Status: COMPLETED

T+95s:   Webhook notification sent

SLA: < 10 minutes typical, D+0 same day (before 17:00)

Error handling

4xx from JD (immediate rejection)

Immediate CancelTransaction in Midaz (releases provision)
Status updated to REJECTED
Webhook transfer.failed sent
Automatic refund (amount + fee)

5xx/Timeout (transient error)

Automatic retry: 5x (0s, 5s, 25s, 60s, 120s)
Query ConsultaNumCtrlIF to check status
If still uncertain after retries: fail-safe refund

Chargeback (STR0010R2)

Return message received from destination bank
CancelTransaction or RevertTransaction in Midaz
Status: REJECTED
Automatic refund with return code

Common error codes

Code	HTTP	Description
`BTF-0001`	400	Invalid data (ISPB, negative amount)
`BTF-0010`	403	Outside BACEN operating hours
`BTF-0011`	422	Daily/monthly limit exceeded
`BTF-0012`	409	Duplicate transfer detected
`BTF-2001`	422	Insufficient balance
`BTF-1000`	503	JD SPB service unavailable

Error response examples

Outside operating hours (403):

{
  "code": "BTF-0010",
  "title": "Operating Hours Violation",
  "message": "Transfers can only be initiated Monday-Friday between 06:30 and 17:00 Brasília time",
  "fields": {
    "currentTime": "2026-01-21T18:30:00-03:00",
    "nextAvailableTime": "2026-01-22T06:30:00-03:00"
  }
}

Insufficient balance (422):

{
  "code": "BTF-2001",
  "title": "Insufficient Balance",
  "message": "Sender account does not have sufficient balance for this transfer.",
  "fields": {
    "available": 500.00,
    "required": 1001.50
  }
}

Check status

Track the transfer progress: Endpoint: GET /v1/transfers/{transferId}

Response

{
  "transferId": "770e8400-e29b-41d4-a716-446655440002",
  "confirmationNumber": "TED-2026-000123",
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "TED_OUT",
  "status": "COMPLETED",
  "sender": {
    "accountId": "550e8400-e29b-41d4-a716-446655440000"
  },
  "recipient": {
    "ispb": "12345678",
    "branch": "0001",
    "account": "123456",
    "accountType": "CHECKING",
    "taxId": "12345678901",
    "name": "João Silva"
  },
  "amount": 1000.00,
  "feeAmount": 1.50,
  "totalAmount": 1001.50,
  "description": "Supplier payment",
  "createdAt": "2026-02-05T15:30:00-03:00",
  "completedAt": "2026-02-05T15:35:12-03:00",
  "statusHistory": [
    {"status": "CREATED", "timestamp": "2026-02-05T15:30:00-03:00"},
    {"status": "PROCESSING", "timestamp": "2026-02-05T15:30:05-03:00"},
    {"status": "COMPLETED", "timestamp": "2026-02-05T15:35:12-03:00"}
  ]
}

Cancel transfer

Transfers can be cancelled while in CREATED or PENDING status. Endpoint: POST /v1/transfers/{transferId}/cancel

Response (200 OK)

{
  "transferId": "770e8400-e29b-41d4-a716-446655440002",
  "status": "CANCELLED",
  "cancelledAt": "2026-02-05T15:32:00-03:00"
}

Transfers in PROCESSING or later states cannot be cancelled. Wait for the operation to complete or fail.

Common ISPB codes

Last verified: 2026-02-06. Values are subject to change.

Bank	ISPB
Banco do Brasil	00000000
Bradesco	60746948
Itaú	60701190
Santander	90400888
Caixa Econômica	00360305
Nubank	18236120
Inter	00416968

Consult the complete ISPB list on the Central Bank website for the most up-to-date information.

Introduction

CRM

Fees Engine

Pix

Indirect Pix

Direct Pix

Bank Transfer (TED)

Send TED (TED OUT)

Prerequisites

Step 1: Initiate the transfer

What happens

Headers

Request body

Recipient fields

Response (200 OK)

Step 2: Confirm the transfer

What happens

Request body

Response (200 OK)

Timeline

Error handling

Common error codes

Error response examples

Check status

Response

Cancel transfer

Response (200 OK)

Common ISPB codes

Introduction

CRM

Fees Engine

Pix

Indirect Pix

Direct Pix

Bank Transfer (TED)

​Prerequisites

​Step 1: Initiate the transfer

​What happens

​Headers

​Request body

​Recipient fields

​Response (200 OK)

​Step 2: Confirm the transfer

​What happens

​Request body

​Response (200 OK)

​Timeline

​Error handling

​Common error codes

​Error response examples

​Check status

​Response

​Cancel transfer

​Response (200 OK)

​Common ISPB codes

Prerequisites

Step 1: Initiate the transfer

What happens

Headers

Request body

Recipient fields

Response (200 OK)

Step 2: Confirm the transfer

What happens

Request body

Response (200 OK)

Timeline

Error handling

Common error codes

Error response examples

Check status

Response

Cancel transfer

Response (200 OK)

Common ISPB codes