Transaction Change Control (TCC) for PayPal

What if you approved one product, but the warehouse shipped you something different — and the merchant had already captured your payment?

That's the problem we're trying to solve with TCC.

Inspiration

AI agents are making it easier to shop and pay online. But there's a part of the buying process that still gets very little attention: what happens after checkout.

Imagine ordering a pair of waterproof hiking shoes. You approve the purchase, PayPal authorizes the payment, and the order goes to the warehouse. But the warehouse runs out of stock and sends you a cheaper, non-waterproof version instead.

Under normal checkout flows, payment may already be captured before the buyer has a chance to inspect the delivered item. When the package arrives days later, your money has already cleared. You now have to contact the seller, explain what happened, and possibly start a weeks-long dispute.

We wanted to explore a different approach: what if the payment wasn't captured until the buyer had a chance to deal with a change to the original order?

That became Transaction Change Control (TCC).

What It Does

TCC connects the original purchase details to the fulfillment process.

It uses PayPal's two-step authorization and capture flow. Instead of capturing the payment immediately, the merchant first authorizes it. TCC then checks the warehouse's fulfillment information against what the buyer originally agreed to purchase.

There are two possible outcomes:

  • Everything matches: TCC can proceed with the normal capture process on PayPal rails.
  • Something important has changed: TCC pauses the settlement flow and asks the buyer what they want to do.

The buyer can reject the changed order and request that the authorization be voided on PayPal, or agree to accept the substitute at a lower discounted price.

When a merchant uses TCC in its fulfillment workflow, a detected material change pauses the settlement process until the buyer has a say.

How We Built It

We built TCC using PayPal's native Orders v2 and Payments v2 APIs.

The main workflow is:

  1. Create Mandate: Create a PayPal order using intent: AUTHORIZE. Funds remain unheld ($0.00) and the order is marked PENDING_APPROVAL.
  2. Authorize Hold: Obtain and verify the authorization hold directly through PayPal's server-side authorization API before proceeding with fulfillment.
  3. Receive Fulfillment Evidence: Ingest the warehouse packing slip or fulfillment webhook (signed with HMAC-SHA256).
  4. Audit Invariants: Use Google's Gemini model to extract and compare the physical specifications from the slip against the buyer's original purchase agreement.
  5. Freeze Settlement on Breach: If a material difference is found, pause the settlement process (HOLD_FROZEN) and wait for the buyer's decision.
  6. Execute Verified Settlement: Carry out the selected action through PayPal's authorization, capture, or void APIs. If the buyer rejects, the authorization is voided. If they accept a discount, a partial capture is performed and the uncaptured portion is released according to PayPal's authorization and capture process.

We also built an MCP (Model Context Protocol) server so AI tools such as Claude, Cursor, and other compatible agents can invoke TCC's purchase checks, fulfillment audits, and settlement actions.

The backend includes signed webhook verification, order-level isolation, and safeguards designed to prevent a failed PayPal API call from ever being reported as a successful transaction.

Challenges We Overcame

The hardest part wasn't getting an AI model to read a packing slip. It was making sure the payment state actually reflected what PayPal had done.

Early in development, we found that it was possible for an application to report a successful settlement even when the payment provider had not confirmed it. We tightened the state transitions so that a failed PayPal response would never be treated as a successful capture or void.

We also worked on matching fulfillment evidence strictly to the correct order and authorization, validating authorization details against the registered order, and making sure that missing or unclear evidence did not automatically count as a successful match.

These details matter because a payment-control system cannot simply assume that an operation succeeded.

What We're Proud Of

  • A working application built around PayPal's actual authorization, capture, and void APIs.
  • A real PayPal Sandbox authorization with a recorded VOIDED status and $0.00 captured (7VU467051N1536501).
  • 21 automated tests covering policy decisions, defensive fail-closed behavior, webhook signatures, order association, dynamic amounts, and settlement safeguards.
  • An MCP interface that allows compatible AI agents to interact with the system.
  • A live hosted application on Render, interactive API documentation, and a clean open-source repository.

What We Learned

We started by thinking about how AI agents could make purchases more safely. While building TCC, we realized that approving a purchase is only one part of the transaction.

The buyer also needs a say when the product they receive is materially different from the product they approved.

We believe that distinction will become increasingly important as AI agents take on more responsibility for online shopping.

Built With

Share this project:

Updates

Submission history