Checkout Pages API — List and Retrieve Checkout Pages

Checkout pages are the hosted payment forms you create in Nova.Pay. Each page can carry one or more products, accept multiple payment methods, and be customised with your brand colours and logo. The endpoints below let you programmatically list your pages, fetch their full configuration, and inspect the payments that have been made through them. Base URL: https://yourcompany.pay.nova.money/api/v1

List checkout pages

Authentication is required for all checkout-page endpoints. Pass your API key in the Authorization header as a Bearer token.

Retrieve a paginated list of your checkout pages. You can narrow the results with the optional query parameters below.

GET /checkout_pages

Query parameters

string

Free-text search string. Matches against the page title and other indexed fields.

boolean

When true, only returns pages that have at least one product attached. When false, returns pages with no products.

array of integers

Filter pages to only those that include any of the specified product IDs. Pass multiple values as repeated query params: product_ids[]=1&product_ids[]=2.

Response

Returns an array of CheckoutPageSummary objects.

curl --request GET \
  --url "https://yourcompany.pay.nova.money/api/v1/checkout_pages?has_products=true" \
  --header "Authorization: Bearer YOUR_API_KEY"

Example response

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "page_title": "Summer Sale Checkout",
    "main_color": "#6366f1",
    "currency": "BRL",
    "gateway": "stripe",
    "public_key": "pk_live_xxxxxxxxxxxx",
    "subscription": false,
    "enable_coupons": true,
    "company_id": 42
  }
]

Complete JSON response

This example includes every response property defined for this operation in the OpenAPI schema.

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "customer_data_at": "string",
    "gateway": "pagarme",
    "main_color": "string",
    "page_title": "string",
    "logo": "https://example.com/resource",
    "currency": "BRL",
    "products": [
      {
        "id": 123,
        "uid": "example-id",
        "name": "Example",
        "description": "string",
        "product_type": "string",
        "subscription": true,
        "type": "string",
        "interval": "string",
        "max_quantity": 1,
        "value": 100.5,
        "image": "https://example.com/resource",
        "allow_quantity": true,
        "recommended": true
      }
    ],
    "order_bump_products": [
      {
        "id": 123,
        "uid": "example-id",
        "name": "Example",
        "description": "string",
        "product_type": "string",
        "subscription": true,
        "type": "string",
        "interval": "string",
        "max_quantity": 1,
        "value": 100.5,
        "image": "https://example.com/resource",
        "allow_quantity": true,
        "recommended": true
      }
    ]
  }
]

Retrieve a checkout page

Fetch the full configuration for a single checkout page by its UUID.

GET /checkout_pages/{id}

Path parameters

string

required

The UUID of the checkout page.

Response

Returns a CheckoutPageShow object, which extends CheckoutPageSummary with the full set of fields listed below.

string (uuid)

Unique identifier for the checkout page.

string

Specifies at which step of the checkout flow customer data is collected. Typical values are "start" or "end".

string

The payment gateway configured for this page (e.g. "stripe", "pagarme").

string

Hex colour code used as the primary brand colour on the hosted page.

string

The display title shown to customers on the checkout page.

string

URL of the logo image displayed on the checkout page.

string

ISO 4217 currency code (e.g. "BRL", "USD").

array

Navigation menu items configured for the page.

string

The gateway public key used to tokenise card data on the client side.

boolean

Whether the checkout page is configured for recurring / subscription billing.

boolean

Whether coupon code entry is enabled on this page.

boolean

When true, the hosted page allows indexing by search engine crawlers.

boolean

When true, the customer must select a scheduled date before completing checkout.

boolean

When true, the customer may split the payment across two credit cards.

integer

ID of the Nova.Pay company that owns this checkout page.

object

An optional product offered as an upsell after the main purchase.

Show upsell_product fields

integer

Product ID.

string

Product name.

string

Arbitrary HTML/JS snippet injected into the hosted page (e.g. tracking pixels).

object

The pre-selected payment plan shown to the customer on page load.

Show default_payment_plan fields

string

Payment plan ID (e.g. "42-1").

string

Human-readable label.

string

Payment method for this plan.

object

Third-party integration configuration (webhooks, analytics, CRM connections, etc.).

array

The products attached to this checkout page.

Show Product fields

integer

Internal product ID.

string

Public-facing unique identifier for the product.

string

Product name.

string

Product description shown to customers.

string

Category of the product (e.g. "digital", "physical").

boolean

Whether the product is sold as a subscription.

string

Product billing type.

string

Recurrence interval for subscriptions (e.g. "monthly").

integer

Maximum number of units a customer can purchase.

number

Unit price of the product.

string

URL of the product image.

boolean

Whether the customer can choose a quantity greater than one.

boolean

Whether this product is highlighted as recommended.

Complete JSON response

This example includes every response property defined for this operation in the OpenAPI schema.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "customer_data_at": "string",
  "gateway": "pagarme",
  "main_color": "string",
  "page_title": "string",
  "logo": "https://example.com/resource",
  "currency": "BRL",
  "products": [
    {
      "id": 123,
      "uid": "example-id",
      "name": "Example",
      "description": "string",
      "product_type": "string",
      "subscription": true,
      "type": "string",
      "interval": "string",
      "max_quantity": 1,
      "value": 100.5,
      "image": "https://example.com/resource",
      "allow_quantity": true,
      "recommended": true
    }
  ],
  "order_bump_products": [
    {
      "id": 123,
      "uid": "example-id",
      "name": "Example",
      "description": "string",
      "product_type": "string",
      "subscription": true,
      "type": "string",
      "interval": "string",
      "max_quantity": 1,
      "value": 100.5,
      "image": "https://example.com/resource",
      "allow_quantity": true,
      "recommended": true
    }
  ],
  "menus": {},
  "public_key": "-----BEGIN RSA PUBLIC KEY-----xxxxx-----END RSA PUBLIC KEY-----",
  "use_antifraud": true,
  "subscription": true,
  "enable_coupons": true,
  "index_on_search_engines": true,
  "require_scheduling": true,
  "enable_two_cards": true,
  "company_id": 123,
  "upsell_product": {
    "id": 123,
    "uid": "example-id",
    "name": "Example",
    "description": "string",
    "product_type": "string",
    "subscription": true,
    "type": "string",
    "interval": "string",
    "max_quantity": 1,
    "value": 100.5,
    "image": "https://example.com/resource",
    "allow_quantity": true,
    "recommended": true
  },
  "custom_code": {
    "example": "value"
  },
  "default_payment_plan": {
    "id": "example-id",
    "installments": 1,
    "payment_method": "string"
  },
  "integrations": {
    "example": "value"
  }
}

Get the Belluno card hash key

Retrieve the RSA public key required to encrypt card data before creating a payment through Belluno.

GET /checkout_pages/{id}/card_hash_key

This endpoint is available only when the checkout page uses the belluno gateway and its company has a configured Belluno integration.

Path parameters

string

required

The CheckoutPage UUID.

Response

Returns the Belluno CardHashKey object exactly as provided by Belluno.

integer

Identifier of the generated card hash key.

string

RSA public key in PEM format. Use it to encrypt card data in the client, then submit the resulting hash as the card token to POST /payments.

string

ISO 8601 datetime when the key was created.

Example response

{
  "id": 123,
  "rsa_public_key": "-----BEGIN RSA PUBLIC KEY-----xxxxx-----END RSA PUBLIC KEY-----",
  "created_at": "2026-08-25T12:00:00Z"
}

Errors

Status	Meaning
`403`	The request origin is not allowed.
`404`	The checkout page was not found.
`422`	The page does not use Belluno, the company has no configured Belluno integration, or Belluno failed to return a key.

A 422 response contains an errors field as either a string or an array of strings.

List payments for a checkout page

Returns all payments submitted through a given checkout page.

GET /checkout_pages/{id}/payments

Path parameters

string

required

The UUID of the checkout page.

Query parameters

array

Filter the results to specific payments. Each value may be either a gateway_id (e.g. "pay_abc123") or an internal payment ID. Pass multiple values as repeated query params: ids[]=pay_abc123&ids[]=pay_def456.

Response

Returns an array of PaymentStatus objects, or HTTP 204 No Content if no payments have been made through this page yet.

Example response

[
  {
    "gateway_id": "pay_abc123",
    "status": "paid"
  },
  {
    "gateway_id": "pay_def456",
    "status": "waiting_payment"
  }
]

string

The payment identifier issued by the gateway (e.g. a Stripe PaymentIntent ID).

string

Current status of the payment. Common values: paid, waiting_payment, failed, cancelled.

Checkout

Payments

Management

Webhooks

Checkout Pages API — List and Retrieve Checkout Pages

List checkout pages

Query parameters

Response

Complete JSON response

Retrieve a checkout page

Path parameters

Response

Complete JSON response

Get the Belluno card hash key

Path parameters

Response

Errors

List payments for a checkout page

Path parameters

Query parameters

Response