Crie e ative uma assinatura

POST

subscription

curl -X POST https://api.therius.io/v1/subscription \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "planId": 42,
    "customerEmail": "ada@example.com",
    "customerName": "Ada Lovelace",
    "card": { "nonceData": { "nonce": "<fresh nonce from JS SDK>" } }
  }'

{}

POST /subscription inscreve um cliente em um plano e estabelece o mandato recorrente que ancora toda futura Merchant Initiated Transaction (MIT). Inscrever um cliente é uma Cardholder Initiated Transaction (CIT), e uma CIT pode exigir 3D Secure. Dois modos:

Modo CIT — nonceData / cardData

O Therius executa a CIT inicial + a primeira cobrança aqui. O cliente deve estar presente. Essa CIT não pode realizar um desafio de 3D Secure — um cartão que exige 3DS falhará.

Modo record — tokenData

O token é um cartão que já concluiu uma CIT (incluindo 3DS) por meio de /payment/authorization ou /payment/purchase. Nenhuma segunda CIT é executada aqui. Use isto para qualquer cartão que precise de 3D Secure.

Forneça o cartão como exatamente um instrumento — nonceData, cardData (apenas servidores em conformidade com PCI DSS), ou tokenData.

cardOnFile e instalments são ignorados aqui — o Therius é dono do mandato. No modo record networkTransactionId / networkReferenceId são lidos do token; passe-os apenas para um cartão cuja CIT foi feita fora do Therius.

Modo record

Execute você mesmo uma CIT com capacidade 3DS, depois anexe o resultado:

Execute a CIT via /payment/*

Chame /payment/authorization (valor 0 = verificação de conta) ou /payment/purchase com card.<x>.tokenize: true + um shopper.id, e trate qualquer desafio de 3DS com o SDK JS como você faria para um pagamento normal. A resposta devolve um token vt_....

Crie a assinatura

POST /subscription com card.tokenData.token. Para o ciclo 1:
• teste ou startAt diferido → nada é cobrado;
• você cobrou o primeiro ciclo na sua CIT (/payment/purchase) → passe também firstPaymentId (o id do pagamento da resposta dessa chamada); o Therius marca a primeira fatura como paga e a vincula, sem cobrança;
• a sua CIT foi uma verificação de valor zero → omita firstPaymentId; o Therius cobra o ciclo 1 como uma MIT contra o mandato registrado (reverte a assinatura com um 402 se for recusada).
O objeto firstCycle da resposta informa o que aconteceu.

Veja o painel de parâmetros acima para a lista completa de campos — planId, customerEmail e um instrumento de cartão (nonceData/cardData/tokenData — exatamente um) são obrigatórios; customerName/customerDocument, firstPaymentId (modo record), startAt, parentSubscriptionId/propagateLifecycle e metadata são opcionais.

Resposta

Uma requisição bem-sucedida devolve 201 Created com o objeto de assinatura completo, incluindo o id da assinatura, o status inicial, as datas de início e fim do período atual, e a primeira fatura.

Status na criação

Status	Quando ocorre
`active`	O plano não tem teste; a primeira cobrança teve sucesso.
`trialing`	O plano tem um `trialPeriodDays` configurado.
`past_due`	A CIT inicial falhou. Raro — normalmente um `402` é devolvido na recusa em vez disso.

Erros

Código	Significado
`400`	Plano não encontrado ou inativo; ou (modo record) o token não carrega nenhum mandato de CIT, ou `firstPaymentId` não se resolve a um pagamento liquidado que cobrou este token.
`402`	A cobrança da CIT inicial foi recusada (modo CIT), ou a MIT do primeiro ciclo foi recusada (modo record — a assinatura é revertida).
`409`	`Idempotency-Key` duplicado com um corpo de requisição em conflito.
`422`	Erro de validação — p. ex. nenhum instrumento de cartão fornecido, um nonce expirado/usado, ou um plano inválido.

curl -X POST https://api.therius.io/v1/subscription \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "planId": 42,
    "customerEmail": "ada@example.com",
    "customerName": "Ada Lovelace",
    "card": { "nonceData": { "nonce": "<fresh nonce from JS SDK>" } }
  }'

{}

Autorizações

Authorization

string

header

obrigatório

Your secret API key: Bearer prv_production_xxx (production) or Bearer prv_sandbox_xxx (sandbox).

Corpo

application/json

merchantCode

string

obrigatório

Your merchant account identifier.

planId

integer

obrigatório

ID of an active plan. Determines amount, currency, interval and trial.

customerEmail

string

obrigatório

Subscriber email. Used for billing and dunning notifications.

card

Raw card (PCI DSS) · object

obrigatório

Card input for creating a subscription. Enrolling a customer is a CIT and a CIT may require 3D Secure — pick the mode that fits:

• CIT mode (nonceData / cardData): Therius runs the initial CIT + first charge here. The customer must be present. This CIT cannot carry out a 3D Secure challenge, so a 3DS-required card will fail — use record mode for those.

• Record mode (tokenData): the token is a card that already completed a CIT — including any 3DS — through /payment/authorization or /payment/purchase (with card.<x>.tokenize: true + shopper.id). No second CIT runs. The mandate is read from the token; pass networkTransactionId / networkReferenceId explicitly only for a card CIT'd outside Therius. For cycle 1: with a trial or deferred start nothing is charged; with firstPaymentId set Therius marks the first invoice paid and links that payment; otherwise Therius charges cycle 1 as an MIT against the recorded mandate.

Provide exactly ONE of cardData, nonceData, or tokenData. cardOnFile and instalments are not accepted — Therius owns the mandate.

Raw card (PCI DSS)
SDK nonce
Vault token

Show child attributes

customerName

string

Subscriber full name, as it should appear on invoices.

customerDocument

string

Subscriber national ID / tax document, where a market requires it (e.g. Brazil CPF/CNPJ).

firstPaymentId

string

Record mode only, when a first payment is due. The payment id from the /payment/authorization or /payment/purchase call in which you ran this card CIT - Therius verifies it charged the same vaulted token in the plan currency, then marks cycle 1 paid and links it (no charge). Omit and Therius charges cycle 1 as an MIT against the recorded mandate.

startAt

string

RFC 3339 future timestamp to defer the first charge. Omit to activate (or start the trial) immediately.

parentSubscriptionId

string

UUID of an existing subscription to attach this one to as a child (add-on hierarchies).

propagateLifecycle

boolean

When true, pause/cancel on parentSubscriptionId cascades to this subscription. Requires parentSubscriptionId.

metadata

object

Arbitrary string key/value pairs, echoed on subscription responses and webhooks.

Show child attributes

Resposta

201 - application/json

Subscription created. Body is the Subscription plus firstInvoice, and firstCycle in record mode (what happened to cycle 1).

A customer enrollment in a plan. plan is embedded on single-subscription responses. Invoice/event history is not included here - use the invoice endpoints.

string

Subscription UUID.

merchantId

integer

The merchant account that owns the subscription.

planId

integer

ID of the plan this subscription is enrolled in.

customerEmail

string

Subscriber email, used for billing and dunning notifications.

customerName

string

Subscriber name as it appears on invoices.

customerDocument

string

Subscriber national ID / tax document, where a market requires it (e.g. Brazil CPF/CNPJ).

cardBrand

string

Brand of the card on the mandate, e.g. visa.

status

enum<string>

pending - awaiting first charge; trialing - in a free trial; active - billing normally; past_due - a renewal failed and dunning is running; suspended - dunning exhausted, needs a new CIT (POST /subscription/{id}/payment-method in CIT mode) to recover; paused - billing stopped on request, resumable; cancelled - terminated; completed - reached maxBillingCycles.

Opções disponíveis:

pending,

trialing,

active,

past_due,

suspended,

paused,

cancelled,

completed

currentPeriodStart

string<date-time>

Start of the current billing period.

currentPeriodEnd

string<date-time>

End of the current billing period.

nextBillingDate

string<date-time>

When the next renewal charge is scheduled.

trialStart

string<date-time>

Trial start, when the plan has a trial.

trialEnd

string<date-time>

Trial end - the first real charge date.

dunningAttemptCount

integer

Failed-renewal retry attempts made in the current dunning sequence.

activatedAt

string<date-time>

When the subscription first became active.

cancelledAt

string<date-time>

pausedAt

string<date-time>

suspendedAt

string<date-time>

startAt

string<date-time>

Deferred start, when creation set a future startAt.

cyclesCompleted

integer

Number of billing cycles charged so far.

completedAt

string<date-time>

When the subscription reached maxBillingCycles.

parentSubscriptionId

string

Parent subscription UUID, for add-on hierarchies.

propagateLifecycle

boolean

Whether pause/cancel on the parent cascades to this subscription.

pendingPlanId

integer

Plan the subscription will switch to at the next cycle, set by a next_billing change-plan.

createdAt

string<date-time>

updatedAt

string<date-time>

plan

object

A reusable billing plan. amount is a flat integer in the currency minor units (with separate currency + exponent) - not an Amount object.

Show child attributes

curl -X POST https://api.therius.io/v1/subscription \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "planId": 42,
    "customerEmail": "ada@example.com",
    "customerName": "Ada Lovelace",
    "card": { "nonceData": { "nonce": "<fresh nonce from JS SDK>" } }
  }'

{}

Pagamentos

Tokenização

Assinaturas

Planos

Sessão do SDK

Crie e ative uma assinatura

Modo CIT — nonceData / cardData

Modo record — tokenData

Modo record

Resposta

Status na criação

Erros

Autorizações

Corpo

Resposta

Modo CIT — nonceData / cardData

Modo record — tokenData

​Modo record

​Resposta

​Status na criação

​Erros

Autorizações

Corpo

Resposta

Modo record

Resposta

Status na criação

Erros