Carts API — Create, Retrieve, and Pay Nova.Pay Carts

Carts let you programmatically compose an order — choosing products, applying freight, pre-filling customer data — and then direct your customer to a hosted payment link, or accept payment directly via API. A cart is always derived from a CartPage, which defines the available products and payment rules. Base URL: https://yourcompany.pay.nova.money/api/v1

Retrieve cart page details

Fetch the configuration and current state of a cart by its unique identifier.

GET /carts/{id}

Path parameters

string

required

The Cart UID.

Response

Returns a CartShow object.

string

The Cart UID.

string

Payment gateway handling transactions for this cart (e.g. "stripe").

string

Hex colour code for the hosted payment page brand colour.

array

Navigation menu items displayed on the hosted page.

string

Title shown to customers on the hosted payment page.

string

Gateway public key used for client-side card tokenisation.

string

URL of the logo image shown on the hosted page.

string

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

boolean

Whether coupon code entry is available for this cart.

boolean

Whether the customer can split payment across two credit cards.

integer

ID of the Nova.Pay company that owns this cart.

number

Shipping / freight amount applied to the cart.

object

Pre-filled customer information.

Show customer fields

string

Customer CPF/CNPJ or other national identifier.

string

Customer email address.

string

Customer phone number.

string

Customer full name.

string

Customer state / province.

string

Customer street address.

string

Customer postal / ZIP code.

string

Customer city.

array

Items currently in the cart.

Show product fields

integer

Internal product ID.

string

Product name.

string

Your own external reference for this product.

integer

Number of units.

number

Unit price.

number

Line total (quantity × value).

string

URL of the product image.

string

Arbitrary code snippet injected into the hosted payment page.

object

The pre-selected payment plan for this cart.

object

Third-party integration configuration attached to this cart.

Complete JSON response

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

{
  "id": "example-id",
  "gateway": "pagarme",
  "main_color": "string",
  "menus": {},
  "page_title": "string",
  "public_key": "-----BEGIN RSA PUBLIC KEY-----xxxxx-----END RSA PUBLIC KEY-----",
  "use_antifraud": true,
  "logo": "https://example.com/resource",
  "currency": "BRL",
  "enable_coupons": true,
  "enable_two_cards": true,
  "company_id": 123,
  "freight": 100.5,
  "customer": {
    "email": "customer@example.com",
    "name": "Example",
    "phone": "+5511999990000",
    "foreign": true,
    "identification": "12345678909",
    "address": {
      "street": "string",
      "neighborhood": "string",
      "number": "string",
      "complement": "string",
      "zipcode": "01310100",
      "city": "string",
      "state": "SP"
    }
  },
  "products": [
    {
      "id": 123,
      "name": "Example",
      "description": "string",
      "product_type": "string",
      "quantity": 1,
      "value": 100.5,
      "image": "string"
    }
  ],
  "custom_code": {
    "example": "value"
  },
  "default_payment_plan": {
    "id": "example-id",
    "installments": 1,
    "payment_method": "string"
  },
  "integrations": {
    "example": "value"
  }
}

Create a cart

Create a new cart from a CartPage. This endpoint requires authentication via API key and returns a hosted payment link you can redirect your customer to.

POST /carts/{id}

This endpoint requires your API key in the Authorization: Bearer YOUR_API_KEY header.

Path parameters

string

required

The CartPage UUID from which the cart will be created.

Request body

string

required

The payment method for this cart. One of: credit_card, bank_slip, pix.

number

Shipping / freight cost to add to the cart total.

number

Override the computed cart total. If omitted, Nova.Pay calculates the total from the items.

object

Pre-fill customer details so the customer doesn’t need to re-enter them on the hosted page.

Show customer fields

string

CPF, CNPJ, or other national identifier.

string

Customer email address.

string

Customer phone number.

string

Customer full name.

string

State / province.

string

Street address.

string

Postal / ZIP code.

string

City.

array

The line items to include in the cart.

Show item fields

integer

Product ID from Nova.Pay.

string

Product name (used if id is not provided).

string

Your own reference ID for this item.

integer

Number of units.

number

Unit price.

number

Line total. Defaults to quantity × value.

string

URL of a product image to show on the hosted page.

object

Arbitrary key-value pairs you want to attach to this cart for your own tracking purposes.

Response

{
  "id": "cart_uid_abc123",
  "link": "https://yourcompany.pay.nova.money/c/cart_uid_abc123"
}

curl --request POST \
  --url "https://yourcompany.pay.nova.money/api/v1/carts/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "payment_method": "credit_card",
    "freight": 15.00,
    "customer": {
      "name": "Maria Silva",
      "email": "maria@example.com",
      "phone": "11999990000",
      "identification": "123.456.789-09",
      "city": "São Paulo",
      "state": "SP",
      "zipcode": "01310-100",
      "street": "Av. Paulista, 1000"
    },
    "items": [
      {
        "id": 7,
        "quantity": 2,
        "value": 49.90
      }
    ],
    "meta": {
      "order_ref": "ORD-2024-001"
    }
  }'

Get the Belluno card hash key

Retrieve the RSA public key required to encrypt card data before paying a cart through Belluno.

GET /carts/{id}/card_hash_key

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

Path parameters

string

required

The Cart UID.

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 /carts/{id}/pay.

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 cart 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 cart

Returns all payments submitted against a cart.

GET /carts/{id}/payments

Path parameters

string

required

The Cart UID.

Query parameters

array

Filter to specific payments by gateway_id or 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 exist for this cart.

Example response

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

Pay a cart

Submit payment for an existing cart. You can pay with a credit card (including a two-card split), Pix, or bank slip (boleto).

POST /carts/{id}/pay

Path parameters

string

required

The Cart UID to pay.

Request body

string

required

The ID of the selected payment plan in the format "{plan_id}-{installments}" (e.g. "42-3" for plan 42 paid in 3 instalments). Retrieve available plans from the Payment Plans endpoint.

string

Coupon code to apply a discount to this payment.

string

Stripe PaymentMethod confirmation token ID, used when the gateway is Stripe.

string

Tokenised card data for the primary (or only) credit card.

string

ID of a saved card on file to use for the primary credit card charge.

string

Payment plan ID applied specifically to the primary card (used in two-card splits).

number

Amount to charge to the primary credit card (used in two-card splits).

string

Tokenised card data for the secondary credit card (two-card split).

string

ID of a saved card to use for the secondary credit card charge.

string

Payment plan ID for the secondary card.

number

Amount to charge to the secondary credit card.

string

Nova.Pay customer ID to associate with this payment.

string

Customer phone number (used if not already on the cart).

string

Customer email address (used if not already on the cart).

string

Override the default gateway for this payment.

array

List of string tags to attach to the resulting order for filtering and reporting.

string

ISO 8601 datetime for scheduling the payment at a future time (requires require_scheduling on the page).

string

Free-text note attached to the order.

object

Arbitrary key-value pairs attached to the order.

Response

Returns a CartPayResult object. Fields present in the response depend on the payment method used.

string

The resulting status of the order (e.g. "paid", "waiting_payment", "pending").

array

Array of payment objects created for this order.

string

URL of the generated boleto (bank slip) PDF. Present only for bank_slip payments.

string

Base64-encoded Pix QR code image. Present only for pix payments.

string

URL to the Pix QR code image. Present only for pix payments.

string

ISO 8601 datetime at which the Pix QR code expires. Present only for pix payments.

string

URL to redirect the customer to after payment (e.g. a thank-you page).

Example — credit card payment

Request body

{
  "payment_plan_id": "42-1",
  "credit_card_0_token": "tok_visa_xxxxxxxxxxxx",
  "customer_email": "maria@example.com",
  "customer_phone": "11999990000",
  "meta": {
    "session_id": "sess_abc123"
  }
}

For a two-card split, provide both credit_card_0_* and credit_card_1_* fields. Make sure the two amounts sum to the cart total. You can use a different payment_plan_id for each card to have one card pay in a single charge and the other in instalments.

Checkout

Payments

Management

Webhooks

Carts API — Create, Retrieve, and Pay Nova.Pay Carts

Retrieve cart page details

Path parameters

Response

Complete JSON response

Create a cart

Path parameters

Request body

Response

Get the Belluno card hash key

Path parameters

Response

Errors

List payments for a cart

Path parameters

Query parameters

Response

Pay a cart

Path parameters

Request body

Response

Example — credit card payment