Skip to main content
Charges are a shortcut for creating ad-hoc Sessions (without a Link). Use them when your use case is a one-off charge — a specific order, a standalone invoice — rather than a link shared at scale. Technically, /checkout/charges creates the same Checkout Sessions as /checkout/sessions ad-hoc, but the listing is filtered to show only Sessions without a linkId — keeping the dashboard clean for direct-sale flows. It also provides a dedicated cancellation endpoint.
The examples use the sandbox: API at https://checkout-api.sandbox.z2pay.com and page at https://pay.sandbox.z2pay.com. In production, use https://checkout-api.z2pay.com and https://pay.z2pay.com. Requests use the x-api-key header — see Authentication.

​
Endpoints

MethodRouteDescription
GET/checkout/chargesList quick sales (ad-hoc Sessions)
POST/checkout/chargesCreate a quick ad-hoc sale
GET/checkout/charges/{id}Fetch a quick sale by ID
POST/checkout/charges/{id}/cancelCancel a quick sale

​
Create a charge

POST /checkout/charges
Creates an ad-hoc Session with inline configuration. The request body is identical to POST /checkout/sessions in ad-hoc form — same schema for items, paymentMethods, branding, splits, customer, etc. Returns 201 with the created Session and a url ready to send. Supports idempotency via the Idempotency-Key header. 
curl -X POST https://checkout-api.sandbox.z2pay.com/checkout/charges \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -d '{
    "items": [{ "name": "Consultoria 1h", "quantity": 1, "unitAmount": 30000 }],
    "paymentMethods": { "pix": { "enabled": true } },
    "customer": { "name": "Cliente X", "email": "x@example.com" }
  }'
The response is a CheckoutSession (with linkId: null) and the url to share through your channel.

​
List charges

GET /checkout/charges
Paginated list of ad-hoc Sessions (without linkId) for the tenant.
​
status
string
Filter by status (CSV). Values: created, opened, paying, partially_paid, paid, failed, expired, canceled.
​
search
string
Search by Session ID or customer (name, email, document).
​
page
number
default:"1"
Page number (≥ 1).
​
limit
number
default:"20"
Items per page (1–100).
curl -G https://checkout-api.sandbox.z2pay.com/checkout/charges \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -d status=paid \
  -d page=1 \
  -d limit=20

​
Fetch a charge by ID

GET /checkout/charges/{id}
Identical to GET /checkout/sessions/{id} — returns the full view of the ad-hoc Session. 
curl https://checkout-api.sandbox.z2pay.com/checkout/charges/cs_a1b2c3d4... \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"
Possible statuses: 200 (found) · 404 (not found).

​
Cancel a charge

POST /checkout/charges/{id}/cancel
Moves the Session to canceled status. Allowed only if the current status is created, opened, or failed. Returns 200. Supports idempotency. 
curl -X POST https://checkout-api.sandbox.z2pay.com/checkout/charges/cs_a1b2c3d4.../cancel \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"
Possible statuses: 200 (canceled) · 404 (not found) · 409 (session_not_cancellable — current status does not allow cancellation, e.g. paid).
A Session that is already paid (paid) or being processed (paying) cannot be canceled. The attempt returns 409 session_not_cancellable. See Errors.

​
Example: recurring individual invoice

Common scenario: sending a monthly boleto invoice with a pre-filled customer and a long expiration window. 
{
  "mode": "payment",
  "currency": "BRL",
  "locale": "pt-BR",
  "items": [{ "name": "Cobrança fatura jan/2026", "quantity": 1, "unitAmount": 25000 }],
  "paymentMethods": { "boleto": { "enabled": true, "dueDateDays": 7 } },
  "customer": {
    "name": "João Silva",
    "email": "joao@example.com",
    "document": "12345678900",
    "documentType": "cpf"
  },
  "metadata": { "invoice_id": "inv_2026_01_joao" },
  "expirationMinutes": 10080
}
The customer details are pre-filled (the buyer does not need to type them again) and the Session expires in 7 days (10080 min). Send the url returned by your channel (email, WhatsApp).
For true recurring billing (plans, automatic renewal, system-generated invoices), see Subscriptions — Charges are for one-off invoices assembled by you.

​
See also

Checkout Sessions

The resource underneath Charges: states, schema, and listing.

Checkout Links

For mass distribution, a Link is the better fit.

Buyer (public page)

What happens when the buyer opens the url.

Errors

Error format and checkout domain codes.