> ## Documentation Index
> Fetch the complete documentation index at: https://developers.nova.money/llms.txt
> Use this file to discover all available pages before exploring further.

# Build a Custom Nova.Pay Checkout with AI

> Install the Nova.Pay Checkout Skill and use an AI coding agent to generate a branded, self-hosted checkout connected to the Nova.Pay API.

Use the **Nova.Pay Checkout Skill** with an AI coding agent to generate a branded payment page from a prompt. The generated checkout runs on your own server, follows your website's design, and connects directly to Nova.Pay for products, payment plans, customers, coupons, payments, Pix, boleto, and card processing.

<CardGroup cols={2}>
  <Card title="Download the Checkout Skill" icon="download" href="https://www.nova.money/nova-transparent-checkout-skill.zip">
    Get the skill package, including its complete Nova.Pay API reference.
  </Card>

  <Card title="Explore the Checkout API" icon="code" href="/concepts/checkout-flow">
    Understand the pages, payment plans, customer, and payment resources used by the generated checkout.
  </Card>
</CardGroup>

## Before You Start

Have these details ready before asking the AI agent to build the checkout:

| Requirement            | Where to find it                                           | Why it is needed                                                                    |
| ---------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| **Tenant**             | The first subdomain in your Nova Money URL, such as `acme` | Builds the API base URL: `https://acme.pay.nova.money/api/v1`                       |
| **Checkout page UUID** | Your Nova.Pay dashboard                                    | Identifies the products, branding, gateway, and checkout configuration              |
| **Allowed host**       | The domain where you will host the generated page          | Nova.Pay validates the browser `Origin`; unregistered hosts receive `403 Forbidden` |

<Warning>
  Never place a private API key or raw card data in browser code. The public checkout endpoints are protected by the allowed-host configuration, and card data must be tokenized client-side with the payment gateway SDK.
</Warning>

## Create the Checkout

<Steps>
  <Step title="Download and install the skill">
    Download the [Nova.Pay Checkout Skill](https://www.nova.money/nova-transparent-checkout-skill.zip), extract it, and add the folder to the skills directory used by your AI coding agent. The package contains:

    * `SKILL.md` — the checkout-building workflow and safety requirements
    * `references/api-reference.md` — the request and response schemas used during implementation

    Restart or reload your agent if it does not discover newly installed skills automatically.
  </Step>

  <Step title="Authorize your checkout domain">
    Open your tenant's integrations page and add the domain that will serve the checkout:

    ```text theme={null}
    https://{tenant}.pay.nova.money/integrations
    ```

    For local development, use `checkout.lvh.me` and run the site at:

    ```text theme={null}
    http://checkout.lvh.me:5173
    ```

    `lvh.me` resolves to `127.0.0.1`, while preserving a hostname that can be registered as an allowed host. If the form expects a complete origin, add `http://checkout.lvh.me:5173`.
  </Step>

  <Step title="Prompt the AI agent">
    Open the project where the checkout should be created and give the agent your tenant and checkout page UUID. Start with a simple prompt:

    ```text theme={null}
    Create a Nova.Pay checkout that matches the design of my website.
    Use tenant "acme" and checkout page UUID "YOUR-CHECKOUT-PAGE-UUID".
    Ask me for any missing information before you begin.
    ```

    The agent should inspect the existing design system, ask for missing information, and use the installed skill to implement the complete purchase flow.
  </Step>

  <Step title="Review the generated experience">
    Confirm that the page loads products and payment methods from Nova.Pay rather than hardcoding them. Depending on the checkout configuration, the generated UI can include:

    * product quantities and order bumps
    * coupons and recalculated payment plans
    * customer and billing-address fields
    * credit-card installments and two-card payments
    * Pix QR code, copy-and-paste code, expiry, and status polling
    * boleto download and payment-status polling
    * scheduling, subscriptions, upsells, and tracking parameters
    * branding from the checkout page's logo, colors, title, and custom code
  </Step>

  <Step title="Test before publishing">
    Run the local server on port `5173`, open `http://checkout.lvh.me:5173`, and verify the checkout with your Nova.Pay test configuration.

    Check the browser console for actionable API diagnostics. A `403` response normally means the current hostname is not registered as an allowed host. A `422` response contains validation messages that the checkout should show without clearing the customer's form.
  </Step>

  <Step title="Deploy on your own server">
    Deploy the generated site to the authorized production domain. Add the exact production hostname or origin to the tenant's allowed hosts, then run an end-to-end payment test before sending traffic to the page.
  </Step>
</Steps>

## What the Skill Implements

The skill instructs the agent to build this flow in order:

```text theme={null}
1. GET  /checkout_pages/:uuid            Load products, branding, gateway, and public key
2. GET  /payment_plans?...               Load methods and installment options
3. GET  /coupons/:code/validate?...      Validate an optional coupon
4. POST /customers                       Create or update the customer
5. Client-side gateway SDK               Tokenize card data in the browser
6. POST /payments                        Process the checkout
7. GET  /checkout_pages/:uuid/payments   Poll Pix or boleto payment status
8. POST /upsell                          Accept an optional one-click upsell
```

<Note>
  The AI agent generates the interface and integration code; Nova.Pay remains the source of truth for products, prices, payment plans, checkout settings, and payment results.
</Note>

## Launch Checklist

* The API base URL is derived from the tenant: `https://{tenant}.pay.nova.money/api/v1`
* The production origin is registered in the tenant's allowed hosts
* Products, order bumps, payment methods, and installments come from Nova.Pay responses
* Card data is tokenized with Pagar.me or Stripe and never sent raw to Nova.Pay
* Pix and boleto screens poll until the payment reaches a final status
* Coupon, UTM, scheduling, subscription, and upsell behavior match the checkout configuration
* Customer-facing errors are concise and the browser console contains safe diagnostics
* Logs exclude card data, tokens, CPF/CNPJ, customer details, and full payment request bodies

<Tip>
  Keep the installed skill in the project while iterating. You can ask the agent to restyle the page, add fields, or troubleshoot the integration without losing the Nova.Pay-specific implementation rules.
</Tip>


## Related topics

- [Nova.Pay API: Payments, Checkout & Order Management](/introduction.md)
- [Nova.Pay Checkout Flow: Pages, Carts, and Charge Links](/concepts/checkout-flow.md)
- [Order Lifecycle and Status Transitions in Nova.Pay](/concepts/orders-lifecycle.md)
- [Customers API — Create and Update Customer Records](/api-reference/customers.md)
- [Payment Plans API — List and Retrieve Installment Options](/api-reference/payment-plans.md)