The following guides provide 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 application user interface. 

Applications generated using the CoPilot API cannot be whitelisted. The generated application is branded with CardPointe and CardConnect logos, making it clear that the merchant account is created outside of the context of the ISV partner’s software. Additionally, the merchant must agree to the Terms and Conditions to work with CardConnect.

Merchant Creation Workflow

The following process outlines the typical workflow for using the CoPilot API to create a merchant application:

  1. You use the CoPilot API to create a bearer token that authenticates your CoPilot user account.
  2. You make a POST request to the merchant endpoint to create a new merchant application.
  3. The API returns a CoPilot Merchant ID (different from the processing Merchant ID).
  4. You make a PUT request to the signature endpoint to generate a signature request form to send to the merchant.
  5. You send the application to the merchant to review and sign.
  6. The merchant signs the application and the underwriting and boarding process begins.

Using Application Templates

Using the CoPilot portal, partners can create application templates that include pre-filled values for any details that have been pre-determined (for example, fees and processing information). Instead of manually including these fields in your API requests, you specify the template ID in your request, and the application will be populated with the values set in the template.

It is strongly recommended that you build application templates to use in conjunction with merchant create API requests. Set any default or common values values that you would otherwise have to manually include in every new merchant application request. This helps to ensure that your applications are correct and consistent, and promotes a smooth application and boarding experience for your merchants.

You can set fees, MCC codes, product deliveries, volume information, and mode of transaction in the template, reducing the fields that you must populate using the API, and that the merchant must fill out manually in the generated application.

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 includes only the minimum data required to create the application. In this case, you include some basic information in the merchant create API request, and generate a link to direct the merchant to the online application. The merchant must then complete the application, providing the necessary information (including bank account details, MCC codes, and demographic information) required for the underwriting and boarding teams to process the application.

The following example illustrates a basic merchant create request:  

If you are using an application template, specify the template identifier in the templateId field in the request.

Example: Merchant Create Request with Minimal Data

{
    "templateId": "{{template-id}}",
    "merchant": {
        "businessStartDate": "02/17/2012",
        "salesCode": "{{sales-code}}",
        "dbaName": "CardConnet",
        "legalBusinessName": "CardConnect LLC",
        "taxFilingName": "CardConnect LLC",
        "processing": {
            "platformDetails": {
                "discoverProgramCd": "MAP",
                "taxId": "123456789",
                "currencyCode": "USD",
                "ownerSiteUser": {
                    "firstName": "Card",
                    "lastName": "Connect",
                    "email": "cardconnect@cardconnect.com"
                }
            }
        },
        "demographic": {
            "websiteAddress": "https://www.cardconnect.com",
            "businessPhone": "877-828-0720",
            "businessAddress": {
                "address1": "1000 Continental Drive",
                "address2": "Suite 300",
                "city": "King of Prussia",
                "stateCd": "PA",
                "zip": "19468",
                "countryCd": "US"
            },
            "mailingAddress": {
                "address1": "1000 Continental Drive",
                "address2": "Suite 300",
                "city": "King of Prussia",
                "stateCd": "PA",
                "zip": "19468",
                "countryCd": "US"
            }
        },
        "ownership": {
            "owner": {
                "ownerAddress": {
                "address1": "1000 Continental Drive",
                "address2": "Suite 300",
                "city": "King of Prussia",
                "stateCd": "PA",
                "zip": "19468",
                "countryCd": "US"
                },
                "ownerEmail": "cardconnect@cardconnect.com",
                "ownerName": "Card Connect",
                "ownerDob": "12/25/1969",
                "ownerPhone": "877-828-0720",
                "ownerSSN": "555-66-7890",
                "ownerTitle": "CEO"
            },
            "ownershipTypeCd": "LLC",
            "ownerOwnershipPct": "100"
        },
        "merchantContactInfo": {
            "contactName": "Card Connect",
            "contactEmail": "cardconnect@contactemail.com",
            "contactPhone": "877-828-0720"
        },
        "bankDetail": {
            "depositBank": {
                "bankAcctNum": "123456789",
                "bankRoutingNum": "987654321",
                "bankAcctTypeCd": "BIZ",
                "bankName": "Gringotts Bank"
            },
            "withdrawalBank": {
                "bankAcctNum": "123456789",
                "bankRoutingNum": "987654321",
                "bankAcctTypeCd": "BIZ",
                "bankName": "Gringotts Bank"
            }
        }
    }
}

Creating an Application with Data Gathered from the Merchant

Instead of requiring the merchant to manually complete most of the application, you can gather the necessary data from the merchant and include it in the merchant create API request. In this case, include the merchant's business information, ownership information, and banking information in the API request. 

The following example illustrates a merchant create request with the merchant's data included:

If you are using an application template, specify the template identifier in the templateId field in the request.

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

   {
    "templateId":"18040",
    "merchant":
       {
        "salesCode":"907LLC",
        "dbaName": "Sample Biz",
        "legalBusinessName": "Sample Business",
        "taxFilingMethod": "SSN",
        "taxFilingName": "Sample Business",
        "demographic": 
           {
            "websiteAddress": "https://cardconnect.com/",
            "businessPhone": "800-555-8000",
            "businessAddress": 
               {
                "address1": "1000 Continental Drive",
                "address2": null,
                "city": "King of Prussia",
                "countryCd": "US",
                "stateCd": "PA",
                "zip": "19406"
               },
            "mailingAddress": 
               {
                "address1": "1000 Continental Drive",
                "address2": null,
                "city": "King of Prussia",
                "countryCd": "US",
                "stateCd": "PA",
                "zip": "19406"
               }
           },
        "businessStartDate": "04/30/1989",
        "bankDetail": 
           {
            "depositBank": 
               {
                "bankAcctNum": "1234567890",
                "bankRoutingNum": "091215927",
                "bankAcctTypeCd": "BIZ",
                "bankName": "First Bank of Test"
               },
            "withdrawalBank": 
               {
                "bankAcctNum": "1234567890",
                "bankRoutingNum": "091215927",
                "bankAcctTypeCd": "BIZ",
                "bankName": "First Bank of Test"
               }
           },
        "ownership": 
           {
            "owner": 
               {
                "ownerAddress": 
                   {
                    "address1": "1000 Continental Drive",
                    "address2": null,
                    "city": "King of Prussia",
                    "countryCd": "US",
                    "stateCd": "PA",
                    "zip": "19406"
                   },
                "ownerEmail": "jsmith@cardconnect.com",
                "ownerName": "John Smith",
                "ownerDob": "01/01/1901",
                "ownerPhone": "555-555-1212",
                "ownerMobilePhone": "555-555-1212",
                "ownerSSN": "123-33-4567",
                "ownerTitle": "CEO"
               },
            "ownershipTypeCd": "PRIVCORP",
            "driversLicenseNumber": "12345678",
            "driversLicenseStateCd": "PA",
            "ownerOwnershipPct": "100"
           },
        "merchantContactInfo": 
           {
            "contactName": "John Smith",
            "contactEmail": "jsmith@cardconnect.com",
            "contactPhone": "555-555-1212"
           },
        "processing": 
           {
            "platformDetails": 
               {
                "amexProgramAssetCd": "OPTBLUE",
                "discoverProgramCd": "MAP",
                "acquiringFlg": true,
                "taxId": "485968574",
                "currencyCode": "USD",
                "mccId": "5999",
                "businessDescription": "Sample merchant creation request"
               }
           },
        "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": "John",
        "lastName": "Smith",
        "email": "jsmith@csa1.com"
       }
   }

Attaching a Voided Check to an Application

Additionally, the application requires copies of voided checks for each deposit and withdrawal account to verify the merchant's banking information. The merchant can upload a check later in the application process, or provide a voided check to the partner. If the merchant provides a voided check, you can attach it to the application using the merchant attachment API request. To do this, you scan and convert the check image into a JSON-escpaed, Base64-encoded string, and include the string in 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=="
    }
}

Tracking an Application

Once the merchant signs off on the application, the underwriting and boarding process begins. Partners can track the account using the merchant find API request. Additionally, once the account is boarded to the CardPointe Gateway, you can use the merchant find request to get the processing merchant ID (MID) for the account.

Scheduling Recurring Payments

This guide provides information for extending your existing CoPilot API integration to add recurring billing to your payment methods.

The CoPilot API includes a Billing Plan endpoint that you can use to create a recurring payment schedule using tokenized and stored customer payment data.

It is a violation of PCI DSS standards to store Card Verification Value (CVV) data. Neither CardConnect 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. depending on your integration and business needs, your procedure may vary.

  1. Tokenize the customer's payment data.

    Depending on your existing integration, there are several ways to tokenize payment data.

    For example, you can:
    • Use the customer’s clear PAN or ACH payment data to make a CardPointe Gateway API authorization request. Include "tokenize" : "y" to retrieve a token in the response.

      Optionally, do the following: 

      • Include ”capture” : “y” to accept an initial payment.
      • include ”profile” : “y” to store the customer’s data in a profile to use in future requests.
    • Gather and tokenize the payment card data using the Hosted iFrame Tokenizer.
    • Use a Bolt terminal and the Bolt P2PE API readCard or readManual service endpoint.
  2. Store the token for reuse.

    You can either store tokens and customer data in your own database, or you can use the CardPointe Gateway API’s profile service endpoint to create and store customer profiles in CardConnect’s secure vault. You can skip this step if you created a profile in step 1.
  3. 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.
  4. Call the CoPilot API Create Billing Plan endpoint to create the billing plan. Specify the Billing Plan parameters as described in the Billing Plan Definition.
  5. To cancel, update, or view your current billing plans, see the CoPilot API for more information on managing billing plans.