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`	UUID of the checkout page
`charge_id`	ID of a specific charge (alternative to `checkout_page_id`)
`cart_id`	ID of a cart object (alternative to `checkout_page_id`)
`amount`	Override amount in cents (alternative to `checkout_page_id`)
`coupon`	Optional coupon code — returned amounts will reflect the discount

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

The response contains an array of plan objects. The id field (e.g. "42-3") is the payment_plan_id you will pass to POST /payments.

[
  {
    "id": "42-1",
    "payment_method": "credit_card",
    "instalments": 1,
    "amount": 9700,
    "instalment_amount": 9700,
    "currency": "BRL",
    "description": "Credit card – 1× of R$ 97.00"
  },
  {
    "id": "42-3",
    "payment_method": "credit_card",
    "instalments": 3,
    "amount": 9700,
    "instalment_amount": 3400,
    "currency": "BRL",
    "description": "Credit card – 3× of R$ 34.00"
  },
  {
    "id": "43-1",
    "payment_method": "pix",
    "instalments": 1,
    "amount": 8900,
    "instalment_amount": 8900,
    "currency": "BRL",
    "description": "Pix – 1× of R$ 89.00"
  }
]

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://pay.nova.money/api/v1

Credit Card
Pix
Boleto

curl -X POST "https://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://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://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.

order_status

string

required

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

payments

array

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

bank_slip_url

string

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

pix_qr_code

string

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

pix_qr_code_url

string

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

pix_expires_at

string

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

redirect_url

string

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

offer

string

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

is_subscription

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