TrueLayer Java

The official TrueLayer Java client provides convenient access to TrueLayer APIs from applications built with Java.

Installation

Stable releases

Our stable releases are hosted on Maven Central.

As such, it's enough to simply declare the desired truelayer-java artifact dependency :

dependencies {
    // ... your existing dependencies

    // TL Java BE library
    implementation 'com.truelayer:truelayer-java:$version'
}

To know more about our final releases please see our Releases section.

Unstable releases

Unstable releases are published as SNAPSHOT releases on the Nexus Sonatype repository.

To use on of those release with Gradle, make sure you have the following repository listed in your build.gradle file:

repositories {
    // ... all your existing repos here
    
    maven{
        url 'https://s01.oss.sonatype.org/content/repositories/snapshots/'
    }   
}

And you declare a dependency with a -SNAPSHOT suffix:

dependencies {
    // ... your existing dependencies

    // TL Java BE library
    implementation 'com.truelayer:truelayer-java:$version-$featureName-SNAPSHOT'
}

A sample snapshot artifact would be com.truelayer:truelayer-java:0.4.10-jsdk-9-SNAPSHOT, where 0.4.10 represents the future final version of the library and jsdk-9 is the branch name on which the new feature is being implemented.

There can be multiple artifacts available for a given snapshot. Gradle will automatically look for the latest one.

Documentation

Check out the API documentation and Java library documentation.

Usage

Prerequisites

Before using the Java library you need a developer account and a signing key pair as explained here.

Initialize TrueLayerClient

TrueLayerClient client = TrueLayerClient.New()
        .environment(Environment.sandbox()) // optional: to use TL sandbox environment
        .withHttpLogs() // optional: logs HTTP traces to stdout
        .clientCredentials(
                ClientCredentials.builder()
                        .clientId("a-client-id")
                        .clientSecret("a-secret").build())
        .signingOptions(
                SigningOptions.builder()
                        .keyId("a-key-id")
                        .privateKey(Files.readAllBytes(Path.of("my-private-key.pem")))
                        .build())
        .build();

More details about our logs can be found on our wiki.

Create a payment

// build the payment request object
CreatePaymentRequest paymentRequest = CreatePaymentRequest.builder()
        .amountInMinor(101)
        .currency(CurrencyCode.GBP)
        .paymentMethod(PaymentMethod.bankTransfer()
            .providerSelection(ProviderSelection.userSelected()
                    .filter(ProviderFilter.builder()
                    .countries(Collections.singletonList(CountryCode.GB))
                    .releaseChannel(ReleaseChannel.GENERAL_AVAILABILITY)
                    .customerSegments(Collections.singletonList(CustomerSegment.RETAIL))
                    .providerIds(Collections.singletonList("mock-payments-gb-redirect"))
                    .build())
                .build())
            .beneficiary(MerchantAccount.builder()
                .merchantAccountId("e83c4c20-b2ad-4b73-8a32-ee855362d72a")
                .build())
            .build())
        .user(User.builder()
            .name("Andrea")
            .email("andrea@truelayer.com")
            .build())
        .build();        

// fire the request        
CompletableFuture<ApiResponse<CreatePaymentResponse>> paymentResponse = client
    .payments()
    .createPayment(paymentRequest);

// wait for the response
ApiResponse<CreatePaymentResponse> payment = paymentResponse.get();

Build a link to our hosted createPaymentResponse page

URI hppLink = client.hpp().getHostedPaymentPageLink("your-createPaymentResponse-id",
        "your-createPaymentResponse-token",
        URI.create("http://yourdomain.com"));

Local setup

Any version of the JDK >= 8 supported by Gradle can build and run this package. Check the Gradle compatibility matrix for more info.

To ensure compatibility, Gradle is configured to use the Java 8 toolchain by default.
Note that on M1 Macs, Gradle is unable to download this toolchain automatically and returns the following error: Could not read 'https: //api.adoptopenidk.net/v3/binary/latest/8/ga/mac/aarch64/idk/hotspot/normal/adoptopenidk' as it does not exist.. Manually install an aarch64 version of the JDK 1.8 to solve it, like the "Azul Zulu 1.8" for example.

Building locally

To build the solution run:

./gradlew build

Testing

Unit tests

To run unit tests:

./gradlew unit-tests

Integration tests

To run integration tests:

./gradlew integration-tests

Acceptance tests

To execute tests against TrueLayer sandbox environment, you should set the below environment variables:

TL_CLIENT_ID
TL_CLIENT_SECRET
TL_SIGNING_KEY_ID
TL_SIGNING_PRIVATE_KEY

and finally run:

./gradlew acceptance-tests

Code linting

To enforce coding style guidelines the project uses palantir-java-format styles via Spotless gradle plugin.

To locally check that your sources comply with our formatting

./gradlew spotlessJavaCheck

To appy the changes suggested - if any

./gradlew spotlessApply

Bear in mind that the above checks are enforced at CI time, thus the builds will fail if not compliant.

When developing on IntelliJ you can optionally install this Spotless IntelliJ Gradle plugin as well.

Due to an open issue with JDK16+, we had to specify some extra Jvm options in the gradle.properties file. If you're building on JDK versions below 9, you'll have to remove/comment the org.gradle.jvmargs key in there.

Contributing

Contributions are always welcome!

See our contributing guide.

Please adhere to this project's code of conduct.

License

MIT

lboynton/truelayer-java