Overview

The CoPilot API uses JSON web service semantics and provides resources for boarding new merchant accounts and managing existing accounts. 

The API complements the CoPilot web application, offering a programmatic interface to some features available in the application; however, you must use the web application to complete some tasks (for example, creating application templates).

What's New?

Visit status.cardconnect.com and click subscribe to updates to receive important release and status notifications.

Date Updated: 9/1/2021

This release contains the following updates:

PCI Program Selection

The Fees definition now includes a required PCI Program Code field, pciProgramCd, to identify the merchant's PCI program enrollment. 

Additionally, the Fees definition includes a new pciConciergeMonthlyFee, required to submit merchant applications when the pciProgramCd is CONCIERGE.

Getting Started

Authentication

The CoPilot API relies on the Bearer Authentication scheme in order to authenticate each request to the API. In order to obtain a Bearer token used to autheticate your API requests, you must first provide your CoPilot API credentials in a request to the Token endpoint. A successful request will return a JSON Web Token (JWT) that is used as the Bearer token in subsequent calls to the CoPilot API.

Versioning

Whenever possible, newer versions of the API will be backwards compatible with older versions. To ensure your integration is not disrupted in the event that backwards compatibility cannot be maintained, it is highly recommended to specify the version in the header of each API request as part of your integration. This is accomplished by supplying the X-CopilotAPI-Version HTTP header with the value of the version your application uses.

Example Header

Authorization: Bearer accessTokenValue
Content-type: application/json
X-CopilotAPI-Version: 1.0
  • This header should be omitted from requests to the Token endpoint, as authentication via the Token endpoint occurs independently of the CoPilot API.
  • The current version of the CoPilot API is 1.0.

Additional Resources

In addition to this API documentation, the following resources are available to help you get started:

Developer Guides

The CoPilot API Developer Guides provide additional information for using the API to complete specific workflows, for example, Using the CoPilot API to Submit a Merchant Application.

Postman Collection

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

Click the Run in Postman button to download the CoPilot API collection.

Run in Postman

See Running the API in Postman in the CoPilot Developer Guides for more information on using the Postman Collection.

Token

To authenticate any request to the CoPilot API, you must first request an access token using the Token endpoint. The Token endpoint requires your CoPilot API credentials, as outlined below, and returns the access token you will use to make API requests during a session.

The access token is valid for a limited timeframe, indicated by the expires_in value (in seconds). Once a token has expired, you must request a new token.

Important Security Considerations:

  • The provided client_secret is a secret and should never be exposed on the client side via JavaScript. Ensure that the client secret is stored securely in your application.
  • Do not expose the access_token or refresh_token in client-side applications.
MethodPOST
Hosthttps://accountsuat.cardconnect.com
Path/auth/realms/cardconnect/protocol/openid-connect/token
HeadersContent-Type: application/x-www-form-urlencoded
Consumesapplication/x-www-form-urlencoded
Producesapplication/json

Token Request 

FieldRequiredDefault ValueComments
usernameyesN/AYour CoPilot username.
passwordyesN/AYour CoPilot password.
grant_typeyespassword
client_idyesmerchapi
client_secretyesN/ACoPilot API registration is required in order to receive your client_secret.

Token Response

The JSON-encoded request will return a signed OpenID Connect JSON Web Token (JWT) as the access_token value, as well as other properties pertaining to authentication.

FieldTypeComments

access_token

stringThe access token value to be used with the Bearer Authentication scheme for subsequent calls to the API.
expires_innumberThe number of seconds until the access token is no longer valid.
refresh_expires_innumberThe number of seconds until the refresh token is no longer valid.
refresh_tokenstringThe refresh token used to request a new access token.
token_typestringThe type of token provided. A successful request returns a bearer token.
not-before-policynumber

When appliciable, restricts authentication prior to the timestamp value.

session_statestringThe session state string.
scopestringThe scope of use for the token provided. A successful request returns "public-application-client copilot"

Supply the access_token value in the Authorization header of your subsequent API calls, using the Bearer Authentication scheme as shown below.

Authorization: Bearer <access_token>

Merchant

The Merchant endpoint is used primarily to create a new merchant account in CoPilot, using a pre-existing application template that has been created in the CoPilot web interface.

You can also use additional Merchant endpoints to retrieve merchant data, update merchant data, or retrieve the status of a merchant account as outlined below.

ActionMethodPath
Create a Merchant AccountPOST/merchant
Get Merchant DataGET/merchant/{merchantId}
Update Merchant DataPUT/merchant/{merchantId}
Get Merchant StatusGET/merchant/{merchantId}/status

Once the merchant account has been created, additional boarding operations can be performed, such as:

Create a Merchant Account

Use the POST method to create a new merchant account using a pre-existing CoPilot Developer Guides that has been created in the CoPilot web interface. A successful request returns the merchantId property, which is used to identify the account within CoPilot and is used in subsequent API calls for additional boarding operations.

Note that a merchId property also exists within the API. While similar in name, this property represents the front end merchant ID assigned once the account is boarded to the Gateway. This processor-specific merchId is used within the CoPilot API only when creating or managing Billing Plans.

The code example to the right is not representative of a legitimate request as it includes all possible fields, including those that would generate a conflict when creating a merchant.

See the CoPilot Developer Guides to learn about the minimum data requirements and process of creating a new merchant.

MethodPOST
Hosthttps://api-uat.cardconnect.com

Path

/merchant
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0
Content-Type: application/json

Consumesapplication/json
Producesapplication/json

Create Merchant Request Body

FieldSizeTypeRequiredComments
templateId19numberyesThe ID of the application template created within the CoPilot web interface.
merchantn/aobjectyesThe merchant object.
ownerSiteUsern/aobjectnoThe owner site user object is used to create the merchant's CardPointe user. If this is null, a CardPointe user will be created using the ownership fields in the merchant.

Create Merchant Response

FieldSizeTypeComments
merchantId19numberThe merchant ID used to identify the account within CoPilot.
errorsn/aarrayThe errors array containing one or more errors if there was a problem creating the merchant.

Get Merchant Data

Use the GET method to retrieve all merchant account data, such as contact and owner information, business details, processing information, pricing, and fees.

MethodGET
Hosthttps://api-uat.cardconnect.com

Path

/merchant/{merchantId}
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Consumesn/a
Producesapplication/json

Get Merchant Data Request

GET https://api-uat.cardconnect.com/merchant/123456789

Get Merchant Data Response

A successful request returns the following, as shown in the example to the right:

Update Merchant Data

Once a merchant account has been created, use the PUT method to update any account data prior to submitting for digital signing by the merchant.

Updating merchant data is only possible when the account has not yet been submitted for digital signature. Use the Get Merchant Status endpoint to verify that the boardingProcessStatusCd is INPROG. If the boardingProcessStatusCd is OFS, then the account has been submitted for digital signature but has not yet been signed. If that is the case, you must use the Retract Signature endpoint before modifying any account data.

MethodPUT
Hosthttps://api-uat.cardconnect.com

Path

/merchant/{merchantId}
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0
Content-Type: application/json

Consumesapplication/json
Producesapplication/json

Partial Updates

It is necessary to supply all children of an object when updating merchant data. When only one field within an object is supplied, the remaining fields within that object are overwritten with null. Objects omitted from the PUT request retain their values.

As an example, submitting a PUT request that only includes a value for merchant.ownership.driversLicenseNumber within the request body sucessfully sets the new driversLicenseNumber value, and overwrites all other fields within the merchant.ownership object with null. Objects not included in the request, such as the merchant.pricing object, retain their existing values.

Updating the Owner

Updating data within the merchant.ownership.owner object does not automatically update the values in the ownerSiteUser object. Use the GET and PUT methods of the Owner Site User endpoint to check the current values for the ownerSiteUser object and update if necessary.

Update Merchant Data Request Body

FieldSizeTypeRequiredComments
merchantn/aobjectyes

The merchant object.

ownerSiteUsern/aobjectnoThe owner site user object is used to create the merchant's CardPointe user. When null, no changes are made to the owner site user.

Update Merchant Data Response

FieldSizeTypeComments
errorsn/aarrayThe errors array containing one or more errors if there was a problem updating the merchant.

Get Merchant Status

Use the Merchant Status endpoint to retrieve the account boarding and gateway boarding status, as well as the date and time that the account transitioned to a new status.

MethodGET
Hosthttps://api-uat.cardconnect.com

Path

/merchant/{merchantId}/status
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Consumesn/a
Producesapplication/json

Get Merchant Status Request

GET https://api-uat.cardconnect.com/merchant/123456789/status

Get Merchant Status Response

A successful request returns the errors object, as well as the merchantStaus object containing the following fields:

FieldTypeComments
approvedDatetimestringThe date and time the account transitioned to the APPROVED status. The date and time is reported in local time, based on the timezone selected in the CoPilot web interface.
boardedDatetimestringThe date and time the account transitioned to the BOARDED status. The date and time is reported in local time, based on the timezone selected in the CoPilot web interface.
cancelledDatetimestringThe date and time the account transitioned to the CANCELLED status. The date and time is reported in local time, based on the timezone selected in the CoPilot web interface.
declinedDatetimestringThe date and time the account transitioned to the DECLINED status. The date and time is reported in local time, based on the timezone selected in the CoPilot web interface.
liveDatetimestringThe date and time the account transitioned to the LIVE status. The date and time is reported in local time, based on the timezone selected in the CoPilot web interface.
boardingProcessPendingFlgboolean
boardingProcessStatusCd

enumeration

See below
gatewayBoardingStatusCdenumerationSee below

Boarding Process Status Codes

CodeDescription
INPROG

The digital application has not yet been submitted to the merchant for signing. Displayed in the CoPilot web interface as "Not Submitted."

Note: Merchant details can only be added or modified in this state.

OFSThe digital application is awaiting merchant signature. Displayed in the CoPilot web interface as "Pending Signature."
QUALIFYThe digital application is signed and undergoing an inital review before being sent for underwriting. Displayed in the CoPilot web interface as "Qualifying."
UNDERThe application is being reviewed by the Underwriting team. Displayed in the CoPilot web interface as "Underwriting."
DECLINEDThe application has been rejected by the Underwriting team.
BOARDINGThe merchant account is in the process of being boarded to the processing platform.
BOARDEDThe merchant account is successfully boarded to the processing platform.
LIVEThe merchant account is boarded to the processing platform, the CardPointe Gateway, and is receiving deposits.
CANCELLEDThe merchant account is cancelled.

Gateway Boarding Status Codes

CodeDescription
NOT_BOARDEDThe merchant ID is not yet boarded to the CardPointe Gateway.
BOARDEDThe merchant account is boarded to the processing platform and the merchant ID is boarded to the CardPointe Gateway.

Signature

The Signature endpoint is used to provide the digital application to the merchant for signature, view the current status of a digital application that is pending signature, or retract the digital application in order to modify it before the merchant has signed.

Request Signature

Use the PUT request when you are ready to submit the application for the merchant to review and sign. If successful, the response returns a unique URL that can be provided to the owner to review and sign the application digitally.

See the CoPilot Developer Guides to learn about how to track the status of a new account after requesting the link to the digital application.

MethodPUT
Hosthttps://api-uat.cardconnect.com

Path

/merchant/{merchantId}/signature
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0
Content-Type: application/json

Consumesapplication/json
Producesapplication/json

Request Signature Request Body

No request body is required for this endpoint.

Request Signature Response

FieldTypeComments
errorsarrayThe errors array containing one or more errors if there was a problem requesting the signature.
signatureUrlstringThe URL for the digital application that is provided to the merchant.

Get Signature Status

Use the GET request to view the current status of an application that has been submitted to the merchant for signing.

MethodGET
Hosthttps://api-uat.cardconnect.com

Path

/merchant/{merchantId}/signature
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Consumesn/a
Producesapplication/json

Get Signature Status Request

GET https://api-uat.cardconnect.com/merchant/123456789/signature

Get Signature Status Response

A successful request returns the errors object, as well as the signatureStatus object containing the following fields:

FieldTypeComments
signedSiteUserIdnumberThe ID of the owner site user who signed the application.
signedDateTimestringThe date and time the application was signed. The date and time is reported in local time, based on the timezone selected in the CoPilot web interface.
signerobjectThe signer object containing the signer's details.
signatureUrlstringThe URL for the digital application that the signer accessed to complete the digital application.
signatureStatusCdenumerationCan be one of the following:
  • NOT_SENT - No URL for the digital application exists.
  • PENDING - The URL for the digital application exists and is pending completion by the merchant.
  • SIGNED - The digital application has been completed and signed.

Signer Definition

FieldTypeComments
emailstringThe email of the signer.
firstNamestringThe first name of the signer.
lastNamestringThe last name of the signer.
ipAddressstringThe signer's IP address at the time of signing.
personalGuaranteeFlgbooleanTrue when the owner selected the Personal Guarantee option.

Retract Signature

Use the DELETE method to disable the URL that is used by the owner to review and sign the digital application. This reverts the merchant's status to the INPROG state, allowing you to make modifications to the account data.

This method can only be used when the application is pending signature. Use Get Signature Status to verify that the current signature status is PENDING, which indicates that the application has been submitted to the owner for signing, but has not yet been signed.

After updating the account data, use Request Signature to generate a new unique URL that the owner will use to review and sign the digital application.

MethodDELETE
Hosthttps://api-uat.cardconnect.com

Path

/merchant/{merchantId}/signature
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Consumesn/a
Producesapplication/json

Retract Signature Request Body

No request body is required for this endpoint.

Retract Signature Response

FieldTypeComments
errorsobjectThe errors array containing one or more errors if there was a problem

Attachment

The Attachment endpoint allows you to upload documents that may be required before the account can be boarded, such as hard copies of agreements that have been completed and signed by the merchant, or a copy of a voided check. Refer to the Attachment Type Codes to view the various agreements, forms, and documents that can be attached to a merchant account.

MethodPUT
Hosthttps://api-uat.cardconnect.com

Path

/merchant/{merchantId}/attachment
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0
Content-Type: application/json

Consumesapplication/json
Producesapplication/json

Upload Attachment Request Body

FieldSizeTypeRequiredComments
fileName60stringyesThe file name of the attachment.
mimeType30stringyesThe MIME type of the attachment file.
description1000stringyesThe description of the attachment file.
attachmentTypeCdn/astringyesThe attachment type code that represents the type of attachment.
document100mbstringyes

The document to upload, provided as a Base 64 encoded file.

Note: Attach only documents or image files. Audio and video files are not supported.

Upload Attachment Response

FieldTypeComments
errorsarrayThe errors array containing one or more errors if there was a problem uploading the attachment.
attachmentIdnumberThe ID of the attachment for reference.

Equipment Catalog

The Equipment Catalog endpoint provides a list of terminals, gateways, and software available for ordering based on the Sales Code supplied in the query string. Use the endpoint to determine the equipment ID of a add-on to be used in a subsequent call to the Create Order endpoint.

MethodGET
Hosthttps://api-uat.cardconnect.com

Path

/equipmentCatalog/list
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Consumesn/a
Producesapplication/json

Equipment Catalog Request

GET https://api-uat.cardconnect.com/equipmentCatalog/list?salesCode=salescode1&equipmentSupplierCd=CARDCONNECT&equipmentTypeCd=TERMINAL&pageNumber=1&pageSize=2
FieldRequiredComments
salesCodeyesThe Sales Code of the merchant that requires additional equipment.
equipmentSupplierCdnoThe equipment supplier code. Used to return only equipment of a specific supplier.
equipmentTypeCdnoThe equipment type code. Used to return only equipment of a specific type.
pageNumbernoThe number of the page being requested.
pageSizenoThe number of results to limit per page.

Equipment Catalog Response

FieldTypeComments
rowsarrayList of equipment definitions returned as an array of equipment objects.
totalServerItemsCountnumberTotal number of rows.
totalDisplayItemsCountnumberThe total number of rows before and including this page.
moreRowsAvailablebooleanTrue if the are more rows available on the next page.
columnSumsn/aInternal use.
errorsarrayThe errors array containing one or more errors if there was a problem with the request.

Order

The Order endpoint is used primarily to create a new equipment order for a merchant account, using the equipment's equipmentId that can be obtained by calling the Equipment Catalog endpoint.

You can also use additional Order endpoints to retrieve the details of a specific order, update an order, cancel an order, as well as using the list endpoint to retrieve all orders for a merchant account.

ActionMethodPath
Create OrderPOST/order
Get OrderGET/order/{orderId}
List OrdersGET/order/list?merchantId={merchantId}
Update OrderPUT/order/{orderId}
Cancel OrderPOST/order/{orderId}/cancel

Create Order

Use the POST method to create a new equipment order for an existing merchant account. Submitting an order requires equipmentId, which can be obtained by calling the Equipment Catalog endpoint for a list of available equipment and the associated equipment IDs.

When placing an equipment order, the following options are available:

  • Equipment orders may be billed using any of the methods supported by your partner account, such as billing to your partner residuals, partner credit card, or to the customer directly.
  • Billing for equipment can be set as a monthly charge, or an upfront one-time charge.
MethodPOST
Hosthttps://api-uat.cardconnect.com

Path

/order
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0
Content-Type: application/json

Consumesapplication/json
Producesapplication/json

Create Order Request Body

FieldSizeTypeRequiredComments
ordern/aobjectyesThe order object.

Order Definition (Request)

FieldSizeTypeRequiredComments
merchantId19numberyesThe merchant ID associated with the order.
equipmentId19numberyesThe equipment ID of the equipment being ordered.
orderNotes1000stringnoOptional notes for the person fulfilling the order.
quantity4numberyesThe number of devices being ordered.
unitPrice10numberSee commentsThe price per unit. Required only when billToFrequencyCd is ONETIME.
monthlyPrice10numberSee commentsThe price per month. Required only when billToFrequencyCd is MONTHLY.
billToCd100stringyesThe bill to code that represents who is billed for the order.
billingFrequencyCd100stringyesThe billing frequency code that represents the frequency of billing.
profileIdn/astringSee commentsThe CardPointe Gateway profile ID to charge for this order. Required only when billToCd is PARTNERCC.
acctId10numberSee commentsThe account ID of the card within the CardPointe Gateway profile to charge for this order. Required only when billToCd is PARTNERCC.
shippingDetailsn/aobjectyesThe shipping details object.

Create Order Response

FieldTypeComments
orderIdnumberThe ID of the order for reference.
errorsarrayThe errors array containing one or more errors if there was a problem creating the order.

Get Order

Use the GET method to retrieve the details and status of a specific equipment order.

MethodGET
Hosthttps://api-uat.cardconnect.com

Path

/order/{orderId}
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Consumesn/a
Producesapplication/json

Get Order Request

GET https://api-uat.cardconnect.com/order/123456

Get Order Response

FieldTypeComments
orderIdnumberThe order ID used to reference this order.
merchantIdnumberThe merchant ID associated with the order.
equipmentIdnumberThe equipment ID of the equipment ordered.
orderNotesstringOptional notes for the person fulfilling the order.
quantitynumberThe number of devices ordered.
unitPricenumberThe price per unit.
monthlyPricenumberThe price per month.
billToCdstringThe bill to code that represents who is billed for the order.
billingFrequencyCdstringThe billing frequency code that represents the frequency of billing.
profileIdstringThe CardPointe Gateway profile ID charged for this order.
acctIdnumberThe account ID of the card within the CardPointe Gateway profile charged for this order
shippingDetailsstringThe shipping details object.
orderStatusCdstringThe order status code that represents the current status of the order.
placedDatetimestringThe date and time the order was placed. The date and time is reported in local time, based on the timezone selected in the CoPilot web interface.
shippedDatetimestringThe date the order was shipped. The date and time is reported in local time, based on the timezone selected in the CoPilot web interface.
canceledDatetimestringThe date the order was canceled. The date and time is reported in local time, based on the timezone selected in the CoPilot web interface.
fulfillingDatetimestringThe date the order was fulfilled. The date and time is reported in local time, based on the timezone selected in the CoPilot web interface.

List Orders

You can retrieve a list of all orders for a specific merchant account by using the List Orders endpoint.

MethodGET
Hosthttps://api-uat.cardconnect.com

Path

/order/list
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Consumesn/a
Producesapplication/json

List Orders Request

GET https://api-uat.cardconnect.com/order/list?merchantId=123456789&pageSize=2&pageNumber=1
FieldRequiredComments
merchantIdyesThe merchant ID used to identify the account within CoPilot.
pageSizenoThe number of results to limit per page.
pageNumbernoThe number of the page being requested.

List Orders Response

Field

Type

Comments

errors

arrayThe errors array containing one or more errors if there was a problem creating the order.
rowsarray

An array of order objects.

totalServerItemsCountnumberThe total number of rows.
totalDisplayItemsCountnumberThe total number of rows before and including this page.
moreRowsAvailablebooleanTrue if there are more rows available on the next page.
columnSumsn/aInternal use.

Update Order

Use the Update Order endpoint to make changes to an existing order, such as the quantity, price, or the bill to code.

MethodPUT
Hosthttps://api-uat.cardconnect.com

Path

/order/{orderId}
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0
Content-Type:application/json

Consumesapplication/json
Producesapplication/json

Update Order Request Body

FieldSizeTypeRequiredComments
ordern/aobjectyes

The order object.

Note: It is not possible to change merchantId and equipmentId for an existing order.

Update Order Response

FieldTypeComments
errors

array

The errors array containing one or more errors if there was a problem creating the order.

Cancel Order

The Cancel Order endpoint can be used to cancel any order where the orderStatusCd is NEW. Use the Get Order endpoint to verify an order's current status.

MethodPOST
Hosthttps://api-uat.cardconnect.com

Path

/order/{orderId}/cancel
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Consumesn/a
Producesapplication/json

Cancel Order Response

FieldTypeComments
errors

array

The errors array containing one or more errors if there was a problem cancelling the order.

Custom Fields

Custom fields can be enabled for your partner account to include additional merchant data, such as associated account numbers, the account's regional area, or any other type of data that you wish to notate.

You can use the PUT or GET methods to update the custom field values for a merchant, or view the current custom fields configured and the current merchant values. If you need to enable a field, disable it, or change whether the field is required, access the CoPilot web interface to make these changes to your partner account.

Update Custom Fields

Use the PUT method to update the custom field values for a merchant, if custom fields are already configured for your merchant via the CoPiot web interface. If unsure, you can use the GET method to view the currently configured custom fields for your partner account. Custom fields that are enabled and required need to be provided before the account can be submitted for digital signature.

MethodPUT
Hosthttps://api-uat.cardconnect.com

Path

/merchant/{merchantId}/customfields
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0
Content-Type:application/json

Consumesapplication/json
Producesapplication/json

Update Custom Fields Request

FieldSizeTypeRequiredComments
customFieldsn/aarraySee commentsThe custom fields array containing objects for each custom field. Required when one or more custom fields have been configured in the CoPilot web interface as a required field for new merchants.

Update Custom Fields Response

FieldSizeTypeComments
errorsn/aarrayThe errors array containing one or more errors if there was a problem updating the custom fields.

Get Custom Fields

Use the GET method to retrieve the list of custom fields configured for your partner account, the custom fields you have set as required for new merchants, as well as the values currently set for the merchant.

MethodGET
Hosthttps://api-uat.cardconnect.com

Path

/merchant/{merchantId}/customfields
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Consumesn/a
Producesapplication/json

Get Custom Fields Request

GET https://api-uat.cardconnect.com/merchant/123456789/customfields

Get Custom Fields Response

The customFields array that is returned includes additional fields that provide details on the custom fields configured, including whether they are currently active or required fields. Refer to the following table for the extended customFields object that is returned with the GET response.

FieldTypeComments
customFieldLabelstringThe label for this custom field, set via the CoPilot web interface.
isRequirednumberWhen 0, this custom field is configured in the CoPilot web interface as not required.

When 1, this custom field is configured in the CoPilot web interface as required.
isActivenumberWhen 0, this custom field is configured in the CoPilot web interface as inactive.

When 1, this custom field is configured in the CoPilot web interface as active.

userFieldNumbernumberA value from 1-10 that represents this custom field's number and is used as an identifier when updating the value via a PUT request.
customFieldValuestringThe custom field's value currently set for this account, whether set via the CoPilot web interface or via the CoPilot API.

Owner Site User

Owner Site User data is used to create a CardPointe account for the owner when the merchant account is submitted for digital signing. If no ownerSiteUser object was provided when creating a merchant account, the fields are populated using data from the merchant.ownership.owner object. You can use the PUT method to update this data or the GET method to view the current values.

Ensure this information is accurate as the owner uses this account to review and sign the digital application. This CardPointe user account also provides the owner access to the CardPointe Web App to view the status of their application, manage account settings, and later view CardPointe Gateway transactions and reports once boarded to the Gateway.

Update Owner Site User

If the owner has not already registered a CardPointe account with the email address currently specified in the ownerSiteUser object, use the PUT method to update these values. If the owner has already completed the CardPointe user registration process, they must log in to CardPointe in order to update this information.

MethodPUT
Hosthttps://api-uat.cardconnect.com

Path

/merchant/{merchantId}/ownerSiteUser
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0
Content-Type: application/json

Consumesapplication/json
Producesapplication/json

Update Owner Site User Request Body

FieldSizeTypeRequiredComments
ownerSiteUsern/aobjectyesThe owner site user object.

Update Owner Site User Response

FieldTypeComments
errors
arrayThe errors array containing one or more errors if there was a problem updating the owner site user.

Get Owner Site User

Use the GET method to retrieve the current owner site user data for an account.

MethodGET
Hosthttps://api-uat.cardconnect.com

Path

/merchant/{merchantId}/ownerSiteUser
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Consumesn/a
Producesapplication/json

Get Owner Site User Request

GET https://api-uat.cardconnect.com/merchant/123456789/ownerSiteUser

Get Owner Site User Response

FieldTypeComments
ownerSiteUserobjectThe owner site user object.
errors
arrayThe errors array containing one or more errors if there was a problem retrieving the owner site user.

Billing Plan

The Billing Plan endpoints are used to create, manage, and cancel billing plans and scheduled payments. These endpoints can be used in conjunction with, or in place of performing these actions within the Billing Plans page of the CardPointe web interface.

Create Billing Plan

Use the Create Billing Plan endpoint to set up recurring payments using a payment profile created via the CardPointe Gateway API, or using a stored customer profile saved via the Customers page of the CardPointe web interface.

MethodPOST
Hosthttps://api-uat.cardconnect.com

Path

/billingplan/create
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0
Content-Type: application/json

Consumesapplication/json
Producesapplication/json

Create Billing Plan Request Body

FieldSizeType

Required

Comments
billingPlann/aobjectyes

The billing plan object.

Note: Leave the billingPlanId field blank or omit it when creating a new billing plan. The billingPlanId is automatically assigned when the plan is created.

Create Billing Plan Response

FieldTypeComments
billingPlanobjectThe billing plan object.
errorsarrayThe errors array containing one or more errors if there was a problem creating the billing plan.

Get Billing Plan List

Retrieve a list of billing plans already configured for a specific front end MID.

MethodGET
Hosthttps://api-uat.cardconnect.com

Path

/billingplan/list/{merchId}
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Consumesn/a
Producesapplication/json

Get Billing Plan List Request

GET https://api-uat.cardconnect.com/billingplan/list/111111111

Get Billing Plan List Response

FieldTypeComments
billingPlansarray

An array containing a billing plan object for each billing plan configured for the MID.

Note: The schedules field of the billing plan objects returned in the response is always null. To view the billing schedule for a specific plan, use the Get Billing Plan endpoint.

errorsarrayThe errors array containing one or more errors if there was a problem retrieving the list of billing plans.

Get Billing Plan

Use the Get Billing Plan endpoint to retrieve the details of a specific billing plan for a front end MID.

MethodGET
Hosthttps://api-uat.cardconnect.com

Path

/billingplan/{merchId}/{billingPlanId}
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Consumesn/a
Producesapplication/json

Get Billing Plan Request

GET https://api-uat.cardconnect.com/billingplan/111111111/123456

Get Billing Plan Response

FieldTypeComments
billingPlanobjectThe billing plan object.
errors arrayThe errors array containing one or more errors if there was a problem retrieving billing plan.

Update Account

Stored customer profiles or payment profiles created via the CardPointe Gateway API can contain more than one payment method, referred to as a payment account. Use the Update Account endpoint to modify the payment account used for a billing plan.

MethodPOST
Hosthttps://api-uat.cardconnect.com

Path

/billingplan/updateAccount
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0
Content-Type: application/json

Consumesapplication/json
Producesapplication/json

Update Account Request Body

FieldSizeTypeRequiredComments
merchId11stringyesThe front end MID associated with the billing plan.
billingPlanId11stringyesThe ID of the billing plan to update.
profileId20stringyesThe CardPointe Gateway profile ID to use for future billing.
acctId3stringno

The account ID of the card within the CardPointe Gateway profile to use for future billing.

Note: When omitted, the default account is used.

Update Account Response

FieldTypeComments
billingPlanobjectThe billing plan object.
errorsarrayThe errors array containing one or more errors if there was a problem updating the account used for the billing plan.

Mark as Paid

Use the Mark as Paid endpoint to set the status of a scheduled payment as PAID.

MethodPOST
Hosthttps://api-uat.cardconnect.com

Path

/billingplan/markAsPaid
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0
Content-Type: application/json

Consumesapplication/json
Producesapplication/json

Mark as Paid Request Body

FieldSizeTypeRequiredComments
billingPlanScheduleId

11

stringyesThe ID of the scheduled payment to update.
retref13stringno

The retref (or refnum) of a transaction to associate with the payment. This can be left as null if unavailable or in the case of a cash payment. If required, multiple payments may be associated to the same transaction by making multiple calls to this endpoint.

Mark as Paid Response

FieldTypeComments
billingPlanobjectThe billing plan object.
errorsarrayThe errors array containing one or more errors if there was a problem marking the scheduled payment as paid.

Cancel Payment

Use the Cancel Payment endpoint to cancel a scheduled payment within a billing plan. You can use the Get Billing Plan endpoint to view all payment schedules within the plan, the associated billingPlanScheduleId, and confirm that the payment you intend to cancel has a paymentStatus of 'Scheduled.'

MethodPOST
Hosthttps://api-uat.cardconnect.com

Path

/billingplan/cancelPayment
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0
Content-Type: application/json

Consumesapplication/json
Producesapplication/json

Cancel Payment Request Body

FieldSizeTypeRequiredComments
billingPlanScheduleId

11

stringyesThe ID of the scheduled payment to cancel.

Cancel Payment Response

FieldTypeComments
billingPlanobjectThe billing plan object.
errorsarrayThe errors array containing one or more errors if there was a problem cancelling the scheduled payment.

Cancel Billing Plan

Use the Cancel Billing Plan endpoint to end a billing plan and cancel all the remaining payments scheduled.

MethodPOST
Hosthttps://api-uat.cardconnect.com

Path

/billingplan/cancel
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0
Content-Type: application/json

Consumesapplication/json
Producesapplication/json

Cancel Billing Plan Request Body

FieldSizeTypeRequiredComments
merchId11stringyesThe front end MID associated with the billing plan.
billingPlanId11stringyesThe ID of the billing plan to cancel.

Cancel Billing Plan Response

FieldTypeComments
billingPlanobjectThe billing plan object.
errors
arrayThe errors array containing one or more errors if there was a problem cancelling the billing plan.

Schemas

See the schema definitions below to view the fields available for each object within the API.

Additional Owners

FieldSizeTypeRequiredComments
ownerFirstName100stringnoThe owner's first name.
ownerLastName100stringnoThe owner's last name.
ownerPhone12stringnoThe owner's phone number, formatted as ###-###-####.
ownerAddressn/aobjectnoThe address object, containing the owner's address information.
ownerSSN11stringnoThe owner's Social Security Number, formatted as ###-##-####.
ownershipPct3

number

yesThe percentage owned by the owner.

Address Definition

FieldSizeTypeRequiredComments
address1200stringyesThe number and street of the address.
address2200stringno

Any additional address information such as apartment number or suite number of the address.

city300stringyesThe city of the address.
stateCd2stringnoThe state code that represents the US state where the address is located.
zip15stringyesThe ZIP code of the address.
countryCd2stringnoThe country code that represents the country where the address is located.

Attachment Definition

FieldSizeTypeRequiredComments
fileName60stringyesThe file name of the attachment.
mimeType30stringyes

The MIME type of the attachment file.

description1000stringyesThe description of the attachment file. 
attachmentTypeCdn/astringyesThe attachment type code that represents the type of attachment.
document100Mbstringyes

The document to upload, provided as a Base 64 encoded file.

Note: Attach only documents or image files. Audio and video files are not supported.

Bank Definition

FieldSizeTypeRequiredComments
bankAcctNum25stringyesThe bank account number.
bankRoutingNum9stringyesThe bank account's routing number.
bankAcctTypeCd10stringyesThe bank account type code that represents the type of bank account.
bankName200stringyesThe name of the bank that holds the account.

Bank Detail Definition

FieldSizeTypeRequiredComments
depositBankn/aobjectyesThe bank object containing the account details used when depositing funds.
withdrawalBankn/aobjectyesThe bank object containing the account details used when withdrawing funds.

Billing Plan Definition

FieldSizeTypeRequiredComments
billingPlanId11

string

no

The unique identifier for the billing plan, generated at the time of creation. Required to update or cancel a billing plan.

Note: Leave this field blank or omit it when creating a new billing plan. The billingPlanId is automatically assigned when the plan is created.

merchId11stringyesThe front end MID associated with the billing plan.
profileId20stringyesThe CardPointe Gateway profile ID to charge for this order.
acctId3stringnoThe account ID of the card within the CardPointe Gateway profile to charge for this order. When not provided, the default account is used. This field is always returned when retrieving a billing plan.
amountnumberyesThe amount to bill for each scheduled payment.
timeSpan1numberyesThe billing frequency, represented as 1 for daily, 2 for weekly, 3 for monthly, or 4 for yearly.
every1numberyesThe billing interval, where 1 represents every period specified in the timeSpan field, and 2 represents every other period specified in the timeSpan field.
untilCondition1stringyesThe condition that ends the billing plan, where C is until cancelled, N is until a number of payments are made, or D to end the billing plan on a specific date.
untilNumPaymentsnumberSee CommentsThe number of payments required to automatically end the billing plan. Required when untilCondition = N.
untilDate8stringSee CommentsThe date the billing plan ends, formatted as MMDDYYYY. Required when untilCondition = D.
currencySymbol1stringyesThe currency symbol for the transaction.
startDate8stringyesThe date the billing plan begins, formatted as MMDDYYYY.
billingPlanName30stringyesThe name used to distinguish the billing plan from other billing plans.
optionsarrayyesThe email_receipt option should be provided with a value of 0 for no or 1 for yes. See example JSON.
planSatus1stringnoThe billing plan status, where A represents an active plan and C represents a cancelled plan. This cannot be set, and is only returned when fetching a billing plan.
schedulesarrayno

An array of billing plan schedules for each of the payments in the billing plan. This cannot be set, and is only returned when fetching a billing plan. This array will always contain all past payments. In addition, it will also contain future scheduled payments (up to 1000 when untilCondition = N or D, or one year of payments when untilCondition = C)

Note: This field is always null for billing plan objects returned in the Get Billing Plan List response. To view the billing schedule for a specific plan, use the Get Billing Plan endpoint.

Billing Plan Schedule Definition

FieldSizeTypeRequiredComments
billingPlanScheduleIdnumberyesThe id of the billing plan schedule entry.
actualAmountnumbernoThe amount that was actually billed, if the payment was processed.
actualPaymentDatestringnoThe date this payment was made, if it was processed.
paymentStatusstringyesThe payment status, such as Scheduled, Cancelled, Paid, or Failed.
retrefstringnoThe transaction id, if the payment was processed.
scheduledAmountnumberyesThe amount scheduled to be billed.
scheduledPaymentDatestringyesThe date scheduled for this payment.

BlueChex Volume Definition

The blueChexVolume object is required for merchants with the ACH from Fiserv add-on. All fields must be provided.

FieldSizeTypeComments
averagePerTransactionSalesAmount18.2numberThe average sales amount per ACH transaction.
maxPerTransactionSalesAmount18.2numberThe maximum sales amount per ACH transaction.
averagePerTransactionCreditAmount18.2numberThe average credit (refund) amount per ACH transaction.
maxPerTransactionCreditAmount18.2numberThe maximum credit (refund) amount per ACH transaction.
averagePerMonthSalesAmount18.2numberThe average monthly sales amount for all ACH transactions.
maxPerMonthSalesAmount18.2numberThe maximum monthly sales amount for all ACH transactions.
averagePerMonthCreditAmount18.2numberThe average monthly credit (refund) amount for all ACH transactions.
maxPerMonthCreditAmount18.2numberThe maximum monthly credit (refund) amount for all ACH transactions.

BlueChex SEC Options Definition

FieldSize

Type

RequiredComments
telSecOptionFlg

n/a

booleanSee comments

Telephone-Initiated Entry: A single entry debit application initiated by an originator pursuant to an oral authorization obtained over the telephone to effect a transfer of funds from an account of the receiver.

Note: At least one SEC Option required for applications that include the ACH from Fiserv add-on for manual signature.

ccdSecOptionFlgn/abooleanSee comments

Cash Concentration and Disbursement: A credit or debit application where funds are transferred between unrelated corporate entities or transmitted as intra-company concentrations and disbursement transactions. Serves as stand-alone funds transfer, or it can support a limited amount of payment-related data with the fund's transfer.

Note: At least one SEC Option required for applications that include the ACH from Fiserv add-on for manual signature.

webSecOptionFlgn/abooleanSee comments

Internet-Initiated Entry: Debit applications initiated by an originator pursuant to an authorization from the receiver via the internet to effect a transfer of funds from an account of the receiver.

Note: At least one SEC Option required for applications that include the ACH from Fiserv add-on for manual signature.

ppdSecOptionFlgn/abooleanSee comments

Prearranged Payment and Deposit: Both direct payments and direct deposits.

Note: At least one SEC Option required for applications that include the ACH from Fiserv add-on for manual signature.

Business Details Definition

FieldSizeTypeRequiredComments
customerBillPriorToShipFlgn/abooleannoTrue if the customer is billed prior to shipment.
depositReqForFulfillFlgn/abooleannoTrue if deposit is required for order fulfillment.
whenCustomerChargedCd10stringnoThe when customer charged code that represents when the customer is charged.
refundPolicyCd10stringnoThe refund policy code that represents the customer's refund policy.
serviceProvidedInCd10stringnoThe service provided in code that represents the typical timeframe between purchase and delivery.

Clover Security and TransArmor Definition

FieldSizeTypeRequiredComments
transarmorDataProtectionFlgn/abooleanno

True if TransArmor Data protection is active.

Requires FALSE when cloverSecurityBundleCd = PCI.

transarmorTokenTypeCdn/astringSee commentsThe TransArmor token type code that represents the token type. Required when transarmorDataProtectionFlg = TRUE.
transarmorMultiPayToken4stringSee commentsThe TransArmor multi-pay token. Required when transarmorTokenTypeCd = MULTI.
transarmorMonthyFee7.2numberSee comments

The Monthly TransArmor Fee amount.

Required when transarmorDataProtectionFlg = TRUE.

cloverSecurityBundleCd

n/a

stringno

Note: Only applicable for merchants with a Clover Security Bundle.

The Clover security bundle code that represents the applicable bundle.

cloverSecurityFeen/anumberSee comments

Note: Only applicable for merchants with a Clover Security Bundle.

The Monthly Clover Security Fee amount.

Required when cloverSecurityBundleCd = TDPPCI.

cloverSecurityPlusFeen/anumberSee comments

Note: Only applicable for merchants with a Clover Security Bundle.

The Monthly Clover Security Plus Fee amount.

Required when cloverSecurityBundleCd = CSPFB.

pciComplianceServiceFeen/anumberSee comments

Note: Only applicable for merchants with a Clover Security Bundle.

The PCI Compliance Service Fee.

Required when cloverSecurityBundleCd = PCI.

pciComplianceServiceFeeFrequency7stringSee comments

Note: Only applicable for merchants with a Clover Security Bundle.

The frequency to bill the PCI Compliance Service Fee. Can be either MONTHLY or ANNUAL.

Required when cloverSecurityBundleCd = PCI.

pciComplianceServiceFeeMonthToBilln/astringSee comments

Note: Only applicable for merchants with a Clover Security Bundle.

The month to bill the PCI Compliance Service Fee, starting with a capital letter.

Required when pciComplianceServiceFeeFrequency = ANNUAL.

Contact Info Definition

FieldSizeTypeRequiredComments
contactName300stringnoThe full name of the contact.
contactEmail300stringnoThe email address of the contact.
contactPhone12stringnoThe phone number of the contact, formatted as ###-###-####.

Custom Fields Definition

FieldSizeTypeRequiredComments
userFieldNumbern/anumberyesThe index number of the custom field. Must be a number between 1-10.
customFieldValue100stringyesRequired when the userFieldNumber is marked as required in the CoPilot web interface.

Delivery Percentages Definition

FieldSizeTypeRequiredComments
dlvry0To7DaysPct3numbernoThe percentage of products or services delivered within 7 days of purchase, represented as a whole number.
dlvry8To14DaysPct3numbernoThe percentage of products or services delivered within 8-14 days of purchase, represented as a whole number.
dlvry15To30DaysPct3numbernoThe percentage of products or services delivered within 15-30 days of purchase, represented as a whole number.
dlvryOver30DaysPct3numbernoThe percentage of products or services delivered more than 30 days after purchase, represented as a whole number.

Demographic Definition

FieldSizeTypeRequiredComments
businessIncorporatedStateCd2stringnoThe state code where the business is incorporated.
merchantTimeZone3stringnoThe 2 or 3 character time zone, such as ET, CT, MT, PT or HST.
websiteAddress200stringyesBusiness website is required if merchant.processing.modeOfTransaction.eCommercePct is greater than 0.
businessPhone12stringnoThe business phone number, formatted as ###-###-####.
businessFax12stringnoThe business fax number, formatted as ###-###-####.
businessAddressn/aobjectyesThe address object, containing the business address.
mailingAddressn/aobjectyesThe address object, containing the business mailing address.

Equipment Definition

FieldSizeTypeComments
equipmentId60numberThe unique identifier for this piece of equipment.
equipmentName60stringThe name for this piece of equipment.
description60stringThe description for this piece of equipment.
make60stringThe manufacturer for this piece of equipment.
model60stringThe model name for this piece of equipment.
imageUrl60stringThe URL for the image representing this piece of equipment.
sku60string

The SKU for this piece of equipment.

platformCd60stringThe platform for this piece of equipment.
equipmentTypeCd60stringThe equipment type code representing the type or category of this piece of equipment.
equipmentSupplierCd60stringThe equipment supplier code representing the provider of this piece of equipment.
defaultPrice60stringThe default one-time price.
defaultPlanPrice60stringThe default monthly price, if allowed.
allowCustomBillingFlg60stringTrue if monthly billing is allowed.
standardShippingPrice60stringThe standard shipping price per unit.
expeditedShippingPrice60stringThe expedited shipping price per unit.

Fees Definition

FieldSizeTypeRequiredComments
achBatchFee7.3numberyesThe ACH Batch Fee.
addressVerifFee7.3numberyesThe Address Verification Fee (AVS).
annualMembershipFee8.2numberyesThe Annual Membership Fee.
appFee8.2numberyesThe Application Fee (One Time).
authFee7.3numberyesThe Authorization Fees (All Card Types).
chargebackFee8.2numberyesThe Chargeback Fee (Per Item).
ddaRejectFee8.2numberyesThe DDA Rejects (Per Item).
earlyCancelFee8.2numberyesThe Early Termination Fee.
minProcessFee8.2numberyesThe Minimum Processing Fee (Monthly).
monthlyEquipmentRentalFee8.2numbernoThe Equipment Rental Fee (Monthly).
pciAnnualFee8.2numbernoThe PCI Annual Fee, applicable when pciProgramCd is ANNUAL.
pciConciergeMonthlyFee8.2numbersee comments

The PCI Concierge Monthly Fee.

Required to submit merchants when pciProgramCd is CONCIERGE.

pciNonComplianceFee8.2numbernoThe PCI Non-Compliance Fee (Monthly), applicable when pciProgramCd is ANNUAL.
pciProgramCd10stringyesThe PCI Program Code that identifies the merchant's PCI Program. 
regProdMonthlyFee8.2numberyesThe Regulatory Product Fee (Monthly).
retrievalFee8.2numberyesThe Retrieval Fee (Per Item).
statementFee8.2numberyesThe Statement Fee (Monthly).
transactionFee7.3numberyesThe Transaction Fees (All Card Types).
voiceAuthFee7.3numberyesThe Voice Authorization Fee.
wirelessActivationFee8.2numberyesThe Wireless Activation Fee (One Time).
wirelessFee8.2numberyesThe Wireless Fee (Monthly).
duesAndAssessmentsFlgn/abooleannoTrue if Dues & Assessments is enabled.
passthruInterchgCostsFlgn/abooleannoReturned only for accounts created prior to the introduction of the interchangeTypeCode field in the 5/5/20 update. True when the account using the IC Plus Pricing model.

Flat Pricing Definition

FieldSizeTypeRequiredComments
amex.esaQualDiscountPct7.3numberSee commentsThe percentage used to calculate the Amex ESA Qualified Credit Discount Fees. Required when amexProgramAssetCd = ESA.
amex.optBlueQualDiscountPct7.3number

See comments

The percentage used to calculate the Amex OptBlue Qualified Credit Discount Fees. Required when amexProgramAssetCd = OPTBLUE.
discover.qualCreditDiscountPct7.3number

See comments

The percentage used to calculate the Discover Qualified Credit Discount Fees. Required when Discover entitlement is enabled..
mastercard.qualCreditDiscountPct7.3numberyesThe percentage used to calculate the Mastercard Qualified Credit Discount Fees.
visa.qualCreditDiscountPct7.3numberyesThe percentage used to calculate the Visa Qualified Credit Discount Fees.

Hierarchy Definition

FieldSizeTypeRequiredComments
corpLevel12stringnoThe Corporate Chain used to associate merchant accounts.
chainLevel12stringnoThe Chain Level used to link merchant accounts for reporting, statement, or financial rollup.
sponsorBankCd5stringnoThe Sponsor Bank code for merchant accounts using the FD North backend. Enter WELLS for Wells Fargo or BBVA for BBVA.

IC-Plus Pricing Definition

FieldSizeTypeRequiredComments
interchangeTypeCode5stringnoThe interchange type code that represents the Passthrough Interchange Costs calculation used.
amex.optBlueQualDiscountPct7.3numberSee commentsThe percentage used to calculate the Amex OptBlue Qualified Credit Discount Fees. Required when amexProgramAssetCd = OPTBLUE.
discover.qualCreditDiscountPct7.3number

See comments

The percentage used to calculate the Discover Qualified Credit Discount Fees. Required when Discover entitlement is enabled.
mastercard.qualCreditDiscountPct7.3numberyesThe percentage used to calculate the Mastercard Qualified Credit Discount Fees.
visa.qualCreditDiscountPct7.3numberyesThe percentage used to calculate the Visa Qualified Credit Discount Fees.

Merchant Definition

FieldSizeTypeRequiredComments
salesCode25stringyesThe Sales Code created within the CoPilot web interface that is applicable for this merchant account.
akaBusinessName200stringnoThe 'Also Known As' business name, such as an informal or shorthand moniker of the legal or DBA name.
dbaName100stringyesThe 'Doing Business As' name, sometimes referred to as the 'Fictitious Business Name' or 'Assumed Business Name' that is legally registered.
legalBusinessName500stringyesThe full legal name of the registered business.
taxFilingName500stringyesThe business name used in tax filing. Include only the following special characters: &, -
taxFilingMethod3stringyesThe method used to identify the business for tax filing. Can be either EIN or SSN. Only the SSN method is possible when merchant.ownership.ownershipType is INDIVSOLE.
businessStartDate8stringnoThe business inception date, formatted as MM/DD/YYYY.
businessIdTypeCd7stringnoThe business identification type code, used to verify the business. Can be either ARTICLE or GOVT.
custPrimaryAcctFlgn/abooleannoTrue when the account is considered the primary account among linked MIDs.
webLeadFlgn/abooleannoTrue when this merchant account is created as the result of an unsolicited merchant inquiry using a hosted web form or a similar lead generation strategy.
hierarchyn/aobjectnoThe hierarchy object, containing custom hierarchy information for this merchant.
demographicn/aobjectyesThe demographic object, containing business information.
ownershipn/aobjectyesThe ownership object, containing ownership information for this merchant account.
bankDetailn/aobjectyesThe bank detail object, containing the depositBank and withdrawalBank objects.
merchantContactInfon/aobjectnoThe contact info object, containing contact information for this merchant account.
processingn/aobjectnoThe processing object, containing various data and options necessary for payment processing. 
pricingn/aobjectnoThe pricing object, containing the pricing structure used for this merchant account.
feesn/aobjectnoThe fees object, containing the fee structure used for this merchant account.
cloverSecurityAndTransarmorn/aobject

no

The Clover security and TransArmor object, containing applicable Clover Security Bundle information and TransArmor Data Protection settings.
customFields10arrayyesThe custom fields array, containing an object for each custom field object. Required when one or more custom fields have been configured in the CoPilot web interface as a required field for new merchants.

Mode of Transaction Definition

FieldSizeTypeRequiredComments
eCommercePct3numberyesThe percentage of card-not-present transactions accepted via eCommerce solutions, represented as a whole number.
keyedPct3numberyesThe percentage of card-not-present transactions entered manually using a hardware terminal keypad or the Virtual Terminal, represented as a whole number.
mailOrderPct3numberyesThe percentage of card-not-present transactions accepted via a call center, represented as a whole number.
swipedPct3numberyesThe percentage of card-present transactions accepted via hardware terminals, represented as a whole number.

Order Definition (Response)

FieldSizeTypeRequiredComments
orderId19numbernoThe unique ID used to identify this order. This value is only returned via a GET request, and cannot be set.
merchantId19numberyesThe merchant ID associated with this order.
equipmentId19numberyesThe equipment ID of the equipment ordered.
orderNotes1000stringnoOptional notes for the person fulfilling the order.
quantity4numberyesThe number of devices ordered.
unitPrice10numberyes (when billToFrequencyCd is ONETIME)The price per unit.
monthlyPrice10numberyes (if billToFrequencyCd is MONTHLY)The price per month.
billToCd100stringyesThe bill to code that represents who is billed for the order.
billingFrequencyCd100stringyesThe billing frequency code that represents the frequency of billing.
profileIdn/astringyes (if billToCd is PARTNERCC)The CardPointe Gateway profile ID charged for this order.
acctId10numberyes (if billToCd is PARTNERCC)The account ID of the card within the CardPointe Gateway profile charged for this order.
shippingDetailsn/aobjectyesThe shipping details object.
orderStatusCdn/astringnoThe order status code that represents the current status of the order.
placedDatetimen/astringnoThe date and time the order was placed. The date and time is reported in local time, based on the timezone selected in the CoPilot web interface.
shippedDatetimen/astringnoThe date and time the order was shipped. The date and time is reported in local time, based on the timezone selected in the CoPilot web interface.
canceledDatetimen/astringnoThe date and time the order was canceled. The date and time is reported in local time, based on the timezone selected in the CoPilot web interface.
fulfillingDatetimen/astringnoThe date and time the order was fulfilled. The date and time is reported in local time, based on the timezone selected in the CoPilot web interface.

Owner Definition

FieldSizeTypeRequiredComments
ownerAddressn/astringyesThe address object, containing the owner's address information.
ownerEmail300stringyesThe email address of the owner.
ownerName300stringyes

The first and last name of the owner.

Note: Do no include title, middle name, or suffix. First name must contain only characters. Last name must not contain more than 1 hyphen or 1 apostrophe.

ownerDob8stringnoThe date of birth of the owner, formatted as MM/DD/YYYY.
ownerPhone12stringyesThe phone number of the owner, formatted as ###-###-####.
ownerMobilePhone12stringyesThe mobile phone number of the owner, formatted as ###-###-####.
ownerSSN11stringyesThe Social Security Number of the owner, formatted as ###-##-####.
ownerTitle200stringyesOne of the Valid Owner Titles listed below.

Valid Owner Titles

Ownership TypeValid Owner Titles
PRTNRSHP (Partnership)
  • PARTNER
GOVT (Government)
  • OWNER
  • PARTNER
  • PRESIDENT
  • VICE_PRESIDENT
  • MEMBER_LLC
  • SECRETARY
  • TREASURER
  • CEO
  • CFO
  • COO
PUBCORP (Public Corporation)
  • PRESIDENT
  • VICE_PRESIDENT
  • SECRETARY
  • TREASURER
  • CEO
  • CFO
  • COO
LLC (LLC)
  • PRESIDENT
  • VICE_PRESIDENT
  • SECRETARY
  • TREASURER
  • CEO
  • CFO
  • COO
  • MEMBER_LLC
PRIVCORP (Private Corporation)
  • PRESIDENT
  • VICE_PRESIDENT
  • SECRETARY
  • TREASURER
  • CEO
  • CFO
  • COO
TAXEXMPT (Tax Exempt)
  • OWNER
  • PARTNER
  • PRESIDENT
  • VICE_PRESIDENT
  • MEMBER_LLC
  • SECRETARY
  • TREASURER
  • CEO
  • CFO
  • COO
NONPRFT (Non-Profit Org)
  • OWNER
  • PARTNER
  • PRESIDENT
  • VICE_PRESIDENT
  • MEMBER_LLC
  • SECRETARY
  • TREASURER
  • CEO
  • CFO
  • COO
INDIVSOLE (Individual / Sole Proprietor)
  • OWNER

Owner Site User Definition

FieldSizeTypeRequiredComments
firstName300stringyesThe first name of the CardPointe user.
lastName300stringyesThe last name of the CardPointe user.
email300stringyesThe email address used to create the CardPointe User.

Ownership Definition

FieldSizeTypeRequiredComments
ownern/aobjectyesThe owner object, containing information about the owner.
additionalOwnersn/a

array

noAn array of additional owner objects containing one object for each additional owner.
ownershipTypeCd10stringnoThe ownership type code that represents the business entity.
publiclyTradedFlagn/abooleannoTrue when the business offers public stock on the NYSE or NASDAQ stock exchanges.
stockSymbol10stringnoThe NYSE or NASDAQ stock symbol of the business.
driversLicenseNumber100stringyesThe primary owner's state issued driver's license number.
driversLicenseStateCd2stringyesThe state code that represents the state who issued the driver's license.
ownerOwnershipPct3numbernoThe percentage of ownership held by the primary owner. 

Platform Details Definition

FieldSizeTypeRequiredComments
backEndMid25stringSee commentsThe settlement processor merchant ID. Required for CardPointe-only accounts.
frontEndMid25stringSee commentsThe authorization processor merchant ID. Required for CardPointe-only accounts.
processorReportingMid25stringSee commentsThe processor merchant ID used for reporting. Required for CardPointe-only accounts.
backEndPlatformCd20stringSee commentsThe back end platform code that represents the settlement processor. Required for CardPointe-only accounts.
frontEndPlatformCd20stringSee commentsThe front end platform code that represents the authorization processor. Required for CardPointe-only accounts.
amexProgramAssetCd7stringSee commentsThe Amex program asset code that represents the American Express program used. Required when Amex entitlement is enabled.
amexProgramMid25stringSee commentsThe Amex merchant ID used to process American Express transactions. Required when amexProgramAssetCd = ESA.
discoverMid25string

See comments

The Discover merchant ID used to process Discover transactions. Required when discoverProgramCd = EASI.
discoverProgramCd10string

See comments

The Discover program code that represents the Discover program used. Required when Discover entitlement is enabled.
incrementalAuthorizationFlgn/abooleanno

True when the account operates within the travel and entertainment industries and requires multiple incremental authorizations.

Note: Requires Discover entitlement and compatible MCC.

debtRepaymentProgramFlgn/abooleanno

True when the account accepts payments to satisfy a loan, mortgage, or other debt.

Note: Requires Discover MAP entitlement and compatible MCC.

acquiringFlgn/abooleanyesTrue when the account is a Merchant Services account. False when the account is a CardPointe-only account.
taxId9

string

noThe merchant's Social Security Number or Employer Identification Number.
tid30stringno
busnsId18stringnoThe merchant's government-issued business license number.
busnsIdPlaceOfIssue2stringyesThe state code that represents the state who issued the business license.
currencyCode5stringnoThe currency code that represents the local currency where the business is located.
mccId5stringyesThe Merchant Category Code (MCC) that represents the business industry.
businessDescription4000stringyesThe description of the business.
iataCode8stringno

The International Air Transportation Association (IATA) code for the business.

quasiCashFlg

n/a

booleannoTrue for accounts that accept Quasi Cash transactions.

Pricing Definition

FieldSizeTypeRequiredComments
flatPricingn/a

object

yesThe flat pricing object containing the pricing structure. 
FieldSizeTypeRequiredComments
icPlusPricingn/aobjectyesThe IC-Plus pricing object containing the containing the pricing structure.

Processing Definition

FieldSizeTypeRequiredComments
platformDetailsn/aobjectyesThe platform details object containing platform processing information.
businessDetailsn/aobjectyesThe business details object containing business policy information.
volumeDetailsn/aobjectyesThe volume details object containing transaction volume information.
deliveryPercentagesn/aobjectnoThe delivery percentages object containing days until delivery information.
modeOfTransactionn/aobjectnoThe mode of transaction object containing transaction mode information.
blueChexVolumen/aobjectSee commentsThe BlueChex volume object containing ACH transaction volume data. Required for applications that include the ACH from Fiserv add-on and a digital signature.
blueChexSecOptionsn/aobjectSee commentsThe BlueChex SEC Options object containing SEC Option Flags. At least one SEC Option required for applications that include the ACH from Fiserv add-on for manual signature.

Shipping Details Definition

FieldSizeTypeRequiredComments
shippingAddressn/aobjectyesThe address object containing the shipping address.
shipToAttn100stringyesThe name of the person receiving the order.
shipToAttnEmail100stringyesThe email address of the person receiving the order.
shippingMethodCd100stringyesThe shipping method code that represents the shipping method used.
shippingBillToCd100stringSee commentsThe bill to code that represents who is billed for the shipping charges. Only required if shippingMethodCd = EXPEDITED.
shippingCarrierCd100stringnoThe shipping carrier code that represents the shipping provider used.
trackingNumber100stringnoThe tracking number of the shipment.
shippingCostn/anumbernoThe shipping cost.
merchantContactPhone12stringyesThe merchant phone number, formatted as ###-###-####.
merchantContactPhoneExt5stringnoThe merchant phone number extension.
poNumber30stringnoThe purchase order number.

Swipe/Non-Swipe Pricing Definition

FieldSizeTypeRequiredComments
swipedDiscountPctnumberyesThe percentage used to calculate the Credit Discount Fees for Visa, Mastercard, Discover Full Service, PIN Debit, PINless Debit, Star Access, and Amex OptBlue transactions when card data is captured from MSR (swiped) or EMV (dipped). Sales volume only. 
swipedTransactionFeenumberyesThe transaction fee applied for Visa, Mastercard, Discover Full Service, Star Access, and Amex OptBlue transactions when card data is captured from MSR (swiped) or EMV (dipped). Sales count only.
nonSwipedDiscountPctnumberyesThe percentage used to calculate the Credit Discount Fees for Visa, Mastercard, Discover Full Service, Star Access, and Amex OptBlue transactions when card data is entered manually. Sales volume only.
nonSwipedTransactionFeenumberyesThe transaction fee applied for Visa, Mastercard, Discover Full Service, Star Access, and Amex OptBlue transactions when card data is entered manually. Sales count only.

Volume Details Definition

FieldSizeTypeRequiredComments
averageMonthlyVolume18.2decimalyesThe average monthly volume of transactions for this merchant.
highTicketAmount18.2decimalyesThe most expensive transaction total expected for this merchant.
averageTicketAmount18.2decimalyesThe average transaction total per sale for this merchant.

Enumeration

Amex Program Asset Codes

Method

GET
Hosthttps://api-uat.cardconnect.com
Path/lookup/amexProgramAssetCodes
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Bodynone
ConsumesN/A
Producesapplication/json

Attachment Type Codes

Method

GET
Hosthttps://api-uat.cardconnect.com
Path/lookup/attachmentTypeCodes
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Bodynone
ConsumesN/A
Producesapplication/json

Back End Platform Codes

Method

GET
Hosthttps://api-uat.cardconnect.com
Path/lookup/backEndPlatformCodes
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Bodynone
ConsumesN/A
Producesapplication/json

Bank Account Types

Method

GET
Hosthttps://api-uat.cardconnect.com
Path/lookup/bankAcctTypes
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Bodynone
ConsumesN/A
Producesapplication/json

Bill To Codes

Method

GET
Hosthttps://api-uat.cardconnect.com
Path/lookup/billToCodes
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Bodynone
ConsumesN/A
Producesapplication/json

Bill To Detail Codes

Method

GET
Hosthttps://api-uat.cardconnect.com
Path/lookup/billToDetailCodes
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Bodynone
ConsumesN/A
Producesapplication/json

Billing Frequency Codes

Method

GET
Hosthttps://api-uat.cardconnect.com
Path/lookup/billingFrequencyCodes
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Bodynone
ConsumesN/A
Producesapplication/json

Clover Security Bundle Codes

Method

GET
Hosthttps://api-uat.cardconnect.com
Path/lookup/cloverSecurityBundleCodes
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Bodynone
ConsumesN/A
Producesapplication/json

Country Codes

Method

GET
Hosthttps://api-uat.cardconnect.com
Path/lookup/countryCodes
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Bodynone
ConsumesN/A
Producesapplication/json

Discover Program Codes

Method

GET
Hosthttps://api-uat.cardconnect.com
Path/lookup/discoverProgramCodes
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Bodynone
ConsumesN/A
Producesapplication/json

Equipment Supplier Codes

Method

GET
Hosthttps://api-uat.cardconnect.com
Path/lookup/equipmentSupplierCodes
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Bodynone
ConsumesN/A
Producesapplication/json

Equipment Type Codes

Method

GET
Hosthttps://api-uat.cardconnect.com
Path/lookup/equipmentTypeCodes
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Bodynone
ConsumesN/A
Producesapplication/json

Front End Platform Codes

Method

GET
Hosthttps://api-uat.cardconnect.com
Path/lookup/frontEndPlatformCodes
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Bodynone
ConsumesN/A
Producesapplication/json

Interchange Type Codes

Method

GET
Hosthttps://api-uat.cardconnect.com
Path/lookup/interchangeTypeCodes
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Bodynone
ConsumesN/A
Producesapplication/json

Order Status Codes

Method

GET
Hosthttps://api-uat.cardconnect.com
Path/lookup/orderStatusCodes
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Bodynone
ConsumesN/A
Producesapplication/json

Ownership Types

Method

GET
Hosthttps://api-uat.cardconnect.com
Path/lookup/ownershipTypes
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Bodynone
ConsumesN/A
Producesapplication/json

PCI Program Codes

Method

GET
Hosthttps://api-uat.cardconnect.com
Path/lookup/pciProgramCodes
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Bodynone
ConsumesN/A
Producesapplication/json

Refund Policy Codes

Method

GET
Hosthttps://api-uat.cardconnect.com
Path/lookup/refundPolicyCodes
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Bodynone
ConsumesN/A
Producesapplication/json

Service Provided In Codes

Method

GET
Hosthttps://api-uat.cardconnect.com
Path/lookup/serviceProvidedInCodes
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Bodynone
ConsumesN/A
Producesapplication/json

Shipping Carrier Codes

Method

GET
Hosthttps://api-uat.cardconnect.com
Path/lookup/shippingCarrierCodes
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Bodynone
ConsumesN/A
Producesapplication/json

Shipping Method Codes

Method

GET
Hosthttps://api-uat.cardconnect.com
Path/lookup/shippingMethodCodes
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Bodynone
ConsumesN/A
Producesapplication/json

State Codes

Method

GET
Hosthttps://api-uat.cardconnect.com
Path/lookup/stateCodes
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Bodynone
ConsumesN/A
Producesapplication/json

TransArmor Token Type Codes

Method

GET
Hosthttps://api-uat.cardconnect.com
Path/lookup/transarmorTokenTypeCodes
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Bodynone
ConsumesN/A
Producesapplication/json

When Customer Charged Codes

Method

GET
Hosthttps://api-uat.cardconnect.com
Path/lookup/whenCustomerChargedCodes
HeadersAuthorization: Bearer

X-CopilotAPI-Version: 1.0

Bodynone
ConsumesN/A
Producesapplication/json

Errors

When there is an error in the request, there will be a non-null errors array in the response body. If there are multiple field validation errors, there will be multiple error objects in the errors array. See the example below.

Errors Definition

FieldTypeComments
codeStringThe error code
messageStringThe error message
errorFieldStringThe field that caused the error
statusStringThe HTTP Status Code