Crea y activa una suscripción

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 inscribe a un cliente en un plan y establece el mandato recurrente que ancla cada futura Merchant Initiated Transaction (MIT). Inscribir a un cliente es una Cardholder Initiated Transaction (CIT), y una CIT puede requerir 3D Secure. Dos modos:

Modo CIT — nonceData / cardData

Therius ejecuta la CIT inicial + el primer cobro aquí. El cliente debe estar presente. Esta CIT no puede llevar a cabo un desafío de 3D Secure — una tarjeta que requiere 3DS fallará.

Modo record — tokenData

El token es una tarjeta que ya completó una CIT (incluyendo 3DS) a través de /payment/authorization o /payment/purchase. No se ejecuta una segunda CIT aquí. Usa esto para cualquier tarjeta que necesite 3D Secure.

Suministra la tarjeta como exactamente un instrumento — nonceData, cardData (solo servidores que cumplen PCI DSS), o tokenData.

cardOnFile e instalments se ignoran aquí — Therius es dueño del mandato. En modo record networkTransactionId / networkReferenceId se leen del token; pásalos solo para una tarjeta CIT’ada fuera de Therius.

Modo record

Ejecuta tú mismo una CIT con capacidad 3DS, luego adjunta el resultado:

Ejecuta la CIT vía /payment/*

Llama a /payment/authorization (monto 0 = verificación de cuenta) o /payment/purchase con card.<x>.tokenize: true + un shopper.id, y maneja cualquier desafío de 3DS con el SDK JS como lo harías para un pago normal. La respuesta devuelve un token vt_....

Crea la suscripción

POST /subscription con card.tokenData.token. Para el ciclo 1:
• prueba o startAt diferido → no se cobra nada;
• cobraste el primer ciclo en tu CIT (/payment/purchase) → pasa también firstPaymentId (el id de pago de la respuesta de esa llamada); Therius marca la primera factura como pagada y la enlaza, sin cobro;
• tu CIT fue una verificación de valor cero → omite firstPaymentId; Therius cobra el ciclo 1 como una MIT contra el mandato registrado (revierte la suscripción con un 402 si se rechaza).
El objeto firstCycle de la respuesta informa lo que ocurrió.

Ver el panel de parámetros de arriba para la lista completa de campos — planId, customerEmail y un instrumento de tarjeta (nonceData/cardData/tokenData — exactamente uno) son obligatorios; customerName/customerDocument, firstPaymentId (modo record), startAt, parentSubscriptionId/propagateLifecycle y metadata son opcionales.

Respuesta

Una solicitud exitosa devuelve 201 Created con el objeto de suscripción completo, incluyendo el id de la suscripción, el status inicial, las fechas de inicio y fin del período actual, y la primera factura.

Estado en la creación

Estado	Cuándo ocurre
`active`	El plan no tiene prueba; el primer cobro tuvo éxito.
`trialing`	El plan tiene un `trialPeriodDays` configurado.
`past_due`	La CIT inicial falló. Raro — normalmente se devuelve un `402` en el rechazo en su lugar.

Errores

Código	Significado
`400`	Plan no encontrado o inactivo; o (modo record) el token no lleva ningún mandato de CIT, o `firstPaymentId` no se resuelve a un pago liquidado que cobró este token.
`402`	El cobro de la CIT inicial fue rechazado (modo CIT), o la MIT del primer ciclo fue rechazada (modo record — la suscripción se revierte).
`409`	`Idempotency-Key` duplicado con un cuerpo de solicitud en conflicto.
`422`	Error de validación — p. ej. no se proporcionó ningún instrumento de tarjeta, un nonce expirado/usado, o un plan 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>" } }
  }'

{}

Autorizaciones

Authorization

string

header

requerido

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

Cuerpo

application/json

merchantCode

string

requerido

Your merchant account identifier.

planId

integer

requerido

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

customerEmail

string

requerido

Subscriber email. Used for billing and dunning notifications.

card

Raw card (PCI DSS) · object

requerido

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

Respuesta

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.

Opciones disponibles:

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

{}

Pagos

Tokenización

Suscripciones

Planes

Sesión del SDK

Crea y activa una suscripción

Modo CIT — nonceData / cardData

Modo record — tokenData

Modo record

Respuesta

Estado en la creación

Errores

Autorizaciones

Cuerpo

Respuesta

Modo CIT — nonceData / cardData

Modo record — tokenData

​Modo record

​Respuesta

​Estado en la creación

​Errores

Autorizaciones

Cuerpo

Respuesta

Modo record

Respuesta

Estado en la creación

Errores