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.
A kind for deposits
Section titled “A kind for deposits”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:
{ "name": "deposit" }{ "name": "deposit" }The posting
Section titled “The posting”One posting records both sides. It debits bank:client-money, an asset, and credits user:42:cash, a liability.
{ "chains": [ [ { "id": "00000000-0000-0000-0000-000000001001", "debit": "bank:client-money", "credit": "user:42:cash", "currency": "USD", "amount": "100000", "kind": "deposit" } ] ]}{ "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 |
Counting a payment once
Section titled “Counting a payment once”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:
{ "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:
- When the provider first tells you about a payment, create a row for it in your own database with a new posting id.
- Send the posting with that id.
- 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.
Choosing ids
Section titled “Choosing ids”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.
When the request itself fails
Section titled “When the request itself fails”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.
Where this leaves us
Section titled “Where this leaves us”| Account | USD |
|---|---|
bank:client-money |
1,000.00 |
user:42:cash |
1,000.00 |
Next, the user spends it.