Fluxo de assinaturas

Este guia apresenta o caminho feliz — o caminho do macaco — para cobrança recorrente na DL Pay. Ao final, você terá um plano de assinatura, um link público que o cliente pode usar para assinar e uma visão clara de como a plataforma agenda e cobra cada pagamento subsequente.

Visão geral

O modelo de assinaturas é composto por três recursos empilhados:

Recurso	Papel
Plano de assinatura	O modelo. Pertence a uma conta de vendedor. Define valor, frequência, métodos de pagamento aceitos e uma data de término opcional.
Assinante	Uma instância de cliente de um plano. Uma por adesão. Acompanha situação, próxima data de cobrança, cartão salvo opcional e histórico.
Pagamento da assinatura	Uma cobrança individual. Muitos por assinante, um por ciclo de cobrança. Vincula-se à transação subjacente assim que o processador aceita a cobrança.

Quando um cliente assina, um assinante é criado e o primeiro pagamento da assinatura é cobrado imediatamente. A partir daí, uma rotina diária gera e cobra o próximo pagamento sempre que a próxima data de cobrança do assinante vence.

Decisões a tomar de antemão

Antes de criar um plano, defina as quatro decisões a seguir. Elas ficam embutidas no plano e se aplicam a todos os assinantes.

Frequência

Escolha uma das cadências predefinidas. A rotina periódica usa esse valor para avançar a próxima data de cobrança após cada cobrança bem-sucedida.

Valor	Cadência
`weekly`	a cada 7 dias
`biweekly`	a cada 14 dias
`monthly`	+1 mês
`bimonthly`	+2 meses
`quarterly`	+3 meses
`semiannual`	+6 meses
`annual`	+12 meses

Não existe interval_count — não há como configurar “a cada 2 semanas” com um multiplicador personalizado. Escolha o valor predefinido mais próximo.

Valor

amount é armazenado como uma string em centavos de BRL. "4990" significa R$ 49,90. O mesmo valor é cobrado em cada ciclo; não há rateio, período de teste ou campo de desconto no próprio plano.

Vigência

Defina end_date com um carimbo ISO 8601 para parar de gerar novos pagamentos após esse ponto, ou deixe null para um plano perpétuo. Planos perpétuos continuam cobrando até que o assinante cancele.

Métodos de pagamento

payment_methods é a lista de métodos que um assinante pode escolher na adesão. Valores aceitos: credit_card, boleto, pix. payment_methods_no_tax é um subconjunto em que o vendedor absorve a taxa do processador.A tarefa agendada de cobrança automática só repete tentativas automaticamente quando o assinante salvou um cartão na adesão (credit_card com save_card=true). Para pix ou boleto, o sistema cria o próximo pagamento da assinatura e envia um link de pagamento por e-mail.

Sequência ponta a ponta

Etapa 1 — Criar um plano

Um plano pertence à conta unificada de um vendedor. Crie-o com POST /subscriptions/seller/{seller_id}/plans/.

Autentique-se como o vendedor

Use um token JWT Bearer (veja o Início rápido) ou uma chave de API do vendedor. O seller_id da rota deve ser o UUID de uma conta unificada que você pode gerenciar.

Envie o corpo do plano

Obrigatórios: name, description, amount, payment_methods, frequency. Opcionais: end_date, payment_methods_no_tax, notification_config.

Guarde o id retornado

A resposta inclui o UUID do plano. Esse UUID é o único identificador que você precisa para a URL pública de adesão.

curl -X POST https://api.dlpay.cloud/subscriptions/seller/$SELLER_ID/plans/ \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Clube do Café — Mensal",
    "description": "Receba 250g de café especial todo mês.",
    "amount": "4990",
    "payment_methods": ["credit_card", "pix"],
    "payment_methods_no_tax": ["pix"],
    "frequency": "monthly",
    "notification_config": {
      "days_before_due": 3,
      "days_after_overdue": 1
    }
  }'

import requests

response = requests.post(
    f"https://api.dlpay.cloud/subscriptions/seller/{seller_id}/plans/",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "name": "Clube do Café — Mensal",
        "description": "Receba 250g de café especial todo mês.",
        "amount": "4990",
        "payment_methods": ["credit_card", "pix"],
        "payment_methods_no_tax": ["pix"],
        "frequency": "monthly",
    },
)
plan = response.json()
plan_id = plan["id"]

Etapa 2 — Encaminhar o plano para uma página pública

O ID do plano é suficiente para montar uma URL pública de adesão. A plataforma expõe dois endpoints sem autenticação para alimentar uma página hospedada:

GET /subscriptions/plan/{plan_id}/ — renderiza o cartão do plano (nome, valor, frequência, métodos aceitos, nome do vendedor).
POST /subscriptions/plan/{plan_id}/subscribe/ — envia a adesão.

Uma página hospedada típica fica em https://seu-storefront/assinar/{plan_id}/. Envie esse link aos clientes por e-mail, WhatsApp ou pelo canal de aquisição que preferir. Não há um “token de checkout” opaco — o próprio UUID é a chave pública.

Etapa 3 — Cliente assina

Quando o cliente envia o formulário, sua página chama POST /subscriptions/plan/{plan_id}/subscribe/ com os dados de identidade e pagamento. O endpoint faz quatro coisas em uma única chamada:

Valida o corpo. O type precisa estar em payment_methods do plano.
Se type=credit_card e save_card=true, tokeniza o cartão no processador para que possa ser reutilizado em cada renovação.
Cria o assinante (situação pending, próxima data de cobrança igual a agora).
Cria o primeiro pagamento da assinatura e cobra-o imediatamente pela conta unificada do vendedor.

Em caso de sucesso, o assinante e o pagamento passam para paid e a próxima data de cobrança é avançada conforme a frequência do plano.

curl -X POST https://api.dlpay.cloud/subscriptions/plan/$PLAN_ID/subscribe/ \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Souza",
    "email": "maria@example.com",
    "phone_number": "11988887777",
    "taxpayer_id": "12345678901",
    "type": "credit_card",
    "installments": 1,
    "save_card": true,
    "card": {
      "number": "4242424242424242",
      "cvv": "123",
      "name": "MARIA SOUZA",
      "expirationMonth": "08",
      "expirationYear": "2028"
    }
  }'

response = requests.post(
    f"https://api.dlpay.cloud/subscriptions/plan/{plan_id}/subscribe/",
    json={
        "name": "Maria Souza",
        "email": "maria@example.com",
        "phone_number": "11988887777",
        "taxpayer_id": "12345678901",
        "type": "credit_card",
        "installments": 1,
        "save_card": True,
        "card": {
            "number": "4242424242424242",
            "cvv": "123",
            "name": "MARIA SOUZA",
            "expirationMonth": "08",
            "expirationYear": "2028",
        },
    },
)
data = response.json()
subscriber_id = data["subscriber"]["id"]

A resposta espelha o que um observador autenticado veria:

{
  "subscriber": {
    "id": "f4b1c7a9-...",
    "status": "paid",
    "next_billing_date": "2026-06-14T12:30:00-03:00",
    "saved_card": { "card_brand": "visa", "last4_digits": "4242", "holder_name": "MARIA SOUZA" }
  },
  "payment": {
    "id": "a1b2c3d4-...",
    "status": "paid",
    "payment_method": "credit_card"
  }
}

Para pix, o objeto payment contém também um bloco pix (QR code + expiração). Para boleto, contém um bloco boleto (URL + código de barras). Nos dois casos o pagamento começa como pending e só passa para paid quando o webhook do processador chega.

Etapa 4 — Acompanhar assinantes e pagamentos

Do lado do vendedor, dois endpoints de listagem cobrem a maior parte da visão operacional:

GET .../plans/{plan_id}/subscribers/ — todos os clientes vinculados a um plano.
GET .../plans/{plan_id}/subscribers/{subscriber_id}/payments/ — todas as cobranças de um cliente.

Situações do assinante

O campo status do assinante é uma consolidação desnormalizada do último pagamento.

Situação	Significado
`pending`	A primeira cobrança está em andamento, ou uma renovação aguarda a ação do cliente (por exemplo, link de PIX/boleto enviado).
`paid`	O último pagamento foi confirmado. É a única situação processada pela rotina de renovação.
`failed`	A última tentativa de cobrança foi recusada pelo processador; a retentativa fica agendada. Após esgotar as tentativas, o assinante permanece nessa situação.
`overdue`	A data de vencimento de um pagamento pendente passou sem confirmação. Definida pela rotina periódica de inadimplência.
`canceled`	Cancelado pelo vendedor ou pelo cliente. A rotina de renovação ignora completamente essa situação.

Situações do pagamento

Espelham as situações do assinante, mas no nível da cobrança individual: pending, paid, failed, overdue, canceled. O pagamento da assinatura é a fonte da verdade — a situação do assinante é derivada do último pagamento.

Etapa 5 — Cancelar

Existem dois caminhos de cancelamento; ambos colocam o assinante em canceled, registram o momento do cancelamento e marcam todo pagamento pendente como canceled:

Autenticado (lado do vendedor) — POST /subscriptions/seller/{seller_id}/plans/{plan_id}/subscribers/{subscriber_id}/cancel/. Use a partir do seu painel.
Público (lado do cliente) — POST /subscriptions/subscriber/{subscriber_id}/cancel/. O UUID do assinante é a única credencial; compartilhe o link de autoatendimento por e-mail se quiser que os clientes se cancelem sozinhos.

Ambos os endpoints disparam o e-mail de confirmação de cancelamento. O cancelamento é terminal: não há endpoint de retomada. Para reiniciar a cobrança do mesmo cliente, crie um novo assinante pelo endpoint público de adesão.

Internos da cobrança recorrente

A plataforma mantém as assinaturas em andamento por meio de quatro rotinas, cada uma agendada periodicamente.

As quatro rotinas

Rotina	Agendamento padrão	O que faz
Rotina diária de processamento	`0 6 * * *`	Localiza assinantes com `status=paid` e `next_billing_date <= agora`. Cria um novo pagamento da assinatura. Para assinantes com cartão, cobra automaticamente via token salvo. Para PIX/boleto, envia um link de pagamento por e-mail e move para `pending`.
Rotina horária de inadimplência	`0 * * * *`	A cada hora. Sinaliza qualquer pagamento `pending` com data de vencimento expirada como `overdue` e propaga essa situação ao assinante.
Rotina de retentativas	`0 /4 * *`	A cada 4 horas. Refaz cobranças de cartão que falharam usando o token salvo. Tentativas em +1, +3 e +7 dias; após o número máximo de tentativas (padrão `3`) o assinante fica permanentemente marcado como `failed`.
Rotina diária de lembretes	`0 9 * * *`	Diariamente às 09:00. Lê a configuração de notificações para enviar lembretes “X dias antes do vencimento”, avisos “vence hoje” e alertas “X dias em atraso”.

O que acontece quando uma cobrança falha

A rotina diária (ou uma passagem de retentativa) captura a recusa do processador.
O pagamento é movido para failed com o motivo da falha preenchido.
O assinante é movido para failed.
A próxima tentativa é agendada para agora + intervalo (1, depois 3, depois 7 dias).
A rotina de retentativas seleciona o caso na próxima execução, incrementa o contador de tentativas e tenta novamente.
Após o número máximo de retentativas sem sucesso, a próxima tentativa fica nula e o assinante permanece em failed para sempre.

Reconciliação por webhook para PIX / boleto

Quando o processador confirma um pagamento pix ou boleto, o ouvinte de webhooks chama a reconciliação de assinaturas. Essa rotina localiza os pagamentos da assinatura cuja transação corresponde e recalcula a situação de cada um. A recalculagem relê a situação subjacente da transação, mapeia para a situação do pagamento e, ao chegar em paid, registra a data de pagamento, dispara a notificação de sucesso e solicita ao assinante que recalcule sua própria situação.

Exemplo ponta a ponta

Um fluxo mínimo que cria um plano, exibe a URL pública de adesão e inspeciona o histórico de pagamentos do primeiro assinante.

import requests

API = "https://api.dlpay.cloud"
HEADERS = {"Authorization": f"Bearer {access_token}"}

plan = requests.post(
    f"{API}/subscriptions/seller/{seller_id}/plans/",
    headers=HEADERS,
    json={
        "name": "Clube do Café — Mensal",
        "description": "Receba 250g de café especial todo mês.",
        "amount": "4990",
        "payment_methods": ["credit_card", "pix"],
        "frequency": "monthly",
    },
).json()
plan_id = plan["id"]

public_url = f"https://seu-storefront/assinar/{plan_id}/"
print("Compartilhe este link com os clientes:", public_url)

subscribers = requests.get(
    f"{API}/subscriptions/seller/{seller_id}/plans/{plan_id}/subscribers/",
    headers=HEADERS,
).json()

if subscribers:
    first_subscriber_id = subscribers[0]["id"]
    payments = requests.get(
        f"{API}/subscriptions/seller/{seller_id}"
        f"/plans/{plan_id}/subscribers/{first_subscriber_id}/payments/",
        headers=HEADERS,
    ).json()
    for p in payments:
        print(p["created_at"], p["amount"], p["payment_status"])

Armadilhas

O recurso de assinante é somente leitura. Não há PATCH nem PUT. Para alterar dados do assinante, use as ações dedicadas (como cancel) ou atualize campos no plano ou no pagamento correlato.

Valores são strings, não inteiros. Tanto o valor do plano quanto o valor do pagamento são armazenados como string. Sempre envie "4990", nunca 4990. O servidor faz a conversão interna ao chamar o processador, portanto strings somente com dígitos são a entrada mais segura.

Não existe interval_count. Não dá para expressar “a cada 2 semanas” ou “a cada 45 dias”. Escolha a frequency predefinida mais próxima. Se precisar de uma cadência fora do padrão, modele com um plano por cadência.

Não há período de teste. Não existe trial_period_days nem carência no plano. A primeira cobrança é tentada imediatamente durante o POST /subscribe/. Cobrança de R$ 0,00 não é suportada — em vez disso, crie o assinante fora do fluxo público pulando a adesão pública, ou aplique um desconto na sua própria camada de aplicação antes de chamar a API.

A renovação automática só ocorre para cartões salvos. Assinantes de PIX e boleto recebem um novo registro de pagamento e um link por e-mail a cada ciclo, mas a rotina não cobrará automaticamente — eles precisam clicar no link e pagar. Se ignorarem além da data de vencimento, a rotina periódica move tanto o pagamento quanto o assinante para overdue.

A rotina diária só processa assinantes em status=paid. Um assinante cujo ciclo anterior falhou (status=failed ou overdue) nunca é selecionado pela rotina de renovação — somente a rotina de retentativas tentará novamente aquele pagamento específico. Após esgotar as retentativas, a cobrança para.

Veja também

Criar plano

Requisição e resposta completas para POST /subscriptions/seller/{seller_id}/plans/.

Adesão pública

O endpoint único que transforma um visitante em assinante pagante.

Listar assinantes

Visão operacional de todos os clientes em um plano.

Listar pagamentos

Histórico de pagamentos por assinante com vínculos para a transação unificada.

Primeiros passos

Conceitos

Fluxos

Fluxo de assinaturas

Visão geral

Decisões a tomar de antemão

Sequência ponta a ponta

Etapa 1 — Criar um plano

Etapa 2 — Encaminhar o plano para uma página pública

Etapa 3 — Cliente assina

Etapa 4 — Acompanhar assinantes e pagamentos

Situações do assinante

Situações do pagamento

Etapa 5 — Cancelar

Internos da cobrança recorrente

As quatro rotinas

O que acontece quando uma cobrança falha

Reconciliação por webhook para PIX / boleto

Exemplo ponta a ponta

Armadilhas

Veja também

Criar plano

Adesão pública

Listar assinantes

Listar pagamentos

​Visão geral

​Decisões a tomar de antemão

​Sequência ponta a ponta

​Etapa 1 — Criar um plano

​Etapa 2 — Encaminhar o plano para uma página pública

​Etapa 3 — Cliente assina

​Etapa 4 — Acompanhar assinantes e pagamentos

​Situações do assinante

​Situações do pagamento

​Etapa 5 — Cancelar

​Internos da cobrança recorrente

​As quatro rotinas

​O que acontece quando uma cobrança falha

​Reconciliação por webhook para PIX / boleto

​Exemplo ponta a ponta

​Armadilhas

​Veja também

Criar plano

Adesão pública

Listar assinantes

Listar pagamentos

Visão geral

Decisões a tomar de antemão

Sequência ponta a ponta

Etapa 1 — Criar um plano

Etapa 2 — Encaminhar o plano para uma página pública

Etapa 3 — Cliente assina

Etapa 4 — Acompanhar assinantes e pagamentos

Situações do assinante

Situações do pagamento

Etapa 5 — Cancelar

Internos da cobrança recorrente

As quatro rotinas

O que acontece quando uma cobrança falha

Reconciliação por webhook para PIX / boleto

Exemplo ponta a ponta

Armadilhas

Veja também