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

Request Body

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.

string

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

string

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

string

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

number

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

string

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

string

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

string

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

number

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

Card Fields (Stripe)

string

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

Customer

integer

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

string

Customer’s email address.

string

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

object

Customer’s billing or shipping address.

Show customer_address fields

string

City name.

string

Neighborhood or district.

string

Street number.

string

State or province (two-letter code recommended).

string

Street name.

string

Postal / ZIP code.

Checkout Context

string

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

integer

ID of the primary product being purchased.

array

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

Show products item fields

integer

Product ID.

integer

Number of units.

Optional Fields

string

Coupon or discount code to apply to the order.

string

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

string

Arbitrary tag string for internal labeling or filtering.

string

ISO 8601 datetime to schedule the charge for a future date and time.

string

Free-text note attached to the order.

object

Arbitrary key/value metadata stored alongside the order. Useful for tracking campaign sources, funnel steps, or custom attributes.

Response — PaymentResult

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.

array of strings

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

string (uri)

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

string

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

string (uri)

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

string (datetime)

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

string (uri)

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

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.

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

number

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

string (datetime)

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

string

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

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://yourcompany.pay.nova.money/api/v1/payments/1234/refund \
  --header "Authorization: Bearer <api_key>" \
  --header "Content-Type: application/json" \
  --data '{}'

curl --request POST \
  --url https://yourcompany.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