Skip to main content
Um Checkout Link (chk_) é um template de cobrança reutilizável. Você define uma vez os itens, o preço, os métodos e o branding, e divulga a URL quantas vezes quiser — cada acesso de comprador materializa uma Session independente. É o formato para link na bio, página de captura ou qualquer divulgação em massa. Para cobrar uma pessoa uma vez, sem template, o caminho é a venda rápida.
Todas as rotas exigem o header x-api-key. Veja Autenticação. Os exemplos usam a base URL de sandbox https://api.sandbox.z2pay.com/v1, e a página hospedada de sandbox é https://pay.sandbox.z2pay.com.

​
Endpoints

Cada endpoint tem sua própria página, com os campos aceitos, exemplos e o playground para testar.
O Link é o molde; a Session (cs_) é a compra. Quando um comprador abre a URL — ou quando você cria uma venda rápida — a Z2Pay materializa uma Session com o valor congelado e um estado que avança conforme ele interage. O snapshot é imutável. Itens, preço, splits, branding e métodos são copiados para a Session no momento em que ela nasce. Editar o Link depois não alcança Sessions já criadas: o comprador paga exatamente o que viu quando abriu a página. Em Session que veio de um Link, linkId aponta para o template de origem; em Session de venda rápida, linkId é null. Nos dois casos, transactionId liga a Session ao pagamento — e é preenchido quando ela entra em paying.
status: "active" não quer dizer que o Link vende. São dois campos independentes: status (active/archived) é decisão sua; sellable é decisão nossa — vira false quando alguém que precisa receber o dinheiro deixa de poder, seja um recebedor do splits ou o dono da conta, e volta a true sozinho quando o cadastro é regularizado.A combinação que engana é active + sellable: false: você não arquivou nada, e quem abrir a URL vê “checkout temporariamente indisponível”. Nenhuma Session nova nasce e o pagamento é recusado. Um painel que mostra “no ar” olhando só o status vai mentir no dia em que um parceiro do split for reprovado no cadastro — confira os dois.O motivo do bloqueio não é devolvido: ele fala do estado cadastral de terceiros. O que a API responde é o fato — vende ou não vende.

​
Estados da Session

O caminho feliz é created → opened → filling → paying → paid.
Expirar não alcança quem está pagando. Sessions em paying ou partially_paid nunca são expiradas pelo processo automático — quem está no meio de um pagamento não perde a compra por tempo. Os demais estados não-terminais expiram ao atingir expiresAt.
partially_paid e paying → opened são exclusivos do combinado. Em pagamento por um método só, a Session vai direto de paying para paid ou failed. A volta para opened acontece quando os cartões falham mas o Pix ou o boleto seguem pendentes, devolvendo o comprador à página para tentar outra composição.
Duas requisições não confirmam a mesma Session. Toda transição é protegida por controle de concorrência: se duas chegarem juntas, só uma vence — a outra recebe session_already_processing ou invalid_status_transition. O contador que faz esse controle é interno e não sai na resposta.

​
Assinaturas via Checkout

Um Link com mode: "subscription" vende uma assinatura recorrente: o comprador paga a primeira cobrança na página hospedada e a Z2Pay ativa a assinatura sozinha. O modelo de planos, ciclos e faturas está em Assinaturas. Cinco regras que nenhum schema expressa:
  • mode e o objeto subscription andam juntos — enviar um sem o outro é recusado.
  • Pagamento combinado não vale aqui — paymentMethods.combined.enabled é recusado em Link de assinatura. Pelo menos um método precisa estar habilitado.
  • Só por Link — a venda rápida recusa mode: "subscription". Recorrência não nasce de Session avulsa.
  • Adesão e trial se excluem — item com chargeType: "activation" e subscription.trialDays > 0 no mesmo Link é recusado. São opostos: a adesão cobra a mais no começo, o trial cobra a menos.
  • Com trial, só cartão — e para validá-lo o checkout faz uma cobrança de R$ 1,23 (123 centavos) estornada automaticamente. A assinatura nasce em trial, sem cobrança real até o fim do período.
A ativação é assíncrona. Depois do pagamento, a Z2Pay cria a assinatura aproveitando a cobrança já feita — a primeira fatura nasce paga, sem cobrar o comprador de novo — e a Session ganha subscriptionId (sub_).
Espere o subscriptionId antes de concluir que deu errado. A ativação leva alguns segundos, e se falhar o worker retenta sozinho a cada 60 segundos, até cinco vezes — cinco minutos no pior caso. Consulte a Session de novo em vez de tratar o campo nulo como erro.Passado esse prazo com subscriptionId ainda nulo, o motivo da falha fica em session.metadata.subscription_activation_error. A recuperação é manual: fale com o suporte com o cs_ em mãos.
A assinatura criada carrega a origem no metadata. Na ativação, a Z2Pay grava três chaves reservadas no metadata da assinatura — e elas saem em todos os eventos subscription.*, inclusive nos que não têm ação do comprador, como subscription.past_due e subscription.canceled: É o que permite reagir aos eventos sem guardar estado do seu lado: libere o acesso no transaction.paid — que traz additionalInfo.checkoutLinkId — e suspenda ou revogue no subscription.past_due / subscription.canceled usando o mesmo chk_, lido direto do evento. Como toda chave reservada, se o seu metadata definir uma homônima, o valor da Z2Pay prevalece.
O primeiro transaction.paid sai sem subscriptionId — ele dispara antes de a assinatura existir. Depois da ativação, a transação daquela compra ganha additionalInfo.subscriptionId (visível ao consultá-la e nos eventos posteriores dela, como estorno e chargeback). Para ligar venda e assinatura já no primeiro evento, ouça também subscription.created e correlacione pelo metadata.checkoutSessionId, que é igual ao referenceCode da transação. Das cobranças recorrentes em diante, os eventos transaction.* já saem com additionalInfo.subscriptionId.

​
Reconciliação

Você não define um código de referência no Checkout. Não existe campo referenceCode na criação de Link, venda rápida ou Session — o que você grava é metadata. Quem preenche o referenceCode da transação é a Z2Pay, com o id da Session (cs_...). Para reconciliar por webhook, não espere eventos checkout.session.* — eles são internos e não existem no catálogo. Use os eventos de transação: transaction.paid e transaction.refused. A correlação funciona pelos dois lados:
  • data.id (o txn_) é igual ao transactionId da Session; ou
  • data.referenceCode é igual ao id da Session.
Para saber de qual Link veio a venda, use data.additionalInfo.checkoutLinkId. O cs_ muda a cada comprador; o chk_ é o mesmo em todas as vendas do Link — é a chave para mapear “este checkout entrega tal produto” do seu lado. A chave é reservada: se o seu metadata definir uma checkoutLinkId, o valor da Z2Pay prevalece. Vendas sem Link (venda rápida, Session avulsa) não a trazem. O estorno da venda também a carrega: os eventos refund.* e as respostas de Reembolsos saem com additionalInfo.checkoutLinkId copiado da transação, então o estorno chega ao Link sem consulta extra. O metadata que você gravou na Session ou na venda rápida volta em data.additionalInfo, com as suas chaves no primeiro nível — o metadata do Link fica no Link e não é copiado para a transação. Os campos customizados preenchidos pelo comprador entram ali sob checkoutCustomFields, como um array de { key, label, type, value } — só os que foram respondidos.

​
Veja também

Visão geral do Checkout

Conceitos, casos de uso e mapa de endpoints.

Venda rápida

Cobrança individual, sem template.

Webhooks

Reconcilie por transaction.paid e transaction.refused.

Splits

O modelo de divisão entre recebedores.