Console

Payments with the Java library

Learn to create a payment with our Java SDK.

Suggest Edits

You can create a payment in your backend application with our Java library. We recommend using the Java library over a custom integration with Java, as it's quicker and easier to maintain.

For installation and general information about our Java SDK, visit the TrueLayer GitHub.

📘

Check out the Payments API v3 reference

Refer to the API reference for further information on creating a payment

Before you start

Initialise the client

You now have all the information required to initialise the Java library. Make sure that you set the environment to .sandbox when testing your integration as shown in the following code sample.

TrueLayerClient client = TrueLayerClient.New()
    .environment(Environment.sandbox())
    .clientCredentials(
            ClientCredentials.builder()
                    .clientId("client-id")
                    .clientSecret("client-secret")
                .build()
    )
    .signingOptions(SigningOptions.builder()
            .keyId("key-id")
            .privateKey(Files.readAllBytes(Path.of("ec512-private-key.pem")))
            .build())
    .build();

To switch from sandbox to live, remove the .environment(...) selector.

The client builder should give you enough flexibility to load your configuration from your filesystem or environment variables. See further examples in our GitHub repository.

Create a payment

Our Java library mimics Payments V3 API. See our API reference to learn more about payment initiation. The following code snippet can be used for reference: 

CreatePaymentRequest createPaymentRequest = CreatePaymentRequest.builder()
    .amountInMinor(100)
    .currency(CurrencyCode.GBP)
    .paymentMethod(PaymentMethod.bankTransfer()
            .providerSelection(ProviderSelection.userSelected.build())
            .beneficiary(Beneficiary.merchantAccount()
                    .accountHolderName("Andrea")
                    .merchantAccountId("e83c4c20-b2ad-4b73-8a32-ee111112d72a")
                    .build())
            .build())
    .user(User.builder()
            .name("Andrea")
            .email("[email protected]")
            .build())
    .build();

ApiResponse<CreatePaymentResponse> createdPayment= tlClient.payments()
        .createPayment(createPaymentRequest).get();

if(createdPaymentResponse.isError()){
    //error scenario branch...
    ProblemDetails problemDetails = createdPaymentResponse.getError();

    // Inspect the Problem details error and return
}

// build a link to our Hosted Payment Page
URI url = client.hpp().getHostedPaymentPageLink(
    createdPayment.getId(),
    createdPayment.getResourceToken(),
    URI.create("https://yourdomain.com/redirect-page"));

return url;

Authorise a payment

After a successful /payments request, you can authorise a payment by:

Hosted payment page

The simplest option for web developers is to redirect to our hosted payment page. The Java library provides a utility to create a link to that page: 

CreatePaymentResponse createdPayment = createPaymentResponse.getData();

URI hppUrl = client.hpp().getHostedPaymentPageLink(
    createdPayment.getId(),
    createdPayment.getResourceToken(),
    URI.create("https://yourdomain.com/redirect-page"));

See our hosted payment page documentation for further details.

Mobile SDKs

To move on with the payment authorization on TrueLayer mobile SDKs, you can return the id and resourceToken fields of a CreatePaymentResponse instance to your mobile clients.

See our iOS SDK or Android SDK documentation for further details.

Direct API integration

If you want to have a fully customised journey, either on mobile or web applications, you can perform the authorisation steps on your server-side component. Refer to the startAuthorizationFlow and submitProviderSelection parts of the Java library for further details.

This is a sample implementation:

// start the auth flow
StartAuthorizationFlowRequest startAuthorizationFlowRequest = StartAuthorizationFlowRequest.builder()
    .redirect(Redirect.builder().returnUri(URI.create("https://yourdomain.com/redirect-page")).build())
    .withProviderSelection()
    .build();
ApiResponse<StartAuthorizationFlowResponse> startAuthorizationFlowResponse = tlClient.payments()
    .startAuthorizationFlow(createPaymentResponse.getData().getId(), startAuthorizationFlowRequest)
    .get();

if(startAuthorizationFlowResponse.isError()){
    //error scenario branch...
    ProblemDetails problemDetails = startAuthorizationFlowResponse.getError();
    
    //return the error details...
}    

// Submit the provider selection
ApiResponse<SubmitProviderSelectionResponse> submitProviderSelectionResponseResponse = tlClient.payments()
    .submitProviderSelection(
            createPaymentResponse.getData().getId(),
            SubmitProviderSelectionRequest.builder()
                    .providerId("provider-id")
                    .build())
    .get();

if(submitProviderSelectionResponse.isError()){
    //error scenario branch...
    ProblemDetails problemDetails = submitProviderSelectionResponse.getError();
    
    //return the error details...
}

// Get the redirect link to the bank and return it to your client
URI bankUrl = submitProviderSelectionResponseResponse.getData()
    .getAuthorizationFlow().getActions().getNext().asRedirect().getUri();

Updated 8 months ago