Send a TED

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.

To pay an account by its bank details you can also use Pix — see Send a Pix payment.

Flow

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.

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.

{
  "_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

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.

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 when you confirm. Reference: Confirm a TED payment

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 — it becomes CANCELLED and nothing is sent. Send no body:

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 to see its status, or list the TEDs of a wallet, an account, an organization or your realm — 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 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.
`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

Send a Pix payment

Pay by Pix key, QR code or bank details.

Wallets for your customers

Read balances and transaction limits, and move money between wallets.

Getting Started

Integration guides

Cards

PIX & payments

Accounts & wallets

Building your integration

Flow

Who can send a TED

Step 1: Create the TED

Step 2: Confirm the TED

When the receiving bank returns the TED

Cancel a TED

Follow a TED

Common errors

Next steps

Send a Pix payment

Wallets for your customers

​Flow

​Who can send a TED

​Step 1: Create the TED

​Step 2: Confirm the TED

​When the receiving bank returns the TED

​Cancel a TED

​Follow a TED

​Common errors

​Next steps

Send a Pix payment

Wallets for your customers

Flow

Who can send a TED

Step 1: Create the TED

Step 2: Confirm the TED

When the receiving bank returns the TED

Cancel a TED

Follow a TED

Common errors

Next steps