> ## 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.

# Nova.Pay Checkout Flow: Pages, Carts, and Charge Links

> Nova.Pay supports three checkout paths: hosted checkout pages, programmatic carts, and charge links. Learn which to use and how they work.

Nova.Pay gives you three distinct paths to collect payment from a customer. Whether you need a fully hosted experience, a custom storefront you control programmatically, or a one-off payment link sent directly to a buyer, there is a checkout path designed for that use case. Each path produces an order and accepts the same core payment methods — the difference is in how the session is initiated and where you submit the final payment request.

## Checkout Pages

A checkout page is a merchant-configured, hosted page that lists one or more products. The customer browses the available offerings, selects what they want, and pays — all within the Nova.Pay-hosted environment.

**How it works:**

<Steps>
  <Step title="List available checkout pages">
    Call `GET /checkout_pages` to retrieve the checkout pages you have configured. Each page has a unique `id`.
  </Step>

  <Step title="Fetch page details">
    Call `GET /checkout_pages/{id}` to get the full product and configuration details for a specific page.
  </Step>

  <Step title="Fetch payment plans">
    Call `GET /payment_plans?checkout_page_id={id}` to retrieve the installment and payment method options available for that page. Each plan returns an `id` (e.g. `"42-3"`) that you pass as `payment_plan_id` in the payment request.
  </Step>

  <Step title="Submit payment">
    Call `POST /payments` with `checkout_page_id` and the chosen `payment_plan_id` to complete the purchase.
  </Step>
</Steps>

<Tip>
  Checkout pages are the fastest way to go live. No custom frontend is required — Nova.Pay handles the UI.
</Tip>

## Carts

A cart lets you build a fully custom storefront while still leveraging Nova.Pay for payment processing. You construct the cart server-side using your API key, attach the products and pricing you want, and then direct your customer to pay against that cart.

**How it works:**

<Steps>
  <Step title="Create or update a cart">
    Call `POST /carts/{id}` with your API key to create or update a cart. You control the line items, amounts, and customer details.
  </Step>

  <Step title="Customer pays">
    Call `POST /carts/{id}/pay` with the customer's chosen payment method to finalize the transaction.
  </Step>
</Steps>

<Note>
  Cart creation requires a valid API key. This path is intended for server-to-server flows where your backend assembles the order before the customer checks out.
</Note>

## Charges

A charge is a payment link or invoice that you generate and send to a specific customer. The customer receives a link, opens it, reviews the charge details, and pays. Charges support due dates and retention values, making them well-suited for invoicing and collections workflows.

**How it works:**

<Steps>
  <Step title="Customer opens the charge link">
    The charge link you sent resolves to `GET /charges/{id}`, which returns the charge details — amount due, due date, and any retention value.
  </Step>

  <Step title="Customer pays">
    Call `POST /charges/{id}/pay` with the customer's chosen payment method.
  </Step>
</Steps>

<Tip>
  Use charges when you need to bill a specific customer for a known amount — for example, an invoice with a due date or a payment plan with a retention fee.
</Tip>

## Choosing a Path

The table below summarizes the key differences between the three checkout paths:

| Path              | Auth Required                  | Best For                                          | Payment Endpoint         |
| ----------------- | ------------------------------ | ------------------------------------------------- | ------------------------ |
| **Checkout Page** | Not required for customers     | Hosted storefronts, no custom frontend needed     | `POST /payments`         |
| **Cart**          | API key required (server-side) | Custom storefronts with full UI control           | `POST /carts/{id}/pay`   |
| **Charge**        | Not required for customers     | Invoicing and payment links to specific customers | `POST /charges/{id}/pay` |

## Payment Plans

Before submitting a payment on any path, you should fetch the available payment plans so the customer can choose how they want to pay — for example, a single payment via Pix or three credit card installments.

Call `GET /payment_plans` with the relevant context parameter:

```http theme={null}
GET https://pay.nova.money/api/v1/payment_plans?checkout_page_id=42
```

The response is an array of plan objects. The `id` field uses a compound format (e.g. `"42-3"` meaning plan 42, 3 installments). Pass this value as `payment_plan_id` in your payment request:

```json theme={null}
{
  "payment_plan_id": "42-3",
  "payment_method": "credit_card",
  "checkout_page_id": 42
}
```

Each plan object also includes a `payment_method` field indicating whether the plan applies to `credit_card`, `pix`, or `bank_slip`. Filter by this field to show only the options relevant to the customer's chosen method.

## Upsell Flow

After a successful `POST /payments`, the response may include an `offer` field containing a Signed Global ID (SGID). This signals that a one-click upsell offer is available. To accept it on behalf of the customer — without requiring them to re-enter payment details — pass the SGID to `POST /upsell`:

```http theme={null}
POST https://pay.nova.money/api/v1/upsell
```

```json theme={null}
{
  "offer": "<sgid_value_from_payment_response>"
}
```

<Note>
  The upsell endpoint reuses the payment method from the original transaction, so no additional card or Pix data is needed.
</Note>


## Related topics

- [Nova.Pay API: Payments, Checkout & Order Management](/introduction.md)
- [Charges API — Pay Invoice and Charge Link Endpoints](/api-reference/charges.md)
- [Carts API — Create, Retrieve, and Pay Nova.Pay Carts](/api-reference/carts.md)
- [Order Lifecycle and Status Transitions in Nova.Pay](/concepts/orders-lifecycle.md)
- [Create and Process Your First Payment with Nova.Pay](/guides/create-payment.md)