Hyperwallet REST SDK v2.4.6

A library to manage users, transfer methods and payments through the Hyperwallet v4 API.

For Hyperwallet v3 API calls, please use the latest SDK version 1.x.x. See here to learn about the differences between versions and the update process required to use REST API v4.

Prerequisites

Hyperwallet's Java server SDK requires at minimum JDK (Java Development Kit) version 1.7 and above.

Installation

Maven

<dependency>
    <groupId>com.hyperwallet</groupId>
    <artifactId>sdk</artifactId>
    <version>2.4.6</version>
</dependency>

Gradle

compile 'com.hyperwallet:sdk:2.4.6'

Documentation

Documentation is available at http://hyperwallet.github.io/java-sdk.

API Overview

To write an app using the SDK

• Register for a sandbox account and get your username, password and program token at the Hyperwallet Program Portal.

• Add dependency com.hyperwallet:sdk:2.4.6 to your pom.xml (or build.gradle).

• Create a instance of the Hyperwallet Client (with username, password and program token)

  Hyperwallet client = new Hyperwallet("restapiuser@4917301618", "mySecurePassword!", "prg-645fc30d-83ed-476c-a412-32c82738a20e");

• Start making API calls (e.g. create a user)

  HyperwalletUser user = new HyperwalletUser();
  user
    .clientUserId("test-client-id-1")
    .profileType(HyperwalletUser.UserProfileType.INDIVIDUAL)
    .firstName("Daffyd")
    .lastName("y Goliath")
    .email("[email protected]")
    .addressLine1("123 Main Street")
    .city("Austin")
    .stateProvince("TX")
    .country("US")
    .postalCode("78701");
  
  try {
      HyperwalletUser createdUser = client.createUser(user);
  } catch (HyperwalletException e) {
      // Add error handling here
  }

Payload Encryption

Hyperwallet’s Payload Encryption is an implementation of Javascript Object Signing and Encryption (JOSE) and JSON Web Tokens (JWT), and provides an alternative to IP allowlisting as the second factor of authentication. Please see https://docs.hyperwallet.com/content/api/v4/overview/payload-encryption for more details.

To enable payload encryption, we need the following two keysets available:

• Hyperwallet's public keyset - https://api.paylution.com/jwkset (PRODUCTION) and https://uat-api.paylution.com/jwkset (UAT)
• Client private keyset

Create a HyperwalletEncryption object providing the two keyset locations, the JWS/JWE algorithms you want to use, and the encryption method.

HyperwalletEncryption hyperwalletEncryption = new HyperwalletEncryptionBuilder()
    .encryptionAlgorithm(JWEAlgorithm.ECDH_ES)
    .encryptionMethod(EncryptionMethod.A256CBC_HS512)
    .signAlgorithm(JWSAlgorithm.ES256)
    .hyperwalletKeySetLocation("src/main/resources/hw-uat.json")
    .clientPrivateKeySetLocation("src/main/resources/client-private-keyset.json")
    .build();

Initialize the Hyperwallet Client with the created HyperwalletEncryption object

Hyperwallet client = new Hyperwallet("restapiuser@4917301618", "mySecurePassword!", "prg-645fc30d-83ed-476c-a412-32c82738a20e", hyperwalletEncryption);  

API requests will now be signed using the private key matching the selected JWS algorithm, and encrypted using Hyperwallet's public key matching the selected JWE algorithm.

Proxy Support

Hyperwallet's API client supports a connection through a proxy. To enable, an appropriate proxy configuration must be provided. It can either be provided as a Proxy object or as a String and Integer representing the URL and Port of the proxy.

A proxy can be configured after creating an instance of the Hyperwallet Client.

client.setHyperwalletProxy("proxyURL", 9090);

To enable Proxy Authorization, proper credentials and System configurations must be provided. In order to connect using Basic Auth, Basic must be an allowed tunneling method within your Java System Properties. By default, it is listed as a disabled tunneling scheme for Java 8. To enable it, follow any of the options provided below:

• Manually remove Basic from the jdk.http.auth.tunneling.disabledSchemes property inside of JAVA_HOME/jre/lib/net.properties

• Override System properties with JVM options by providing the below option

  -Djdk.http.auth.tunneling.disabledSchemes=""

• Set the System property within your code before initializing the Hyperwallet API client

  System.setProperty("jdk.http.auth.tunneling.disabledSchemes", "");
  Hyperwallet client = new Hyperwallet("restapiuser@4917301618", "mySecurePassword!", "prg-645fc30d-83ed-476c-a412-32c82738a20e");

An example of a fully configured Proxy is provided below:

System.setProperty("jdk.http.auth.tunneling.disabledSchemes", "");
Hyperwallet client = new Hyperwallet("restapiuser@4917301618", "mySecurePassword!", "prg-645fc30d-83ed-476c-a412-32c82738a20e");
client.setHyperwalletProxy("proxyURL", 3128);
client.setHyperwalletProxyUsername("proxyUsername");
client.setHyperwalletProxyPassword("proxyPassword");

To enable Proxy Support when loading JWS keys for encryption, similar proxy configurations need to be set for the HyperwalletEncryption object.

HyperwalletEncryption hyperwalletEncryption;
      ...
      hyperwalletEncryption.setProxy("proxyURL", 9090);
      hyperwalletEncryption.setProxyUsername("proxyUsername");
      hyperwalletEncryption.setProxyPassword("proxyPassword");

Once this object has been properly configured, it can then be utilized within the Hyperwallet's API client constructor.

Timeout Support

Hyperwallet's API client supports timeout value, in milliseconds, for reading and establishing communications link to Hyperwallet API resources.

   //300 milliseconds
   int connectionTimeout = 300;
   // 2 seconds  
   int readTimout = 2000;
   Hyperwallet client=new Hyperwallet("restapiuser@4917301618","mySecurePassword!","prg-645fc30d-83ed-476c-a412-32c82738a20e",connectionTimeout,readTimout);

Development

Run the tests using maven:

$ mvn test

Reference

REST API Reference

License

MIT