Actualiza el método de pago de una suscripción

POST

subscription

{id}

payment-method

curl -X POST https://api.therius.io/v1/subscription/sub_abc123def456/payment-method \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "card": { "tokenData": { "token": "vt_9f2c..." } }
  }'

curl -X POST https://api.therius.io/v1/subscription/sub_abc123def456/payment-method \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "card": { "nonceData": { "nonce": "<fresh nonce from JS SDK>" } }
  }'

{}

POST /subscription/{id}/payment-method reemplaza la tarjeta de una suscripción y su mandato de credencial almacenada, de modo que cada futura renovación (una Merchant Initiated Transaction, MIT) cite el networkTransactionId / networkReferenceId correcto. Cambiar la tarjeta de una suscripción es siempre una Cardholder Initiated Transaction (CIT), y una CIT puede requerir 3D Secure. Hay dos formas de suministrar la nueva tarjeta:

Modo record — card.tokenData

El token es una tarjeta que ya completó una CIT en otro lugar. Tú ejecutas la CIT (con 3DS si el emisor lo pide) a través de /payment/authorization o /payment/purchase, luego adjuntas el token resultante aquí. Sin llamada al gateway, sin 3DS en este endpoint. Usa esto para cualquier tarjeta que necesite 3D Secure.

Modo CIT — card.nonceData / card.cardData

Ejecuta una CIT de valor cero aquí para validar la tarjeta y establecer un mandato fresco, y puede reactivar una suscripción suspended. Esta CIT no puede llevar a cabo un desafío de 3D Secure — una tarjeta que requiere 3DS fallará.

Cualquiera de los dos modos reinicia la secuencia de reintentos de la bandera y dispara subscription.payment_method_updated.

Modo record (recomendado)

Como la propia CIT de este endpoint no puede hacer un desafío de 3DS, la forma confiable de cambiar una tarjeta es ejecutar tú mismo la CIT donde 3DS sí está soportado, luego registrarla:

Ejecuta una CIT con capacidad 3DS

Llama a /payment/authorization (una autorización de valor cero o pequeña) o /payment/purchase con card.nonceData.tokenize: true (o card.cardData.tokenize: true) y un shopper.id. Maneja cualquier actionRequired / desafío de 3DS con el SDK JS exactamente como lo harías para un pago normal. En caso de éxito la respuesta devuelve un vault token y card.networkTransactionId / card.networkReferenceId.

Adjunta el token a la suscripción

POST /subscription/{id}/payment-method con card.tokenData.token establecido en ese vault token. Therius lee el mandato que el token almacenó en su CIT — no necesitas pasar networkTransactionId tú mismo. (Pásalo explícitamente solo cuando la tarjeta fue CIT’ada fuera de Therius.)

El modo record no puede reactivar una suscripción suspended — no ejecuta ningún cobro para confirmar que la nueva tarjeta funciona. Para una suscripción suspendida, usa el modo CIT (abajo), o ejecuta un cobro de recuperación tú mismo primero.

Proporciona exactamente un instrumento de tarjeta — ver el panel de parámetros de arriba para la lista completa de campos (tokenData.token para modo record; nonceData/cardData para modo CIT; networkTransactionId/networkReferenceId opcionales para una tarjeta CIT’ada fuera de Therius).

Respuesta

Devuelve 200 OK con el objeto de suscripción actualizado.

Eventos de webhook disparados

Evento	Cuándo
`subscription.payment_method_updated`	Siempre, en caso de éxito. La carga lleva `mode: "record"` para el modo record.
`subscription.reactivated`	Solo en modo CIT — se dispara adicionalmente cuando la suscripción estaba `suspended` y la nueva CIT + el cobro de recuperación tuvieron éxito.

Errores

Código	Significado
`400`	Falta la tarjeta; modo record en una suscripción `suspended`; el token no lleva ningún mandato de CIT y no se pasó ningún `networkTransactionId`; o la suscripción está `cancelled`.
`402`	Modo CIT — la autorización de la tarjeta fue rechazada.
`404`	Suscripción no encontrada.
`422`	Ningún instrumento de tarjeta / instrumento inválido, o un nonce expirado/usado.

curl -X POST https://api.therius.io/v1/subscription/sub_abc123def456/payment-method \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "card": { "tokenData": { "token": "vt_9f2c..." } }
  }'

curl -X POST https://api.therius.io/v1/subscription/sub_abc123def456/payment-method \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "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).

Parámetros de ruta

string

requerido

Cuerpo

application/json

merchantCode

string

requerido

Your merchant account identifier.

card

Raw card (PCI DSS) · object

requerido

Card input for replacing the card on a subscription. Changing the card is always a CIT and a CIT may require 3D Secure — pick the mode that fits:

• Record mode (tokenData): the token is a card that already completed a CIT elsewhere. Run your own 3DS-capable CIT via /payment/authorization or /payment/purchase (with card.<x>.tokenize: true + shopper.id), then attach the resulting vt_... token here. No gateway call, no 3DS. The mandate is read from the token; pass networkTransactionId / networkReferenceId explicitly only for a card CIT'd outside Therius. Cannot reactivate a suspended subscription.

• CIT mode (nonceData / cardData): runs a zero-value CIT here and can reactivate a suspended subscription — but this CIT cannot carry out a 3D Secure challenge, so a card that requires 3DS will fail. Use record mode for those.

Provide exactly ONE of cardData, nonceData, or tokenData.

Raw card (PCI DSS)
SDK nonce
Vault token

Show child attributes

Respuesta

200 - application/json

Payment method updated

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/sub_abc123def456/payment-method \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "card": { "tokenData": { "token": "vt_9f2c..." } }
  }'

curl -X POST https://api.therius.io/v1/subscription/sub_abc123def456/payment-method \
  -H "Authorization: Bearer prv_production_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantCode": "MERCHANT_001",
    "card": { "nonceData": { "nonce": "<fresh nonce from JS SDK>" } }
  }'

{}

Pagos

Tokenización

Suscripciones

Planes

Sesión del SDK

Actualiza el método de pago de una suscripción

Modo record — card.tokenData

Modo CIT — card.nonceData / card.cardData

Modo record (recomendado)

Respuesta

Eventos de webhook disparados

Errores

Autorizaciones

Parámetros de ruta

Cuerpo

Respuesta

Modo record — card.tokenData

Modo CIT — card.nonceData / card.cardData

​Modo record (recomendado)

​Respuesta

​Eventos de webhook disparados

​Errores

Autorizaciones

Parámetros de ruta

Cuerpo

Respuesta

Modo record (recomendado)

Respuesta

Eventos de webhook disparados

Errores