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).
This release contains the following updates:
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.
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.
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.
Authorization: Bearer accessTokenValue
Content-type: application/json
X-CopilotAPI-Version: 1.0
In addition to this API documentation, the following resources are available to help you get started:
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.
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.
See Running the API in Postman in the CoPilot Developer Guides for more information on using the Postman Collection.
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:
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.access_token or refresh_token in client-side applications.| Method | POST |
| Host | https://accountsuat.cardconnect.com |
| Path | /auth/realms/cardconnect/protocol/openid-connect/token |
| Headers | Content-Type: application/x-www-form-urlencoded |
| Consumes | application/x-www-form-urlencoded |
| Produces | application/json |
| Field | Required | Default Value | Comments |
|---|---|---|---|
| username | yes | Your CoPilot username. | |
| password | yes | Your CoPilot password. | |
| grant_type | yes | password | |
| client_id | yes | merchapi | |
| client_secret | yes | CoPilot API registration is required in order to receive your client_secret. |
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.
| Field | Type | Comments |
|---|---|---|
access_token | string | The access token value to be used with the Bearer Authentication scheme for subsequent calls to the API. |
| expires_in | number | The number of seconds until the access token is no longer valid. |
| refresh_expires_in | number | The number of seconds until the refresh token is no longer valid. |
| refresh_token | string | The refresh token used to request a new access token. |
| token_type | string | The type of token provided. A successful request returns a bearer token. |
| not-before-policy | number | When appliciable, restricts authentication prior to the timestamp value. |
| session_state | string | The session state string. |
| scope | string | The 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>
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.
| Action | Method | Path |
|---|---|---|
| Create a Merchant Account | POST | /merchant |
| Get Merchant Data | GET | /merchant/{merchantId} |
| Update Merchant Data | PUT | /merchant/{merchantId} |
| Get Merchant Status | GET | /merchant/{merchantId}/status |
Once the merchant account has been created, additional boarding operations can be performed, such as:
Use the POST method to create a new merchant account using a pre-existing application template 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.
| Method | POST |
| Host | https://api-uat.cardconnect.com |
Path | /merchant |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Consumes | application/json |
| Produces | application/json |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| templateId | 19 | number | yes | The ID of the application template created within the CoPilot web interface. |
| merchant | n/a | object | yes | The merchant object. |
| ownerSiteUser | n/a | object | no | The 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. |
| Field | Size | Type | Comments |
|---|---|---|---|
| merchantId | 19 | number | The merchant ID used to identify the account within CoPilot. |
| errors | n/a | array | The errors array containing one or more errors if there was a problem creating the merchant. |
Use the GET method to retrieve all
merchant account data, such as contact and owner information, business
details, processing information, pricing, and fees.
| Method | GET |
| Host | https://api-uat.cardconnect.com |
Path | /merchant/{merchantId} |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Consumes | n/a |
| Produces | application/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:
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.
| Method | PUT |
| Host | https://api-uat.cardconnect.com |
Path | /merchant/{merchantId} |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Consumes | application/json |
| Produces | application/json |
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 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.
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| merchant | n/a | object | yes | The merchant object. |
| ownerSiteUser | n/a | object | no | The owner site user object is used to create the merchant's CardPointe user. When null, no changes are made to the owner site user. |
| Field | Size | Type | Comments |
|---|---|---|---|
| errors | n/a | array | The errors array containing one or more errors if there was a problem updating the merchant. |
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.
| Method | GET |
| Host | https://api-uat.cardconnect.com |
Path | /merchant/{merchantId}/status |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Consumes | n/a |
| Produces | application/json |
GET https://api-uat.cardconnect.com/merchant/123456789/status
A successful request returns the errors object, as well as the merchantStaus object containing the following fields:
| Field | Type | Comments |
|---|---|---|
| approvedDatetime | string | The 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. |
| boardedDatetime | string | The 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. |
| cancelledDatetime | string | The 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. |
| declinedDatetime | string | The 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. |
| liveDatetime | string | The 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. |
| boardingProcessPendingFlg | boolean | |
| boardingProcessStatusCd | enumeration | See below |
| gatewayBoardingStatusCd | enumeration | See below |
| Code | Description |
|---|---|
| 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. |
| OFS | The digital application is awaiting merchant signature. Displayed in the CoPilot web interface as "Pending Signature." |
| QUALIFY | The digital application is signed and undergoing an inital review before being sent for underwriting. Displayed in the CoPilot web interface as "Qualifying." |
| UNDER | The application is being reviewed by the Underwriting team. Displayed in the CoPilot web interface as "Underwriting." |
| DECLINED | The application has been rejected by the Underwriting team. |
| BOARDING | The merchant account is in the process of being boarded to the processing platform. |
| BOARDED | The merchant account is successfully boarded to the processing platform. |
| LIVE | The merchant account is boarded to the processing platform, the CardPointe Gateway, and is receiving deposits. |
| CANCELLED | The merchant account is cancelled. |
| Code | Description |
|---|---|
| NOT_BOARDED | The merchant ID is not yet boarded to the CardPointe Gateway. |
| BOARDED | The merchant account is boarded to the processing platform and the merchant ID is boarded to the CardPointe Gateway. |
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.
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.
| Method | PUT |
| Host | https://api-uat.cardconnect.com |
Path | /merchant/{merchantId}/signature |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Consumes | application/json |
| Produces | application/json |
No request body is required for this endpoint.
| Field | Type | Comments |
|---|---|---|
| errors | array | The errors array containing one or more errors if there was a problem requesting the signature. |
| signatureUrl | string | The URL for the digital application that is provided to the merchant. |
Use the GET request to view the current status of an application that has been submitted to the merchant for signing.
| Method | GET |
| Host | https://api-uat.cardconnect.com |
Path | /merchant/{merchantId}/signature |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Consumes | n/a |
| Produces | application/json |
GET https://api-uat.cardconnect.com/merchant/123456789/signature
A successful request returns the errors object, as well as the signatureStatus object containing the following fields:
| Field | Type | Comments |
|---|---|---|
| signedSiteUserId | number | The ID of the owner site user who signed the application. |
| signedDateTime | string | The 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. |
| signer | object | The signer object containing the signer's details. |
| signatureUrl | string | The URL for the digital application that the signer accessed to complete the digital application. |
| signatureStatusCd | enumeration | Can be one of the following:
|
| Field | Type | Comments |
|---|---|---|
| string | The email of the signer. | |
| firstName | string | The first name of the signer. |
| lastName | string | The last name of the signer. |
| ipAddress | string | The signer's IP address at the time of signing. |
| personalGuaranteeFlg | boolean | True when the owner selected the Personal Guarantee option. |
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.
| Method | DELETE |
| Host | https://api-uat.cardconnect.com |
Path | /merchant/{merchantId}/signature |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Consumes | n/a |
| Produces | application/json |
No request body is required for this endpoint.
| Field | Type | Comments |
|---|---|---|
| errors | object | The errors array containing one or more errors if there was a problem |
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.
| Method | PUT |
| Host | https://api-uat.cardconnect.com |
Path | /merchant/{merchantId}/attachment |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Consumes | application/json |
| Produces | application/json |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| fileName | 60 | string | yes | The file name of the attachment. |
| mimeType | 30 | string | yes | The MIME type of the attachment file. |
| description | 1000 | string | yes | The description of the attachment file. |
| attachmentTypeCd | n/a | string | yes | The attachment type code that represents the type of attachment. |
| document | 100mb | string | yes | 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. |
| Field | Type | Comments |
|---|---|---|
| errors | array | The errors array containing one or more errors if there was a problem uploading the attachment. |
| attachmentId | number | The ID of the attachment for reference. |
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.
| Method | GET |
| Host | https://api-uat.cardconnect.com |
Path | /equipmentCatalog/list |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Consumes | n/a |
| Produces | application/json |
GET https://api-uat.cardconnect.com/equipmentCatalog/list?salesCode=salescode1&equipmentSupplierCd=CARDCONNECT&equipmentTypeCd=TERMINAL&pageNumber=1&pageSize=2
| Field | Required | Comments |
|---|---|---|
| salesCode | yes | The Sales Code of the merchant that requires additional equipment. |
| equipmentSupplierCd | no | The equipment supplier code. Used to return only equipment of a specific supplier. |
| equipmentTypeCd | no | The equipment type code. Used to return only equipment of a specific type. |
| pageNumber | no | The number of the page being requested. |
| pageSize | no | The number of results to limit per page. |
| Field | Type | Comments |
|---|---|---|
| rows | array | List of equipment definitions returned as an array of equipment objects. |
| totalServerItemsCount | number | Total number of rows. |
| totalDisplayItemsCount | number | The total number of rows before and including this page. |
| moreRowsAvailable | boolean | True if the are more rows available on the next page. |
| columnSums | n/a | Internal use. |
| errors | array | The errors array containiing one or more errors if there was a problem with the request. |
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.
| Action | Method | Path |
|---|---|---|
| Create Order | POST | /order |
| Get Order | GET | /order/{orderId} |
| List Orders | GET | /order/list?merchantId={merchantId} |
| Update Order | PUT | /order/{orderId} |
| Cancel Order | POST | /order/{orderId}/cancel |
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:
| Method | POST |
| Host | https://api-uat.cardconnect.com |
Path | /order |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Consumes | application/json |
| Produces | application/json |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| merchantId | 19 | number | yes | The merchant ID associated with the order. |
| equipmentId | 19 | number | yes | The equipment ID of the equipment being ordered. |
| orderNotes | 1000 | string | no | Optional notes for the person fulfilling the order. |
| quantity | 4 | number | yes | The number of devices being ordered. |
| unitPrice | 10 | number | See comments | The price per unit. Required only when billToFrequencyCd is ONETIME. |
| monthlyPrice | 10 | number | See comments | The price per month. Required only when billToFrequencyCd is MONTHLY. |
| billToCd | 100 | string | yes | The bill to code that represents who is billed for the order. |
| billingFrequencyCd | 100 | string | yes | The billing frequency code that represents the frequency of billing. |
| profileId | n/a | string | See comments | The CardPointe Gateway profile ID to charge for this order. Required only when billToCd is PARTNERCC. |
| acctId | 10 | number | See comments | The account ID of the card within the CardPointe Gateway profile to charge for this order. Required only when billToCd is PARTNERCC. |
| shippingDetails | n/a | object | yes | The shipping details object. |
| Field | Type | Comments |
|---|---|---|
| orderId | number | The ID of the order for reference. |
| errors | array | The errors array containing one or more errors if there was a problem creating the order. |
Use the GET method to retrieve the details and status of a specific equipment order.
| Method | GET |
| Host | https://api-uat.cardconnect.com |
Path | /order/{orderId} |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Consumes | n/a |
| Produces | application/json |
GET https://api-uat.cardconnect.com/order/123456
| Field | Type | Comments |
|---|---|---|
| orderId | number | The order ID used to reference this order. |
| merchantId | number | The merchant ID associated with the order. |
| equipmentId | number | The equipment ID of the equipment ordered. |
| orderNotes | string | Optional notes for the person fulfilling the order. |
| quantity | number | The number of devices ordered. |
| unitPrice | number | The price per unit. |
| monthlyPrice | number | The price per month. |
| billToCd | string | The bill to code that represents who is billed for the order. |
| billingFrequencyCd | string | The billing frequency code that represents the frequency of billing. |
| profileId | string | The CardPointe Gateway profile ID charged for this order. |
| acctId | number | The account ID of the card within the CardPointe Gateway profile charged for this order |
| shippingDetails | string | The shipping details object. |
| orderStatusCd | string | The order status code that represents the current status of the order. |
| placedDatetime | string | The 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. |
| shippedDatetime | string | The date the order was shipped. The date and time is reported in local time, based on the timezone selected in the CoPilot web interface. |
| canceledDatetime | string | The date the order was canceled. The date and time is reported in local time, based on the timezone selected in the CoPilot web interface. |
| fulfillingDatetime | string | The date the order was fulfilled. The date and time is reported in local time, based on the timezone selected in the CoPilot web interface. |
You can retrieve a list of all orders for a specific merchant account by using the List Orders endpoint.
| Method | GET |
| Host | https://api-uat.cardconnect.com |
Path | /order/list |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Consumes | n/a |
| Produces | application/json |
GET https://api-uat.cardconnect.com/order/list?merchantId=123456789&pageSize=2&pageNumber=1
| Field | Required | Comments |
|---|---|---|
| merchantId | yes | The merchant ID used to identify the account within CoPilot. |
| pageSize | no | The number of results to limit per page. |
| pageNumber | no | The number of the page being requested. |
| Field | Type | Comments |
|---|---|---|
errors | array | The errors array containing one or more errors if there was a problem creating the order. |
| rows | array | An array of order objects. |
| totalServerItemsCount | number | The total number of rows. |
| totalDisplayItemsCount | number | The total number of rows before and including this page. |
| moreRowsAvailable | boolean | True if there are more rows available on the next page. |
| columnSums | n/a | Internal use. |
Use the Update Order endpoint to make changes to an existing order, such as the quantity, price, or the bill to code.
| Method | PUT |
| Host | https://api-uat.cardconnect.com |
Path | /order/{orderId} |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Consumes | application/json |
| Produces | application/json |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| order | n/a | object | yes | The order object. Note: It is not possible to change |
| Field | Type | Comments |
|---|---|---|
| errors | array | The errors array containing one or more errors if there was a problem creating the 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.
| Method | POST |
| Host | https://api-uat.cardconnect.com |
Path | /order/{orderId}/cancel |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Consumes | n/a |
| Produces | application/json |
| Field | Type | Comments |
|---|---|---|
| errors | array | The errors array containing one or more errors if there was a problem cancelling the order. |
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.
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.
| Method | PUT |
| Host | https://api-uat.cardconnect.com |
Path | /merchant/{merchantId}/customfields |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Consumes | application/json |
| Produces | application/json |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| customFields | n/a | array | See comments | The 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. |
| Field | Size | Type | Comments |
|---|---|---|---|
| errors | n/a | array | The errors array containing one or more errors if there was a problem updating the 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.
| Method | GET |
| Host | https://api-uat.cardconnect.com |
Path | /merchant/{merchantId}/customfields |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Consumes | n/a |
| Produces | application/json |
GET https://api-uat.cardconnect.com/merchant/123456789/customfields
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.
| Field | Type | Comments |
|---|---|---|
| customFieldLabel | string | The label for this custom field, set via the CoPilot web interface. |
| isRequired | number | When 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. |
| isActive | number | When 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. |
| userFieldNumber | number | A 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. |
| customFieldValue | string | The custom field's value currently set for this account, whether set via the CoPilot web interface or via the CoPilot API. |
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 CardPointe Web App access to view the status of their application, manage their account settings, and later view CardPointe Gateway transactions and reports once boarded to the Gateway.
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.
| Method | PUT |
| Host | https://api-uat.cardconnect.com |
Path | /merchant/{merchantId}/ownerSiteUser |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Consumes | application/json |
| Produces | application/json |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| ownerSiteUser | n/a | object | yes | The owner site user object. |
| Field | Type | Comments |
|---|---|---|
| errors | array | The errors array containing one or more errors if there was a problem updating the owner site user. |
Use the GET method to retrieve the current owner site user data for an account.
| Method | GET |
| Host | https://api-uat.cardconnect.com |
Path | /merchant/{merchantId}/ownerSiteUser |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Consumes | n/a |
| Produces | application/json |
GET https://api-uat.cardconnect.com/merchant/123456789/ownerSiteUser
| Field | Type | Comments |
|---|---|---|
| ownerSiteUser | object | The owner site user object. |
| errors | array | The errors array containing one or more errors if there was a problem retrieving the owner site user. |
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.
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.
| Method | POST |
| Host | https://api-uat.cardconnect.com |
Path | /billingplan/create |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Consumes | application/json |
| Produces | application/json |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| billingPlan | n/a | object | yes | The billing plan object. Note: Leave the |
| Field | Type | Comments |
|---|---|---|
| billingPlan | object | The billing plan object. |
| errors | array | The errors array containing one or more errors if there was a problem creating the billing plan. |
Retrieve a list of billing plans already configured for a specific front end MID.
| Method | GET |
| Host | https://api-uat.cardconnect.com |
Path | /billingplan/list/{merchId} |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Consumes | n/a |
| Produces | application/json |
GET https://api-uat.cardconnect.com/billingplan/list/111111111
| Field | Type | Comments |
|---|---|---|
| billingPlans | array | An array containing a billing plan object for each billing plan configured for the MID. Note: The |
| errors | array | The errors array containing one or more errors if there was a problem retrieving the list of billing plans. |
Use the Get Billing Plan endpoint to retrieve the details of a specific billing plan for a front end MID.
| Method | GET |
| Host | https://api-uat.cardconnect.com |
Path | /billingplan/{merchId}/{billingPlanId} |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Consumes | n/a |
| Produces | application/json |
GET https://api-uat.cardconnect.com/billingplan/111111111/123456
| Field | Type | Comments |
|---|---|---|
| billingPlan | object | The billing plan object. |
| errors | array | The errors array containing one or more errors if there was a problem retrieving billing plan. |
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.
| Method | POST |
| Host | https://api-uat.cardconnect.com |
Path | /billingplan/updateAccount |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Consumes | application/json |
| Produces | application/json |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| merchId | 11 | string | yes | The front end MID associated with the billing plan. |
| billingPlanId | 11 | string | yes | The ID of the billing plan to update. |
| profileId | 20 | string | yes | The CardPointe Gateway profile ID to use for future billing. |
| acctId | 3 | string | no | The account ID of the card within the CardPointe Gateway profile to use for future billing. Note: When omitted, the default account is used. |
| Field | Type | Comments |
|---|---|---|
| billingPlan | object | The billing plan object. |
| errors | array | The errors array containing one or more errors if there was a problem updating the account used for the billing plan. |
Use the Mark as Paid endpoint to set the status of a scheduled payment as PAID.
| Method | POST |
| Host | https://api-uat.cardconnect.com |
Path | /billingplan/markAsPaid |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Consumes | application/json |
| Produces | application/json |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| billingPlanScheduleId | 11 | string | yes | The ID of the scheduled payment to update. |
| retref | 13 | string | no | 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. |
| Field | Type | Comments |
|---|---|---|
| billingPlan | object | The billing plan object. |
| errors | array | The errors array containing one or more errors if there was a problem marking the scheduled payment as paid. |
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.'
| Method | POST |
| Host | https://api-uat.cardconnect.com |
Path | /billingplan/cancelPayment |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Consumes | application/json |
| Produces | application/json |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| billingPlanScheduleId | 11 | string | yes | The ID of the scheduled payment to cancel. |
| Field | Type | Comments |
|---|---|---|
| billingPlan | object | The billing plan object. |
| errors | array | The errors array containing one or more errors if there was a problem cancelling the scheduled payment. |
Use the Cancel Billing Plan endpoint to end a billing plan and cancel all the remaining payments scheduled.
| Method | POST |
| Host | https://api-uat.cardconnect.com |
Path | /billingplan/cancel |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Consumes | application/json |
| Produces | application/json |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| merchId | 11 | string | yes | The front end MID associated with the billing plan. |
| billingPlanId | 11 | string | yes | The ID of the billing plan to cancel. |
| Field | Type | Comments |
|---|---|---|
| billingPlan | object | The billing plan object. |
| errors | array | The errors array containing one or more errors if there was a problem cancelling the billing plan. |
See the schema definitions below to view the fields available for each object within the API.
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| ownerFirstName | 100 | string | no | The owner's first name. |
| ownerLastName | 100 | string | no | The owner's last name. |
| ownerPhone | 12 | string | no | The owner's phone number, formatted as ###-###-####. |
| ownerAddress | n/a | object | no | The address object, containing the owner's address information. |
| ownerSSN | 11 | string | no | The owner's Social Security Number, formatted as ###-##-####. |
| ownershipPct | 3 | number | yes | The percentage owned by the owner. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| address1 | 200 | string | yes | The number and street of the address. |
| address2 | 200 | string | no | Any additional address information such as apartment number or suite number of the address. |
| city | 300 | string | yes | The city of the address. |
| stateCd | 2 | string | no | The state code that represents the US state where the address is located. |
| zip | 15 | string | yes | The ZIP code of the address. |
| countryCd | 2 | string | no | The country code that represents the country where the address is located. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| fileName | 60 | string | yes | The file name of the attachment. |
| mimeType | 30 | string | yes | The MIME type of the attachment file. |
| description | 1000 | string | yes | The description of the attachment file. |
| attachmentTypeCd | n/a | string | yes | The attachment type code that represents the type of attachment. |
| document | 100Mb | string | yes | 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. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| bankAcctNum | 25 | string | yes | The bank account number. |
| bankRoutingNum | 9 | string | yes | The bank account's routing number. |
| bankAcctTypeCd | 10 | string | yes | The bank account type code that represents the type of bank account. |
| bankName | 200 | string | yes | The name of the bank that holds the account. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| depositBank | n/a | object | yes | The bank object containing the account details used when depositing funds. |
| withdrawalBank | n/a | object | yes | The bank object containing the account details used when withdrawing funds. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| billingPlanId | 11 | 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. |
| merchId | 11 | string | yes | The front end MID associated with the billing plan. |
| profileId | 20 | string | yes | The CardPointe Gateway profile ID to charge for this order. |
| acctId | 3 | string | no | The 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. |
| amount | number | yes | The amount to bill for each scheduled payment. | |
| timeSpan | 1 | number | yes | The billing frequency, represented as 1 for daily, 2 for weekly, 3 for monthly, or 4 for yearly. |
| every | 1 | number | yes | The billing interval, where 1 represents every period specified in the timeSpan field, and 2 represents every other period specified in the timeSpan field. |
| untilCondition | 1 | string | yes | The 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. |
| untilNumPayments | number | See Comments | The number of payments required to automatically end the billing plan. Required when untilCondition = N. | |
| untilDate | 8 | string | See Comments | The date the billing plan ends, formatted as MMDDYYYY. Required when untilCondition = D. |
| currencySymbol | 1 | string | yes | The currency symbol for the transaction. |
| startDate | 8 | string | yes | The date the billing plan begins, formatted as MMDDYYYY. |
| billingPlanName | 30 | string | yes | The name used to distinguish the billing plan from other billing plans. |
| options | array | yes | The email_receipt option should be provided with a value of 0 for no or 1 for yes. See example JSON. | |
| planSatus | 1 | string | no | The 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. |
| schedules | array | no | 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. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| billingPlanScheduleId | number | yes | The id of the billing plan schedule entry. | |
| actualAmount | number | no | The amount that was actually billed, if the payment was processed. | |
| actualPaymentDate | string | no | The date this payment was made, if it was processed. | |
| paymentStatus | string | yes | The payment status, such as Scheduled, Cancelled, Paid, or Failed. | |
| retref | string | no | The transaction id, if the payment was processed. | |
| scheduledAmount | number | yes | The amount scheduled to be billed. | |
| scheduledPaymentDate | string | yes | The date scheduled for this payment. |
The blueChexVolume object is required for merchants with the ACH from Fiserv add-on. All fields must be provided.
| Field | Size | Type | Comments |
|---|---|---|---|
| averagePerTransactionSalesAmount | 18.2 | number | The average sales amount per ACH transaction. |
| maxPerTransactionSalesAmount | 18.2 | number | The maximum sales amount per ACH transaction. |
| averagePerTransactionCreditAmount | 18.2 | number | The average credit (refund) amount per ACH transaction. |
| maxPerTransactionCreditAmount | 18.2 | number | The maximum credit (refund) amount per ACH transaction. |
| averagePerMonthSalesAmount | 18.2 | number | The average monthly sales amount for all ACH transactions. |
| maxPerMonthSalesAmount | 18.2 | number | The maximum monthly sales amount for all ACH transactions. |
| averagePerMonthCreditAmount | 18.2 | number | The average monthly credit (refund) amount for all ACH transactions. |
| maxPerMonthCreditAmount | 18.2 | number | The maximum monthly credit (refund) amount for all ACH transactions. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| telSecOptionFlg | n/a | boolean | See 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. |
| ccdSecOptionFlg | n/a | boolean | See 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. |
| webSecOptionFlg | n/a | boolean | See 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. |
| ppdSecOptionFlg | n/a | boolean | See 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. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| customerBillPriorToShipFlg | n/a | boolean | no | True if the customer is billed prior to shipment. |
| depositReqForFulfillFlg | n/a | boolean | no | True if deposit is required for order fulfillment. |
| whenCustomerChargedCd | 10 | string | no | The when customer charged code that represents when the customer is charged. |
| refundPolicyCd | 10 | string | no | The refund policy code that represents the customer's refund policy. |
| serviceProvidedInCd | 10 | string | no | The service provided in code that represents the typical timeframe between purchase and delivery. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| transarmorDataProtectionFlg | n/a | boolean | no | True if TransArmor Data protection is active. Requires FALSE when cloverSecurityBundleCd = PCI. |
| transarmorTokenTypeCd | n/a | string | See comments | The TransArmor token type code that represents the token type. Required when transarmorDataProtectionFlg = TRUE. |
| transarmorMultiPayToken | 4 | string | See comments | The TransArmor multi-pay token. Required when transarmorTokenTypeCd = MULTI. |
| transarmorMonthyFee | 7.2 | number | See comments | The Monthly TransArmor Fee amount. Required when transarmorDataProtectionFlg = TRUE. |
| cloverSecurityBundleCd | n/a | string | no | Note: Only applicable for merchants with a Clover Security Bundle. The Clover security bundle code that represents the applicable bundle. |
| cloverSecurityFee | n/a | number | See comments | Note: Only applicable for merchants with a Clover Security Bundle. The Monthly Clover Security Fee amount. Required when cloverSecurityBundleCd = TDPPCI. |
| cloverSecurityPlusFee | n/a | number | See comments | Note: Only applicable for merchants with a Clover Security Bundle. The Monthly Clover Security Plus Fee amount. Required when cloverSecurityBundleCd = CSPFB. |
| pciComplianceServiceFee | n/a | number | See comments | Note: Only applicable for merchants with a Clover Security Bundle. The PCI Compliance Service Fee. Required when cloverSecurityBundleCd = PCI. |
| pciComplianceServiceFeeFrequency | 7 | string | See 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. |
| pciComplianceServiceFeeMonthToBill | n/a | string | See 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. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| contactName | 300 | string | no | The full name of the contact. |
| contactEmail | 300 | string | no | The email address of the contact. |
| contactPhone | 12 | string | no | The phone number of the contact, formatted as ###-###-####. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| userFieldNumber | n/a | number | yes | The index number of the custom field. Must be a number between 1-10. |
| customFieldValue | 100 | string | yes | Required when the userFieldNumber is marked as required in the CoPilot web interface. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| dlvry0To7DaysPct | 3 | number | no | The percentage of products or services delivered within 7 days of purchase, represented as a whole number. |
| dlvry8To14DaysPct | 3 | number | no | The percentage of products or services delivered within 8-14 days of purchase, represented as a whole number. |
| dlvry15To30DaysPct | 3 | number | no | The percentage of products or services delivered within 15-30 days of purchase, represented as a whole number. |
| dlvryOver30DaysPct | 3 | number | no | The percentage of products or services delivered more than 30 days after purchase, represented as a whole number. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| businessIncorporatedStateCd | 2 | string | no | The state code where the business is incorporated. |
| merchantTimeZone | 3 | string | no | The 2 or 3 character time zone, such as ET, CT, MT, PT or HST. |
| websiteAddress | 200 | string | yes | Business website is required if merchant.processing.modeOfTransaction.eCommercePct is greater than 0. |
| businessPhone | 12 | string | no | The business phone number, formatted as ###-###-####. |
| businessFax | 12 | string | no | The business fax number, formatted as ###-###-####. |
| businessAddress | n/a | object | yes | The address object, containing the business address. |
| mailingAddress | n/a | object | yes | The address object, containing the business mailing address. |
| Field | Size | Type | Comments |
|---|---|---|---|
| equipmentId | 60 | number | The unique identifier for this piece of equipment. |
| equipmentName | 60 | string | The name for this piece of equipment. |
| description | 60 | string | The description for this piece of equipment. |
| make | 60 | string | The manufacturer for this piece of equipment. |
| model | 60 | string | The model name for this piece of equipment. |
| imageUrl | 60 | string | The URL for the image representing this piece of equipment. |
| sku | 60 | string | The SKU for this piece of equipment. |
| platformCd | 60 | string | The platform for this piece of equipment. |
| equipmentTypeCd | 60 | string | The equipment type code representing the type or category of this piece of equipment. |
| equipmentSupplierCd | 60 | string | The equipment supplier code representing the provider of this piece of equipment. |
| defaultPrice | 60 | string | The default one-time price. |
| defaultPlanPrice | 60 | string | The default monthly price, if allowed. |
| allowCustomBillingFlg | 60 | string | True if monthly billing is allowed. |
| standardShippingPrice | 60 | string | The standard shipping price per unit. |
| expeditedShippingPrice | 60 | string | The expedited shipping price per unit. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| achBatchFee | 7.3 | number | yes | The ACH Batch Fee. |
| addressVerifFee | 7.3 | number | yes | The Address Verification Fee (AVS). |
| annualMembershipFee | 8.2 | number | yes | The Annual Membership Fee. |
| appFee | 8.2 | number | yes | The Application Fee (One Time). |
| authFee | 7.3 | number | yes | The Authorization Fees (All Card Types). |
| chargebackFee | 8.2 | number | yes | The Chargeback Fee (Per Item). |
| ddaRejectFee | 8.2 | number | yes | The DDA Rejects (Per Item). |
| earlyCancelFee | 8.2 | number | yes | The Early Termination Fee. |
| minProcessFee | 8.2 | number | yes | The Minimum Processing Fee (Monthly). |
| monthlyEquipmentRentalFee | 8.2 | number | no | The Equipment Rental Fee (Monthly). |
| pciAnnualFee | 8.2 | number | no | The PCI Annual Fee, applicable when pciProgramCd is ANNUAL. |
| pciConciergeMonthlyFee | 8.2 | number | see comments | The PCI Concierge Monthly Fee. Required to submit merchants when |
| pciNonComplianceFee | 8.2 | number | no | The PCI Non-Compliance Fee (Monthly), applicable when pciProgramCd is ANNUAL. |
| pciProgramCd | 10 | string | yes | The PCI Program Code that identifies the merchant's PCI Program. |
| regProdMonthlyFee | 8.2 | number | yes | The Regulatory Product Fee (Monthly). |
| retrievalFee | 8.2 | number | yes | The Retrieval Fee (Per Item). |
| statementFee | 8.2 | number | yes | The Statement Fee (Monthly). |
| transactionFee | 7.3 | number | yes | The Transaction Fees (All Card Types). |
| voiceAuthFee | 7.3 | number | yes | The Voice Authorization Fee. |
| wirelessActivationFee | 8.2 | number | yes | The Wireless Activation Fee (One Time). |
| wirelessFee | 8.2 | number | yes | The Wireless Fee (Monthly). |
| duesAndAssessmentsFlg | n/a | boolean | no | True if Dues & Assessments is enabled. |
| passthruInterchgCostsFlg | n/a | boolean | no | Returned 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. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| amex.esaQualDiscountPct | 7.3 | number | See comments | The percentage used to calculate the Amex ESA Qualified Credit Discount Fees. Required when amexProgramAssetCd = ESA. |
| amex.optBlueQualDiscountPct | 7.3 | number | See comments | The percentage used to calculate the Amex OptBlue Qualified Credit Discount Fees. Required when amexProgramAssetCd = OPTBLUE. |
| discover.qualCreditDiscountPct | 7.3 | number | See comments | The percentage used to calculate the Discover Qualified Credit Discount Fees. Required when Discover entitlement is enabled.. |
| mastercard.qualCreditDiscountPct | 7.3 | number | yes | The percentage used to calculate the Mastercard Qualified Credit Discount Fees. |
| visa.qualCreditDiscountPct | 7.3 | number | yes | The percentage used to calculate the Visa Qualified Credit Discount Fees. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| corpLevel | 12 | string | no | The Corporate Chain used to associate merchant accounts. |
| chainLevel | 12 | string | no | The Chain Level used to link merchant accounts for reporting, statement, or financial rollup. |
| sponsorBankCd | 5 | string | no | The Sponsor Bank code for merchant accounts using the FD North backend. Enter WELLS for Wells Fargo or BBVA for BBVA. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| interchangeTypeCode | 5 | string | no | The interchange type code that represents the Passthrough Interchange Costs calculation used. |
| amex.optBlueQualDiscountPct | 7.3 | number | See comments | The percentage used to calculate the Amex OptBlue Qualified Credit Discount Fees. Required when amexProgramAssetCd = OPTBLUE. |
| discover.qualCreditDiscountPct | 7.3 | number | See comments | The percentage used to calculate the Discover Qualified Credit Discount Fees. Required when Discover entitlement is enabled. |
| mastercard.qualCreditDiscountPct | 7.3 | number | yes | The percentage used to calculate the Mastercard Qualified Credit Discount Fees. |
| visa.qualCreditDiscountPct | 7.3 | number | yes | The percentage used to calculate the Visa Qualified Credit Discount Fees. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| salesCode | 25 | string | yes | The Sales Code created within the CoPilot web interface that is applicable for this merchant account. |
| akaBusinessName | 200 | string | no | The 'Also Known As' business name, such as an informal or shorthand moniker of the legal or DBA name. |
| dbaName | 100 | string | yes | The 'Doing Business As' name, sometimes referred to as the 'Fictitious Business Name' or 'Assumed Business Name' that is legally registered. |
| legalBusinessName | 500 | string | yes | The full legal name of the registered business. |
| taxFilingName | 500 | string | yes | The business name used in tax filing. Include only the following special characters: &, - |
| taxFilingMethod | 3 | string | yes | The 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. |
| businessStartDate | 8 | string | no | The business inception date, formatted as MM/DD/YYYY. |
| businessIdTypeCd | 7 | string | no | The business identification type code, used to verify the business. Can be either ARTICLE or GOVT. |
| custPrimaryAcctFlg | n/a | boolean | no | True when the account is considered the primary account among linked MIDs. |
| webLeadFlg | n/a | boolean | no | True 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. |
| hierarchy | n/a | object | no | The hierarchy object, containing custom hierarchy information for this merchant. |
| demographic | n/a | object | yes | The demographic object, containing business information. |
| ownership | n/a | object | yes | The ownership object, containing ownership information for this merchant account. |
| bankDetail | n/a | object | yes | The bank detail object, containing the depositBank and withdrawalBank objects. |
| merchantContactInfo | n/a | object | no | The contact info object, containing contact information for this merchant account. |
| processing | n/a | object | no | The processing object, containing various data and options necessary for payment processing. |
| pricing | n/a | object | no | The pricing object, containing the pricing structure used for this merchant account. |
| fees | n/a | object | no | The fees object, containing the fee structure used for this merchant account. |
| cloverSecurityAndTransarmor | n/a | object | no | The Clover security and TransArmor object, containing applicable Clover Security Bundle information and TransArmor Data Protection settings. |
| customFields | 10 | array | yes | The 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. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| eCommercePct | 3 | number | yes | The percentage of card-not-present transactions accepted via eCommerce solutions, represented as a whole number. |
| keyedPct | 3 | number | yes | The percentage of card-not-present transactions entered manually using a hardware terminal keypad or the Virtual Terminal, represented as a whole number. |
| mailOrderPct | 3 | number | yes | The percentage of card-not-present transactions accepted via a call center, represented as a whole number. |
| swipedPct | 3 | number | yes | The percentage of card-present transactions accepted via hardware terminals, represented as a whole number. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| orderId | 19 | number | no | The unique ID used to identify this order. This value is only returned via a GET request, and cannot be set. |
| merchantId | 19 | number | yes | The merchant ID associated with this order. |
| equipmentId | 19 | number | yes | The equipment ID of the equipment ordered. |
| orderNotes | 1000 | string | no | Optional notes for the person fulfilling the order. |
| quantity | 4 | number | yes | The number of devices ordered. |
| unitPrice | 10 | number | yes (when billToFrequencyCd is ONETIME) | The price per unit. |
| monthlyPrice | 10 | number | yes (if billToFrequencyCd is MONTHLY) | The price per month. |
| billToCd | 100 | string | yes | The bill to code that represents who is billed for the order. |
| billingFrequencyCd | 100 | string | yes | The billing frequency code that represents the frequency of billing. |
| profileId | n/a | string | yes (if billToCd is PARTNERCC) | The CardPointe Gateway profile ID charged for this order. |
| acctId | 10 | number | yes (if billToCd is PARTNERCC) | The account ID of the card within the CardPointe Gateway profile charged for this order. |
| shippingDetails | n/a | object | yes | The shipping details object. |
| orderStatusCd | n/a | string | no | The order status code that represents the current status of the order. |
| placedDatetime | n/a | string | no | The 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. |
| shippedDatetime | n/a | string | no | The 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. |
| canceledDatetime | n/a | string | no | The 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. |
| fulfillingDatetime | n/a | string | no | The 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. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| ownerAddress | n/a | string | yes | The address object, containing the owner's address information. |
| ownerEmail | 300 | string | yes | The email address of the owner. |
| ownerName | 300 | string | yes | 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. |
| ownerDob | 8 | string | no | The date of birth of the owner, formatted as MM/DD/YYYY. |
| ownerPhone | 12 | string | yes | The phone number of the owner, formatted as ###-###-####. |
| ownerMobilePhone | 12 | string | yes | The mobile phone number of the owner, formatted as ###-###-####. |
| ownerSSN | 11 | string | yes | The Social Security Number of the owner, formatted as ###-##-####. |
| ownerTitle | 200 | string | yes | One of the Valid Owner Titles listed below. |
| Ownership Type | Valid Owner Titles |
|---|---|
| PRTNRSHP (Partnership) |
|
| GOVT (Government) |
|
| PUBCORP (Public Corporation) |
|
| LLC (LLC) |
|
| PRIVCORP (Private Corporation) |
|
| TAXEXMPT (Tax Exempt) |
|
| NONPRFT (Non-Profit Org) |
|
| INDIVSOLE (Individual / Sole Proprietor) |
|
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| firstName | 300 | string | yes | The first name of the CardPointe user. |
| lastName | 300 | string | yes | The last name of the CardPointe user. |
| 300 | string | yes | The email address used to create the CardPointe User. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| owner | n/a | object | yes | The owner object, containing information about the owner. |
| additionalOwners | n/a | array | no | An array of additional owner objects containing one object for each additional owner. |
| ownershipTypeCd | 10 | string | no | The ownership type code that represents the business entity. |
| publiclyTradedFlag | n/a | boolean | no | True when the business offers public stock on the NYSE or NASDAQ stock exchanges. |
| stockSymbol | 10 | string | no | The NYSE or NASDAQ stock symbol of the business. |
| driversLicenseNumber | 100 | string | yes | The primary owner's state issued driver's license number. |
| driversLicenseStateCd | 2 | string | yes | The state code that represents the state who issued the driver's license. |
| ownerOwnershipPct | 3 | number | no | The percentage of ownership held by the primary owner. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| backEndMid | 25 | string | See comments | The settlement processor merchant ID. Required for CardPointe-only accounts. |
| frontEndMid | 25 | string | See comments | The authorization processor merchant ID. Required for CardPointe-only accounts. |
| processorReportingMid | 25 | string | See comments | The processor merchant ID used for reporting. Required for CardPointe-only accounts. |
| backEndPlatformCd | 20 | string | See comments | The back end platform code that represents the settlement processor. Required for CardPointe-only accounts. |
| frontEndPlatformCd | 20 | string | See comments | The front end platform code that represents the authorization processor. Required for CardPointe-only accounts. |
| amexProgramAssetCd | 7 | string | See comments | The Amex program asset code that represents the American Express program used. Required when Amex entitlement is enabled. |
| amexProgramMid | 25 | string | See comments | The Amex merchant ID used to process American Express transactions. Required when amexProgramAssetCd = ESA. |
| discoverMid | 25 | string | See comments | The Discover merchant ID used to process Discover transactions. Required when discoverProgramCd = EASI. |
| discoverProgramCd | 10 | string | See comments | The Discover program code that represents the Discover program used. Required when Discover entitlement is enabled. |
| incrementalAuthorizationFlg | n/a | boolean | no | True when the account operates within the travel and entertainment industries and requires multiple incremental authorizations. Note: Requires Discover entitlement and compatible MCC. |
| debtRepaymentProgramFlg | n/a | boolean | no | True when the account accepts payments to satisfy a loan, mortgage, or other debt. Note: Requires Discover MAP entitlement and compatible MCC. |
| acquiringFlg | n/a | boolean | yes | True when the account is a Merchant Services account. False when the account is a CardPointe-only account. |
| taxId | 9 | string | no | The merchant's Social Security Number or Employer Identification Number. |
| tid | 30 | string | no | |
| busnsId | 18 | string | no | The merchant's government-issued business license number. |
| busnsIdPlaceOfIssue | 2 | string | yes | The state code that represents the state who issued the business license. |
| currencyCode | 5 | string | no | The currency code that represents the local currency where the business is located. |
| mccId | 5 | string | yes | The Merchant Category Code (MCC) that represents the business industry. |
| businessDescription | 4000 | string | yes | The description of the business. |
| iataCode | 8 | string | no | The International Air Transportation Association (IATA) code for the business. |
| quasiCashFlg | n/a | boolean | no | True for accounts that accept Quasi Cash transactions. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| flatPricing | n/a | object | yes | The flat pricing object containing the pricing structure. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| icPlusPricing | n/a | object | yes | The IC-Plus pricing object containing the containing the pricing structure. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| platformDetails | n/a | object | yes | The platform details object containing platform processing information. |
| businessDetails | n/a | object | yes | The business details object containing business policy information. |
| volumeDetails | n/a | object | yes | The volume details object containing transaction volume information. |
| deliveryPercentages | n/a | object | no | The delivery percentages object containing days until delivery information. |
| modeOfTransaction | n/a | object | no | The mode of transaction object containing transaction mode information. |
| blueChexVolume | n/a | object | See comments | The BlueChex volume object containing ACH transaction volume data. Required for applications that include the ACH from Fiserv add-on and a digital signature. |
| blueChexSecOptions | n/a | object | See comments | The 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. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| shippingAddress | n/a | object | yes | The address object containing the shipping address. |
| shipToAttn | 100 | string | yes | The name of the person receiving the order. |
| shipToAttnEmail | 100 | string | yes | The email address of the person receiving the order. |
| shippingMethodCd | 100 | string | yes | The shipping method code that represents the shipping method used. |
| shippingBillToCd | 100 | string | See comments | The bill to code that represents who is billed for the shipping charges. Only required if shippingMethodCd = EXPEDITED. |
| shippingCarrierCd | 100 | string | no | The shipping carrier code that represents the shipping provider used. |
| trackingNumber | 100 | string | no | The tracking number of the shipment. |
| shippingCost | n/a | number | no | The shipping cost. |
| merchantContactPhone | 12 | string | yes | The merchant phone number, formatted as ###-###-####. |
| merchantContactPhoneExt | 5 | string | no | The merchant phone number extension. |
| poNumber | 30 | string | no | The purchase order number. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| swipedDiscountPct | number | yes | The 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. | |
| swipedTransactionFee | number | yes | The 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. | |
| nonSwipedDiscountPct | number | yes | The 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. | |
| nonSwipedTransactionFee | number | yes | The transaction fee applied for Visa, Mastercard, Discover Full Service, Star Access, and Amex OptBlue transactions when card data is entered manually. Sales count only. |
| Field | Size | Type | Required | Comments |
|---|---|---|---|---|
| averageMonthlyVolume | 18.2 | decimal | yes | The average monthly volume of transactions for this merchant. |
| highTicketAmount | 18.2 | decimal | yes | The most expensive transaction total expected for this merchant. |
| averageTicketAmount | 18.2 | decimal | yes | The average transaction total per sale for this merchant. |
Method | GET |
| Host | https://api-uat.cardconnect.com |
| Path | /lookup/amexProgramAssetCodes |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Body | none |
| Consumes | N/A |
| Produces | application/json |
Method | GET |
| Host | https://api-uat.cardconnect.com |
| Path | /lookup/attachmentTypeCodes |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Body | none |
| Consumes | N/A |
| Produces | application/json |
Method | GET |
| Host | https://api-uat.cardconnect.com |
| Path | /lookup/backEndPlatformCodes |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Body | none |
| Consumes | N/A |
| Produces | application/json |
Method | GET |
| Host | https://api-uat.cardconnect.com |
| Path | /lookup/bankAcctTypes |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Body | none |
| Consumes | N/A |
| Produces | application/json |
Method | GET |
| Host | https://api-uat.cardconnect.com |
| Path | /lookup/billToCodes |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Body | none |
| Consumes | N/A |
| Produces | application/json |
Method | GET |
| Host | https://api-uat.cardconnect.com |
| Path | /lookup/billToDetailCodes |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Body | none |
| Consumes | N/A |
| Produces | application/json |
Method | GET |
| Host | https://api-uat.cardconnect.com |
| Path | /lookup/billingFrequencyCodes |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Body | none |
| Consumes | N/A |
| Produces | application/json |
Method | GET |
| Host | https://api-uat.cardconnect.com |
| Path | /lookup/cloverSecurityBundleCodes |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Body | none |
| Consumes | N/A |
| Produces | application/json |
Method | GET |
| Host | https://api-uat.cardconnect.com |
| Path | /lookup/countryCodes |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Body | none |
| Consumes | N/A |
| Produces | application/json |
Method | GET |
| Host | https://api-uat.cardconnect.com |
| Path | /lookup/discoverProgramCodes |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Body | none |
| Consumes | N/A |
| Produces | application/json |
Method | GET |
| Host | https://api-uat.cardconnect.com |
| Path | /lookup/equipmentSupplierCodes |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Body | none |
| Consumes | N/A |
| Produces | application/json |
Method | GET |
| Host | https://api-uat.cardconnect.com |
| Path | /lookup/equipmentTypeCodes |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Body | none |
| Consumes | N/A |
| Produces | application/json |
Method | GET |
| Host | https://api-uat.cardconnect.com |
| Path | /lookup/frontEndPlatformCodes |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Body | none |
| Consumes | N/A |
| Produces | application/json |
Method | GET |
| Host | https://api-uat.cardconnect.com |
| Path | /lookup/interchangeTypeCodes |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Body | none |
| Consumes | N/A |
| Produces | application/json |
Method | GET |
| Host | https://api-uat.cardconnect.com |
| Path | /lookup/orderStatusCodes |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Body | none |
| Consumes | N/A |
| Produces | application/json |
Method | GET |
| Host | https://api-uat.cardconnect.com |
| Path | /lookup/ownershipTypes |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Body | none |
| Consumes | N/A |
| Produces | application/json |
Method | GET |
| Host | https://api-uat.cardconnect.com |
| Path | /lookup/pciProgramCodes |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Body | none |
| Consumes | N/A |
| Produces | application/json |
Method | GET |
| Host | https://api-uat.cardconnect.com |
| Path | /lookup/refundPolicyCodes |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Body | none |
| Consumes | N/A |
| Produces | application/json |
Method | GET |
| Host | https://api-uat.cardconnect.com |
| Path | /lookup/serviceProvidedInCodes |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Body | none |
| Consumes | N/A |
| Produces | application/json |
Method | GET |
| Host | https://api-uat.cardconnect.com |
| Path | /lookup/shippingCarrierCodes |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Body | none |
| Consumes | N/A |
| Produces | application/json |
Method | GET |
| Host | https://api-uat.cardconnect.com |
| Path | /lookup/shippingMethodCodes |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Body | none |
| Consumes | N/A |
| Produces | application/json |
Method | GET |
| Host | https://api-uat.cardconnect.com |
| Path | /lookup/stateCodes |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Body | none |
| Consumes | N/A |
| Produces | application/json |
Method | GET |
| Host | https://api-uat.cardconnect.com |
| Path | /lookup/transarmorTokenTypeCodes |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Body | none |
| Consumes | N/A |
| Produces | application/json |
Method | GET |
| Host | https://api-uat.cardconnect.com |
| Path | /lookup/whenCustomerChargedCodes |
| Headers | Authorization: Bearer
X-CopilotAPI-Version: 1.0 |
| Body | none |
| Consumes | N/A |
| Produces | application/json |
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.
| Field | Type | Comments |
|---|---|---|
| code | String | The error code |
| message | String | The error message |
| errorField | String | The field that caused the error |
| status | String | The HTTP Status Code |