Skip to main content
O cliente paga com cartão de crédito Visa ou Mastercard na página de pagamento da AbacatePay (o checkout) ou num formulário dentro do seu site (o checkout transparente). O valor entra no seu saldo no prazo de recebimento que você escolheu.

Quando usar

Como ativar o cartão na sua conta

Para receber no cartão em produção, a sua conta precisa ter o cartão ativado. Quando o cartão está disponível para você, aparece no topo do dashboard a faixa Você tem acesso a cartão no checkout, com o botão Ativar agora.
1

Comece a ativação

Clique em Ativar agora e depois em Ativar Cartão.
2

Escolha o prazo de recebimento

Escolha quando quer receber as vendas no crédito e clique em Continuar. Veja Prazo de recebimento.
3

Escolha o nome na fatura

Escreva o nome que o cliente vai ler na fatura do cartão. Veja Nome na fatura.
4

Pronto

Com Cartão ativado!, seus clientes já podem pagar no cartão. Se aparecer Recebimento configurado, a adquirente ainda está analisando a sua conta: o cartão entra no checkout quando a análise terminar, sem nada a fazer.
Se a adquirente pedir mais informações, o dashboard mostra o aviso Falta pouco pra liberar o cartão. Clique em Ver o que falta e envie o que ela pediu. A ativação libera, de uma vez: cartão, Apple Pay e Google Pay no checkout, parcelamento em até 12x, assinaturas no cartão e o checkout transparente pela API. Se a faixa não aparece e o cartão não está entre os métodos de pagamento, fale com o suporte.

Como funciona o pagamento com cartão

Bandeiras aceitas

A AbacatePay aceita cartões de crédito Visa e Mastercard. Um cartão de outra bandeira é recusado com a mesma mensagem de qualquer recusa.

Autenticação 3DS

Toda compra com o cliente presente passa pela autenticação 3DS do banco emissor, no checkout e no checkout transparente. Quando o banco pede, o cliente confirma a compra (com um código por SMS ou uma aprovação no app do banco) numa janela que abre por cima da página e fecha sozinha. Você não precisa fazer nada. A cobrança de um cartão salvo, sem o cliente presente, não passa pelo 3DS. Veja One click buy.

Cartão recusado

Quando o banco recusa, a resposta é a mesma para qualquer motivo: Não foi possível processar o pagamento com este cartão. É de propósito: detalhar o motivo ajudaria quem testa cartões roubados. Peça ao cliente para conferir os dados ou usar outro cartão.

Status do pagamento

Cada pagamento de cartão tem um id card_... e um destes status: No checkout e no link de pagamento, a cobrança (bill_...) passa a PAID quando o cartão é aprovado. Os status da cobrança estão em Checkout. Para devolver o dinheiro ao cliente, veja Reembolsos. As regras do cartão mudam depois que a venda é liquidada (PAID).

Prazo de recebimento e nome na fatura

Depois da ativação, a página Financeiro → Cartão mostra como o seu cliente vê você na fatura e quando você recebe.

Prazo de recebimento

É quando o dinheiro das vendas no crédito cai na sua conta. Você escolhe na ativação e pode trocar depois: A taxa muda com o prazo, e a tela mostra a taxa de cada opção. Prazos marcados como Em breve ainda não estão abertos. Para trocar, escolha outro prazo e clique em Salvar prazo. Depois de uma troca, a próxima só fica liberada em 30 dias; a escolha feita na ativação não conta.

Nome na fatura

É o que o cliente lê na fatura do cartão. Um nome que ele reconhece evita contestação.
  • Até 15 caracteres. O banco imprime em maiúsculas, sem acento e sem espaço.
  • Antes do nome vem a identificação fixa da adquirente.
  • A tela mostra uma prévia de como fica na fatura.
Clique em Salvar nome. O nome novo vale para as próximas vendas; o que já foi cobrado continua com o nome de antes.

Pelo dashboard

  1. Vá em Sua Loja → Cobranças e clique em Criar cobrança. Para um link de pagamento, vá em Sua Loja → Links de pagamento e clique em Criar link de pagamento.
  2. Em Métodos de pagamento, selecione Cartão.
  3. Se quiser, escolha o máximo em Parcelas no cartão e ligue Repassar a taxa do cartão ao cliente.
  4. Salve e mande o link para o cliente.
No checkout, o cliente escolhe Crédito, digita o cartão, escolhe as parcelas e clica em Concluir pagamento. Acompanhe as vendas em Sua Loja → Cobranças, ou dentro do link, em Sua Loja → Links de pagamento.

Pela API

No checkout

Inclua CARD em methods ao criar o checkout. Sem methods, o checkout já oferece Pix e cartão.
O objeto card é opcional: ele define as parcelas e o repasse de taxa. Para um link de pagamento, mande o mesmo corpo para Criar link de pagamento.

No checkout transparente

O formulário de cartão fica no seu site, e o número do cartão nunca passa pelo seu servidor:
  1. O abacatepay.js, o script de cartão da AbacatePay, mostra o formulário e devolve o token ctok_.
  2. O seu backend cria a cobrança em Criar cobrança Cartão, com o ctok_ e a chave de API.
  3. A resposta traz o status e o cardToken, que cobra o mesmo cartão depois, pelo One click buy.
Para consultar uma cobrança de cartão, use GET /v2/transparents/get?id=card_... (permissão TRANSPARENT:READ) ou a listagem com method=CARD. A rota GET /v2/transparents/check é só para Pix. O checkout transparente de cartão precisa estar liberado na conta, também no Modo Teste. Sem a liberação, a API responde CARD_TRANSPARENTS is not available for this store. O passo a passo completo, com página e backend prontos para copiar, está em Checkout transparente com cartão.

Chave pública e chave de API

O checkout transparente usa duas chaves: Não há risco em expor a chave pública: quem copiar a sua pk_ consegue no máximo gerar tokens, e um token só vira cobrança quando o seu backend chama a API com a sua chave de API. Para copiar a chave pública, abra Integração → Checkout próprio e, em Sua chave pública, clique no olho para revelar ou no ícone de copiar. A página mostra a chave do ambiente em que o dashboard está, com o rótulo Teste (DEV) ou Produção. Cada loja tem uma chave pública de teste e uma de produção, e as duas começam com pk_: pelo formato não dá para saber o ambiente. Use sempre a chave pública e a chave de API do mesmo ambiente. Um token gerado com a chave pública de teste não pode ser cobrado com a chave de API de produção, e vice-versa: a cobrança falha com Invalid or expired card token. O ambiente vem da chave: se o seu site usa a chave pública de produção, o formulário é o de produção, mesmo com o Modo Teste ligado no dashboard. Para trocar de teste para produção sem mexer no código, guarde a chave pública numa variável de ambiente do backend e entregue ao navegador junto com o valor do pedido. Assim as duas chaves mudam juntas.

abacatepay.js

O abacatepay.js é o script que coloca o formulário de cartão no seu site:
  • desenha os campos do cartão num iframe seguro, e o número e o CVV nunca passam pelo seu código;
  • faz a autenticação 3DS quando o banco exige, numa janela com o título Autenticação do cartão que abre e fecha sozinha;
  • devolve o token ctok_, que o seu backend usa para criar a cobrança.
Uso básico:
Se o cliente não confirmar o 3DS, o tokenize() rejeita com o erro THREE_DS_FAILED. Opções, métodos, eventos e erros do script estão na referência do abacatepay.js.
Coloque a tag do script no index.html (no Next.js, use <Script src="https://abacatepay.com/abacatepay.js" strategy="beforeInteractive" /> no layout raiz). O componente cobra por um backend com a rota POST /pagar, como o do tutorial:
PagamentoCartao.jsx
Uso:

Notificações

No pagamento com cartão, payerInformation.method vem como "CARD", com a bandeira e o final do cartão em payerInformation.CARD (brand e number). A passagem de APPROVED para PAID não gera webhook. O cardToken não vem no webhook: guarde o que volta na resposta da cobrança. Veja como configurar em Webhooks.

Testar no Modo Teste

No Modo Teste, o cartão funciona no checkout mesmo antes da ativação, e nada é cobrado de verdade. Use os cartões de teste: o resultado depende dos 4 últimos dígitos. Com a chave pública de teste, o abacatepay.js mostra um formulário de teste, já preenchido com o cartão 4242 4242 4242 4242 e sem 3DS. O cardToken das cobranças de teste é dev_card_ mais os 4 últimos dígitos do cartão.

Perguntas frequentes

Visa e Mastercard, no crédito. Um cartão de outra bandeira é recusado com a mensagem genérica de recusa.
A mensagem é a mesma para qualquer recusa, de propósito, para não ajudar quem testa cartões roubados. Peça para o cliente conferir os dados ou usar outro cartão.
O banco ainda não respondeu. Não libere o pedido nem tente cobrar de novo: espere o webhook de pagamento aprovado.
No prazo de recebimento que você escolheu (D+1, D+7, D+15 ou D+30). Ele fica em Financeiro → Cartão.
Pode, em Financeiro → Cartão → Nome na fatura. O nome novo vale para as próximas vendas.
Pode. As regras, inclusive para a venda já liquidada, estão em Reembolsos.
Pode. Ela foi feita para isso. O que nunca pode ir para o navegador é a chave de API.
Não. É uma chave por ambiente da loja (teste e produção), e ela funciona em qualquer domínio.
Não. Ela vale até ser trocada. Se precisar de uma chave nova, fale com o suporte.
Não. As rotas da API só aceitam a chave de API. A chave pública serve apenas para o abacatepay.js.