Simulation

Use simulation to test Pix and boleto payments, refunds and results awaiting confirmation. The results update Sandbox records so you can check the charge's progress and its effects on the balance, statement and receipts.

Use only in the Sandbox

Create the customer and charge with a Sandbox API key from your company. Use the same company and environment to simulate the result and retrieve the records. The key identifies the environment; you do not provide the environment in the request body or URL.

Provide the charge or refund ID in the path, according to the request. A Production key receives 403 SANDBOX_ENVIRONMENT_REQUIRED. An ID that does not exist, belongs to another company or belongs to another environment receives the same resource-not-found response.

Confirm a payment

Use Confirm payment to complete payment of a test charge that is still open. The response reports status: 4, meaning paid, and amount_cents with the charge amount in Brazilian real cents.

The amount is credited to the Sandbox balance only once. You can check the balance in Retrieve balance and track the entry in Statement. The entry may take a few moments to appear; do not repeat the confirmation to try to speed up this update.

To test payment details and the receipt, create the charge with the payment method you want: payment_method: 1 for Pix or payment_method: 2 for boleto. See the issuance conditions in Charges. After confirmation, use the payment details and receipt endpoints. Test documents identify the payment as simulated. Confirmation does not choose a payment method for the charge.

Simulate a failure

Use Simulate payment failure to test how you handle an open charge that was not paid. The response reports status: 9, meaning failed. This result does not credit the balance or create an incoming payment entry in the statement.

Failure ends this test. To check an approved payment afterward, create another Sandbox charge.

Pending and failed Pix refunds

Create a Pix charge, confirm payment and use Simulate a pending refund. Send the amount in amount_cents, as in a normal refund request. The balance and remaining amount conditions still apply.

The 202 response returns the refund ID with status: accepted. Keep this ID to track the request. The requested amount leaves the total and available balances while the request awaits a result; this reservation does not increase the blocked balance field. The receipt is not available yet.

Choose a result for the same refund:

• Complete a simulated refund returns completed, updates the refund on the charge and makes the receipt available. The amount is not deducted again.
• Simulate refund failure returns failed, with REFUND_PROCESSING_FAILED in failure_reason.code, and returns the amount to the available balance. There is no completed refund receipt.

Repeating the same final result returns the refund without repeating its effect. Trying to change a completed result to failure, or a failure to completion, returns 409 REFUND_NOT_SIMULATABLE. For another test, check eligibility before creating a new request. Repeating creation while another request is pending receives PIX_REFUND_IN_PROGRESS; use the ID you already received to complete or fail that request.

The normal endpoint POST /v1/charges/{id}/refunds still completes the refund immediately in the Sandbox. Use the simulation routes when you need to test the wait and the later result.

Boleto clearing and settlement

Create a boleto charge and issue its payment instructions. Use Simulate boleto clearing to record that the payment has cleared but still awaits settlement. This step does not credit the balance or make a completed payment receipt available.

Retrieving the charge reports progress in payment_information.boleto_payment_status: awaiting_payment before clearing, compensated while awaiting settlement and settled after confirmation. The field returns null when no progress is available.

Then use Confirm payment to settle the boleto. Only this confirmation credits the amount and makes payment details and the receipt available. The statement may take a few moments to show the incoming payment. Repeating clearing or confirmation does not repeat the credit.

Pending or failed issuance and cancellation

Use Prepare a scenario before the action you want to test. Send action with pix_issuance, boleto_issuance or cancellation and choose outcome: pending or outcome: failed. The response with state: configured confirms preparation; it has not yet issued payment instructions or canceled the charge.

For issuance, create the charge with payment_method_types: [1] for Pix or payment_method_types: [2] for boleto, without issuance during creation. Prepare the scenario and use Issue a test payment, providing payment_method: 1 or 2. Issuance through the charge checkout also uses the prepared scenario. See the creation conditions in Charges.

For cancellation, prepare the scenario before using Revoke a charge. The normal request returns the selected pending or failed result. Preparing the scenario does not change the balance or refund a payment already received.

With outcome: pending, track the charge and use Resolve a pending scenario to choose completed or failed for the same action. This request completes an action that has already started; it does not start issuance or cancellation. Completed issuance makes the Pix or boleto available without confirming payment. Completed cancellation revokes the charge without refunding amounts.

With outcome: failed, the action returns the failure without going through resolution. Issuance failure appears in pix_status or boleto_status, and its reason in pix_error or boleto_error. It differs from Simulate payment failure, which closes the charge with a payment failure.

Each scenario applies to the specified charge. Repeating the same preparation or resolution preserves the result; trying to replace a scenario already defined receives 409 CHARGE_SCENARIO_CONFLICT. Create another charge to test a different combination.

Repeat a simulation

If the connection is interrupted, retrieve the charge or refund by the same ID. Repeating a confirmation, payment failure, clearing or scenario step already applied reports duplicate: true without applying the financial effect again. For refund completion and failure, the response returns the same refund with its final status.

A paid charge cannot receive a simulated payment failure, and a failed charge cannot receive confirmation. These two requests also reject canceled charges or charges with another final result, with 409 CHARGE_NOT_SIMULATABLE. Retrieve the current status and create another charge to test a different result.

Test other resources

Use each resource's endpoints with the Sandbox key. You do not need a simulation endpoint to create customers, create or update charges, manage payment links or revoke a charge.

To test a refund, create a Pix charge, confirm its payment and use Refunds. The balance, remaining amount and charge status conditions still apply. Refunds in the Sandbox are simulated; the refund endpoint does not accept boleto.

Balance, statement, statistics, payment details and receipt queries let you check the test results. Withdrawal requests remain restricted to Production; charge simulations do not transfer amounts to a bank account.

To test an overdue charge, create one with a short due period and wait for it to expire. Payment simulation can also confirm an overdue charge, provided it is still open to receive the result. Simulation preserves the charge's due date.

Disputes queries return the cases available in the queried environment. Confirming a test payment does not open a dispute.

Changes confirmed by simulation generate the corresponding webhook events for destinations registered in the Sandbox. Requests to your endpoint are real; use a test receiver and see Receive and validate events. Requests in other resources that ask to send email retain their own rules; use only authorized recipients in tests.