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: '[email protected]',
      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: '[email protected]',
      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.