The following guide provides best practices and other supplemental information for integrating the CoPilot API.

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. 

Applications generated using the CoPilot API cannot be white-labeled. The merchant application contains CardPointe and CardConnect branding as an indicator that the merchant account is independent of the ISV partner’s software, as well as containing CardConnect's Terms and Conditions that must be reviewed and accepted in order to create the account.

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.

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.

Although only minimal data is required when creating an Application Template in the CoPilot web interface, you should strongly consider providing as many defaults as possible. This reduces the amount of fields that must be supplied in the API call, ensures standardized values are applied consistently, and can potentially reduce the amount of data the merchant must enter manually.

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:

Example: Merchant Create Request with Minimal Data

{
    "templateId": "{{template-id}}",
    "merchant": {
        "salesCode": "{{sales-code}}",
        "dbaName": "The Card Shoppe",
        "legalBusinessName": "The Card Shoppe",
        "taxFilingName": "The Card Shoppe LLC",
        "taxFilingMethod": "EIN",
        "demographic": {
            "businessAddress": {
                "address1": "123 Fake Street",
                "address2": "Suite 300",
                "city": "Keystone",
                "stateCd": "CO",
                "zip": "80435",
                "countryCd": "US"
            },
            "mailingAddress": {
                "address1": "123 Fake Street",
                "address2": "Suite 300",
                "city": "Keystone",
                "stateCd": "CO",
                "zip": "80435",
                "countryCd": "US"
            }
        },
        "ownership": {
            "owner": {
                "ownerAddress": {
                    "address1": "1 Imaginary Lane",
                    "address2": "Apt 221B",
                    "city": "Dillon",
                    "stateCd": "CO",
                    "zip": "80435",
                    "countryCd": "US"
                },
                "ownerEmail": "name@email.com",
                "ownerName": "Forename Surname",
                "ownerPhone": "555-123-4567",
                "ownerTitle": "CEO"
            },
            "driversLicenseNumber": "123456789",
            "driversLicenseStateCd": "CO"
        },
        "bankDetail": {
            "depositBank": {
                "bankAcctNum": "123456789",
                "bankRoutingNum": "987654321",
                "bankAcctTypeCd": "BIZ",
                "bankName": "Deposit Bank"
            },
            "withdrawalBank": {
                "bankAcctNum": "123456789",
                "bankRoutingNum": "987654321",
                "bankAcctTypeCd": "BIZ",
                "bankName": "Withdrawal Bank"
            }
        }
    },
    "ownerSiteUser": {
        "firstName": "Forename",
        "lastName": "Surname",
        "email": "name@email.com"
    }
}

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:

Example: Merchant Create Request Using a Template and Merchant Business Details

{
    "templateId":"{{template-id}}",
    "merchant": {
        "salesCode":"{{sales-code}}",
        "dbaName": "The Card Shoppe",
        "legalBusinessName": "The Card Shoppe",
        "taxFilingName": "The Card Shoppe LLC",
        "taxFilingMethod": "EIN",
        "businessStartDate": "09/17/1949",
        "demographic": {
            "websiteAddress": "www.example.com",
            "businessPhone": "555-123-4567",
            "businessAddress": {
                "address1": "123 Fake Street",
                "address2": "Suite 300",
                "city": "Keystone",
                "stateCd": "CO",
                "zip": "80435",
                "countryCd": "US"
            },
            "mailingAddress": {
                "address1": "123 Fake Street",
                "address2": "Suite 300",
                "city": "Keystone",
                "stateCd": "CO",
                "zip": "80435",
                "countryCd": "US",
            }
        },
        "ownership": {
            "owner": {
                "ownerAddress": {
                    "address1": "1 Imaginary Lane",
                    "address2": "Apt 221B",
                    "city": "Dillon",
                    "stateCd": "CO",
                    "zip": "80435",
                    "countryCd": "US",
                },
                "ownerEmail": "name@email.com",
                "ownerName": "Forename Surname",
                "ownerDob": "09/04/1929",
                "ownerPhone": "555-123-4567",
                "ownerMobilePhone": "555-987-6543",
                "ownerSSN": "111-22-3333",
                "ownerTitle": "CEO"
            },
            "ownershipTypeCd": "PRIVCORP",
            "driversLicenseNumber": "123456789",
            "driversLicenseStateCd": "CO",
            "ownerOwnershipPct": "100"
        },
        "merchantContactInfo": {
            "contactName": "Forename Surname",
            "contactEmail": "name@email.com",
            "contactPhone": "555-123-4567"
        },
        "bankDetail": {
            "depositBank": {
                "bankAcctNum": "1234567890",
                "bankRoutingNum": "987654321",
                "bankAcctTypeCd": "BIZ",
                "bankName": "Deposit Bank"
            },
            "withdrawalBank": {
                "bankAcctNum": "1234567890",
                "bankRoutingNum": "091215927",
                "bankAcctTypeCd": "BIZ",
                "bankName": "Withdrawal Bank"
            }
        },
        "processing": {
            "platformDetails": {
                "amexProgramAssetCd": "OPTBLUE",
                "discoverProgramCd": "MAP",
                "acquiringFlg": true,
                "taxId": "123456789",
                "currencyCode": "USD",
                "mccId": "3076",
                "businessDescription": "Business Description"
            },
            "businessDetails": {
                "customerBillPriorToShipFlg": false,
                "depositReqForFulfillFlg": true,
                "whenCustomerChargedCd": "INADVANCE",
                "refundPolicyCd": "EXCHONLY",
                "serviceProvidedInCd": "30LESS"
            },
            "volumeDetails": {
                "averageMonthlyVolume": 9999.00,
                "highTicketAmount": 99.99,
                "averageTicketAmount": 9.99
            },
            "deliveryPercentages": {
                "dlvry0To7DaysPct": 100,
                "dlvry15To30DaysPct": 0,
                "dlvry8To14DaysPct": 0,
                "dlvryOver30DaysPct": 0
            },
            "modeOfTransaction": {
                "eCommercePct": 100,
                "keyedPct": 0,
                "mailOrderPct": 0,
                "swipedPct": 0
            }
        }
    },
    "ownerSiteUser": {
        "firstName": "Forename",
        "lastName": "Surname",
        "email": "name@email.com"
    }
}

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.

You must include all applicable and required fields of the parent object when supplementing or overriding data from the Application Template. For example, if adding or overriding the earlyCancelFee in your POST or PUT request, include values for all fields of the fees parent object. Any fields omitted under the fees parent object will be set to null, erasing any previous values set.

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:

Example: Merchant Attachment Request with Voided Check

{
    "attachment" : {
        "fileName" : "VoidedCheck.pdf",
        "mimeType" : "application/pdf",
        "description" : "This is the voided check",
        "attachmentTypeCd" : "VOIDBNKCHK1",
        "document" : "JVBERi0xLjEKJcKlwrHDqwoKMSAwIG9iagogIDw8IC9UeXBlIC9DYXRhbG9nCiAgICAgL1BhZ2Vz
IDIgMCBSCiAgPj4KZW5kb2JqCgoyIDAgb2JqCiAgPDwgL1R5cGUgL1BhZ2VzCiAgICAgL0tpZHMg
WzMgMCBSXQogICAgIC9Db3VudCAxCiAgICAgL01lZGlhQm94IFswIDAgMzAwIDE0NF0KICA+Pgpl
bmRvYmoKCjMgMCBvYmoKICA8PCAgL1R5cGUgL1BhZ2UKICAgICAgL1BhcmVudCAyIDAgUgogICAg
ICAvUmVzb3VyY2VzCiAgICAgICA8PCAvRm9udAogICAgICAgICAgIDw8IC9GMQogICAgICAgICAg
ICAgICA8PCAvVHlwZSAvRm9udAogICAgICAgICAgICAgICAgICAvU3VidHlwZSAvVHlwZTEKICAg
ICAgICAgICAgICAgICAgL0Jhc2VGb250IC9UaW1lcy1Sb21hbgogICAgICAgICAgICAgICA+Pgog
ICAgICAgICAgID4+CiAgICAgICA+PgogICAgICAvQ29udGVudHMgNCAwIFIKICA+PgplbmRvYmoK
CjQgMCBvYmoKICA8PCAvTGVuZ3RoIDU1ID4+CnN0cmVhbQogIEJUCiAgICAvRjEgMTggVGYKICAg
IDAgMCBUZAogICAgKEhlbGxvIFdvcmxkKSBUagogIEVUCmVuZHN0cmVhbQplbmRvYmoKCnhyZWYK
MCA1CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAxOCAwMDAwMCBuIAowMDAwMDAwMDc3IDAw
MDAwIG4gCjAwMDAwMDAxNzggMDAwMDAgbiAKMDAwMDAwMDQ1NyAwMDAwMCBuIAp0cmFpbGVyCiAg
PDwgIC9Sb290IDEgMCBSCiAgICAgIC9TaXplIDUKICA+PgpzdGFydHhyZWYKNTY1CiUlRU9GCg=="
    }
}

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.

Errors are most commonly encountered when you have not provided values for all of the required fields. See the Adding Supplemental Data and Overriding Default Values section for more information on supplementing existing merchant data with the missing values.

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.

Dates and times are returned in local time, based on the timezone selected in the CoPilot web interface.

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.

Note that the account's processing MID is different from the CoPilot MID returned when creating a new account. The CoPilot MID is the merchantId value within the merchant object. This merchant ID used to identify the account in CoPilot and used in the majority of API calls. The account's processing MID is the frontEndMid value within the platformDetails object. The front end MID is assigned only when the account has been successfully boarded to the Gateway.

Scheduling Recurring Payments

You can augment your existing CoPilot API integration by using the various Billing Plan endpoints to create and manage recurring billing plans using tokenized and stored customer payment data.

It is a violation of PCI DSS standards to store Card Verification Value (CVV) data. Neither the CardPointe Gateway nor the merchant can store this data for the purpose of recurring billing.

How it Works

The following process provides a general overview of the steps required to set up a recurring payment schedule using the CoPilot API.

  1. Tokenize the customer's payment data and create a profile. Depending on your existing integration, there are several ways to tokenize payment data and create a payment profile:
    • Use the customer’s payment card or ACH payment data to make a CardPointe Gateway API authorization request including "profile" : "y" to create a stored profile (optionally, include "capture":"y" to also capture a payment). The authorization response includes the profileid and acctid for the new profile.
    • Use the Hosted iFrame Tokenizer to gather and tokenize the payment data, then use the CardPointe Gateway API to create a profile.
    • Use a Bolt Terminal and the Bolt Terminal API authCard or authManual request, including "createProfile":"true", to accept a payment and create a profile. 
  2. Take note of the profileid and acctid generated during profile creation, as these fields are required to create the billing plan.

Note that the CardPointe Gateway stores these fields as profileid and acctid; however the CoPilot Billing Plan endpoint refers to these values as profileId and acctId.

  1. Gather your billing requirements. Determine the start date and length of the billing plan, the payment amount and frequency, and any additional information that you'll need to include in your requests.
  2. Call the Create Billing Plan endpoint to create the billing plan. Specify the profileID and acctId Billing Plan parameters as described in the Billing Plan Definition.

See the CoPilot API for more information on how to view, update, or cancel existing billing plans.