Payment Plans API — List and Retrieve Installment Options

Before accepting payment, fetch the available payment methods and installment options. GET /payment_plans returns options grouped by method, with one entry per selectable installment count. Pass the selected option’s id verbatim as payment_plan_id when submitting a payment. Base URL: https://yourcompany.pay.nova.money/api/v1 Replace yourcompany with your company’s Nova.Pay subdomain.

List payment plans

GET /payment_plans

Context and total calculation

Send exactly one context parameter: checkout_page_id, charge_id, cart_id, or cart_page_id. If you send more than one, the API resolves them in that order. With no context parameter, it returns every kept payment plan.

Use cart_page_id to display a cart page’s installment options before a cart exists. Pair it with amount or products to calculate installment values. Once you create the cart, use cart_id.
amount overrides the context total whenever you supply it.
Otherwise, a charge uses its items, freight, fine, and late interest; a cart uses its total.
For checkout_page_id or no context, the API computes the total from products and applies coupon when valid.

products is required unless you supply charge_id, cart_id, or cart_page_id. Supplying amount does not remove this requirement for checkout-page or no-context requests. Missing products return 422 with Informe ao menos um produto.

Query parameters

string (uuid)

CheckoutPage UUID. Returns the plans enabled for that checkout page. Include products.

string

Order UID for the charge context. Without an amount override, installment values use the charge total, including items, freight, fine, and late interest.

string

Cart UID. Returns plans from the cart’s cart page and uses the cart total unless amount overrides it.

string (uuid)

CartPage UUID. Returns plans before a cart exists. Pair with amount or products to get installment values; switch to cart_id after creating the cart.

number

Overrides the context total. This is an amount override, not a context selector; it does not waive the conditional products requirement.

string

Coupon code. When the total is calculated from products, a valid coupon is applied before returning installment values.

object

Products hash containing product IDs and quantities, for example products[7]=2&products[12]=1. Required unless charge_id, cart_id, or cart_page_id is supplied.

Request examples

Replace the sample UUIDs and product IDs with your own. Requests remain subject to host restrictions.

curl -G "https://yourcompany.pay.nova.money/api/v1/payment_plans" \
  --data-urlencode "checkout_page_id=550e8400-e29b-41d4-a716-446655440000" \
  --data-urlencode "products[7]=2"

curl -G "https://yourcompany.pay.nova.money/api/v1/payment_plans" \
  --data-urlencode "cart_page_id=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  --data-urlencode "amount=120"

curl -G "https://yourcompany.pay.nova.money/api/v1/payment_plans" \
  --data-urlencode "cart_id=cart_uid_abc123"

Response

200 OK returns a PaymentPlanOptions object, not an array. Only payment methods configured for the context appear as top-level keys. Each key maps to an array of PaymentPlanOption objects: one per selectable installment count.

PaymentPlanOption[]

Credit-card options, when configured for the context.

PaymentPlanOption[]

Bank-slip options, when configured for the context.

PaymentPlanOption[]

Pix options, when configured for the context.

Complete JSON response

This illustrative response includes every option property in the Swagger schema. It shows a total of 120, all three methods configured, and no fees, late charges, or coupon discount. Actual options and amounts depend on your context.

{
  "credit_card": [
    {
      "id": "42-1",
      "name": "1x no Cartão de Crédito",
      "number": 1,
      "value": 120,
      "fine": 0,
      "fine_tax": 0,
      "fine_type": "fixed",
      "late_interest": 0,
      "late_interest_tax": 0,
      "payment_method": "credit_card",
      "fixed": 0,
      "percentage": 0
    },
    {
      "id": "42-3",
      "name": "3x no Cartão de Crédito",
      "number": 3,
      "value": 40,
      "fine": 0,
      "fine_tax": 0,
      "fine_type": "fixed",
      "late_interest": 0,
      "late_interest_tax": 0,
      "payment_method": "credit_card",
      "fixed": 0,
      "percentage": 0
    }
  ],
  "bank_slip": [
    {
      "id": "44-1",
      "name": "Boleto",
      "number": 1,
      "value": 120,
      "fine": 0,
      "fine_tax": 0,
      "fine_type": "fixed",
      "late_interest": 0,
      "late_interest_tax": 0,
      "payment_method": "bank_slip",
      "fixed": 0,
      "percentage": 0
    }
  ],
  "pix": [
    {
      "id": "43-1",
      "name": "Pix",
      "number": 1,
      "value": 120,
      "fine": 0,
      "fine_tax": 0,
      "fine_type": "fixed",
      "late_interest": 0,
      "late_interest_tax": 0,
      "payment_method": "pix",
      "fixed": 0,
      "percentage": 0
    }
  ]
}

PaymentPlanOption fields

string

Compound identifier in the format "{payment_plan_id}-{installments}", for example "42-3". Send it verbatim as payment_plan_id to the payment endpoint.

string

Human-readable option label, for example "3x no Cartão de Crédito".

integer

Installment count.

number

Per-installment amount, with applicable interest and coupon already applied.

number

Fine amount for charge contexts past their due date.

number

Fine rate returned for the option.

string

Fine type returned for the option.

number

Late-interest amount returned for the option.

number

Late-interest rate returned for the option.

string

One of credit_card, bank_slip, or pix.

number

Fixed fee added to the total for this installment count, in the context currency. Already included in value. Returns 0 when the plan has no tax row for this installment count.

number

Interest rate applied to the total for this installment count, expressed as a percentage: 1.79 means 1.79%. Already included in value. Returns 0 when the plan has no tax row for this installment count.

Display the returned value for each installment. Do not add fixed or apply percentage again: both are already included in value.

Error responses

403 Forbidden: the origin is not allowed or the API key is invalid. The Swagger does not define a JSON response body for this status.
422 Unprocessable Entity: validation or business-logic error. The JSON body contains errors, an array of strings.

Missing products (422)

{"errors":["Informe ao menos um produto"]}

Using payment plan IDs

Fetch available plans

Call GET /payment_plans with the relevant context and any required products. Use cart_page_id before cart creation and cart_id afterward.

Present options to the customer

Render each option’s name, number, and value. Use the returned method groups to show the available payment methods.

Pass the selected ID to the payment endpoint

Send the option’s exact id as payment_plan_id to the cart, charge, or checkout payment endpoint. For example, select "42-3" for the three-installment credit-card option above.

When using a coupon, fetch plans with the coupon to display the applicable values, and pass the same coupon code when submitting the payment.

Checkout

Payments

Management

Webhooks

Payment Plans API — List and Retrieve Installment Options

List payment plans

Context and total calculation

Query parameters

Request examples

Response

Complete JSON response

PaymentPlanOption fields

Error responses

Using payment plan IDs

​List payment plans

​Context and total calculation

​Query parameters

​Request examples

​Response

​Complete JSON response

​PaymentPlanOption fields

​Error responses

​Using payment plan IDs

List payment plans

Context and total calculation

Query parameters

Request examples

Response

Complete JSON response

PaymentPlanOption fields

Error responses

Using payment plan IDs