Java SDK

Get started seamlessly integrating our payment solution with the Java Software Development Kit.

This guide will outline how to install, configure, and initialize the Java SDK with code demos of how to execute our most common API Requests.

See the Java SDK Reference for more information on our available methods, objects, and errors.

Get Started

Getting started with the Java SDK requires three steps:

1. Download Software requirements
2. Download and Install the SDK
3. Download and Install Third Party Dependencies

Download Software requirements

Download and Install the SDK

• Copy the file inside your site directory.
• Add prerelease-WePay-Java-SDK-version.jar as a library for your site. Depending on your project setup, this could be:
  • Adding the .jar as a library through your build management tool.
  • Adding the .jar to your classpath, eg. java -classpath path/to/prerelease-WePay-Java-SDK-version.jar.

Download and Install Third Party Dependencies

Add third party library dependencies as jar files in your project. The dependency jar files can be downloaded from these links:

• JSON (20090211)
• Apache HttpCore (4.4.13)

If using gradle, these dependencies can be installed by adding them as dependencies in your gradle build script:

implementation "org.json:json:20090211"
implementation "org.apache.httpcomponents:httpcore:4.4.13"

Use Gradle

dependencies {
  implementation "com.wepay:wepay-java-sdk:0.0.1"
//..
}

Next, since the SDK relies on Java 1.8 or later, you'll need to specify that as your target Java version (also in build.gradle):

compileOptions {
  sourceCompatibility JavaVersion.VERSION_1_8
  targetCompatibility JavaVersion.VERSION_1_8
}

Public Release

To be updated Q321.

SDK Organization

The Java SDK contains several packages:

• com.wepay.exception: Defines exceptions that could be thrown by the APIs. See Handle Errors.
• com.wepay.endpoints: Functions that are the entry points for making API calls.
• com.wepay.model.*: These packages contains POJO classes that represent objects used in the WePay API.
  • com.wepay.model.resource: Represent a WePay resource (which is what's returned by most API requests).
  • com.wepay.model.collection: Represent a collection of WePay resources (returned by find() requests).
  • com.wepay.model.request_params: The body of an API request.
  • com.wepay.model.additional_params: Additional data for an API request, such as headers.
  • com.wepay.model.data: Nested objects in the request or response.
  • com.wepay.model.enum: Enumeration values.
• com.wepay.network: Used internally by the SDK.

Configure the SDK

Use the table below to determine which testing environment your app will use. The environment inputs are case-sensitive.

import com.wepay.network.Configuration;
import com.wepay.network.WePayRequest;

    Configuration configuration = new Configuration();
    configuration.setAppId("<YOUR APP ID>");
    configuration.setAppToken("<YOUR APP TOKEN>");
    configuration.setEnvironment(Configuration.Environment.STAGE);
    WePayRequest.initializeRequest();

Make API Requests

The SDK methods are grouped under each top-level API resource. For example, this is the mapping for Accounts:

• GET /accounts <FaIcons.FaArrowRight /> AccountsApi.find()
• POST /accounts <FaIcons.FaArrowRight /> AccountsApi.create()
• GET /accounts/id <FaIcons.FaArrowRight /> AccountsApi.lookup()
• POST /accounts/id <FaIcons.FaArrowRight /> AccountsApi.update()
• DELETE /accounts/id <FaIcons.FaArrowRight /> AccountsApi.delete()
• GET /accounts/id/capabilities <FaIcons.FaArrowRight /> AccountsApi.getCapabilities()
• POST /accounts/id/capabilities <FaIcons.FaArrowRight /> AccountsApi.capabilities()

Handle Errors

All API request methods can throw these exceptions within the SDK:

You have several options for handling API errors.

Handle the relevant WePay errors

This option allows your application to have special handling for any errors it cares about, while handling the rest as generic errors.

try {
    AccountsRequestParamData accountsRequestParamData = new AccountsRequestParamData();
    AccountsFindRespData findResult = AccountsApi.find(accountsRequestParamData);
}
catch (InvalidParams e) {
    LOGGER.info("handling invalid params error");
    LOGGER.info(e.getMessage());
}
catch (WePayException e) {
    LOGGER.info("handling any other WePay errors");
}
catch (IOException | JSONException e) {
    LOGGER.info("failed to send the request");
}

Handle every type of error

This option is the most tedious, but it has the benefit of having a strict compile-time check that all exceptions have been caught.

try {
    AccountsRequestParamData accountsRequestParamData = new AccountsRequestParamData();
    AccountsFindRespData findResult = AccountsApi.find(accountsRequestParamData);
}
catch (InvalidParams | NotAuthorized e) {
    LOGGER.info("handling some known WePay errors");
}
catch (ThrottleExceeded e) {
    LOGGER.info("handling throttle exceeded");
}
catch (UnknownWePayException | UnexpectedError | ServiceTemporarilyUnavailable | JSONException | IOException e) {
    LOGGER.info("handling non-actionable errors");
}

Handle errors based on the error code

The type of error can also be determined by the exception's error code.

try {
    AccountsRequestParamData accountsRequestParamData = new AccountsRequestParamData();
    AccountsFindRespData findResult = AccountsApi.find(accountsRequestParamData);
}
catch (WePayException e) {
    switch (e.getErrorCode() {
        case InvalidParams.ERROR_CODE: break;
        case NotAuthorized.ERROR_CODE: break;
    }
}
catch (IOException | JSONException e) {
    LOGGER.info("failed to send the request");
}

Use Auto Pagination

    AccountsRequestParamData requestParamData = new AccountsRequestParamData();
    requestParamData.setPageSize(50);
    AccountsFindRespData accounts = AccountsApi.find(new AccountsRequestParamData());
    for (Account account: accounts.autoPagingIterable()) {
        // Do something with `account`
    }

Implement Idempotency

Configure retry policy

WePayRequest.setHttpClient(
    WePayHttpClient.builder().retryPolicy(PredefinedRetryPolicies.NO_RETRY)
    .build()
);

The default retry condition checks multiple conditions in the following order:

• If the Unique-Key header is not present;
• If the retry deadline is past;
• If the max number of retries is reached;
• If the error is one of the retry-able errors.

Make async requests

Synchronous Example:

Payment payment = PaymentsApi.create( paymentsCreateData, paymentsCreateAdditionalParams);
// waiting for line above to finish executing before moving on

Asynchronous Example:

CompletableFuture<Payment> paymentCompletableFuture = PaymentsApi.createAsync(
    paymentsCreateData, paymentsCreateAdditionalParams
);
// do some other stuff
Payment paymentCreateResult = paymentCompletableFuture.join();

Persistence

The SDK currently does not provide any persistence support, so partners need to implement a strategy to retrieve and continue in-retry requests in the case of an application restart.

Clear Usage Demos