Using the CoPilot API to Submit a Merchant Application

Overview

The Copilot API is an interface into the CoPilot merchant management platform. You can use the CoPilot API to create and update merchant accounts programmatically, instead of using the CoPilot web interface. 

Merchant Creation Workflow

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

1. Submit a request to the Token endpoint to obtain a bearer token needed for authentication.
2. Submit a POST request to the Merchant endpoint to create a new merchant account.
3. Store the CoPilot Merchant ID returned in the response, as it is needed in subsequent calls.
4. Submit a PUT request to the Signature endpoint to receive the link to the digital application.

Provide the digital application URL to the merchant so that they may review and sign the application digitally using their web browser. Once signed, the account then automatically progresses through the remaining underwriting and boarding procedures.

Running the API in Postman

To help you get started with your integration, we have created a Postman Collection that includes templates for all of the requests documented in the CoPilot API. 

The Postman Collection also includes a sample Environment containing variables for fields that are required in many of the API requests. See Configuring Your Postman Environment below for more information. 

Click the button below to download the CoPilot API Postman collection:

Configuring Your Postman Environment

Included with the collection is a Postman Environment containing variables where you can pre-fill fields that are required in many of the API requests. 

As an initial step in configuring your environment variables, enter your authentication credentials in the existing environment variables and send a request to the Token endpoint. The Bearer token returned is automatically stored to the access-token environment variable and used to authenticate your subsequent API requests.

See the Postman Learning Center for more information on managing environments and variables.

Using Application Templates

Before you can create a new merchant account using the CoPilot API, you must first create an Application Template using the CoPilot web interface. Once you have created at least one template in the CoPilot web interface, it is possible to use the CoPilot API exclusively for merchant creation and management in most cases.

The Application Template is required when creating a new account in order to automatically assign pre-configured default values for new accounts. Almost all fields available in the merchant application can be preset using a template, and multiple templates can be created that use different Sales Codes, default pricing, fees, equipment, or other settings.

When creating an account using the API, the Application Template you provide in the request determines what default values are applied to the new account. Remember to supplement the values automatically applied by the Application Template with any additional objects or fields that may also be required in order to request the link to the merchant-facing digital application. See the section on Adding Supplemental Data and Overriding Default Values for more information.

Creating an Application

Depending on your needs, you can create applications with varying degrees of merchant data included.

Creating an Application with Minimal Data

You might want to provide merchants with an application that requires nearly all fields to be completed by the business owner using the digital application. In this case, you must start by creating an account using the Merchant endpoint with the required business information and contact details.

You can then request the digital application link using the Signature endpoint and supply this URL to the owner to complete and sign the reminder of the digital application using their web browser. Using the digital application link, the owner can add additional owners, input their bank account details, processing volume, select the applicable Merchant Category Code (MCC), and other details needed to submit the application for underwriting and boarding.

The example below illustrates the minimum amount of data needed to create an account and generate the link to the digital signature:

Creating an Application with Data Gathered from the Merchant

When you have already gathered business information from the merchant before creating the account in CoPilot, you can supply additional data in the call to the Merchant endpoint to reduce the amount of fields the merchant must manually enter when completing the application. The merchant data you provide during account creation will populate in the digital application that the merchant receives, requiring them to complete only the remaining fields.

The following example illustrates a merchant creation request with additional merchant data included:

Adding Supplemental Data and Overriding Default Values

You can set values for fields that are not pre-configured in the Application Template, or override any value set by the Application Template during merchant creation:

• To set or override default values from the Application Template during merchant creation, include the values in your POST request to the Merchant endpoint.
• To set or override default values from the Application Template after the merchant account is created, but prior to generating the digital application link, include the values in a PUT request to the Merchant endpoint. Remember to specify the applicable merchantId in the endpoint path as outlined in the API documentation.
  

Attaching a Voided Check to an Application

The digital application that the owner receives includes a section to enter and verify their banking information instantly. When a merchant uses the instant verification method to confirm their banking information, you are not required to provide a voided check from the merchant's deposit and withdrawal accounts.

If the merchant bypasses the instant verification and manually enters their banking information, or if you have already obtained voided checks from the merchant, use the Attachment endpoint to upload a copy of the voided checks. Scan the document and convert the file to a Base64-encoded string required for the document field in the request.

The following example illustrates a merchant attachment request used to attach a voided check to an application:

Generating the Digital Application Link

Once you have created the new account and supplied all the required fields, use the Signature endpoint to generate the URL that will be used by the owner to complete and sign the digital application. A successful request returns the digital application URL that can be provided to the account owner.

If the request is unsuccessful, you should refer to the Errors array returned in the response for additional details.

Tracking an Application

Submit a GET request to the Merchant endpoint to view all merchant data, including the merchantStatus object where you can find information on the current state of new accounts.

Determining the Account Boarding Status

The boardingProcessStatusCd field of the merchantStatus object provides you with the current state of the account. After you have generated the link for the digital application, the boarding state is updated to OFS, indicating that the application is "Out For Signature." Once the merchant has completed and submitted the application, the boarding status then continues to update as it progresses through the remaining underwriting and boarding procedures.

Determining the Gateway Boarding Status

The gatewayBoardingStatusCd field of the merchantStatus object provides you details on the gateway boarding status of the account. You know the account is active and ready to process transactions when the gateway boarding status is BOARDED.

Determining the Account's Processing MID

When the gateway boarding status returned is BOARDED, you can then obtain the account's processing MID by referencing the frontEndMid value within the merchant.processing.platformDetails object of the GET response.