Skip to main content
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:
1

List available checkout pages

Call GET /checkout_pages to retrieve the checkout pages you have configured. Each page has a unique id.
2

Fetch page details

Call GET /checkout_pages/{id} to get the full product and configuration details for a specific page.
3

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

Submit payment

Call POST /payments with checkout_page_id and the chosen payment_plan_id to complete the purchase.
Checkout pages are the fastest way to go live. No custom frontend is required — Nova.Pay handles the UI.

​
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:
1

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

Customer pays

Call POST /carts/{id}/pay with the customer’s chosen payment method to finalize the transaction.
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.

​
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:
1

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

Customer pays

Call POST /charges/{id}/pay with the customer’s chosen payment method.
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.

​
Choosing a Path

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

​
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:
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:
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:
The upsell endpoint reuses the payment method from the original transaction, so no additional card or Pix data is needed.

Related topics

Nova.Pay API: Payments, Checkout & Order ManagementCharges API — Pay Invoice and Charge Link EndpointsCarts API — Create, Retrieve, and Pay Nova.Pay CartsOrder Lifecycle and Status Transitions in Nova.PayCreate and Process Your First Payment with Nova.Pay