Holds
Place, capture, and release authorization holds against an account's available balance.
A hold is a reservation against an account's available balance. It does not move money (the ledger balance is unchanged) but it reduces the amount available for new debits. Holds let you authorize a transaction now and settle it later, or authorize an amount and settle the final value once it's known.
Lifecycle
A hold is created in Active status and ends up in one of three terminal
states:
| Status | How it gets there |
|---|---|
Active | Just placed, not yet captured or released |
Captured | Caller posted the settling journal entry: balance moves |
Released | Caller abandoned the hold: available balance restored |
Expired | expiresAt passed; treated like a release |
Only active holds count against available balance. Once captured or released, they no longer reduce availability.
ledger_balance − Σ(active holds) = available_balance. See Accounts
for the two balance concepts.
The Hold object
{
"id": "hld_01HZ...",
"accountId": "acc_01HZ...",
"amountMinor": 25000,
"currency": "GHS",
"reference": "auth_01J...",
"status": "Active",
"journalEntryId": null,
"metadata": { "order": "ord_4821" },
"expiresAt": "2026-04-08T12:00:00Z",
"createdBy": "checkout-service",
"createdAt": "2026-04-07T12:00:00Z"
}Prop
Type
Place a hold
/api/v1/ledger/holdsIdempotency-KeyReserves amountMinor on an account. The account's ledger balance does not
change. Fails with 422 if the available balance is insufficient.
Request body
Prop
Type
curl -X POST "https://api.shiwake.example.com/api/v1/ledger/holds" \
-H "X-Api-Key: sk_live_..." \
-H "Idempotency-Key: 8b7f9c2e-4d1a-4e6b-9c3a-1f2e3d4c5b6a" \
-H "Content-Type: application/json" \
-d '{
"accountId": "acc_01HZ...",
"amountMinor": 25000,
"currency": "GHS",
"reference": "auth_01J...",
"createdBy": "checkout-service",
"expiresAt": "2026-04-08T12:00:00Z"
}'Status codes
| Code | When |
|---|---|
201 | Hold placed |
400 | Missing Idempotency-Key, invalid body |
404 | Account does not exist |
422 | Insufficient available balance, currency mismatch |
Capture a hold
/api/v1/ledger/holds/{holdId}/captureIdempotency-KeySettles an active hold by posting a journal entry. The entry's lines must balance per the usual double-entry rules (see Journal Entries). The captured amount can be less than the original hold. The remainder is released automatically.
Request body
Prop
Type
Each line has accountCode, entryType (Debit or Credit), amount, and
optional description: identical to a normal journal entry line.
curl -X POST "https://api.shiwake.example.com/api/v1/ledger/holds/hld_01HZ.../capture" \
-H "X-Api-Key: sk_live_..." \
-H "Idempotency-Key: 9c8f0d3f-5e2b-4f7c-ad4b-2e3f4d5c6b7c" \
-H "Content-Type: application/json" \
-d '{
"description": "Order ord_4821 settlement",
"createdBy": "checkout-service",
"lines": [
{ "accountCode": "CLIENT-42", "entryType": "Debit", "amount": 22500 },
{ "accountCode": "PLATFORM-FLOAT", "entryType": "Credit", "amount": 22500 }
]
}'Status codes
| Code | When |
|---|---|
200 | Hold captured; journal entry posted |
400 | Missing Idempotency-Key, invalid body |
404 | Hold does not exist |
409 | Hold is not in Active status (already captured/released/expired) |
422 | Capture amount exceeds hold, lines don't balance, insufficient balance |
Release a hold
/api/v1/ledger/holds/{holdId}/releaseIdempotency-KeyAbandons an active hold without posting an entry. The reserved amount returns to available balance immediately. Releasing is the right call when an authorization is cancelled before settlement.
Request body
Prop
Type
curl -X POST "https://api.shiwake.example.com/api/v1/ledger/holds/hld_01HZ.../release" \
-H "X-Api-Key: sk_live_..." \
-H "Idempotency-Key: ad9e1f4a-6f3c-5a8d-be5c-3f4e5d6c7b8d" \
-H "Content-Type: application/json" \
-d '{ "reason": "Customer cancelled order" }'Status codes
| Code | When |
|---|---|
200 | Hold released |
404 | Hold does not exist |
409 | Hold is not in Active status |
List holds on an account
/api/v1/ledger/accounts/{accountId}/holdsReturns holds for a specific account, newest first. Paginated with cursor
format createdAt|id. See Pagination.
Query parameters
Prop
Type
curl "https://api.shiwake.example.com/api/v1/ledger/accounts/acc_01HZ.../holds?status=Active&size=20" \
-H "X-Api-Key: sk_live_..."Last updated on