API-driven boarding quickstart

Applies to:Developers

This guide covers setting up a custom app for processing boarding applications using example code, including modifying the form layout, applying a custom theme, and changing individual form fields. The result is a custom app that caters to private corporations with a fulfillment window of 30 days or less on all transactions and a minimum average transaction amount of $100 USD.

Hosting your own boarding solution means that you’re responsible for maintaining it. Talk to your Payabli solutions engineer about whether API-driven boarding is a good option for your organization.

Visit the repository’s README for information about specific files, functions, component props, and other technical details.

Dependencies

Before you begin, make sure you have the following installed on your machine:

Set up the app

Run these commands in your terminal to configure the boarding example app on your local machine:

Clone the repo

$ git clone https://github.com/payabli/examples

Navigate to the app directory

$ cd examples/boarding

Install the dependencies

$ npm install

Copy the environment template

$ cp .env.template .env

Fill in your environment variables

Open the .env file in your code editor. Set PAYABLI_API_TOKEN to your Payabli API token and BETTER_AUTH_SECRET to any text string with a length of 32 characters:

  # your Payabli API token
  PAYABLI_API_TOKEN="123...XYZ"
  # which Payabli environment to use
  PAYABLI_ENVIRONMENT="sandbox"
  # your better-auth secret
  BETTER_AUTH_SECRET=ABCDEFGHIJKLMNOPQRSTUVWXYZ123456
  # base URL of your app
  BETTER_AUTH_URL=http://localhost:4321 # https://my-production-site.com

The BETTER_AUTH_SECRET is a string used to encrypt sensitive information. You can generate a 32-character string using the secret key generator in the better-auth documentation. The BETTER_AUTH_URL is the base URL of your app.

Set up better-auth

Enter “yes” for all prompts:

$ npx @better-auth/cli generate
> npx @better-auth/cli migrate

Start the development server

$ npm run dev

Authentication

The example boarding app uses a JavaScript library called better-auth for user authentication. Authentication is important because it prevents access to secure information by unauthorized users.

Open your app

Navigate to http://localhost:4321 in your web browser to see the login page.

Authenticate

After you sign up, you’ll be authenticated and see the boarding form.

Screenshot of boarding app — Boarding Example App

Customize the boarding form

The boarding form is built with React components that you can customize to fit your business needs. Follow the walkthrough below to learn how to move form fields, change section details, add validation rules, and more:

Loading walkthrough content

Loading walkthrough...

+++ Modify form steps ++ Move the “Business Summary” field from the “Financial Information” section to the “Business Information.” Then rename the section to “Corporation Overview”.

/// Find the Financial Information section

The “Financial Information” section contains fields for financial statistics about a merchant. It’s located in the src/components/PayabliForm.tsx file.

1 // src/components/PayabliForm.tsx
2 <WizardStep icon={<Banknote />} label="Financial Information">
3     <h2 className="mb-4 w-full text-center text-2xl font-bold">
4       Step 4: Financial Information
5     </h2>
6     <div className="items-end gap-4 md:grid md:grid-cols-2">
7       <FormInput
8         name="bsummary"
9         label="Business Summary"
10         tooltip="Brief description of your business activities"
11       />
12     // ...
13 </WizardStep>

/// Delete the bsummary field

Cut the bsummary field from the “Financial Information” section. You’ll paste this later.

1 // src/components/PayabliForm.tsx
2 <WizardStep icon={<Banknote />} label="Financial Information">
3     <h2 className="mb-4 w-full text-center text-2xl font-bold">
4       Step 4: Financial Information
5     </h2>
6     <div className="items-end gap-4 md:grid md:grid-cols-2">
7     // ...
8 </WizardStep>

/// Find the Business Information section

The “Business Information” section contains fields for legal name and other business details.

1 // src/components/PayabliForm.tsx
2 <WizardStep icon={<Building />} label="Business Information">
3   <h2 className="mb-4 w-full text-center text-2xl font-bold">
4     Step 1: Business Information
5   </h2>
6   <div className="items-end gap-4 md:grid md:grid-cols-2">
7     <FormInput
8       name="legalname"
9       label="Legal Name"
10       tooltip="The official registered name of your business"
11     />
12   // ...
13 </WizardStep>

/// Move business summary field

Add the business summary field to the “Business Information” section.

-16

1 // src/components/PayabliForm.tsx
2 <WizardStep icon={<Building />} label="Business Information">
3   <h2 className="mb-4 w-full text-center text-2xl font-bold">
4     Step 1: Business Information
5   </h2>
6   <div className="items-end gap-4 md:grid md:grid-cols-2">
7     <FormInput
8       name="legalname"
9       label="Legal Name"
10       tooltip="The official registered name of your business"
11     />
12     <FormInput
13       name="bsummary"
14       label="Business Summary"
15       tooltip="Brief description of your business activities"
16     />
17   // ...
18 </WizardStep>

/// Change section label

Change the wizard step’s label prop to say “Corporation Overview” instead of “Business Information”. Then change the icon prop to use the Briefcase icon provided by lucide.dev. Make sure to import the Briefcase icon at the top of the file.

-4

1 // src/components/PayabliForm.tsx
2 <WizardStep icon={<Briefcase />} label="Corporation Overview">
3   <h2 className="mb-4 w-full text-center text-2xl font-bold">
4     Step 1: Corporation Overview
5   </h2>
6   <div className="items-end gap-4 md:grid md:grid-cols-2">
7     <FormInput
8       name="legalname"
9       label="Legal Name"
10       tooltip="The official registered name of your business"
11     />
12     <FormInput
13       name="bsummary"
14       label="Business Summary"
15       tooltip="Brief description of your business activities"
16     />
17   // ...
18 </WizardStep>

+++ Update form schema ++ Update the form schema to reflect the changes we made to the form fields.

/// Find the form schema

The schema defines validation rules and default values for form fields. It’s located in the src/Schema.ts file.

1 // src/Schema.ts
2 import { z } from 'zod';
3 
4 const requireString = () => z.string().min(1, { message: 'This field is required' });
5 const requiredNumber = () => z.coerce.number().min(1, { message: 'This field is required' });
6 
7 export const formSchema = z.object({
8   // ... other fields
9   legalname: requireString(),
10   btype: requireString(),
11   ticketamt: requiredNumber(),
12   // ... other fields
13 });

/// Add minimum validation

Add a minimum value validation for the ticket amount field.

-13

1 // src/Schema.ts
2 import { z } from 'zod';
3 
4 const requireString = () => z.string().min(1, { message: 'This field is required' });
5 const requiredNumber = () => z.coerce.number().min(1, { message: 'This field is required' });
6 
7 export const formSchema = z.object({
8   // ... other fields
9   legalname: requireString(),
10   btype: requireString(),
11   ticketamt: requiredNumber().min(100, { 
12     message: 'Ticket amount must be at least $100' 
13   }),
14   // ... other fields
15 });

/// Set default business type

Set a default value of “Private Corp” for the btype field.

1 // src/Schema.ts
2 import { z } from 'zod';
3 
4 const requireString = () => z.string().min(1, { message: 'This field is required' });
5 const requiredNumber = () => z.coerce.number().min(1, { message: 'This field is required' });
6 
7 export const formSchema = z.object({
8   // ... other fields
9   legalname: requireString(),
10   btype: requireString().default("Private Corp"),
11   ticketamt: requiredNumber().min(100, { 
12     message: 'Ticket amount must be at least $100' 
13   }),
14   // ... other fields
15 });

+++ Customize form fields ++ Customize the labels, tooltips, and options for specific form fields.

/// Find ticketamt field

Find the <FormInput> component for the ticket amount field.

1 // src/components/PayabliForm.tsx
2 // ... other fields
3 <FormInput
4   name="ticketamt"
5   label="Ticket Amount"
6   tooltip="Average amount per transaction"
7   prefix="$"
8   numeric
9 />
10 // ... other fields

/// Specify minimum ticket amount

Customize the ticket amount field to show the minimum requirement.

-6

1 // src/components/PayabliForm.tsx
2 // ... other fields
3 <FormInput
4   name="ticketamt"
5   label="Ticket Amount ($100+)"
6   tooltip="Average amount per transaction (min. $100)"
7   prefix="$"
8   numeric
9 />
10 // ... other fields

/// Find whenDelivered field

Find the <FormSelect> component for the delivery timeframe field.

1 // src/components/PayabliForm.tsx
2 // ... other fields
3 <FormSelect
4   name="whenDelivered"
5   label="When Delivered"
6   options={[
7     { value: '0-7 Days', label: '0-7 Days' },
8     { value: '8-14 Days', label: '8-14 Days' },
9     { value: '15-30 Days', label: '15-30 Days' },
10     { value: 'Over 30 Days', label: 'Over 30 Days' },
11   ]}
12   tooltip="Typical timeframe for delivering products or services"
13 />
14 // ... other fields

/// Remove “Over 30 Days” option

Remove the “Over 30 Days” option from the delivery timeframe field.

-9

1 // src/components/PayabliForm.tsx
2 // ... other fields
3 <FormSelect
4   name="whenDelivered"
5   label="When Delivered"
6   options={[
7     { value: '0-7 Days', label: '0-7 Days' },
8     { value: '8-14 Days', label: '8-14 Days' },
9     { value: '15-30 Days', label: '15-30 Days' },
10   ]}
11   tooltip="Typical timeframe for delivering products or services"
12 />
13 // ... other fields

/// Find whenRefunded field

Find the <FormSelect> component for the refund timeframe field.

1 // src/components/PayabliForm.tsx
2 // ... other fields
3 <FormSelect
4   name="whenRefunded"
5   label="When Refunded"
6   options={[
7     { value: 'Exchange Only', label: 'Exchange Only' },
8     { value: 'No Refund or Exchange', label: 'No Refund or Exchange' },
9     { value: '30 Days or Less', label: '30 Days or Less' },
10     { value: 'Over 30 Days', label: 'Over 30 Days' },
11   ]}
12   tooltip="Typical timeframe for processing refunds"
13 />
14 // ... other fields

/// Remove “Over 30 Days” refund option

Remove the “Over 30 Days” option from the refund timeframe field.

-9

1 // src/components/PayabliForm.tsx
2 // ... other fields 
3 <FormSelect
4   name="whenRefunded"
5   label="When Refunded"
6   options={[
7     { value: 'Exchange Only', label: 'Exchange Only' },
8     { value: 'No Refund or Exchange', label: 'No Refund or Exchange' },
9     { value: '30 Days or Less', label: '30 Days or Less' },
10   ]}
11   tooltip="Typical timeframe for processing refunds"
12 />
13 // ... other fields

Customize the app theme

The example app is built with shadcn/ui and Tailwind CSS. You can customize the app’s appearance by modifying the CSS file located at styles/globals.css. The :root selector contains CSS variables that apply to light mode, and the .dark selector contains CSS variables for dark mode.

Default theme

1 @tailwind base;
2 @tailwind components;
3 @tailwind utilities;
4 
5 @layer base {
6   :root {
7     --background: 0 0% 100%;
8     --foreground: 240 10% 3.9%;
9     --card: 0 0% 100%;
10     --card-foreground: 240 10% 3.9%;
11     --popover: 0 0% 100%;
12     --popover-foreground: 240 10% 3.9%;
13     --primary: 240 5.9% 10%;
14     --primary-foreground: 0 0% 98%;
15     --secondary: 240 4.8% 95.9%;
16     --secondary-foreground: 240 5.9% 10%;
17     --muted: 240 4.8% 95.9%;
18     --muted-foreground: 240 3.8% 46.1%;
19     --accent: 240 4.8% 95.9%;
20     --accent-foreground: 240 5.9% 10%;
21     --destructive: 0 84.2% 60.2%;
22     --destructive-foreground: 0 0% 98%;
23     --border: 240 5.9% 90%;
24     --input: 240 5.9% 90%;
25     --ring: 240 5.9% 10%;
26     --radius: 0.5rem;
27     --chart-1: 12 76% 61%;
28     --chart-2: 173 58% 39%;
29     --chart-3: 197 37% 24%;
30     --chart-4: 43 74% 66%;
31     --chart-5: 27 87% 67%;
32   }
33 
34   .dark {
35     --background: 240 10% 3.9%;
36     --foreground: 0 0% 98%;
37     --card: 240 10% 3.9%;
38     --card-foreground: 0 0% 98%;
39     --popover: 240 10% 3.9%;
40     --popover-foreground: 0 0% 98%;
41     --primary: 0 0% 98%;
42     --primary-foreground: 240 5.9% 10%;
43     --secondary: 240 3.7% 15.9%;
44     --secondary-foreground: 0 0% 98%;
45     --muted: 240 3.7% 15.9%;
46     --muted-foreground: 240 5% 64.9%;
47     --accent: 240 3.7% 15.9%;
48     --accent-foreground: 0 0% 98%;
49     --destructive: 0 62.8% 30.6%;
50     --destructive-foreground: 0 0% 98%;
51     --border: 240 3.7% 15.9%;
52     --input: 240 3.7% 15.9%;
53     --ring: 240 4.9% 83.9%;
54     --chart-1: 220 70% 50%;
55     --chart-2: 160 60% 45%;
56     --chart-3: 30 80% 55%;
57     --chart-4: 280 65% 60%;
58     --chart-5: 340 75% 55%;
59   }
60 }
61 
62 @layer base {
63   * {
64     @apply border-border;
65   }
66 
67   html {
68     @apply scroll-smooth;
69   }
70 
71   body {
72     @apply bg-background text-foreground;
73     font-synthesis-weight: none;
74     text-rendering: optimizeLegibility;
75   }
76 }
77 
78 @layer base {
79     img {
80         display: initial;
81     }
82 }

Additional customization

To learn more about the available props for the form components and additional customization options, see the following resources:

Form fields: See the example app’s README for available props
Icons: Browse available icons at lucide.dev

See these related resources to help you get the most out of Payabli.

Next steps

Manage notifications - Set up notifications to stay informed about boarding application status changes

References

Boarding API example - Full API-driven boarding application example on GitHub
Boarding statuses reference - Learn about statuses and substatuses during the merchant boarding process
Paypoint statuses - Learn about the different statuses of paypoints