How to Validate and Apply Discount Coupons in Nova.Pay

Nova.Pay supports coupon codes that reduce the order total for your customers. The recommended flow is to validate the coupon code first so you can display the discounted price before checkout, then pass the code when fetching payment plans and again when submitting the payment. This ensures the discount is applied consistently at every stage of the purchase.

Step 1: Validate a Coupon

Before showing the discounted price to a customer, verify that the coupon code exists, is active, and applies to the product being purchased. Endpoint: GET /coupons/{code}/validate

Query parameter	Description
`product_id`	ID of the product the customer is purchasing

curl -G "https://yourcompany.pay.nova.money/api/v1/coupons/SUMMER20/validate" \
  --data-urlencode "product_id=101"

Response:

{
  "code": "SUMMER20",
  "value": 20.0,
  "type": "percentage"
}

string

required

The coupon code as stored in Nova.Pay (normalized, uppercased).

number

required

The discount magnitude. Interpretation depends on type:

When type is "percentage", this is the percentage to deduct (e.g. 20.0 = 20% off).
When type is "price", this is the fixed amount to deduct in the currency’s major unit (e.g. 15.0 = R$ 15.00 off).

string

required

Discount strategy. One of:

Value	Meaning
`percentage`	Deduct a percentage of the order total
`price`	Deduct a fixed amount from the order total

If the coupon code is invalid, expired, or does not apply to the specified product, the API returns 422 Unprocessable Entity with a descriptive error message. Always handle this case in your UI so customers can correct the code.

Step 2: Fetch Payment Plans with the Coupon

Once you have a valid coupon, pass it as the coupon query parameter when fetching payment plans. Nova.Pay recalculates plan amounts server-side and returns prices that already reflect the discount — you can display these directly to the customer without any client-side arithmetic. Endpoint: GET /payment_plans

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

products is required for checkout-page requests. The response is grouped by payment method, and each option’s value is the per-installment amount with the valid coupon applied. This example assumes a product total of 100, a 20% coupon, no fees, and all three methods configured.

{
  "credit_card": [
    {
      "id": "42-1",
      "name": "1x no Cartão de Crédito",
      "number": 1,
      "value": 80,
      "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": 80,
      "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": 80,
      "fine": 0,
      "fine_tax": 0,
      "fine_type": "fixed",
      "late_interest": 0,
      "late_interest_tax": 0,
      "payment_method": "pix",
      "fixed": 0,
      "percentage": 0
    }
  ]
}

Each option includes fixed and percentage, both already included in value. Do not apply these fees again. See the Payment Plans reference for the complete field descriptions.

Step 3: Apply the Coupon at Payment Time

Include the coupon field in your POST /payments request body. Nova.Pay validates the coupon again server-side and applies the discount to the charge. Endpoint: POST /payments

curl -X POST "https://yourcompany.pay.nova.money/api/v1/payments" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_plan_id": "42-1",
    "checkout_page_id": "550e8400-e29b-41d4-a716-446655440000",
    "customer_email": "customer@example.com",
    "customer_phone": "11999998888",
    "coupon": "SUMMER20",
    "credit_card_0_token": "tok_abc123",
    "credit_card_0_payment_plan": "42-1"
  }'

Full End-to-End Example

Here is a complete POST /payments request body that combines a coupon with a credit card payment:

{
  "payment_plan_id": "42-1",
  "checkout_page_id": "550e8400-e29b-41d4-a716-446655440000",
  "customer_email": "customer@example.com",
  "customer_phone": "11999998888",
  "coupon": "SUMMER20",
  "credit_card_0_token": "tok_abc123",
  "credit_card_0_payment_plan": "42-1"
}

And the same flow with Pix — no card fields needed:

{
  "payment_plan_id": "43-1",
  "checkout_page_id": "550e8400-e29b-41d4-a716-446655440000",
  "customer_email": "customer@example.com",
  "customer_phone": "11999998888",
  "coupon": "SUMMER20"
}

If the coupon code passed in POST /payments is invalid or does not apply to the selected products, Nova.Pay returns 422 Unprocessable Entity with an error message identifying the problem. Make sure your checkout UI surfaces this error clearly so customers can enter a different code or proceed without a coupon.

Get Started

Concepts

Guides

How to Validate and Apply Discount Coupons in Nova.Pay

Step 1: Validate a Coupon

Step 2: Fetch Payment Plans with the Coupon

Step 3: Apply the Coupon at Payment Time

Full End-to-End Example

​Step 1: Validate a Coupon

​Step 2: Fetch Payment Plans with the Coupon

​Step 3: Apply the Coupon at Payment Time

​Full End-to-End Example

Step 1: Validate a Coupon

Step 2: Fetch Payment Plans with the Coupon

Step 3: Apply the Coupon at Payment Time

Full End-to-End Example