Skip to main content
Esta página trata da cobrança com um cartão que já está guardado. O cadastro e a gestão dos cartões (registrar, consultar status, listar e excluir) estão em Cofre de cartões. Com o cartão salvo, o cliente digita os dados do cartão uma única vez. Nas compras seguintes, o seu checkout mostra o cartão mascarado (ex.: ****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.
O cofre de cartões é o mesmo para teste e produção. Um cardTokenId criado durante a homologação também funciona com a chave de produção, e aí a mesma chamada cobra de verdade. Controle no seu sistema qual chave cada ambiente usa.

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 chave sk_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

A cobrança com cartão salvo não acontece com o cliente ausente. Se o seu modelo é cobrar todo mês sem o cliente digitar o CVV, use Assinaturas.
Para o desenvolvedor: não armazene o CVV. Peça ao cliente que digite o código a cada compra e envie direto na requisição.

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 com GET /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

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.
Sim. Envie installments de 1 a 12, como na cobrança com cartão digitado.
Não. O cartão pertence ao merchant da chave que o registrou e só pode ser usado por ele.
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.
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 com cardTokenId 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.