Sandbox Testing

The Gatelithix sandbox lets you build and test your integration without processing real payments. Use your test API keys (sk_test_, pk_test_) to make requests against the sandbox environment. No real charges are created, and no real card networks are contacted.

Sandbox base URL: https://sandbox.api.gatelithix.com/v1/

Test Card Numbers

The sandbox uses Stripe-compatible test card numbers. These cards produce predictable outcomes when used with the Gatelitest mock connector.

For all test cards:

• Use any future expiry date (e.g., 12/2028).
• Use any 3-digit CVC (e.g., 123).
• Use any 5-digit ZIP if prompted (e.g., 10001).

End-to-End Test Flow

Walk through a complete payment lifecycle: tokenize a card, authorize, capture, and refund.

Step 1: Tokenize a Test Card

Response:

{
  "token": "tok_test_aBcDeFgHiJkLmNoPqRsTuVwX",
  "bin_prefix": "4242",
  "last4": "4242",
  "exp_month": 12,
  "exp_year": 2028,
  "card_brand": "visa",
  "created_at": "2026-03-18T12:00:00Z"
}

Step 2: Authorize a Payment

Step 3: Capture the Payment

Step 4: Refund the Payment

Testing Error Scenarios

Use the decline test cards to verify your error handling. Each card triggers a specific error response.

Example: Insufficient funds decline

curl -X POST https://sandbox.api.gatelithix.com/v1/payments/authorize \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: err_$(uuidgen)" \
  -d '{
    "amount": 5000,
    "currency": "usd",
    "gateway_token": "tok_test_insufficient_funds_token",
    "capture_method": "manual"
  }'

Error response:

{
  "error": {
    "type": "connector_error",
    "code": "connector_error",
    "message": "The card has insufficient funds.",
    "connector_code": "insufficient_funds",
    "request_id": "req_abc123def456"
  }
}

Always check the error.type and error.connector_code fields to determine the cause. See Error Codes for the full error reference.

Testing Webhooks

To test webhook delivery without completing a real payment:

1. Register a webhook endpoint using the API or dashboard .
2. Use the test delivery feature on POST /v1/webhook_endpoints/{id}/test to send a sample event.
3. Verify your endpoint receives the event and returns a 200 response.

See Webhooks for setup details and signature verification.

Gatelitest Mock Connector

Gatelitest is the built-in mock payment connector designed for safe testing. It simulates a real PSP without connecting to any external service.

How Gatelitest works:

• Card-driven outcomes: The test card number determines the result. 4242424242424242 always approves; decline cards return appropriate error codes.
• Auto-routing in sandbox: When using test API keys (sk_test_), if no routing configuration is set for your merchant, payments are automatically routed to Gatelitest.
• Full lifecycle support: Gatelitest supports authorize, capture, sale, refund, and void — the complete payment lifecycle.
• Configurable behavior: Gatelitest reads the test card BIN to determine the response, matching Stripe test card conventions.

Gatelitest is always available in the sandbox environment. You do not need to configure a connector to start testing.

Tips

Use unique Idempotency-Key values. Every write request (POST) requires a unique Idempotency-Key header. Using the same key with different parameters returns a 422 error. Use UUIDs for simplicity.

Capture X-Request-Id for debugging. Every API response includes an X-Request-Id header. Log this value — it is essential for tracing issues and communicating with support.

Separate test and live keys. Never use sk_live_ keys in your test environment. Sandbox keys (sk_test_) ensure no real charges are created.

Next Steps

• Getting Started — Set up your account and make your first payment.
• Error Codes — Handle all error types gracefully.
• Troubleshooting — Diagnose integration issues.
• Webhooks — Set up real-time event notifications.