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.

Branding: Applications generated using the Boarding API cannot be white labeled. The merchant application contains Run Payments branding as an indicator that the new merchant account is independent from the partner’s software platform.

Merchant Creation

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

Obtain your credentials (Client ID and Client Secret) from your Integration Delivery Lead.
Define the pricing, platform fees, and products that will be set to build your API request.
Submit a POST request to the merchant endpoint to create a new merchant account. To immediately send the application to the merchant, set the auto-send for signature flag to Y.
Store the response for future interactions with the newly created merchant record, such as tracking merchant statsu

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.

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
`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

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.