Frequently Asked Questions

This page answers common questions about the CX Platform.

If your question is not answered here, check the Error Handling page or contact CX Support at cx-support@openedgepay.com.

Tip

If clicking the email link does not open a new draft, your browser/OS may not have a default mail app configured. Copy and paste cx-support@openedgepay.com into your email client.

---

What Java versions are supported?

The SDK requires Java 8 or later.

The SDK supports Java 8 and above.

---

How do I add the SDK to my project?

Add the us.cxgp:cx-sdk-client dependency to your build file:

Gradle (Kotlin DSL)Maven

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>

Note

Use the latest stable us.cxgp:cx-sdk-client release from Maven Central.

See the Quick Start for full setup instructions.

---

Is the SDK thread-safe?

Yes — the CxSdkClient instance is safe to share across multiple threads for making parallel API requests. You should create a single client instance and reuse it for the lifetime of your application.

Mutation Is Not Thread-Safe

Do not call setApiKey() on the underlying ApiClient while API requests are in-flight. If you need to rotate credentials, create a new CxSdkClient instance instead.

---

How do I configure timeouts?

Timeouts are configured on the underlying ApiClient instance:

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

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

        // Access the underlying ApiClient through a specific API module
        CustomersApi customersApi = client.getCustomersApi();
        customersApi.getApiClient().setConnectTimeout(5000);   // 5 seconds
    }
}

Tip

The SDK uses Apache HttpClient 5.2 under the hood. Refer to Apache HttpClient documentation for advanced connection pool and timeout tuning.

---

How do I configure a proxy?

If your environment requires an outbound HTTP/HTTPS proxy, configure it at the JVM level before starting your application. A common approach is to set Java system properties for the proxy host and port.

java \
  -Dhttps.proxyHost=proxy.example.com \
  -Dhttps.proxyPort=8443 \
  -Dhttp.proxyHost=proxy.example.com \
  -Dhttp.proxyPort=8080 \
  -jar your-app.jar

If your proxy requires authentication or non-default routing behavior, use your application's HTTP/client configuration layer together with Apache HttpClient capabilities.

Tip

Start with standard JVM proxy settings first. They are the simplest option for most enterprise environments and are easier to support operationally.

---

How do I use custom SSL/TLS certificates?

If your environment uses a corporate CA, TLS inspection, or a private certificate chain, add the required CA certificate to a JVM truststore and run your application with that truststore.

java \
  -Djavax.net.ssl.trustStore=C:\path\to\custom-truststore.jks \
  -Djavax.net.ssl.trustStorePassword=changeit \
  -jar your-app.jar

If you see handshake or PKIX validation errors, verify that the full certificate chain is trusted by the JVM used to run your application.

Warning

Do not disable SSL/TLS certificate validation in production. Import the required CA or intermediate certificates into a proper truststore instead.

---

What authentication is required?

The SDK authenticates using an API key sent in the CX-API-KEY HTTP header. Pass your key when building the client:

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

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

See Authentication & Environments for details on obtaining and managing API keys.

---

Do I include /cx/v2 in the SDK baseUrl?

No. Set baseUrl(...) to the environment host only:

CxSdkClient client = new CxSdkClient.Builder()
    .apiKey(System.getenv("CX_API_KEY"))
    .baseUrl("https://cx2-main.pit.cxgp.us")
    .build();

REST API examples on this documentation site use explicit versioned request paths such as /cx/v2/action/setCustomer, but the Java SDK configuration should not include /cx/v2 in the base URL.

See API Versioning for the public REST path convention.

---

Does the SDK support async operations?

No. The SDK is synchronous only — all API calls block the calling thread until the response is received.

If you need non-blocking behavior, wrap SDK calls in a CompletableFuture or submit them to an executor:

import com.gp.cx.sdk.client.CxSdkClient;
import com.gp.cx.sdk.model.CustomerDTO;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

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

        ExecutorService executor = Executors.newFixedThreadPool(4);

        CompletableFuture<CustomerDTO> future = CompletableFuture.supplyAsync(
            () -> client.getCustomersApi().getCustomerById("customer-uuid"),
            executor
        );

        future.thenAccept(customer ->
            System.out.println("Got customer: " + customer.getGivenName())
        ).exceptionally(ex -> {
            System.err.println("Failed: " + ex.getMessage());
            return null;
        });
    }
}

Tip

When wrapping SDK calls in CompletableFuture, use a dedicated thread pool rather than the common ForkJoinPool to avoid blocking shared threads.

---

What HTTP client does the SDK use?

The SDK uses Apache HttpClient 5.2 for all HTTP communication. This is included as a transitive dependency — you do not need to add it to your project separately.

If your project uses a different version of Apache HttpClient, be aware of potential classpath conflicts. Use your build tool's dependency management to enforce a consistent version.

---

How do I enable debug logging?

The SDK uses SLF4J 2.0.13 as its logging facade. To see detailed request/response logging, configure your SLF4J binding to enable DEBUG level for the SDK's package.

Logback (logback.xml):

<configuration>
    <logger name="com.gp.cx.sdk" level="DEBUG" />

    <root level="INFO">
        <appender-ref ref="STDOUT" />
    </root>
</configuration>

Log4j2 (log4j2.xml):

<Configuration>
    <Loggers>
        <Logger name="com.gp.cx.sdk" level="DEBUG" />
        <Root level="INFO">
            <AppenderRef ref="Console" />
        </Root>
    </Loggers>
</Configuration>

Warning

Debug logging may include sensitive information such as request/response bodies. Only enable it in development or staging environments.

---

What serialization library is used?

The SDK uses Jackson 2.15.3 for JSON serialization and deserialization. Jackson is included as a transitive dependency.

All model classes (e.g., CustomerDTO, StatementDTO, PaymentRequestDTO) are Jackson-annotated POJOs. If you need to customize serialization behavior, you can access the ObjectMapper via the underlying ApiClient.

---

Can I use the SDK with Kotlin or Scala?

Yes. The SDK is written in Java and is fully compatible with any JVM language that supports Java 8+ bytecode. Kotlin and Scala projects can use it directly with no additional configuration.

---

Still have questions, or suggestions for us?

Contact CX Support at cx-support@openedgepay.com.

For faster troubleshooting, include:

• SDK version (e.g., 0.2.1)
• Java version (e.g., Java 17.0.8)
• Build tool and version (e.g., Gradle 8.5)
• A minimal code sample that reproduces the problem
• The full stack trace (if applicable)
• The status code and API error details from CxSdkClientException (getStatusCode(), getApiErrorCode(), getApiErrorMessage())

---