Reserve funds (the pending phase of a two-phase posting)
The reserve half of a two-phase posting.
/v1/ledgers/{ledgerId}/pendingsThe reserve half of a two-phase posting. It holds amount against the account for ttl_seconds without writing any entry, which is what replaces the shared database transaction a service boundary cannot reach: reserve here, commit your own state, then post or void. The reservation is checked against available funds at creation, so insufficient_funds, account_frozen and account_closed all refuse here rather than at capture. Requires an Idempotency-Key. The TTL is a promise, not just a schedule: consumption past expires_at is refused even before the sweeper gets to the row.
Authorization
bearerAuth In: header
Path Parameters
uuidHeader Parameters
Replays return the original response byte-identically within the retention window.
1 <= length <= 255Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/problem+json
curl -X POST "https://example.com/v1/ledgers/497f6eca-6276-4993-bfeb-53cbbbba6f08/pendings" \ -H "Idempotency-Key: string" \ -H "Content-Type: application/json" \ -d '{ "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65", "amount": 1, "ttl_seconds": 1 }'{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65", "reference_id": "97c1ff22-6e4f-4821-b1d3-5236781d37b8", "amount": 0, "status": "pending", "expires_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z"}Validate a posting against live state without committing
Walks the entire posting path against live state - vocabulary, account locks, floors, owner floors, preconditions, limit claims, closed periods - and then rolls everything back.
Read one pending, whatever its state
Reads one pending in any state - pending, posted, voided or expired.