Testando pagamento com cartão de crédito

O ambiente Sandbox permite simular pagamentos com cartão de crédito para validar fluxos de cobrança, tratamento de respostas da API, recebimento de webhooks e regras de negócio da sua aplicação antes da utilização em produção.

Esses testes são especialmente recomendados para integrações que trabalham com:

cobranças avulsas;
assinaturas;
pagamentos recorrentes;
tokenização de cartões;
checkout próprio;
automações baseadas em eventos de pagamento.

Quando utilizar

Utilize este fluxo sempre que precisar:

validar a criação de cobranças com cartão de crédito;
testar aprovações e recusas de pagamento;
validar webhooks relacionados ao processamento da cobrança;
homologar integrações antes da entrada em produção;
testar o comportamento da aplicação diante de diferentes resultados de pagamento.

Pré-requisitos

Antes de realizar os testes, é necessário:

Possuir uma conta Sandbox.
Possuir uma API Key de Sandbox.
Criar um cliente para vincular à cobrança.
Utilizar o endpoint de criação de cobrança com cartão de crédito.

Consulte a referência:

Criar cobrança com cartão de crédito

Campos importantes da cobrança

Ao criar uma cobrança com cartão de crédito, alguns campos possuem papel fundamental para o teste:

Campo	Finalidade
customer	Identificador do cliente que receberá a cobrança
billingType	Deve ser informado como CREDIT_CARD
value	Valor da cobrança
dueDate	Data de vencimento da cobrança
creditCard	Dados do cartão utilizado no pagamento
creditCardHolderInfo	Dados do titular do cartão

📘
Importante
Os parâmetros completos da requisição estão documentados na referência do endpoint.
Esta página tem como objetivo demonstrar os cenários de homologação disponíveis no Sandbox.

Cartão válido para simular sucesso

Utilize os dados abaixo para simular uma transação aprovada:

Cartão de crédito: 4444 4444 4444 4444
Vencimento: qualquer mês posterior à data atual
CCV: 123 ou qualquer outro número de 3 dígitos

Ao utilizar esse cartão, a cobrança deverá ser processada com sucesso no ambiente Sandbox.

Cartões para simular erro

Utilize os cartões abaixo para validar cenários de falha:

Mastercard: 5184019740373151
Visa: 4916561358240741

Esses cartões podem ser utilizados para validar o tratamento de recusas e comportamentos de erro na integração.

Comportamento esperado

Durante os testes, o Sandbox simula o resultado do processamento da cobrança com base no cartão utilizado.

De forma geral:

cartões válidos retornam aprovação;
cartões destinados a erro retornam falha simulada;
nenhum valor real é processado;
nenhuma adquirente é acionada;
nenhuma movimentação financeira real ocorre.

Isso permite validar toda a jornada da integração sem impacto financeiro.

Exemplo de fluxo de homologação

Uma homologação típica de cartão de crédito segue o fluxo abaixo:

Criar cliente
        ↓
Criar cobrança
com cartão
        ↓
Receber resposta
da API
        ↓
Receber webhook
de pagamento
        ↓
Atualizar status
na aplicação

Ao final do processo, sua aplicação deve ser capaz de processar corretamente tanto os cenários de aprovação quanto os cenários de falha.

Boas práticas

📘
Recomendado

Teste cenários de sucesso e de erro antes da entrada em produção.

Valide o recebimento e processamento dos webhooks.

Não utilize dados reais de clientes durante a homologação.

Utilize apenas cartões destinados a testes.

Não baseie sua integração exclusivamente na resposta síncrona da API; considere também os eventos recebidos via webhook.

Diferenças entre Sandbox e Produção

Embora o fluxo seja semelhante ao ambiente produtivo, existem diferenças importantes:

Sandbox	Produção
Utiliza cartões de teste	Utiliza cartões reais
Não movimenta valores reais	Movimenta valores reais
Simula aprovações e recusas	Processa transações reais
Não depende de adquirentes	Depende do processamento real das operadoras

Por esse motivo, recomenda-se realizar testes adicionais após a habilitação da funcionalidade em produção.

Impactos operacionais

A validação correta dos fluxos de cartão permite identificar antecipadamente problemas relacionados a:

processamento de pagamentos;
atualização de status;
recebimento de webhooks;
tratamento de falhas;
regras de negócio da aplicação.

Uma homologação adequada reduz significativamente a ocorrência de erros após a entrada em produção.

Você também pode utilizar geradores de cartão de crédito para testes, como o 4Devs. Os cartões válidos gerados nesses cenários serão aceitos no ambiente Sandbox.