PayZu GatewayRecorrência
Criar um plano
Defina o valor de cada ciclo, a periodicidade, os meios aceitos e, se quiser, um desconto para os primeiros ciclos.
Crie o plano
bash
curl -X POST https://api.sandbox.payzu.dev/v1/plans \
-H "Authorization: Bearer SUA_CHAVE_DE_API" \
-H "Idempotency-Key: a3f1c9e2-7b4d-4e8a-9c6f-1d2e3f4a5b6c" \
-H "Content-Type: application/json" \
-d '{
"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,
"internal_description": "Campanha de novembro",
"public_description": "10% nos 3 primeiros meses"
},
"metadata": {
"internal_id": "1234"
}
}'json
{
"id": "plan_oOsn4Cs4eayZ3LoytwzErn",
"status": "active",
"url": "https://invoice.payzu.com.br/checkout/jdUWa_UHtX_7a-vtN_NChU7bug_IbxizyqDEN2X0000/plano-mensal",
"name": "Plano Mensal",
"description": "Acesso mensal à plataforma",
"amount": 15990,
"recurrence": "monthly",
"created_at": "2026-11-11T15:20:59.297Z",
"updated_at": "2026-11-11T15:20:59.297Z",
"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,
"internal_description": "Campanha de novembro",
"public_description": "10% nos 3 primeiros meses"
},
"metadata": {
"internal_id": "1234"
}
}Referência: Criar um plano
O plano nasce active, com a página de adesão em url, como em Planos.
Campos
checkout, discount e metadata são opcionais, e os outros campos são obrigatórios. Campo fora destas tabelas responde 400.
| Campo | Regra |
|---|---|
name | De 1 a 120 caracteres. |
description | Até 1000 caracteres. |
amount | Valor de cada ciclo em centavos, de no mínimo 500 (R$ 5,00). |
recurrence | monthly ou annual. As outras periodicidades respondem 422. |
payment_settings.accepted_methods | Pelo menos um entre credit_card e pix. Cada meio precisa estar habilitado na conta. |
metadata | Os seus dados no plano, com os limites de Metadados. |
Idempotency-Key | Cabeçalho opcional que permite repetir a criação sem duplicar o plano, como em Idempotência. |
| Campo | Regra |
|---|---|
checkout.slug | Identifica o plano na url da página de adesão, com 3 a 64 letras minúsculas, números e hífens. Não se repete entre os planos da conta; o de um plano excluído fica livre. |
checkout.logo_url | Endereço com https. |
checkout.redirect_url | Endereço com https. |
| Campo | Regra |
|---|---|
discount.type | percentage ou fixed_amount. |
discount.value | De 1 a 99 no percentage; em centavos e menor que amount no fixed_amount. |
discount.cycles | Quantos dos primeiros ciclos têm desconto, contando a adesão. |
discount.internal_description, discount.public_description | Opcionais, de 1 a 255 caracteres. |
O valor com desconto também precisa ser de no mínimo R$ 5,00.
Abaixo do mínimo, a resposta 400 traz o motivo em fields: O valor mínimo é R$ 5,00. no campo amount ou O valor com desconto precisa ser de no mínimo R$ 5,00. no campo discount.value.
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
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. |
PZ034 | 404 | Recorrência não ativada para esta conta. |
PZ550 | 409 | Já existe um plano com este slug. |
| - | 422 | Tipo de recorrência não suportado no momento |
Os erros de autenticação, de idempotência e de validação estão no Catálogo de erros.