React SDK

Crater React SDK is a library of ready-to-use React components. These components can help you embed invoicing and bill pay functionality into your React-based web application with just a few lines of code.

Works with:

Next.js

Installation

Step 1: Install the Crater React SDK via npm or yarn

The Crater React SDK package is available on the NPM and Yarn directories. To install:

npm install @crater/react-sdk

Step 2: Configure `CraterSDK` instance

The CraterSDK instance provides configuration for all Crater React UI components through the CraterProvider wrapper.

JavaScript

const crater = new CraterSDK({
  tenantUrl: 'https://payments.your-domain.com', // We will provide you with the API URL to use
});

Properties

Name
tenantUrl
Type
string
Description
The URL for the API in use.

Step 3: Set Crater access token

In order to authorise the SDK components to access the Crater API, you need to first generate a business access token from your backend. Once you have the access token, you need to call setToken method to save the access token in the SDK. You can view our Authentication documentation for more information on how to generate a new business access token.

JavaScript

import { authService } from '@crater/react-sdk'

authService.setToken(`YOUR_ACCESS_TOKEN`)

Step 4: Configure `CraterProvider`

Wrap your root component with CraterProvider.

The CraterProvider is the root component that must wrap all other Crater-connected components. The wrapper provides configuration for all Crater components beneath it.

App.tsx

<CraterProvider crater={crater} locale="en">
  <div className="App">...</div>
</CraterProvider>

Step 5: Import Components and Styles

Import the components you want to use from the Crater React SDK package and the stylesheet. Any other components imported from @crater/react-sdk must be placed inside the CraterProvider provider.

App.tsx

import { CraterProvider, CraterSDK, InvoiceTable } from '@crater/react-sdk'
import '@crater/react-sdk/dist/style.css'

return (
  <CraterProvider crater={crater} locale="en">
    <InvoiceTable />
  </CraterProvider>
)

Step 6: Review implementation

If you followed the above steps correctly, your code should look like this:

App.tsx

import { CraterProvider, CraterSDK, InvoiceTable } from '@crater/react-sdk'
import { authService } from '@crater/react-sdk'
import '@crater/react-sdk/dist/style.css'

function App() {
  useEffect(() => {
    fetchCraterToken()
  }, [])

  const fetchCraterToken = () => {
    fetch(`https://your-backend-api.com/access-token`).then((response) => {
      authService.setToken(response.token)
    })
  }

  const crater = new CraterSDK({
    tenantUrl: 'https://payments.your-domain.com', // We will provide you with the TENANT URL to use
  })

  return (
    <CraterProvider crater={crater} locale="en">
      <InvoiceTable />
    </CraterProvider>
  )
}

export default App

Step 7: Run the application

npm run start

Theme Config

You can use your own theme colors by updating the following CSS variables inside :root selector.

style.css

:root {
    --cr-color-primary-50: 247, 246, 253;
    --cr-color-primary-100: 238, 238, 251;
    --cr-color-primary-200: 213, 212, 245;
    --cr-color-primary-300: 188, 185, 239;
    --cr-color-primary-400: 138, 133, 228;
    --cr-color-primary-500: 88, 81, 216;
    --cr-color-primary-600: 79, 73, 194;
    --cr-color-primary-700: 53, 49, 130;
    --cr-color-primary-800: 40, 36, 97;
    --cr-color-primary-900: 26, 24, 65;
}

You can use the Tailwind Shades Generator to generate your own color theme. Just make sure to change the css color variable names correctly as given above after you copy the theme from the shades generator.

Invoice Table

This component displays all invoices created by a business. The component shows each invoice's amount, status, due date, overdue date, and the counterpart to which they were sent.

Preview

Usage

Import the InvoiceTable component and use it in your application as shown below:

Invoices.tsx

import { InvoiceTable } from '@crater/react-sdk';

...

// NOTE: This component must be rendered within the CraterProvider wrapper
return (
  <>
    <InvoiceTable />
  </>
);

Props

Name
onRowClick
Type
function
Description
It is triggered when an invoice table row is clicked. Its parameter is the identifier of the clicked row. You can use this callback to navigate to the invoice details page.

Invoice Create

This component serves as an interface for users to input and submit information essential for generating a new invoice. It handles the UI elements & data validation to create invoices within your application.

Preview

Usage

Import the InvoiceCreate component and use it in your application as shown below:

Invoice.tsx

import { InvoiceCreate } from '@crater/react-sdk';

...

// NOTE: This component must be rendered within the CraterProvider wrapper
return (
  <>
    <InvoiceCreate />
  </>
);

Props

Name
onCreate
Type
function
Description
Triggered when an invoice is created successfully.

Invoice Edit

This component renders a form for editing a pre-existing invoice. It encompasses functionalities tailored to allow users to update specific details of an invoice.

Preview

Usage

Import the InvoiceEdit component and use it in your application as shown below:

Invoice.tsx

import { InvoiceEdit } from '@crater/react-sdk';

...

// NOTE: This component must be rendered within the CraterProvider wrapper
return (
  <>
    <InvoiceEdit id="INVOICE_ID" />
  </>
);

Props

Name
id
Type
string
Description
This is a required prop that accepts the ID of the invoice.
Name
onUpdate
Type
function
Description
Triggered when the invoice is updated successfully.

Invoice Details

This component renders the interface for displaying an existing invoice. It also allows performing various actions on the invoice such as editing, deleting, and sending it.

Preview

Usage

Use the InvoiceDetails component to view details of an existing invoice.

Invoice.tsx

import { InvoiceDetails } from '@crater/react-sdk';

...

// NOTE: This component must be rendered within the CraterProvider wrapper
return (
  <>
    <InvoiceDetails id="INVOICE_ID" />
  </>
);

Props

Name
id
Type
string
Description
This is a required prop that accepts the ID of the invoice details to be displayed.

Payments Onboarding

This component displays the current onboarding status by default and provides an option to start the onboarding process if it is not completed yet. It is usually used on the dashboard of the application after the user is logged in.

Preview

Usage

Import the BusinessPaymentStatus component and use it in your application as shown below:

PaymentStatus.tsx

import { BusinessPaymentStatus } from '@crater/react-sdk';

...

// NOTE: This component must be rendered within the CraterProvider wrapper
return (
  <>
    <BusinessPaymentStatus  />
  </>
);

Payment Element

This component renders a payment form for paying a single invoice. It supports all the payment methods that are configured in your tenant settings.

Preview

Usage

Import the PaymentElement component and use it in your application as shown below:

Payment.tsx

import { PaymentElement } from '@crater/react-sdk';

...

// NOTE: This component must be rendered within the CraterProvider wrapper
return (
  <>
    <PaymentElement id="INVOICE_ID" />
  </>
);

Props

Name
id
Type
string
Description
This is a required prop that accepts the ID of the invoice to be payed.
Name
onSuccess
Type
function
Description
Triggered when the payment process is successfully completed, indicating that the payment was successful.
Name
onError
Type
function
Description
Triggered when any error occurs during the payment process.

Customer Table

This component displays a table of all customers. The component shows each customer's name, email and amount due as well as other required details.

Preview

Usage

Import the CustomerTable and use it in your application as shown below:

Customers.tsx

import { CustomerTable } from '@crater/react-sdk';

...

// NOTE: This component must be rendered within the CraterProvider wrapper
return (
  <>
    <CustomerTable />
  </>
);

Props

Name
onRowClick
Type
function
Description
This callback is triggered when a customer table row is clicked. Its parameter is the identifier of the clicked row. You can use this callback to navigate to the customer details page.

Customer Details

This component renders UI to view details of a single customer and allows performing various actions on the customer.

Preview

Usage

Customer.tsx

import { CustomerDetails } from '@crater/react-sdk';

...

// NOTE: This component must be rendered within the CraterProvider wrapper
return (
  <>
    <CustomerDetails id="CUSTOMER_ID" />
  </>
);

Props

Name
id
Type
string
Description
This is a required prop that accepts the ID of the customer details to be displayed.

Customer Create

This component serves as an interface for users to input and submit information essential for creating a new customer. It handles the UI elements, data validation, and submission of the form.

Preview

Usage

Import the CustomerCreate component and use it in your application as shown below:

Customer.tsx

import { CustomerCreate } from '@crater/react-sdk';

...

// NOTE: This component must be rendered within the CraterProvider wrapper
return (
  <>
    <CustomerCreate />
  </>
);

Props

Name
onCreate
Type
function
Description
Triggered when a customer is created successfully.

Customer Edit

This component renders the UI for editing a pre-existing customer. It encompasses functionalities tailored to allow users to update specific details of a customer.

Preview

Usage

Import the CustomerEdit component and use it in your application as shown below:

Customer.tsx

import { CustomerEdit } from '@crater/react-sdk';

...

// NOTE: This component must be rendered within the CraterProvider wrapper
return (
  <>
    <CustomerEdit id="CUSTOMER_ID" />
  </>
);

Props

Name
id
Type
string
Description
This is a required prop that accepts the ID of the customer.
Name
onUpdate
Type
function
Description
Triggered when the customer is updated successfully.

Estimate Table

This component displays all estimates created by a business. The component shows each estimate's amount, status, due date, overdue date, and the counterpart to which they were sent.

Preview

Usage

Import the EstimateTable component and use it in your application as shown below:

Estimates.tsx

import { EstimateTable } from '@crater/react-sdk';

...

// NOTE: This component must be rendered within the CraterProvider wrapper
return (
  <>
    <EstimateTable />
  </>
);

Props

Name
onRowClick
Type
function
Description
It is triggered when an estimate table row is clicked. Its parameter is the identifier of the clicked row. You can use this callback to navigate to the estimate details page.

Estimate Details

This component renders the interface for displaying an existing estimate. It also allows performing various actions on the estimate such as editing, deleting, and sending it.

Preview

Usage

Use the EstimateDetails component to view details of an existing estimate.

Estimate.tsx

import { EstimateDetails } from '@crater/react-sdk';

...

// NOTE: This component must be rendered within the CraterProvider wrapper
return (
  <>
    <EstimateDetails id="ESTIAMTE_ID" />
  </>
);

Props

Name
id
Type
string
Description
This is a required prop that accepts the ID of the estimate details to be displayed.

Estimate Create

This component serves as an interface for users to input and submit information essential for generating a new estimate. It handles the UI elements & data validation to create estimates within your application.

Preview

Usage

Import the EstimateCreate component and use it in your application as shown below:

Estimate.tsx

import { EstimateCreate } from '@crater/react-sdk';

...

// NOTE: This component must be rendered within the CraterProvider wrapper
return (
  <>
    <EstimateCreate />
  </>
);

Props

Name
onCreate
Type
function
Description
Triggered when an estimate is created successfully.

Estimate Edit

This component renders a form for editing a pre-existing estimate. It encompasses functionalities tailored to allow users to update specific details of an estimate.

Preview

Usage

Import the EstimateEdit component and use it in your application as shown below:

Estimate.tsx

import { EstimateEdit } from '@crater/react-sdk';

...

// NOTE: This component must be rendered within the CraterProvider wrapper
return (
  <>
    <EstimateEdit id="ESTIMATE_ID" />
  </>
);

Props

Name
id
Type
string
Description
This is a required prop that accepts the ID of the estimate.
Name
onUpdate
Type
function
Description
Triggered when the estimate is updated successfully.

Integration Settings

This component renders a list of integrations available on the given business. Users can choose to connect any of the given integration partners to automatically sync their data.

Preview

Usage

Import the IntegrationSettings component and use it in your application as shown below:

IntegrationSettings.tsx

import { IntegrationSettings } from '@crater/react-sdk';

...

// NOTE: This component must be rendered within the CraterProvider wrapper
return (
  <>
    <IntegrationSettings  />
  </>
);

React SDK

Works with:

Step 1: Install the Crater React SDK via npm or yarn

Step 2: Configure CraterSDK instance

JavaScript

Properties

Step 3: Set Crater access token

JavaScript

Step 4: Configure CraterProvider

App.tsx

Step 5: Import Components and Styles

App.tsx

Step 6: Review implementation

App.tsx

Step 7: Run the application

style.css

Preview

Usage

Invoices.tsx

Props

Preview

Usage

Invoice.tsx

Props

Preview

Usage

Invoice.tsx

Props

Preview

Usage

Invoice.tsx

Props

Preview

Usage

PaymentStatus.tsx

Preview

Usage

Payment.tsx

Props

Preview

Usage

Customers.tsx

Props

Preview

Usage

Customer.tsx

Props

Preview

Usage

Customer.tsx

Props

Preview

Usage

Customer.tsx

Props

Preview

Usage

Estimates.tsx

Props

Preview

Usage

Estimate.tsx

Props

Preview

Usage

Estimate.tsx

Props

Preview

Usage

Estimate.tsx

Props

Preview

Usage

IntegrationSettings.tsx

Step 2: Configure `CraterSDK` instance

Step 4: Configure `CraterProvider`