Java SDK Quick Start

Get up and running with the CX Platform Java SDK in minutes. By the end of this guide you will have a working project that authenticates and creates your first customer via the API.

---

Prerequisites

• Java 8 or later (SDK supports Java 8 and above)
• Maven or Gradle as your build tool
• A valid CX Location API key for location-scoped calls (or an Implementation key to generate Location keys) (see Authentication & Environments)

---

Step 1 — Add the Dependency

Gradle (Kotlin DSL)Gradle (Groovy DSL)Maven

repositories {
    mavenCentral()
}

dependencies {
    implementation("us.cxgp:cx-sdk-client:0.2.1")
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'us.cxgp:cx-sdk-client:0.2.1'
}

<dependencies>
    <dependency>
        <groupId>us.cxgp</groupId>
        <artifactId>cx-sdk-client</artifactId>
        <version>0.2.1</version>
    </dependency>
</dependencies>

Tip

Check Maven Central for the latest published us.cxgp:cx-sdk-client version and prefer the newest stable release in production integrations.

Latest Maven Coordinates

Full Javadoc

• Java SDK Client Javadoc
• Java SDK Core Javadoc

---

Step 2 — Initialize the Client

import com.gp.cx.sdk.client.CxSdkClient;

public class QuickStart {
    public static void main(String[] args) {
        CxSdkClient client = new CxSdkClient.Builder()
            .apiKey(System.getenv("CX_LOCATION_API_KEY"))
            .baseUrl("https://cx2-main.pit.cxgp.us")
            .build();

        System.out.println("Client initialized successfully!");
    }
}

Tip

Store your API key in the CX_LOCATION_API_KEY environment variable rather than hard-coding it in source code.

About /cx/v2/

REST API examples on this site use explicit versioned paths such as /cx/v2/.... When configuring the Java SDK, keep baseUrl(...) set to the environment host only. Do not append /cx, /cx/v2, or an endpoint path.

The Builder accepts the following options:

Method	Required	Description
apiKey(String)	Yes	Your CX Platform API key
baseUrl(String)	Yes	The environment host for the CX API, for example https://cx2-main.pit.cxgp.us

---

Step 3 — Make Your First API Call

Before calling location-scoped endpoints (for example CustomersApi), set the service location at least once first using the same location key and base URL. The platform uses this service location context to route and validate downstream calls.

Use this order:

1. Initialize the client with your Location API key and environment base URL.
2. Configure service location with setServiceLocation(...).
3. Make your first downstream API call.

Note

If you only have an Implementation key, generate a Location key first (for example with ApiKeyApi#createApiKeyForNewLocation) and then continue with the flow below.

Warning

If you skip setServiceLocation(...) and call downstream location-scoped APIs directly, the request can fail because the required service-location context has not been established for that key.

import java.time.LocalDate;

import com.gp.cx.sdk.api.CustomersApi;
import com.gp.cx.sdk.api.ServiceLocationApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.model.ChannelAddressDTO;
import com.gp.cx.sdk.model.ChannelEmailDTO;
import com.gp.cx.sdk.model.ChannelPhoneDTO;
import com.gp.cx.sdk.model.CustomerDTO;
import com.gp.cx.sdk.model.ServiceLocationDTO;

public class QuickStart {
    public static void main(String[] args) {
        // 1) Initialize a location-scoped client
        CxSdkClient client = new CxSdkClient.Builder()
            .apiKey(System.getenv("CX_LOCATION_API_KEY"))
            .baseUrl("https://cx2-main.pit.cxgp.us")
            .build();

        // 2) Configure service location before downstream calls
        ServiceLocationApi serviceLocationApi = client.getServiceLocationApi();
        ServiceLocationDTO serviceLocationRequest = new ServiceLocationDTO()
            .name("PetHealth Inc")
            .locale("en-US")
            .timeZone("America/Denver")
            .primaryPhone(new ChannelPhoneDTO().value("+18015555555"))
            .primaryEmail(new ChannelEmailDTO().value("pethealth@globalpay.com"));

        serviceLocationApi.setServiceLocation(serviceLocationRequest);

        // 3) First downstream location-scoped call -> create customer
        CustomersApi customersApi = client.getCustomersApi();

        CustomerDTO customerRequest = new CustomerDTO()
                .givenName("Ol")
                .familyName("Persson")
                .displayCustomerId("Customer-12345")
                .dateOfBirth(LocalDate.of(1990, 6, 15))
                .sex("FEMALE")
                .locale("en-US")
                .primaryPhone(new ChannelPhoneDTO().value("+18015555555"))
                .primaryEmail(new ChannelEmailDTO().value("cx-test@tsys.com"))
                .primaryAddress(new ChannelAddressDTO()
                        .country(ChannelAddressDTO.CountryEnum.US)
                        .streetAddress1("123 Main Street")
                        .postalCode("84045"));

        CustomerDTO created = customersApi.setCustomer(customerRequest);

        System.out.println("Customer created: " + created.getDisplayCustomerId());
    }
}

If everything is configured correctly you should see:

Customer created: Customer-12345

---

Complete Working Example

Below is a full, self-contained class demonstrating the complete partner onboarding flow:

import java.time.LocalDate;

import com.gp.cx.sdk.api.ApiKeyApi;
import com.gp.cx.sdk.api.CustomersApi;
import com.gp.cx.sdk.api.ServiceLocationApi;
import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.exceptions.CxSdkClientException;
import com.gp.cx.sdk.model.ApiKeyResponseDTO;
import com.gp.cx.sdk.model.ChannelAddressDTO;
import com.gp.cx.sdk.model.ChannelEmailDTO;
import com.gp.cx.sdk.model.ChannelPhoneDTO;
import com.gp.cx.sdk.model.CustomerDTO;
import com.gp.cx.sdk.model.ServiceLocationDTO;

public class CxQuickStartExample {
    public static void main(String[] args) {
        try {
            // Step 1: Assumption - Implementation API key is shared by CX Support
            String implementationApiKey = System.getenv("CX_IMPLEMENTATION_API_KEY");

            // Step 2: Generate a Location API key using the Implementation key
            CxSdkClient implClient = new CxSdkClient.Builder()
                .apiKey(implementationApiKey)
                .baseUrl("https://cx2-main.pit.cxgp.us")
                .build();

            ApiKeyApi apiKeyApi = implClient.getApiKeyApi();
            ApiKeyResponseDTO keyResponse = apiKeyApi.createApiKeyForNewLocation();
            String locationApiKey = keyResponse.getApiKey();
            System.out.println("Step 2: Location API key generated");

            // Step 3: Create a Location-scoped client with the generated Location key
            CxSdkClient locationClient = new CxSdkClient.Builder()
                .apiKey(locationApiKey)
                .baseUrl("https://cx2-main.pit.cxgp.us")
                .build();

            // Step 3: Create the Service Location
            ServiceLocationApi serviceLocationApi = locationClient.getServiceLocationApi();
            ServiceLocationDTO serviceLocationRequest = new ServiceLocationDTO()
                .name("PetHealth Inc")
                .locale("en-US")
                .timeZone("America/Denver")
                .primaryPhone(new ChannelPhoneDTO().value("+18015555555"))
                .primaryEmail(new ChannelEmailDTO().value("pethealth@globalpay.com"))
                .primaryAddress(new ChannelAddressDTO()
                    .country(ChannelAddressDTO.CountryEnum.US)
                    .streetAddress1("123 Easy Street")
                    .postalCode("84045"));

            ServiceLocationDTO createdServiceLocation = serviceLocationApi.setServiceLocation(serviceLocationRequest);
            System.out.println("Step 3: Service location created: " + createdServiceLocation.getName());

            // Step 4: Create a Customer for the Service Location
            CustomersApi customersApi = locationClient.getCustomersApi();

            CustomerDTO customerRequest = new CustomerDTO()
                .givenName("Ol")
                .familyName("Persson")
                .dateOfBirth(LocalDate.of(1990, 6, 15))
                .sex("FEMALE")
                .locale("en-US")
                .primaryPhone(new ChannelPhoneDTO().value("+18015555555"))
                .primaryEmail(new ChannelEmailDTO().value("cx-test@tsys.com"))
                .primaryAddress(new ChannelAddressDTO()
                    .country(ChannelAddressDTO.CountryEnum.US)
                    .streetAddress1("123 Main Street")
                    .postalCode("84045"));

            CustomerDTO customerCreated = customersApi.setCustomer(customerRequest);
            System.out.println("Step 4: Customer created: " + customerCreated.getDisplayCustomerId());

        } catch (CxSdkClientException e) {
            System.err.println("API error: " + e.getApiErrorMessage());
            System.err.println("Status code: " + e.getStatusCode());
        }
    }
}

---

Troubleshooting Setup Issues

If setup fails before your first API call, check these common causes first:

• SSL/TLS trust errors (PKIX path building failed, handshake failures): ensure your JVM truststore is up to date and your network is not intercepting TLS with an untrusted certificate.
• Proxy/network restrictions (timeouts, unable to resolve host): if your environment requires an outbound proxy, configure JVM proxy flags:

java -Dhttps.proxyHost=YOUR_PROXY_HOST -Dhttps.proxyPort=YOUR_PROXY_PORT -jar app.jar

• API key issues (401 or 403): verify the correct key type is used (Implementation vs Location), and that it matches the target environment.
• Wrong base URL: Java SDK baseUrl(...) must be host-only (for example https://cx2-main.pit.cxgp.us), without /cx or /cx/v2.
• Service location not initialized: call setServiceLocation(...) before downstream location-scoped APIs.

Next Steps

• Explore more patterns in Usage Examples
• Learn about Error Handling and retry strategies
• Check the FAQ for common questions
• Browse the REST API Overview for the full endpoint reference

---