Assinar um plano pelo checkout
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.
curl "https://api.sandbox.payzu.dev/v1/checkout/plans/plan_oOsn4Cs4eayZ3LoytwzErn" \
-H "x-checkout-key: SUA_CHAVE_DE_CHECKOUT"{
"id": "plan_oOsn4Cs4eayZ3LoytwzErn",
"name": "Plano Mensal",
"description": "Acesso mensal à plataforma",
"amount": 15990,
"recurrence": "monthly",
"payment_settings": {
"accepted_methods": ["credit_card", "pix"]
},
"checkout": {
"slug": "plano-mensal",
"logo_url": "https://loja.exemplo.com.br/logo.png",
"redirect_url": "https://loja.exemplo.com.br/obrigado"
},
"merchant": {
"display_name": "Loja da Maria"
},
"discount": {
"type": "percentage",
"value": 10,
"cycles": 3,
"public_description": "10% nos 3 primeiros meses"
}
}Referência: Consultar um plano pela página
| Campo | O que traz |
|---|---|
payment_settings.accepted_methods | Só os meios do plano que a sua conta pode cobrar. credit_card também sai quando recurrence não é monthly nem annual. |
discount | Vem 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.
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"
}'{
"id": "sub_EG9uphTcCTMvYBkHPKr4cc",
"code": "EELBD9PE",
"status": "incomplete",
"name": "Plano Mensal",
"amount": 15990,
"recurrence": "monthly",
"payment_method": "credit_card",
"recurrence_mode": "native",
"created_at": "2026-11-11T15:20:59.359Z",
"updated_at": "2026-11-11T15:20:59.359Z",
"recurrence_end_date": null,
"credit_card": null,
"billing": {
"anchor_at": "2026-11-11T03:00:00.000Z",
"next_at": "2026-12-11T15:20:59.362Z",
"canceled_at": null
},
"grace": null,
"cancellation": null,
"customer": {
"id": "cus_bdQT0ls1QMIXVuhngvhbwC",
"name": "Maria Souza",
"email": "maria@exemplo.com.br",
"phone": "11987654321",
"document": "52998224725",
"document_type": "cpf"
},
"plan": {
"id": "plan_oOsn4Cs4eayZ3LoytwzErn",
"name": "Plano Mensal",
"description": "Acesso mensal à plataforma",
"amount": 15990,
"recurrence": "monthly",
"payment_settings": {
"accepted_methods": ["credit_card", "pix"]
},
"checkout": {
"slug": "plano-mensal",
"logo_url": "https://loja.exemplo.com.br/logo.png",
"redirect_url": "https://loja.exemplo.com.br/obrigado"
}
},
"discount": {
"type": "percentage",
"value": 10,
"cycles": 3,
"public_description": "10% nos 3 primeiros meses"
},
"invoice": {
"id": "in_PSSHbv1eu5ZneriC2C3my4",
"status": "pending",
"url": "https://invoice.payzu.com.br/pay/in_PSSHbv1eu5ZneriC2C3my4",
"description": "Plano Mensal",
"created_at": "2026-11-11T15:20:59.361Z",
"updated_at": "2026-11-11T15:20:59.361Z",
"amounts": {
"subtotal": 15990,
"discount": 1599,
"total": 14391,
"paid": 0,
"refunded": 0
},
"billing": {
"cycle_number": 0,
"due_at": "2026-11-11T15:20:59.361Z",
"expires_at": "2026-11-11T16:20:59.361Z",
"paid_at": null,
"canceled_at": null,
"refunded_at": null,
"chargedback_at": null
},
"items": [
{ "name": "Plano Mensal", "sku": null, "quantity": 1, "unit_price": 15990 }
],
"payment_settings": {
"accepted_methods": ["credit_card"],
"credit_card": { "max_installments": 1 }
},
"checkout": {
"redirect_url": "https://loja.exemplo.com.br/obrigado",
"cancel_url": null
},
"merchant": {
"display_name": "Loja da Maria"
},
"customer": {
"name": "Maria",
"email": "m***@exemplo.com.br",
"document": "***.982.247-**",
"document_type": "cpf",
"phone": "(11) *****-4321",
"address_on_file": true
},
"subscription": {
"code": "EELBD9PE",
"name": "Plano Mensal"
},
"payment_link": null,
"payments": [],
"refunds": []
}
}Referência: Criar uma assinatura pela página
| Campo | Regra |
|---|---|
payment_method | credit_card ou pix, um dos meios em payment_settings.accepted_methods do plano. |
customer | Quem 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_id | O 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, combilling.cycle_numberigual a0. Ela aceita só o meio escolhido, à vista no cartão, e vence uma hora depois da criação, embilling.expires_at.- Valor:
invoice.amounts.totaljá tem o desconto do primeiro ciclo. No exemplo,14391é o plano de15990com 10% de desconto. - Endereço: com
customer.addresscompleto, inclusivenumber,invoice.customer.address_on_filevemtruee 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ção | Resultado |
|---|---|
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 prazo | Retorna a mesma assinatura e a mesma fatura de adesão. |
Outro payment_method ou plano com algum desses termos alterado | Cria outra assinatura. A adesão anterior segue até o prazo dela. |
Adesão já paga, com a assinatura active | Cria outra assinatura. |
| Cobrança da adesão no cartão ainda sem resposta da adquirente | Recusa 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:
| Resultado | Assinatura | Fatura de adesão | Eventos |
|---|---|---|---|
| Adesão paga | active | paid | invoice.paid e subscription.activated |
| Cartão recusado | incomplete | pending, com a tentativa failed | invoice.payment_failed |
Sem pagamento até billing.expires_at | canceled, com o motivo initial_payment_failure | expired | invoice.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.
curl "https://api.sandbox.payzu.dev/v1/checkout/subscriptions/sub_EG9uphTcCTMvYBkHPKr4cc" \
-H "x-checkout-key: SUA_CHAVE_DE_CHECKOUT"{
"id": "sub_EG9uphTcCTMvYBkHPKr4cc",
"code": "EELBD9PE",
"status": "active",
"name": "Plano Mensal",
"amount": 15990,
"recurrence": "monthly",
"payment_method": "credit_card",
"credit_card": {
"card": {
"id": "card_GL2pIWf5pznF4qwg2KKd5v",
"last_digits": "1111",
"expiration": "12/2030",
"holder_name": "MARIA SOUZA"
}
},
"billing": {
"anchor_at": "2026-11-11T03:00:00.000Z",
"next_at": "2026-12-11T15:20:59.362Z",
"canceled_at": null
},
"merchant": {
"display_name": "Loja da Maria"
},
"customer": {
"id": "cus_bdQT0ls1QMIXVuhngvhbwC",
"name": "Maria Souza",
"email": "m***@exemplo.com.br",
"phone": "(11) *****-4321",
"document": "***.982.247-**",
"document_type": "cpf"
}
}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,amounterecurrencesã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ódigo | HTTP | Mensagem |
|---|---|---|
| - | 401 | Chave de checkout ausente. |
| - | 401 | Chave de checkout inválida. |
PZ031 | 403 | Esta conta só tem acesso de consulta. |
PZ032 | 403 | Cartão não habilitado para esta conta. Fale com o suporte para habilitar ou ofereça apenas Pix. |
PZ033 | 403 | Pix não habilitado para esta conta. Fale com o suporte para habilitar. |
| - | 404 | Plano não encontrado para o id informado |
| - | 404 | Plano não encontrado para o slug informado |
| - | 404 | Plano não encontrado. |
| - | 404 | Assinatura não encontrada para o id informado. |
PZ034 | 404 | Recorrência não ativada para esta conta. |
PZ500 | 409 | A cobrança inicial desta assinatura ainda aguarda confirmação. Tente novamente mais tarde. |
PZ101 | 422 | Valor fora do limite desta conta. |
| - | 422 | Não foi possível criar a assinatura: plano está desativado ou foi excluído. |
| - | 422 | Não foi possível criar a assinatura: método de pagamento não suportado pelo plano. |
| - | 422 | Não foi possível criar a assinatura: periodicidade não disponível para cartão. |
| - | 429 | Muitas tentativas. Aguarde um minuto. |
Os demais erros estão no Catálogo de erros.