API Reference

Getting Started with Compound Ledger

Introduction

Bond's Compound Ledger exposes the same ledger that supports Bond's embedded finance products to a general audience, allowing you to use Bond's double-entry accounting system built on ISO-8583 standards to manage balances of accounts not tied to Bond-issued cards or accounts.

You can integrate Compound Ledger into your app without being an expert in accounting systems, and can track balances with just a few API calls.

Typical use-cases for Compound Ledger include:

  • Replacing a managed ledger by a downstream card processor with something more reliable so that you can better represent balances and transactions to your users.
  • Tracking non-monetary assets like points, miles, or other rewards as they get earned and redeemed by your users.
  • Scale up managing accrued balances and payouts for tens of thousands of accounts.
  • Store balances of other virtual assets in an auditable and highly-reliable way.
  • Building a peer-to-peer closed-loop transaction processing system built on an omnibus account structure.

Getting API Keys

To sign up, visit signup.ledger.bond.tech and sign up for Compound Ledger. There, you will be able to create API keys for Compound Ledger, and view accounts and transactions that you create. See Authentication for more details.

Creating Accounts

An account is an entity that you create that can maintain balances. You don't have to pass any information to creating an account. For example, 

curl --location --request POST 'https://api.ledger.bond.tech/api/v0/accounting/accounts' \
--header 'Identity: YOUR-IDENTITY' \
--header 'Authorization: YOUR-AUTHORIZATION' \
--header 'Content-Type: application/json' \
--data-raw '{}'

will yield a response with an auto-generated account UUID and the balances of that created account: 

{
    "balances": {
        "available": 0,
        "settled": 0
    },
    "id": "831d4a3b-9e7e-47c2-8446-a532c8838435"
}

📘

Adding metadata to accounts

The ability to add queryable metadata to accounts is coming soon. This will allow you to add arbitrary attributes like a customer ID, your own identifier, or other information to accounts you create. You'll then be able to query on these attributes when looking up accounts.

If you are interested in using metadata in accounts, please send an email to [email protected] so that we can provide early-access to this feature.

Logging Transactions

Once accounts have been created, you can create transactions that affect the balance of those accounts. Bond supports both single-account transactions and account-to-account transactions:

  • Single account transactions are transactions that only affect one account in the ledger. They can be used for transactions like account funding from an external source, card transactions that withdraw funds from a single account, and rewards disbursements that add funds to a single account.
  • Account-to-account transactions are transactions that move funds from one account on the ledger to another. These can be use for peer-to-peer transactions or transactions between different accounts under a single user.

Compound Ledger also provides the option for whether the transaction should settle immediately or should settle later.

  • If the transaction is set to settle later, then after the transaction is created, it will be set to pending, with the transaction only affecting the available_balance of the account. It will then need to be settled manually with the settle API to be completed.

Note: Account-to-account transactions always settle immediately.

See the Transaction Lifecycle page for much more detail on how transactions can be settled.

The most basic example to get started making transactions after creating two accounts would be to (1) make a single-account deposit to fund Account 1, and (2) make an account-to-account transaction to move funds from Account 1 to Account 2. For example:

Single-account Deposit

curl --location --request POST 'https://api.ledger.bond.tech/api/v0/accounting/transactions' \
--header 'Identity: 9be7fd14-d9f3-4405-91f5-55b68d88243f' \
--header 'Authorization: gM5rvQia4oJ1fE6ZcGZwtLh4S/K0sOZnj2eNKBwZD34PIBzMI7cLAsBAr+Jn9zv+' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": 100,
    "account_id": "account1-id",
    "is_immediately_settle": true,
    "transaction_type": "SINGLE_ACCOUNT_DEPOSIT",
    "description": "initial funding"
}'

with response: 

{
    "account_id": "831d4a3b-9e7e-47c2-8446-a532c8838435",
    "amount": 100,
    "description": "initial funding",
    "from_account_id": null,
    "id": "5ce324be-6dae-4754-9f09-30decb540b37",
    "to_account_id": null,
    "transaction_state": "COMPLETED",
    "type": "SINGLE_ACCOUNT_DEPOSIT"
}

Account-to-account Transaction

curl --location --request POST 'https://api.ledger.bond.tech/api/v0/accounting/transactions' \
--header 'Identity: 9be7fd14-d9f3-4405-91f5-55b68d88243f' \
--header 'Authorization: gM5rvQia4oJ1fE6ZcGZwtLh4S/K0sOZnj2eNKBwZD34PIBzMI7cLAsBAr+Jn9zv+' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": 10,
    "from_account_id": "831d4a3b-9e7e-47c2-8446-a532c8838435",
    "to_account_id": "78ba55d2-3f74-4deb-a244-889aac93f03a",
    "is_immediately_settle": true,
    "transaction_type": "ACCOUNT_TO_ACCOUNT"
}'

with response: 

{
    "account_id": null,
    "amount": 10,
    "description": "",
    "from_account_id": "831d4a3b-9e7e-47c2-8446-a532c8838435",
    "id": "7d163b1e-8a9f-49d4-8950-be2729324062",
    "to_account_id": "78ba55d2-3f74-4deb-a244-889aac93f03a",
    "transaction_state": "COMPLETED",
    "type": "ACCOUNT_TO_ACCOUNT"
}

📘

Adding metadata to transactions

The ability to add queryable metadata to transactions is coming soon. This will allow you to add arbitrary attributes like a transaction tags, your own identifier, or other information to transactions. You'll then be able to query on these attributes when querying on transactions.

If you are interested in using metadata in transactions, please send an email to [email protected] so that we can provide early-access to this feature.