Authorization & Capture

Reserve funds before work#

Use Authorization when the final service cost is known later. The buyer signs a ceiling for a hold. reserve registers it onchain, and the fixed merchant operator can then capture a cumulative amount or void the hold.

Wait for reserve to confirm before using the hold as payment capacity. A signature by itself has not locked any funds.

Use the right request ID#

Authorization uses nonzero bytes32 request IDs. Session uses nonempty strings. Keep each rail's serialization and EIP-712 domain separate.

The authorization identifies the payment ID, merchant and operator, signing authority, refund receiver and maximum budget. Use unsigned integers and set a validity deadline for every hold.

Create and capture a hold#

The example starts with a funded authorization payment and its deployment manifest. Final capture settles the cumulative target and releases the unused part of the reservation.

const { ethers } = require("ethers");
const {
  createAuthorizationBackend, createAuthorizationClient,
} = require("./sdk/payment-sessions/index.cjs");
const backend = createAuthorizationBackend({
  ...authorizationDeployment, provider, signer: merchantOperatorSigner,
});
const client = createAuthorizationClient({
  backend, signer: authorizationSigner,
  store: authorizationStore, terms: authorizationTerms,
});
const requestId = ethers.utils.id("inference-42");
const approval = await client.authorize({
  requestId, ceiling: "20", validUntil: String(now + 120), nonce: "0",
});
await backend.reserve(approval);
await backend.capture(authorizationTerms.paymentId, requestId, "15", true);

Release the remaining reservation#

Repeating the same capture target adds no payout. Final capture, void or expiry ends the hold. Payment cancellation returns unreserved value to its fixed refund receiver, while existing holds retain capture rights until they reach a terminal state.

Use resume for a registered request and nonce. Do not sign a replacement just because the first submission was interrupted. The contract records the captured payment; your application must separately record service delivery.