External bank transfers (TED)

🚧

API Upgrade

Starting in v2.3.0 external bank transfers using BRLD are considered deprecated and will be disable soon. Check the BRLP migration guide with the support service desk.

External bank transfers use the TED (Transferência Eletrônica Disponível) system in Brasil, which allows fast and secure fiat movement between accounts from different banks.

When creating a new withdrawal request through TED, you may send all the banking information as part of the transfer request, or you can select a previously created Banking for convenience.

const me = await bitcapital.users().me();
const source = me.wallets[0].id;

// Taking an asset out of the Bitcapital platform is always called "withdraw"
const transaction = await  bitcapital.wallets().withdraw(source, {
  amount: 100,
  // This banking information will be used to create a new Banking Information associated with the source user.
  // Optionally, instead of `bank` you could use a previously
  // created destination banking information.
  // For more informations check out    https://developers.bitcapital.com.br/docs/managing-banking-infos
  // bankingId: '4bdbcc4c-203a-4a79-9608-c83a27ae528d'
  bank: {
    holderType: AccountType.PERSONAL,
    bank: '123',
    agency: 456,
    agencyDigit: '0', // Use zero or '' if unavailable
    account: 789,
    accountDigit: 'X', // Use zero or '' if unavailable
    name: 'John Nobody',
    taxId: '123456789', // CPF
    //asset: 'BRLD', // If not set, the system uses the root asset
  }
});
curl --location --request POST 'https://instance-url.btcore.app/wallets/7a19e13b-60c1-49cd-b309-165fd93b5485/withdraw' \
--header 'Authorization: Bearer 0000000000000000000000000000000000000000'\
--header 'Content-Type: application/json' \
--header 'X-Request-Signature: 140cf378103cb985a938fa3080401f9eb72524172f1a9725482c74a003d4993b' \
--header 'X-Request-Timestamp: 1578678110828' \
--data-raw '{
	"amount": "1.00",
	"bank": {
		"bank": 123,
		"agency": 456,
		"agencyDigit": "0",
		"account": 789,
		"accountDigit": "X",
		"taxId": "123456789",
                "holderType": "personal",
		"name": "John Nobody"
	}
}'

For more informations about the request, check out our api reference.


STR Extra Fields

📘

Idempotency

The withdrawal endpoint is idempotent using the header X-Idempotence-Key as it's key. For more informations on idempotency, check out this article.

For the STR Provider and it's assets, withdraws have some other optional fields that can be used in your operations. All of them should be used inside an "extra" object in the root of the withdrawal request object:

FieldDescription
extra.scheduledForOptional field: ISO Date

Schedules a withdrawal in the STR. The transaction will be authorized but only executed when the time comes.
extra.purposeOptional field: number

Specifies the purpose used in the TED, using the codes indicated in the BACEN Messaging Protocol. The default is 10, relating to Credit in Account.

The complete list is available in the Purpose Code Reference.
extra.creditAgreementIdOptional field: number

The credit agreement id to be sent in case this TED is used for a credit agreement payment between a financial institution and a client.
extra.accountExternalIdOptional field: string
PIX ONLY
The account id on your platform, used to reference an account outside Bit Capital, if this option is set, the source account in the message will follow the informations saved from it.
extra.remittanceInfoOptional field: string
PIX ONLY
Used as a "description" field for the receiving party to see in it's receipt.