Reservations API endpoints for holding and releasing funds
Reservations place a hold on funds in a wallet without actually moving them. This is useful for authorization patterns where you need to ensure funds are available before completing a transaction.
Hold funds in a wallet for a future transaction.
Header Required Description AuthorizationYes Bearer token Content-TypeYes application/jsonIdempotency-KeyYes Unique request identifier
Field Type Required Description wallet_idstring Yes Wallet to reserve funds from amountstring Yes Amount to reserve (decimal string) assetstring Yes Asset type (e.g., POINTS, BONUS) expires_atstring No Expiration timestamp (ISO 8601, default: 15 minutes) referencestring No Your reference for this reservation metadataobject No Custom key-value pairs lot_selectionobject No Configure which lots to hold
Field Type Default Description lot_selection.strategystring fifoSelection strategy: fifo, lifo, expiring_first, specific lot_selection.lot_idsarray - Specific lot IDs (required when strategy is specific)
curl -X POST {{BASE_URL}}/reservations \ -H " Authorization: Bearer {{API_KEY}} " \ -H " Content-Type: application/json " \ -H " Idempotency-Key: {{IDEMPOTENCY_KEY}} " \ -d ' { "wallet_id": "wal_abc123def456", "amount": "75.00", "asset": "POINTS", "expires_at": "2024-01-15T12:00:00Z", "reference": "order_auth_789", "metadata": { "order_id": "ord_12345", "merchant": "coffee_shop" }, "lot_selection": { "strategy": "expiring_first" } } ' { " data " : { " id " : " rsv_abc123def456 " , " wallet_id " : " wal_abc123def456 " , " amount " : " 75.00 " , " asset " : " POINTS " , " status " : " active " , " expires_at " : " 2024-01-15T12:00:00Z " , " reference " : " order_auth_789 " , " held_lots " : [ { " lot_id " : " lot_xyz789abc123 " , " amount " : " 75.00 " } ] , " metadata " : { " order_id " : " ord_12345 " , " merchant " : " coffee_shop " } , " created_at " : " 2024-01-15T11:45:00Z " } } Code Description WALLET_NOT_FOUNDWallet does not exist WALLET_SUSPENDEDCannot reserve from a suspended wallet INSUFFICIENT_BALANCEWallet has insufficient available funds INVALID_AMOUNTAmount must be a positive decimal INVALID_ASSETAsset type is not configured INVALID_EXPIRYExpiration must be in the future LOT_NOT_FOUNDSpecified lot does not exist LOT_INSUFFICIENT_BALANCESpecified lot has insufficient balance POLICY_VIOLATIONReservation violates wallet policies
Convert a reservation into an actual debit from the wallet.
POST /reservations/{{RESERVATION_ID}}/commit Parameter Type Description reservation_idstring The reservation ID
Field Type Required Description amountstring No Amount to commit (defaults to full reservation) referencestring No Your reference for the commit metadataobject No Additional metadata to merge
curl -X POST {{BASE_URL}}/reservations/{{RESERVATION_ID}}/commit \ -H " Authorization: Bearer {{API_KEY}} " \ -H " Content-Type: application/json " \ -H " Idempotency-Key: {{IDEMPOTENCY_KEY}} " \ -d ' { "amount": "65.00", "reference": "order_complete_789", "metadata": { "final_amount": "65.00", "tip_included": false } } ' { " data " : { " id " : " rsv_abc123def456 " , " wallet_id " : " wal_abc123def456 " , " original_amount " : " 75.00 " , " committed_amount " : " 65.00 " , " released_amount " : " 10.00 " , " asset " : " POINTS " , " status " : " committed " , " reference " : " order_complete_789 " , " debit_id " : " dbt_pqr789stu012 " , " metadata " : { " order_id " : " ord_12345 " , " merchant " : " coffee_shop " , " final_amount " : " 65.00 " , " tip_included " : false } , " created_at " : " 2024-01-15T11:45:00Z " , " committed_at " : " 2024-01-15T11:55:00Z " } } When committing less than the reserved amount, the difference is automatically released back to the wallet's available balance.
Code Description RESERVATION_NOT_FOUNDReservation does not exist RESERVATION_EXPIREDReservation has expired RESERVATION_ALREADY_COMMITTEDReservation was already committed RESERVATION_ALREADY_RELEASEDReservation was already released AMOUNT_EXCEEDS_RESERVATIONCommit amount exceeds reserved amount
Cancel a reservation and return the held funds to available balance.
POST /reservations/{{RESERVATION_ID}}/release Parameter Type Description reservation_idstring The reservation ID
Field Type Required Description reasonstring No Reason for releasing metadataobject No Additional metadata
curl -X POST {{BASE_URL}}/reservations/{{RESERVATION_ID}}/release \ -H " Authorization: Bearer {{API_KEY}} " \ -H " Content-Type: application/json " \ -H " Idempotency-Key: {{IDEMPOTENCY_KEY}} " \ -d ' { "reason": "Order cancelled by customer", "metadata": { "cancelled_by": "user_12345" } } ' { " data " : { " id " : " rsv_abc123def456 " , " wallet_id " : " wal_abc123def456 " , " amount " : " 75.00 " , " asset " : " POINTS " , " status " : " released " , " release_reason " : " Order cancelled by customer " , " metadata " : { " order_id " : " ord_12345 " , " merchant " : " coffee_shop " , " cancelled_by " : " user_12345 " } , " created_at " : " 2024-01-15T11:45:00Z " , " released_at " : " 2024-01-15T11:50:00Z " } } Code Description RESERVATION_NOT_FOUNDReservation does not exist RESERVATION_ALREADY_COMMITTEDReservation was already committed RESERVATION_ALREADY_RELEASEDReservation was already released
Retrieve details of a specific reservation.
GET /reservations/{{RESERVATION_ID}} Parameter Type Description reservation_idstring The reservation ID
curl -X GET {{BASE_URL}}/reservations/{{RESERVATION_ID}} \ -H " Authorization: Bearer {{API_KEY}} " { " data " : { " id " : " rsv_abc123def456 " , " wallet_id " : " wal_abc123def456 " , " amount " : " 75.00 " , " asset " : " POINTS " , " status " : " active " , " expires_at " : " 2024-01-15T12:00:00Z " , " reference " : " order_auth_789 " , " held_lots " : [ { " lot_id " : " lot_xyz789abc123 " , " amount " : " 75.00 " } ] , " metadata " : { " order_id " : " ord_12345 " , " merchant " : " coffee_shop " } , " created_at " : " 2024-01-15T11:45:00Z " } } Retrieve reservations for a wallet.
GET /wallets/{{WALLET_ID}}/reservations Parameter Type Description wallet_idstring The wallet ID
Parameter Type Default Description limitinteger 20 Number of results (max 100) cursorstring - Pagination cursor statusstring - Filter by status: active, committed, released, expired assetstring - Filter by asset type
curl -X GET " {{BASE_URL}}/wallets/{{WALLET_ID}}/reservations?status=active " \ -H " Authorization: Bearer {{API_KEY}} " { " data " : [ { " id " : " rsv_abc123def456 " , " wallet_id " : " wal_abc123def456 " , " amount " : " 75.00 " , " asset " : " POINTS " , " status " : " active " , " expires_at " : " 2024-01-15T12:00:00Z " , " reference " : " order_auth_789 " , " created_at " : " 2024-01-15T11:45:00Z " } ] , " pagination " : { " has_more " : false , " next_cursor " : null } } Extend the expiration time of an active reservation.
POST /reservations/{{RESERVATION_ID}}/extend Parameter Type Description reservation_idstring The reservation ID
Field Type Required Description expires_atstring Yes New expiration timestamp (ISO 8601)
curl -X POST {{BASE_URL}}/reservations/{{RESERVATION_ID}}/extend \ -H " Authorization: Bearer {{API_KEY}} " \ -H " Content-Type: application/json " \ -H " Idempotency-Key: {{IDEMPOTENCY_KEY}} " \ -d ' { "expires_at": "2024-01-15T14:00:00Z" } ' { " data " : { " id " : " rsv_abc123def456 " , " wallet_id " : " wal_abc123def456 " , " amount " : " 75.00 " , " asset " : " POINTS " , " status " : " active " , " expires_at " : " 2024-01-15T14:00:00Z " , " previous_expires_at " : " 2024-01-15T12:00:00Z " , " created_at " : " 2024-01-15T11:45:00Z " , " extended_at " : " 2024-01-15T11:50:00Z " } } Code Description RESERVATION_NOT_FOUNDReservation does not exist RESERVATION_NOT_ACTIVECan only extend active reservations INVALID_EXPIRYNew expiration must be after current expiration MAX_EXTENSION_EXCEEDEDReservation cannot be extended beyond maximum duration
