Skip to main content
POST
Criar venda rápida
POST /checkout/charges Faz parte do recurso Vendas rápidas — a relação com Link e Session está lá. Cria a compra com a configuração inline: itens, métodos, branding e splits vão no topo do corpo, com o mesmo formato que o Link aceita. A resposta é 201 com a Session (linkId: null) e a url para você enviar pelo seu canal. O objeto customer é opcional e serve para pré-preencher os dados na página — o comprador ainda pode corrigi-los, e os requiredFields continuam valendo na confirmação.
null explícito é recusado aqui. No Link, vários campos aceitam null; no corpo da venda rápida, não. Campo que você não vai usar deve ser omitido. É a diferença que mais derruba quem copia a configuração de um Link direto para cá — veja o clean() no exemplo abaixo.
Valores são inteiros em centavos, e o split exige soma 100 com exatamente um liable: true — as mesmas regras do Link. Veja Criar checkout link.
Endpoint idempotente. Envie Idempotency-Key para que um retry por timeout não crie duas cobranças — sem ele, a segunda chamada gera outro cs_ e outra URL. Veja Convenções.

​
Exemplo

Resposta 201

​
Cobrança agendada

Com scheduledAt (só em mode: "payment"), a venda combina uma data em vez de cobrar agora. O aceite do comprador não move dinheiro: a Session nasce com amount: 0, ele escolhe o método, e o que vence na data é uma fatura, devolvida em invoiceId assim que o aceite acontece. O que muda conforme o método que ele escolhe:
  • Cartão: o aceite valida o cartão com uma cobrança de R$ 1,23, estornada na hora, e guarda esse cartão na fatura. Na data, ela é cobrada sozinha.
  • PIX ou boleto: nada acontece no aceite. O link de pagamento chega ao comprador por e-mail antes do vencimento.
Três regras que o schema não expressa:
  • A data precisa de folga, contada pelo maior prazo entre os métodos habilitados: 1 dia no cartão, 2 no PIX, 3 no boleto. Data próxima demais é recusada — o link precisa chegar antes.
  • O link da venda expira na véspera da data. O que precisa acontecer a tempo é o aceite, não o pagamento.
  • Pagamento combinado não vale aqui, porque nada é cobrado no aceite.
A fatura nasce de forma assíncrona: por alguns segundos a venda fica paga com invoiceId nulo. Consulte de novo em vez de tratar o nulo como erro. Se a criação falhar, o motivo fica em metadata.scheduled_invoice_error — e o caso mais comum é a data já ter passado quando o comprador aceitou, que se resolve criando outra venda com data nova. Daí em diante quem manda é a fatura, com estados, régua de atraso e link próprios — veja Faturas. Esta venda não gera mais nenhum evento de checkout depois do aceite: o que acompanhar é a família invoice.*.

​
Assinatura na venda rápida

Com mode: "subscription" e subscriptionConfig, a venda rápida vende uma assinatura recorrente — um sem o outro é recusado. A diferença para o Link é a origem do preço: aqui você monta a recorrência na própria requisição, em vez de apontar para um plano publicado.
  • recurrence e currency são obrigatórios — sem plano, não há de onde herdar a cadência nem a moeda. planId é recusado.
  • As linhas vendidas ficam em items, cada uma com o seu chargeType: recurring para o que se repete a cada ciclo, activation para a adesão, cobrada uma vez no aceite.
  • Adesão e período de teste se excluem, e com trialDays o cartão precisa ser o único método habilitado — é ele que valida o cartão antes do primeiro ciclo.
  • startAt adia o início da recorrência, não a adesão, que continua cobrada no aceite. Não convive com período de teste nem com item avulso (um item sem chargeType nunca seria cobrado), e a data precisa da mesma folga mínima da cobrança agendada: 1 dia no cartão, 2 no PIX, 3 no boleto.
  • Pagamento combinado não vale em assinatura, e a âncora day_of_week ainda não é suportada.
A ativação é assíncrona: depois do pagamento a Session ganha o subscriptionId. O que fazer enquanto ele é nulo, e o que a Z2Pay grava no metadata da assinatura, está em Assinaturas via Checkout — vale igual aqui.
Já tem um Link com branding, métodos e splits ajustados e quer disparar uma cobrança individual com a mesma cara, mas com outro carrinho? Leia o Link, mova o config para o topo do corpo e poste aqui. É o mesmo caminho do “Duplicar como venda rápida” do painel.
A venda rápida resultante é independente: ela copia a configuração no momento da criação, não cria vínculo. Editar o Link depois não a alcança. Se você quer o vínculo vivo, compartilhe a URL do próprio Link.
1

Leia o Link

GET /checkout/links/{id}. A resposta traz items, paymentMethods, splits e branding dentro de config; o resto já vem no topo.
2

Mova o config para o topo

Os quatro campos aninhados sobem um nível. locale, currency, requiredFields, customFields, successUrl, cancelUrl, description, metadata e expirationMinutes são copiados direto.
3

Troque o que é seu

items vem do seu carrinho, não do Link. Omita name, slug e qualquer configuração de assinatura. Envie mode: "payment".
4

Poste

POST /checkout/charges → 201 com o cs_ e a url.
Quatro coisas não atravessam: name e slug (são identidade do template); qualquer null (omita em vez de enviar); chargeType recurring/activation nos itens — em pagamento único todo item é cobrança única; e o objeto subscription, que aqui se chama subscriptionConfig e não aceita planId (veja Assinatura na venda rápida).
As URLs de mídia (branding.logoUrl, faviconUrl, coverUrl e items[].imageUrl) copiam verbatim — são endereços públicos de CDN, sem novo upload.

Authorizations

​
x-api-key
string
header
required

API key unificada (z2_{live|test}{sk|pk}...) — secret (sk) para integração backend, publishable (pk) para uso no frontend público

Body

application/json
​
items
object[]
required

Itens da cobrança (unitAmount em centavos); ao menos 1 é obrigatório.

Minimum array length: 1
​
paymentMethods
object
required

Métodos de pagamento habilitados (card/pix/boleto/combined); ao menos um enabled.

​
mode
enum<string>
default:payment

'payment' (default) para cobrança única; 'subscription' para venda rápida recorrente — exige subscriptionConfig populado.

Available options:
payment,
subscription
​
currency
enum<string>
default:BRL

Moeda da cobrança. Só BRL — os gateways liquidam em real.

Available options:
BRL
​
locale
enum<string>
default:pt-BR

Idioma do checkout (default 'pt-BR').

Available options:
pt-BR,
en-US,
es-ES
​
splits
object[]

Divisão de receita por percentual; a soma deve ser exatamente 100.

​
branding
object

Customização visual do checkout.

​
subscriptionConfig
object

Configuração de assinatura; obrigatória (e exclusiva) quando mode='subscription'. Mesmo shape do subscription do Checkout Link — preço, cadência, ciclos e entrada opcional — exceto planId: assinatura a partir de plano publicado exige um Checkout Link.

​
scheduledAt
string<date-time>

Data de cobrança da venda rápida de pagamento único (ISO 8601 com offset), só com mode='payment'. Nada é cobrado no aceite: a Session nasce com amount: 0, o comprador escolhe o método e uma fatura vence nessa data — no cartão ela é cobrada sozinha (após validação de R$ 1,23, estornada); no PIX/boleto o link chega por e-mail antes do vencimento. Entre amanhã e +365 dias; a folga mínima segue o maior prazo entre os métodos habilitados (1 dia cartão, 2 PIX, 3 boleto). Incompatível com paymentMethods.combined. Não existe em Checkout Link.

​
customer
object

Pré-preenchimento dos dados do comprador.

​
requiredFields
enum<string>[]

Campos do comprador exigidos no checkout (email, document, phone, address).

Available options:
email,
document,
phone,
address
​
customFields
object[]

Campos customizados do formulário (máx. 20).

Maximum array length: 20
​
successUrl
string<uri>

URL de redirecionamento após pagamento aprovado.

Maximum string length: 2000
​
cancelUrl
string<uri>

URL de redirecionamento quando o comprador cancela.

Maximum string length: 2000
​
description
string

Descrição da venda rápida (exibida na listagem).

Maximum string length: 2000
​
metadata
object

Metadados do seller (string → string); propagados ao additionalInfo da Transaction e dos webhooks.

​
expirationMinutes
integer

Expiração da sessão em minutos (5 a 43200 = 30 dias).

Required range: 5 <= x <= 43200

Response

Venda rápida criada

​
id
string

Identificador único do registro.

​
linkId
string | null

Identificador do link de checkout que originou o registro; nulo em sessões ad-hoc.

​
status
string

Estado atual do registro.

​
mode
string

Modo do checkout: 'payment' (pagamento único) ou 'subscription' (assinatura).

​
currency
string

Moeda no padrão ISO 4217 (ex.: BRL).

​
locale
string

Idioma do checkout (ex.: pt-BR, en-US, es-ES).

​
config
object

Snapshot da configuração do checkout (formas de pagamento, itens e personalização visual).

​
customer
object | null

Dados do comprador (nome, e-mail, documento e demais informações).

​
customFieldValues
object | null

Valores preenchidos nos campos personalizados, indexados pela key de cada campo.

​
paymentMethodSelected
string | null

Forma de pagamento selecionada pelo comprador na sessão (ex.: credit_card, pix, boleto).

​
subtotal
integer

Soma dos itens antes dos descontos, em centavos.

​
discountTotal
integer

Total de descontos aplicados, em centavos.

​
amount
integer

Valor total a ser cobrado, em centavos.

​
discounts
object[] | null

Descontos aplicados ao valor da sessão.

​
paymentAttempts
integer

Quantidade de tentativas de pagamento realizadas na sessão.

​
transactionId
string | null

Identificador da transação gerada pelo pagamento da sessão; nulo até haver pagamento.

​
subscriptionId
string | null

Identificador da assinatura criada a partir da sessão; nulo até a ativação.

​
invoiceId
string | null

Fatura gerada pela venda com data de cobrança (scheduledAt), criada quando o comprador aceita. Nula em toda outra venda — pagamento no ato não gera fatura.

​
metadata
object | null

Metadados livres (pares chave-valor) para uso do integrador; não afeta o processamento.

​
createdAt
string<date-time>

Data e hora de criação do registro (ISO 8601).

​
updatedAt
string<date-time>

Data e hora da última atualização do registro (ISO 8601).

​
openedAt
string<date-time> | null

Data e hora em que a sessão foi aberta pelo comprador (ISO 8601); nula se ainda não aberta.

​
paidAt
string<date-time> | null

Data e hora em que o pagamento foi confirmado (ISO 8601); nula se não pago.

​
canceledAt
string<date-time> | null

Data e hora do cancelamento (ISO 8601); nula se não cancelado.

​
expiresAt
string<date-time>

Data e hora de expiração (ISO 8601).

​
url
string

URL pública do checkout para o comprador finalizar o pagamento.