Guides

Run Developer Home

Getting Started

Tokenize with Runner.js

Reporting with Run Merchant

Boarding API

Validation & Deployment

Changelog

Boarding API Overview

The Boarding API is an interface into Relay, the merchant management platform. You can utilize the Boarding API to create and update merchant accounts via API, instead of using the Relay web interface.

<aside> 👟 Note about 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.

</aside>

Merchant Creation Workflow

The following process outlines the typical workflow when using the Boarding API to create a merchant account and send the digital application to the owner for reviewing and signing:

  1. Obtain credential set from Relay portal: client ID and client secret
  2. Submit a POST request to use the merchant endpoint to create a new merchant account
  3. Enable auto-send for signature flag to Y
  4. Store merchant ID information returned in the response

Running the API in Postman

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

<aside> <img src="https://cdn.worldvectorlogo.com/logos/postman.svg" alt="https://cdn.worldvectorlogo.com/logos/postman.svg" width="40px" /> Run in Postman

Boarding API

Utilities API

</aside>

Configuring Your Postman Environment

Configuring Your Postman Environment.png

Merchant Applications

Fee Templates

Before creating a new merchant account, you can create a fee template through Relay. Once you have created at least one template in Relay, you can enable this as a default when calling the Boarding API.

The fee template is required when creating a new account to automatically pull in pre-configured default values for the new account. Multiple templates can be created that use different sales codes and default fees.

When creating an account using the API, the fee template you provide in the request determines what default values that are applied to the new account. To supplement the values automatically applied by the fee template with different values, you can amend this in the API call, and it will override the default pricing found within the template.

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 Size Type Comments
platform N/A String Either Payroc or Fiserv. Any other values will throw error.
rep_code N/A String Must be one a rep_code that exists on your account. See rep_codes endpoint.
dba_name 150 String
signer_first_name 100 String
signer_last_name 100 String
signer_email 150 String
pricing N/A Object

Tracking the Application Status

Submit a GET request to the merchants or merchants/:id endpoint to view all merchant data including the merchant status field where you can find information on the current state of new accounts. Specifying the merchant ID in the request will pull information specifically for that merchant account.

<aside> 👟 To view test merchant accounts created in Relay, click into profile or user and enable test mode

Untitled

</aside>

Merchant Status Table

merchant_status Meaning
new New
sent_for_signature Sent For Signature
signed Signed
in_underwriting In Underwriting
boarded Boarded
live Live
cancelled Cancelled
declined Declined
unknown Unknown

Boarding API

API Overview

The Boarding API uses JSON web services and provides resources for boarding new merchant accounts and managing existing merchant accounts.

The API complements the Relay merchant onboarding process; however, the web application must be used to complete tasks such as creating the fee templates.

Authentication

The Boarding API uses a Client ID and Client Secret generated from Relay Sales Office access. To obtain the Client ID and Client Secret, you must have Relay access as Sales Office, this will allow onboarding capability and visibility into merchants and future merchants stored within your hierarchy.

<aside> 👟 Let’s Run the Boarding API!

</aside>

Create a Merchant Account

Use the POST method to create a new merchant account with the option to use a pre-existing pricing template that was been created within the Relay web interface. A successful request returns the merchant_id property, which is used to identify the account within Relay, and can be used in subsequent API calls to receive merchant data.

Payroc / Fiserv / Fiserv Clover Bundle

Method           POST

URL                  https://apps.runpayments.io/ords/relay/api/boarding/v1/merchants

Produces         application/json

Create Merchant Request

Field Size Type Required Comments
platform N/A String Y Either payroc or fiserv. Any other values will throw error.
rep_code N/A String Y Must be one a rep_code that exists on your account. See rep_codes endpoint.
customer_id N/A Number N Optional. Used if adding to an existing account. Customer Id can be fetched using merchant/:id endpoint
fee_template_id N/A Number N Optional
dba_name 150 String Y
legal_name 150 String N
tax_id 12 String N
years_in_business Number N
website 250 String N
phone 12 String N In format ###-###-####
mcc_code 4 String N See /mcc
business_desc 400 String N
when_card_charged N/A String N Must be one of the following in_advance, on_delivery
services_provided_in N/A String N Must be one of the following 0_7_days, 8_14_days, 15_30_days, over_30_days
refund_policy N/A String N Must be one of the following no_refunds, ss_than_30_days, less_than_60_days
seasonal N/A Boolean N
seasonal_months 30 String N Colon delimited month numbers (e.g. 1:2:10 would be January, February and October). Required if seasonal is true.
annual_volume N/A Number N
average_ticket N/A Number N
in_person_pct N/A Number N
online_pct N/A Number N
telephone_pct N/A Number N
ownership_type N/A String N Fiserv: Must be one of the following 'llc', 'sole_proprietor', 'government', 'not_for_profit', 'partnership', 'tax_exempt', 'public_corp', 'private_corp' Payroc: 'llc', 'sole_proprietor', 'government', 'not_for_profit', 'partnership', 's_corp', 'c_corp', 'other'
signer_first_name 100 String Y
signer_last_name 100 String Y
signer_dob 10 String N In format mm/dd/yyyy
signer_res_address1 150 String N
signer_res_address2 150 String N
signer_res_city 150 String N
signer_res_state 2 String N
signer_res_zip 10 String N
signer_email 150 String Y
signer_phone 12 String N In format ###-###-####
signer_ownership_pct N/A Number N
addresses N/A Array N
pricing N/A Object Y
fees N/A Object N
products N/A Array N

Nested Objects Defined:

Addresses

Field Size Type Required Comments
address1 150 String Y
address2 150 String N Default to 1 if not provided
city 150 String Y
state 2 String Y 2 Character state abbreviation
zip 10 String Y
address_type N/A String Y Must be one of the following: 'business', 'legal', 'mail_to'