Purchase Tools
List payment methods, prepare a purchase with a saved card, or generate Stripe Checkout.
AI apps connected by signing in (Claude, ChatGPT) get only purchaseLabTestWithCheckout: the member pays on the Stripe page themselves. listSavedPaymentMethods and purchaseLabTest work with a key (bk_) and in the Betterness app.
listSavedPaymentMethods
Returns saved cards: externalId, brand, last4, expiresAt, isDefault. If the user has no Stripe customer or no saved cards, returns an empty list with a message.
Parameters: none
purchaseLabTest
Prepares buying a lab test with a saved card. Use when listSavedPaymentMethods returned at least one card. Nothing is charged: it returns a preview (test, price, discount, card) and a pendingId. After the user approves the preview, confirm_action(pendingId) charges the card and creates the order.
| Parameter | Required |
|---|---|
labTestObjectKey | yes (from listAvailableLabTests) |
paymentMethodExternalId | yes (from listSavedPaymentMethods) |
promotionCode | no |
Before calling:
getProfile()— verify gender, phone (with dial code), birth date, complete home address.updateProfileif needed.
The card is never charged more than the previewed price. If the price changed after the preview, confirm_action answers stale: prepare it again and show the new preview.
Permission: purchases
purchaseLabTestWithCheckout
Generates a Stripe Checkout payment link when the user has no saved cards.
| Parameter | Required |
|---|---|
labTestObjectKey | yes |
successUrl | yes — where to redirect after payment |
cancelUrl | yes — where to redirect on cancel |
promotionCode | no |
Share the complete checkoutUrl with the user. Never truncate. The order is created via webhook after payment completes.
Common errors
| Error | Cause |
|---|---|
| Profile incomplete | Missing required fields — fix with updateProfile |
Invalid labTestObjectKey | Use the exact value from listAvailableLabTests |
| Promo code invalid / expired | Try without the promo or get an updated code |

