We are very proud to present you with version 3.0 of our Java library, which contains a host of changes, some of which are fundamental and could break your code. We have compiled a few notes on the areas to which you would need to pay attention in order to safely migrate to the latest version of OmiseJava. Naturally, this upgrade is not mandatory for any user and you would only need to make the jump if you want to make use of the new features or changes in this release.

In this guide we will go through

• Accessing the API
• New API and related breaking changes
• Other small non-breaking changes

Accessing the API

API Client Creation

In previous versions, you needed to instantiate the Omise API Client through the constructor by passing both private and public keys. In v3.0, this has been changed to a Builder pattern to enable you to pass in both or either key in places where just one of them is required. If you are currently using both keys to create the Client, you may continue to do so.

Client client = new Client.Builder() 
.publicKey("pkey_test_123") 
.secretKey("skey_test_123")
.build();

Requests

Request is the new class introduced in v3.0 as an easier and more robust way for you to construct the request you would like to send to the Omise API. This way, you would create a Request object and then pass it to the Client in order to send an API Request. This makes the process much more clear and also allows customization of the requests if there is ever a need for it. A Request contains all the information regarding the API request, endpoint and also any payload that would need to be sent along with it. See the following example for building a Request for creating a Charge.

Request<Charge> request = new Charge.CreateRequestBuilder()
.amount(100000) 
.customer("cust_test_123")
.card("card_test_123")
.build();

As seen here with Charge.CreateRequestBuilder, each model that represents an API endpoint contains within its class different RequestBuilders for different operations you are able to perform through that endpoint such as GET, POST, PATCH and DELETE. You can then use these RequestBuilders to generate the appropriate Request for performing your desired action. Each RequestBuilder can also take in parameters required (if any) in the Request.

Sending the Request

Now that you have created the Request object for your desired action, all that is left to do is send the Request to Omise. That is done by passing the Request object to the Client and await the response.

Charge charge = client.sendRequest(request);

Just to put it all together in one snippet of code

Client client = new Client.Builder()
.secretKey("skey_test_123")
.build();

Request<Charge> request = new Charge.CreateRequestBuilder()
.amount(100000)
.customer("cust_test_123")
.card("card_test_123")
.build();

Charge charge = client.sendRequest(request);

System.out.printf("Created charge: %s", charge.getId());

New API version

Breaking changes

OmiseJava v3.0 uses our latest API version “2019-05-29” as opposed to our previous version that uses “2017-11-02”. The new API brings a lot of improvements and new endpoints but also changes the behavior of some existing APIs and there are a few places that you may need to make changes, depending on your usage of said classes and variables within those classes. The extensive guide on all that is new or changed in the API can be found in the Upgrade Guide 2019-05-29, and we strongly suggest that you also take a look at document in order to get a better picture of all the changes. Some of the most important changes (along with their respective changes within this library) are listed below.

Capability API

OmiseJava v3.0 also adds Capability API into the mix of our API endpoints. This API returns all capabilities that an account possesses, such as their supported banks and payment methods. In short, Capability API has been made available to you to better shape the experience of your users by giving you further information about their account up front. Further information on this API can be found on the Capability API docs.

Request<Capability> request = new Capability.GetRequestBuilder().build(); 
Capability capability = client().sendRequest(request); 
System.out.printf("isZeroInterestInstallments: %b", capability.isZeroInterestInstallments());

Other non-breaking changes

New Source types

In v3.0, we had added TrueMoney and also a host of Installment source types that can be used to create Sources from now on. The installment plans coming through different providers and can be found in SourceType class if you are interested to find out more about them.

Serializable models

The data models we use to represent each endpoint and also contain its response data now implements the Serializable interface in order to allow our models to be easily serialized/deserialized. If you have had to implement shadow models or have achieved serializability through any other methods, you may now directly use OmiseJava models.

Guava removed

Guava has been removed from our release build and if there is anyone who relied on OmiseJava’s version of Guava in your project, you might need to pull this library in directly.