How It Works

An agentic purchase runs in two phases. Setup happens once per card. The purchase flow then repeats for every order against that stored card.

​

Who does what

• The user is the cardholder who stores a card and approves each charge on a hosted page
• The client is you, and your agent chooses what to buy and drives the API calls
• Reap stores the card and prices the order with the merchant, then completes the checkout and reports the outcome
• The merchant is the seller that supplies the catalog and the current price, including the shipping options and the tax

​

The two phases

Setup runs once and the enrollment stays reusable. The purchase phase then repeats for every later order.

​

One purchase in detail

The search line and the quote line each stand for more than one call. One-Time Purchases shows every request and response in order.

​

Enrollment

An enrollment stores one card and returns an ID. Create one with POST /agentic/enrollments and pass that ID to checkout whenever you charge the card. You can charge only an enrollment with status ACTIVE. Three sources store a card, and every source takes an owner and a return URL. The user then finishes the enrollment on a page hosted by Reap.

• A Reap card uses source set to REAP_CARD with the card ID
• A BIN sponsor card uses source set to BIN_SPONSOR with the public token ID
• An external card uses source set to EXTERNAL, and the user enters the card on the hosted page

Every enrollment belongs to an owner. Use REAP_USER for a Reap cardholder and CLIENT_REFERENCE for a customer record in your own system. Every call to GET /agentic/enrollments covers a single owner, so keep the owner reference you sent. Setup walks through each source with a request and a response.

​

Mandate

A mandate records the terms the user approved for one enrollment. It holds the approved amount, the charge frequency, the maximum number of charges, and the merchant scope. Read it with GET /agentic/mandates/:id. The approved amount acts as a ceiling. The final quote total has to stay at or below that amount for the charge to run under the same approval. You can pause, resume, and cancel a mandate. Lifecycle and Statuses covers each operation.

​

Product search

Product search reads merchant catalogs and turns what the user chose into the variant a quote needs.

• POST /agentic/products/search returns matching products with a price range and one preview variant
• POST /agentic/products/details expands a product into its description, media, and option groups
• POST /agentic/products/variant turns the selected options into one purchasable variant

Search returns a price range rather than one price, because shipping and tax arrive with the quote. One-Time Purchases shows each call with a request and a response.

​

Quote

POST /agentic/quotes opens the merchant checkout for the selected items and returns pricing from the merchant. It gives you the available shipping options. It also returns an itemized total with subtotal, shipping, tax, discounts, and the final amount. A quote accepts a variant rather than a product, so resolve the chosen options to a variant first. Every quote carries an expiresAt value. Open the checkout before that time, and create a new quote once it passes.

​

Checkout

POST /agentic/checkouts charges an ACTIVE enrollment for an unexpired quote. The response tells you what to do next.

• When nextAction is present, send the user to nextAction.url to approve the charge
• When the user returns to your return URL, read the checkout with GET /agentic/checkouts/:id to get orderId and finalAmount

​

Idempotency

Send an Idempotency-Key header on every call that creates something. POST /agentic/enrollments, POST /agentic/quotes, and POST /agentic/checkouts all require it, and a call that omits the header is rejected. A retry with the same key replays the first response instead of storing a second card, creating a second quote, or running a second charge. Send Reap-Version on every request. See versioning for how versions change.

​

Next steps