Fundbox Checkout SDK for React Native

A React Native SDK that provides seamless integration with Fundbox's checkout process. This SDK allows you to easily implement Fundbox's payment processing in your React Native applications.

Installation

yarn add fundbox-checkout-sdk

or

npm install fundbox-checkout-sdk

Prerequisites

• React Native 0.76.7 or higher
• React 18.3.1 or higher
• Expo dependencies (expo-linking, expo-web-browser)

Usage

import { FundboxCheckout } from 'fundbox-checkout-sdk';

// Example usage
const handleCheckout = async () => {
  try {
    const result = await FundboxCheckout({
      fuse_partner_id: 'ABCD1234EF',
      fbx_transaction_token: 'sample-token-123e-4567-a890-123456789012',
      customer_token: 'customer-abc-456-def-789-sample123456',
      callback_url: 'yourapp://payment-result' // Optional: defaults to 'myapp://callback'
    });

    if (result.result === 'success') {
      // Payment successful
      console.log('Payment successful!');
      console.log('Transaction Token:', result.transactionToken);
      console.log('Partner ID:', result.partnerId);
      console.log('Timestamp:', result.timestamp);
    } else if (result.result === 'canceled') {
      // Payment was canceled by user
      console.log('Payment was canceled');
      if (result.reason) {
        console.log('Reason:', result.reason);
      }
    } else {
      // An error occurred
      console.log('Payment failed');
      if (result.error) {
        console.log('Error:', result.error);
      }
    }
  } catch (error) {
    console.error('Error during checkout:', error);
  }
};

API Reference

FundboxCheckout

The main function to initiate the checkout process.

Parameters

| Parameter | Type | Required | Description | | --------------------- | ------ | -------- | ------------------------------------ | | fuse_partner_id | string | Yes | The partner ID for Fuse integration | | fbx_transaction_token | string | Yes | The transaction token from Fundbox | | customer_token | string | Yes | The customer identification token | | callback_url | string | No | URL scheme for returning results (defaults to 'myapp://callback') | | base_url | string | No | The base URL for Fundbox checkout (defaults to 'https://app.fundbox.com'). The SDK will append '/checkout/' automatically |

Return Value

Returns a Promise that resolves to a TResultType object with the following structure:

type TResultType = {
  result: 'success' | 'canceled' | 'declined';
  type?: 'checkout_success' | 'checkout_canceled' | 'checkout_error';
  transactionToken?: string;
  partnerId?: string;
  customerToken?: string;
  timestamp?: string;
  reason?: string; // for canceled results
  error?: string;  // for error results
};

Example Implementation

Here's a complete example of how to integrate the SDK into your React Native component:

import React, { useState } from 'react';
import { View, Button, Alert } from 'react-native';
import { FundboxCheckout } from 'fundbox-checkout-sdk';

const CheckoutScreen = () => {
  const [loading, setLoading] = useState(false);

  const handlePayment = async () => {
    setLoading(true);
    try {
      const result = await FundboxCheckout({
        fuse_partner_id: 'YOUR_FUSE_PARTNER_ID',
        fbx_transaction_token: 'YOUR_TRANSACTION_TOKEN',
        customer_token: 'YOUR_CUSTOMER_TOKEN',
        callback_url: 'yourapp://checkout-result' // Use your app's URL scheme
      });

      if (result.result === 'success') {
        Alert.alert(
          'Success', 
          `Payment completed successfully!\nTransaction: ${result.transactionToken}`
        );
      } else if (result.result === 'canceled') {
        const reason = result.reason ? `\nReason: ${result.reason}` : '';
        Alert.alert('Canceled', `Payment was canceled${reason}`);
      } else {
        const errorMsg = result.error ? `\nError: ${result.error}` : '';
        Alert.alert('Error', `Payment failed. Please try again.${errorMsg}`);
      }
    } catch (error) {
      Alert.alert('Error', 'An unexpected error occurred');
      console.error('Checkout error:', error);
    } finally {
      setLoading(false);
    }
  };

  return (
    <View style={{ flex: 1, justifyContent: 'center', padding: 20 }}>
      <Button
        title={loading ? 'Processing...' : 'Pay with Fundbox'}
        onPress={handlePayment}
        disabled={loading}
      />
    </View>
  );
};

export default CheckoutScreen;

Base URL Configuration

The base_url parameter is optional and defaults to https://app.fundbox.com. You only need to specify it if you're using a different Fundbox environment (e.g., staging or testing).

The SDK automatically appends /checkout/ to the base URL.

Default behavior (production):

// Uses: https://app.fundbox.com/checkout/
await FundboxCheckout({
  fuse_partner_id: 'YOUR_FUSE_PARTNER_ID',
  fbx_transaction_token: 'YOUR_TRANSACTION_TOKEN',
  customer_token: 'YOUR_CUSTOMER_TOKEN',
});

Custom base URL (for testing/staging):

// Uses: https://sdk-example.fundbox.com/checkout/
await FundboxCheckout({
  fuse_partner_id: 'YOUR_FUSE_PARTNER_ID',
  fbx_transaction_token: 'YOUR_TRANSACTION_TOKEN',
  customer_token: 'YOUR_CUSTOMER_TOKEN',
  base_url: 'https://sdk-example.fundbox.com',
});

Important: Do NOT include /checkout/ in your base_url parameter. The SDK handles this automatically.

URL Scheme Configuration

To receive payment results, you need to configure your app to handle URL schemes. The callback_url parameter should match your app's URL scheme configuration.

Expo Configuration

Add your URL scheme to app.json:

{
  "expo": {
    "scheme": "yourapp"
  }
}

React Native Configuration

iOS (Info.plist)

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>yourapp</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>yourapp</string>
    </array>
  </dict>
</array>

Android (AndroidManifest.xml)

<activity
  android:name=".MainActivity"
  android:exported="true"
  android:launchMode="singleTask">
  <intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="yourapp" />
  </intent-filter>
</activity>

Callback URL Examples

// Basic callback
callback_url: 'yourapp://callback'

// More descriptive paths
callback_url: 'yourapp://payment-result'
callback_url: 'yourapp://checkout-complete'

// Nested paths for better organization
callback_url: 'yourapp://payments/fundbox-result'
callback_url: 'yourapp://checkout/success'

Response Data

The SDK returns rich response data for all scenarios:

Success Response

{
  result: 'success',
  type: 'checkout_success',
  transactionToken: '4e5c275e-a74d-4d76-8646-52b7c4855823',
  partnerId: 'F4X6E3RXUQ',
  customerToken: '53fc35dc-5569-4d66-81f2-203cd4cd7a6d',
  timestamp: '2025-07-28T04:59:40.657Z'
}

Canceled Response

{
  result: 'canceled',
  type: 'checkout_canceled',
  reason: 'user_canceled',
  transactionToken: '4e5c275e-a74d-4d76-8646-52b7c4855823',
  partnerId: 'F4X6E3RXUQ',
  customerToken: '53fc35dc-5569-4d66-81f2-203cd4cd7a6d',
  timestamp: '2025-07-28T04:59:15.641Z'
}

Error Response

{
  result: 'declined',
  type: 'checkout_error',
  error: 'Payment method declined',
  transactionToken: '4e5c275e-a74d-4d76-8646-52b7c4855823',
  partnerId: 'F4X6E3RXUQ',
  customerToken: '53fc35dc-5569-4d66-81f2-203cd4cd7a6d',
  timestamp: '2025-07-28T04:59:30.123Z'
}

Error Handling

The SDK handles various scenarios and returns appropriate results:

• result: 'success': Payment was successful
• result: 'canceled': User canceled the payment process
• result: 'declined': The payment was declined or failed

Contributing

We welcome contributions! Please see our Contributing Guidelines for more information.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support, please open an issue in the GitHub repository.

Made with create-react-native-library