Skip to main content
As credenciais armazenadas — também chamadas de Merchant Initiated Transactions (MIT) — permitem cobrar o cartão salvo de um cliente em qualquer momento depois que ele tenha autorizado você explicitamente a fazê-lo. Casos de uso comuns incluem renovações de assinatura, planos de parcelamento e cobranças não programadas, como o faturamento por uso. As regras das bandeiras de cartão (Visa, Mastercard e outras) exigem que você declare o tipo de uso da credencial tanto na cobrança inicial quanto em toda cobrança posterior. O Therius passa essa informação diretamente às redes de cartão em seu nome, mas você precisa fornecer os campos corretos.

​
CIT vs. MIT

Toda relação de credencial armazenada começa com uma Customer Initiated Transaction (CIT), durante a qual o cliente está presente e autoriza explicitamente as cobranças futuras.

CIT — cliente presente

O cliente está concluindo ativamente o checkout. Você coleta o cartão via um nonce novo (ou número de cartão bruto) e define cardOnFile.usage: "first". A resposta devolve card.networkTransactionId e card.networkReferenceId — salve os dois valores no seu banco de dados. Você vai precisar deles para toda MIT posterior.

MIT — iniciada pelo lojista

O cliente não está presente. Você passa o vault token salvo mais os campos de credencial armazenada, incluindo o networkTransactionId e o networkReferenceId da CIT original. As redes de cartão usam essas referências para vincular a cobrança ao mandato autorizado.

​
O objeto cardOnFile

Adicione um bloco cardOnFile dentro do objeto card tanto na CIT quanto em toda MIT. O próprio cardOnFile é opcional (o Therius deriva um padrão a partir do contexto — um tokenize novo versus uma reutilização de tokenData — quando omitido), mas, uma vez enviado, usage, initiatedBy e type são os três campos que juntos classificam a cobrança para as redes de cartão.
initiatedBy usa "cardholder", não "customer" — corresponda ao valor exato do enum.
exceptionReason é opcional e ocupa um eixo próprio, independente de type — não substitui type, adiciona um rótulo de exceção de negócio por cima. A maioria das cobranças MIT posteriores nunca o envia; defina-o apenas quando a cobrança específica se enquadrar em uma destas categorias definidas pela bandeira:

​
Exemplo de CIT inicial

Colete o cartão normalmente (usando um nonce do SDK ou dados de cartão brutos em um servidor em conformidade com PCI), tokenize-o definindo tokenize: true, e inclua o bloco cardOnFile.
Da resposta, salve estes dois campos no seu banco de dados — vinculados ao vault token do cliente:

​
Salvando um cartão sem conhecer o padrão de cobrança futuro

Se você está salvando no vault um cartão e ainda não sabe se ele vai virar uma assinatura recorrente, um plano de parcelas ou uma cobrança única não programada, declare-o como "type": "unscheduled" — a categoria que as redes de cartão reservam para “uso futuro autorizado pelo portador, padrão ainda não determinado”. Salve o networkTransactionId/networkReferenceId retornados de qualquer forma; você vai precisar deles seja qual for a MIT que enviar no futuro.
Se o cartão só for reutilizado em um futuro checkout com o cliente presente — o cliente o escolhe entre seus métodos salvos e confirma a cobrança ele mesmo, nunca cobrado sem presença por você — você não precisa de nenhum bloco cardOnFile. Basta enviar tokenize: true com shopper.id. cardOnFile só importa quando uma MIT vai acontecer.

​
Exemplo de MIT posterior — renovação recorrente

Em toda cobrança posterior — uma renovação, uma parcela, um acréscimo não programado — passe o vault token mais os campos de credencial armazenada e as referências de rede da CIT original. Este exemplo mostra uma renovação recorrente (estilo assinatura); troque type por installment ou unscheduled para corresponder ao mandato estabelecido na CIT.
O motor de assinaturas do Therius gerencia as credenciais armazenadas internamente para todas as renovações de assinatura. Você nunca precisa fornecer cardOnFile nem campos de referência de rede ao usar a API de assinaturas — este guia só é relevante se você estiver construindo a sua própria lógica de faturamento fora do motor de assinaturas.
Se o seu CIT inicial passa pelo Checkout Widget em vez de uma chamada direta à API, você não precisa construir esse bloco cardOnFile manualmente — passe-o uma vez ao criar a sessão do SDK (POST /sdk/session’s cardOnFile). O widget então mostra um aviso de “o cartão será salvo” e o servidor aplica a marcação de credencial armazenada e a tokenização para você. Veja Assinaturas gerenciadas pelo lojista.

​
Tipos de credencial

Recorrente

Use "type": "recurring" para cobranças de valor fixo que se repetem em um cronograma previsível — mensalidades de SaaS, renovações anuais, taxas de associação.

Parcela

Use "type": "installment" quando um cliente autoriza um pagamento dividido em um número fixo de cobranças — por exemplo, três pagamentos mensais por uma única compra.

Não programada

Use "type": "unscheduled" para cobranças que são autorizadas com antecedência mas disparadas por um evento definido pelo lojista — faturamento por uso, recargas de conta, taxas de conveniência, ou um cartão salvo para uso futuro antes de conhecer seu padrão definitivo.
Veja Motivos de exceção acima para exceptionReason — um eixo separado e opcional de type, usado apenas quando uma MIT específica se enquadra em uma categoria de exceção definida pela bandeira.
As regras das bandeiras de cartão exigem uma declaração CIT/MIT precisa em toda transação. Classificar mal uma cobrança — por exemplo, enviar uma MIT sem o networkTransactionId original — pode resultar em taxas de recusa maiores, chargebacks ou penalidades do adquirente. Em caso de dúvida, entre em contato com o suporte do Therius antes de entrar em produção com um novo modelo de faturamento.