Create and Process Your First Payment with Nova.Pay

Nova.Pay’s checkout flow is built around three core steps: fetch the available payment plans for your product, tokenize sensitive card data client-side, and submit the payment. This guide walks you through each step end-to-end and explains how to interpret the response so you can deliver a smooth experience to your customers.

Get Available Payment Plans

Before presenting a checkout form, retrieve the payment plans associated with your product. Each plan describes an available payment method (credit card, Pix, boleto) along with instalment options and pricing.Endpoint: GET /payment_plans

Query parameter	Description
`checkout_page_id`	CheckoutPage UUID; include `products`
`charge_id`	Order UID for a charge
`cart_id`	Cart UID; uses the cart’s total
`cart_page_id`	CartPage UUID before a cart exists; pair with `amount` or `products`
`amount`	Overrides the context total; does not waive the conditional `products` requirement
`coupon`	Optional coupon code applied when calculating the total from products
`products`	Product ID/quantity hash; required unless `charge_id`, `cart_id`, or `cart_page_id` is supplied

Send one context parameter. If multiple are supplied, precedence is checkout_page_id, charge_id, cart_id, then cart_page_id. With no context, every kept plan is returned and products are still required.

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"

The response is an object grouped by payment method, with one entry per selectable installment count. Only configured methods appear. Pass the chosen id (for example, "42-3") as payment_plan_id. This example shows a total of 120 without fees or discounts and includes every option field.

{
  "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
    }
  ]
}

value is the per-installment amount. fixed and percentage are already included; do not add them again. See the Payment Plans reference for field definitions and error responses.

Tokenize the Card (Credit Card Only)

Nova.Pay never receives raw card numbers. Card data must be tokenized client-side using the gateway’s own SDK before you submit the payment. Nova.Pay supports both Pagar.me and Stripe as card gateways.

Never send raw card numbers to the Nova.Pay API. Always tokenize card data using the gateway SDK running in the customer’s browser.

Pagar.me
Stripe

Use the Pagar.me.js SDK to create a card token. The returned token string (e.g. tok_abc123) is what you pass to POST /payments as credit_card_0_token.

const pagarme = await PagarMe.init({ publicKey: "pk_live_..." });

const cardToken = await pagarme.fields.getCreditCardToken({
  holderName: "Maria Silva",
  number: "4111111111111111",
  expirationMonth: "12",
  expirationYear: "2027",
  cvv: "123",
});

console.log(cardToken.token); // "tok_abc123"

Use Stripe.js to create a ConfirmationToken. Pass the returned confirmation_token_id as credit_card_0_token in the Nova.Pay request body.

const stripe = Stripe("pk_live_...");

const { confirmationToken, error } = await stripe.createConfirmationToken({
  elements, // your Stripe Elements instance
});

console.log(confirmationToken.id); // "ctoken_abc123"

Submit the Payment

Call POST /payments with the payment_plan_id from Step 1, the gateway token from Step 2 (credit card only), and the customer’s contact details.Endpoint: POST /payments
Base URL: https://yourcompany.pay.nova.money/api/v1

Credit Card
Pix
Boleto

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",
    "credit_card_0_token": "tok_abc123",
    "credit_card_0_payment_plan": "42-1"
  }'

No card token is required for Pix. Nova.Pay generates a QR code and returns it in the response.

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

Nova.Pay generates a bank slip (boleto) URL and returns it in the response.

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

Handle the Response

A successful request returns HTTP 200 with a PaymentResult object. Inspect order_status first, then branch based on the payment method used.

string

required

Overall status of the order (e.g. "paid", "pending", "refused").

array

Array of gateway-level payment IDs created for this order.

string

URL to the generated boleto PDF. Present only when the payment method is boleto.

string

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

string

Hosted URL for the Pix QR code image. Present only for Pix payments.

string

ISO 8601 timestamp indicating when the Pix QR code expires. Present only for Pix payments.

string

Success redirect URL if one is configured on the checkout page. Redirect the customer here after displaying confirmation.

string

Signed GlobalID (SGID) of an upsell offer, if the checkout page has one configured and the payment succeeded.

boolean

true when the purchased product is a subscription. Use this to show appropriate messaging to the customer.

If the response contains an offer field, you can present the customer with a one-click upsell — no card re-entry needed. See the Upsell guide for details.

Two-Card Split Payment

Nova.Pay supports splitting a payment across two credit cards. Include both tokens and their respective payment plan assignments in the request body.

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",
    "credit_card_0_token": "tok_abc123",
    "credit_card_0_payment_plan": "42-1",
    "credit_card_1_token": "tok_xyz789",
    "credit_card_1_payment_plan": "42-1"
  }'

Each card is charged independently by the gateway. The payments array in the response will contain two entries — one per card.

Get Started

Concepts

Guides

Create and Process Your First Payment with Nova.Pay

Two-Card Split Payment

​Two-Card Split Payment

Two-Card Split Payment