PayZu GatewayRecorrência

Criar uma assinatura


Nesta páginaCrie a assinaturaLeia a respostaConfirme a adesãoErros desta operação

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

bash
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"
    }
  }'

Referência: Criar uma assinatura

CampoRegra
plan_idO plano assinado. O nome, o valor, a periodicidade e o desconto ativo do plano ficam guardados na assinatura.
name, amount e recurrenceOs 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).
discountOpcional e só na avulsa, com type, value, cycles, internal_description e public_description, como o desconto do plano.
payment_methodcredit_card ou pix. Com plano, precisa ser um dos meios do plano.
credit_cardObrigatório no cartão, com um só entre card_id, card_token e card. No Pix, não vai.
customer_id ou customerUm 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-KeyCabeçalho obrigatório.

Campo fora da tabela responde 400, inclusive installments: a cobrança da assinatura é sempre à vista.

  • Periodicidade: no Pix, recurrence aceita monthly, bimonthly, quarterly, semiannual e annual. No cartão, só monthly e annual, 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_token vem da Tokenização de cartão, e card leva number, expiration, cvv, holder_name e, 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 metadata diferente em cada uma para distinguir uma da outra.

Estas recusas respondem 400, com o campo em fields:

RecusaCampo em fields
Plano desativado ou excluídoplan_id
Meio fora do plano, ou plano com periodicidade que o cartão não aceitapayment_method
Avulsa no cartão com periodicidade que o cartão não aceitarecurrence

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

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"
  },
  "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"
  }
}
  • invoice: é a fatura de adesão, no formato de Consultar faturas, com billing.cycle_number igual a 0. Ela vence uma hora depois da criação, em billing.expires_at, e aceita só o meio da assinatura.
  • Pix: a assinatura vem incomplete, com o copia e cola em invoice.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_token ou card, credit_card.card.id vem null.
  • Avulsa: plan vem null, e discount só 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.

ResultadoAssinaturaFatura de adesãoEventos
Cartão aprovadoactivepaidinvoice.paid e subscription.activated
Cartão recusadoincompletepending, com a tentativa failedinvoice.payment_failed
Cartão sem resposta da adquirenteincompletepending, com a tentativa processing-
Pix pagoactivepaidinvoice.paid e subscription.activated
Sem pagamento até billing.expires_atcanceled, com o motivo initial_payment_failureexpiredinvoice.expired e subscription.canceled
  • Nova tentativa: pague a fatura de adesão em POST /v1/invoices/:invoice_id/payments, com o invoice.id da 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_method e metadata tenta outra vez na fatura de adesão em aberto, sem mudar valores nem datas. Com outro meio, outro metadata ou 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 mesmos name, amount, recurrence e payment_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ódigoHTTPMensagem
PZ201400Token de cartão inválido ou vencido. Gere o token de novo.
PZ503400O valor da assinatura, com o desconto em vigor, precisa ser de no mínimo R$ 5,00.
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
-404Cliente não encontrado para o id informado.
-404Cartão não encontrado para o id informado.
PZ034404Recorrência não ativada para esta conta.
PZ110409Esta fatura já foi paga.
PZ111409Só uma fatura em aberto pode ser paga ou cancelada.
PZ500409A cobrança inicial desta assinatura ainda aguarda confirmação. Tente novamente mais tarde.
PZ101422Valor fora do limite desta conta.
PZ114422Limite diário de tentativas de cobrança desta fatura atingido. Tente novamente mais tarde.
PZ203422Esta conta exige os dados de antifraude na cobrança no cartão.
PZ202503Não foi possível processar o cartão agora. Tente de novo.
PZ900503Nã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.