> ## Documentation Index
> Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Criar session
> Cria uma Session já materializada a partir de um Link — opcionalmente com os dados do comprador pré-preenchidos, para levar seu usuário direto ao pagamento.
`POST /checkout/sessions`
Faz parte do recurso [Links](/pt-BR/checkout/links) — o que é uma Session e os estados dela estão
lá.
Cria uma **Session** server-to-server, já materializada e pronta para pagar. Diferente do fluxo público — em que a própria página do comprador materializa a Session quando ele abre o Link — aqui **você** cria a Session pela API e recebe de volta a `url` da página de pagamento para redirecionar o comprador.
O body aceita **duas formas** (`oneOf`):
* **A partir de um Link** (`linkId`): materializa uma Session reusando toda a configuração do Link `chk_*` (itens, valor, métodos de pagamento, branding, splits). É a forma recomendada quando você já tem um Link.
* **Ad-hoc** (body completo): cria uma Session sem Link, informando `items` + `paymentMethods` na própria requisição.
Em ambas, o objeto **`customer` é opcional** e serve para **pré-preencher** os dados do comprador.
**Com `linkId`, o resto do corpo é ignorado — sem erro.** A forma a partir do Link aceita
exatamente três campos: `linkId`, `customer` e `metadata`. Mandar `items`, `paymentMethods` ou
`branding` junto não altera nada e **não** responde `400`: a configuração vem toda do Link, e o
excedente é descartado em silêncio.
Se você precisa de itens ou métodos diferentes dos do Link, é a forma ad-hoc — sem `linkId`, com
a configuração inteira no corpo.
Endpoint idempotente. Envie `Idempotency-Key` para que um retry por timeout não crie duas Sessions
— sem ele, a segunda chamada gera outra `cs_` e outra URL de pagamento. Veja
[Convenções](/pt-BR/convencoes#idempot%C3%AAncia).
## Por que usar: pré-preencher e reduzir atrito
O caso clássico é uma plataforma **SaaS** com usuário logado — você **já conhece** os dados dele (nome, e-mail, documento…). Em vez de mandá-lo para o checkout e pedir que digite tudo de novo, você cria a Session com o `customer` preenchido e o **redireciona direto para o pagamento**. Na prática, é como se o comprador tivesse aberto a página e já tivesse preenchido o formulário — só que essa etapa é pulada.
Você já tem os dados dele no seu banco.
`POST /checkout/sessions` com o `linkId` do Link e o `customer` pré-preenchido. A resposta traz o `id` (`cs_*`) e a `url`.
O comprador chega na página de pagamento **com os campos já preenchidos** — menos atrito, menos abandono.
O `customer` é **pré-preenchimento**, não trava: o comprador ainda pode corrigir os dados na página. Os `requiredFields` do Link continuam valendo no confirm.
## Exemplo
```bash theme={null}
curl -X POST https://api.sandbox.z2pay.com/v1/checkout/sessions \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
-H "Content-Type: application/json" \
-d '{
"linkId": "chk_my2vr53qlp0yc7usqztta5ynn",
"customer": {
"name": "João Silva",
"email": "joao@example.com",
"document": "12345678900",
"documentType": "cpf",
"phone": "+5511999999999"
}
}'
```
```json Resposta 201 theme={null}
{
"id": "cs_50b0abc54b632e7c57de3a73815413ace1d545dcd16da95c",
"linkId": "chk_my2vr53qlp0yc7usqztta5ynn",
"status": "created",
"amount": 8500,
"currency": "BRL",
"customer": {
"name": "João Silva",
"email": "joao@example.com",
"document": "12345678900",
"documentType": "cpf",
"phone": "+5511999999999"
},
"url": "https://pay.sandbox.z2pay.com/c/cs_50b0abc54b632e7c57de3a73815413ace1d545dcd16da95c",
"expiresAt": "2026-07-09T12:00:00.000Z"
}
```
Em seguida, **redirecione o comprador para `url`**. Em produção, troque o host por `https://api.z2pay.com/v1`.
Autenticação por `x-api-key` (server-side) — nunca exponha a chave no navegador. É o oposto do fluxo do comprador, que é público e autenticado pela posse do `cs_*`.
## OpenAPI
````yaml openapi/checkout.json POST /checkout/sessions
openapi: 3.0.3
info:
title: Z2Pay Checkout API
version: 1.0.0
description: >-
API pública dedicada do Checkout. Autenticação via header x-api-key com a
API key unificada da conta (z2_{live|test}_{sk|pk}_...). Endpoints privados
exigem uma key secret (sk); endpoints públicos aceitam a key publishable
(pk) consumida pelo frontend do comprador.
servers:
- url: https://api.sandbox.z2pay.com/v1
description: Sandbox
- url: https://api.z2pay.com/v1
description: Produção
security: []
tags:
- name: Checkout Links
description: Checkout Links (integração API via sk_)
- name: Checkout Sessions
description: Checkout Sessions (integração API via sk_)
- name: Vendas rápidas
description: Cobrança individual sem Link — Sessions ad-hoc criadas com a chave secreta
paths:
/checkout/sessions:
post:
tags:
- Checkout Sessions
summary: Criar checkout session
description: >-
Cria uma Session. Se `linkId` estiver presente, materializa a partir do
Link; senão, cria ad-hoc com os dados do body.
operationId: CheckoutSessionApiController_create
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- type: object
properties:
linkId:
type: string
minLength: 1
description: ID do Link (chk_*) a materializar em Session.
customer:
type: object
properties:
name:
type: string
maxLength: 255
description: Nome completo do cliente.
email:
type: string
format: email
maxLength: 255
description: E-mail do cliente.
document:
type: string
minLength: 6
maxLength: 30
description: Documento do cliente (CPF ou CNPJ, somente dígitos).
documentType:
type: string
enum:
- cpf
- cnpj
- passport
description: 'Tipo do documento do cliente: cpf ou cnpj.'
phone:
type: string
maxLength: 30
description: >-
Telefone do cliente (formato E.164, ex.:
+5511987654321).
address:
type: object
properties:
zipCode:
type: string
minLength: 3
maxLength: 20
description: CEP / código postal (somente dígitos).
street:
type: string
maxLength: 255
description: Logradouro (rua, avenida).
number:
type: string
maxLength: 20
description: Número do endereço.
complement:
type: string
maxLength: 255
description: >-
Complemento do endereço (apartamento, bloco,
sala).
neighborhood:
type: string
maxLength: 100
description: Bairro.
city:
type: string
maxLength: 100
description: Cidade.
state:
type: string
maxLength: 100
description: 'Estado ou UF (ex.: SP).'
country:
type: string
default: BR
description: 'País (código ISO 3166-1 alfa-2, ex.: BR).'
description: Pré-preenchimento dos dados do comprador.
metadata:
type: object
additionalProperties:
type: string
description: >-
Metadados do seller (string → string); propagados ao
additionalInfo da Transaction e dos webhooks.
required:
- linkId
- type: object
properties:
mode:
type: string
enum:
- payment
- subscription
default: payment
description: >-
Apenas 'payment' é aceito na venda rápida ad-hoc —
'subscription' é rejeitado (recorrência exige Link).
currency:
type: string
enum:
- BRL
default: BRL
description: >-
Moeda da cobrança. Só `BRL` — os gateways liquidam em
real.
locale:
type: string
enum:
- pt-BR
- en-US
- es-ES
default: pt-BR
description: Idioma do checkout (default 'pt-BR').
items:
type: array
items:
type: object
properties:
name:
type: string
minLength: 1
maxLength: 255
description: Nome do item exibido no checkout.
description:
type: string
maxLength: 2000
description: Descrição do item.
imageUrl:
type: string
format: uri
maxLength: 2000
description: URL da imagem do item.
quantity:
type: integer
minimum: 1
description: Quantidade do item (inteiro ≥ 1).
unitAmount:
type: integer
minimum: 1
description: Preço UNITÁRIO do item, em centavos (inteiro ≥ 1).
chargeType:
type: string
enum:
- one_time
- recurring
- activation
description: >-
Eixo de cobrança da linha: ausente/'one_time' em
pagamento único; 'recurring'/'activation' espelham
PlanItem.kind em mode=subscription.
metadata:
type: object
additionalProperties:
type: string
description: Metadados livres do item (string → string).
required:
- name
- quantity
- unitAmount
minItems: 1
description: >-
Itens da cobrança (unitAmount em centavos); ao menos 1 é
obrigatório.
paymentMethods:
type: object
properties:
card:
type: object
properties:
enabled:
type: boolean
installments:
type: object
properties:
maxInstallments:
type: integer
minimum: 1
maximum: 12
freeInstallments:
type: integer
minimum: 0
maximum: 12
interestRate:
type: number
minimum: 0
maximum: 100
interestType:
type: string
enum:
- simple
- compound
default: compound
required:
- maxInstallments
threeDSecure:
type: boolean
description: >-
Liga a autenticação 3D Secure para os pagamentos
com cartão deste checkout. Aceita `true` ou
`false`; default `false` (sem desafio). Exige
3DS habilitado para a conta — sem a habilitação
o campo é aceito e ignorado (nenhum erro, nenhum
desafio); se a conta for habilitada depois, os
checkouts com `true` passam a desafiar
automaticamente.
required:
- enabled
pix:
type: object
properties:
enabled:
type: boolean
expiresIn:
type: integer
minimum: 60
maximum: 86400
required:
- enabled
boleto:
type: object
properties:
enabled:
type: boolean
dueDateDays:
type: integer
minimum: 1
maximum: 30
required:
- enabled
combined:
type: object
properties:
enabled:
type: boolean
minAmountPerPayment:
type: integer
minimum: 1
maxPaymentsCount:
type: integer
minimum: 2
maximum: 8
required:
- enabled
description: >-
Métodos de pagamento habilitados
(card/pix/boleto/combined); ao menos um enabled.
splits:
type: array
items:
type: object
properties:
recipientId:
type: string
minLength: 1
description: Recebedor (`rec_`) que fica com esta fatia.
percentage:
type: number
minimum: 0.01
maximum: 100
description: >-
Fatia do valor total, em porcentagem. Aceita
decimais (`33.33`).
liable:
type: boolean
description: >-
Marca o recebedor como responsável por
chargebacks. Exatamente um split do array precisa
ter `true` — nenhum ou mais de um é recusado.
required:
- recipientId
- percentage
description: >-
Divisão de receita por percentual; a soma deve ser
exatamente 100.
branding:
type: object
properties:
primaryColor:
type: string
pattern: ^#([0-9a-f]{6}|[0-9a-f]{3})$
description: 'Cor primária do checkout em hex (#RRGGBB ou #RGB).'
logoUrl:
type: string
format: uri
maxLength: 2000
description: URL do logo exibido no checkout.
merchantName:
type: string
maxLength: 100
description: Nome do vendedor exibido no checkout (≤ 100 chars).
mobileLayout:
type: string
enum:
- single-page
- step-by-step
description: 'Layout no mobile: ''single-page'' ou ''step-by-step''.'
faviconUrl:
type: string
format: uri
maxLength: 2000
description: URL do favicon da página de checkout.
coverUrl:
type: string
format: uri
maxLength: 2000
description: URL da imagem de capa do checkout.
description: Customização visual do checkout.
customer:
type: object
properties:
name:
type: string
maxLength: 255
description: Nome completo do cliente.
email:
type: string
format: email
maxLength: 255
description: E-mail do cliente.
document:
type: string
minLength: 6
maxLength: 30
description: Documento do cliente (CPF ou CNPJ, somente dígitos).
documentType:
type: string
enum:
- cpf
- cnpj
- passport
description: 'Tipo do documento do cliente: cpf ou cnpj.'
phone:
type: string
maxLength: 30
description: >-
Telefone do cliente (formato E.164, ex.:
+5511987654321).
address:
type: object
properties:
zipCode:
type: string
minLength: 3
maxLength: 20
description: CEP / código postal (somente dígitos).
street:
type: string
maxLength: 255
description: Logradouro (rua, avenida).
number:
type: string
maxLength: 20
description: Número do endereço.
complement:
type: string
maxLength: 255
description: >-
Complemento do endereço (apartamento, bloco,
sala).
neighborhood:
type: string
maxLength: 100
description: Bairro.
city:
type: string
maxLength: 100
description: Cidade.
state:
type: string
maxLength: 100
description: 'Estado ou UF (ex.: SP).'
country:
type: string
default: BR
description: 'País (código ISO 3166-1 alfa-2, ex.: BR).'
description: Pré-preenchimento dos dados do comprador.
requiredFields:
type: array
items:
type: string
enum:
- email
- document
- phone
- address
description: >-
Campos do comprador exigidos no checkout (email,
document, phone, address).
customFields:
type: array
items:
type: object
properties:
key:
type: string
pattern: ^[a-z][a-z0-9_]*$
maxLength: 50
label:
oneOf:
- type: string
minLength: 1
maxLength: 200
- type: object
additionalProperties:
type: string
minLength: 1
maxLength: 200
type:
type: string
enum:
- text
- select
- checkbox
options:
type: array
items:
oneOf:
- type: string
maxLength: 100
- type: object
properties:
value:
type: string
maxLength: 100
label:
oneOf:
- type: string
minLength: 1
maxLength: 200
- type: object
additionalProperties:
type: string
minLength: 1
maxLength: 200
required:
- value
- label
required:
type: boolean
required:
- key
- label
- type
maxItems: 20
description: Campos customizados do formulário (máx. 20).
successUrl:
type: string
format: uri
maxLength: 2000
description: URL de redirecionamento após pagamento aprovado.
cancelUrl:
type: string
format: uri
maxLength: 2000
description: URL de redirecionamento quando o comprador cancela.
description:
type: string
maxLength: 2000
description: Descrição da venda rápida (exibida na listagem).
metadata:
type: object
additionalProperties:
type: string
description: >-
Metadados do seller (string → string); propagados ao
additionalInfo da Transaction e dos webhooks.
expirationMinutes:
type: integer
minimum: 5
maximum: 43200
description: Expiração da sessão em minutos (5 a 43200 = 30 dias).
required:
- items
- paymentMethods
responses:
'201':
description: Session criada
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: Identificador único do registro.
linkId:
type: string
nullable: true
description: >-
Identificador do link de checkout que originou o registro;
nulo em sessões ad-hoc.
status:
type: string
description: Estado atual do registro.
mode:
type: string
description: >-
Modo do checkout: 'payment' (pagamento único) ou
'subscription' (assinatura).
currency:
type: string
description: 'Moeda no padrão ISO 4217 (ex.: BRL).'
locale:
type: string
description: 'Idioma do checkout (ex.: pt-BR, en-US, es-ES).'
config:
type: object
description: >-
Snapshot da configuração do checkout (formas de pagamento,
itens e personalização visual).
customer:
type: object
nullable: true
description: >-
Dados do comprador (nome, e-mail, documento e demais
informações).
customFieldValues:
type: object
nullable: true
description: >-
Valores preenchidos nos campos personalizados, indexados
pela key de cada campo.
paymentMethodSelected:
type: string
nullable: true
description: >-
Forma de pagamento selecionada pelo comprador na sessão
(ex.: credit_card, pix, boleto).
subtotal:
type: integer
description: Soma dos itens antes dos descontos, em centavos.
discountTotal:
type: integer
description: Total de descontos aplicados, em centavos.
amount:
type: integer
description: Valor total a ser cobrado, em centavos.
discounts:
type: array
items:
type: object
nullable: true
description: Descontos aplicados ao valor da sessão.
paymentAttempts:
type: integer
description: >-
Quantidade de tentativas de pagamento realizadas na
sessão.
transactionId:
type: string
nullable: true
description: >-
Identificador da transação gerada pelo pagamento da
sessão; nulo até haver pagamento.
subscriptionId:
type: string
nullable: true
description: >-
Identificador da assinatura criada a partir da sessão;
nulo até a ativação.
metadata:
type: object
nullable: true
description: >-
Metadados livres (pares chave-valor) para uso do
integrador; não afeta o processamento.
createdAt:
type: string
format: date-time
description: Data e hora de criação do registro (ISO 8601).
updatedAt:
type: string
format: date-time
description: Data e hora da última atualização do registro (ISO 8601).
openedAt:
type: string
format: date-time
nullable: true
description: >-
Data e hora em que a sessão foi aberta pelo comprador (ISO
8601); nula se ainda não aberta.
paidAt:
type: string
format: date-time
nullable: true
description: >-
Data e hora em que o pagamento foi confirmado (ISO 8601);
nula se não pago.
canceledAt:
type: string
format: date-time
nullable: true
description: >-
Data e hora do cancelamento (ISO 8601); nula se não
cancelado.
expiresAt:
type: string
format: date-time
description: Data e hora de expiração (ISO 8601).
url:
type: string
description: >-
URL pública do checkout para o comprador finalizar o
pagamento.
example:
id: cs_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
linkId: chk_byd8p3p79re859jpkmr0j65n3
status: created
mode: payment
currency: BRL
locale: pt-BR
config:
paymentMethods:
card:
enabled: true
pix:
enabled: true
successUrl: https://academia.com/obrigado
customer:
name: João Silva
email: joao@example.com
customFieldValues: null
paymentMethodSelected: null
subtotal: 49700
discountTotal: 0
amount: 49700
discounts: null
paymentAttempts: 0
transactionId: null
subscriptionId: null
metadata:
source: api
createdAt: '2025-06-29T13:45:30.000Z'
updatedAt: '2025-06-29T13:45:30.000Z'
openedAt: null
paidAt: null
canceledAt: null
expiresAt: '2025-06-30T13:45:30.000Z'
url: >-
https://pay.z2pay.com/c/cs_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
'400':
description: >-
Requisição inválida — algum parâmetro ou campo do corpo não passou
na validação
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
issues:
type: array
description: >-
Um item por campo rejeitado. Nunca vem vazio: se há
400 de validação, há pelo menos um.
items:
type: object
properties:
path:
type: string
description: >-
Campo que falhou. Vem vazio quando o erro é do
corpo como um todo.
message:
type: string
description: O que há de errado com esse campo.
example:
error:
code: VALIDATION_ERROR
message: Validation failed
issues:
- path: status
message: >-
Status inválido. Valores aceitos: pending,
waiting_payment, paid, refused, canceled, refunded
- path: startDate
message: >-
Data deve ser ISO 8601 com timezone (ex.:
2026-06-24T00:00:00Z)
'401':
description: Chave de API ausente, malformada ou inválida
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: UNAUTHORIZED
message: Invalid API key
'403':
description: >-
A chave é válida, mas não tem permissão para esta operação — é o
caso de usar uma publishable key (pk) onde a rota exige uma secret
key (sk)
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: FORBIDDEN
message: Forbidden — insufficient permissions
'409':
description: >-
Já existe uma requisição em andamento com esta Idempotency-Key. A
API aguarda a primeira concluir por até 5 segundos antes de
responder assim
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: >-
Mensagem do conflito de idempotência. Aqui `error` é
texto, não objeto — ramifique pelo status HTTP.
example:
error: A request with this idempotency key is already being processed
'422':
description: >-
Idempotency-Key já usada com um corpo diferente. Use uma chave nova
para uma operação diferente
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: >-
Mensagem do conflito de idempotência. Aqui `error` é
texto, não objeto — ramifique pelo status HTTP.
example:
error: Idempotency key already used with a different request body
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: >-
API key unificada (z2_{live|test}_{sk|pk}_...) — secret (sk) para
integração backend, publishable (pk) para uso no frontend público
````