# Follow-up questions for Synchron — route payments and card on file

Reply to "Synchron × HeavyHaul Agent: route payments and card on file" (October 6, 2026). Their design fits what HHA already built: the same prices ($1.99 Express, $10.00 Extended), a pending purchase per cart, one Stripe Checkout, a signed callback and a status pull. The questions below are the gaps.

## Must be answered before either side builds

1. **Routes on trips created in HHA have no Synchron order.** Your purchase endpoint requires an existing `order_token` and never creates an order. Routes are only sold on trips created in HHA (Synchron-pushed permits already include their route), and none of those trips has a Synchron order or permit token. How should HHA buy a route there? Options: Synchron creates an order for the HHA trip through a new endpoint, or the purchase is keyed by HHA trip id, HHA permit id and route token instead of `order_token` and `permit_token`.
2. **New HHA users have no Synchron user token or Stripe customer.** Only people imported from Synchron have one. Will the API create or link a Synchron customer from an HHA user (name, email, company)? For a carrier with several dispatchers, is the card held per person or per carrier (you store Stripe customer ids on both users and carriers)?
3. **How does the finished route come back to HHA?** After payment you create the routing work. Do the deliverables (Google Maps links, GPX file, Hummer link) arrive in a signed callback such as `route.completed`, through the agent backend, or only through the status pull? How long does an Extended Route take to prepare?
4. **Who decides Express versus Extended?** HHA decides it from how many times the permit's route token has been used: 3 or more uses is Express. Should Synchron check that against its own data (the route token `Frequency`) or accept HHA's product code? Can your API return the use count per token, since our agent backend does not send it yet?

## Contract details to agree

5. **Product codes.** HHA uses `express_route` and `extended_route`; you proposed `HHA_EXPRESS` and `HHA_EXTENDED`. Which do we use? Does HHA Express correspond to your "Routing" product and Extended to "Route Discovery", or are they separate?
6. **Who loads a price change?** You offered two ways: Synchron loads the agreed version, or HHA pushes it through an admin endpoint. We prefer HHA pushes it.
7. **Callback signature.** HHA already verifies `X-Synchron-Timestamp` (Unix seconds, 10 digits) and `X-Synchron-Signature` = hex HMAC-SHA256 of `timestamp + "." + body`, rejects anything older than 5 minutes, and needs a secret of at least 32 characters. Will you sign exactly that way? Should HHA's requests to you (`X-HHA-Signature`) use the same scheme?
8. **Callback events.** You named `purchase.paid` and `payment_profile.ready`. We also need `purchase.payment_failed`, `purchase.expired`, `purchase.refunded` and `purchase.partially_refunded` (with the affected items), and item status changes (in progress, completed, fulfillment failed). Please confirm the list and payload of each.
9. **Card confirmation per permit order.** We had agreed a Synchron-hosted page where the customer picks a saved card and re-enters the CVV for each permit order, because HHA may never show a card field. Your answer covers card setup but not this page. Will you build it, or do we rely on the saved card plus 3-D Secure?
10. **Documents for "Buy More Permits".** The endpoint takes document URLs. HHA files sit in private storage behind links that expire. Will you download the files when the request arrives (how long must a link stay valid), or offer an upload endpoint?
11. **Consent wording for later charges.** You found no authorization wording for variable permit charges. Who writes it, and does it appear on your card-setup page, on HHA before the redirect, or both?

## Security changes that touch HHA

12. **The HHA bearer token found in your code.** Is it the token HHA uses to call you, or the one you use to call HHA's agent backend? When you rotate it, tell us which of our settings changes and when.
13. **API key scopes.** Our Synchron import reads `/api/v1/carriers/{id}/full-records` with our API key. When keys get hashing and scopes, which scope keeps the import working? Is anything of ours calling the unauthenticated `/api/v1/orders` endpoints you plan to close?

## Test environment and timing

14. When will a test environment be ready: a staging URL, test-mode Stripe keys, and a test webhook that can call HHA's staging site?
15. Your estimate is 4 to 5.5 weeks. Can route purchase and its callback ship first, before card on file and permit ordering, and when would you start?

## Not covered by your answers

These came from the January–March import and this week's trips. They may belong to the agent backend developer rather than you.

16. Permit weights of 1,111 lbs appear on many permits and look like a placeholder. Does that value mean "unknown"?
17. 21 imported orders have no permits (for example HH-93939530 and HH-21810243). Do they really have none?
18. 20 imported permits have no map and are marked "needs preparation" (for example IL on HH-38762483). Will they get maps, and how is HHA told?
