Skip to content

2. Deposits

Money arriving, and making sure a payment is never counted twice.

User 42 sends $1,000 by bank transfer. The money lands in the brokerage’s bank account, and the brokerage now owes it to the user.

Every posting has a kind, which says what it is. Kinds are registered once, like currencies. Deposits get their own kind, deposit, so later you can list just a user’s deposits:

POST /kinds
{ "name": "deposit" }
201 Created
{ "name": "deposit" }

One posting records both sides. It debits bank:client-money, an asset, and credits user:42:cash, a liability.

POST /transfers
{
"chains": [
[
{
"id": "00000000-0000-0000-0000-000000001001",
"debit": "bank:client-money",
"credit": "user:42:cash",
"currency": "USD",
"amount": "100000",
"kind": "deposit"
}
]
]
}
200 OK
{ "chains": [[{ "id": "00000000-0000-0000-0000-000000001001", "group_id": "00000000-0000-0000-0000-000000001001", "status": "created" }]] }

chains is a list of chains. A chain is a list of postings that all happen or none do. This deposit is one chain with one posting in it. The response has the same shape.

Both balances go up, as chapter 1 said they would:

Account Type Side Change Why
bank:client-money asset debit +$1,000 the bank holds $1,000 more
user:42:cash liability credit +$1,000 the brokerage owes the user $1,000 more

Payment providers tell you about a deposit with a webhook, and they often send the same webhook more than once. If each delivery added $1,000, the user would get free money.

The posting id prevents that. Send the same posting again, and Torment recognises it:

200 OK
{ "chains": [[{ "id": "00000000-0000-0000-0000-000000001001", "group_id": "00000000-0000-0000-0000-000000001001", "status": "exists" }]] }

exists means “already applied, nothing changed”. It’s a success, not an error.

The trick is to choose the id before you send anything, and store it with the payment:

  1. When the provider first tells you about a payment, create a row for it in your own database with a new posting id.
  2. Send the posting with that id.
  3. On every later webhook for the same payment, look up the row and send the same id again.

Provider ids like pay_8f3k2 can’t be used directly, because Torment ids are UUIDs. That’s why you keep your own.

Ids are UUIDs. This tutorial writes them as 00000000-0000-0000-0000-000000001001, with a short number at the end, so they’re easy to read and …2001 visibly belongs to order …2000. In production, generate a UUIDv7 for each posting; any language’s UUID library can. UUIDv7s increase over time, which TigerBeetle prefers: random UUIDs work, but they slow it down.

If the request times out or returns a 500, you don’t know whether the deposit was applied. Send the exact same request again. Each posting comes back created (it wasn’t applied before) or exists (it was). Either way, it’s applied exactly once.

Account USD
bank:client-money 1,000.00
user:42:cash 1,000.00

Next, the user spends it.