Skip to main content
POST
Criar Assinatura
Permite criar assinaturas recorrentes (semanal, mensal ou anual) com cobrança automática. Ideal para serviços SaaS, academias, escolas e outros modelos de negócio baseados em recorrência.
Há três jeitos de vender uma assinatura, todos no mesmo modelo:
  1. Oferta recorrente com link pronto: crie uma oferta recorrente e compartilhe o checkout_url dela. O comprador informa os próprios dados e paga.
  2. Link de pagamento recorrente: crie um link com recurrence_interval. Mesma ideia, sem produto.
  3. Headless (esta rota): você já tem os dados do cliente e do cartão e cria a assinatura direto. Aponte uma oferta recorrente por offer_id para herdar a régua de preços, ou envie interval mais amount para uma recorrência simples.
Não existe “plano avulso”: a régua de preços vive na oferta.

Idempotência (obrigatória)

Esta rota exige o header Idempotency-Key — uma chave única gerada por assinatura (ex.: um UUID). Sem ele, a resposta é 400.
  • Replay: a mesma chave com o mesmo corpo devolve a resposta original (não cria uma segunda assinatura) — seguro para retry.
  • Conflito (409): a mesma chave com corpo diferente é rejeitada.
  • Em voo: requisição concorrente com a mesma chave recebe 409 + header Retry-After.

Parâmetros da Requisição

Dados Básicos

string
required
Descrição da assinatura (aparece na fatura)Máximo: 255 caracteres
string
required
Identificador único da assinatura no seu sistemaMáximo: 255 caracteres
string
required
Código MCC (Merchant Category Code) do seu negócioExemplo: "5734" (Software as a Service)
string
URL para receber webhooks sobre eventos da assinaturaFormato: URL válida

Oferta e Recorrência

string
UUID de uma oferta recorrente (criada em Produtos e Ofertas). Quando fornecido, a assinatura herda a régua de preços e o intervalo da oferta, e você não precisa enviar interval. A régua congela na assinatura no momento em que ela nasce: editar a oferta depois nunca reprecifica quem já assina.
string
Intervalo de cobrança (obrigatório se offer_id não fornecido)Valores: weekly, monthly, yearly
date
Data de início da assinaturaFormato: YYYY-MM-DDPadrão: data atual
integer
Melhor dia do mês para cobrança (1-31)Padrão: dia da criação
integer
Dias de período de teste gratuitoMínimo: 0 | Máximo: 365
integer
required
Valor da próxima cobrança em centavosImportante: Para PIX Recorrente, se não especificado, será usado o valor de payment.pix_recurring.recurring_amount ou payment.amountExemplo: 4990 = R$ 49,90

Cliente

object
required

Pagamento

object
required

Itens (Opcional)

array
Lista de itens da assinatura (opcional, para controle interno)

Exemplos de Requisição

Resposta

string
UUID único da assinatura
string
Hash único da assinatura
string
O momento da assinatura, para você decidir o acesso do cliente.Valores: trial, pending, active, past_due, unpaid, canceled, ended, completed. Ver Ciclo de vida e estados.
boolean
Libere o seu serviço por aqui. true quando o cliente deve ter acesso. Não recalcule a partir do state.
string
Intervalo de cobrança: weekly, monthly, yearly
integer
Valor da próxima cobrança em centavos
integer
Número de parcelas
string
Data/hora da próxima cobrança (formato: DD/MM/YYYY HH:mm:ss)
string
Data de início da assinatura
string
Data de término (se aplicável)
integer
Dias de período de teste
integer
Ciclo atual da assinatura
object
object
object

Exemplo de Resposta

201 Created

Códigos de Status

PIX Recorrente - Como Funciona

O PIX Recorrente permite cobranças automáticas recorrentes usando o PIX como método de pagamento, sem a necessidade de cartão de crédito.

Fluxo de Pagamento

  1. Primeiro Pagamento (Autorização)
    • Cliente escaneia QR Code e realiza o primeiro pagamento via PIX
    • Esse pagamento autoriza cobranças futuras automáticas
    • Um charge_code único é gerado para identificar a autorização recorrente
  2. Cobranças Recorrentes Automáticas
    • O sistema agenda automaticamente os pagamentos futuros
    • Pagamentos são processados 2-10 dias antes da data de vencimento.
    • Cliente é notificado antes de cada cobrança
  3. Política de Retry (Tentativas)
    • Em caso de falha, o sistema tenta novamente automaticamente
    • Até 3 tentativas com intervalo de 1 dia entre cada
    • Tentativas ocorrem em até 7 dias da data original

Status do Ciclo de Vida do Pagamento PIX Recorrente

Os status de pagamento do PIX Recorrente seguem um fluxo específico diferente dos outros métodos.

Transições de Status Permitidas

PIX Recorrente - Primeiro Pagamento:
PIX Recorrente - Cobranças Automáticas:

Regras Importantes

Janela de Processamento: Pagamentos PIX Recorrentes devem ser enviados entre 2 e 10 dias antes da data de vencimento.
  • Valor Mínimo: Defina min_amount para evitar cobranças abaixo de um valor específico
  • Período de Trial: Pode ser usado com trial_days > 0, mas o primeiro pagamento deve ser amount = 0
  • Política de Retry: Com retry_policy = true, até 3 tentativas automáticas em caso de falha
  • Charge Code: Obrigatório e único por assinatura, usado para identificar a autorização recorrente

Exemplo de Resposta com PIX Recorrente

201 Created

Próximos Passos

Após criar uma assinatura:
  1. Cancelar assinatura quando necessário
  2. Consultar pagamentos da assinatura
  3. Configurar webhooks para acompanhar eventos de cobrança recorrente
  4. Para PIX Recorrente: exibir QR Code ao cliente e aguardar primeiro pagamento