Uprails
DocumentationAPI ReferenceSettings

Testing Guide

Comprehensive guide to testing your Uprails integration before going live.

Testing Overview

Uprails provides a complete test environment that mirrors production. Use sandbox API keys (prefixed with snd_) to simulate all payment scenarios without processing real transactions.

Test Mode
All requests made with test API keys are processed in sandbox mode. No real money is moved, and you can test freely without affecting real accounts.

Test Card Numbers

Use these test card numbers to simulate different payment scenarios:

Success Cards

Card NumberBrandBehavior
4242424242424242VisaAlways succeeds
5555555555554444MastercardAlways succeeds
378282246310005American ExpressAlways succeeds
6011111111111117DiscoverAlways succeeds

3D Secure Test Cards

Card NumberBehavior
4000002500003155Requires 3DS authentication, then succeeds
4000008260003178Requires 3DS authentication, then fails
40000027600031843DS authentication fails immediately

Failure Cards

Card NumberError
4000000000000002Card declined
4000000000009995Insufficient funds
4000000000009987Lost card
4000000000009979Stolen card
4000000000000069Expired card
4000000000000127Incorrect CVC
4000000000000119Processing error

For all test cards, use any valid future expiration date and any 3-digit CVC (4-digit for Amex).

Pre-Launch Checklist

Before going live, ensure you've tested these scenarios:

Payments

  • Successful card payment
  • Declined card payment
  • 3D Secure authentication flow
  • Manual capture (authorize then capture)
  • Payment cancellation
  • Idempotency key handling

Refunds

  • Full refund
  • Partial refund
  • Multiple partial refunds
  • Refund failure handling

Customers & Payment Methods

  • Create customer
  • Save payment method to customer
  • Pay with saved payment method
  • Update payment method
  • Delete payment method

Error Handling

  • Invalid API key response
  • Validation error response
  • Rate limit handling
  • Network timeout handling

Going Live

When you're ready to go live:

  1. Switch to production API keys - Replace snd_ with prd_ keys in your production environment
  2. Update webhook endpoints - Point webhooks to your production URLs
  3. Verify processor settings - Ensure your payment processor is ready for production
  4. Test with real cards - Make a small real transaction to verify everything works
  5. Monitor your dashboard - Watch for any errors or unexpected behavior
Live Mode
In live mode, real money is processed. Start with small amounts to verify your integration before processing larger transactions.

Debugging Tips

Check the Dashboard

All API requests and webhook events are logged in your dashboard. Use it to inspect request/response details and event payloads.

Use Idempotency Keys

Always include idempotency keys for POST requests. This prevents duplicate payments if a request is retried due to network issues.

Log Everything

Log all API responses and webhook events. This helps diagnose issues and provides an audit trail for transactions.

Next Steps

Error Handling

Handle errors gracefully

Webhooks

Set up event notifications

API Basics

Learn about idempotency and rate limits

Authentication

Secure your API keys