Criar Assinatura

post

https://api.toktus.com/api/v1/subscriptions/

Cria uma assinatura recorrente com cobrança automática no intervalo definido.

Campos obrigatórios: gateway, customerId, planName, amount, interval, paymentMethod

Comportamento por gateway:

Gateway	Mecanismo	Observação
Stripe	Price + Subscription	Gestão completa via API
Pagar.me	Plan + Subscription	Criação automática do plano
Asaas	Ciclo nativo	Gestão completa via API
Mercado Pago	PreApproval	Retorna link `init_point` para autorização. Exige `email` e `token` para cartão
PagSeguro	Plan + Subscription	Aceita token encrypted ou dados raw

Mercado Pago: O assinante deve acessar o link init_point retornado para autorizar a cobrança recorrente.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

gateway

string

enum

Identificador do gateway de pagamento:

stripe — Gateway internacional com APIs modernas
pagarme — Gateway brasileiro com boa documentação
asaas — Focado em cobranças recorrentes e boletos
mercadopago — Maior gateway da América Latina
pagseguro — Gateway tradicional do Brasil (PagBank)

Allowed:

customerId

string

required

ID do cliente no gateway. Para Mercado Pago, o e-mail do customer é obtido automaticamente.

planName

string

required

length between 3 and 100

Nome do plano de assinatura

amount

integer

required

≥ 100

Valor cobrado em cada renovação (centavos). R$ 49,90 = 4990. Valor mínimo: R$ 1,00 (100 centavos)

interval

string

enum

required

Intervalo de cobrança recorrente:

weekly — Semanal (a cada 7 dias)
monthly — Mensal (a cada 30 dias)
quarterly — Trimestral (a cada 3 meses)
yearly — Anual (a cada 12 meses)

Allowed:

paymentMethod

string

enum

required

Método de pagamento utilizado na transação:

credit_card — Cartão de crédito (à vista ou parcelado)
debit_card — Cartão de débito (aprovação instantânea)
boleto — Boleto bancário (compensação em 1-3 dias úteis)
pix — Pagamento instantâneo via PIX (disponível 24/7)

Allowed:

description

string

length ≤ 200

Descrição da assinatura

startDate

date

Data de início (formato: AAAA-MM-DD)

endDate

date

Data de término. Opcional.

creditCard

object

Dados do cartão de crédito. Obrigatório quando paymentMethod = credit_card.

Prioridade de campos: paymentMethodId > token > dados raw (number/expMonth/expYear/cvv).

Compatibilidade por gateway:

Gateway	Token	PaymentMethod ID	Dados raw
Stripe			(requer ativação)
Pagar.me
Asaas
Mercado Pago	(obrigatório)	(alias)
PagSeguro	(encrypted)	(alias)

metadata

object

Metadados adicionais. Mercado Pago: envie email aqui caso não haja customer cadastrado (ex: { "email": "[email protected]" }).

totalCycles

integer

≥ 1

Número máximo de ciclos de cobrança. Após atingir o limite, a assinatura é cancelada automaticamente. Suportado por Pagar.me e Asaas.

trialDays

integer

1 to 365

Dias de trial gratuito antes da primeira cobrança. Suportado por Stripe e Pagar.me.

billingDay

integer

1 to 31

Dia do mês para cobrança (1-31). Suportado por Pagar.me e Asaas.

intervalCount

integer

1 to 12

Quantidade de intervalos entre cobranças. Ex: interval=monthly + intervalCount=3 = a cada 3 meses. Suportado por Stripe e Pagar.me.

code

string

length ≤ 255

Código do pedido ou venda no seu sistema (opcional). Use para agrupar assinaturas.

Responses

201Default Response