Sandbox Simulation

Sandbox Environment Only

The simulation features described on this page are available exclusively in the sandbox environment for testing purposes. These capabilities allow you to test your integration's resilience and error handling without affecting production systems.

Overview

The EBANX sandbox environment provides comprehensive simulation capabilities that enable merchants and internal teams to test various failure scenarios and edge cases. These simulations help ensure your integration can properly handle system volatility, network issues, and reconciliation processes before going live.

The Internal System Failure Simulation feature allows you to trigger controlled failures that mimic real-world scenarios where EBANX internal systems experience temporary issues. This enables rigorous testing of your reconciliation processes, retry strategies, and error handling logic to ensure data integrity and correct transaction state management.

Internal System Failure Simulation

Internal System Failure Simulation enables you to test how your integration handles EBANX system failures, including server-side timeouts, service unavailability, and BP-DR (Business Process - Decline Reason) events at critical points in the transaction lifecycle. This feature is particularly valuable for testing scenarios where transactions enter pending or unknown states that require later reconciliation.

How It Works

To simulate internal system failures, include the X-EBANX-Simulate-Internal-Error header in your API requests to the /ws/direct endpoint. The header value determines which specific error scenario will be simulated.

Add the following HTTP header to your request:

X-EBANX-Simulate-Internal-Error: <HEADER_VALUE>

Where <HEADER_VALUE> corresponds to one of the available simulation codes listed in the table below (e.g., BP-DR-119, 503, BP-R-5, etc.).

Important: This simulation layer intercepts requests in the sandbox environment only. Production environments are protected and will reject any simulation attempts with an error.

Simulating Network Timeout Errors

Network timeout errors simulate scenarios where communication with external payment services fails or times out. These errors cause payments to remain in a pending or unknown state, requiring your system to implement proper reconciliation logic.

BP-DR-119: Timeout on External API Communication

This error simulates a timeout during communication with acquirer or payment provider APIs. When this occurs, the payment status remains unknown because the external service did not respond within the expected timeframe.

Use Case: Test your reconciliation process when acquirer communication times out and the final payment status is uncertain.

Header Value: BP-DR-119

Example Request:

curl -X POST 'https://sandbox.ebanx.com/ws/direct' \
  --header 'Content-Type: application/json' \
  --header 'X-EBANX-Simulate-Internal-Error: BP-DR-119' \
  --data '{
    "integration_key": "your_integration_key",
    "payment": {
      "merchant_payment_code": "unique_payment_code_123",
      "amount_total": 100.00,
      "currency_code": "BRL",
      "country": "BR",
      "payment_type_code": "creditcard",
      "name": "João Silva",
      "email": "joao.silva@example.com",
      "document": "853.513.468-93",
      "card_number": "4111111111111111",
      "card_cvv": "123",
      "card_due_date": "12/2025"
    }
  }'

Expected Response: The API will return an error response indicating a timeout occurred during external API communication, and the payment will be logged as pending or unknown, requiring reconciliation.

BP-DR-120: External Service Not Available

This error simulates scenarios where an external payment service is temporarily unavailable or unreachable. This differs from a timeout in that the service actively indicates unavailability rather than simply not responding.

Use Case: Test how your system handles temporary service outages from payment providers and implements appropriate retry logic.

Header Value: BP-DR-120

Example Request:

curl -X POST 'https://sandbox.ebanx.com/ws/direct' \
  --header 'Content-Type: application/json' \
  --header 'X-EBANX-Simulate-Internal-Error: BP-DR-120' \
  --data '{
    "integration_key": "your_integration_key",
    "payment": {
      "merchant_payment_code": "unique_payment_code_124",
      "amount_total": 150.00,
      "currency_code": "USD",
      "country": "BR",
      "payment_type_code": "creditcard",
      "name": "Maria Santos",
      "email": "maria.santos@example.com",
      "document": "685.784.987-04",
      "card_number": "5555555555554444",
      "card_cvv": "456",
      "card_due_date": "06/2026"
    }
  }'

Expected Response: The API will return an error indicating the external payment service is unavailable, and the transaction state will require reconciliation.

BP-DR-143: Hard Decline from E-Wallet After Retry

This error simulates a hard decline response from an e-wallet provider after retry attempts. This scenario is important for testing how your system handles definitive failures after exhausting retry attempts.

Use Case: Verify your system correctly handles hard declines from e-wallet providers and stops retry attempts appropriately.

Header Value: BP-DR-143

Example Request:

curl -X POST 'https://sandbox.ebanx.com/ws/direct' \
  --header 'Content-Type: application/json' \
  --header 'X-EBANX-Simulate-Internal-Error: BP-DR-143' \
  --data '{
    "integration_key": "your_integration_key",
    "payment": {
      "merchant_payment_code": "unique_payment_code_125",
      "amount_total": 75.50,
      "currency_code": "MXN",
      "country": "MX",
      "payment_type_code": "spei",
      "name": "Carlos Rodriguez",
      "email": "carlos.rodriguez@example.com"
    }
  }'

Expected Response: The API will return a hard decline error from the e-wallet provider, indicating no further retry attempts should be made.

Simulating Unknown Result Errors

Unknown result errors simulate scenarios where the payment enters an unknown state due to validation failures, enrollment issues, or retry conflicts. These require careful reconciliation to determine the actual payment status.

BP-DR-60: Invalid Merchant Enrollment Code for PIX Automático

This error simulates an enrollment validation failure for PIX Automático transactions. The merchant enrollment code provided is either invalid or not properly configured.

Use Case: Test validation logic for recurring payment enrollments and ensure proper error messaging to customers.

Header Value: BP-DR-60

Example Request:

curl -X POST 'https://sandbox.ebanx.com/ws/direct' \
  --header 'Content-Type: application/json' \
  --header 'X-EBANX-Simulate-Internal-Error: BP-DR-60' \
  --data '{
    "integration_key": "your_integration_key",
    "payment": {
      "merchant_payment_code": "unique_payment_code_126",
      "amount_total": 50.00,
      "currency_code": "BRL",
      "country": "BR",
      "payment_type_code": "pix-automatico",
      "name": "Ana Costa",
      "email": "ana.costa@example.com",
      "document": "527.137.415-72",
      "due_date": "25/12/2025",
      "enrollment": {
        "merchant_enrollment_code": "invalid_enrollment_123"
      }
    }
  }'

Expected Response: The API will return an error indicating the merchant enrollment code is invalid for PIX Automático transactions.

BP-DR-182: Enrollment Not Accepted

This error simulates scenarios where a customer enrollment has not been accepted yet, preventing transaction processing. This is common in recurring payment flows where enrollment acceptance is pending.

Use Case: Test how your system handles attempts to charge customers whose enrollments are still pending acceptance.

Header Value: BP-DR-182

Example Request:

curl -X POST 'https://sandbox.ebanx.com/ws/direct' \
  --header 'Content-Type: application/json' \
  --header 'X-EBANX-Simulate-Internal-Error: BP-DR-182' \
  --data '{
    "integration_key": "your_integration_key",
    "payment": {
      "merchant_payment_code": "unique_payment_code_127",
      "amount_total": 99.90,
      "currency_code": "COP",
      "country": "CO",
      "payment_type_code": "nequi-recurrent",
      "name": "Laura Gomez",
      "email": "laura.gomez@example.com",
      "document": "4023030074",
      "enrollment": {
        "merchant_enrollment_code": "pending_enrollment_456"
      }
    }
  }'

Expected Response: The API will return an error indicating the enrollment is not accepted and cannot be used for transactions.

BP-R-5: Payment Has Attempt Being Processed

This error simulates a concurrent retry attempt conflict where another retry attempt for the same payment is already being processed. This prevents duplicate processing of the same transaction.

Use Case: Test your retry logic to ensure it properly handles concurrent retry attempts and avoids duplicate charges.

Header Value: BP-R-5

Example Request:

curl -X POST 'https://sandbox.ebanx.com/ws/direct' \
  --header 'Content-Type: application/json' \
  --header 'X-EBANX-Simulate-Internal-Error: BP-R-5' \
  --data '{
    "integration_key": "your_integration_key",
    "payment": {
      "merchant_payment_code": "unique_payment_code_128",
      "amount_total": 200.00,
      "currency_code": "BRL",
      "country": "BR",
      "payment_type_code": "creditcard",
      "name": "Pedro Oliveira",
      "email": "pedro.oliveira@example.com",
      "document": "723.645.557-10",
      "card_number": "4111111111111111",
      "card_cvv": "789",
      "card_due_date": "03/2027"
    }
  }'

Expected Response: The API will return an error indicating another retry attempt is already in progress for this payment.

BP-R-6: Payment Has No Available Retries

This error simulates scenarios where a payment has exhausted all available retry attempts. No further retry attempts are allowed for this transaction.

Use Case: Verify your system correctly handles exhausted retry attempts and transitions the payment to a final failed state.

Header Value: BP-R-6

Example Request:

curl -X POST 'https://sandbox.ebanx.com/ws/direct' \
  --header 'Content-Type: application/json' \
  --header 'X-EBANX-Simulate-Internal-Error: BP-R-6' \
  --data '{
    "integration_key": "your_integration_key",
    "payment": {
      "merchant_payment_code": "unique_payment_code_129",
      "amount_total": 125.00,
      "currency_code": "BRL",
      "country": "BR",
      "payment_type_code": "pix-automatico",
      "name": "Fernanda Lima",
      "email": "fernanda.lima@example.com",
      "document": "561.072.634-46",
      "due_date": "30/12/2025",
      "enrollment": {
        "merchant_enrollment_code": "enrollment_789"
      }
    }
  }'

Expected Response: The API will return an error indicating the payment has no available retry attempts remaining.

Simulating HTTP Internal and Timeout Errors

HTTP timeout errors simulate server-side issues where EBANX systems experience temporary problems responding to requests. These scenarios are critical for testing how your integration handles infrastructure-level failures.

500 Internal Server Error

The 500 Internal Server Error simulates scenarios where EBANX internal servers encounter unexpected conditions that prevent them from fulfilling requests. This represents a generic server-side failure.

Use Case: Test how your application handles generic server errors and implements retry logic with exponential backoff.

Header Value: 500

Example Request:

curl -X POST 'https://sandbox.ebanx.com/ws/direct' \
  --header 'Content-Type: application/json' \
  --header 'X-EBANX-Simulate-Internal-Error: 504' \
  --data '{
    "integration_key": "your_integration_key",
    "payment": {
      "merchant_payment_code": "unique_payment_code_130",
      "amount_total": 300.00,
      "currency_code": "USD",
      "country": "BR",
      "payment_type_code": "creditcard",
      "name": "Roberto Santos",
      "email": "roberto.santos@example.com",
      "document": "703.766.940-76",
      "card_number": "5555555555554444",
      "card_cvv": "321",
      "card_due_date": "09/2026"
    }
  }'

Expected Response: The API will return a 500 Internal Server Error HTTP status code, and the payment status will be unknown, requiring reconciliation through the query endpoint.

504 Gateway Timeout

The 504 Gateway Timeout error simulates scenarios where EBANX gateway servers timeout while waiting for upstream services to respond. This represents infrastructure-level issues that can occur during high load or service degradation.

Use Case: Test how your application handles gateway timeouts and implements appropriate retry logic with exponential backoff.

Header Value: 504

Example Request:

curl -X POST 'https://sandbox.ebanx.com/ws/direct' \
  --header 'Content-Type: application/json' \
  --header 'X-EBANX-Simulate-Internal-Error: 504' \
  --data '{
    "integration_key": "your_integration_key",
    "payment": {
      "merchant_payment_code": "unique_payment_code_130",
      "amount_total": 300.00,
      "currency_code": "USD",
      "country": "BR",
      "payment_type_code": "creditcard",
      "name": "Roberto Santos",
      "email": "roberto.santos@example.com",
      "document": "703.766.940-76",
      "card_number": "5555555555554444",
      "card_cvv": "321",
      "card_due_date": "09/2026"
    }
  }'

Expected Response: The API will return a 504 Gateway Timeout HTTP status code, and the payment status will be unknown, requiring reconciliation through the query endpoint.

503 Service Unavailable

The 503 Service Unavailable error simulates scenarios where EBANX services are temporarily unavailable due to maintenance, overload, or other operational issues. This is a temporary condition that should trigger retry logic.

Use Case: Test your integration's resilience to temporary service unavailability and verify proper implementation of retry strategies with appropriate delays.

Header Value: 503

Example Request:

curl -X POST 'https://sandbox.ebanx.com/ws/direct' \
  --header 'Content-Type: application/json' \
  --header 'X-EBANX-Simulate-Internal-Error: 503' \
  --data '{
    "integration_key": "your_integration_key",
    "payment": {
      "merchant_payment_code": "unique_payment_code_131",
      "amount_total": 175.00,
      "currency_code": "BRL",
      "country": "BR",
      "payment_type_code": "boleto",
      "name": "Juliana Ferreira",
      "email": "juliana.ferreira@example.com",
      "document": "831.836.515-13"
    }
  }'

Expected Response: The API will return a 503 Service Unavailable HTTP status code, indicating the service is temporarily unavailable and the request should be retried later.

Best Practices for Testing

When using the Internal System Failure Simulation feature, consider the following best practices to maximize the value of your testing:

Implement Comprehensive Reconciliation Logic: Use these simulations to verify your reconciliation processes can correctly identify and resolve payments in unknown or pending states. Your system should periodically query payment status using the /ws/query endpoint for transactions that did not receive a definitive response.

Test Retry Strategies: Verify your retry logic implements exponential backoff and respects retry limits. Test scenarios where retries eventually succeed, where they exhaust all attempts, and where concurrent retry attempts conflict.

Validate Error Handling: Ensure your application gracefully handles all simulated error scenarios with appropriate user messaging and logging. Users should receive clear information about what happened and what actions they can take.

Monitor Transaction States: During testing, monitor how your system tracks transaction states through the entire lifecycle, especially for payments that enter pending or unknown states. Verify that no transactions are lost or incorrectly marked as failed when they should be reconciled.

Test Idempotency: Use the same merchant_payment_code with different simulation headers to verify your integration properly handles idempotent requests and prevents duplicate charges.

Document Operational Procedures: Use insights from simulation testing to document operational procedures for handling real-world failures, including escalation paths and reconciliation timelines.

Summary of Simulation Headers

The following table summarizes all available simulation headers and their use cases:

Header Value	Error Type	Description	Primary Use Case
BP-DR-119	Network Timeout	Timeout during acquirer communication	Test reconciliation for unknown payment states
BP-DR-120	Service Unavailable	External payment service unavailable	Test retry logic for service outages
BP-DR-143	Hard Decline	E-wallet hard decline after retry	Test handling of definitive failures
BP-DR-60	Validation Error	Invalid PIX Automático enrollment code	Test enrollment validation logic
BP-DR-182	Enrollment Error	Enrollment not accepted	Test pending enrollment handling
BP-R-5	Retry Conflict	Concurrent retry attempt in progress	Test concurrent retry prevention
BP-R-6	Retry Exhausted	No available retry attempts remaining	Test exhausted retry handling
504	HTTP Timeout	Gateway timeout	Test infrastructure failure handling
503	HTTP Error	Service temporarily unavailable	Test service unavailability resilience

Still need help?

We hope this article was helpful. If you still have questions, you can explore the following options:

• Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
• Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.