> ## Documentation Index
> Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Send a TED

> Transfer money from a wallet to an account at another bank by TED: create the transfer, then confirm it

A TED is a transfer from one of your wallets to an account at another bank, identified by its bank details. Sending one takes two steps: you **create** the TED with the beneficiary's bank details and the amount, and then you **confirm** it, choosing the balance category the amount comes from. Nothing leaves the wallet until you confirm, and you can cancel the TED until then.

> [!TIP]
>
> To pay an account by its bank details you can also use Pix — see [Send a Pix payment](https://developers.portao3.com.br/guides/send-pix.md).

## Flow

```mermaid theme={null}
sequenceDiagram
  participant You
  participant P3 as Portão 3
  You->>P3: POST .../ted (beneficiary, amount)
  P3->>You: _id — status REQUESTED
  You->>P3: POST .../ted/{tedId}/confirm (category)
  P3->>You: status PAID
  opt the receiving bank returns the transfer
    Note over P3: status REFUNDED — the amount comes back to the wallet
  end
```

## Who can send a TED

You need permission to pay from the wallet:

* on the organization's **main wallet**, be an admin of the organization or of the realm;
* on **another wallet**, be one of those admins or have the wallet shared with you as `OWNER` or `USER`.

The same rule applies to confirming and cancelling. Without it you get `403 FORBIDDEN_WALLET`. Any member of the organization can read and list TEDs.

## Step 1: Create the TED

Send the amount in centavos, the beneficiary's bank details in `creditParty`, and in `debitParty` the name of the person making the transfer on your side.

```bash theme={null}
curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/ted' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 235000,
    "description": "Ensaio fotográfico da campanha de novembro",
    "creditParty": {
      "bankCode": "341",
      "branch": "1234",
      "accountNumber": "0045671",
      "accountType": "CACC",
      "document": "11222333000181",
      "name": "Estúdio Lumen Fotografia Ltda"
    },
    "debitParty": {
      "personName": "Mariana Souza Lima"
    }
  }'
```

| Field | Notes |
| - | - |
| `amount` | In centavos — `235000` is R\$ 2,350.00. Required. |
| `description` | A note kept with the TED and sent to the bank with it. Optional. |
| `creditParty.bankCode` | The beneficiary bank's three-digit code (COMPE), such as `341` or `001`. |
| `creditParty.branch` | The branch (*agência*): 4 digits, without its check digit. |
| `creditParty.accountNumber` | The account number with its check digit: digits only, at least 5, no hyphen. |
| `creditParty.accountType` | `CACC` for a checking account, `SVGS` for a savings account. |
| `creditParty.document` | The account holder's CPF or CNPJ, with valid check digits. Punctuation is accepted and removed. |
| `creditParty.name` | The account holder's name. |
| `debitParty.personName` | Who is making the transfer on your side. It is sent to the bank with the TED. |

Send `bankCode`, `branch` and `accountNumber` as strings, so leading zeros are kept. Use `default` as `{walletId}` for the organization's main wallet.

The TED is created as `REQUESTED` and nothing is sent yet. The bank details are not checked at this point — the bank checks them when you confirm. Keep the TED's **`_id`**: it is the `{tedId}` of the next steps.

```json theme={null}
{
  "_id": "6728c4e1b4d3e80012c9a5b3",
  "status": "REQUESTED",
  "walletId": "66f2a3d1b4d3e80012c9a0d2",
  "txnAmount": 235000,
  "txnCurrency": "986",
  "confirmedAmount": 0,
  "creditParty": {
    "_id": "6728c4e1b4d3e80012c9a5b4",
    "bankCode": "341",
    "branch": "1234",
    "accountNumber": "0045671",
    "accountType": "CACC",
    "document": "11222333000181",
    "name": "Estúdio Lumen Fotografia Ltda"
  },
  "debitParty": { "_id": "6728c4e1b4d3e80012c9a5b5", "personName": "Mariana Souza Lima" },
  "description": "Ensaio fotográfico da campanha de novembro"
}
```

Reference: [Create a TED payment](https://developers.portao3.com.br/api-reference/banking/ted-payments/create-a-ted-payment.md)

## Step 2: Confirm the TED

Confirm it with the balance category of the wallet the amount is taken from. `FLEX_INTERNATIONAL` is the general-purpose one.

```bash theme={null}
curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/ted/{tedId}/confirm' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{ "category": "FLEX_INTERNATIONAL" }'
```

A successful confirmation answers `200` with the TED `PAID`: the bank accepted the transfer and the amount left the wallet. `confirmedAmount`, `confirmedBalanceCategory` and `confirmedAt` record it, `external.tedId` holds the bank's identifier for the transfer, and the debit appears in the wallet's transactions.

If the confirmation fails while sending — the balance category doesn't cover the amount, a transaction limit is exceeded, or the bank refuses the beneficiary's details — you get the error and the TED becomes `FAILED`. A `FAILED` TED can't be confirmed again: create a new one. An error before anything is sent (the permission check, or the bank not answering while the wallet is read) leaves the TED `REQUESTED`; read it when in doubt.

The bank applies the wallet's TED [transaction limits](https://developers.portao3.com.br/api-reference/banking/transaction-limits/get-transaction-limits.md) when you confirm.

Reference: [Confirm a TED payment](https://developers.portao3.com.br/api-reference/banking/ted-payments/confirm-a-ted-payment.md)

## When the receiving bank returns the TED

A `PAID` TED can still come back: when the receiving bank returns the transfer — for example because the account details don't match an open account — the amount is credited back to the wallet and the TED becomes `REFUNDED`, with the time in `refundedAt`. A `FAILED` TED whose confirmation timed out after the bank had already taken it can end `REFUNDED` the same way.

## Cancel a TED

A TED that is still `REQUESTED` can be [cancelled](https://developers.portao3.com.br/api-reference/banking/ted-payments/cancel-a-ted-payment.md) — it becomes `CANCELLED` and nothing is sent. Send no body:

```bash theme={null}
curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/ted/{tedId}/cancel' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE'
```

It answers `204`. A TED in any other status — including one already `CANCELLED` — answers `409 TED_STATUS_IS_NOT_PENDING`.

## Follow a TED

[Read the TED](https://developers.portao3.com.br/api-reference/banking/ted-payments/get-a-ted-payment.md) to see its `status`, or list the TEDs of a [wallet](https://developers.portao3.com.br/api-reference/banking/ted-payments/list-a-wallets-ted-payments.md), an [account](https://developers.portao3.com.br/api-reference/banking/ted-payments/list-an-accounts-ted-payments.md), an [organization](https://developers.portao3.com.br/api-reference/banking/ted-payments/list-an-organizations-ted-payments.md) or your [realm](https://developers.portao3.com.br/api-reference/banking/ted-payments/list-the-realms-ted-payments.md) — newest first, filtered by `status` (for example `?status=PAID,REFUNDED`) and paged with `limit` + `next`. Send the same `x-environment` you created the TED in. There is no webhook for TEDs.

| Status | Meaning |
| - | - |
| `REQUESTED` | Created, not sent yet. Confirm or cancel it. |
| `PAID` | The bank accepted the transfer and the amount left the wallet. |
| `FAILED` | The confirmation failed. Create a new TED. |
| `CANCELLED` | Cancelled before it was sent. |
| `REFUNDED` | The bank returned the transfer and the amount came back to the wallet — usually after `PAID`. |

## Common errors

Errors come in the [error envelope](https://developers.portao3.com.br/index.md#errors) with a stable `code`. When the bank refuses a transfer for a reason without a code of its own in this API, `code` carries the bank's reason in lower case and `message` the bank's explanation — or `Unknown error` when it gave none. Branch on `code`, not on the message.

| Status | `code` | When | What to do |
| - | - | - | - |
| `422` | `BAD_REQUEST` | A field is invalid — for example a `document` with wrong check digits, or a `bankCode` that isn't 3 digits. `fields` lists each one. | Fix the request. |
| `403` | `FORBIDDEN_WALLET` | You can't pay from this wallet. | See [Who can send a TED](#who-can-send-a-ted). |
| `404` | `TED_NOT_FOUND` | The wallet has no TED with this ID in this environment. | Check the `tedId` and the `x-environment`. |
| `409` | `TED_STATUS_IS_NOT_PENDING` | The TED isn't `REQUESTED`: it was already paid, cancelled, failed or refunded. | Read the TED; create a new one if needed. |
| `422` | `INSUFFICIENT_FUNDS` | The balance category doesn't cover the amount. The TED is now `FAILED`. | Fund the wallet and create a new TED. |
| `422` | `LIMIT_EXCEEDED` | The amount is above one of the wallet's TED limits. The TED is now `FAILED`. | Create a new TED within the limit. |
| `422` | `BANKING_PROVIDER_VALIDATION_ERROR` | The bank refused a field of the transfer, such as the beneficiary's details. The TED is now `FAILED`. | Check the bank details and create a new TED. |
| `500` / `502` / `503` / `504` | `BANKING_PROVIDER_UNAVAILABLE` | The bank didn't answer. | Retry. If it happened while confirming, read the TED first: still `REQUESTED` means nothing was sent — confirm it again; `FAILED` means it failed while sending — check the wallet's balance and transactions before you create a new one, since the money may still go out. |

Each endpoint's reference page lists every error it can return.

## Next steps

> [card] [Send a Pix payment](https://developers.portao3.com.br/guides/send-pix.md)
>
> Pay by Pix key, QR code or bank details.

> [card] [Wallets for your customers](https://developers.portao3.com.br/guides/wallets.md)
>
> Read balances and transaction limits, and move money between wallets.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.