Build a Jovvie Checkout integration with an AI coding assistant
This page is for you if an AI coding assistant or an AI app builder writes the code for your Jovvie Checkout integration. It shows you what to prepare, how to point the assistant at these docs, and a set of rules to paste into your project, so the code it writes works with the Jovvie SDKs and is safe to use with real payments.
It covers both Jovvie SDKs for Stripe: the TypeScript SDK (@bizswoop/jovvie-payments on npm) and the PHP SDK. For how a payment works, see Build your own Jovvie Checkout integration.
Before you start
Section titled “Before you start”Have these ready before you ask the assistant to write any code:
- A platform provider ID from Jovvie support. Your code must pass it every time it creates the SDK client. See Get started.
- A server application and its keys. You need the Public Key, Secret Key, and Webhook Key from the merchant’s Payments Dashboard. See Get started.
- A place for server code. The SDK must run on a server, never in the browser. If your app builder only makes front-end apps, add a server function, such as a Supabase Edge Function, a Vercel function, or a Cloudflare Worker. The TypeScript SDK runs on all of them, and on Node.js 20.19 or later, Deno, and Bun.
Point the assistant at these docs
Section titled “Point the assistant at these docs”AI assistants write better code when they read the current docs instead of guessing from memory. Give your assistant one of these:
https://docs.jovvie.com/llms.txt: a short guide to Jovvie for AI assistants, with links to the full text of each section. The developer pages are in the Developers section file it lists.- The Markdown copy of a single page: add
index.mdto the end of the page’s address. For example,https://docs.jovvie.com/developers/webhooks/index.md.
The code examples on the developer pages show PHP and TypeScript side by side. In the Markdown copies and the full-text files, each example starts with “If you use PHP:” or “If you use TypeScript:”, so tell the assistant which one you use.
Rules to give your assistant
Section titled “Rules to give your assistant”Copy the rules for your SDK into your assistant’s project instructions, or paste them at the start of your conversation.
You are helping me build a Jovvie Checkout integration with the Jovvie PHP SDK forStripe (Composer package bizswoop/jovvie-payments). Follow the Jovvie docs athttps://docs.jovvie.com/llms.txt and these rules. If something is not in the docs, say so and ask me. Do not guess.
Keys and setup1. Use the SDK only in server-side PHP code. Never put the keys in browser, front-end, or mobile app code.2. Read every value from environment variables: JOVVIE_PUBLIC_KEY, JOVVIE_SECRET_KEY, JOVVIE_PLATFORM_PROVIDER, JOVVIE_WEBHOOK_KEY, JOVVIE_MODE. Never hard-code them, and never log them. I will set the values myself. Never ask me to paste keys into the chat.3. Always pass the platform provider ID from JOVVIE_PLATFORM_PROVIDER as the third argument of JovviePaymentsClient, in test mode too. Stop with an error if it is missing. Never make up, shorten, or replace this value.4. Take the mode from JOVVIE_MODE ('live' or 'test'). Use 'test' while we build.
Payments5. Save the Jovvie payment ID with the order when you create the payment. Never read the payment ID from a URL or a form the browser sends.6. Never mark an order paid because the browser reached the return URL. Fetch the payment on the server and check it: a one-time payment is paid when its status is 'completed', a recurring payment has started when its status is 'active'.7. Never retry creating a payment automatically, and never in a loop. If the result is unclear, stop and show staff a message to check the card reader and the Stripe Dashboard. Only create a replacement payment, or take payment another way, after fetching every payment saved for the order and confirming that no payment went through and none is still processing.8. Only create authorization links for the merchant's signed-in staff. Always set redirectUrl and a short expiresAt. Never show checkout links or authorization links to customers, or put them in emails or logs.9. Do not build a refund button. Refunds are made in the Stripe Dashboard.
Webhooks10. Verify every webhook with WebhookEvent::constructEvent(), using the raw body from file_get_contents('php://input') and the X-Jovvie-Signature header. Never decode the body first, and never use constructFrom() for incoming requests.11. Answer 200 when a WebhookError message starts with "Unsupported event type", and 400 to any other WebhookError.12. Ignore events whose getPaymentMode() does not match JOVVIE_MODE, and answer 200.13. Save the event ID and your changes in one database transaction, with a unique constraint on the event ID, so each event is handled only once. Answer quickly.
Never use SDK options or API endpoints that the Jovvie docs do not describe.You are helping me build a Jovvie Checkout integration with the Jovvie TypeScript SDK(@bizswoop/jovvie-payments). Follow the Jovvie docs at https://docs.jovvie.com/llms.txtand these rules. If something is not in the docs, say so and ask me. Do not guess.
Keys and setup1. Run the SDK only in server code (an API route, server function, or edge function). Never import it in browser, front-end, or mobile app code.2. Read every value from environment variables: JOVVIE_PUBLIC_KEY, JOVVIE_SECRET_KEY, JOVVIE_PLATFORM_PROVIDER, JOVVIE_WEBHOOK_KEY, JOVVIE_MODE. Never hard-code them, never log them, and never use a variable name the build exposes to the browser (such as NEXT_PUBLIC_, VITE_, PUBLIC_, or EXPO_PUBLIC_). I will set the values myself. Never ask me to paste keys into the chat.3. Always pass platformProvider from JOVVIE_PLATFORM_PROVIDER, in test mode too. Stop with an error if it is missing. Never make up, shorten, or replace this value. Treat a "No platform provider given" warning as an error.4. Take the mode from JOVVIE_MODE ('live' or 'test'). Use 'test' while we build.
Payments5. Save the Jovvie payment ID with the order when you create the payment. Never read the payment ID from a URL or a form the browser sends.6. Never mark an order paid because the browser reached the return URL. Fetch the payment on the server and check it: a one-time payment is paid when its status is 'completed', a recurring payment has started when its status is 'active'.7. Never retry creating a payment automatically, and never in a loop. If the result is unclear, stop and show staff a message to check the card reader and the Stripe Dashboard. Only create a replacement payment, or take payment another way, after fetching every payment saved for the order and confirming that no payment went through and none is still processing.8. Only create authorization links for the merchant's signed-in staff. Always set redirectUrl and a short expiresAt. Never show checkout links or authorization links to customers, or put them in emails or logs.9. Do not build a refund button. Refunds are made in the Stripe Dashboard.
Webhooks10. Verify every webhook with WebhookEvent.constructEvent(), using the raw request body exactly as received and the X-Jovvie-Signature header. Never parse the body as JSON first, and never use constructFrom() for incoming requests.11. Answer 200 to UnknownEventError and 400 to any other WebhookError.12. Ignore events whose payment.mode does not match JOVVIE_MODE, and answer 200.13. Save the event ID and your changes in one database transaction, with a unique constraint on the event ID, so each event is handled only once. Answer quickly.
Never use SDK options or API endpoints that the Jovvie docs do not describe.Where to put your keys
Section titled “Where to put your keys”Set the values in your hosting platform’s environment variables or secrets settings, for example the project settings of your app builder or the secrets of your server functions. Use these names, so they match the rules and the examples on the developer pages:
| Variable | Value |
|---|---|
JOVVIE_PUBLIC_KEY |
The application’s Public Key |
JOVVIE_SECRET_KEY |
The application’s Secret Key |
JOVVIE_WEBHOOK_KEY |
The application’s Webhook Key |
JOVVIE_PLATFORM_PROVIDER |
The platform provider ID from Jovvie support |
JOVVIE_MODE |
test while you build, live for real payments |
If you keep them in a local .env file while you build, make sure that file is listed in .gitignore, so it never goes into version control.
If a key ends up somewhere it should not be, such as the chat, a commit, or browser code, regenerate the keys. See If a key is exposed.
Check the code before you go live
Section titled “Check the code before you go live”AI assistants can write code that works in a quick test but is not safe with real payments. Before the merchant takes a live payment, look for these problems, or ask your assistant to check for them:
- The SDK is imported in a page, component, or other code that runs in the browser.
- A key, the webhook key, or the platform provider ID is written into the code, or uses a browser-exposed variable name.
platformProvideris missing, or set to anything other than your environment variable.- The webhook route parses the body as JSON before it calls
constructEvent(). - The return page marks the order paid without fetching the payment first.
- Creating a payment is wrapped in a retry or a loop.
Then work through Before you go live with the merchant.
Related pages
Section titled “Related pages”Need help?
Section titled “Need help?”To get a platform provider ID or ask about your integration, contact Jovvie support.