Testing Credit Card Payment

The Sandbox environment allows you to simulate credit card payments to validate charge flows, API response handling, webhook delivery, and your application's business rules before using them in production.

These tests are especially recommended for integrations that work with:

• one-time charges;
• subscriptions;
• recurring payments;
• card tokenization;
• custom checkout solutions;
• automations based on payment events.

When to use

Use this flow whenever you need to:

• validate the creation of credit card charges;
• test payment approvals and declines;
• validate webhooks related to charge processing;
• homologate integrations before going live in production;
• test your application's behavior under different payment outcomes.

Prerequisites

Before performing the tests, you must:

1. Have a Sandbox account.
2. Have a Sandbox API Key.
3. Create a customer to associate with the charge.
4. Use the credit card charge creation endpoint.

See the reference:

Create a credit card charge

Important charge fields

When creating a credit card charge, some fields play a key role in testing:

📘

Important

The complete request parameters are documented in the endpoint reference.

The purpose of this page is to demonstrate the homologation scenarios available in Sandbox.

Valid card to simulate success

Use the data below to simulate an approved transaction:

• Credit card: 4444 4444 4444 4444
• Expiration date: any month later than the current date
• CCV: 123 or any other 3-digit number

When using this card, the charge should be processed successfully in the Sandbox environment.

Cards to simulate errors

Use the cards below to validate failure scenarios:

• Mastercard: 5184019740373151
• Visa: 4916561358240741

These cards can be used to validate decline handling and error behaviors in the integration.

Expected behavior

During testing, Sandbox simulates the charge processing result based on the card used.

In general:

• valid cards return approval;
• cards intended for error simulation return a simulated failure;
• no real amount is processed;
• no acquirer is contacted;
• no real financial transaction occurs.

This allows you to validate the entire integration journey without financial impact.

Example homologation flow

A typical credit card homologation follows the flow below:

Create customer
        ↓
Create charge
with card
        ↓
Receive API
response
        ↓
Receive payment
webhook
        ↓
Update status
in the application

At the end of the process, your application should be able to correctly handle both approval and failure scenarios.

Best practices

📘

Recommended

• Test both success and failure scenarios before going live in production.
• Validate webhook delivery and processing.
• Do not use real customer data during homologation.
• Use only cards intended for testing.
• Do not base your integration exclusively on the synchronous API response; also consider events received via webhook.

Differences between Sandbox and Production

Although the flow is similar to the production environment, there are important differences:

For this reason, additional testing is recommended after the feature is enabled in production.

Operational impacts

Proper validation of card flows helps identify issues in advance related to:

• payment processing;
• status updates;
• webhook delivery;
• failure handling;
• application business rules.

Proper homologation significantly reduces the occurrence of errors after going live in production.

You can also use credit card generators for testing, such as 4Devs. Valid cards generated in these scenarios will be accepted in the Sandbox environment.