Tokenização de cartão: salve cartões para pagamentos futuros

A tokenização substitui um número de cartão sem criptografia por uma referência reutilizável — um token com o prefixo vt_ — que o Therius armazena com segurança no cofre. Depois que um cartão é tokenizado, você nunca precisa coletar os dados do cartão novamente. Os tokens são restritos à sua conta do lojista, carregam metadados de BIN (bandeira, tipo e emissor do cartão) e funcionam em qualquer chamada futura de purchase ou authorization exatamente como os dados do cartão original.

Duas formas de tokenizar

1. Durante um pagamento

Adicione "tokenize": true dentro de card.cardData (ou card.nonceData se você usa o fluxo de nonce do SDK de JS), e inclua um shopper.id para associar o token a um cliente específico. O pagamento é processado normalmente, e a resposta inclui o novo token.

{
  "merchantCode": "MERCHANT_001",
  "orderCode": "ORDER-001",
  "amount": { "currency": "USD", "value": 2999, "exponent": 2 },
  "shopper": { "id": "shopper-42" },
  "card": {
    "cardData": {
      "cardNumber": "4111111111111111",
      "cardholderName": "Ada Lovelace",
      "expiryMonth": "12",
      "expiryYear": "2030",
      "cvv": "123",
      "tokenize": true
    }
  }
}

A resposta inclui um campo token ao lado dos campos normais do pagamento:

{
  "status": "captured",
  "paymentCode": "PAY-abc123",
  "token": {
    "id": "vt_4xK9mNpQ2rLsT7uV",
    "expirationDate": "2030-12-31",
    "tokenCreationReference": "PAY-abc123"
  }
}

Armazene token.id associado ao cliente no seu banco de dados. É a única coisa que você precisa para cobrá-lo novamente.

Cartões em pagamentos assíncronos

Um cartão é salvo somente quando o pagamento é aprovado. Quando o provedor responde um pagamento com cartão com pending (4ON, por exemplo), a resposta ainda não traz token: o Therius guarda o cartão criptografado até o pagamento ser resolvido e então o salva, ou o apaga se o pagamento falhar. Quando o cartão é salvo você recebe:

O webhook payment.captured (ou payment.authorized), com data.token no mesmo formato acima, quando o cartão foi salvo antes de ele ser enviado.
Um webhook token.created com data.token, data.payment_id e data.payment_code. É o confiável: armazene o token a partir dele, porque o webhook do pagamento pode ser enviado antes de o cartão ser salvo.

Veja Eventos de cartões salvos.

2. Criação de token independente

Chame POST /token para armazenar um ou mais cartões como tokens sem fazer um pagamento. É útil durante os fluxos de configuração de conta em que você quer salvar um cartão em arquivo antes da primeira compra.

{
  "merchantCode": "MERCHANT_001",
  "shopper": { "id": "shopper-42" },
  "card": {
    "cardData": {
      "cardNumber": "4111111111111111",
      "cardholderName": "Ada Lovelace",
      "expiryMonth": "12",
      "expiryYear": "2030",
      "cvv": "123"
    }
  }
}

A resposta retorna o mesmo valor token (vt_...) sem processar uma cobrança.

Usar um token em requisições futuras

Passe card.tokenData.token no lugar de card.cardData em qualquer compra ou autorização subsequente. A estrutura da requisição e a da resposta são idênticas às de um pagamento normal.

{
  "merchantCode": "MERCHANT_001",
  "orderCode": "ORDER-002",
  "amount": { "currency": "USD", "value": 2999, "exponent": 2 },
  "shopper": { "id": "shopper-42" },
  "card": {
    "tokenData": {
      "token": "vt_4xK9mNpQ2rLsT7uV"
    }
  }
}

CVV em cartões tokenizados

Opcionalmente você pode incluir card.tokenData.cvv ao cobrar um token. Alguns adquirentes exigem o CVV para as transações iniciadas pelo titular (CIT) mas não para as transações iniciadas pelo lojista (MIT) nem para as cobranças recorrentes.

{
  "card": {
    "tokenData": {
      "token": "vt_4xK9mNpQ2rLsT7uV",
      "cvv": "123"
    }
  }
}

Se você está executando uma assinatura ou uma nova tentativa automatizada, omita o CVV — o cliente não está presente para fornecê-lo.

Tokenização de carteira

Os métodos de pagamento Apple Pay e Google Pay também podem ser salvos para uso recorrente. Adicione "tokenize": true e um shopper.id dentro do objeto walletData.

{
  "shopper": { "id": "shopper-42" },
  "card": {
    "walletData": {
      "type": "apple_pay",
      "token": "<wallet payment token from device>",
      "tokenize": true
    }
  }
}

O token vt_... resultante se comporta de forma idêntica a um token de cartão em requisições futuras.

Tokenização de ACH

Os dados de conta bancária enviados por ACH podem ser tokenizados da mesma forma. Adicione "tokenize": true dentro do objeto apm.

{
  "shopper": { "id": "shopper-42" },
  "apm": {
    "type": "ach",
    "accountNumber": "123456789",
    "routingNumber": "021000021",
    "tokenize": true
  }
}

A resposta retorna um token vt_... que você pode usar em cobranças de ACH futuras sem pedir os dados da conta bancária ao cliente novamente.

Ciclo de vida do token

Um token pode estar active, deleted, erased ou expired. Consulte-o a qualquer momento com GET /token/{token}.

Status	O que significa	Pode ser cobrado?
`active`	O cartão está salvo e em uso.	Sim.
`deleted`	O cliente removeu o cartão, um agente de suporte o excluiu, um salvamento mais recente do mesmo cartão o substituiu, ou o Therius o retirou (veja abaixo).	Sim, até que os dados do cartão sejam apagados. A resposta traz o cabeçalho `X-Therius-Token-Status: deleted`.
`erased`	Os dados do cartão foram apagados permanentemente conforme a política de retenção.	Não.
`expired`	A data de expiração do próprio token passou.	Não.

Quando os dados do cartão são apagados

O Therius não guarda dados de cartão para sempre. Os prazos abaixo são os valores padrão da plataforma; erasesAt no endpoint de status sempre mostra a data que vale para um token.

Um cartão excluído é apagado 2 anos depois da mais recente entre a exclusão, o último pagamento e o fim da última assinatura que o usou. Se o token for usado de novo, essa data muda.
Um cartão que ninguém excluiu é retirado quando venceu há mais de 30 dias, ou quando nenhum pagamento foi feito com ele por 18 meses. Um cartão retirado passa a deleted com deletedReason expired ou unused, você recebe token.deleted e os dados dele são apagados 30 dias depois.
Um cartão que uma assinatura ativa ou um beneficiário de repasses ainda usa nunca é retirado nem apagado.

Apagar remove o número do cartão criptografado, o token de rede e os dados de conta bancária, e exclui o cartão no provedor de cofre de cartões do Therius. A bandeira, os quatro últimos dígitos e a validade permanecem, então pagamentos antigos continuam mostrando “Visa ••••4242”. O token em si também permanece, então as suas referências a ele nunca ficam soltas.

Como saber quando um token deixa de funcionar

Webhooks: token.deleted quando um cartão é excluído ou retirado, token.erased quando os dados dele são apagados, e subscription.payment_method_removed quando um cliente exclui o cartão em que uma assinatura renova. Veja Eventos de webhook.
Erros: cobrar um token que não pode mais ser cobrado retorna 400 com um code em que você pode basear a sua lógica.

`code`	Significado	O que fazer
`token_erased`	Os dados do cartão foram apagados.	Peça um novo cartão ao cliente.
`token_expired`	A data de expiração do token passou.	Peça um novo cartão ao cliente.
`token_not_found`	Não existe esse token na sua conta de lojista.	Confira o valor que você guardou.

Uma assinatura continua cobrando o cartão depois que o cliente o remove dos cartões salvos, até que você substitua a forma de pagamento com Atualizar método de pagamento. Use subscription.payment_method_removed para pedir um novo cartão ao cliente a tempo.

Segurança

Os tokens do Therius são seguros para PCI. Um token vt_... só é utilizável dentro do cofre do Therius e somente pela sua conta do lojista. Ele não pode ser usado para recuperar o número do cartão sem criptografia, e nenhum sistema de pagamento externo o aceita. Armazenar tokens em vez de dados de cartão significa que seu banco de dados fica fora do escopo dos requisitos de PCI DSS relacionados a PANs.

Primeiros passos

Conceitos básicos

Guias

Webhooks

Assistente de IA

Plugins de e-commerce

Tokenização de cartão: salve cartões para pagamentos futuros

Duas formas de tokenizar

1. Durante um pagamento

Cartões em pagamentos assíncronos

2. Criação de token independente

Usar um token em requisições futuras

CVV em cartões tokenizados

Tokenização de carteira

Tokenização de ACH

Ciclo de vida do token

Quando os dados do cartão são apagados

Como saber quando um token deixa de funcionar

Segurança

​Duas formas de tokenizar

​1. Durante um pagamento

​Cartões em pagamentos assíncronos

​2. Criação de token independente

​Usar um token em requisições futuras

​CVV em cartões tokenizados

​Tokenização de carteira

​Tokenização de ACH

​Ciclo de vida do token

​Quando os dados do cartão são apagados

​Como saber quando um token deixa de funcionar

​Segurança

Duas formas de tokenizar

1. Durante um pagamento

Cartões em pagamentos assíncronos

2. Criação de token independente

Usar um token em requisições futuras

CVV em cartões tokenizados

Tokenização de carteira

Tokenização de ACH

Ciclo de vida do token

Quando os dados do cartão são apagados

Como saber quando um token deixa de funcionar

Segurança