Booking API course · updated 2026-10-05
Lesson 6: POST /intents, the server prices the order and opens the payment
This is the call that turns a filled form into a payment waiting for a card. You send the order and the customer; the server prices it again, runs every rule and the fraud screening, creates the Stripe PaymentIntent and gives you a client_secret. No price travels from your page to ours.
Before you start
- Lesson 5: you have a size_id, rental_days, a delivery date that passed /check and, if used, a valid promo code
- ## Request
```
POST /intents
{
"size_id": "<uuid>",
"rental_days": 7,
"delivery_date": "2026-11-10",
"pickup_date": "2026-11-17",
"delivery_address": "123 Main St",
"delivery_city": "Orlando",
"delivery_state": "FL",
"delivery_zip": "32801",
"placement_lat": 28.5383,
"placement_lng": -81.3792,
"debris_type": "household",
"notes": "Gate code 4471. Paver driveway, please bring plywood.",
"customer": { "name": "Jane Doe", "email": "jane@example.com", "phone": "4075550100", "type": "residential", "company_name": null },
"promo_code": "SAVE10",
"terms_accepted": true,
"session_id": "your-own-id-optional"
}
```
Required: size_id, rental_days (1 to 365), delivery_date (YYYY-MM-DD), delivery_address (street number and name), delivery_zip, customer.name, customer.email, customer.phone, terms_accepted = true. pickup_date defaults to delivery_date plus rental_days. customer.type is residential or contractor. notes is optional plain text up to 500 characters (where to place the dumpster, gate code, surface): it is saved on the order as the placement notes the driver sees; HTML and control characters are removed. session_id is 8 to 64 characters (letters, digits, _ or -); send your own to make retries idempotent. - ## Response
```
{ "data": {
"session_id": "...", "payment_intent_id": "pi_...", "client_secret": "pi_..._secret_...",
"stripe": { "publishable_key": "pk_live_...", "account": null },
"currency": "usd",
"amount": { "total": 350, "total_cents": 35000, "processing_fee": 14.46, "processing_fee_cents": 1446, "gross_total": 364.46, "gross_total_cents": 36446, "card_fee_handling": "customer_pays" },
"next": "Confirm the card with Stripe.js ..."
} }
```
Keep session_id, payment_intent_id and client_secret in memory for the next two lessons. For Canadian companies stripe.account is the connected account id: initialize Stripe.js with it (lesson 7). - ## What happens on the server
In order: the input is validated (400 invalid_body with field), the price is recomputed from the company's account, booking must be on and Stripe ready, the date must be open and the ZIP inside the service area, the promo must be valid, the email must not belong to a commercial account of the company (409 account_customer), the rate limits and the card-testing gate are checked, the card fee is computed under the company's handling, and the PaymentIntent is created on Stripe with the risk tier of the company (manual capture for review when the company holds suspicious orders). A record of the attempt is kept so the company can see abandoned checkouts. - ## Errors you should handle
400 invalid_body: show the message next to the field. 409 booking_offline, payments_not_ready: show the company's phone. 409 date_past, date_closed, out_of_service_area: send the customer back to that step with the message. 409 account_customer: the message tells the customer to order through their account or call. 409 already_authorized: this session already has an authorized payment; go straight to POST /confirm with its payment_intent_id. 429 rate_limited: wait Retry-After seconds. 502 upstream: try again in a few seconds. - ## Idempotency
Send the same session_id on a retry and the server reuses the open PaymentIntent instead of creating a new one. If the payment was already authorized you get 409 already_authorized with the hint to confirm. Generate a new session_id only for a genuinely new attempt (a different size, date or customer). - ## material and material_acknowledged
Send material (a slug from GET /materials) when the company prices by material; the server prices the order by it and the order carries the material. When that material has requires_ack, send material_acknowledged: true after showing the explanation; otherwise 400 invalid_body with field material_acknowledged and the explanation in the message. A debris_type equal to an active material slug is treated as the material; sending both with different values is 400. 409 material_not_allowed works as in POST /quote. The price is resolved once here and frozen with the payment: editing prices in the account afterwards does not change this order.
What happens next
- Nothing has been charged yet. The customer still has to confirm the card (lesson 7) and your page still has to call POST /confirm (lesson 8).
Troubleshooting
The amount in /intents differs from my last /quote.
The company changed a price or a promo between the two calls, or the promo became invalid. Always show the amount from /intents on the payment step; it is what the card will be charged.
Related guides
- Lesson 7: take the card with Stripe.js on your page
- Lesson 8: POST /confirm and GET /sessions, create the order and never lose one
© 2026 Dumpster Controls. All rights reserved. Made in the USA.