****1111), o cliente informa só o CVV e a cobrança é feita com o identificador do cartão (cardTokenId).
Para o negócio: o cartão salvo encurta o checkout de quem compra de novo, porque o cliente não precisa digitar número, nome e validade. O CVV continua sendo pedido em toda compra: esta forma de pagamento é para compras com o cliente presente. Para cobrar automaticamente todo mês, use Assinaturas.
Quando usar
Cartão salvo ou assinatura?
Os dois usam o mesmo cartão registrado: o
id devolvido por POST /v1/cards serve tanto para a cobrança com um clique quanto para criar uma assinatura.
Como funciona
O desenho abaixo mostra as duas fases: guardar o cartão uma vez e, nas compras seguintes, cobrar pedindo só o CVV. O cadastro do cartão não tem modo de teste e não cobra nada. Com a chavesk_test_, só a cobrança da segunda fase é simulada.
1
Tenha um cartão ativo no cofre
O cartão foi registrado com
POST /v1/cards e já nasce active. O cadastro não faz nenhuma cobrança nem transação de validação. O seu sistema guardou o id do cartão e o número mascarado. Veja Cofre de cartões.2
Na recompra, peça só o CVV
O checkout mostra o cartão mascarado e o cliente digita o CVV.
3
Cobre com cardTokenId e cvv
Seu servidor chama
POST /v1/charges com paymentMethod.type credit_card, cardTokenId, cvv e installments.4
Leia o resultado na resposta
O resultado volta na resposta, como no cartão digitado:
paid, refused ou failed, com o motivo em reason.Regras de negócio
Modo Teste
Para testar uma recusa no sandbox, use a cobrança com cartão digitado e o cartão de recusa
4444333322221112.
Passo a passo
1. Confirme que o cartão pode ser usado
Antes de oferecer o cartão no checkout, liste os cartões do cliente comGET /v1/cards?customerId=... e mostre só os que estão active. A cobrança recusa cartão revoked ou expired. Use a listagem, e não a consulta individual: hoje a consulta pode mostrar active para um cartão já excluído ou vencido. Detalhes em Cofre de cartões.
2. Cobre com um clique
3. Trate o resultado
A resposta tem o mesmo formato da cobrança com cartão digitado:id, status, paymentDetails e reason. Libere o pedido só com paid. Em refused, mostre o motivo e ofereça outro cartão ou Pix. Detalhes em Cartão de crédito.
Erros comuns
Perguntas frequentes
Posso cobrar o cartão salvo sem pedir o CVV?
Posso cobrar o cartão salvo sem pedir o CVV?
Não. O CVV é obrigatório em toda cobrança com
cardTokenId. Para cobrar sem o cliente presente, use Assinaturas, que dispensam o CVV na recorrência.Posso parcelar uma compra com cartão salvo?
Posso parcelar uma compra com cartão salvo?
Sim. Envie
installments de 1 a 12, como na cobrança com cartão digitado.Uma subconta pode usar o cartão registrado pela conta master?
Uma subconta pode usar o cartão registrado pela conta master?
Não. O cartão pertence ao merchant da chave que o registrou e só pode ser usado por ele.
O cadastro do cartão cobra algum valor do cliente?
O cadastro do cartão cobra algum valor do cliente?
Não.
POST /v1/cards guarda o cartão no cofre e o registra na adquirente sem nenhuma cobrança nem transação de validação. O cartão já nasce active.Como testo sem cobrar de verdade?
Como testo sem cobrar de verdade?
Com a chave
sk_test_, a cobrança com cardTokenId é simulada e não movimenta dinheiro. O cadastro do cartão é real, mas não cobra nada. Lembre que o mesmo cardTokenId gera cobrança real com a chave de produção.Como testar
Execute o cenário SUB-02 da seção “Cartão salvo e assinaturas” do roteiro de homologação: cobrança comcardTokenId e cvv usando a chave de teste, com status paid, comprovando que o CVV é coletado a cada cobrança. O registro do cartão (SUB-01) está em Cofre de cartões.
Veja também
Cofre de cartões
Registrar, consultar, listar e excluir cartões.
Assinaturas
Cobrança recorrente sem o cliente presente.
Criar cobrança
Referência de
POST /v1/charges.Cartão de crédito
Cobrança com cartão digitado.

