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.
Atenção: 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
Para simular uma transação aprovada no Sandbox, utilize um dos cartões de teste indicados abaixo.
Esses números são fictícios e destinados exclusivamente à homologação de integrações.
| Bandeira | Número do cartão |
|---|---|
| Visa | 4539 6560 4839 2220 |
| Mastercard | 5263 8372 5327 8275 |
| American Express | 3471 756966 23141 |
| Discover | 6011 6650 7493 0565 |
Para realizar os testes, utilize os seguintes dados:
| Informação | Valor |
|---|---|
| Número do cartão | Um dos cartões de teste da tabela acima |
| Validade | Qualquer data futura |
| CCV | Código de segurança fictício, conforme a quantidade de dígitos da bandeira |
| Nome do titular | Nome fictício |
O Sandbox deverá simular o processamento bem-sucedido da cobrança para os cartões de aprovação validados.
Atenção: Utilize exclusivamente dados fictícios durante os testes. Não informe números de cartões reais no ambiente Sandbox, mesmo que pertençam a você.
3. Simule uma recusa
Para validar o tratamento de transações recusadas, utilize um dos cartões de teste abaixo:
| Bandeira | Número do cartão |
|---|---|
| Mastercard | 5184019740373151 |
| Visa | 4916561358240741 |
Esses números permitem testar o tratamento de falhas no processamento, incluindo as respostas retornadas pela API e o comportamento da integração diante de uma cobrança recusada.
Utilize uma data de validade futura e um código de segurança fictício para completar os dados do cartão.
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.
Fluxo de validação:
Criar cliente
↓
Criar cobrança com cartão
↓
Receber resposta da API
↓
Receber Webhook
↓
Atualizar o status na aplicação
Importante: Nã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 indicados permitem simular os cenários de aprovação e recusa;
- nenhuma adquirente é acionada;
- nenhum valor real é movimentado;
- os retornos servem exclusivamente para homologação.
Atenção: Os cartões apresentados neste guia são recomendados para testes. A utilização de outros números ainda não é tecnicamente restringida pelo Sandbox. Independentemente disso, utilize somente dados fictícios.
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 fictícios | 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;
- utiliza somente dados fictícios durante os testes no Sandbox.
Próximos passos
Updated 1 day ago