Testing

Test your Flintn integration in the sandbox environment before going live.

Sandbox Environment

The sandbox environment mirrors production but processes test transactions only. No real money is transferred.

Environment	Dashboard	API Base URL
Sandbox	hub.sandbox.flintn.com	https://api.sandbox.flintn.com/v1
Production	hub.flintn.com	https://api.flintn.com/v1

API Keys

Sandbox and production use different API keys:

Environment	Key Prefix	Example
Sandbox	pk_test_	pk_test_abc123def456...
Production	pk_live_	pk_live_xyz789ghi012...

Important: Never use production keys in your test environment or sandbox keys in production.

Test Cards

Use these card numbers to simulate different payment scenarios.

Successful Payments

Card Number	Brand	Description
4111 1111 1111 1111	Visa	Successful payment
5555 5555 5555 4444	Mastercard	Successful payment
3782 822463 10005	American Express	Successful payment
6011 1111 1111 1117	Discover	Successful payment

Declined Payments

Card Number	Brand	Decline Reason
4000 0000 0000 0002	Visa	Generic decline
4000 0000 0000 9995	Visa	Insufficient funds
4000 0000 0000 9987	Visa	Lost card
4000 0000 0000 9979	Visa	Stolen card
4000 0000 0000 0069	Visa	Expired card
4000 0000 0000 0127	Visa	Invalid CVV

3D Secure Testing

Card Number	Behavior
4000 0000 0000 3220	3DS authentication required
4000 0000 0000 3063	3DS authentication fails

Specific Response Codes

Card Number	Response Code
4000 0000 0000 0044	Address mismatch (AVS)
4000 0000 0000 0101	CVV mismatch

Test Card Details

For all test cards:

Field	Value
Expiration	Any future date (e.g., 12/30)
CVV	Any 3 digits (4 for Amex)
Postal Code	Any valid format

Testing Scenarios

Successful Subscription

1. Create a subscription plan (sandbox)

2. Generate a client session

3. Use test card 4111 1111 1111 1111

4. Verify SUBSCRIPTION_ACTIVATED webhook

Failed Payment

1. Create a subscription plan

2. Generate a client session

3. Use test card 4000 0000 0000 0002

4. Verify TRANSACTION_DECLINED webhook

Subscription Renewal

Subscription renewals are triggered automatically based on billing frequency. In sandbox, you can simulate renewals via the dashboard.

Refund Flow

1. Complete a successful payment

2. Wait for settlement (or simulate via dashboard)

3. Issue refund via API or dashboard

4. Verify TRANSACTION_REFUNDED webhook

Testing Webhooks

Local Development

Use a tunneling service to expose your local server:

# Using ngrok
ngrok http 3000

Register the ngrok URL as your webhook endpoint in the sandbox dashboard.

Testing with cURL

Simulate webhook payloads locally:

curl -X POST http://localhost:3000/webhooks/flintn \
  -H "Content-Type: application/json" \
  -H "X-Signature-Primary: <test-signature>" \
  -d '{
    "id": "evt_test123",
    "type": "TRANSACTION_SETTLED",
    "created_at": "2024-01-15T10:30:00Z",
    "data": {
      "transaction_id": "txn_test456",
      "amount": 2999,
      "currency": "USD"
    }
  }'

Dashboard Test Events

Send test webhook events from the dashboard:

1. Go to Developers > Webhooks

2. Click on your webhook endpoint

3. Click Send Test Event

4. Select event type and send

Sandbox Limitations

The sandbox environment has some differences from production:

Feature	Sandbox	Production
Real payments	No	Yes
Settlement timing	Simulated	Real bank processing
Card networks	Simulated responses	Real authorization
Rate limits	Same	Same

Going Live Checklist

Before switching to production:

• All test scenarios pass in sandbox

• Webhook signature verification implemented

• Error handling tested with decline scenarios

• Production API keys created (with minimum required permissions)

• Production webhook endpoints configured

• Idempotency keys implemented for retryable operations

• Logging and monitoring set up

• Test with a real card (small amount) in production

Debugging

Check API Responses

All API responses include a request_id for debugging:

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Error details here"
}

Include this ID when contacting support.

View Webhook Logs

In the dashboard:

1. Go to Developers > Webhooks

2. Click on your endpoint

3. View Recent Deliveries

4. Inspect request/response details

Common Issues

Issue	Solution
401 Unauthorized	Check API key and environment match
Webhook not received	Verify endpoint URL and event subscriptions
3DS not triggering	Use the 3DS test card number
Wrong environment	Ensure pk_test_ for sandbox, pk_live_ for production

Next Steps

• Subscription Payments Quickstart - Build your first integration

• Webhooks - Configure webhook endpoints

• Authentication - API key management