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

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

> REST API for Nova.Pay carts. Create a cart from a checkout page, list cart payments, and submit a cart payment using credit card, Pix, or bank slip.

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://pay.nova.money/api/v1`

***

## Retrieve cart page details

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

```http theme={null}
GET /carts/{id}
```

### Path parameters

<ParamField path="id" type="string" required>
  The Cart UID.
</ParamField>

### Response

Returns a **CartShow** object.

<ResponseField name="id" type="string">
  The Cart UID.
</ResponseField>

<ResponseField name="gateway" type="string">
  Payment gateway handling transactions for this cart (e.g. `"stripe"`).
</ResponseField>

<ResponseField name="main_color" type="string">
  Hex colour code for the hosted payment page brand colour.
</ResponseField>

<ResponseField name="menus" type="array">
  Navigation menu items displayed on the hosted page.
</ResponseField>

<ResponseField name="page_title" type="string">
  Title shown to customers on the hosted payment page.
</ResponseField>

<ResponseField name="public_key" type="string">
  Gateway public key used for client-side card tokenisation.
</ResponseField>

<ResponseField name="logo" type="string">
  URL of the logo image shown on the hosted page.
</ResponseField>

<ResponseField name="currency" type="string">
  ISO 4217 currency code (e.g. `"BRL"`, `"USD"`).
</ResponseField>

<ResponseField name="enable_coupons" type="boolean">
  Whether coupon code entry is available for this cart.
</ResponseField>

<ResponseField name="enable_two_cards" type="boolean">
  Whether the customer can split payment across two credit cards.
</ResponseField>

<ResponseField name="company_id" type="integer">
  ID of the Nova.Pay company that owns this cart.
</ResponseField>

<ResponseField name="freight" type="number">
  Shipping / freight amount applied to the cart.
</ResponseField>

<ResponseField name="customer" type="object">
  Pre-filled customer information.

  <Expandable title="customer fields">
    <ResponseField name="identification" type="string">Customer CPF/CNPJ or other national identifier.</ResponseField>
    <ResponseField name="email" type="string">Customer email address.</ResponseField>
    <ResponseField name="phone" type="string">Customer phone number.</ResponseField>
    <ResponseField name="name" type="string">Customer full name.</ResponseField>
    <ResponseField name="state" type="string">Customer state / province.</ResponseField>
    <ResponseField name="street" type="string">Customer street address.</ResponseField>
    <ResponseField name="zipcode" type="string">Customer postal / ZIP code.</ResponseField>
    <ResponseField name="city" type="string">Customer city.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="products" type="array">
  Items currently in the cart.

  <Expandable title="product fields">
    <ResponseField name="id" type="integer">Internal product ID.</ResponseField>
    <ResponseField name="name" type="string">Product name.</ResponseField>
    <ResponseField name="external_id" type="string">Your own external reference for this product.</ResponseField>
    <ResponseField name="quantity" type="integer">Number of units.</ResponseField>
    <ResponseField name="value" type="number">Unit price.</ResponseField>
    <ResponseField name="total" type="number">Line total (`quantity × value`).</ResponseField>
    <ResponseField name="image" type="string">URL of the product image.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="custom_code" type="string">
  Arbitrary code snippet injected into the hosted payment page.
</ResponseField>

<ResponseField name="default_payment_plan" type="object">
  The pre-selected payment plan for this cart.
</ResponseField>

<ResponseField name="integrations" type="object">
  Third-party integration configuration attached to this cart.
</ResponseField>

***

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

```http theme={null}
POST /carts/{id}
```

<Note>
  This endpoint requires your API key in the `Authorization: Bearer YOUR_API_KEY` header.
</Note>

### Path parameters

<ParamField path="id" type="string" required>
  The **CartPage UUID** from which the cart will be created.
</ParamField>

### Request body

<ParamField body="payment_method" type="string" required>
  The payment method for this cart. One of: `credit_card`, `bank_slip`, `pix`.
</ParamField>

<ParamField body="freight" type="number">
  Shipping / freight cost to add to the cart total.
</ParamField>

<ParamField body="total" type="number">
  Override the computed cart total. If omitted, Nova.Pay calculates the total from the items.
</ParamField>

<ParamField body="customer" type="object">
  Pre-fill customer details so the customer doesn't need to re-enter them on the hosted page.

  <Expandable title="customer fields">
    <ParamField body="identification" type="string">CPF, CNPJ, or other national identifier.</ParamField>
    <ParamField body="email" type="string">Customer email address.</ParamField>
    <ParamField body="phone" type="string">Customer phone number.</ParamField>
    <ParamField body="name" type="string">Customer full name.</ParamField>
    <ParamField body="state" type="string">State / province.</ParamField>
    <ParamField body="street" type="string">Street address.</ParamField>
    <ParamField body="zipcode" type="string">Postal / ZIP code.</ParamField>
    <ParamField body="city" type="string">City.</ParamField>
  </Expandable>
</ParamField>

<ParamField body="items" type="array">
  The line items to include in the cart.

  <Expandable title="item fields">
    <ParamField body="id" type="integer">Product ID from Nova.Pay.</ParamField>
    <ParamField body="name" type="string">Product name (used if `id` is not provided).</ParamField>
    <ParamField body="external_id" type="string">Your own reference ID for this item.</ParamField>
    <ParamField body="quantity" type="integer">Number of units.</ParamField>
    <ParamField body="value" type="number">Unit price.</ParamField>
    <ParamField body="total" type="number">Line total. Defaults to `quantity × value`.</ParamField>
    <ParamField body="image" type="string">URL of a product image to show on the hosted page.</ParamField>
  </Expandable>
</ParamField>

<ParamField body="meta" type="object">
  Arbitrary key-value pairs you want to attach to this cart for your own tracking purposes.
</ParamField>

### Response

```json theme={null}
{
  "id": "cart_uid_abc123",
  "link": "https://pay.nova.money/c/cart_uid_abc123"
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url "https://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"
      }
    }'
  ```
</CodeGroup>

***

## List payments for a cart

Returns all payments submitted against a cart.

```http theme={null}
GET /carts/{id}/payments
```

### Path parameters

<ParamField path="id" type="string" required>
  The Cart UID.
</ParamField>

### Query parameters

<ParamField query="ids" type="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`.
</ParamField>

### Response

Returns an **array of PaymentStatus** objects, or HTTP **204 No Content** if no payments exist for this cart.

```json Example response theme={null}
[
  {
    "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).

```http theme={null}
POST /carts/{id}/pay
```

### Path parameters

<ParamField path="id" type="string" required>
  The Cart UID to pay.
</ParamField>

### Request body

<ParamField body="payment_plan_id" type="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](/api-reference/payment-plans).
</ParamField>

<ParamField body="coupon" type="string">
  Coupon code to apply a discount to this payment.
</ParamField>

<ParamField body="confirmation_token_id" type="string">
  Stripe PaymentMethod confirmation token ID, used when the gateway is Stripe.
</ParamField>

<ParamField body="credit_card_0_token" type="string">
  Tokenised card data for the primary (or only) credit card.
</ParamField>

<ParamField body="credit_card_0_card_id" type="string">
  ID of a saved card on file to use for the primary credit card charge.
</ParamField>

<ParamField body="credit_card_0_payment_plan" type="string">
  Payment plan ID applied specifically to the primary card (used in two-card splits).
</ParamField>

<ParamField body="credit_card_0_amount" type="number">
  Amount to charge to the primary credit card (used in two-card splits).
</ParamField>

<ParamField body="credit_card_1_token" type="string">
  Tokenised card data for the secondary credit card (two-card split).
</ParamField>

<ParamField body="credit_card_1_card_id" type="string">
  ID of a saved card to use for the secondary credit card charge.
</ParamField>

<ParamField body="credit_card_1_payment_plan" type="string">
  Payment plan ID for the secondary card.
</ParamField>

<ParamField body="credit_card_1_amount" type="number">
  Amount to charge to the secondary credit card.
</ParamField>

<ParamField body="customer_id" type="string">
  Nova.Pay customer ID to associate with this payment.
</ParamField>

<ParamField body="customer_phone" type="string">
  Customer phone number (used if not already on the cart).
</ParamField>

<ParamField body="customer_email" type="string">
  Customer email address (used if not already on the cart).
</ParamField>

<ParamField body="gateway" type="string">
  Override the default gateway for this payment.
</ParamField>

<ParamField body="tags" type="array">
  List of string tags to attach to the resulting order for filtering and reporting.
</ParamField>

<ParamField body="scheduled_at" type="string">
  ISO 8601 datetime for scheduling the payment at a future time (requires `require_scheduling` on the page).
</ParamField>

<ParamField body="observation" type="string">
  Free-text note attached to the order.
</ParamField>

<ParamField body="meta" type="object">
  Arbitrary key-value pairs attached to the order.
</ParamField>

### Response

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

<ResponseField name="order_status" type="string">
  The resulting status of the order (e.g. `"paid"`, `"waiting_payment"`, `"pending"`).
</ResponseField>

<ResponseField name="payments" type="array">
  Array of payment objects created for this order.
</ResponseField>

<ResponseField name="bank_slip_url" type="string">
  URL of the generated boleto (bank slip) PDF. Present only for `bank_slip` payments.
</ResponseField>

<ResponseField name="pix_qr_code" type="string">
  Base64-encoded Pix QR code image. Present only for `pix` payments.
</ResponseField>

<ResponseField name="pix_qr_code_url" type="string">
  URL to the Pix QR code image. Present only for `pix` payments.
</ResponseField>

<ResponseField name="pix_expires_at" type="string">
  ISO 8601 datetime at which the Pix QR code expires. Present only for `pix` payments.
</ResponseField>

<ResponseField name="redirect_url" type="string">
  URL to redirect the customer to after payment (e.g. a thank-you page).
</ResponseField>

### Example — credit card payment

```json Request body theme={null}
{
  "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"
  }
}
```

<Tip>
  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.
</Tip>


## Related topics

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