​

Authorize wallet holds for multi-step purchases

​

1. The race one-phase debit creates

• Charge up front, then call the provider. If the carrier rejects, or the KYC reviewer denies, the wallet is debited with no delivery. Until releaseHold existed, that charge had no programmatic refund path; it accumulated as drift that finance reconciled by hand.
• Call the provider, then charge. The whole provider-call window becomes a solvency race: any number of concurrent purchases all read the old balance as sufficient, all spend, and the wallet over-draws.

​

2. The three primitives

​

placeHold — authorize the debit

import { placeHold } from "@devotel/billing";

const hold = await placeHold({
  tenantId,
  amount: 1250,               // positive integer cents
  holdId: "did-order:ord_7f3", // caller-supplied, unique per reservation
  reason: "did-purchase",
});

// → { idempotencyKey: "hold:did-order:ord_7f3",
//     remaining: <balance after the debit, cents>,
//     idempotentReplay: false }

• holdId must match ^[a-z0-9][a-z0-9:_-]{0,119}$ (no spaces, 1–120 chars) so the hold/release key pair stays collision-free. A structured slug like did-order:<orderId> or kyc:<submissionId> keeps the ledger readable.
• The authorize debit is stamped under the derived key hold:<holdId>. A duplicate placeHold for the same holdId replays the cached result (idempotentReplay: true) and does not charge twice — so your own retry after a transport timeout is safe.
• Options: ledgerOptions forwards attribution to the ledger row; solvencyFloorCents is a post-authorize probe that reports belowSolvencyFloor: true (hold still succeeded — pure observability for e.g. wholesale-rate misconfig alerts).
• The stored ledger reason is hold:<reason>:<holdId>, which distinguishes the authorize row from a one-phase charge.

​

captureHold — settle the purchase

import { captureHold } from "@devotel/billing";

const settled = await captureHold({
  tenantId,
  capturedAmount: 1250,      // the figure you actually settled for
  authorizedAmount: 1250,    // what placeHold authorized (the upper bound)
  holdId: "did-order:ord_7f3",
  reason: "did-purchase",
});

• Both amounts must be positive integer cents.
• capturedAmount over authorizedAmount throws — a caller bug (settle at or below the hold; if the carrier upsold mid-flight, release and re-authorize).
• holdId must be the same tenant-safe slug passed at authorize time.

​

releaseHold — refund a failed leg

import { releaseHold } from "@devotel/billing";

const refund = await releaseHold({
  tenantId,
  amount: 1250,                                 // MUST equal the authorized amount
  chargeIdempotencyKey: "hold:did-order:ord_7f3", // the EXACT authorize key
  reason: "did-purchase",                        // optional free-text suffix
});

// → { released: true, remaining: <balance after the credit, in cents> }

• chargeIdempotencyKey must be the byte-identical string placeHold stamped — hold:<holdId> verbatim. Get the wrong text and a wrong amount means no release; a wrong key means the release retries forever. holdIdempotencyKey(holdId) is exported if you prefer deriving it programmatically.
• amount must match the authorized figure. There is deliberately no per-charge refund cap, so an incorrect amount is not caught — it would make the release a silent wrong-valued credit.
• The authorize debit row and the release credit row both stay in the ledger (type debit / refund), so finance reconciliation always sees the pair.

​

3. Worked example — a DID purchase order

import { placeHold, captureHold, releaseHold } from "@devotel/billing";

const holdId = `did-order:${order.id}`;
const authorized = order.quoteAmountCents;

// 1. AUTHORIZE the moment the customer confirms the order.
await placeHold({ tenantId, amount: authorized, holdId, reason: "did-purchase" });

try {
  const provision = await carrier.buyAndKyc(order);   // slow third-party legs
  // 2. CAPTURE when the carrier confirms — settle at the authorized figure
  //    (or the carrier's final, if it came back lower).
  await captureHold({
    tenantId,
    capturedAmount: provision.finalAmountCents,
    authorizedAmount: authorized,
    holdId,
    reason: "did-purchase",
  });
  if (provision.finalAmountCents < authorized) {
    // Give the unused remainder back — still exactly-once.
    await releaseHold({
      tenantId,
      amount: provision.finalAmountCents,
      chargeIdempotencyKey: `hold:${holdId}`,
      reason: "did-purchase-partial",
    });
  }
} catch (err) {
  // 3. RELEASE in full when anything terminal fails after the authorize.
  await releaseHold({
    tenantId,
    amount: authorized,
    chargeIdempotencyKey: `hold:${holdId}`,
    reason: "did-purchase",
  });
  throw err;
}

​

4. Common mistakes

• Releasing after settle. If captureHold succeeded, do not also call releaseHold for the same hold; release is the compensating branch of failure paths, and a second credit after a successful settle double-refunds. If your figure came back lower, release only the difference — never the whole authorized amount after capture.
• Passing the wrong key to release. chargeIdempotencyKey must be the exact string authorize stamped, e.g. hold:did-order:ord_7f3. Passing the bare holdId (did-order:ord_7f3) or null means every release retries forever because its own one-shot key never matches the authorize.
• Re-capture with a different amount. Capture succeeds once and only validates; calling it again tells you nothing. If the provider upsold, release the original hold and re-authorize at the new figure.
• Authorize without a guaranteed terminal call. placeHold followed by a flow that can abandon the branch without reaching release strands the funds until a human reconciles. Wrap the whole downstream body in try { } catch { releaseHold(...); throw; }.

​

5. When to use two-phase authorization

1. There is a genuinely long third-party leg (a carrier provision, a KYC review, an eSIM profile push) between commitment and confirmation.
2. The order is price-committed before the leg, so the wallet must be locked against concurrent purchases.
3. A failure must mechanically refund, not queue for manual reconciliation.

• The whole flow completes synchronously in one request — take the one-phase debit.
• The amount is computed only after the leg runs — you cannot authorize what you have not priced. Verify first, then authorize a known figure.