Checkout Sessions - Z2Pay Developers

A Checkout Session (cs_) is a concrete purchase instance. Unlike a Link (template), it has a frozen amount and a state that progresses as the buyer interacts. The id is 48 hex chars (192 bits of entropy), safe to expose in a URL.

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. Seller requests use the x-api-key header — see Authentication.

Endpoints

Method	Route	Description
`POST`	`/checkout/sessions`	Creates a Session (from a Link or ad-hoc)
`GET`	`/checkout/sessions`	Lists Sessions (paginated)
`GET`	`/checkout/sessions/{id}`	Fetches a Session by ID

To create ad-hoc Sessions with a separate listing (direct sale), see also Charges — the /checkout/charges shortcut.

Immutable snapshot

When creating a Session from a Link, all data (items, price, splits, branding, methods) is copied into the Session. Editing the Link afterwards does not affect Sessions already created. This ensures that what the buyer saw at the time of payment is exactly what they pay.

Create Session

POST /checkout/sessions

Accepts two forms, discriminated by the presence of the linkId field. Returns 201. Supports idempotency via the Idempotency-Key header (see Conventions).

Form A — from a Link

Materializes the Session by copying the Link’s snapshot.

linkId

string

required

ID of the CheckoutLink (chk_*). The presence of this field discriminates the body as “from a Link”.

customer

object

Pre-fills the buyer’s data. See Customer.

metadata

object

Metadata specific to this Session (overrides the Link’s metadata).

curl -X POST https://checkout-api.sandbox.z2pay.com/checkout/sessions \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -d '{
    "linkId": "chk_abc123...",
    "customer": {
      "name": "João Silva",
      "email": "joao@example.com",
      "document": "12345678900",
      "documentType": "cpf"
    },
    "metadata": { "order_id": "ord_42", "shop": "loja-principal" }
  }'

Form B — ad-hoc (without a Link)

Full body with inline config. Equivalent to the create Link body, with minor differences: no name/slug, with customer (pre-fills the buyer) and with description (displayed on the page).

curl -X POST https://checkout-api.sandbox.z2pay.com/checkout/sessions \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "payment",
    "currency": "BRL",
    "locale": "pt-BR",
    "items": [{ "name": "Pedido #1234", "quantity": 1, "unitAmount": 8500 }],
    "paymentMethods": {
      "card": { "enabled": true },
      "pix":  { "enabled": true }
    },
    "customer": { "email": "joao@example.com" },
    "successUrl": "https://meu-site.com/obrigado",
    "expirationMinutes": 30,
    "metadata": { "order_id": "ord_42" }
  }'

The config fields (items, paymentMethods, branding, splits, requiredFields, customFields, successUrl, cancelUrl, expirationMinutes) follow exactly the same schema as the Checkout Link.

Response (201):

{
  "id": "cs_a1b2c3d4...48hex",
  "tenantId": "ten_xyz...",
  "linkId": "chk_abc123...",
  "status": "created",
  "mode": "payment",
  "currency": "BRL",
  "locale": "pt-BR",
  "config": {
    "items": [{ "...": "..." }],
    "paymentMethods": { "...": "..." },
    "splits": null,
    "branding": { "...": "..." },
    "requiredFields": ["email", "document", "phone"],
    "customFields": [],
    "successUrl": "https://meu-site.com/obrigado",
    "cancelUrl": null
  },
  "customer": { "name": "João Silva", "email": "joao@example.com" },
  "subtotal": 8500,
  "discountTotal": 0,
  "amount": 8500,
  "discounts": null,
  "paymentAttempts": 0,
  "transactionId": null,
  "metadata": { "order_id": "ord_42" },
  "createdAt": "2026-06-24T12:00:00.000Z",
  "updatedAt": "2026-06-24T12:00:00.000Z",
  "openedAt": null,
  "paidAt": null,
  "canceledAt": null,
  "expiresAt": "2026-06-25T12:00:00.000Z",
  "deletedAt": null,
  "version": 0,
  "url": "https://pay.sandbox.z2pay.com/c/cs_a1b2c3d4..."
}

In ad-hoc Sessions, linkId is null. The returned url is ready to deliver to the buyer.

Common errors

HTTP	Code	When
`400`	`validation_failed`	Invalid body
`404`	`not_found`	`linkId` does not exist or has been archived
`409`	`link_not_active`	Link exists but is archived

See Errors for the full format.

Customer object

name

string

Full name (≤ 255 chars).

string

Email address (≤ 255 chars). Always required on confirm — see required fields.

document

string

CPF, CNPJ, or passport (6–30 chars; digits only for CPF/CNPJ).

documentType

string

"cpf", "cnpj", or "passport".

phone

string

Phone number (≤ 30 chars). E.164 recommended: +5511999999999.

address

object

Address (zipCode, street, number, complement, neighborhood, city, state, country default "BR"). Opt-in: only required if "address" is present in requiredFields.

List Sessions

GET /checkout/sessions

Paginated list of the tenant’s Sessions.

status

string

Filter by status (CSV). E.g.: ?status=paid,opened. Values: created, opened, paying, partially_paid, paid, failed, expired, canceled.

linkId

string

Filter Sessions from a specific Link.

string

Search by Session ID or buyer 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/sessions \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -d status=paid \
  -d page=1 \
  -d limit=20

Response (200): paginated object { data, total, page, limit }.

Fetch Session by ID

GET /checkout/sessions/{id}

Returns the full seller view (includes tenantId, metadata, transactionId).

curl https://checkout-api.sandbox.z2pay.com/checkout/sessions/cs_a1b2c3d4... \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

Possible statuses: 200 (found) · 404 (not found).

States and transitions

created → opened → paying → paid          (terminal ✓)
                         → failed → opened  (retry allowed)
                         → expired         (terminal)
                → expired                  (without reaching opened)
                → canceled                 (terminal)

opened  → expired                          (timeout without confirming)
        → canceled

Valid transitions table

From	To
`created`	`opened`, `expired`, `canceled`
`opened`	`paying`, `expired`, `canceled`
`paying`	`paid`, `partially_paid`, `failed`, `expired`
`partially_paid`	`paid`, `failed`
`failed`	`opened` (retry), `expired`, `canceled`
`paid`	— (terminal)
`expired`	— (terminal)
`canceled`	— (terminal)

Meaning of each state

State	Meaning
`created`	Session created (via API); the buyer has not yet opened the page
`opened`	Buyer opened the payment page
`paying`	Buyer clicked “Pay”; transaction being processed by the gateway
`partially_paid`	Combined payment: at least one payment confirmed, but the aggregate does not yet match `session.amount` (e.g., PIX paid, card pending)
`paid`	Payment confirmed. Webhook `checkout.session.payment_succeeded` fired
`failed`	Payment declined. The Session automatically returns to `opened` to allow a retry
`expired`	`expiresAt` reached without confirmation
`canceled`	Manual cancellation (via `POST /charges/{id}/cancel` or dashboard)

partially_paid is exclusive to the combined payment flow. In single-method payments, the Session goes directly from paying to paid or failed.

Every Session has a version field (integer) incremented on each transition (optimistic locking). If two threads attempt to confirm the same Session, only one wins; the other receives session_already_processing or invalid_status_transition. You normally do not need to worry about this.

Reconciliation

Every Session has a transactionId (populated after entering paying) that links the Session to the payment record in the PSP. Use transactionId to fetch processing details (gateway, NSU, authorization code, etc.) from the transactions API, if needed for financial reconciliation.

Checkout Overview

Concepts, use cases, and endpoint map.

Checkout Links

Reusable templates and full config schema.

Charges (quick sale)

Ad-hoc Sessions with separate listing and cancellation.

Buyer (public page)

How the Session progresses from created to paid.

Webhooks

Session state change events.

Errors

Error format and checkout domain codes.

​Endpoints

​Immutable snapshot

​Create Session

​Common errors

​Customer object

​List Sessions

​Fetch Session by ID

​States and transitions

​Valid transitions table

​Meaning of each state

​Reconciliation

​See also

Checkout Overview

Checkout Links

Charges (quick sale)

Buyer (public page)

Webhooks

Errors

Endpoints

Immutable snapshot

Create Session

Common errors

Customer object

List Sessions

Fetch Session by ID

States and transitions

Valid transitions table

Meaning of each state

Reconciliation

See also