Managing Banking Information

Managing your consumer's frequent transaction destinations to external institutions

In the Bit Capital platform we call a BankingInfo as a set of informations that reference an external bank account. Every time a user sends a withdrawal, we save the banking informations from that transaction for the purpose of saving it to make it easier to send another withdrawal to that person.


Creating a Banking Information

Basically we have two ways of creating a new banking info for a consumer.

Automatic Creation

The first one is just sending a External bank transfers (TED) with the full bank field, the system will automatically create one associated with the user that did the transaction, such as:

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",
		"name": "John Nobody"
	}
}'

The system will respond with a Transaction, referencing the Banking Information ID generated for this bank field combination.

Manual Creation

The second way to generate a new entry is to manually request the creation of the banking information using the POST /consumers/:id/bankings method from the API, such as:

For personal accounts:

const bitcapital = Bitcapital.getInstance();
const me = await bitcapital.users().me();
const info = await bitcapital.bankings().create(me.id, {
  agency: 1,
  account: 1234,
  name: 'John Doe',
  taxId: '01234567890',
  bank: '123',
  // type: 'checking' is the default value
  // holderType: 'personal' is the default value
});
curl --location --request POST 'https://testnet.btcore.app/consumer/3c70525f-bc87-4859-8daf-ff053a5a059a/bankings' \
--header 'Content-Type: application/json' \
--data-raw ' {
 	"type": "checking",
	"bank": "260",
	"agency": "8074",
	"agencyDigit": "2",
	"account": "15936",
	"accountDigit": "2",
	"taxId": "012345678901",
	"name": "John Doe",
	"holderType": "personal"
}'

For corporate accounts:

const bitcapital = Bitcapital.getInstance();
const me = await bitcapital.users().me();
const info = await bitcapital.bankings().create(me.id, {
  type: "savings",
  name: "Corporate Company ME",
  holderType: "corporate",//requires holderType as corporate
  taxId: "100100100100",
  bank: "260",
  agency: 1212,
  account: 121212,
});

Withdraw to existing banking information


Once you have an existing Banking Information ID, you can speed up the withdrawal process requiring less fields in the request:


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,
  bankingId: '4bdbcc4c-203a-4a79-9608-c83a27ae528d'
});
curl --location --request POST 'https://testnet.btcore.app/wallets//withdraw/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": "100.00",
    "bankingId": ""
}'

Listing Existing Informations

To get the list of banking infos, use the GET consumers/:id/bankings method of the documentation.

const bitcapital = Bitcapital.getInstance();
const me = await bitcapital.users().me();
const list = await bitcapital.bankings().findAll(me.id)
curl --location --request GET 'https://testnet.btcore.app/consumer/3c70525f-bc87-4859-8daf-ff053a5a059a/bankings'

The response should be like the one below:

[
    {
        "accountDigit": "2",
        "account": 15936,
        "agencyDigit": "0",
        "agency": 1,
        "bank": "341",
        "type": "checking",
        "holderType": "personal",
        "taxId": "1234567890",
        "name": "John Doe",
        "updatedAt": "2019-11-13T03:04:25.458Z",
        "createdAt": "2019-11-13T03:04:25.458Z",
        "id": "b275b5c6-892b-4e7b-a02c-1a3579adb182"
    }
]

Managing Existing Informations

To retrieve the full information about a single banking Info you should use the GET /consumers/:userId/bankings/:bankingId method, with the specific IDs you're looking for.

const bitcapital = Bitcapital.getInstance();
const me = await bitcapital.users().me();

const info = await bitcapital.bankings().findOne(me.id, '8a12a7d7-1b13-4ee8-bc51-2b68b6485fd2');

console.log(info);
curl --location --request GET 'https://testnet.btcore.app/consumer/3c70525f-bc87-4859-8daf-ff053a5a059a/bankings/05fb7bad-0c37-4b72-b8fc-c2415acd214d'