Payments API — Create Payments and Issue Refunds

The Payments API is the core of Nova.Pay’s checkout flow. Use POST /payments to initiate a payment for a hosted checkout page — supporting credit card (single or two-card split), Pix, and bank slip — and use POST /payments/{id}/refund to issue full or partial refunds against any completed payment.

POST /payments

If any product in the order has subscription: true, the payment is processed as a recurring subscription rather than a one-time charge.

Create a checkout payment. This is the primary endpoint for hosted checkout pages. The method (credit card, Pix, or bank slip) is determined by the payment plan referenced in payment_plan_id. Base URL: https://pay.nova.money/api/v1

Request Body

payment_plan_id

string

required

The payment plan identifier retrieved from GET /payment_plans. Must follow the format "{plan_id}-{installments}" — for example, "42-3" means plan 42 paid in 3 installments.

Card Fields (Pagar.me)

For a two-card split, include both credit_card_0_* and credit_card_1_* fields and provide an amount for each card. The two amounts must sum to the order total.

credit_card_0_token

string

Card token obtained from client-side Pagar.me tokenization. Use this or credit_card_0_card_id, not both.

credit_card_0_card_id

string

Saved card ID from a previous transaction (alternative to credit_card_0_token).

credit_card_0_payment_plan

string

Payment plan for this card, in "{plan_id}-{installments}" format. Required when using a two-card split.

credit_card_0_amount

number

Amount charged to this card, in the order’s currency. Required when performing a two-card split.

credit_card_1_token

string

Card token for the second card in a split payment (Pagar.me tokenization).

credit_card_1_card_id

string

Saved card ID for the second card (alternative to credit_card_1_token).

credit_card_1_payment_plan

string

Payment plan for the second card, in "{plan_id}-{installments}" format.

credit_card_1_amount

number

Amount charged to the second card. Required when performing a two-card split.

Card Fields (Stripe)

confirmation_token_id

string

A Stripe ConfirmationToken ID generated client-side using the Stripe.js SDK. Use this field when gateway is set to "stripe".

Customer

customer_id

integer

ID of an existing Nova.Pay customer. When provided, customer contact fields are optional.

customer_email

string

Customer’s email address.

customer_phone

string

Customer’s phone number (digits only, including area code).

customer_address

object

Customer’s billing or shipping address.

Show customer_address fields

city

string

City name.

neighborhood

string

Neighborhood or district.

number

string

Street number.

state

string

State or province (two-letter code recommended).

street

string

Street name.

zipcode

string

Postal / ZIP code.

Checkout Context

checkout_page_id

string

UUID of the Nova.Pay checkout page associated with this order.

main_product_id

integer

ID of the primary product being purchased.

products

array

List of products included in the order. Each item must contain an id and a quantity.

Show products item fields

integer

Product ID.

quantity

integer

Number of units.

Optional Fields

coupon

string

Coupon or discount code to apply to the order.

gateway

string

Payment gateway to use. Accepted values: pagarme, stripe. Defaults to the checkout page’s configured gateway.

Response — PaymentResult

order_status

string

Current status of the order. Possible values:

Value	Description
`pending`	Order created but not yet submitted to the gateway.
`waiting_payment`	Awaiting customer payment (e.g., Pix or boleto not yet paid).
`partially_paid`	A partial payment has been received.
`paid`	Payment confirmed in full.
`cancelled`	Order cancelled.
`partially_refunded`	A partial refund has been issued.
`refunded`	Full refund has been issued.
`billed`	Order has been invoiced.

payments

array of strings

List of gateway-side payment IDs (e.g., Pagar.me charge IDs or Stripe PaymentIntent IDs) associated with this order.

bank_slip_url

string (uri)

URL to the printable bank slip (boleto). Present only when the payment method is bank_slip.

pix_qr_code

string

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

pix_qr_code_url

string (uri)

URL to a hosted Pix QR code page. Present only for Pix payments.

pix_expires_at

string (datetime)

ISO 8601 datetime after which the Pix QR code is no longer valid. Present only for Pix payments.

redirect_url

string (uri)

Success redirect URL, if a post-payment redirect is configured on the checkout page.

offer

string

Signed GlobalID (SGID) for a one-click upsell offer. Present only when the checkout page has an upsell configured and the payment succeeded. Pass this value to POST /upsell to confirm the offer.

is_subscription

boolean

true when the order was processed as a subscription (i.e., at least one product has subscription: true).

Request Examples

Credit Card
Pix
Boleto

{
  "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_test_abc123",
  "credit_card_0_payment_plan": "42-1"
}

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

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

Two-Card Split

When splitting a payment across two cards, include both credit_card_0_* and credit_card_1_* fields. The amount values must sum to the full order total.

{
  "payment_plan_id": "42-2",
  "checkout_page_id": "550e8400-e29b-41d4-a716-446655440000",
  "customer_email": "customer@example.com",
  "customer_phone": "11999998888",
  "credit_card_0_token": "tok_test_card1",
  "credit_card_0_payment_plan": "42-1",
  "credit_card_0_amount": 60.00,
  "credit_card_1_token": "tok_test_card2",
  "credit_card_1_payment_plan": "42-1",
  "credit_card_1_amount": 40.00
}

POST /payments/{id}/refund

This endpoint requires authentication. Include your API key as Authorization: Bearer <api_key> in the request headers.

Issue a full or partial refund for a completed payment. To refund the full amount, omit the amount field.

Path Parameters

integer

required

The numeric ID of the payment to refund.

Request Body

amount

number

Amount to refund, in the payment’s currency. Omit this field to issue a full refund.

date

string (datetime)

ISO 8601 datetime for the refund. Defaults to the current date and time if omitted.

type

string

Refund type identifier. Consult your Nova.Pay account configuration for accepted values.

transaction_id

string

Gateway-side transaction ID to target for the refund (useful when an order has multiple charges).

Response

Returns 200 OK with an empty body on success.

Request Examples

curl --request POST \
  --url https://pay.nova.money/api/v1/payments/1234/refund \
  --header "Authorization: Bearer <api_key>" \
  --header "Content-Type: application/json" \
  --data '{}'

curl --request POST \
  --url https://pay.nova.money/api/v1/payments/1234/refund \
  --header "Authorization: Bearer <api_key>" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 25.00
  }'

Checkout

Payments

Management

Webhooks

Payments API — Create Payments and Issue Refunds

POST /payments

Request Body

Card Fields (Pagar.me)

Card Fields (Stripe)

Customer

Checkout Context

Optional Fields

Response — PaymentResult

Request Examples

Two-Card Split

POST /payments/{id}/refund

Path Parameters

Request Body

Response

Request Examples

​POST /payments

​Request Body

​Card Fields (Pagar.me)

​Card Fields (Stripe)

​Customer

​Checkout Context

​Optional Fields

​Response — PaymentResult

​Request Examples

​Two-Card Split

​POST /payments/{id}/refund

​Path Parameters

​Request Body

​Response

​Request Examples

POST /payments

Request Body

Card Fields (Pagar.me)

Card Fields (Stripe)

Customer

Checkout Context

Optional Fields

Response — PaymentResult

Request Examples

Two-Card Split

POST /payments/{id}/refund

Path Parameters

Request Body

Response

Request Examples