Capture an Authorization

Capture an authorization when the order is ready to settle. The operator transfers all or part of the escrowed amount to the receiver and fee receiver without collecting from the payer again. Capture the full amount at once, capture less when the final total changes after checkout, or capture multiple increments as an order ships.

This guide’s payment flow is based on the Commerce Payments Protocol.

Demo

The demo above is mock only. If you want to see onchain demos on Vibenet, head to Base chain demos.

Check and Capture

Read paymentState(paymentInfoHash) before capture. The amount must be nonzero, no greater than capturableAmount, and submitted strictly before authorizationExpiry. The operator supplies an absolute feeAmount in raw token units. The protocol validates it against the per-capture minFeeBps and maxFeeBps stored in PaymentInfo.

TypeScript

export async function captureAuthorization(
  payment: StoredProtocolPayment,
  amount = payment.paymentInfo.maxAmount,
) {
  const [, capturableAmount] = await publicClient.readContract({
    address: AUTH_CAPTURE_ESCROW,
    abi: authCaptureEscrowAbi,
    functionName: "paymentState",
    args: [payment.paymentInfoHash],
  });
  if (amount > capturableAmount) throw new Error("Capture exceeds authorized amount");
  const simulation = await publicClient.simulateContract({
    account,
    address: AUTH_CAPTURE_ESCROW,
    abi: authCaptureEscrowAbi,
    functionName: "capture",
    args: [payment.paymentInfo, amount, 0n, zeroAddress],
  });
  const hash = await walletClient.writeContract(simulation.request);
  const receipt = await publicClient.waitForTransactionReceipt({ hash, confirmations: 2 });
  if (receipt.status !== "success") throw new Error("Payment capture reverted");
  return receipt;
}

Capture decreases capturableAmount and increases refundableAmount by the same gross amount. The receiver gets the gross amount minus fees.

Verify PaymentCaptured(paymentInfoHash, amount, feeAmount, feeReceiver) and the expected receiver transfers before marking the fulfillment increment settled.

Capture a Partial Amount

Pass a smaller amount to the same capture call for every increment. The sum of successful captures cannot exceed PaymentAuthorized.amount, and each capture independently validates its fee bounds. The remaining reservation is tracked onchain without a custom checkout contract. For a 100 USDC authorization, a 64 USDC capture leaves 36 USDC capturable and makes 64 USDC refundable. You can capture another increment or void the remainder.

After every capture, reconcile PaymentCaptured.amount with the new capturableAmount and refundableAmount before another worker advances the order.

Fee bounds are evaluated per capture and use integer division. With low-decimal tokens, fragmenting one settlement into many small captures can reduce the aggregate minimum fee. Enforce a minimum capture size offchain when that matters.

Capture Deadline

At authorizationExpiry, capture is no longer available and the payer can reclaim the remaining balance. Use chain time rather than an application server clock when enforcing the deadline.

Void an Authorization

Return the unneeded remainder to the payer.

Refund a Payment

Return previously captured value to the payer.

Overview

Integrate DeFi

Tokenize Assets

Issue Stablecoins

Accept Payments

Private Transactions

Demo

Check and Capture

Capture a Partial Amount

Capture Deadline

See Also

Void an Authorization

Refund a Payment

​Demo

​Check and Capture

​Capture a Partial Amount

​Capture Deadline

​See Also

Void an Authorization

Refund a Payment

Demo

Check and Capture

Capture a Partial Amount

Capture Deadline

See Also