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

gateway

string

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

main_color

string

Hex colour code for the hosted payment page brand colour.

menus

array

Navigation menu items displayed on the hosted page.

page_title

string

Title shown to customers on the hosted payment page.

public_key

string

Gateway public key used for client-side card tokenisation.

logo

string

URL of the logo image shown on the hosted page.

currency

string

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

enable_coupons

boolean

Whether coupon code entry is available for this cart.

enable_two_cards

boolean

Whether the customer can split payment across two credit cards.

company_id

integer

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

freight

number

Shipping / freight amount applied to the cart.

customer

object

Pre-filled customer information.

Show customer fields

identification

string

Customer CPF/CNPJ or other national identifier.

string

Customer email address.

phone

string

Customer phone number.

name

string

Customer full name.

state

string

Customer state / province.

street

string

Customer street address.

zipcode

string

Customer postal / ZIP code.

city

string

Customer city.

products

array

Items currently in the cart.

Show product fields

integer

Internal product ID.

name

string

Product name.

external_id

string

Your own external reference for this product.

quantity

integer

Number of units.

value

number

Unit price.

total

number

Line total (quantity × value).

image

string

URL of the product image.

custom_code

string

Arbitrary code snippet injected into the hosted payment page.

default_payment_plan

object

The pre-selected payment plan for this cart.

integrations

object

Third-party integration configuration attached to this cart.

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

payment_method

string

required

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

freight

number

Shipping / freight cost to add to the cart total.

total

number

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

customer

object

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

Show customer fields

identification

string

CPF, CNPJ, or other national identifier.

string

Customer email address.

phone

string

Customer phone number.

name

string

Customer full name.

state

string

State / province.

street

string

Street address.

zipcode

string

Postal / ZIP code.

city

string

City.

items

array

The line items to include in the cart.

Show item fields

integer

Product ID from Nova.Pay.

name

string

Product name (used if id is not provided).

external_id

string

Your own reference ID for this item.

quantity

integer

Number of units.

value

number

Unit price.

total

number

Line total. Defaults to quantity × value.

image

string

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

Response

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

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"
    }
  }'

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

ids

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

payment_plan_id

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.

coupon

string

Coupon code to apply a discount to this payment.

confirmation_token_id

string

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

credit_card_0_token

string

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

credit_card_0_card_id

string

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

credit_card_0_payment_plan

string

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

credit_card_0_amount

number

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

credit_card_1_token

string

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

credit_card_1_card_id

string

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

credit_card_1_payment_plan

string

Payment plan ID for the secondary card.

credit_card_1_amount

number

Amount to charge to the secondary credit card.

customer_id

string

Nova.Pay customer ID to associate with this payment.

customer_phone

string

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

customer_email

string

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

gateway

string

Override the default gateway for this payment.

Response

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

order_status

string

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

payments

array

Array of payment objects created for this order.

bank_slip_url

string

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

pix_qr_code

string

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

pix_qr_code_url

string

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

pix_expires_at

string

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

redirect_url

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

Create a cart

Path parameters

Request body

Response

List payments for a cart

Path parameters

Query parameters

Response

Pay a cart

Path parameters

Request body

Response

Example — credit card payment

​Retrieve cart page details

​Path parameters

​Response

​Create a cart

​Path parameters

​Request body

​Response

​List payments for a cart

​Path parameters

​Query parameters

​Response

​Pay a cart

​Path parameters

​Request body

​Response

​Example — credit card payment

Retrieve cart page details

Path parameters

Response

Create a cart

Path parameters

Request body

Response

List payments for a cart

Path parameters

Query parameters

Response

Pay a cart

Path parameters

Request body

Response

Example — credit card payment