> ## Documentation Index > Fetch the complete documentation index at: https://docs.therius.io/llms.txt > Use this file to discover all available pages before exploring further. # Cobre cartões salvos usando credenciais armazenadas e MIT > Use credenciais armazenadas para cobrar clientes sem que estejam presentes — faturamento recorrente, parcelas e pagamentos MIT não programados com o Therius. 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. 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. 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. | Campo | Valores | Obrigatório em | | ----------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------- | | `initiatedBy` | `"cardholder"` \| `"merchant"` | CIT + MIT | | `type` | `"recurring"` \| `"installment"` \| `"unscheduled"` | CIT + MIT | | `usage` | `"first"` \| `"subsequent"` | CIT + MIT | | `exceptionReason` | `"resubmission"` \| `"incremental"` \| `"reauthorization"` \| `"delayed_charge"` \| `"no_show"` | Somente MIT, e apenas quando aplicável | `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: | Valor | Significado | Exemplo | | ----------------- | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | `resubmission` | Nova tentativa de uma cobrança previamente recusada de forma leve (fundos insuficientes, não honrar) pelo mesmo valor | Uma renovação de assinatura tentada novamente no dia seguinte após uma recusa `51` | | `incremental` | Um acréscimo de autorização sobre um mandato existente | Um folio de hotel adiciona uma cobrança de serviço de quarto antes do checkout | | `reauthorization` | Uma nova autorização porque a original expirou antes da captura | Mercadoria ainda não enviada quando a janela de autorização inicial expira | | `delayed_charge` | O valor final difere de uma estimativa ou retenção anterior | Quilometragem extra de aluguel de carro; uma gorjeta adicionada após a refeição | | `no_show` | O portador do cartão não compareceu a uma reserva garantida | Uma taxa de não comparecimento em hotel | *** ## 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`. ```json theme={"dark"} POST /payment/purchase { "merchantCode": "MERCHANT_001", "orderCode": "ORDER-CIT-001", "amount": { "currency": "USD", "value": 1999, "exponent": 2 }, "card": { "cardData": { "cardNumber": "4111111111111111", "expiryMonth": "12", "expiryYear": "2027", "cvv": "123", "tokenize": true }, "cardOnFile": { "initiatedBy": "cardholder", "type": "recurring", "usage": "first" } }, "shopper": { "id": "customer-42" } } ``` Da resposta, salve estes dois campos no seu banco de dados — vinculados ao vault token do cliente: ```json theme={"dark"} { "card": { "token": "vt_a1b2c3d4e5", "networkTransactionId": "016153570XXXXXX", "networkReferenceId": "MCC000XXXXXXXXXXXX" } } ``` *** ## 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. ```json theme={"dark"} POST /payment/purchase { "merchantCode": "MERCHANT_001", "orderCode": "ORDER-SAVE-003", "amount": { "currency": "USD", "value": 1999, "exponent": 2 }, "card": { "cardData": { "cardNumber": "4111111111111111", "expiryMonth": "12", "expiryYear": "2027", "cvv": "123", "tokenize": true }, "cardOnFile": { "initiatedBy": "cardholder", "type": "unscheduled", "usage": "first" } }, "shopper": { "id": "customer-42" } } ``` 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. ```json theme={"dark"} POST /payment/purchase { "merchantCode": "MERCHANT_001", "orderCode": "ORDER-MIT-002", "amount": { "currency": "USD", "value": 1999, "exponent": 2 }, "card": { "tokenData": { "token": "vt_a1b2c3d4e5" }, "cardOnFile": { "initiatedBy": "merchant", "type": "recurring", "usage": "subsequent" }, "networkTransactionId": "016153570XXXXXX", "networkReferenceId": "MCC000XXXXXXXXXXXX" } } ``` 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](/pt/sdk/session-bootstrap#assinaturas-gerenciadas-pelo-lojista). *** ## Tipos de credencial 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. 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. 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](#o-objeto-cardonfile) 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.