> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runpayments.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runpayments.io/_mcp/server.

# Boarding API

## Overview

The Boarding API is an interface into Run Partner, our merchant management platform. The Boarding API uses JSON web services and provides resources for boarding new merchant accounts and managing existing merchant accounts.

## Merchant Creation

The following process outlines the high level workflow when using the Boarding API to create a merchant account:

1. Obtain your credentials (Client ID and Client Secret) from your Integration Delivery Lead.
2. Define the pricing, platform fees, and products that will be set to build your API request.
3. Submit a `POST` request to the merchant endpoint to create a new merchant account. To immediately send the application to the merchant, set `auto_send_for_signature` to `true`.
4. Store the response for future interactions with the newly created merchant record, such as tracking merchant status.

## Running the API in Postman

To help you get started with your integration, we have created a Postman collection that contains templates for all the requests included in the Boarding API.

* [**Boarding API in Postman**](https://app.getpostman.com/run-collection/27934988-3a410274-c8c1-492b-8c8b-75da9651909a?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D27934988-3a410274-c8c1-492b-8c8b-75da9651909a%26entityType%3Dcollection%26workspaceId%3D6f46012f-fa64-439e-89c0-6484dba3dbb7)
* [**Utilities API in Postman**](https://app.getpostman.com/run-collection/27934988-6ecafefa-5485-4dbb-a05e-0b80021734bb?action=collection%2Ffork\&source=rip_markdown\&collection-url=entityId%3D27934988-6ecafefa-5485-4dbb-a05e-0b80021734bb%26entityType%3Dcollection%26workspaceId%3D6f46012f-fa64-439e-89c0-6484dba3dbb7)

## **Authentication**

The Boarding API requires a Client ID and Client Secret for authentication. You may request your credentials from your Integration Delivery Lead who will deliver them via secure link. Your credentials will provide visibility into existing merchants and future merchants stored within your hierarchy.

## Creating an Application with Minimal Data

If you are looking to provide merchants with an application that requires most fields to be completed by the business owner, you are welcome to pass the minimum amount of data needed to create an account.

### Required Application Fields

| **Field**                 | **Max Length** | **Data Type** | **Comments**                                                                                                                                     |
| ------------------------- | -------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `platform`                | N/A            | String        | Either `Payroc` or `Fiserv`. Any other values will throw error.                                                                                  |
| `rep_code`                | N/A            | String        | Must be a `rep_code` that you have access to through your Run Partner user.  See `rep_codes` endpoint.                                           |
| `dba_name`                | 150            | String        |                                                                                                                                                  |
| `signer_first_name`       | 100            | String        |                                                                                                                                                  |
| `signer_last_name`        | 100            | String        |                                                                                                                                                  |
| `signer_email`            | 150            | String        |                                                                                                                                                  |
| `signer_ownership_pct`    | N/A            | Number        | Ownership percentage of the signer (0-100).                                                                                                      |
| `application_template_id` | N/A            | Number        | Must be an `application_template_id` that you have access to through your Run Partner user.                                                      |
| `pricing`\*               | N/A            | Object        | \*Optional if not sending for signature, omit if using a pricing template.                                                                       |
| `fees`\*                  | N/A            | Object        | \*Optional if not sending for signature, omit if using a pricing template.                                                                       |
| `product`\*               | N/A            | Object        | \*Optional if not sending for signature, omit if using a pricing template. At least one product must be added if sending directly for signature. |

## **Tracking the Application Status**

After submitting your `POST` request, you will receive an `id`. you may submit a `GET` request to the merchants/:id endpoint to view information for that merchant account, including `merchant_status`.

### Merchant Status Table

| **merchant_status**  | **Meaning**                                                                                                                |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `new`                | Merchant record has been created in Run Partner. App has not been sent for signature.                                      |
| `sent_for_signature` | An email link to the application has been sent to the signer contact on file.                                              |
| `signed`             | Signed and submitted to the boarding platform for approval.                                                                |
| `in_underwriting`    | In underwriting at the boarding platform. If additional information is requested prior to boarding, you will be contacted. |
| `boarded`            | The merchant application has been accepted.                                                                                |
| `live`               | The merchant may process transactions.                                                                                     |
| `cancelled`          | This merchant may no longer able to process transactions.                                                                  |
| `declined`           | Declined - Underwriting has declined the merchant application.                                                             |
| `unknown`            | Unknown                                                                                                                    |

> **Warning**
>
> If a `merchant_status` is `unknown` or you believe the `merchant_status` is inaccurate (e.g. a merchant is showing `cancelled` when they should be `live`), please contact your Integration Delivery Lead or send an email to [integrations@runpayments.io](mailto:integrations@runpayments.io).