Atualize o método de pagamento de uma assinatura

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 substitui o cartão de uma assinatura e o mandato de credencial armazenada dela, de modo que toda futura renovação (uma Merchant Initiated Transaction, MIT) cite o networkTransactionId / networkReferenceId correto. Mudar o cartão de uma assinatura é sempre uma Cardholder Initiated Transaction (CIT), e uma CIT pode exigir 3D Secure. Há duas formas de fornecer o novo cartão:

Modo record — card.tokenData

O token é um cartão que já concluiu uma CIT em outro lugar. Você executa a CIT (com 3DS se o emissor pedir) por meio de /payment/authorization ou /payment/purchase, depois anexa o token resultante aqui. Nenhuma chamada ao gateway, nenhum 3DS neste endpoint. Use isto para qualquer cartão que precise de 3D Secure.

Modo CIT — card.nonceData / card.cardData

Executa uma CIT de valor zero aqui para validar o cartão e estabelecer um mandato novo, e pode reativar uma assinatura suspended. Essa CIT não pode realizar um desafio de 3D Secure — um cartão que exige 3DS falhará.

Qualquer um dos modos reinicia a sequência de novas tentativas da bandeira e dispara subscription.payment_method_updated.

Modo record (recomendado)

Como a própria CIT deste endpoint não pode fazer um desafio de 3DS, a forma confiável de mudar um cartão é executar você mesmo a CIT onde 3DS é suportado, depois registrá-la:

Execute uma CIT com capacidade 3DS

Chame /payment/authorization (uma autorização de valor zero ou pequena) ou /payment/purchase com card.nonceData.tokenize: true (ou card.cardData.tokenize: true) e um shopper.id. Trate qualquer actionRequired / desafio de 3DS com o SDK JS exatamente como você faria para um pagamento normal. Em caso de sucesso a resposta devolve um vault token e card.networkTransactionId / card.networkReferenceId.

Anexe o token à assinatura

POST /subscription/{id}/payment-method com card.tokenData.token definido como esse vault token. O Therius lê o mandato que o token armazenou na CIT dele — você não precisa passar networkTransactionId você mesmo. (Passe-o explicitamente apenas quando o cartão teve a CIT feita fora do Therius.)

O modo record não pode reativar uma assinatura suspended — ele não executa nenhuma cobrança para confirmar que o novo cartão funciona. Para uma assinatura suspensa, use o modo CIT (abaixo), ou execute uma cobrança de recuperação você mesmo primeiro.

Forneça exatamente um instrumento de cartão — veja o painel de parâmetros acima para a lista completa de campos (tokenData.token para modo record; nonceData/cardData para modo CIT; networkTransactionId/networkReferenceId opcionais para um cartão cuja CIT foi feita fora do Therius).

Resposta

Devolve 200 OK com o objeto de assinatura atualizado.

Eventos de webhook disparados

Evento	Quando
`subscription.payment_method_updated`	Sempre, em caso de sucesso. A carga leva `mode: "record"` para o modo record.
`subscription.reactivated`	Apenas no modo CIT — disparado adicionalmente quando a assinatura estava `suspended` e a nova CIT + a cobrança de recuperação tiveram sucesso.

Erros

Código	Significado
`400`	Cartão ausente; modo record em uma assinatura `suspended`; o token não carrega nenhum mandato de CIT e nenhum `networkTransactionId` foi passado; ou a assinatura está `cancelled`.
`402`	Modo CIT — a autorização do cartão foi recusada.
`404`	Assinatura não encontrada.
`422`	Nenhum instrumento de cartão / instrumento inválido, ou um 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>" } }
  }'

{}

Autorizações

Authorization

string

header

obrigatório

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

Parâmetros de caminho

string

obrigatório

Corpo

application/json

merchantCode

string

obrigatório

Your merchant account identifier.

card

Raw card (PCI DSS) · object

obrigatório

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

Resposta

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.

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

{}

Pagamentos

Tokenização

Assinaturas

Planos

Sessão do SDK

Atualize o método de pagamento de uma assinatura

Modo record — card.tokenData

Modo CIT — card.nonceData / card.cardData

Modo record (recomendado)

Resposta

Eventos de webhook disparados

Erros

Autorizações

Parâmetros de caminho

Corpo

Resposta

Modo record — card.tokenData

Modo CIT — card.nonceData / card.cardData

​Modo record (recomendado)

​Resposta

​Eventos de webhook disparados

​Erros

Autorizações

Parâmetros de caminho

Corpo

Resposta

Modo record (recomendado)

Resposta

Eventos de webhook disparados

Erros