Bit Capital

The Bit Capital Developer Hub

Welcome to the Bit Capital developer hub. You'll find comprehensive guides and documentation to help you start working with the platform as quickly as possible, as well as support if you get stuck. Let's jump right in!

Guides    Community

Handling Deposits

How to handle deposits in the platform?

When integration on the platform after you successfully created an account the next step is to process deposits to your digital accounts, in this section we explain a little more how the deposit flow works and the fields you should implement.


Deposit Events

Every time a digital account receives a deposit, it'll generate a postback to your instance(if configured, to learn how to set it up check out this link) with the entity transaction.
You can identify a deposit postback looking for the payments inside the transaction, if there's a payment with the type deposit it indicates that a deposit just happened in the account.

A deposit transaction has a set of pre-defined fields and depending on the custody provider it can provide some other additional fields. Here we describe each custody provider and how it generates a deposit transaction.


Client-to-Client Deposits (STR0008)

Client Deposits are deposits originated by a client from another bank, so the transaction is between clients from Financial Institutions (FIs), In those cases the deposits look like the ones below:

DOCK Provider

{
        "payments": [
            {
                "status": "settled",
                "type": "deposit",
                "destination": {
                    "id": "5fd48d30-f9f3-452e-93ba-c13d6c8ff1ce",
                    "stellar": {
                        "publicKey": "GA6A4OSFYBASFIEOBGMCSQEUVV6CHECTMINRWJ4OSYG666BXH4S4US33"
                    },
                    "updatedAt": "2019-06-28T17:23:24.981Z",
                    "createdAt": "2019-06-28T17:23:24.981Z",
                    "user": {
                        "id": "891fa348-c676-458e-ba59-7fe4400c7849",
                        "name": "JOÃO BRITO",
                        "firstName": "JOÃO",
                        "lastName": "BRITO",
                        "email": "[email protected]",
                        "role": "consumer",
                        "twoFactorRequired": false,
                        "updatedAt": "2019-09-16T18:41:03.096Z",
                        "createdAt": "2019-06-28T17:23:24.265Z"
                    }
                },
                "amount": "1",
                "asset": {
                    "id": "1edf6304-fb5d-4208-9444-93a99b9d10f1",
                    "name": "BRL Digital",
                    "code": "BRLD",
                    "root": true,
                    "provider": "cdt-visa",
                    "updatedAt": "2019-06-27T19:27:23.834Z",
                    "createdAt": "2019-06-27T19:27:23.834Z"
                },
                "scheduleFor": null,
                "updatedAt": "2020-04-01T06:03:04.752Z",
                "createdAt": "2020-04-01T06:03:04.752Z",
                "id": "674dc2af-1871-41e6-b173-8e1fe7380849"
            }
        ],
        "source": {
            "id": "0041a0e8-c096-4946-bbbe-63609bf8c67b",
            "root": true,
            "stellar": {
                "publicKey": "DAGPSIHDVEMMMH55GI3YNNR4KPU4OKZGF3XBOXYRCJWCNNZT4PHVI2MA"
            },
            "updatedAt": "2019-06-27T19:27:23.823Z",
            "createdAt": "2019-06-27T19:27:23.823Z",
            "user": {
                "id": "417c7972-cc9b-4b23-b956-5a87d06ed587",
                "name": "Bit Capital Issuer",
                "firstName": "Bit Capital",
                "lastName": "Issuer",
                "email": "[email protected]",
                "role": "admin",
                "twoFactorRequired": false,
                "updatedAt": "2019-06-27T19:27:23.814Z",
                "createdAt": "2019-06-27T19:27:23.814Z"
            }
        },
        "states": [
            {
                "additionalData": {}
                "updatedAt": "2020-04-01T06:03:06.590Z",
                "createdAt": "2020-04-01T06:03:04.883Z",
                "status": "AUTHORIZED",
                "id": "22934c1f-31b3-4a98-8938-b345acc10c09"
            },
            {
                "additionalData": {},
                "updatedAt": "2020-04-01T06:03:04.745Z",
                "createdAt": "2020-04-01T06:03:04.745Z",
                "status": "pending",
                "id": "d1bd916f-090e-4394-9106-eea78be1ae3f"
            }
        ],
        "updatedAt": "2020-04-01T06:03:04.709Z",
        "createdAt": "2020-04-01T06:03:04.709Z",
        "additionalData": {
            "externalTransaction": {
                "createdAt": "None",
                "id": 1631
            },
            "wallet_id": "5fd48d30-f9f3-452e-93ba-c13d6c8ff1ce"
        },
        "status": "AUTHORIZED",
        "type": "payment",
        "id": "9f08a514-cf57-48b1-96df-6ee104ed473b"
    }

STR Provider

{
        "payments": [
            {
                "status": "settled",
                "type": "deposit",
                "destination": {
                    "id": "25e4f719-081c-42d8-862c-f32861f389e9",
                    "stellar": {
                        "publicKey": "DC22Z7BOVVPLGPVOSZTJSBDX2AAW7LX5UUI63R5Z62VQRTQ52JRXVHDS"
                    },
                    "updatedAt": "2019-11-13T02:47:57.864Z",
                    "createdAt": "2019-11-13T02:47:57.864Z",
                    "user": {
                        "id": "bb8fe757-4470-40ba-b3e8-c86e630441cb",
                        "name": "João Brito",
                        "firstName": "João",
                        "lastName": "Brito",
                        "email": "[email protected]",
                        "role": "consumer",
                        "twoFactorRequired": false,
                        "updatedAt": "2019-11-13T02:47:57.647Z",
                        "createdAt": "2019-11-13T02:47:57.653Z"
                    }
                },
                "amount": "5.00",
                "asset": {
                    "id": "5858aaaf-acfe-4ab3-b981-bba22aa20109",
                    "name": "BRL Parati",
                    "code": "BRLP",
                    "root": true,
                    "provider": "parati-provider",
                    "updatedAt": "2019-11-13T02:30:33.573Z",
                    "createdAt": "2019-11-13T02:30:33.573Z"
                },
                "scheduleFor": null,
                "updatedAt": "2020-04-20T16:04:02.546Z",
                "createdAt": "2020-04-20T16:04:02.546Z",
                "id": "e6f006f1-0aee-44bc-94c6-dc0b64335b98"
            }
        ],
        "source": {
            "id": "54d62d41-585b-455a-a730-78cbac0d947e",
            "root": true,
            "stellar": {
                "publicKey": "GAGPSIHDVEMMMH55GI3YNNR4KPU4OKZGF3XBOWYRCJWCNZNT4PHVI2DC"
            },
            "updatedAt": "2019-11-13T02:30:33.449Z",
            "createdAt": "2019-11-13T02:30:33.449Z",
            "user": {
                "id": "fefe4065-e3a8-4e01-8d7e-8f7842504500",
                "name": "Bit Capital Issuer",
                "firstName": "Bit Capital",
                "lastName": "Issuer",
                "email": "[email protected]",
                "role": "admin",
                "twoFactorRequired": false,
                "updatedAt": "2019-11-13T02:30:33.420Z",
                "createdAt": "2019-11-13T02:30:33.420Z"
            }
        },
        "states": [
            {
                "additionalData": {},
                "updatedAt": "2020-04-20T16:04:08.379Z",
                "createdAt": "2020-04-20T16:04:08.379Z",
                "status": "notified",
                "id": "9e6b8c78-8cc2-46c9-9867-acbfb018ecf0"
            },
            {
                "additionalData": {},
                "updatedAt": "2020-04-20T16:04:07.553Z",
                "createdAt": "2020-04-20T16:04:07.553Z",
                "status": "executed",
                "id": "7468693e-b0b4-45f3-8135-b2a6232ea7c8"
            },
            {
                "additionalData": {
                    "authorized": [],
                    "skipped": [
                        {
                            "provider": "parati-provider",
                            "payment": "e6f006f1-0aee-44bc-94c6-dc0b64335b98",
                            "asset": "BRLP"
                        }
                    ]
                },
                "updatedAt": "2020-04-20T16:04:03.597Z",
                "createdAt": "2020-04-20T16:04:02.678Z",
                "status": "AUTHORIZED",
                "id": "6aafe128-1bc3-41fa-b4ce-5589ef83980d"
            },
            {
                "additionalData": {},
                "updatedAt": "2020-04-20T16:04:02.540Z",
                "createdAt": "2020-04-20T16:04:02.540Z",
                "status": "pending",
                "id": "eb33bcd2-5326-4159-a715-c51ce194218f"
            }
        ],
        "updatedAt": "2020-04-20T16:04:07.445Z",
        "createdAt": "2020-04-20T16:04:02.534Z",
        "additionalData": {
            "externalTransaction": {
                "id": "STR20200420034373139"
            },
            "destination": {
                "accountHolderTaxId": "1234567890",
                "accountHolderName": "JOAO BRITO",
                "accountNumber": "1908",
                "branchNumber": "1"
            },
            "description": "Crédito em Conta",
            "reversal": false,
            "source": {
                "accountHolderTaxId": "1234567890",
                "accountHolderName": "JOAO BRITO",
                "accountNumber": "123457788",
                "branchNumber": "1",
                "bankNumber": "260"
            },
            "hash": "c4197ac8487a942a795ed5808270063c99ea67b0a2ac32906da2b2d8746b8545"
        },
        "status": "notified",
        "type": "payment",
        "id": "3183c3fc-0d0a-42c4-ae05-163effb4deec"
    }

As you can see, in the additionalData of the transaction you can see a lot of informations about the transaction, and many more are available. If you are missing something, you can ask for that in our help desk or in our community section.

FI-to-Client Deposit (STR0007)

This flow happens when an FI needs to pay a client from another bank for some operation. In this cases the deposit will be made in the settlement account with a additionalData that looks like this:

{
            "externalTransaction": {
                "id": "88d8625e-Bf5Z"
            },
            "destination": {
                "accountHolderTaxId": "09001630707",
                "accountHolderType": "personal",
                "accountHolderName": "Mr. Dieguito",
                "accountNumber": "30608366",
                "branchNumber": "1"
            },
            "description": "Visa Crédito - Liquidação Doméstica",
            "reasonCode": 114,
            "reversal": false,
            "source": {
                "bankNumber": "341"
            },
            "hash": "c2ac08dbb869809dbe08d7141ec760d9806e68a2f652ec978ffb14551ab8581b",
            "str": {
                "messageCode": "STR0007R2"
            }
        }

(SaaS only) FI-to-FI Deposit (STR0004)

FI-to-FI deposits are deposits originated by a financial institution to another financial institution, for example a bank paying another bank for some operation they both had. In this cases the deposit will be made in the settlement account with a additionalData that looks like this:

{
            "externalTransaction": {
                "id": "STR20200720033031253"
            },
            "destination": {
                "accountHolderType": "financial_institution"
            },
            "description": "Antecipação de recebíveis",
            "reasonCode": 90,
            "reversal": false,
            "source": {
                "accountHolderType": "financial_institution",
                "bankNumber": "326"
            },
            "hash": "f318590d8aced1679573c36fc335c69ed82d3afc27d5715ef7a0cd83e8b5ef8e",
            "str": {
                "messageCode": "STR0004R2"
            }
        }

(SaaS only) Client-To-FI Deposit (STR0006)

This happens when a client needs to pay your FI for some operation you and him had from another bank. In this cases the deposit will be made in the settlement account with a additionalData that looks like this:

{
            "externalTransaction": {
                "id": "4HH2D8777R-VT3R"
            },
            "destination": {},
            "description": "787878",
            "reasonCode": 787878,
            "reversal": false,
            "source": {
                "accountHolderTaxId": "09072897000133",
                "accountHolderType": "corporate",
                "accountHolderName": "Mitá Tecnologia",
                "accountNumber": "6151620",
                "branchNumber": "1849",
                "bankNumber": "1"
            }
}

(SaaS only) Credit Portability Deposit (STR0047)

These deposits happen when another FI does a credit portability and pays you for it. In this cases the deposit will be made in the settlement account with a additionalData that looks like this:

{
            "externalTransaction": {
                "id": "4HH2D8777R-VT3R"
            },
            "destination": {
                "accountHolderType": "financial_institution",
                "branchNumber": "1"
            },
            "reversal": false,
            "source": {
                "accountHolderType": "financial_institution",
                "bankNumber": "1"
            },
            "hash": "68afbb1f2d999ba4a4bb6cca0683c0ce03c0d4d34372a4192218c0bdfb116e2e",
            "str": {
                "messageCode": "STR0047R2"
            }
}

Updated 4 months ago



Handling Deposits


How to handle deposits in the platform?

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.