Java SDK
Looking for the Card Present SDK?Warning
This page is under construction. Some links throughout the doc could be dead links and some usage demo links might become out of date.
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.
We periodically release updates which can include new functionality, bug fixes, and security updates; check these changes out here in the Release Notes.Get Started
Getting started with the Java SDK requires three steps:
- Download Software requirements
- Download and Install the SDK
- Download and Install Third Party Dependencies
Download Software requirements
Download Java 1.8 or laterDownload and Install the SDK
Theprerelease
versions of the WePay API include new features that are not widely released yet. If you would like to
use a prerelease API version, choose the version in Partner Center and use the Prerelease SDK.It is named as
prerelease-WePay-Java-SDK-version.jar
.- 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:
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
To install the SDK, addwepay-java-sdk
to the dependencies block of your app/build.gradle
file: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 byfind()
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
The SDK must be configured with your app's credentials before it can be used. You can find these in the Partner Center under the Development tab.Use the table below to determine which testing environment your app will use. The environment inputs are case-sensitive.
Base URL | Environment |
---|---|
https://stage-api.wepay.com | STAGE |
https://api.wepay.com | PRODUCTION |
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
API requests can be made to WePay using the classes undercom.wepay.endpoints.*
. Each class corresponds to an API
resource, and each function corresponds to an operation on that resource.The mapping between SDK methods and API calls is useful for referencing the API Reference and Guides and understanding the structure of the SDK.
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:
SDK Error | Description |
---|---|
IOException | The SDK failed to establish valid connection to our servers. |
JSONException | The SDK failed to get a valid JSON response. |
WePayException | We returned an error response. |
UnknownWePayException | An unknown exception occurred. |
IOException
and JSONException
) are subclasses of WePayException
. The exceptions here correspond to the errors described in our Errors Guide.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
The find() method request returns a fixed-size page, which may not fetch all results in your query. Instead of manually asking for the next page to get all results, theautoPagingIterable
makes this simpler by fetching large lists of resources: AccountsRequestParamData requestParamData = new AccountsRequestParamData();
requestParamData.setPageSize(50);
AccountsFindRespData accounts = AccountsApi.find(new AccountsRequestParamData());
for (Account account: accounts.autoPagingIterable()) {
// Do something with `account`
}
Implement Idempotency
By default, the SDK requests are configured to retry on retry-able error responses as described in detail in our Design a Retry Strategy cookbook. The default retry policy comes with exponential backoff, a deadline of 24 hours and 30 retry attempts maximum. Retries will be attempted only if theUnique-Key
header is provided in the original request.Configure retry policy
Partners can disable retry by configuring theWePayHttpClient
with the NO_RETRY
policy:WePayRequest.setHttpClient(
WePayHttpClient.builder().retryPolicy(PredefinedRetryPolicies.NO_RETRY)
.build()
);
BackoffStrategy
and RetryCondition
.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
If you are implementing a retry strategy that takes longer than 30 seconds to terminate, use the asynchronous version of methods to make requests. This helps to avoid prolonged and hanging API 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.
The solution will possibly include persisting the request body and headers with itsretryContext
which contains the initial request time,
number of attempts, etc. The restarted application can load these data and re-attempt the requests.