Invoices - Z2Pay Developers

An invoice is the billing document generated for each subscription cycle. It accumulates line items (charged items), has a total amount in cents, and follows a lifecycle of statuses (scheduled → open → paid, with deviations to past_due, unpaid, canceled, and refunded). This API exposes invoice retrieval, administrative reconciliation actions (out-of-band payment and cancellation), and the hosted invoice page — the public link that an anonymous payer opens to pay via PIX, boleto, or card.

All authenticated endpoints use the x-api-key header (see Authentication). Endpoints under /public/invoices/* are public — the credential is possession of the high-entropy token generated when the invoice is issued. Monetary values are always integers in cents (e.g., 18990 = R$ 189.90).

Endpoints

Method	Route	Description
`GET`	`/invoices`	List invoices with filters and pagination
`GET`	`/invoices/:id`	Retrieve an invoice
`GET`	`/invoices/:id/line-items`	List the line items of an invoice
`POST`	`/admin/invoices/:id/mark-paid-out-of-band`	Reconcile a payment made outside the gateway
`POST`	`/admin/invoices/:id/void`	Cancel (void) an invoice before payment
`GET`	`/public/invoices/:token`	(Public) Retrieve the invoice for the hosted page
`POST`	`/public/invoices/:token/pay`	(Public) Generate the PIX/boleto slip
`POST`	`/public/invoices/:token/pay-card`	(Public) Charge the invoice with a tokenized card

Invoice statuses

The invoice status field follows this lifecycle:

Status	Meaning
`scheduled`	Created in advance; becomes active when `chargeAt` arrives (slip issuance deferred)
`suspended`	Frozen due to a subscription pause — outside the billing cycles
`open`	Active, awaiting payment (PIX/boleto slip already exists when applicable)
`paid`	Fully paid
`past_due`	Charge failed; undergoing retry (dunning)
`unpaid`	Retries exhausted — charge abandoned
`canceled`	Voided by the merchant before payment
`refunded`	Refunded after payment

Terminal statuses (paid, canceled, refunded, unpaid) reject cancellation actions. Out-of-band reconciliation only accepts invoices in open, past_due, or unpaid.

List invoices

status

string[]

Filter by one or more statuses. Accepts CSV (status=open,past_due) or repeated params (status=open&status=past_due). Values: scheduled, suspended, open, paid, past_due, unpaid, canceled, refunded.

subscriptionId

string

Filter invoices belonging to a specific subscription.

customerId

string

Filter invoices belonging to a specific customer.

paymentMethods

string[]

Filter by payment method (CSV or repeated). Values: card, pix, boleto, other.

string

Free-text search by customer name, email, document, or invoice code (prefix).

code

string

Partial search by the formatted invoice number (e.g., 2026-0007, 2026-, 42). Max 20 characters.

customer

string

Partial search by customer name, email, or document. Max 255 characters.

totalMin

integer

Minimum invoice total, in cents.

totalMax

integer

Maximum invoice total, in cents.

dateField

string

Date field to apply dateFrom/dateTo against. Values: issued, due, paid, created, charge.

dateFrom

string

Start of the date range. ISO 8601 with timezone (e.g., 2026-06-01T00:00:00-03:00) or a plain date (2026-06-01).

dateTo

string

End of the date range. Same format as dateFrom.

orderBy

string

Sort field. Values: createdAt (default), dueAt, code, customer, paidAt, value.

order

string

Sort direction: asc or desc (default).

page

integer

Pagination page number.

limit

integer

Items per page.

curl "https://billing-api.sandbox.z2pay.com/invoices?status=open,past_due&limit=20" \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

{
  "data": [
    {
      "id": "inv_7Hf2kLpQ9mWxYz",
      "number": { "year": 2026, "sequence": 7 },
      "customerId": "cust_3Kd8mNvB2pQr",
      "customerName": "Maria Souza",
      "customerEmail": "maria@exemplo.com",
      "currency": "BRL",
      "subscriptionId": "sub_9Lp4qWrT6yUi",
      "status": "open",
      "kind": "recurring",
      "chargeAt": "2026-06-20T09:00:00.000Z",
      "dueAt": "2026-06-25T00:00:00.000Z",
      "subtotal": 18990,
      "taxTotal": 0,
      "total": 18990,
      "amountPaid": 0,
      "amountRemaining": 18990,
      "amountRefunded": 0,
      "installments": 1,
      "createdAt": "2026-06-13T09:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 1
}

The exact pagination envelope format follows the API conventions — see Conventions.

Retrieve an invoice

string

required

Invoice ID (prefix inv_).

curl https://billing-api.sandbox.z2pay.com/invoices/inv_7Hf2kLpQ9mWxYz \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

The response is the invoice object. Main fields:

string

Invoice ID (inv_).

number

object

Invoice number: { year, sequence }. Unique and sequential per company/year.

status

string

Current status (see the status table).

kind

string

Invoice nature: enrollment (sign-up fee), recurring (regular cycle), or manual (one-off). Immutable.

customerId

string

Customer ID (cust_).

customerName

string | null

Customer name (snapshot).

customerEmail

string | null

Customer email (snapshot).

customerDocument

string | null

Customer document (snapshot).

currency

string

3-letter ISO currency code (e.g., BRL).

subscriptionId

string | null

Source subscription (sub_), when applicable.

chargeAt

string

When the invoice leaves scheduled and becomes payable. ISO 8601.

dueAt

string | null

Due date. ISO 8601.

issuedAt

string | null

Issue date. ISO 8601.

paidAt

string | null

Payment date. ISO 8601.

canceledAt

string | null

Cancellation date. ISO 8601.

subtotal

integer

Sum of line items, in cents.

taxTotal

integer

Total taxes, in cents.

total

integer

Total invoice amount, in cents.

amountPaid

integer

Amount already paid, in cents.

amountRemaining

integer

Remaining amount due, in cents.

amountRefunded

integer

Cumulative amount refunded, in cents.

installments

integer

Card installments for the charge (1–12; 1 = full payment).

periodStart

string | null

Start of the service period. Null for kind=manual. ISO 8601.

periodEnd

string | null

End of the service period. Null for kind=manual. ISO 8601.

createdAt

string

Creation date. ISO 8601.

updatedAt

string

Last updated date. ISO 8601.

Declared statuses for this endpoint:

200 — invoice found
404 — invoice not found

See Errors for the error response body format.

List line items

Returns the line items (billing lines) of an invoice.

string

required

Invoice ID (inv_).

curl https://billing-api.sandbox.z2pay.com/invoices/inv_7Hf2kLpQ9mWxYz/line-items \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

[
  {
    "id": "line_2Wq8xZ4mTnRb",
    "invoiceId": "inv_7Hf2kLpQ9mWxYz",
    "subscriptionId": "sub_9Lp4qWrT6yUi",
    "type": "subscription",
    "description": "Plano Pro - mensal",
    "quantity": 1,
    "unitAmount": 18990,
    "amount": 18990,
    "periodStart": "2026-06-25T00:00:00.000Z",
    "periodEnd": "2026-07-25T00:00:00.000Z",
    "createdAt": "2026-06-13T09:00:00.000Z"
  }
]

type

string

Item type: subscription, proration, one_time, or metered_usage.

quantity

integer

Quantity.

unitAmount

integer

Unit price, in cents.

amount

integer

Total amount for the item, in cents.

Reconcile an out-of-band payment

Marks the invoice as paid when payment was received outside the gateway (bank transfer, cash, check). Does not go through the gateway. Accepts invoices in open, past_due, or unpaid.

This endpoint lives under the /admin prefix. Use it only for real reconciliation — it transitions the invoice status without electronic charging.

This endpoint is idempotent: send the Idempotency-Key header to prevent reprocessing on retries. See Conventions.

string

required

Invoice ID (inv_).

amount

integer

required

Amount received, in cents. Positive integer.

method

string

default:"other"

Off-channel payment method: bank_transfer, cash, check, or other.

paidAt

string

Date and time of receipt, ISO 8601 in UTC (with Z suffix, e.g., 2026-06-22T17:30:00.000Z). Optional.

note

string

Free-form note (max 500 characters). Optional.

curl -X POST https://billing-api.sandbox.z2pay.com/admin/invoices/inv_7Hf2kLpQ9mWxYz/mark-paid-out-of-band \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Idempotency-Key: 5a9c1e2f-7b3d-4f8a-9c0e-1d2b3a4c5e6f" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 18990,
    "method": "bank_transfer",
    "paidAt": "2026-06-22T17:30:00.000Z",
    "note": "TED recebida em conta"
  }'

{
  "id": "inv_7Hf2kLpQ9mWxYz",
  "status": "paid",
  "amountPaid": 18990,
  "amountRemaining": 0,
  "paidAt": "2026-06-22T17:30:00.000Z"
}

Declared statuses:

200 — invoice updated (status=paid)
409 — invoice is in a terminal status (reconciliation not allowed)

Cancel (void) an invoice

Cancels an invoice before payment. Accepts scheduled, open, or past_due. Terminal statuses and unpaid are rejected. Both reason and reasonDetails are required. This endpoint is idempotent: send the Idempotency-Key header.

string

required

Invoice ID (inv_).

reason

string

required

Cancellation reason: duplicate, wrong_amount, customer_agreement, issued_by_mistake, or other.

reasonDetails

string

required

Reason details (1 to 500 characters).

curl -X POST https://billing-api.sandbox.z2pay.com/admin/invoices/inv_7Hf2kLpQ9mWxYz/void \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Idempotency-Key: 7c1b9d3e-2a4f-4c6b-8d0a-3e5f7a9b1c2d" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "issued_by_mistake",
    "reasonDetails": "Fatura emitida em duplicidade para o cliente"
  }'

{
  "id": "inv_7Hf2kLpQ9mWxYz",
  "status": "canceled",
  "canceledAt": "2026-06-22T18:00:00.000Z"
}

Declared statuses:

200 — invoice canceled (status=canceled)
409 — invoice is in a terminal/unpaid status (cancellation not allowed)

Hosted invoice page (public)

Instead of emailing a PIX/boleto slip (which expires), Z2Pay generates a hosted invoice link in the format /i/{token}. The anonymous payer opens the link and the slip is generated on demand. These endpoints do not use x-api-key — the credential is possession of the token (generated at issuance, high entropy). They are rate-limited to prevent abuse.

The token is the invoice’s public_access_token. The page polls the GET endpoint to display the slip and detect payment (the invoice transitions from open to paid).

Retrieve the invoice for payment

Returns the safe invoice data (without internal IDs or sensitive companyId) and the current slip, if already generated.

token

string

required

Public invoice token.

curl https://billing-api.sandbox.z2pay.com/public/invoices/itk_Qx8mZ2pL9vRtKwYn

{
  "number": { "year": 2026, "sequence": 7 },
  "status": "open",
  "currency": "BRL",
  "total": 18990,
  "amountRemaining": 18990,
  "dueAt": "2026-06-25T00:00:00.000Z",
  "customerName": "Maria S.",
  "lineItems": [
    {
      "id": "line_2Wq8xZ4mTnRb",
      "description": "Plano Pro - mensal",
      "quantity": 1,
      "unitAmount": 18990,
      "amount": 18990
    }
  ],
  "slip": null,
  "allowedPaymentMethods": ["pix", "boleto"],
  "installmentsConfig": null,
  "companyId": "comp_4Tn7yWx2mKpQ"
}

slip

object | null

Slip for the pending charge attempt. null while not yet generated. When present, contains paymentMethod, status, pixUrl, pixCopyPaste, boletoUrl, boletoDigitableLine, boletoBarcode, and expiresAt.

allowedPaymentMethods

string[] | null

Methods allowed for this invoice. null = no restriction (the page decides based on the subscription’s default method).

installmentsConfig

object | null

Card installment configuration: { maxInstallments, freeInstallments?, interestRate? }. null = full payment only.

companyId

string

Exposed to initialize the card tokenizer on the front end. See Tokenizer.

Declared statuses: 200 (invoice view), 404 (invalid token).

Generate the PIX/boleto slip

Ensures a valid slip for the invoice. The request body is optional: the method field forces PIX or boleto (among the allowed methods). Without method, the subscription’s default is used.

token

string

required

Public invoice token.

method

string

pix or boleto. Optional.

curl -X POST https://billing-api.sandbox.z2pay.com/public/invoices/itk_Qx8mZ2pL9vRtKwYn/pay \
  -H "Content-Type: application/json" \
  -d '{ "method": "pix" }'

The response has the same format as the GET above. The slip may take ~1–2s to appear (async persistence) — the page should keep polling the GET endpoint. Declared statuses: 200 (view, slip may not be populated yet), 404 (invalid token), 409 (method not allowed for this invoice).

Charge with a tokenized card

Charges the invoice with a card tokenized by the Tokenizer on the front end (can be a third-party card). Eager charge — the result is reflected in the GET on the next poll.

token

string

required

Public invoice token.

cardToken

string

required

Card token issued by the tokenizer.

installments

integer

Number of installments chosen by the payer (1 to 12; 1 = full payment). Optional.

curl -X POST https://billing-api.sandbox.z2pay.com/public/invoices/itk_Qx8mZ2pL9vRtKwYn/pay-card \
  -H "Content-Type: application/json" \
  -d '{
    "cardToken": "card_5Pm9xQ2wL8vTnRb",
    "installments": 3
  }'

The response is the updated invoice view. Declared statuses: 200 (updated view), 404 (invalid token), 409 (card not allowed or invoice not payable).

To test the payment flow in the sandbox, use the test cards and PIX/boleto data, and simulate outcomes via Simulate.

Actions available in the dashboard

Some invoice operations — create a one-off invoice, generate a payment link, reschedule, and force a new charge (retry) — are performed through the merchant dashboard (user session) and are not exposed in the public API via x-api-key. The payloads below document these data shapes for reference.

Create a one-off invoice (manual)

Creates an ad-hoc charge tied to a subscription, outside the recurring cycle. Body:

subscriptionId (string, required)
description (string, 1–200, required)
amount (integer in cents, positive, required) — unit price
quantity (positive integer, default 1)
dueAt (ISO 8601, required, strictly in the future)
reason (required): extra_service, adjustment, penalty, ad_hoc, or other
reasonDetails (string, 1–500, required)
allowedPaymentMethods (array of card/pix/boleto, 1–3 items, optional) — methods offered on the hosted page
installmentsConfig (object, optional/null): { maxInstallments (1-12), freeInstallments? (1-12), interestRate? (0-100) }. freeInstallments cannot exceed maxInstallments.

A one-off invoice is created with kind=manual, without a service period (periodStart/periodEnd are null).

Generate a payment link

Transitions a scheduled invoice to open before its chargeAt and makes the hosted page link available. No charge is executed — the payer chooses the method when opening the link. Body:

methods (array of card/pix/boleto, 1–3 items, required) — methods offered on the page
installmentsConfig (object, optional/null, same shape as the one-off invoice)

Reschedule an invoice

Changes the charge date (chargeAt) of a scheduled invoice. The dueAt shifts by the same interval. Body:

chargeAt (ISO 8601, required)

Force a new charge (retry)

Triggers a new charge attempt on an open/past_due invoice without waiting for the dunning cycle. No body required. See Cycles.

Subscriptions

Create and manage the contracts that generate invoices.

Billing cycles

How each cycle issues an invoice and the dunning flow.

Plans and pricing

Define the values that make up invoice line items.

Tokenizer

Tokenize cards on the front end for the hosted invoice page.

​Endpoints

​Invoice statuses

​List invoices

​Retrieve an invoice

​List line items

​Reconcile an out-of-band payment

​Cancel (void) an invoice

​Hosted invoice page (public)

​Retrieve the invoice for payment

​Generate the PIX/boleto slip

​Charge with a tokenized card

​Actions available in the dashboard

​See also

Subscriptions

Billing cycles

Plans and pricing

Tokenizer

Endpoints

Invoice statuses

List invoices

Retrieve an invoice

List line items

Reconcile an out-of-band payment

Cancel (void) an invoice

Hosted invoice page (public)

Retrieve the invoice for payment

Generate the PIX/boleto slip

Charge with a tokenized card

Actions available in the dashboard

See also