Testando pagamento com cartão de crédito
Utilize cartões de teste para validar cobranças com cartão de crédito sem movimentar valores reais.
Neste fluxo, você pode testar aprovações, recusas, respostas da API e o processamento dos Webhooks relacionados à cobrança.
Ao concluir este guia, você terá testado os cenários de aprovação e recusa de uma cobrança com cartão de crédito.
Quando utilizar
Use este fluxo para homologar:
- cobranças avulsas;
- assinaturas e recorrências;
- tokenização de cartões;
- checkout próprio;
- tratamento de aprovações e recusas;
- atualizações recebidas por Webhook.
Antes de começar
Você precisa:
- Ter uma conta e uma chave de API de Sandbox.
- Criar um cliente para vincular à cobrança.
- Configurar os Webhooks utilizados pela integração.
- Utilizar o endpoint de cobrança com cartão de crédito.
Consulte Criar cobrança com cartão de crédito.
Utilize somente cartões e dados fictícios.
Nunca use informações reais de clientes durante a homologação.
1. Crie a cobrança
Na requisição, informe os dados do cliente, da cobrança e do cartão.
Os principais campos são:
| Campo | Finalidade |
|---|---|
customer | ID do cliente vinculado à cobrança |
billingType | Deve ser CREDIT_CARD |
value | Valor da cobrança |
dueDate | Data de vencimento |
creditCard | Dados do cartão utilizado |
creditCardHolderInfo | Dados do titular do cartão |
Consulte a referência do endpoint para conhecer todos os campos e regras de preenchimento.
2. Simule uma aprovação
Utilize os dados abaixo:
| Informação | Valor |
|---|---|
| Número do cartão | 4444 4444 4444 4444 |
| Validade | Qualquer data futura |
| CCV | 123 ou outro número com três dígitos |
O Sandbox deverá simular o processamento bem-sucedido da cobrança.
3. Simule uma recusa
Utilize um dos cartões abaixo:
| Bandeira | Número |
|---|---|
| Mastercard | 5184019740373151 |
| Visa | 4916561358240741 |
Esses números permitem testar o tratamento de falhas no processamento.
4. Valide o resultado
Após enviar a requisição:
- confira o status HTTP e o corpo da resposta;
- armazene o ID da cobrança;
- acompanhe o status da cobrança;
- receba o Webhook correspondente;
- confirme se sua aplicação processou o resultado corretamente.
Criar cliente
↓
Criar cobrança com cartão
↓
Receber resposta da API
↓
Receber Webhook
↓
Atualizar o status na aplicaçãoNão utilize somente a resposta síncrona para concluir o processamento.
Considere também os eventos recebidos por Webhook e as alterações posteriores no status da cobrança.
Comportamento esperado
No Sandbox:
- os cartões de teste determinam o resultado simulado;
- nenhuma adquirente é acionada;
- nenhum valor real é movimentado;
- os retornos servem exclusivamente para homologação.
Teste, no mínimo:
| Cenário | O que validar |
|---|---|
| Aprovação | Atualização da cobrança e processamento do Webhook |
| Recusa | Mensagem retornada e tratamento da falha |
| Webhook repetido | Processamento idempotente |
| Erro inesperado | Logs, alertas e comportamento da aplicação |
Diferenças entre Sandbox e Produção
| Sandbox | Produção |
|---|---|
| Utiliza cartões de teste | Utiliza cartões reais |
| Simula aprovações e recusas | Depende do processamento real |
| Não movimenta valores | Movimenta valores reais |
| Não aciona adquirentes | Depende das operadoras e adquirentes |
A aprovação de um cartão no Sandbox não garante que uma transação semelhante será aprovada em Produção.
Checklist de homologação
Antes de considerar o fluxo homologado, confirme se sua aplicação:
- trata aprovações e recusas;
- processa os Webhooks de forma idempotente;
- registra os IDs e horários das operações;
- não armazena dados sensíveis de cartão;
- apresenta mensagens adequadas ao pagador;
- possui logs e monitoramento;
- está preparada para respostas diferentes em Produção.
Próximos passos
Updated 13 days ago