Integrate ProveCart

Two ways to integrate

Start with shadow mode to see your own numbers. Move to enforcement when you are ready for the verdict to gate the payment.

Quickstart

Base URL for every call: https://api.provecart.com. Interactive endpoint reference: api.provecart.com/docs.

1. Get an API key ProveCart issues a key for your store. The key is shown once; ProveCart stores only its hash. Send it as the X-API-Key header on every call.
2. Create a mandate Record the customer's instruction with POST /mandates (orders), POST /booking-mandates (travel), or POST /reservation-mandates (services). The server signs the mandate and returns its id and signature.
3. Verify what the agent built Send the mandate id and the agent's cart, booking, or reservation to POST /verify, POST /verify-booking, or POST /verify-reservation. Add an Idempotency-Key header, unique per attempt.
4. Read the verdict The answer carries the verdict, a result for each part of the comparison, any corrections, the signed verdict_token your payment step uses, and the record_id of the sealed evidence record.

Create a mandate:

Verify a cart against it:

What you send

Three mandate types, one shape: what the customer authorized, then what the agent built.

Orders: the cart mandate (POST /mandates)

Then verify the cart (POST /verify) with: mandate_id; merchant as {name, domain}; items, each with name, variant, quantity, and unit_price; total_price plus any tax, shipping, and fees; currency; and, for a corrected resubmission, previous_record_id.

Travel: the booking mandate (POST /booking-mandates)

Verify with POST /verify-booking: the booking as the agent built it (travelers, segments, cabin and fare terms, lodging if any, and the price). The verdict gates both payment capture and ticket issuance, and a re-priced, re-scheduled, or substituted booking must be re-verified before either happens.

Services: the reservation mandate (POST /reservation-mandates)

Verify with POST /verify-reservation: the reservation as the agent made it.

What you get back: the verdict contract

Every check compares the transaction part by part and answers one of three verdicts. A hard failure (over the price ceiling, a different traveler, an excluded merchant, an expired instruction) is a BLOCK. A soft failure (more units than the stated maximum, a different currency, anything genuinely in between) is a REVIEW. Everything passing is a MATCH. When the checker is uncertain, the answer is REVIEW, never a silent pass.

• Signed verdict token. Each answer carries a signed token that binds the check's record, the mandate, the verdict, the hash of the cart or booking, the amount, and the currency, with a 15-minute expiry. A verdict issued for one cart cannot capture a different cart or a different amount.
• Single-use and hold-bound. One check funds at most one payment capture and at most one ticket issuance. At capture time, the token's mandate and cart hash must equal the values stored on the payment hold itself. A corrected transaction is a new check with a new token.
• Idempotency. Send an Idempotency-Key with each verify call. Repeating the same call with the same body returns the original verdict, marked as a replay, with no duplicate record. Reusing the same key with a different body is refused with a 409.
• Your data stays yours. Every mandate is bound to the key that created it. Your key sees only your own mandates, records, and verdict feed; another key asking for your mandate gets a 404, and a verify against a mandate that is not yours is refused without revealing that it exists.
• Verdict feed, not webhooks. Poll GET /verdicts?since=<record_id> to receive the same signed verdict payloads in order.
• Sealed evidence. Every check appends a record to a hash-chained evidence store. Any record can be fetched and exported as a dispute-evidence bundle.
• A second look, inside strict limits. A REVIEW that turns on wording, such as the same item described in different words, may receive an automated second read. It can never overturn a BLOCK, and when it is not sure, the case stays in REVIEW.

Corrections: the agent fixes it and resubmits

A REVIEW or BLOCK answer carries a machine-readable corrections array: for each problem the agent can fix, the action to take and the expected versus actual values. Nothing about the checking internals is included.

• Orders: remove_item, replace_item, change_variant, reduce_quantity, reduce_total, change_currency.
• Bookings: correct_traveler_name, change_travel_date, change_airport, change_cabin, change_fare_terms, rebuild_itinerary, change_room, and more.
• Reservations: change_date, change_time, change_party_size, correct_reservation_name, reduce_deposit, change_cancellation_terms, change_provider, change_location.

Problems an agent cannot fix by editing the transaction (an expired or invalid instruction, an excluded merchant, an exhausted standing budget) are marked correctable: false on their result, so the agent does not loop retrying them.

The agent resubmits the corrected transaction as a new verify call against the same mandate, with previous_record_id set to the earlier check. Both rounds stay in the evidence chain, and the response suggests a guidance limit of max_attempts: 3.

Testing

• Sandbox key. Ask ProveCart for a separate test key. Calls made with it are sealed under that key and never mix with your live data, and verdicts, records, and the feed behave exactly as in production.
• Portal access. Pilot merchants receive an invite with a one-time link to set their own portal password; after that they sign in with their email and password and see only their own store's checks.
• Rehearse capture end to end. The mock payment endpoints apply the same token rules as a real capture: POST /mock-psp/authorize creates a hold, you verify the cart, and POST /mock-psp/capture accepts only a valid, unexpired token bound to the same cart and amount. A BLOCK always refuses; a REVIEW capture needs an explicit override: true, and the override is recorded. POST /mock-psp/void releases a hold. For bookings, POST /mock-ticketing/issue applies the same rules to ticket issuance.
• Watch a check walk through. The merchant portal has a sample demo (Ridge Trail Bikes, no sign-in needed) that shows exactly what a signed-in merchant sees, including order #1042: flagged, corrected by the agent, and passed on the recheck.
• Check the chain. GET /records/verify-chain recomputes the evidence chain and reports whether it is intact.

How much work is it?

Three ways in, in order of effort. Every pilot starts at the top of this ladder.

During pilots, ProveCart works white-glove alongside your developer: key setup, field mapping, and test cases are done with you, not handed over as homework.