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

# Payment Plans API — List and Retrieve Installment Options

> Query available payment plans for a checkout page, charge, cart, or custom amount. Returns installment options grouped by payment method.

Before accepting payment you need to present your customer with the available instalment options and payment methods. The `/payment_plans` endpoint returns these options grouped by method (credit card, Pix, bank slip), each carrying the per-instalment value and all applicable fine and interest parameters. The `id` returned by each plan option is the value you pass directly as `payment_plan_id` when calling the pay endpoints.

**Base URL:** `https://pay.nova.money/api/v1`

***

## List payment plans

Returns available payment plans for a given context. Provide **exactly one** context parameter — `checkout_page_id`, `charge_id`, or `cart_id` — or pass `amount` to calculate plans for a custom value.

```http theme={null}
GET /payment_plans
```

<Note>
  Only pass **one** context parameter per request. If you pass more than one (e.g. both `checkout_page_id` and `cart_id`), the API will use the first matching context and ignore the rest.
</Note>

### Query parameters

<ParamField query="checkout_page_id" type="string">
  Return plans for a specific checkout page. Pass the checkout page UUID.
</ParamField>

<ParamField query="charge_id" type="string">
  Return plans for a specific charge. Pass the Order UID of the charge.
</ParamField>

<ParamField query="cart_id" type="string">
  Return plans for a specific cart. Pass the Cart UID.
</ParamField>

<ParamField query="amount" type="number">
  Calculate plans for a custom monetary amount instead of a specific page, charge, or cart. Useful for dynamic pricing scenarios.
</ParamField>

<ParamField query="coupon" type="string">
  Apply a coupon code before calculating plan amounts. The returned `value` fields will reflect the discounted totals.
</ParamField>

<ParamField query="products" type="object">
  A hash of product ID to quantity pairs used to compute the amount when `checkout_page_id` is provided without a fixed cart. Example: `products[7]=2&products[12]=1`.
</ParamField>

### Response

Returns a **PaymentPlanOptions** object with keys for each available payment method. Each key maps to an array of plan option objects.

<Note>
  The `id` field of each plan option (e.g. `"42-3"`) is the exact string you must pass as `payment_plan_id` in the [Carts pay endpoint](/api-reference/carts#pay-a-cart), [Charges pay endpoint](/api-reference/charges#pay-a-charge), or any other payment endpoint.
</Note>

```json Example response theme={null}
{
  "credit_card": [
    {
      "id": "42-1",
      "name": "1x no Cartão de Crédito",
      "number": 1,
      "value": 100.00,
      "payment_method": "credit_card"
    },
    {
      "id": "42-3",
      "name": "3x no Cartão de Crédito",
      "number": 3,
      "value": 34.50,
      "payment_method": "credit_card"
    }
  ],
  "pix": [
    {
      "id": "43-1",
      "name": "Pix",
      "number": 1,
      "value": 95.00,
      "payment_method": "pix"
    }
  ],
  "bank_slip": [
    {
      "id": "44-1",
      "name": "Boleto",
      "number": 1,
      "value": 100.00,
      "payment_method": "bank_slip"
    }
  ]
}
```

### PaymentPlanOption fields

<ResponseField name="id" type="string">
  Unique identifier for this plan option in the format `"{plan_id}-{installments}"` (e.g. `"42-3"`). Pass this value verbatim as `payment_plan_id` when submitting a payment.
</ResponseField>

<ResponseField name="name" type="string">
  Human-readable label for this plan option as shown to the customer (e.g. `"3x no Cartão de Crédito"`).
</ResponseField>

<ResponseField name="number" type="integer">
  Number of instalments. A value of `1` means a single lump-sum payment.
</ResponseField>

<ResponseField name="value" type="number">
  Amount per instalment. Multiply by `number` to get the total amount the customer will pay under this plan.
</ResponseField>

<ResponseField name="fine" type="number">
  Fixed fine amount applied to late payments.
</ResponseField>

<ResponseField name="fine_tax" type="number">
  Fine expressed as a percentage rate applied to late payments.
</ResponseField>

<ResponseField name="fine_type" type="string">
  Whether the fine is a fixed value (`"fixed"`) or a percentage (`"percentage"`).
</ResponseField>

<ResponseField name="late_interest" type="number">
  Fixed late-interest amount added per period after the due date.
</ResponseField>

<ResponseField name="late_interest_tax" type="number">
  Late interest expressed as a percentage rate per period.
</ResponseField>

<ResponseField name="payment_method" type="string">
  The payment method for this plan. One of: `credit_card`, `bank_slip`, `pix`.
</ResponseField>

***

## Using payment plan IDs

<Steps>
  <Step title="Fetch available plans">
    Call `GET /payment_plans` with the appropriate context parameter to retrieve the options you want to present to your customer.

    ```bash cURL theme={null}
    curl --request GET \
      "https://pay.nova.money/api/v1/payment_plans?checkout_page_id=3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ```
  </Step>

  <Step title="Present options to the customer">
    Render each plan's `name` and `value` in your UI so the customer can choose their preferred instalment option and payment method.
  </Step>

  <Step title="Pass the plan ID to the pay endpoint">
    When the customer confirms, send the selected plan's `id` as the `payment_plan_id` field in the pay request body.

    ```json theme={null}
    {
      "payment_plan_id": "42-3",
      "credit_card_0_token": "tok_visa_xxxxxxxxxxxx"
    }
    ```
  </Step>
</Steps>

<Tip>
  If you apply a `coupon` query parameter to the `/payment_plans` request, the discounted `value` fields are returned. Make sure you use the plan `id` from that coupon-aware response when calling the pay endpoint — you will also need to pass the same `coupon` code in the pay request body to apply the discount.
</Tip>


## Related topics

- [Nova.Pay Checkout Flow: Pages, Carts, and Charge Links](/concepts/checkout-flow.md)
- [Nova.Pay Payment Methods: Credit Card, Pix, and Boleto](/concepts/payment-methods.md)
- [Create and Process Your First Payment with Nova.Pay](/guides/create-payment.md)
- [Carts API — Create, Retrieve, and Pay Nova.Pay Carts](/api-reference/carts.md)
- [Orders API — List, Retrieve, Create, and Manage Orders](/api-reference/orders.md)