How to test your Spreedly React Native SDK integration before going to production.
- A Spreedly test environment with a valid
environmentKey - Backend-signed authentication parameters (nonce, signature, timestamp, certificateToken)
- For 3DS (Forter): a
forterSiteIdconfigured in your Spreedly environment - For 3DS (Gateway-Specific): a gateway that supports
attempt_3dsecure - For Stripe APM: a Stripe test publishable key (
pk_test_...) and a Stripe Payment Intents gateway - For Braintree APM: a Braintree sandbox gateway configured in Spreedly
- For offsite payments: an offsite gateway (use SPREL for testing)
| Setting | Test | Production |
|---|---|---|
| Card numbers | Use test cards below | Real cards |
| Environment | Spreedly test environment | Spreedly live environment |
| Stripe key | pk_test_... |
pk_live_... |
| Braintree gateway | Sandbox gateway | Production gateway |
| Offsite gateway | SPREL (test) | PayPal, EBANX, etc. |
| Card Number | Brand | Use Case |
|---|---|---|
4111 1111 1111 1111 |
Visa | Successful tokenization |
5555 5555 5555 4444 |
Mastercard | Successful tokenization |
3782 822463 10005 |
American Express | Successful tokenization |
Use any future expiry date (e.g., 12/30) and any 3-digit CVV (e.g., 123).
| Card Number | 3DS Behavior | Expected Result |
|---|---|---|
4000 0000 0000 0002 |
Requires 3DS challenge | Challenge appears, complete to succeed |
4000 0000 0000 0101 |
3DS authentication fails | Challenge fails with error |
4242 4242 4242 4242 |
Frictionless 3DS | No challenge, instant success |
Contact your Spreedly account manager or Forter support for complete test card lists specific to your configuration.
Use test amounts (not card numbers) to trigger different 3DS scenarios:
| Amount (cents) | Scenario |
|---|---|
| 3001 | Frictionless flow |
| 3003 | Device fingerprint + direct authorize |
| 3004 | Device fingerprint + challenge |
| 3005 | Direct challenge |
| 3103 | Fingerprint failure |
| 3104 | Challenge failure |
Test card numbers for gateway-specific 3DS:
4000000000001091 -- Triggers 3DS challenge
4000000000001109 -- Frictionless 3DS (no challenge)
Your purchase request must include attempt_3dsecure: true for 3DS to trigger.
| Field | Brazil (Pix/Boleto/NuPay) | Mexico (OXXO) |
|---|---|---|
| CPF/Document | 853.513.468-93 |
Not required |
| Name | Ana Santos Araujo |
Manuela E. Beyer Rocabado |
test@test.com |
test@test.com |
|
| Phone | 8522847035 |
(040) 577-7687 |
| Address | Rua E, 1040 |
Oyono, 882 |
| City | Maracanaú |
Hermosillo |
| State | CE |
Sonora |
| Zip | 12345 |
48822 |
| Country | BR |
MX |
| Currency | BRL |
MXN |
- Initialize the SDK with fresh backend-signed parameters via
SpreedlyCore.initSdk() - Call
SpreedlyCore.paymentBottomSheet()to present the payment sheet - Enter a test card number, future expiry, and any CVV
- Tap "Pay"
- Collect the result via
SpreedlyEventEmitter:kind: 'success'with atokenmeans successful tokenizationkind: 'failed'indicates an error -- checkerrorTypeandmessagekind: 'canceled'means the user dismissed the sheet
import {
SpreedlyCore,
SpreedlyEventEmitter,
SpreedlyEventTypes,
mapPaymentResult,
} from '@spreedly/react-native-checkout';
const subscription = SpreedlyEventEmitter.addListener(
SpreedlyEventTypes.PAYMENT_BOTTOM_SHEET_RESULT,
(result) => {
const mapped = mapPaymentResult(result);
console.log('Payment result:', mapped.kind);
}
);
SpreedlyCore.paymentBottomSheet({ yearFormat: '4' });- Initialize the SDK
- Render
SPLTextFieldcomponents for card, expiry, and CVV - Fill in test card data
- Call
SpreedlyCore.createCreditCard()with form fields and any additional fields - Verify
kind: 'success'via the payment result listener
import { SPLTextField, FormFieldTypes } from '@spreedly/react-native-checkout';
<SPLTextField formFieldType={FormFieldTypes.CARD} label="Card Number" />
<SPLTextField formFieldType={FormFieldTypes.EXPIRY_DATE} label="MM/YY" />
<SPLTextField formFieldType={FormFieldTypes.CVV} label="CVV" />- Initialize the SDK
- Set up a listener on
SpreedlyEventTypes.RECACHE_RESULT - Present the recache UI with a saved payment method token
- Enter any 3-digit CVV
- Submit and verify
kind: 'success'
See CVV Recaching Guide for configuration details.
- Initialize the SDK with
forterSiteIdin your init options - Tokenize a card and send the token to your backend to create a purchase
- If the purchase response includes
sca_authentication, callSpreedlyCore.showThreeDSChallenge(transactionToken) - Complete the challenge in the Forter UI
- Collect results from
SpreedlyEventTypes.THREE_DS_CHALLENGE_RESULT - Verify events in the Forter Portal under Sandbox > Mobile Events Viewer
See 3DS Guide for the full integration.
- Initialize the SDK
- Tokenize a card, send the token to your backend
- Create a purchase with
attempt_3dsecure: trueand a test amount (e.g., 3005 cents for a direct challenge) - If the response includes
required_action, callSpreedlyCore.showGatewaySpecific3DSChallenge(transactionToken) - The challenge opens in a browser view
- Complete the challenge and verify the result via
SpreedlyEventTypes.GATEWAY_SPECIFIC_3DS_RESULT
See 3DS Gateway Guide for the full integration.
- Initialize the SDK
- Create an offsite payment method via your backend
- Tokenize, purchase via your backend, then call
SpreedlyCore.presentOffsitePayment(transactionToken)with the redirect URL - Complete checkout on the SPREL test page in the browser
- Verify the deep link returns to your app and
OFFSITE_PAYMENT_RESULTevent fires
See Offsite Payments Guide for PayPal and EBANX flows.
- Initialize the SDK
- Install the Stripe APM package:
@spreedly/react-native-checkout-stripe-apm - Create a purchase on your backend with
payment_method_type: 'stripe_apm' - Configure with Stripe test keys and the
clientSecretfrom the purchase response - Present the Stripe PaymentSheet via
StripeAPM.presentCheckout(config) - Select an APM (e.g., iDEAL) and complete the test payment
- Verify
STRIPE_APM_RESULTevent
See Stripe APM Guide for the full integration.
- Configure a Braintree sandbox gateway in your Spreedly environment
- Install the Braintree APM package:
@spreedly/react-native-checkout-braintree-apm - Create a purchase on your backend with the Braintree gateway
- Use sandbox credentials for PayPal and Venmo testing
- PayPal: use PayPal sandbox buyer accounts for the PayPal checkout flow
- Venmo: requires the Venmo app installed on the test device, or use Braintree SDK test mode
See Braintree Payment Guide for the full integration.
- Initialize the SDK with fresh backend-signed parameters via
SpreedlyCore.initSdk() - Enable screenshot protection:
ScreenSecurity.activateProtection() - Drop-in sheet: call
SpreedlyCore.achBankAccountBottomSheet(options)and listen onSpreedlyEventTypes.ACH_BANK_ACCOUNT_BOTTOM_SHEET_RESULT - Custom form: render
SPLTextFieldforROUTING_NUMBER,ACCOUNT_NUMBER, and name; callSpreedlyCore.createBankAccount(options) - Use sandbox routing/account values from your Spreedly environment docs
- Verify
mapped.kind === 'success'(sheet) orstatus === 'completed'(custom form), then callSpreedlyCore.resetPaymentState()
See ACH Bank Account Guide for the full integration.
- Install
@spreedly/react-native-checkout-stripe-radarand complete platform setup (iOS Stripe bundle rename script) - Initialize core with
SpreedlyCore.initSdk() - Call
StripeRadar.createRadarSession({ publishableKey })with a Stripe test publishable key - Verify a non-null
radar_session_id(rse_…) is returned - Attach the session ID on your backend to Spreedly purchase/authorization requests
See Stripe Radar Guide for the full integration.
// Test validation errors -- use empty required fields
SpreedlyCore.createCreditCard({
additionalFields: {
first_name: '',
last_name: '',
},
});
// Test success -- enter test card "4111111111111111" in the UI first
SpreedlyCore.createCreditCard({
additionalFields: {
first_name: 'John',
last_name: 'Doe',
},
});| Scenario | Mapped outcome | errorType |
|---|---|---|
| Real card in test environment | kind: 'failed' |
API_ERROR (account inactive) |
| Empty required fields | kind: 'validation' |
N/A (validation result) |
| Invalid/expired auth params | kind: 'failed' |
API_ERROR |
| No network | kind: 'failed' |
NETWORK_ERROR |
| Unexpected error | kind: 'failed' |
UNKNOWN_ERROR |
For full error handling patterns, see Integration Guide -- Error Handling.
During development, use React Native's Metro console and platform-specific log tools:
React Native (Metro):
SDK events logged to the console are visible in Metro output. Add temporary logging to your event listeners during testing:
SpreedlyEventEmitter.addListener(
SpreedlyEventTypes.PAYMENT_BOTTOM_SHEET_RESULT,
(result) => {
const mapped = mapPaymentResult(result);
if (__DEV__) {
console.log('Payment result kind:', mapped.kind);
}
}
);Android (Logcat):
adb logcat | grep -E "(Spreedly|SpreedlyCheckout)"iOS (Xcode):
Filter the Xcode console by Spreedly to see SDK log output.
The SDK sends diagnostic telemetry to Spreedly by default (see Diagnostic telemetry). This telemetry is not available in your own tools. To check SDK behavior during testing:
- Turn on SDK console logs -- SDK console output is off by default. While testing, call
SpreedlyCore.setLogLevel(LogLevel.DEBUG)and read the logs in Logcat or the Xcode console as shown above. This doesn't change telemetry. - Test with telemetry reduced -- If your app will ship with
SpreedlyCore.setDatadogLogLevel(LogLevel.ERROR), test with the same setting. See Integration Guide — Telemetry and logging. - Contacting Spreedly support -- Include the approximate time (UTC), platform and OS version, SDK version and your environment key, so Spreedly can find the matching telemetry.
The public example app has screens for every payment flow. This is the fastest way to verify SDK behavior end-to-end.
- Clone
https://github.com/spreedly/checkout-react-native-example.git - Copy
.env.exampleto.envand fill in your credentials - Install dependencies with
GITHUB_TOKENexported:yarn install - iOS only:
cd ios && pod install && cd .. - Start Metro:
yarn start - Run on Android:
yarn android, or on iOS:yarn ios
See the example app's README for prerequisites.
The example app includes screens for: Express Checkout (Payment Bottom Sheet), Hosted Fields, ACH Bank Account (drop-in sheet and custom form), CVV Recaching, 3DS Challenge, 3DS Gateway-Specific, Offsite Payments, EBANX, Stripe APM, Stripe Radar, and Braintree APM.
- Integration Guide -- Installation, initialization, and complete walkthrough
- Integration Guide -- Troubleshooting -- Symptom-based troubleshooting
- Express Checkout Guide -- Payment bottom sheet details
- Security -- Screenshot protection,, data handling, PCI compliance and vulnerability reporting policy
- Security -- Screen capture protection via
ScreenSecurity - Hosted Fields — PAN display and field state -- Merchant-safe field callbacks
- Integration Guide -- Telemetry and logging -- Reduce SDK telemetry