PayZu GatewayRecorrência
Consultar assinaturas
Leia o status, as datas de cobrança e o cancelamento de uma assinatura, ou liste as assinaturas da conta.
Consulte uma assinatura
bash
curl "https://api.sandbox.payzu.dev/v1/subscriptions/sub_EG9uphTcCTMvYBkHPKr4cc" \
-H "Authorization: Bearer SUA_CHAVE_DE_API"json
{
"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"
},
"metadata": {
"internal_id": "1234"
}
}Referência: Consultar uma assinatura
| Campo | O que traz |
|---|---|
status | incomplete, active ou canceled. |
credit_card | O cartão da assinatura, com card.id só quando o cartão está salvo. Vem null no Pix. |
billing | A data-base dos ciclos em anchor_at, a próxima cobrança em next_at, a data do cancelamento em canceled_at e as renovações recusadas seguidas em renewal_failures. Na assinatura cancelada, next_at vem null. |
grace | O início e o fim da carência, em started_at e ends_at. |
cancellation | Na assinatura cancelada, o motivo em reason e a sua observação em note. |
previous_cancellations | Os cancelamentos desfeitos, do mais novo para o mais antigo, cada um com canceled_at, reason, note e reactivated_at. |
plan | O id e o name do plano de origem. Vem null na assinatura avulsa. |
discount | O desconto da assinatura, que vale nos primeiros cycles ciclos. |
O significado de cada status e de cada motivo está em Ciclo da assinatura, e o prazo da carência, em Carência.
Trecho de uma assinatura em carência
{
"status": "active",
"billing": {
"anchor_at": "2026-11-11T03:00:00.000Z",
"next_at": "2026-12-11T15:20:59.362Z",
"canceled_at": null,
"renewal_failures": 1
},
"grace": {
"started_at": "2026-12-11T15:21:03.871Z",
"ends_at": "2026-12-14T15:20:59.362Z"
}
}Liste as assinaturas
bash
curl "https://api.sandbox.payzu.dev/v1/subscriptions?status=active&plan_id=plan_oOsn4Cs4eayZ3LoytwzErn" \
-H "Authorization: Bearer SUA_CHAVE_DE_API"Referência: Listar as assinaturas
A lista traz items e next_cursor, da assinatura mais nova para a mais antiga, com cada item igual à consulta. A paginação é por cursor, como em Paginação.
| Filtro | O que traz |
|---|---|
status | As assinaturas nesse status. |
plan_id | As assinaturas de um plano. As avulsas ficam de fora. |
customer_id | As assinaturas de um cliente. |
next_from, next_to | O dia da próxima cobrança. |
created_from, created_to | O dia da criação. |
search | Busca no código da assinatura e no nome, no e-mail ou no documento do cliente. |
Os dias vão no formato AAAA-MM-DD, no fuso de São Paulo, e incluem o dia inteiro. Parâmetro que a lista não tem é ignorado.
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
| - | 404 | Assinatura não encontrada para o id informado. |
PZ034 | 404 | Recorrência não ativada para esta conta. |
Os erros de autenticação e de validação estão no Catálogo de erros.