Skip to main content
The Z2Pay Checkout is a hosted payment page (Z2Pay-hosted, in the style of Stripe Checkout / Mercado Pago Checkout Pro). You create the configuration via API — items, accepted methods, branding, splits — and receive a ready-to-use URL to hand off to the buyer. They complete the payment on a page served by Z2Pay (mobile-first, with your brand identity), and you receive webhooks throughout the entire lifecycle.
All examples in this section use the sandbox URLs (https://checkout-api.sandbox.z2pay.com for the API and https://pay.sandbox.z2pay.com for the page). In production, switch to https://checkout-api.z2pay.com and https://pay.z2pay.com.

​
What you do NOT need to implement

Payment page (UI)

The checkout interface is ours — responsive and branded with your identity.

Card tokenization (PCI)

Sensitive card data never touches your server.

PIX, boleto, and installments

All payment method logic is handled by us.

Routing between acquirers

Just register the gateway once in the dashboard.

​
Typical use cases

  • Online store — create a CheckoutSession per order and redirect the customer.
  • Shareable payment link (Instagram bio, post, WhatsApp) — create a CheckoutLink (persistent template) and share the URL. Each click generates a new CheckoutSession.
  • Individual charge — call /checkout/charges (quick ad-hoc sale) and send the URL directly via WhatsApp or email.
  • Marketplace — use splits to automatically distribute the amount among multiple recipients.

​
Core concepts

A concrete purchase attempt. It has a frozen amount (snapshot of the Link at creation time), a buyer (partial or complete), and a state that progresses: created → opened → paying → paid. IDs start with cs_ (48 hex chars = 192 bits of entropy, safe to expose in URLs).
When a Session is created from a Link, all data (items, price, splits, branding, methods) is copied. Editing the Link afterwards does not affect already-created Sessions. This ensures that what the buyer saw at the time of payment is exactly what they pay.
You are not required to create a Link first — you can create an “ad-hoc” Session (without a linkId), with all configuration inline. Useful for one-off or custom charges. Charges are a shortcut for this same flow, with a filtered listing that shows only Sessions without a linkId.
Every credential is tied to a tenant (your seller account). Listings are automatically filtered by tenant — you never see resources from another seller. IDs follow the prefix pattern: chk_ (Link), cs_ (Session), ci_ (item), cmed_ (media), rec_ (recipient for splits).

​
Endpoint map

All seller requests use the x-api-key header. See Authentication.

​
Seller resources (authenticated)

MethodRouteResourceWhat it does
POST/checkout/linksLinkCreates a billing template
GET/checkout/linksLinkLists templates (paginated)
GET/checkout/links/{id}LinkRetrieves a template by ID
PUT/checkout/links/{id}LinkUpdates a template
DELETE/checkout/links/{id}LinkArchives (soft-delete) a template
POST/checkout/sessionsSessionCreates a Session (from a Link or ad-hoc)
GET/checkout/sessionsSessionLists Sessions (paginated)
GET/checkout/sessions/{id}SessionRetrieves a Session by ID
GET/checkout/chargesChargeLists quick sales (ad-hoc Sessions)
POST/checkout/chargesChargeCreates a quick ad-hoc sale
GET/checkout/charges/{id}ChargeRetrieves a quick sale by ID
POST/checkout/charges/{id}/cancelChargeCancels a quick sale

​
Public endpoints (consumed by the buyer’s browser)

MethodRouteWhat it does
GET/public/checkout/{id}Retrieves the public config to render the page
POST/public/checkout/{id}/openedMarks the Session as “opened by the buyer”
POST/public/checkout/{id}/confirmConfirms payment (tokenId + buyer data)
You typically do not call the public endpoints — they are called by the Z2Pay payment page. They are documented in Buyer (public page) for transparency purposes, or in case you want to build a custom checkout on top of our API.

​
Quickstart

In 3 steps, from zero to your first payment.
1

Create a Checkout Link

curl -X POST https://checkout-api.sandbox.z2pay.com/checkout/links \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Curso de Backend",
    "items": [
      { "name": "Curso de Backend — vitalício", "quantity": 1, "unitAmount": 49900 }
    ],
    "paymentMethods": {
      "card":   { "enabled": true, "installments": { "maxInstallments": 12, "freeInstallments": 3 } },
      "pix":    { "enabled": true, "expiresIn": 3600 },
      "boleto": { "enabled": true, "dueDateDays": 3 }
    }
  }'
Response (201):
{
  "id": "chk_abc123...",
  "status": "active",
  "url": "https://pay.sandbox.z2pay.com/c/chk_abc123...",
  "createdAt": "2026-06-24T12:00:00.000Z"
}
unitAmount is an integer in cents: R$ 499.00 = 49900. Never send a float (499.00) — it will be rejected by validation.
2

Share the URL

The returned url (https://pay.sandbox.z2pay.com/c/chk_abc123...) is the payment link. It can be shared through any channel. Every time someone opens the link, a new CheckoutSession is materialized automatically.
3

Receive webhooks

Every relevant change (Session created, payment approved, etc.) triggers a webhook to the URL configured in the dashboard. See Webhooks for the complete catalog of checkout events.

​
Session states (summary)

created → opened → paying → paid          (terminal ✓)
                         → failed → opened  (retry allowed)
                         → expired         (terminal)
                → canceled                 (terminal)
State machine details are covered in Checkout Sessions.

​
See also

Checkout Links

Create and manage reusable billing templates.

Checkout Sessions

Purchase instances, states, and immutable snapshots.

Charges (quick sale)

Individual ad-hoc charge, without a Link.

Buyer (public page)

The endpoints consumed by the payment page.

Quickstart

Receive an end-to-end test payment.

Test cards

Approval and decline scenarios in the sandbox.