PayZu GatewayCheckout

Assinar um plano pelo checkout


Nesta páginaLeia o plano públicoCrie a assinaturaConfirme a adesãoErros desta operação

Assine um cliente a um plano ativo numa página sua, com a chave de checkout no cabeçalho x-checkout-key, e leve-o à página de pagamento da fatura de adesão.

As rotas desta página dependem da Recorrência ativa na conta.

A chave de checkout de uma conta suspensa responde 401, como chave inválida.

Sem página própria, envie o cliente para a página de adesão da PayZu, na url do plano, que segue estes mesmos passos.

Leia o plano público

Passe no caminho o id do plano ou, com ?type=slug, o checkout.slug. Só o plano active aparece.

bash
curl "https://api.sandbox.payzu.dev/v1/checkout/plans/plan_oOsn4Cs4eayZ3LoytwzErn" \
  -H "x-checkout-key: SUA_CHAVE_DE_CHECKOUT"

Referência: Consultar um plano pela página

CampoO que traz
payment_settings.accepted_methodsSó os meios do plano que a sua conta pode cobrar. credit_card também sai quando recurrence não é monthly nem annual.
discountVem só quando o desconto do plano está ativo. Mostre discount.public_description ao cliente.

Crie a assinatura

A chamada cria a assinatura e a fatura de adesão, sem cobrar. O cliente paga a adesão depois, na página da fatura.

bash
curl -X POST https://api.sandbox.payzu.dev/v1/checkout/subscriptions \
  -H "x-checkout-key: SUA_CHAVE_DE_CHECKOUT" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "credit_card",
    "customer": {
      "name": "Maria Souza",
      "email": "maria@exemplo.com.br",
      "phone": "11987654321",
      "birthdate": "1990-05-20",
      "document": "52998224725",
      "document_type": "cpf",
      "address": {
        "street": "Avenida Paulista",
        "number": "1000",
        "complement": "Sala 12",
        "district": "Bela Vista",
        "city": "São Paulo",
        "state": "SP",
        "zip_code": "01310100",
        "country": "BR"
      }
    },
    "plan_id": "plan_oOsn4Cs4eayZ3LoytwzErn"
  }'

Referência: Criar uma assinatura pela página

CampoRegra
payment_methodcredit_card ou pix, um dos meios em payment_settings.accepted_methods do plano.
customerQuem assina, com os campos de Cadastrar um cliente, menos metadata. O cliente é identificado pelo document: com um documento que já existe na conta, a PayZu atualiza esse cliente e cria a assinatura nele.
plan_idO plano assinado. O nome, o valor, a periodicidade e o desconto ativo do plano ficam guardados na assinatura.

Campo fora da tabela é ignorado. O cartão é informado só na página da fatura.

  • invoice: é a fatura de adesão, com billing.cycle_number igual a 0. Ela aceita só o meio escolhido, à vista no cartão, e vence uma hora depois da criação, em billing.expires_at.
  • Valor: invoice.amounts.total já tem o desconto do primeiro ciclo. No exemplo, 14391 é o plano de 15990 com 10% de desconto.
  • Endereço: com customer.address completo, inclusive number, invoice.customer.address_on_file vem true e a página da fatura não pede o endereço antes do cartão.
  • Limite: cada IP faz até 10 chamadas por minuto nesta rota.

Uma nova chamada com o mesmo cliente e o mesmo plano parte da adesão que já existe:

SituaçãoResultado
Assinatura ainda incomplete, com o mesmo payment_method, plano sem mudança no nome, no valor, na periodicidade, nos meios ou no desconto, e fatura de adesão pending no prazoRetorna a mesma assinatura e a mesma fatura de adesão.
Outro payment_method ou plano com algum desses termos alteradoCria outra assinatura. A adesão anterior segue até o prazo dela.
Adesão já paga, com a assinatura activeCria outra assinatura.
Cobrança da adesão no cartão ainda sem resposta da adquirenteRecusa a criação, em qualquer meio.

Confirme a adesão

Leve o cliente para invoice.url, onde ele paga a adesão no cartão ou no Pix, como em Pagar a fatura pela página. Com a adesão paga, a assinatura vira active, e a página da fatura leva o cliente ao checkout.redirect_url do plano ou, sem ele, à página de acompanhamento da assinatura. Esse endereço vem em invoice.checkout.redirect_url.

Na criação, a PayZu envia subscription.created e invoice.created aos seus webhooks. Depois:

ResultadoAssinaturaFatura de adesãoEventos
Adesão pagaactivepaidinvoice.paid e subscription.activated
Cartão recusadoincompletepending, com a tentativa failedinvoice.payment_failed
Sem pagamento até billing.expires_atcanceled, com o motivo initial_payment_failureexpiredinvoice.expired e subscription.canceled

Se a última tentativa no cartão segue sem resposta da adquirente quando a fatura vence, a PayZu espera até 48 horas, contadas dessa tentativa, antes de cancelar a assinatura.

Consulte a assinatura pelo id que veio no 201.

bash
curl "https://api.sandbox.payzu.dev/v1/checkout/subscriptions/sub_EG9uphTcCTMvYBkHPKr4cc" \
  -H "x-checkout-key: SUA_CHAVE_DE_CHECKOUT"

Referência: Consultar uma assinatura pela página

  • Cliente: a consulta mostra o e-mail, o celular e o documento mascarados.
  • Dados da assinatura: name, amount e recurrence são os da assinatura, guardados na adesão, e não mudam quando o plano é alterado.
  • Limite: cada IP faz até 60 consultas por minuto, somadas entre as consultas do checkout.

Os ciclos depois da adesão estão em Ciclo da assinatura.

Erros desta operação

CódigoHTTPMensagem
-401Chave de checkout ausente.
-401Chave de checkout inválida.
PZ031403Esta conta só tem acesso de consulta.
PZ032403Cartão não habilitado para esta conta. Fale com o suporte para habilitar ou ofereça apenas Pix.
PZ033403Pix não habilitado para esta conta. Fale com o suporte para habilitar.
-404Plano não encontrado para o id informado
-404Plano não encontrado para o slug informado
-404Plano não encontrado.
-404Assinatura não encontrada para o id informado.
PZ034404Recorrência não ativada para esta conta.
PZ500409A cobrança inicial desta assinatura ainda aguarda confirmação. Tente novamente mais tarde.
PZ101422Valor fora do limite desta conta.
-422Não foi possível criar a assinatura: plano está desativado ou foi excluído.
-422Não foi possível criar a assinatura: método de pagamento não suportado pelo plano.
-422Não foi possível criar a assinatura: periodicidade não disponível para cartão.
-429Muitas tentativas. Aguarde um minuto.

Os demais erros estão no Catálogo de erros.