CardConnect's core APIs and services are at the center of all of our payment solutions. This guide provides detailed information to help you understand the architecture of our services, and how your integrated solutions connect to them.
Specific information, including the site name and port numbers that you will need, is provided in your welcome kit.
APIs and Services
Whether you are developing a robust point-of-sale application that integrates Bolt for payment acceptance, or a web application for boarding and managing merchant accounts, your app will connect to one or more of our core services.
Click through the following topics for a brief overview of each service.
CardSecure is CardConnect's patented payment card tokenization and encryption service. CardSecure is integrated with the Bolt and CardPointe Gateway payment solutions; however you can also use the CardSecure API or Hosted iFrame Tokenizer to integrate CardSecure directly with your application.
See the CardSecure Support Page for more information on CardSecure.
See the CardSecure API documentation for detailed information on integrating CardSecure using the API.
The CardPointe Gateway is CardConnect's payment gateway, and is the core of the CardPointe business platform. The CardPointe Gateway API allows you to integrate our complete payment acceptance and transaction management solution with the tools that you use to run your business.
See the CardPointe Gateway API Support Page for more information on the CardPointe Gateway.
See the CardPointe Gateway API documentation for detailed information on integrating the CardPointe Gateway using the API.
Bolt is CardConnect's P2PE-validated, card-present payment solution. Bolt provides a streamlined terminal device integration to CardSecure and the CardPointe Gateway.
See the Bolt Support Page for more information on Bolt.
See the Bolt P2PE API documentation for detailed information on integrating the Bolt API.
CoPilot is CardConnect's customer and merchant management platform. CoPilot provides CardConnect partners with all of the tools they need to manage their business portfolio. In addition to the cloud-based web portal, CoPilot provides an API for developers looking to integrate certain CoPilot capabilities directly with their business platform.
See the CoPilot API documentation for detailed information on integrating the CoPilot API.
Each API exposes specific connection and authorization methods that your application uses to communicate with the web service. The following topics describe these methods in detail.
Like most applications, each CardConnect service includes two instances, one for testing and validation, and one for production use.
You connect to the UAT (user acceptance testing) sandbox environment to test and validate your integration. When you begin your application development and integration, you connect to the UAT instance of our service.
The UAT environment includes emulators that simulate the payment processing activities that occur in production. In this environment, you test with dummy data that is never sent to the payment processor. You should use test card numbers (for example, 4111 1111 1111 1111 or 4444 3333 2222 1111) and physical test cards.
CardConnect provides test Merchant ID (MID) accounts for use in the UAT environment. If necessary, you can request a merchant record with a valid MID to test in the UAT environment.
You connect to the PROD (production) environment to run your live application. After you successfully test and validate your integration, CardConnect provides a production MID and access to the PROD environment.
In this environment you use valid merchant and payment data. Test card numbers that work in UAT will decline in this environment. All request traffic is inspected by CardConnect and, if valid, is sent to the production host for authorization and settlement.
For smoke testing, you must direct traffic to a valid MID with production credentials that have been provided by CardPointe Support.
Tokens generated in one environment (UAT or PROD) can not be used to make authorization requests in the other environment. For example, an authorization request in the PROD environment using a token generated in the UAT environment will fail with the error "invalid token."
Web Service URLs
Each service has one or more URLs that your application uses to connect and send requests to the service.
The following table provides an overview of the URLs and the components that they are comprised of.
|CardPointe Gateway API||
|CardSecure API (JSON)|
|CardSecure API (Legacy)||
https://<site>.cardconnect.com:<port>/cardsecure/cs?action=<action code>&data=<data string>
In the context of CardConnect products and services, a "site" is a partner-level grouping of one or more merchants and the specific business settings that apply to all merchants under the partner. Some business capabilities and transaction processing settings are configured for the site.
In general, most merchants are boarded to a default site configuration. Depending on the scale and specific business needs of an integration (for example, to allow or disallow specific processing capabilities, or to support a large number of terminal devices), a partner can be granted a unique site for its merchants.
CardConnect provides integrators with the exact site name and assists with specific configuration details.
CardConnect tokens are site-specific.
Tokens generated in one site can be used in authorization requests made by any merchant ID within the same site.
Tokens generated in one site are not valid for use in an authorization request made to another site. In this case, the response will return an "invalid token" error.
Each environment uses a dedicated port on the host.
In addition to specifying the site or host name in your request, you also indicate the specific port for the UAT or PROD environment.
Your welcome kit includes the port numbers you need to connect.
With the exception of CardSecure, each CardConnect service authorizes requests sent by the client application.
The following table describes the authorization methods used by each service:
|CardPointe Gateway API||Basic Authorization with username and password||Your client application is authorized using a username and password. CardConnect generates a username and password pair for each merchant ID or for all merchant accounts on a given site, depending on the needs of the integration.|
Base64 encode the "username:password" value and pass it in the Authorization header of all CardPointe Gateway API requests.
See the Connecting to the Server topic in the CardPointe Gateway API documentation for more information.
|Bolt P2PE API||Basic Authorization with secret API key||Your client application is authorized using a unique API key. This value is generated by CardConnect and is valid for use with all Bolt terminal devices associated with a merchant ID.|
Include the API key in the Authorization header of all Bolt API requests.
See the Connecting to the Server topic in the Bolt P2PE API documentation for more information.
|CoPIlot API||Bearer Token Authentication||Your client application is authorized using a JSON Web Token, which is retrieved in an authentication request to the CoPilot service. CardConnect generates a unique client secret value that is used to generate the bearer token.|
Include the token in the Authorization field in the header of all CoPilot API requests.
See the Authentication topic in the CoPilot API documentation for more information.