react-native-cashonrails

Cashonrails

Cashonrails is a lightweight React Native library that provides easy-to-integrate components and hooks for embedding a secure and customizable checkout or access code process into your application.

🚀 Installation

Use npm or yarn to add Cashonrails to your project:

npm install react-native-cashonrails
# or
yarn add react-native-cashonrails

🧩 Basic Usage

1. Wrap Your App with CashonrailsProvider

To enable context-based features (e.g., modals, configuration sharing), you must wrap your app with CashonrailsProvider.

import React from 'react';
import { CashonrailsProvider } from 'react-native-cashonrails';

const App = () => (
  <CashonrailsProvider>
    {/* Your components go here */}
  </CashonrailsProvider>
);

export default App;

2. Checkout Using CheckoutButton

The CheckoutButton component renders a styled button that opens the secure checkout modal when clicked.

import React from 'react';
import { CheckoutButton } from 'react-native-cashonrails';

const App = () => {
  const config = {
    api_key: 'your-api-key',
    amount: 1000,
    currency: 'USD',
    customer: {
      email: '[e-mail]',
      first_name: 'John',
      last_name: 'Doe',
      phone: '1234567890',
    },
    onComplete: (data) => console.log('Payment complete:', data),
    onCancel: (data) => console.log('Payment cancelled:', data),
  };

  return <CheckoutButton config={config} />;
};

export default App;

3. Trigger Checkout Directly with Checkout

The Checkout component opens the modal automatically when rendered.

import React from 'react';
import { Checkout } from 'react-native-cashonrails';

const App = () => {
  const config = {
    api_key: 'your-api-key',
    amount: 1000,
    currency: 'USD',
    customer: {
      email: '[e-mail]',
      first_name: 'John',
      last_name: 'Doe',
      phone: '1234567890',
    },
    onComplete: (data) => console.log('Payment complete:', data),
    onCancel: (data) => console.log('Payment cancelled:', data),
  };

  return <Checkout config={config} />;
};

export default App;

4. Use Access Code Flow via UseAccessCode

This component renders a modal-based WebView for handling access code-based flows.

import React from 'react';
import { UseAccessCode } from 'react-native-cashonrails';

const App = () => {
  const config = {
    access_code: 'your-access-code',
    onComplete: (data) => console.log('Access code success:', data),
    onCancel: (data) => console.log('Access code cancelled:', data),
  };

  return <UseAccessCode config={config} />;
};

export default App;

📘 API Reference

CheckoutButton

Prop	Type	Default	Description
config	CheckoutConfig	Required	Checkout configuration object
buttonText	string	'Checkout Securely'	Button label
style	React.CSSProperties	undefined	Custom style for the button container
textStyle	React.CSSProperties	undefined	Custom style for the button text
disabled	boolean	false	Disables the button
loadingText	string	'Processing...'	Text displayed when loading
showHeader	boolean	true	Display header text above button
headerText	string	'Secure payment powered by Cashonrails'	Header text
headerStyle	React.CSSProperties	undefined	Custom style for the header

Checkout

Prop	Type	Default	Description
config	CheckoutConfig	Required	Triggers checkout modal on render

UseAccessCode

Prop	Type	Default	Description
config	UseAccessCodeConfig	Required	Triggers access code modal on render

📦 Types

CheckoutConfig

type CheckoutConfig = {
  api_key: string;
  amount: number;
  currency: string;
  customer: {
    email: string;
    first_name: string;
    last_name: string;
    phone: string;
  };
  callback_url?: string;
  onComplete?: (data: Response) => void;
  onCancel?: (data: Response) => void;
  debug?: boolean;
};

UseAccessCodeConfig

type UseAccessCodeConfig = {
  access_code: string;
  callback_url?: string;
  onComplete?: (data: Response) => void;
  onCancel?: (data: Response) => void;
  debug?: boolean;
};

Response

type Response = {
  status: string;
  reference: string;
  transaction_date?: string;
  [key: string]: any;
};

CashonrailsContextType

type CashonrailsContextType = {
  openCheckout: (config: CheckoutConfig) => void;
  openAccessCode: (config: UseAccessCodeConfig) => void;
  subscribeToModalClose: (callback: () => void) => () => void;
  isDebug: boolean;
  setIsDebug: (value: boolean) => void;
};

📄 License

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