Criar uma assinatura
Crie a assinatura e cobre o primeiro ciclo na mesma chamada, a partir de um plano ou com um valor combinado só com este cliente.
Crie a assinatura
curl -X POST https://api.sandbox.payzu.dev/v1/subscriptions \
-H "Authorization: Bearer SUA_CHAVE_DE_API" \
-H "Idempotency-Key: a3f1c9e2-7b4d-4e8a-9c6f-1d2e3f4a5b6c" \
-H "Content-Type: application/json" \
-d '{
"payment_method": "credit_card",
"credit_card": {
"card_id": "card_GL2pIWf5pznF4qwg2KKd5v"
},
"customer_id": "cus_bdQT0ls1QMIXVuhngvhbwC",
"plan_id": "plan_oOsn4Cs4eayZ3LoytwzErn",
"metadata": {
"internal_id": "1234"
}
}'curl -X POST https://api.sandbox.payzu.dev/v1/subscriptions \
-H "Authorization: Bearer SUA_CHAVE_DE_API" \
-H "Idempotency-Key: 7d4e2b9c-1f3a-4c5e-8b6d-2a9f0e1c3b4d" \
-H "Content-Type: application/json" \
-d '{
"name": "Mentoria individual",
"amount": 49900,
"recurrence": "monthly",
"payment_method": "credit_card",
"credit_card": {
"card_id": "card_GL2pIWf5pznF4qwg2KKd5v"
},
"customer_id": "cus_bdQT0ls1QMIXVuhngvhbwC",
"metadata": {
"internal_id": "1234"
}
}'curl -X POST https://api.sandbox.payzu.dev/v1/subscriptions \
-H "Authorization: Bearer SUA_CHAVE_DE_API" \
-H "Idempotency-Key: 5b8c1e4f-9a2d-4f6b-8c3e-7d1a0b2c4e6f" \
-H "Content-Type: application/json" \
-d '{
"payment_method": "pix",
"customer_id": "cus_bdQT0ls1QMIXVuhngvhbwC",
"plan_id": "plan_oOsn4Cs4eayZ3LoytwzErn"
}'Referência: Criar uma assinatura
| Campo | Regra |
|---|---|
plan_id | O plano assinado. O nome, o valor, a periodicidade e o desconto ativo do plano ficam guardados na assinatura. |
name, amount e recurrence | Os termos da assinatura avulsa, os três juntos e sem plan_id. name tem até 120 caracteres, e amount é o valor de cada ciclo em centavos, de no mínimo 500 (R$ 5,00). |
discount | Opcional e só na avulsa, com type, value, cycles, internal_description e public_description, como o desconto do plano. |
payment_method | credit_card ou pix. Com plano, precisa ser um dos meios do plano. |
credit_card | Obrigatório no cartão, com um só entre card_id, card_token e card. No Pix, não vai. |
customer_id ou customer | Um dos dois. customer_id usa o cliente cadastrado sem mudar o cadastro. customer cadastra o cliente pelo document ou atualiza o que já tem esse documento, com os campos de Cadastrar um cliente, menos metadata. |
metadata | É só da assinatura e não vem do plano. Os limites estão em Metadados. |
Idempotency-Key | Cabeçalho obrigatório. |
Campo fora da tabela responde 400, inclusive installments: a cobrança da assinatura é sempre à vista.
- Periodicidade: no Pix,
recurrenceaceitamonthly,bimonthly,quarterly,semiannualeannual. No cartão, sómonthlyeannual, na avulsa e no plano. - Cartão:
card_idé um cartão salvo do mesmo cliente e passa a ser o cartão da assinatura.card_tokenvem da Tokenização de cartão, ecardlevanumber,expiration,cvv,holder_namee, se quiser,holder_document. - Antifraude: a cobrança no cartão pela API não leva dados de antifraude. Se a sua conta exige antifraude no cartão, a criação é recusada, e o Pix segue disponível.
- Mesmo plano mais de uma vez: o mesmo cliente pode ter várias assinaturas ativas do mesmo plano. Envie um
metadatadiferente em cada uma para distinguir uma da outra.
Estas recusas respondem 400, com o campo em fields:
| Recusa | Campo em fields |
|---|---|
| Plano desativado ou excluído | plan_id |
| Meio fora do plano, ou plano com periodicidade que o cartão não aceita | payment_method |
| Avulsa no cartão com periodicidade que o cartão não aceita | recurrence |
Use uma Idempotency-Key nova para cada assinatura.
Um erro antes da cobrança libera a chave, mas o que já foi gravado fica: o cliente enviado em customer e, quando o erro vem depois da criação, a assinatura incomplete com a fatura de adesão. Depois que a cobrança sai, a resposta fica guardada, inclusive a do cartão recusado. O número, o CVV e o token do cartão ficam fora da comparação do corpo: com a mesma chave, outro token, ou outro cartão digitado, recebe a primeira resposta e não é cobrado. Trocar o token pelo cartão digitado, ou o contrário, responde 409. Veja Idempotência.
Leia a resposta
{
"id": "sub_EG9uphTcCTMvYBkHPKr4cc",
"code": "EELBD9PE",
"status": "active",
"name": "Plano Mensal",
"amount": 15990,
"recurrence": "monthly",
"payment_method": "credit_card",
"created_at": "2026-11-11T15:20:59.359Z",
"updated_at": "2026-11-11T15:20:59.366Z",
"credit_card": {
"card": {
"id": "card_GL2pIWf5pznF4qwg2KKd5v",
"brand": "visa",
"last_digits": "1111",
"holder_name": "MARIA SOUZA"
}
},
"billing": {
"anchor_at": "2026-11-11T03:00:00.000Z",
"next_at": "2026-12-11T15:20:59.362Z",
"canceled_at": null,
"renewal_failures": 0
},
"grace": null,
"cancellation": null,
"previous_cancellations": [],
"customer": {
"id": "cus_bdQT0ls1QMIXVuhngvhbwC",
"name": "Maria Souza",
"email": "maria@exemplo.com.br",
"document": "52998224725",
"document_type": "cpf"
},
"plan": {
"id": "plan_oOsn4Cs4eayZ3LoytwzErn",
"name": "Plano Mensal"
},
"discount": {
"type": "percentage",
"value": 10,
"cycles": 3,
"internal_description": "Campanha de novembro",
"public_description": "10% nos 3 primeiros meses"
},
"invoice": {
"id": "in_PSSHbv1eu5ZneriC2C3my4",
"status": "paid",
"url": "https://invoice.payzu.com.br/pay/in_PSSHbv1eu5ZneriC2C3my4",
"description": "Plano Mensal",
"external_reference": null,
"created_at": "2026-11-11T15:20:59.361Z",
"updated_at": "2026-11-11T15:20:59.365Z",
"amounts": {
"subtotal": 15990,
"discount": 1599,
"total": 14391,
"paid": 14391,
"refunded": 0
},
"billing": {
"cycle_number": 0,
"due_at": "2026-11-11T15:20:59.361Z",
"expires_at": "2026-11-11T16:20:59.361Z",
"paid_at": "2026-11-11T15:20:59.363Z",
"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": null,
"cancel_url": null
},
"customer": {
"id": "cus_bdQT0ls1QMIXVuhngvhbwC",
"name": "Maria Souza",
"email": "maria@exemplo.com.br",
"document": "52998224725",
"document_type": "cpf"
},
"subscription": {
"id": "sub_EG9uphTcCTMvYBkHPKr4cc",
"code": "EELBD9PE",
"name": "Plano Mensal"
},
"payment_link": null,
"payments": [
{
"id": "pay_r9j4jAwhQdxwZUsHlBVGJT",
"status": "paid",
"method": "credit_card",
"amount": 14391,
"created_at": "2026-11-11T15:20:59.362Z",
"paid_at": "2026-11-11T15:20:59.363Z",
"failed_at": null,
"failure": null,
"credit_card": {
"installments": 1,
"authorization_code": "123456",
"card": {
"id": "card_GL2pIWf5pznF4qwg2KKd5v",
"brand": "visa",
"last_digits": "1111",
"holder_name": "MARIA SOUZA"
}
}
}
],
"refunds": [],
"cancellation": null,
"chargeback": null,
"metadata": null
},
"metadata": {
"internal_id": "1234"
}
}{
"id": "sub_9WxK4mQcTb7NzYv2LdRh6E",
"status": "incomplete",
"payment_method": "pix",
"credit_card": null,
"invoice": {
"id": "in_4TqM9xWcLb2NzYv8KdRh6E",
"status": "pending",
"url": "https://invoice.payzu.com.br/pay/in_4TqM9xWcLb2NzYv8KdRh6E",
"billing": {
"cycle_number": 0,
"due_at": "2026-11-11T15:34:12.122Z",
"expires_at": "2026-11-11T16:34:12.122Z"
},
"payments": [
{
"id": "pay_5VbT8nQcLm3XzYw6KdRh2E",
"status": "pending",
"method": "pix",
"amount": 14391,
"pix": {
"qr_code_text": "00020126MOCK5VbT8nQcLm3XzYw6KdRh2E",
"expires_at": "2026-11-11T16:34:12.130Z",
"end_to_end_id": null,
"payer": null
}
}
]
}
}{
"id": "sub_5LtR8nXcVb3MwYz7KdQh2E",
"status": "incomplete",
"payment_method": "credit_card",
"credit_card": {
"card": {
"id": null,
"brand": "visa",
"last_digits": "1111",
"holder_name": "MARIA SOUZA"
}
},
"invoice": {
"id": "in_6PwZ3nKcVb8TxYm5LdQh4E",
"status": "pending",
"payments": [
{
"id": "pay_7XmQ4wKcLb9NzYt2VdRh6E",
"status": "failed",
"method": "credit_card",
"amount": 14391,
"failed_at": "2026-11-11T15:36:48.989Z",
"failure": {
"stage": "issuer",
"code": "PZ230",
"message": "O banco do cliente recusou sem dizer o motivo. O cliente pode usar outro cartão ou falar com o banco."
}
}
]
}
}invoice: é a fatura de adesão, no formato de Consultar faturas, combilling.cycle_numberigual a0. Ela vence uma hora depois da criação, embilling.expires_at, e aceita só o meio da assinatura.- Pix: a assinatura vem
incomplete, com o copia e cola eminvoice.payments[0].pix.qr_code_text. Mostre o código ao cliente. O QR Code vence junto com a fatura de adesão. - Cartão não salvo: com
card_tokenoucard,credit_card.card.idvemnull. - Avulsa:
planvemnull, ediscountsó vem preenchido se você enviou um.
O cartão recusado também responde 201.
Leia o status da assinatura e de invoice.payments[0]. A assinatura incomplete com a tentativa failed ainda espera o pagamento da adesão, com o motivo da recusa em failure.
Confirme a adesão
Antes da cobrança, a PayZu cria a assinatura incomplete e a fatura de adesão, e envia subscription.created e invoice.created.
| Resultado | Assinatura | Fatura de adesão | Eventos |
|---|---|---|---|
| Cartão aprovado | active | paid | invoice.paid e subscription.activated |
| Cartão recusado | incomplete | pending, com a tentativa failed | invoice.payment_failed |
| Cartão sem resposta da adquirente | incomplete | pending, com a tentativa processing | - |
| Pix pago | active | paid | invoice.paid e subscription.activated |
Sem pagamento até billing.expires_at | canceled, com o motivo initial_payment_failure | expired | invoice.expired e subscription.canceled |
- Nova tentativa: pague a fatura de adesão em
POST /v1/invoices/:invoice_id/payments, com oinvoice.idda resposta, como em Pagar uma fatura. Aprovada, ela ativa a assinatura. - Nova criação: na assinatura de plano, criar de novo com o mesmo cliente, plano,
payment_methodemetadatatenta outra vez na fatura de adesão em aberto, sem mudar valores nem datas. Com outro meio, outrometadataou o plano alterado, nasce outra assinatura, e a adesão antiga vence no prazo dela. Na avulsa, cada criação abre outra assinatura. - Cobrança sem desfecho: enquanto a adquirente não responde à cobrança da adesão no cartão, a criação repetida é recusada. Na de plano, a recusa vale para o mesmo cliente, plano e
metadata, em qualquer meio. Na avulsa, para o mesmo cliente com os mesmosname,amount,recurrenceepayment_method. - Sem pagamento: se a última tentativa no cartão segue sem desfecho quando a fatura vence, a PayZu espera até 48 horas, contadas dessa tentativa, antes de cancelar a assinatura.
Sem esperar o webhook, consulte a assinatura ou a fatura de adesão em Consultar faturas, com o filtro subscription_id. O cliente também pode assinar pela página, como em Assinar um plano pelo checkout.
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
PZ201 | 400 | Token de cartão inválido ou vencido. Gere o token de novo. |
PZ503 | 400 | O valor da assinatura, com o desconto em vigor, precisa ser de no mínimo R$ 5,00. |
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 | Cliente não encontrado para o id informado. |
| - | 404 | Cartão não encontrado para o id informado. |
PZ034 | 404 | Recorrência não ativada para esta conta. |
PZ110 | 409 | Esta fatura já foi paga. |
PZ111 | 409 | Só uma fatura em aberto pode ser paga ou cancelada. |
PZ500 | 409 | A cobrança inicial desta assinatura ainda aguarda confirmação. Tente novamente mais tarde. |
PZ101 | 422 | Valor fora do limite desta conta. |
PZ114 | 422 | Limite diário de tentativas de cobrança desta fatura atingido. Tente novamente mais tarde. |
PZ203 | 422 | Esta conta exige os dados de antifraude na cobrança no cartão. |
PZ202 | 503 | Não foi possível processar o cartão agora. Tente de novo. |
PZ900 | 503 | Não foi possível processar o pagamento agora. Tente novamente mais tarde. |
Os erros de autenticação, de idempotência e de validação estão no Catálogo de erros.