JustiFi API Documentation (v1)

The JustiFi API is a REST-based payment processing API. Our API has predictable, resource-oriented URLs, accepts JSON, and returns JSON. We use HTTP status codes and supply detailed error codes whenever possible. We'll provide you with both a test and live account with which to use our API. Each account will have its own API key, and the key you use to authenticate each request will determine whether to use your test or live account. When you use your test account, it won't affect your live data or move any real money.

To process a payment with JustiFi, follow these steps

• Get Your Accounts
• Get Your API Keys
• Authenticate With JustiFi
• For Platforms, Create and Onboard Your Sub Accounts
• Create a Payment

Get Your Accounts

Our customer onboarding team will work with you to create your test and live accounts. For platforms, our team will also guide you through setting up your sub accounts onboarding. Once you're up and running, you'll have access to the JustiFi API as well as the admin features at https://app.justifi.ai where you can see your account overview, payments, payouts, issue refunds, etc.

Get Your API Keys

Once your test and live accounts have been created, you'll have access to generate your API keys in the Developer Tools section of the app. You'll need a test key and a live key. Each key will provide you with a client id and a client secret, which you'll use to authenticate your API requests. Requests authenticated with your test key will use your test account; requests authenticated with your live key will use your live account. Make sure to store your client secrets somewhere secure (like a password manager) because this is the only time they'll display in the UI.

Additionally, we can provide access to a sandbox environment upon request.

Authenticate With JustiFi

curl -X POST https://api.justifi.ai/oauth/token \
    -H 'Content-Type: application/json' \
    --data '{"client_id":"[your client id]","client_secret":"[your client secret]"}'

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

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'

JustiFi uses the OAuth Client Credentials authentication flow. To access, use your JustiFi client id and client secret to POST to https://api.justifi.ai/oauth/token. These are valid for 24 hours. The test key is prepended with test_ and the live key is prepended with live_.

Next, take the access token in that response and pass it in all subsequent requests as the Authorization header.

This token is valid for 24 hours, so be sure to handle a 401 - Unauthorized response by getting a new access token via the client credentials grant API.

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

In order to guarantee that payments and other important transactions are only ever processed a single time, we leverage the Idempotency-Key header in our payments APIs. This means that you MUST provide an Idempotency-Key header along with your request, otherwise you'll receive an error. If a second request with same idempotent key is processed concurrently, it will result in a 409 error instead of double processing.

If these requests fail with a network timeout or a 5XX error, they should be retried with the same exact parameters. Once they're fully successful, you'll receive a 2XX response. If you POST the same request and Idempotency-Key again, you'll get the response you originally received back. If you receive a 4XX error, do not retry the request, unless the response code is a 409.

If you try the same Idempotency-Key with different parameters, your request will error and won't be possible to process. The Idempotency-Key header is only meant for a single transaction; it's there to protect against processing the same exact thing more than once. Once the parameters change, a request is considered distinct from the original request.

You may use any string to identify your Idempotency-Key; we generally recommend using a generated uuid, but you may use any unique string.

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'

{
    "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"
    }
}

Standard array API Request Parameters

The after_cursor/before_cursor parameter determines which page of results will be returned. If after_cursor is the encoded id of the last record in the collection has_next will be false and you'll get an empty array response. If before_cursor is the encoded id of the first record in the collection has_previous will be false and you'll get an empty array response.

The limit parameter determines the maximum number of results included in each response. If there are fewer records available than the limit value, the response will include all available records. The maximum value allowed is 100 with a default value of 25. If the limit value is an invalid type, the default value of 25 is used.

Standard API Response Structure

All of our responses are contained in the same envelope, for arrays the id field will be null and the object will be an array.

Use these card numbers to test successful transactions as well as various error scenarios. Make sure to authenticate your requests using your test API key (these cards won't work for live payments).

Successful Test Cards

Declined Test Cards

Successful Bank Account (ACH)

Declined Bank Accounts (ACH)

The JustiFi API may return a number of standard HTTP errors due to invalid requests. Some common errors are described below to help you build with JustiFi.

Bad Request

The server cannot process the request. This error is most likely due to malformed request syntax.

• code: 400
• status: Bad Request

Unauthorized

Similar to a 403 Forbidden, but specifically when authentication is provided and has failed, or has not been provided. This error is most likely due to not including your API key in the request header.

• code: 401
• status: Unauthorized

Payment Required

There was an error processing the payment. This response is returned when errors occur while tokenizing the payment method, such as an invalid cvc or an expiration date in the past. This can also occur when making a payment and the card is declined. In that case, the error message will provide more specific information about why the request was declined.

• code: 402
• status: Payment Required

Forbidden

The request was valid, but you are unable to execute the request. This error is most likely due to the API key that was used not having the necessary permissions, or attempting a prohibited action such as creating a duplicate record where one already exists.

• code: 403
• status: Forbidden

Not Found

The requested resource could not be found, but may be available in the future. This error is most likely due to requesting a resource by id that doesn't exist. You'll want to double check that you're referencing the correct id and that it exists on your account.

• code: 404
• status: Not Found

Concurrent Request Error

The request has an identical Idempotency-Key header for another request which either failed OR is processing at the same time. You can retry these requests without risk of double processing.

• code: 409
• status: Conflict

Unprocessable Entity

The request was well-formed, but was unable to be processed due to semantic errors. This error is most likely due to including invalid data in POST, PATCH, and PUT requests. Double check the request documentation to make sure you're supplying the required attributes, and that the attribute types are correct.

• code: 422
• status: Unprocessable Entity

Internal Server Error

An internal server error occurred due to an unexpected condition. This error is most likely due to an issue with our servers.

• code: 500
• status: Internal Server Error

Error Codes

Many of our 4XX errors will provide an error code in addition to their HTTP status. Here is a list of our error codes and a brief description of the error to provide more context when applicable.

We provide the network error code, and the network error category to help inform you how to handle a decline. These are only returned when a transaction fails while trying to process on the card network. Please take a look at each section. The network error category is especially relevant for recurring payments. It can reduce retries on transactions which will never succeed.

Network Error Codes

In addition to the standard error codes provided by JustiFi, some errors may include a network_error_code that provides more specific information about the error from the payment network. Here's a list of common network_error_code values and their meanings:

Network Error Category

Both Visa and Mastercard send additional information about how to handle a declined payment for recurring payments. Effective May 30th, 2025 we pass through this information to help handle failures. We have added the network and network_error_category attributes to declined payments, when we get the additional information from the card networks. We are working on further classification of errors, for now please only respond to those documented here.

JustiFi's enhanced fee management gives platforms granular control over how fees are charged and—importantly—how they are returned when processing refunds.

New Integrations: If you're building a new integration, use the fees array described below. This is the recommended approach for all new implementations.

Existing Integrations: The application_fee_amount field continues to work unchanged. You can migrate to the new structure at your own pace—we'll provide migration support in a future release.

Overview

The enhanced fee structure separates your fees into distinct types, each tracked independently:

This separation enables:

• Selective refunds: Return the processing fee while keeping your platform fee, or vice versa
• Clear reporting: Each fee type appears as a separate line item in balance transactions
• Remaining amount tracking: Track how much of each fee can still be refunded

Supported Endpoints

Creating Payments with Fees

Request:

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" }
}

Response (Create):

{
  "id": "py_123xyz",
  "type": "payment",
  "data": {
    "id": "py_123xyz",
    "amount": 10000,
    "fee_amount": 850,
    "fees": [
      { "type": "processing_fee", "amount": 350 },
      { "type": "platform_fee", "amount": 500 }
    ]
  }
}

Response (Get Payment):

When fetching a payment, you'll see additional tracking fields:

{
  "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" }
  ]
}

Refunding Payments with Selective Fee Return

You control exactly which fees are returned to the merchant. This enables flexible refund policies.

Request:

POST /v1/payments/{id}/refunds
{
  "amount": 5000,
  "reason": "customer_request",
  "fees": [
    { "type": "processing_fee", "amount": 175 }
  ]
}

In this example:

• $50.00 is refunded to the customer
• $1.75 processing fee is returned to the merchant
• The platform fee is retained

Response:

{
  "id": "re_xyz",
  "type": "refund",
  "data": {
    "id": "re_xyz",
    "amount": 5000,
    "status": "succeeded",
    "returned_fees": [
      {
        "id": "rtfee_xyz",
        "payment_fee_id": "pyfee_abc",
        "type": "processing_fee",
        "returned_amount": 175,
        "original_amount": 350,
        "remaining_amount": 175,
        "currency": "usd"
      }
    ]
  }
}

After this refund, fetching the payment shows the updated remaining_amount:

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

Note: If no fees array is provided in the refund request, no fees are returned to the merchant.

Creating Checkouts with Fees

For checkouts, use the payment.fees field:

Request:

POST /v1/checkouts
{
  "amount": 10000,
  "description": "Order #12345",
  "payment": {
    "fees": [
      { "type": "processing_fee", "amount": 295 },
      { "type": "platform_fee", "amount": 150 }
    ]
  }
}

Response:

{
  "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 }
      ]
    }
  }
}

When the checkout is completed, the fees are passed to the payment and tracked with remaining_amount.

Refunding Checkouts with Fee Return

Request:

POST /v1/checkouts/{id}/refunds
{
  "amount": 5000,
  "fees": [
    { "type": "processing_fee", "amount": 147 }
  ]
}

Response:

{
  "id": "chr_xyz",
  "type": "checkout_refund",
  "data": {
    "id": "chr_xyz",
    "checkout_id": "cho_xyz",
    "status": "succeeded",
    "refund_amount": 5000,
    "returned_fees": [
      { "type": "processing_fee", "amount": 147 }
    ]
  }
}

Validation Rules

Fee Lifecycle

When using the enhanced fee structure (fees array), fees are handled as follows throughout the payment lifecycle:

For refunds, if no fees array is provided in the refund request, no fees are returned—giving you full control over your refund policy. For ACH returns and voids, fee returns happen automatically since the original payment is reversed.

Note: Payments created with application_fee_amount (legacy structure) continue to behave as before—this fee lifecycle applies only to payments using the fees array.

Balance Transactions

Each fee type creates separate balance transaction entries for clear tracking:

When a payment is captured:

When fees are returned (refund/ACH return/void):

Reporting

Each fee type appears as a separate line item in:

• Balance transactions for both merchants and platforms
• Subaccount payout reports
• Platform proceeds reports

This gives merchants clear visibility into their true processing costs versus platform charges, and gives platforms detailed revenue breakdowns by fee type.

For Existing Integrations

The application_fee_amount field continues to work unchanged for existing integrations. When you're ready to adopt the enhanced fee structure:

1. Replace application_fee_amount with the fees array
2. Decide how to split your fee between processing_fee and platform_fee
3. Update your refund logic to specify which fees to return

You cannot use both application_fee_amount and fees in the same request.

Coming Soon: We'll be providing migration tooling and support to help existing integrations transition to the enhanced fee structure.

Sub Accounts are the representation of your platform's customers for payment processing in JustiFi and are associated with your platform account. To gain approval for payment processing each of your customers need to be onboarded as a business via web compoenent, hosted onboarding or API. During the onboarding process a sub account is automatically created for each business and updated along the way. Payments can be processed through a sub account once it's status is enabled.

A Platform Wallet Account allows you to store payment methods centrally and use them across multiple sub accounts within your platform. This feature enables you to maintain a single source of stored payment methods while processing payments through different sub accounts.

Note: You can choose a sub account as your platform_wallet_account once it is underwritten and enabled for payments.

Contact us at customer_success@justifi.tech to enable the platform_wallet_account setting for your designated platform wallet account.

Once enabled, you can:

• Store payment methods in the designated platform wallet account
• Use these payment methods across your platform's sub accounts
• Group payment methods for easier management using PaymentMethodGroups, to associate multiple payment methods to your customer

Note: While the PaymentMethods and Payments API allow you to tokenize a payment method we strongly suggest using the Unified Fintech Checkout or Tokenize Payment Method web components instead to avoid PCI scope

1. Manage Payment Methods

Create and organize payment methods in your platform wallet account. All payment method operations require the platform wallet account ID in the Sub-Account header.

// Example: Create payment method group
const group = await fetch('https://api.justifi.ai/v1/payment_method_groups', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Sub-Account': platformWalletAccountId,  // Platform wallet account
    'Content-Type': 'application/json'
  }
});

// Example: Add payment methods to group
const updatedGroup = await fetch(`https://api.justifi.ai/v1/payment_method_groups/${groupId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Sub-Account': platformWalletAccountId,  // Platform wallet account
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "payment_method_ids": ["pm_walletaccxyz", "pm_walletaccabc"]
  })
});

2. Process Payments

You can process payments using wallet payment methods either through the Unified Fintech Checkout web component or via API

Via Checkout Component

Checkout via Component Walkthrough

// Create checkout
const checkout = await fetch('https://api.justifi.ai/v1/checkouts', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Sub-Account': processingSubAccountId,  // Processing sub account
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "amount": 1799,
    "description": "Example item",
    "payment_method_group_id": "pmg_walletGroupId", // Group from wallet account
    "origin_url": "http://localhost:3000"  // Required for component
  })
});

// Render component
<justifi-checkout
  auth-token="${webComponentToken}"
  checkout-id="${checkout.id}">
</justifi-checkout>

Via API

// Create checkout
const checkout = await fetch('https://api.justifi.ai/v1/checkouts', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Sub-Account': processingSubAccountId,  // Processing sub account
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "amount": 1799,
    "description": "Example item",
    "payment_method_group_id": "pmg_walletGroupId" // Group from wallet account
  })
});

// Complete checkout with wallet payment method
const completion = await fetch(`https://api.justifi.ai/v1/checkouts/${checkoutId}/complete`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Sub-Account': processingSubAccountId,  // Processing sub account
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "payment_token": "pm_walletPaymentMethodToken"
  })
});

• You can update a payment method via the payment methods API
• Updates should always be made to the payment method in the platform wallet account
• Any changes made to the platform wallet payment method automatically propagate to all cloned payment methods across sub accounts
• Available update options include:
  • Card expiration date
  • Payment method metadata
• The system maintains consistency by:
  • Automatically syncing updates to all cloned versions of the payment method

• Header Requirements:
  • Use platform wallet account ID for:
    • Creating/managing payment methods
    • Creating/managing payment method groups
  • Use processing sub account ID for:
    • Creating checkouts
    • Completing payments
• The system automatically:
  • Validates wallet payment method access
  • Creates payment method clones for processing sub accounts
  • Returns new sub account specific tokens in responses
• All sub accounts must be on the same platform as the platform wallet account

For complete details on specific endpoints, see:

• Checkout via Component
• Checkout via API
• Payments API

In order to process payments, each of your customers must be onboarded on the JustiFi platform. Once they are added they go through an approval process. JustiFi's PaymentProvisioning web component allows you to collect the required business and financial information from each of your customers. Once approved, your customer can process payments through JustiFi.

To onboard a new business via PaymentProvisioning web component

1. Get an access token
2. Create a business
3. Generate a web component token
4. Render the Payment Provisioning web component
5. Handle success/failure events of the web component
6. Check the sub account's status

Get an access token

On your backend, using your client id and client secret from the Developer > API keys section of the JustiFi dashboard, generate an access token.

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();

Create a business

From your backend create a business using the Business API. A business only requires one parameter (e.g. legal_name) but you can pass as much information about your customer as you have. When you render the web component all the data you passed to the business will be pre-filled in the form and can be updated by your customer.

async function createBusiness(token) {
  const response = await fetch('https://api.justifi.ai/v1/entities/business', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({
      "legal_name": "First Business"
    })
  });
  const data = await response.json();
  return data;
}

const business = await createBusiness(token);

Generate a web component token

To render the PaymentProvisioning web component, you must generate a web component token. This is a short lived token which is meant to grant short term, fine grained access. The web component requires the role of write:business:${businessId} with the id of the business you created in the previous step.

async function getWebComponentToken(token, businessId) {
  const response = await fetch('https://api.justifi.ai/v1/web_component_tokens', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({
      "resources": [`write:business:${businessId}`]
    })
  });
  const data = await response.json();
  return data.access_token;
}

const webComponentToken = await getWebComponentToken(token, business.id);

Render the PaymentProvisioning web component

Using the web component token generated above and the business id, render the PaymentProvisioning web component. This will allow your customer to provide all business information required for payment processing

<justifi-payment-provisioning auth-token="${webComponentToken}" business-id="${business.id}"></justifi-payment-provisioning>

Handle success/failure events of the web component

The web component makes an API request every time the user moves to a Next step and when the user submits the form. Whenever the web component receives an API response it emits a submitted event that contains the API response.

When the form is submitted we provision the business and create a sub account for the business. The submitted event data will contain the response from the Provisioning API request. If the provisioning request was successful the response will include the sub_account_id attribute of that newly created sub account. Otherwise, an error message can be presented to the user. Our example below covers both.

The error event means there was an issue with the PaymentProvisioning form connecting to the network, etc.

<script>
  const justifiPaymentProvisioning = document.querySelector('justifi-payment-provisioning');
  justifiPaymentProvisioning.addEventListener('submit-event', (event) => {
    if (event.details.data) {
      console.log("Form sumbission succeeded!");
    } else {
      console.log("An error occured")
    }
  });
  justifiPaymentProvisioning.addEventListener('error-event', (event) => {
    console.log(event);
  });
</script>

Check the sub account's status

Once your business submits the onboarding form

1. We will provision your business for payment processing and create a sub account for this business as mentioned above. This sub account is the representation of your business for payment processing.
2. We'll review the submitted information. This underwriting process can take up to a few business days. Once approved the status of the sub account will be updated to enabled and payments can be processed.

In order to check the account's onboarding status, call the Get a Sub Account endpoint or use an event publisher to subscribe to the sub_account.updated events

Retrieve a sub account

async function getBusiness(token, accountId) {
  const response = await fetch(`https://api.justifi.ai/v1/sub_accounts/${accountId}`, {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    }
  });
  const data = await response.json();
  return data;
}

const business = await getBusiness(toke, account.id);

In order to process payments, each of your customers (whom we refer to as businesses) will have to be onboarded on our platform. Once they are added they go through an approval process. JustiFi's hosted onboarding provides you with an easy-to-implement, user-friendly way to collect the required business and financial information from each business within your platform. Once approved, your business can process payments through JustiFi.

To onboard a new business via hosted onboarding:

1. Get an access token
2. Create a business
3. Generate a web component token
4. Include JustiFi Hosted Onboarding in your application
5. (optional) Listen to success/fail message
6. Check the underwriting status of the sub account connected to the business

1. Get an access token

On your backend, using your client id and client secret from the Developer > API keys section of the JustiFi dashboard, generate an access token.

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();

2. Create a business

From your backend create a business using the Business API. A business only requires one parameter (e.g. legal_name) but you can pass as much information about your customer as you have. When you render the web component all the data you passed to the business will be pre-filled in the form and can be updated by your customer.

async function createBusiness(token) {
  const response = await fetch('https://api.justifi.ai/v1/entities/business', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({
      "legal_name": "First Business"
    })
  });
  const data = await response.json();
  return data;
}

const business = await createBusiness(token);

3. Generate a web component token

To render the Hosted Onboarding form, you must generate a web component token. This is a short-lived token intended to grant temporary, fine-grained access. The web component requires the role write:business:${businessId}, with the ID of the business created in the previous step.

Note:The web component token expires after 60 minutes. If the onboarding flow takes longer than that to complete, you’ll need to generate a new web component token and reinitialize the component with the refreshed token.

async function getWebComponentToken(token, businessId) {
  const response = await fetch('https://api.justifi.ai/v1/web_component_tokens', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({
      "resources": [`write:business:${businessId}`]
    })
  });
  const data = await response.json();
  return data.access_token;
}

const webComponentToken = await getWebComponentToken(token, business.id);

4. Include JustiFi Hosted Onboarding in your application

To present the JustiFi hosted onboarding form to your user, create an iframe with with the following source:
https://components.justifi.ai/onboarding?business_id=BUSINESS_ID&web_component_token=WEB_COMPONENT_TOKEN,
where BUSINESS_ID is the business_id that was created in step 2 and WEB_COMPONENT_TOKEN is the access_token that was created in step 3.
This iframe will present your user with a multi-step form where they can enter the business and financial information needed for approval. Upon submission, a success message will display.

5. (optional) Listen to success/fail message

Listen to success/fail message

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

window.addEventListener('message', handleOnboardingCompletion);

When the onboarding is completed, success or failure, the JustiFi iframe will send a postMessage. This allows your platform to take a next step, for example closing a modal, or redirecting to another page.

6. Check the underwriting status of the sub account connected to the business

Once your business submits the onboarding form

1. We will provision your business for payment processing and create a sub account for this business. This sub account is the representation of your business for payment processing.
2. We'll review the submitted information. This approval process can take up to a few business days. In order to check the account's onboarding status, call the Get a Sub Account endpoint or use an event publisher to subscribe to the sub_account.updated events

Retrieve a sub account

curl -X GET https://api.justifi.ai/v1/sub_accounts/ACCOUNT_ID \
    -H 'Authorization: Bearer [access_token]' \
    -H 'Accept: application/json'

In order to process payments, each of your customers (whom we refer to as businesses) will have to be onboarded on the JustiFi platform. Once they are added they go through an approval process. JustiFi's onboarding API allows you to utilize your own onboarding frontend to collect the required business and financial information from each of your businesses. Once approved, your business can process payments through JustiFi.

To onboard a new business via the API

1. Create a business
2. Create a bank account
3. Upload documents
4. Accept terms and conditions
5. Provision the business
6. Check the sub account's status

Create a business

Create a business

curl -X POST \
  https://api.justifi.ai/v1/entities/business \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "legal_name": "Business name"
  }'

Use the business API to create a business on JustiFi that is associated with your platform. The create business API endpoint does not require any parameters but they will be required when the business is provisioned (see step 5). You will need the ID from the business you create for the next steps.

Create a bank account

Use the bank account API to create a bank account. This bank account will be used to pay out earnings for payment processing to the business.

Upload documents

Use the document API to upload a document. The minimum document requirement (for small businesses and sole proprietors) is a voided check.

Accepte terms and conditions

Use the terms and conditions API to accept terms for payment processing.

Provision the business

Provision the business for payment processing

curl -X POST \
  https://api.justifi.ai/v1/entities/provisioning \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -d '{
      "business_id": "biz_123",
      "product_category": "payment"
      }'

Once you have submitted all business related information use the provisioning API to provision the business for payment processing. At this point all required parameters for payment processing are validated. An error is returned if any fields are missing. If successful, the product provisioning request will create a sub account associated with the business. The response will include the ID of that associated sub account. It is required for any payment processing related API requests.

Check the sub account status

Retrieve a sub account

curl -X GET https://api.justifi.ai/v1/sub_accounts/ACCOUNT_ID \
    -H 'Authorization: Bearer [access_token]' \
    -H 'Accept: application/json'

Once you have provisioned the busiess, we'll review their information. This approval process can take up to a few business days. In order to check the associated sub account's onboarding status, call the Get a Sub Account endpoint or use an event publisher to subscribe to the sub_account.updated events.

Proceeds represent your platform's take-home portion of the fees from your sub account's financial transactions. Proceeds are batched together according to the payout schedule configured on your account, then transferred to your active bank account.

Reports can be used to pull data for various different resources. They are CSV format, and can be filtered by date and sub account. Once a the create endpoint is called via POST, a report will be in created status. The report will move to processing status once it is being generated. Finally, when the report is generated, and the CSV file is available, the report will be in completed status.

To download a report, you can use the download_url provided in the response when retrieving a report. We use presigned URLs to allow you to download the report directly from our S3 bucket.

Payout Report

Contains balance transaction data for payouts.

Proceeds Report

Contains platform proceeds data.

To charge a payment method the desired amount, you'll use a payment. You can choose whether to charge a payment method that's already been tokenized or tokenize a new one when you create the payment. If a payment fails, the status will reflect it and an error code will be returned. You can retrieve information about your payments and refund them if needed.