### Start Local Development Server

Source: https://github.com/justifi-tech/public-docs/blob/main/README.md

Use this command to start a local development server. Changes are reflected live without a server restart.

```bash
$ pnpm run start
```

--------------------------------

### Start Local Web Server with Python

Source: https://github.com/justifi-tech/public-docs/blob/main/docs/infrastructure/webComponentTokens.mdx

Use this command to start a local HTTP server in the directory containing your HTML file, useful for testing.

```bash
# example using Python
python3 -m http.server

```

--------------------------------

### Example Paginated Request

Source: https://github.com/justifi-tech/public-docs/blob/main/docs/apiFundamentals/pagination.mdx

Use the `after_cursor` parameter to fetch the next page of data. Ensure your `limit` is between 1 and 100.

```sh
curl -X GET https://api.justifi.ai/v1/payments?limit=25&after_cursor=token-from-page-info \
    -H 'Authorization: Bearer [access_token]' \
    -H 'Accept: application/json'
```

--------------------------------

### Card Tokenization Sample

Source: https://github.com/justifi-tech/public-docs/blob/main/docs/payments/tokenization.mdx

This example demonstrates how to tokenize a credit card using the JustiFi API.

```APIDOC
## POST /v1/payment_methods

### Description
This endpoint is used to tokenize a payment method, such as a credit card.

### Method
POST

### Endpoint
https://api.justifi.ai/v1/payment_methods

### Headers
- **Authorization** (string) - Required - Bearer Token
- **Content-Type** (string) - Required - application/json
- **Idempotency-Key** (string) - Required - Unique key for idempotency
- **Sub-Account** (string) - Required - The sub-account ID

### Request Body
- **payment_method** (object) - Required
  - **card** (object) - Required
    - **name** (string) - Required - The name on the card
    - **number** (integer) - Required - The credit card number
    - **verification** (integer) - Required - The CVV code
    - **month** (integer) - Required - The expiration month
    - **year** (integer) - Required - The expiration year
    - **address_postal_code** (integer) - Optional - The billing postal code
    - **metadata** (object) - Optional - Additional metadata

### Request Example
```bash
curl -i -X POST \
  https://api.justifi.ai/v1/payment_methods \
  -H 'Authorization: <Bearer Token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -H 'Sub-Account: <sub-account id>' \
  -d 
{
  "payment_method": {
    "card": {
      "name": "Lindsay Whalen",
      "number": 4242424242421111,
      "verification": 123,
      "month": 5,
      "year": 2042,
      "address_postal_code": 55555,
      "metadata": {
        "new": "info"
      }
    }
  }
}
```

### Response
#### Success Response (200)
- **token** (string) - Description of the token generated for the payment method.
```

--------------------------------

### Paginated Request Example

Source: https://github.com/justifi-tech/public-docs/blob/main/docs/apiFundamentals/pagination.mdx

This example demonstrates how to make a paginated request to the JustiFi API, specifying a limit and an after_cursor for fetching the next page of data.

```APIDOC
## GET /v1/payments

### Description
Fetches a list of payments with support for pagination.

### Method
GET

### Endpoint
/v1/payments

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Controls the number of resources retrieved per request. It can range from 1 to 100, with a default value of 25.
- **after_cursor** (string) - Optional - Fetches the next page of data.
- **before_cursor** (string) - Optional - Retrieves the previous page of data.

### Request Example
```sh
curl -X GET https://api.justifi.ai/v1/payments?limit=25&after_cursor=token-from-page-info \
    -H 'Authorization: Bearer [access_token]' \
    -H 'Accept: application/json'
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the object returned, null for array responses.
- **type** (string) - Indicates the type of object returned, typically an "array" for bulk fetches.
- **data** (array) - Contains the requested resource(s) or an empty array if no resources are available.
- **page_info** (object) - Provides pagination details, including cursor positions.
  - **has_previous** (boolean) - Indicates if there is a previous page of data.
  - **has_next** (boolean) - Indicates if there is a next page of data.
  - **start_cursor** (string) - The cursor for the first item on the current page.
  - **end_cursor** (string) - The cursor for the last item on the current page.

#### Response Example
```json
{
    "id": null,
    "type": "array",
    "data":[
        {
          "id":"py_438xBom2Drh55kE1WfyGLg",
          "amount": 1000,
          "... additional response attributes based on resource schema"
        }
    ],
    "page_info": {
      "has_previous": false,
      "has_next": true,
      "start_cursor": "WyIyMDIyLTAxLTExIDE1OjI3OjM2LjAyNzc3MDAwMCIsImNhNjQwMTk1LTEzYzMtNGJlZi1hZWQyLTU3ZjA1MzhjNjNiYSJd",
      "end_cursor": "WyIyMDIyLTAxLTExIDEyOjU5OjQwLjAwNTkxODAwMCIsImQ0Njg5MGE2LTJhZDItNGZjNy1iNzdkLWFiNmE3MDJhNTg3YSJd"
    }
}
```
```

--------------------------------

### Bank Tokenization Sample

Source: https://github.com/justifi-tech/public-docs/blob/main/docs/payments/tokenization.mdx

This example demonstrates how to tokenize a bank account using the JustiFi API.

```APIDOC
## POST /v1/payment_methods

### Description
This endpoint is used to tokenize a payment method, such as a bank account.

### Method
POST

### Endpoint
https://api.justifi.ai/v1/payment_methods

### Headers
- **Authorization** (string) - Required - Bearer Token
- **Content-Type** (string) - Required - application/json
- **Idempotency-Key** (string) - Required - Unique key for idempotency
- **Sub-Account** (string) - Required - The sub-account ID

### Request Body
- **payment_method** (object) - Required
  - **bank_account** (object) - Required
    - **account_owner_name** (string) - Required - The name of the account owner
    - **routing_number** (string) - Required - The bank routing number
    - **account_number** (string) - Required - The bank account number
    - **account_type** (string) - Required - The type of account (e.g., checking, savings)
    - **account_owner_type** (string) - Required - The type of account owner (e.g., individual, business)
    - **country** (string) - Required - The country code of the bank account
    - **currency** (string) - Required - The currency of the bank account (e.g., usd, cad)
    - **metadata** (object) - Optional - Additional metadata

### Request Example
```bash
curl -i -X POST \
  https://api.justifi.ai/v1/payment_methods \
  -H 'Authorization: <Bearer Token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -H 'Sub-Account: <sub-account id>' \
  -d 
{
   "payment_method": {
    "bank_account": {
      "account_owner_name": "Lindsay Whalen",
      "routing_number": "110000000",
      "account_number": "000123456789",
      "account_type": "checking",
      "account_owner_type": "individual",
      "country": "US",
      "currency": "usd",
      "metadata": {
        "new": "info"
      }
    }
  }
}
```

:::note Currency
When tokenizing bank accounts, the `currency` field must match the currency of the sub-account (e.g., `usd` or `cad`). Sub-accounts are scoped to a single currency. To process payments in CAD, you need a dedicated Canada platform account.
:::

### Response
#### Success Response (200)
- **token** (string) - Description of the token generated for the payment method.
```

--------------------------------

### Get Checkout API Example

Source: https://github.com/justifi-tech/public-docs/blob/main/docs/checkouts/lifecycle.mdx

Use the Get Checkout API to retrieve the current state and attributes of a checkout. This includes details like payment amount, currency, status, and associated payment IDs.

```json
{
  "id": "cho_xyz",
  "type": "checkout",
  "data": {
    "id": "cho_xyz",
    "account_id": "acc_xyz",
    "platform_account_id": "acc_xyz",
    "payment_amount": 10000,
    "payment_currency": "usd",
    "payment_description": "my_order_xyz",
    "payment_methods": [],
    "payment_method_group_id": "pmg_xyz",
    "status": "created",
    "mode": "test",
    "successful_payment_id": "py_xyz",
    "statement_descriptor": "Big Business",
    "payment_fees": [
      { "type": "processing_fee", "amount": 295 },
      { "type": "platform_fee", "amount": 150 }
    ],
    "payment_settings": {},
    "created_at": "2024-01-01T12:00:00Z",
    "updated_at": "2024-01-01T12:00:00Z"
  },
  "page_info": "string"
}
```

--------------------------------

### Paginated Request Example

Source: https://github.com/justifi-tech/public-docs/blob/main/openapi/docs/description.md

Example of a GET request to retrieve a paginated list of payments.

```APIDOC
## GET /v1/payments

### Description
Retrieves a paginated list of payments.

### Method
GET

### Endpoint
/v1/payments

### Query Parameters
- **limit** (integer) - Optional - The number of resources to retrieve. Default is 25, maximum is 100.
- **after_cursor** (string) - Optional - Token to fetch the next page of a list.
- **before_cursor** (string) - Optional - Token to fetch the previous page of a list.

### Request Example
```sh
curl -X GET https://api.justifi.ai/v1/payments?limit=25&after_cursor=token-from-page-info \
    -H 'Authorization: Bearer [access_token]' \
    -H 'Accept: application/json'
```

### Response
#### Success Response (200)
- **id** (string) - The id of the object returned. Will be null for arrays.
- **type** (string) - The type of object returned. Default is "array".
- **data** (array | object) - The resource OR an array of the requested resources. May be an empty array `[]` if no resources are available.
- **page_info** (object) - The object containing pagination information. Contains `has_previous`, `has_next`, `start_cursor` and `end_cursor`.

#### Response Example
```json
{
    "id": null,
    "type": "array",
    "data":[
        { "id":"py_438xBom2Drh55kE1WfyGLg",
          "amount": 1000,
          ... additional response attributes based on resource schema
        }
    ],
    "page_info": {
      "has_previous": false,
      "has_next": true,
      "start_cursor": "WyIyMDIyLTAxLTExIDE1OjI3OjM2LjAyNzc3MDAwMCIsImNhNjQwMTk1LTEzYzMtNGJlZi1hZWQyLTU3ZjA1MzhjNjNiYSJd",
      "end_cursor": "WyIyMDIyLTAxLTExIDEyOjU5OjQwLjAwNTkxODAwMCIsImQ0Njg5MGE2LTJhZDItNGZjNy1iNzdkLWFiNmE3MDJhNTg3YSJd"
    }
}
```
```

--------------------------------

### Create Payment with Auto-Calculated Fees

Source: https://github.com/justifi-tech/public-docs/blob/main/docs/configurableFees/examples.mdx

This example shows how to create a payment without specifying fees. The system automatically detects the card brand and applies the appropriate fee configuration.

```APIDOC
## POST /v1/payments

### Description
Creates a payment with auto-calculated fees based on the payment method.

### Method
POST

### Endpoint
/v1/payments

### Request Body
- **amount** (integer) - Required - The payment amount in the smallest currency unit.
- **currency** (string) - Required - The currency of the payment (e.g., "usd").
- **payment_method** (object) - Required - Details of the payment method.
  - **token** (string) - Required - The token representing the payment method.

### Request Example
```json
{
  "amount": 10000,
  "currency": "usd",
  "payment_method": {
    "token": "pm_xxx"
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the payment.
- **amount** (integer) - The payment amount.
- **fee_amount** (integer) - The total calculated fee amount.
- **fees** (array) - An array of fee objects.
  - **id** (string) - The unique identifier for the fee.
  - **type** (string) - The type of fee (e.g., "processing_fee", "platform_fee").
  - **amount** (integer) - The amount of the fee.
  - **remaining_amount** (integer) - The remaining amount for the fee.
  - **currency** (string) - The currency of the fee.
  - **source_configuration_id** (string) - The ID of the source fee configuration.
  - **source_fee_type** (string) - The type of the source fee.

#### Response Example
```json
{
  "id": "py_xxx",
  "amount": 10000,
  "fee_amount": 450,
  "fees": [
    {
      "id": "pyfee_1",
      "type": "processing_fee",
      "amount": 350,
      "remaining_amount": 350,
      "currency": "usd",
      "source_configuration_id": "sfc_abc123",
      "source_fee_type": "amex_brand_ecomm"
    },
    {
      "id": "pyfee_2",
      "type": "platform_fee",
      "amount": 100,
      "remaining_amount": 100,
      "currency": "usd",
      "source_configuration_id": "sfc_def456",
      "source_fee_type": "platform"
    }
  ]
}
```
```

--------------------------------

### Payment Provisioning Web Component for Merchant Onboarding

Source: https://context7.com/justifi-tech/public-docs/llms.txt

Embed the full merchant onboarding form using the justifi-payment-provisioning component. Listen for 'submit-event' to get the sub_account_id and 'error-event' for component errors.

```html
<!doctype html>
<html>
  <head>
    <script type="module"
      src="https://cdn.jsdelivr.net/npm/@justifi/webcomponents@4.11.0/dist/webcomponents/webcomponents.esm.js">
    </script>
  </head>
  <body>
    <!-- business-id from POST /v1/entities/business -->
    <!-- auth-token scoped: write:business:{businessId} -->
    <justifi-payment-provisioning
      auth-token="WEB_COMPONENT_TOKEN"
      business-id="biz_a1b2c3d4">
    </justifi-payment-provisioning>

    <script>
      const provisionEl = document.querySelector('justifi-payment-provisioning');

      provisionEl.addEventListener('submit-event', (event) => {
        if (event.details.data) {
          const subAccountId = event.details.data.sub_account_id;
          console.log('Sub account created:', subAccountId);
          // Monitor sub_account.updated webhooks for underwriting status → "enabled"
        } else {
          console.error('Provisioning failed');
        }
      });

      provisionEl.addEventListener('error-event', (event) => {
        console.error('Component error:', event);
      });
    </script>
  </body>
</html>
```

--------------------------------

### Example Paginated Response

Source: https://github.com/justifi-tech/public-docs/blob/main/docs/apiFundamentals/pagination.mdx

The response includes a `page_info` object with `has_next`, `has_previous`, `start_cursor`, and `end_cursor` for navigation.

```json
{
    "id": null,
    "type": "array",
    "data":[
        { "id":"py_438xBom2Drh55kE1WfyGLg",
          "amount": 1000,
          ... additional response attributes based on resource schema
        }
    ],
    "page_info": {
      "has_previous": false,
      "has_next": true,
      "start_cursor": "WyIyMDIyLTAxLTExIDE1OjI3OjM2LjAyNzc3MDAwMCIsImNhNjQwMTk1LTEzYzMtNGJlZi1hZWQyLTU3ZjA1MzhjNjNiYSJd",
      "end_cursor": "WyIyMDIyLTAxLTExIDEyOjU5OjQwLjAwNTkxODAwMCIsImQ0Njg5MGE2LTJhZDItNGZjNy1iNzdkLWFiNmE3MDJhNTg3YSJd"
    }
}
```

--------------------------------

### Retrieve a sub account

Source: https://github.com/justifi-tech/public-docs/blob/main/openapi/docs/api_onboarding.md

Check the onboarding status of a sub account after provisioning. This can be done by calling the Get a Sub Account endpoint or subscribing to `sub_account.updated` events.

```APIDOC
## Retrieve a sub account

### Description
Retrieves the details and onboarding status of a sub account.

### Method
GET

### Endpoint
https://api.justifi.ai/v1/sub_accounts/{ACCOUNT_ID}

### Parameters
#### Path Parameters
- **ACCOUNT_ID** (string) - Required - The ID of the sub account to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The sub account ID.
- **business_id** (string) - The ID of the associated business.
- **status** (string) - The current onboarding status of the sub account (e.g., 'approved', 'pending', 'rejected').

#### Response Example
{
  "id": "subacc_def456",
  "business_id": "biz_abc123",
  "status": "approved"
}
```

--------------------------------

### Create Payment with Fees

Source: https://github.com/justifi-tech/public-docs/blob/main/openapi/docs/description.md

When creating a payment, include a `fees` array to specify processing and platform fees. Note that the `fees` array will be empty in the initial Create Payment response; fees are processed asynchronously and available via webhooks or Get Payment requests.

```json
POST /v1/payments
{
  "amount": 10000,
  "currency": "usd",
  "capture_strategy": "automatic",
  "fees": [
    { "type": "processing_fee", "amount": 350 },
    { "type": "platform_fee", "amount": 500 }
  ],
  "payment_method": { "token": "pm_xyz" }
}
```

```json
{
  "id": "py_123xyz",
  "type": "payment",
  "data": {
    "id": "py_123xyz",
    "amount": 10000,
    "fee_amount": 850,
    "fees": []
  }
}
```

```json
{
  "fees": [
    { "id": "pyfee_abc", "type": "processing_fee", "amount": 350, "remaining_amount": 350, "currency": "usd" },
    { "id": "pyfee_xyz", "type": "platform_fee", "amount": 500, "remaining_amount": 500, "currency": "usd" }
  ]
}
```

--------------------------------

### Google Pay Tokenization Specification Example

Source: https://github.com/justifi-tech/public-docs/blob/main/docs/payments/googlePay.mdx

This JSON object illustrates the `TokenizationSpecification` parameters automatically configured by JustiFi's checkout components when initializing the Google Pay button. It includes the gateway type and merchant ID, handled internally by JustiFi.

```json
{
  "tokenizationSpecification": {
    "type": "PAYMENT_GATEWAY",
    "parameters": {
      "gateway": "justifi",
      "gatewayMerchantId": "acc_m9IjrorZoehPX9BA7kIrn"
    }
  }
}
```

--------------------------------

### Development and Build Commands

Source: https://github.com/justifi-tech/public-docs/blob/main/CLAUDE.md

Standard commands for running the development server, building for production, serving the built site, and performing TypeScript type checking.

```bash
pnpm run start      # Dev server on port 3000
```

```bash
pnpm run build      # Production build (runs prebuild for .wc-current/)
```

```bash
pnpm run serve      # Serve built site
```

```bash
pnpm run typecheck  # TypeScript type checking
```

--------------------------------

### Replace Existing Fee Configuration

Source: https://github.com/justifi-tech/public-docs/blob/main/docs/configurableFees/managingConfigurations.mdx

To update an existing fee configuration, create a new configuration for the same fee type. The previous configuration will be automatically retired and its effective end date set to the new configuration's start date. This example shows updating the 'processing_ecomm' fee.

```http
POST /v1/sub_accounts/acc_xxx/fee_configurations/processing_ecomm
```

```json
{
  "variable_rate": 2.50,
  "transaction_fee_cents": 30
}
```

--------------------------------

### HTML for Payment Provisioning

Source: https://github.com/justifi-tech/public-docs/blob/main/docs/infrastructure/webComponentTokens.mdx

This HTML file sets up the Justifi payment provisioning web component. Replace placeholders with your actual WEB_COMPONENT_TOKEN and BUSINESS_ID.

```html
<!doctype html>
<html dir="ltr" lang="en">
  <head>
    <meta charset="utf-8" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=5.0"
    />
    <title>justifi-payment-details</title>
    <script
      type="module"
      src="https://cdn.jsdelivr.net/npm/@justifi/webcomponents@4.11.0/dist/webcomponents/webcomponents.esm.js"
    ></script>
    <script
      nomodule
      src="https://cdn.jsdelivr.net/npm/@justifi/webcomponents@4.11.0/dist/webcomponents/webcomponents.js"
    ></script>
  </head>
  <body>
    <justifi-payment-provisioning
      business-id="${BUSINESS_ID}"
      auth-token="${WEB_COMPONENT_TOKEN}"
    >
    </justifi-payment-provisioning>
  </body>
</html>

```

--------------------------------

### Get Sub Account — GET /v1/sub_accounts/{id}

Source: https://context7.com/justifi-tech/public-docs/llms.txt

Retrieves the current status of a sub account (merchant). This is useful for polling underwriting status or confirming onboarding completion.

```APIDOC
## Get Sub Account — GET /v1/sub_accounts/{id}

Retrieves the current status of a sub account (merchant). Use this to poll underwriting status after onboarding, or subscribe to `sub_account.updated` webhooks.

```bash
curl -X GET https://api.justifi.ai/v1/sub_accounts/acc_5Et9iXrSSAZR2KSouQGAWi \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

# Response includes status field:
# {
#   "data": {
#     "id": "acc_5Et9iXrSSAZR2KSouQGAWi",
#     "status": "enabled",   // "enabled" = approved and can process payments
#     ...
#   }
# }
```
```

--------------------------------

### Build Static Website Content

Source: https://github.com/justifi-tech/public-docs/blob/main/README.md

This command generates static website files into the 'build' directory, ready for hosting.

```bash
$ pnpm run build
```

--------------------------------

### Get Sub Account Status

Source: https://context7.com/justifi-tech/public-docs/llms.txt

Retrieve the current status of a sub account using its ID via a GET request to the /v1/sub_accounts/{id} endpoint. The response includes a 'status' field indicating if the account is 'enabled'.

```bash
curl -X GET https://api.justifi.ai/v1/sub_accounts/acc_5Et9iXrSSAZR2KSouQGAWi \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

# Response includes status field:
# {
#   "data": {
#     "id": "acc_5Et9iXrSSAZR2KSouQGAWi",
#     "status": "enabled",   // "enabled" = approved and can process payments
#     ...
#   }
# }
```

--------------------------------

### Authenticated Response Example

Source: https://github.com/justifi-tech/public-docs/blob/main/openapi/docs/description.md

A successful response to the OAuth token request will contain an access token.

```json
{
  "access_token": "... this will be a very long string and is valid for 24 hours"
}
```

--------------------------------

### Initialize PaymentsJS with Client Key

Source: https://github.com/justifi-tech/public-docs/blob/main/openapi/docs/payments_js.md

Initialize PaymentsJS by calling `window.JustiFiPaymentsJS` with your client key. Ensure you use your client ID and never share your client secret publicly.

```javascript
const justifiJS = window.JustiFiPaymentsJS({ clientKey: "test_xxx" });
```

--------------------------------

### Deploy Website using SSH

Source: https://github.com/justifi-tech/public-docs/blob/main/README.md

Command to deploy the website using SSH. Ensure the USE_SSH environment variable is set.

```bash
$ USE_SSH=true pnpm run deploy
```

--------------------------------

### Get configuration history for a fee type

Source: https://github.com/justifi-tech/public-docs/blob/main/docs/configurableFees/managingConfigurations.mdx

Retrieves the historical fee configurations for a specific fee type for a given sub account.

```APIDOC
## GET /v1/sub_accounts/:id/fee_configurations/:fee_type/history

### Description
Retrieves the historical fee configurations for a specific fee type for a given sub account.

### Method
GET

### Endpoint
/v1/sub_accounts/:id/fee_configurations/:fee_type/history
```

--------------------------------

### List All Active Fee Configurations

Source: https://github.com/justifi-tech/public-docs/blob/main/docs/configurableFees/managingConfigurations.mdx

Retrieve a paginated list of all active fee configurations for a sub-account. Use query parameters like `limit`, `after_cursor`, and `before_cursor` for pagination.

```bash
GET /v1/sub_accounts/acc_xxx/fee_configurations
```

```json
{
  "type": "array",
  "page_info": {
    "has_previous": false,
    "has_next": false,
    "start_cursor": "...",
    "end_cursor": "..."
  },
  "data": [
    {
      "id": "sfc_abc123",
      "account_id": "acc_xxx",
      "platform_account_id": "acc_yyy",
      "fee_type": "processing_ecomm",
      "variable_rate": 2.75,
      "transaction_fee_cents": 25,
      "transaction_fee_currency": "usd",
      "fee_cap_cents": null,
      "effective_start": "2026-02-01T00:00:00Z",
      "effective_end": null
    },
    {
      "id": "sfc_def456",
      "account_id": "acc_xxx",
      "platform_account_id": "acc_yyy",
      "fee_type": "amex_brand_ecomm",
      "variable_rate": 3.25,
      "transaction_fee_cents": 25,
      "transaction_fee_currency": "usd",
      "fee_cap_cents": null,
      "effective_start": "2026-02-01T00:00:00Z",
      "effective_end": null
    }
  ]
}
```

--------------------------------

### Payment Provisioning Web Component — Merchant Onboarding

Source: https://context7.com/justifi-tech/public-docs/llms.txt

Embeds the merchant onboarding form using the `justifi-payment-provisioning` web component. It provisions a sub-account for payment processing upon submission.

```APIDOC
## Payment Provisioning Web Component — Merchant Onboarding

Embeds the full merchant onboarding form. On submission, provisions a sub account for payment processing. Subscribe to `sub_account.updated` events to track underwriting status.

```html
<!doctype html>
<html>
  <head>
    <script type="module"
      src="https://cdn.jsdelivr.net/npm/@justifi/webcomponents@4.11.0/dist/webcomponents/webcomponents.esm.js">
    </script>
  </head>
  <body>
    <!-- business-id from POST /v1/entities/business -->
    <!-- auth-token scoped: write:business:{businessId} -->
    <justifi-payment-provisioning
      auth-token="WEB_COMPONENT_TOKEN"
      business-id="biz_a1b2c3d4">
    </justifi-payment-provisioning>

    <script>
      const provisionEl = document.querySelector('justifi-payment-provisioning');

      provisionEl.addEventListener('submit-event', (event) => {
        if (event.details.data) {
          const subAccountId = event.details.data.sub_account_id;
          console.log('Sub account created:', subAccountId);
          // Monitor sub_account.updated webhooks for underwriting status → "enabled"
        } else {
          console.error('Provisioning failed');
        }
      });

      provisionEl.addEventListener('error-event', (event) => {
        console.error('Component error:', event);
      });
    </script>
  </body>
</html>
```
```

--------------------------------

### Get active configuration for a specific fee type

Source: https://github.com/justifi-tech/public-docs/blob/main/docs/configurableFees/managingConfigurations.mdx

Retrieves the active fee configuration for a specific fee type for a given sub account.

```APIDOC
## GET /v1/sub_accounts/:id/fee_configurations/:fee_type

### Description
Retrieves the active fee configuration for a specific fee type for a given sub account.

### Method
GET

### Endpoint
/v1/sub_accounts/:id/fee_configurations/:fee_type
```

--------------------------------

### Authenticated API Request Example

Source: https://github.com/justifi-tech/public-docs/blob/main/openapi/docs/description.md

Include the obtained access token in the Authorization header for subsequent API requests. Ensure the Content-Type is set to application/json.

```sh
curl -X POST https://api.justifi.ai/v1/payments \
    -H 'Authorization: Bearer [access_token]' \
    -H 'Content-Type: application/json'
    -H 'Idempotency-Key: a-unique-string-for-the-transaction'
```

--------------------------------

### Tree View of Paths Folder (Placeholder)

Source: https://github.com/justifi-tech/public-docs/blob/main/openapi/multi-yaml/paths/README.md

This is a placeholder for a tree view illustrating the 'file-per-path' organization. Actual implementation would show the directory structure.

```bash
# todo: insert tree view of paths folder
```

--------------------------------

### Handle Web Component Events

Source: https://github.com/justifi-tech/public-docs/blob/main/openapi/docs/tokenize.md

Listen for 'submit-event' to get the tokenized payment method details upon successful submission, or 'error-event' to handle any issues during the process.

```javascript
<script>
  const justifiTokenizePaymentMethod = document.querySelector('justifi-tokenize-payment-method');
  justifiTokenizePaymentMethod.addEventListener('submit-event', (event) => {
    console.log('Submitted data:', event.detail);
  });
  justifiTokenizePaymentMethod.addEventListener('error-event', (event) => {
    console.error('error-event:', event.detail);
  });
</script>
```

--------------------------------

### Listen for Onboarding Completion Events

Source: https://github.com/justifi-tech/public-docs/blob/main/openapi/docs/hosted_onboarding.md

Add an event listener to handle success or failure messages posted from the JustiFi hosted onboarding iframe. This allows your application to react to the onboarding outcome.

```javascript
const handleOnboardingCompletion = (e) => {
  const { eventType } = e.data;
  if (eventType === 'submitSuccess') {
    // Handle successful onboarding
  }
  if (eventType === 'submitFailure') {
    // Handle failed onboarding
  }
};

window.addEventListener('message', handleOnboardingCompletion);
```

--------------------------------

### Initialize PaymentsJS

Source: https://github.com/justifi-tech/public-docs/blob/main/openapi/docs/payments_js.md

Initialize the PaymentsJS library with your client key. For platforms, include the account ID for sub-account processing.

```APIDOC
## Initialize PaymentsJS

Initialize the PaymentsJS library by calling `window.JustiFiPaymentsJS` with your client key. If you are a Platform processing on behalf of a Sub Account, also provide the `account` option.

### Parameters

- **clientKey** (string) - Required - Your JustiFi client key.
- **account** (string) - Optional - The account ID of the Sub Account if processing on behalf of one.

### Request Example

```javascript
// For standard initialization
const justifiJS = window.JustiFiPaymentsJS({ clientKey: "test_xxx" });

// For platform initialization with a sub-account
const justifiJS = window.JustiFiPaymentsJS({
  clientKey: "test_xxx",
  account: "acc_testsubacct"
});
```
```

--------------------------------

### on('ready', handler)

Source: https://github.com/justifi-tech/public-docs/blob/main/openapi/docs/payments_js.md

Registers a handler for the 'ready' event, which is triggered when the payment method input is rendered and initial validation errors are available.

```APIDOC
## on('ready', *handler*)

Registers an event handler for the 'ready' event. This event fires when the payment method input has finished rendering and provides initial validation errors.

### Parameters

- **handler** (function) - Required - The callback function to execute when the 'ready' event is triggered. It receives an object containing `errors`.

### Method

`on`

### Endpoint

N/A (Client-side SDK method)

### Request Example

```javascript
justifiJS.on('ready', (data: any) => {
  // Example: Set loading state
  loading = false;

  // Example: Store initial errors
  paymentMethodErrors = data.errors;
});
```
```

--------------------------------

### Get Access Token

Source: https://github.com/justifi-tech/public-docs/blob/main/openapi/docs/checkout_api.md

Generates an access token required for authenticating API requests. Use your client ID and client secret obtained from the JustiFi dashboard.

```javascript
function getToken() {
  return fetch('https://api.justifi.ai/oauth/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      "client_id": "YOUR CLIENT ID",
      "client_secret": "YOUR CLIENT SECRET"
    })
  })
    .then(response => response.json())
    .then(data => data.access_token);
}

const token = await getToken();
```

--------------------------------

### Initialize PaymentsJS for Platform Accounts

Source: https://github.com/justifi-tech/public-docs/blob/main/openapi/docs/payments_js.md

When processing payments on behalf of a Sub Account as a Platform, initialize PaymentsJS with both `clientKey` and the `account` option specifying the Sub Account ID.

```javascript
const justifiJS = window.JustiFiPaymentsJS({
  clientKey: "test_xxx",
  account: "acc_testsubacct"
});
```

--------------------------------

### Create Payment with Auto-Calculated Fees

Source: https://context7.com/justifi-tech/public-docs/llms.txt

Initiate a payment request after fee configurations are in place. The 'amount' field is the total charge, and fees will be automatically calculated and deducted based on the active configurations.

```bash
curl -X POST https://api.justifi.ai/v1/payments \
  -H 'Authorization: Bearer [access_token]' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: new-uuid-here' \
  -H 'Sub-Account: acc_5Et9iXrSSAZR2KSouQGAWi' \
  -d '{
    "amount": 10000,
    "currency": "usd",
    "capture_strategy": "automatic",
    "payment_method": { "token": "pm_abc123" }
  }'
```

--------------------------------

### Get Access Token for JustiFi API

Source: https://github.com/justifi-tech/public-docs/blob/main/openapi/docs/onboarding.md

Obtain an access token from the JustiFi API using your client ID and client secret. This token is required for subsequent API calls.

```javascript
function getToken() {
  return fetch('https://api.justifi.ai/oauth/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      "client_id": "YOUR CLIENT ID",
      "client_secret": "YOUR CLIENT SECRET"
    })
  })
  .then(response => response.json())
  .then(data => data.access_token);
}

const token = await getToken();
```

--------------------------------

### Get Specific Fee Type Configuration

Source: https://github.com/justifi-tech/public-docs/blob/main/docs/configurableFees/managingConfigurations.mdx

Retrieve the active configuration for a specific fee type. Returns a 404 error if no active configuration exists for the given fee type.

```bash
GET /v1/sub_accounts/acc_xxx/fee_configurations/processing_ecomm
```

```json
{
  "id": "sfc_abc123",
  "type": "standard_fee_configuration",
  "data": {
    "id": "sfc_abc123",
    "account_id": "acc_xxx",
    "platform_account_id": "acc_yyy",
    "fee_type": "processing_ecomm",
    "variable_rate": 2.75,
    "transaction_fee_cents": 25,
    "transaction_fee_currency": "usd",
    "fee_cap_cents": null,
    "effective_start": "2026-02-01T00:00:00Z",
    "effective_end": null
  }
}
```

--------------------------------

### Create Business Entity and Web Component Token

Source: https://context7.com/justifi-tech/public-docs/llms.txt

Use cURL to create a business entity via the API, then generate a web component token for onboarding. The business ID is required for token generation.

```bash
# Backend: create a business entity
curl -sS -X POST https://api.justifi.ai/v1/entities/business \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "legal_name": "Acme Construction LLC"
  }'

# Response:
# { "id": "biz_a1b2c3d4", "type": "business", "data": { "legal_name": "Acme Construction LLC", ... } }

# Use business.id to generate a web component token for onboarding:
curl -sS -X POST https://api.justifi.ai/v1/web_component_tokens \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{ "resources": ["write:business:biz_a1b2c3d4"] }'
```

--------------------------------

### Relative Reference Example in Deep Paths

Source: https://github.com/justifi-tech/public-docs/blob/main/openapi/multi-yaml/paths/README.md

Illustrates a deeply nested relative reference within an OpenAPI path definition. This highlights the complexity of managing relative paths in subfolder structures.

```yaml
file: /paths/customers/{id}/timeline/{messageId}/get.yaml

# excerpt of file
    headers:
      Rate-Limit-Remaining:
        $ref: ../../../../../components/headers/Rate-Limit-Remaining.yaml
```

--------------------------------

### Create a business

Source: https://github.com/justifi-tech/public-docs/blob/main/openapi/docs/api_onboarding.md

Use the business API to create a business on JustiFi. This endpoint does not require parameters initially, but they will be needed for provisioning. The ID returned is crucial for subsequent steps.

```APIDOC
## Create a business

### Description
Creates a new business entity on the JustiFi platform.

### Method
POST

### Endpoint
https://api.justifi.ai/v1/entities/business

### Request Body
- **legal_name** (string) - Required - The legal name of the business.

### Request Example
{
  "legal_name": "Business name"
}

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created business.
- **legal_name** (string) - The legal name of the business.

#### Response Example
{
  "id": "biz_abc123",
  "legal_name": "Business name"
}
```

--------------------------------

### Import PGP Key

Source: https://github.com/justifi-tech/public-docs/blob/main/openapi/docs/payment_method_migration.md

Command to import JustiFi's PGP public key into your GPG keyring. This is a necessary step before encrypting files for JustiFi.

```bash
gpg --import public.key
```

--------------------------------

### Creating Checkouts with Fees

Source: https://github.com/justifi-tech/public-docs/blob/main/openapi/docs/description.md

Set up a checkout process and include fees that will be applied to the associated payment. These fees are defined within the payment object of the checkout request.

```APIDOC
## POST /v1/checkouts

### Description
Creates a checkout with a specified amount and description. Fees can be included within the nested `payment.fees` field.

### Method
POST

### Endpoint
/v1/checkouts

### Request Body
- **amount** (integer) - Required - The amount for the checkout.
- **description** (string) - Required - A description for the checkout.
- **payment** (object) - Required - Payment details for the checkout.
  - **fees** (array) - Optional - An array of fee objects to be associated with the payment.
    - **type** (string) - Required - The type of fee (e.g., "processing_fee", "platform_fee").
    - **amount** (integer) - Required - The amount of the fee.

### Request Example
```json
{
  "amount": 10000,
  "description": "Order #12345",
  "payment": {
    "fees": [
      { "type": "processing_fee", "amount": 295 },
      { "type": "platform_fee", "amount": 150 }
    ]
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the checkout.
- **type** (string) - The resource type, always "checkout".
- **data** (object) - Contains checkout details.
  - **id** (string) - The checkout ID.
  - **payment_amount** (integer) - The amount designated for payment.
  - **status** (string) - The current status of the checkout (e.g., "created").
  - **payment** (object) - Nested payment details.
    - **fees** (array) - An array of fee objects associated with the payment.
      - **type** (string) - The type of fee.
      - **amount** (integer) - The amount of the fee.

#### Response Example
```json
{
  "id": "cho_xyz",
  "type": "checkout",
  "data": {
    "id": "cho_xyz",
    "payment_amount": 10000,
    "status": "created",
    "payment": {
      "fees": [
        { "type": "processing_fee", "amount": 295 },
        { "type": "platform_fee", "amount": 150 }
      ]
    }
  }
}
```

**Note**: When the checkout is completed, these fees are passed to the payment and tracked with `remaining_amount`.
```

--------------------------------

### Get a Specific Fee Type Configuration

Source: https://github.com/justifi-tech/public-docs/blob/main/docs/configurableFees/managingConfigurations.mdx

Retrieves the currently active configuration for a specific fee type. Returns a 404 error if no active configuration exists for the specified fee type.

```APIDOC
## GET /v1/sub_accounts/{sub_account_id}/fee_configurations/{fee_type}

### Description
Retrieves the active configuration for a specific fee type. Returns 404 if none exists.

### Method
GET

### Endpoint
/v1/sub_accounts/acc_xxx/fee_configurations/processing_ecomm

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the fee configuration.
- **type** (string) - The type of the response, expected to be 'standard_fee_configuration'.
- **data** (object) - The fee configuration details.
  - **id** (string) - The unique identifier for the fee configuration.
  - **account_id** (string) - The ID of the sub-account this configuration belongs to.
  - **platform_account_id** (string) - The ID of the platform account.
  - **fee_type** (string) - The type of fee.
  - **variable_rate** (number) - The variable rate percentage for the fee.
  - **transaction_fee_cents** (integer) - The fixed transaction fee in cents.
  - **transaction_fee_currency** (string) - The currency of the transaction fee.
  - **fee_cap_cents** (integer or null) - The maximum fee in cents, or null if no cap.
  - **effective_start** (string) - The date and time when the configuration becomes effective.
  - **effective_end** (string or null) - The date and time when the configuration becomes inactive, or null if it's ongoing.

### Response Example
```json
{
  "id": "sfc_abc123",
  "type": "standard_fee_configuration",
  "data": {
    "id": "sfc_abc123",
    "account_id": "acc_xxx",
    "platform_account_id": "acc_yyy",
    "fee_type": "processing_ecomm",
    "variable_rate": 2.75,
    "transaction_fee_cents": 25,
    "transaction_fee_currency": "usd",
    "fee_cap_cents": null,
    "effective_start": "2026-02-01T00:00:00Z",
    "effective_end": null
  }
}
```
```

--------------------------------

### Create Test Payment with cURL

Source: https://github.com/justifi-tech/public-docs/blob/main/docs/testing/card_payments.mdx

Use this cURL command to create a test payment. Pass the desired test scenario in the `metadata.payment_test.scenario` field. Ensure the currency matches your sub-account configuration.

```curl
curl -X POST https://api.justifi.tech/v1/payments \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "usd",
    "payment_method": {
      "card": {
        "number": "4242424242424242",
        "exp_month": 12,
        "exp_year": 2025,
        "cvc": "123"
      }
    },
    "metadata": {
      "payment_test": {
        "scenario": "insufficient_funds"
      }
    }
  }'
```