Testing Payment Integrations: Sandbox Guide

API Integration

Testing Payment Integrations: Sandbox Guide

January 15, 2025 8 min read TIB Finance Team

Sandbox Environment Overview
Sandbox Credentials
Test Card Numbers
Simulating Different Responses
Testing Error Cases
Testing Webhooks
Going Live Checklist

One of the most common causes of production payment failures is inadequate testing. An integration that only handles the happy path — a successful card charge — will fail spectacularly when it encounters a declined card, an expired payment method, a network timeout, or a 3DS authentication requirement. The TIB Finance sandbox environment exists to let you encounter and handle all of these scenarios before your customers do.

This guide covers everything you need to know about using the TIB Finance sandbox to build a thorough test suite. Combined with the API integration guide, this gives you a complete picture of building and validating a production-quality integration.

Sandbox Environment Overview

The TIB Finance sandbox is a fully isolated environment that mirrors the production API in functionality, but processes no real transactions and charges no real money. Key characteristics:

Separate API endpoint: https://sandbox-api.tib.finance/v1 — distinct from the production URL.
Separate credentials: Sandbox API keys are prefixed with sk_test_ and pk_test_. Production keys use sk_live_ and pk_live_. Never mix them.
Sandbox dashboard: View sandbox transactions, customers, and events at the TIB Finance sandbox dashboard — separate from your live merchant dashboard.
Test data is not real: No actual funds move. No card issuers are contacted. All responses are simulated based on the test card number you use.
Full feature parity: Webhooks, tokenization, 3DS, refunds, disputes, and all other features are available in the sandbox.

Tip: Always include an environment check in your application startup to verify that sandbox credentials are never used in production and production credentials are never used in development.

Sandbox Credentials

Access your sandbox credentials from the TIB Finance developer dashboard. You will find:

Sandbox Secret Key: sk_test_xxxxxxxxxxxxxxxxxxxx — use on your server
Sandbox Publishable Key: pk_test_xxxxxxxxxxxxxxxxxxxx — use in client-side JavaScript
Sandbox Webhook Secret: Used to verify sandbox webhook signatures (separate from production webhook secret)

Store sandbox credentials in a separate .env.test or .env.development file from your production .env or .env.production file. Your deployment pipeline should set environment variables from the appropriate file based on the target environment.

Test Card Numbers

TIB Finance provides a set of test card numbers that trigger specific responses. Use any future expiration date (e.g., 12/27), any 3-digit CVV (e.g., 123), and any valid billing zip code (e.g., 10001).

Card Number	Brand	Result
4111 1111 1111 1111	Visa	payment.succeeded
5500 0000 0000 0004	Mastercard	payment.succeeded
3714 496353 98431	Amex	payment.succeeded
6011 1111 1111 1117	Discover	payment.succeeded
4000 0000 0000 0002	Visa	card_declined
4000 0000 0000 9995	Visa	insufficient_funds
4000 0000 0000 0069	Visa	expired_card
4000 0000 0000 0127	Visa	incorrect_cvc
4000 0027 6000 3184	Visa	authentication_required (3DS)
4000 0000 0000 3220	Visa	payment.pending (async)

Simulating Different Responses

Beyond specific test cards, TIB Finance's sandbox supports additional simulation mechanisms:

Amount-Based Simulation

You can trigger specific behaviors based on the amount you set in test transactions:

Amount ending in .01 (e.g., $49.01 / 4901 cents): Triggers a generic decline
Amount ending in .02: Triggers an insufficient funds decline
Amount of exactly $0.00 / 0 cents: Triggers a card verification (zero-auth) check
Amount greater than $999.99: Triggers an authentication_required response

Testing 3DS Authentication Flow

Use card number 4000 0027 6000 3184 to test the full 3D Secure 2 authentication flow. In the sandbox, the 3DS challenge page displays a passcode of 424242 for a successful authentication, or you can submit an incorrect code to test a 3DS failure. Your integration must handle the requires_action response and guide the customer through the authentication flow.

Testing Error Cases

A robust integration handles every error gracefully. Here is a systematic approach to error case testing:

Network and Infrastructure Errors

Timeout simulation: Use the special card 4000 0000 0000 1000 in the sandbox to simulate a gateway timeout. Your code should handle timeouts with appropriate retry logic using your idempotency key.
Rate limiting: Send more than 100 API requests per second to trigger HTTP 429. Verify your exponential backoff retry logic.
Server error (500): Set the X-TIB-Simulate-Error: 500 header in sandbox requests to simulate a server error. Only safe with idempotency keys.

Input Validation Errors

// Test missing required fields
POST /v1/transactions
{
  // Missing 'amount' — should return 400 invalid_request
  "currency": "USD",
  "payment_method": "pm_test_xxx"
}

// Test invalid card number format
// Use card number: 4000 0000 0000 XXXX where XXXX fails Luhn check
// Should return: invalid_card_number

// Test expired card explicitly
// Card: 4000 0000 0000 0069 — returns expired_card
                        

Authentication Errors

Use an invalid API key to verify your integration returns a 401 and does not expose the invalid key in logs or error messages
Use a publishable key for a server-side operation to verify your integration detects and handles the "wrong key type" error
Test with an expired or revoked API key by temporarily disabling a test key in the dashboard

Testing Webhooks in the Sandbox

The TIB Finance sandbox dashboard provides a webhook testing tool that lets you manually trigger any event type to your registered endpoint, without needing to create a transaction that generates the event naturally. This is invaluable for testing edge-case events like dispute.created or refund.failed.

Using the Sandbox Webhook Inspector

Navigate to Settings > Webhooks in the sandbox dashboard
Select your webhook endpoint
Click "Send test event" and select the event type
The inspector shows the outgoing payload, your endpoint's response, and delivery status
For local development, use a tool like ngrok to expose your local server with a public HTTPS URL

Automated Webhook Testing

// Example Jest test for webhook handler
const crypto = require('crypto');

test('processes payment.succeeded webhook', async () => {
  const payload = JSON.stringify({
    id: 'evt_test_001',
    type: 'payment.succeeded',
    data: { object: { id: 'txn_test_001', reference: 'ORDER-001', status: 'succeeded' } }
  });

  const timestamp = Math.floor(Date.now() / 1000);
  const signature = crypto
    .createHmac('sha256', process.env.TEST_WEBHOOK_SECRET)
    .update(`${timestamp}.${payload}`)
    .digest('hex');

  const response = await request(app)
    .post('/webhook')
    .set('TIB-Signature', `t=${timestamp},v1=${signature}`)
    .set('Content-Type', 'application/json')
    .send(payload);

  expect(response.status).toBe(200);
  // Verify business logic was executed
  expect(mockOrderFulfillment).toHaveBeenCalledWith('ORDER-001');
});
                        

Going Live Checklist

When your sandbox testing is thorough and all test cases pass, use this checklist to confirm you are ready for production:

All payment flows tested: Successful charge, declined card, insufficient funds, expired card, incorrect CVV, 3DS authentication

Error handling verified: All error codes from the API reference have corresponding user-facing messages

Webhooks implemented and tested: All relevant event types handled, signature verification in place, idempotency implemented

Idempotency keys used: All transaction creation requests include unique idempotency keys

API keys in environment variables: No hardcoded keys in source code or version control

Production URL configured: API calls point to api.tib.finance not sandbox-api.tib.finance

TLS enforced: All checkout pages and API calls use HTTPS

livemode flag checked: Application checks the livemode field in API responses and webhook events

Logging in place: All payment events, API errors, and webhook deliveries are logged for audit and debugging

Monitoring and alerting: Alerts configured for elevated payment failure rates or webhook delivery failures

Production webhook endpoint configured: Separate from sandbox endpoint, with production webhook secret

Smoke test in production: Complete one real transaction with a real card immediately after deploying to production

Access the TIB Finance Sandbox

The TIB Finance sandbox provides full API access, test card numbers, webhook simulation, and a complete testing environment — all free of charge.

Open Sandbox API Docs

Testing Payment Integrations: Sandbox Guide