Charges API — Pay Invoice and Charge Link Endpoints

A charge in Nova.Pay represents a single invoice or payment link sent to a specific customer. Unlike a checkout page (which is reusable and public), a charge is a one-time payment request tied to a particular customer and order. Use these endpoints to fetch charge details, monitor payment status, and accept payment programmatically. Base URL: https://yourcompany.pay.nova.money/api/v1

Retrieve a charge

Fetch the full details of a charge, including customer information, products, and attached documents.

GET /charges/{id}

Path parameters

string

required

The Order UID of the charge.

Response

Returns a ChargeShow object.

string

The Order UID for this charge.

string

Payment gateway handling this charge (e.g. "stripe", "pagarme").

string

Hex colour code used on the hosted charge payment page.

array

Navigation menu items shown on the hosted page.

string

Title displayed to the customer on the hosted payment page.

string

Gateway public key used for client-side card tokenisation.

string

URL of the logo image displayed on the hosted page.

string

ISO 4217 currency code (e.g. "BRL", "USD").

string

ISO 8601 date on which the charge was issued.

string

ISO 8601 due date by which the charge should be paid. Used to calculate interest and fines for late payments.

number

Retention / withholding amount deducted from the charge value.

number

Shipping / freight amount included in the charge.

boolean

Whether the customer can split this charge across two credit cards.

string

Free-text note attached to the charge, visible to the customer.

object

Customer to whom the charge is addressed.

Show customer fields

string

Customer email address.

string

Customer full name.

boolean

Whether the customer is a foreign (non-local) entity.

string

CPF, CNPJ, or other national identifier.

Company legal name (for corporate customers).

object

Customer address details.

object

Coupon applied to this charge, if any.

Show coupon fields

string

Coupon code string.

number

Discount amount or percentage applied by the coupon.

array

Products included in this charge.

Show product fields

integer

Internal product ID.

string

Product name.

string

Product description.

string

Product category (e.g. "digital", "physical").

boolean

Whether the product is a subscription.

integer

Number of units included in the charge.

number

Unit price of the product.

string

URL of the product image.

array

Fiscal invoices (NF-e / NFS-e) attached to this charge.

Show invoice fields

string

Invoice type (e.g. "nfe", "nfse").

string

Download URL for the invoice document.

array

Additional files attached to the charge (e.g. contracts, receipts).

Show file fields

string

Download URL for the file.

string

File name.

string

Arbitrary code snippet injected into the hosted charge page.

object

The pre-selected payment plan for this charge.

Complete JSON response

This example includes every response property defined for this operation in the OpenAPI schema.

{
  "id": "example-id",
  "gateway": "pagarme",
  "main_color": "string",
  "menus": {},
  "page_title": "string",
  "public_key": "-----BEGIN RSA PUBLIC KEY-----xxxxx-----END RSA PUBLIC KEY-----",
  "use_antifraud": true,
  "logo": "https://example.com/resource",
  "currency": "BRL",
  "date": "2026-08-25",
  "due_date": "2026-08-25",
  "retention": 123,
  "freight": 100.5,
  "enable_two_cards": true,
  "observation": "string",
  "customer": {
    "email": "customer@example.com",
    "name": "Example",
    "foreign": true,
    "identification": "12345678909",
    "social_reason": "string",
    "address": {
      "street": "string",
      "neighborhood": "string",
      "number": "string",
      "complement": "string",
      "zipcode": "01310100",
      "city": "string",
      "state": "SP"
    }
  },
  "coupon": {
    "code": "string",
    "discount": 100.5
  },
  "products": [
    {
      "id": 123,
      "name": "Example",
      "description": "string",
      "product_type": "string",
      "subscription": true,
      "quantity": 1,
      "value": 100.5,
      "image": "https://example.com/resource"
    }
  ],
  "invoices": [
    {
      "type": "string",
      "url": "https://example.com/resource"
    }
  ],
  "files": [
    {
      "url": "https://example.com/resource",
      "name": "Example"
    }
  ],
  "custom_code": {
    "example": "value"
  },
  "default_payment_plan": {
    "id": "example-id",
    "installments": 1,
    "payment_method": "string"
  }
}

Get the Belluno card hash key

Retrieve the RSA public key required to encrypt card data before paying a charge through Belluno.

GET /charges/{id}/card_hash_key

This endpoint is available only when the charge page uses the belluno gateway and its company has a configured Belluno integration.

Path parameters

string

required

The Order UID of the charge.

Response

Returns the Belluno CardHashKey object exactly as provided by Belluno.

integer

Identifier of the generated card hash key.

string

RSA public key in PEM format. Use it to encrypt card data in the client, then submit the resulting hash as the card token to POST /charges/{id}/pay.

string

ISO 8601 datetime when the key was created.

Example response

{
  "id": 123,
  "rsa_public_key": "-----BEGIN RSA PUBLIC KEY-----xxxxx-----END RSA PUBLIC KEY-----",
  "created_at": "2026-08-25T12:00:00Z"
}

Errors

Status	Meaning
`403`	The request origin is not allowed.
`404`	The charge was not found.
`422`	The page does not use Belluno, the company has no configured Belluno integration, or Belluno failed to return a key.

A 422 response contains an errors field as either a string or an array of strings.

Get the last payment for a charge

Returns the most recent active or failed payment attempt for a charge. This is useful for polling payment status without needing to manage a list of payment IDs.

GET /charges/{id}/last_payment

Path parameters

string

required

The Order UID of the charge.

Response

Returns a LastPayment object, or HTTP 204 No Content if no payment attempt has been made yet.

Example response

{
  "gateway_id": "pay_xyz789",
  "amount": 100.00,
  "interest": 0,
  "paid_at": null,
  "status": "waiting_payment"
}

string

The payment identifier issued by the gateway.

number

The total amount of the payment attempt.

number

Late-payment interest added to the original charge amount (zero if paid on time or in advance).

string | null

ISO 8601 datetime at which the payment was confirmed. null if not yet paid.

string

Current payment status. Possible values: waiting_payment, paid, failed, cancelled, pending.

Pay a charge

Submit payment for a charge. You can pay using a credit card, Pix, or bank slip (boleto).

POST /charges/{id}/pay

Path parameters

string

required

The Order UID of the charge to pay.

Request body

string

required

The ID of the selected payment plan (e.g. "42-1"). Retrieve available plans from the Payment Plans endpoint.

string

Stripe PaymentMethod confirmation token ID. Required when the gateway is Stripe and the payment method is credit card.

string

Tokenised card data for the primary credit card.

string

ID of a saved card on file to use as the primary card.

string

Payment plan ID for the primary card (used in two-card splits).

number

Amount charged to the primary card (used in two-card splits).

string

Tokenised card data for the secondary credit card (two-card split).

string

ID of a saved card to use as the secondary card.

string

Payment plan ID for the secondary card.

number

Amount charged to the secondary card.

string

Free-text note to attach to this specific payment attempt.

object

Arbitrary key-value pairs attached to the payment for your own tracking.

Response

Returns a ChargePayResult object. Only the fields relevant to the chosen payment method are included.

The response shape differs by payment method. Always check which fields are present before accessing them.

string

The resulting payment status for credit card payments. Possible values:

Value	Description
`pending`	Payment is being processed.
`waiting_payment`	Awaiting payment confirmation from the gateway.
`paid`	Payment confirmed.
`cancelled`	Payment was cancelled.
`failed`	Payment attempt failed.
`waiting_cancellation`	Cancellation has been requested and is pending.

string

URL of the generated boleto PDF. Present only for bank_slip payments.

string

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

string

URL to the Pix QR code image. Present only for pix payments.

string

ISO 8601 datetime when the Pix QR code expires. Present only for pix payments.

string

URL to redirect the customer to after payment (e.g. a confirmation or thank-you page).

Checkout

Payments

Management

Webhooks

Charges API — Pay Invoice and Charge Link Endpoints

Retrieve a charge

Path parameters

Response

Complete JSON response

Get the Belluno card hash key

Path parameters

Response

Errors

Get the last payment for a charge

Path parameters

Response

Pay a charge

Path parameters

Request body

Response