ShiwakeDocs

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:

StatusHow it gets there
ActiveJust placed, not yet captured or released
CapturedCaller posted the settling journal entry: balance moves
ReleasedCaller abandoned the hold: available balance restored
ExpiredexpiresAt 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

POST/api/v1/ledger/holdsIdempotency-Key

Reserves 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

CodeWhen
201Hold placed
400Missing Idempotency-Key, invalid body
404Account does not exist
422Insufficient available balance, currency mismatch

Capture a hold

POST/api/v1/ledger/holds/{holdId}/captureIdempotency-Key

Settles 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

CodeWhen
200Hold captured; journal entry posted
400Missing Idempotency-Key, invalid body
404Hold does not exist
409Hold is not in Active status (already captured/released/expired)
422Capture amount exceeds hold, lines don't balance, insufficient balance

Release a hold

POST/api/v1/ledger/holds/{holdId}/releaseIdempotency-Key

Abandons 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

CodeWhen
200Hold released
404Hold does not exist
409Hold is not in Active status

List holds on an account

GET/api/v1/ledger/accounts/{accountId}/holds

Returns 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_..."
Edit on GitHub

Last updated on

On this page