@rubytech/taskmaster 1.13.4 → 1.14.2

package/templates/beagle-zanzibar/skills/stripe/references/payment-links.md

@@ -0,0 +1,71 @@
+# Stripe Payment Links — Checkout Session Creation
+
+## Booking Fee Calculation
+
+The tourist pays a booking fee to confirm their ride:
+
+```
+fee = max($2, min($5, fare × 0.05))
+```
+
+In cents (Stripe uses the smallest currency unit):
+
+```
+fee_cents = max(200, min(500, round(fare_usd × 5)))
+```
+
+Examples: $20 fare → $2.00 fee | $50 fare → $2.50 fee | $100 fare → $5.00 fee
+
+## Creating a Checkout Session
+
+Call the Stripe Checkout Sessions API:
+
+```
+POST https://api.stripe.com/v1/checkout/sessions
+Authorization: Bearer {stripe_secret_key}
+Content-Type: application/x-www-form-urlencoded
+
+mode=payment
+payment_method_types[]=card
+line_items[0][price_data][currency]=usd
+line_items[0][price_data][unit_amount]={fee_cents}
+line_items[0][price_data][product_data][name]=Beagle booking fee — {job_id}
+line_items[0][price_data][product_data][description]={route} on {date}
+line_items[0][quantity]=1
+metadata[booking_id]={job_id}
+metadata[tourist_phone]={tourist_phone}
+metadata[negotiated_fare]={fare_usd}
+```
+
+The Stripe secret key is the `stripe` key stored in your API key config (`sk_test_...` for test mode, `sk_live_...` for production).
+
+The response includes a `url` field — this is the hosted checkout page to send the tourist.
+
+## Sending the Link
+
+Send the tourist the checkout URL with context:
+
+> "To confirm your booking, pay the $[fee] booking fee here: [url]
+> This locks in your ride. You pay $[fare] directly to your driver at the end of the journey."
+
+## Verifying Payment
+
+Before releasing driver details (Phase 5), verify the session is paid:
+
+```
+GET https://api.stripe.com/v1/checkout/sessions/{session_id}
+Authorization: Bearer {stripe_secret_key}
+```
+
+Check `payment_status == "paid"`. If not yet paid, wait for the tourist to say they've paid — then verify. Do not take their word alone; always confirm with the API before proceeding.
+
+## What to Store in the Booking Record
+
+Add these fields to `bookings/{job-id}.md` when the session is created and confirmed:
+
+```
+stripe_session_id: cs_...
+booking_fee_usd: 2.50
+payment_status: pending   → paid (update when confirmed)
+paid_at: [timestamp from session]
+```