On this page:

Requirements

Java

Java 1.7 or later is required.

Verify if you have the correct version installed in your system by running:

java -version

Maven

The Nuvei SDK for Java employs the Apache Maven software project management tool.

Getting the Nuvei SDK for Java

Clone the Nuvei-server-java project from GitHub.

Setting Maven Dependencies

If your application is going to be deployed on a Java EE server, add the following dependency in the Maven POM file:

<dependency>    
    <groupId>com.safecharge</groupId>
    <artifactId>safecharge-sdk-java</artifactId>
    <version>1.7.x</version>
</dependency>

For version, specify the latest version.

If you are going to use the SDK in Java SE or a non-Java EE server, add a Bean Validation API Implementation dependency in the POM file. Certified implementations of Bean Validation API can be found here.

Example – Specifying Java SDK Version 1.7.7

<dependencies> ... <dependency>
        <groupId>com.safecharge</groupId>
        <artifactId>safecharge-sdk-java</artifactId>
        <version>1.7.7</version>
    </dependency>
    <dependency>
        <groupId>org.apache.bval</groupId>
        <artifactId>bval-jsr</artifactId>
        <version>1.1.2</version>
    </dependency>
</dependencies>

Initializing the SDK

When you initialize the SDK, you effectively perform the authentication that is needed to send requests to the REST API. Ensure that you initialize the SDK properly by including the following before any request:

public class Main {
 
    public static void main(String[] args) {
        // Parameters needed for initialize call
        String merchantId = "<your merchantId>";
        String merchantSiteId = "<your merchantSiteId>";
        String merchantKey = "<your merchantKey>";
 
        Safecharge safecharge = new Safecharge();
        safecharge.initialize(merchantId, merchantSiteId, merchantKey, APIConstants.Environment.INTEGRATION_HOST.getUrl(), Constants.HashAlgorithm.SHA256);
    }
}

Running Your First Request

All you need to do is set up an HTTP client and provide the address of the Nuvei API host to the request executor. Then you can start building requests and send them to the Nuvei API.

The following example shows how simple this process is. It initializes the SDK, then sends a simple credit card payment request.

    public static void main(String[] args) {
        // Parameters needed for the call to initialize
        String merchantId = "<your merchantId>";
        String merchantSiteId = "<your merchantSiteId>";
        String merchantKey = "<your merchantKey>";

        // Parameters used for the other calls
        String userTokenId = "<unique customer identifier in merchant system>";
        String clientRequestId = "<unique request ID in merchant system>";
        String clientUniqueId = "<unique transaction ID in merchant system>";
        String currency = "USD";
        String amount = "200";

    deviceDetails.setIpAddress("<customer's IP address>");

    card.setCardNumber("4000027891380961");
    card.setCardHolderName("John Smith");
    card.setCVV("217");
    card.setExpirationMonth("12");
    card.setExpirationYear("2030");

    paymentOption.setCard(card);

    billingAddress.setEmail("[email protected]");
    billingAddress.setCountry("US");

    SafechargeResponse response = safecharge.payment(userTokenId, clientUniqueId, clientRequestId,
paymentOption, null, currency, amount, null, null, deviceDetails, null, null, billingAddress, null,
null, null, null, null, null, null, null, null, null, null, null, null, null, null, null);
}

Advanced Example

The following example runs a full payment request. 3D-Secure v2 poses a challenge and this is handled.

    public static void main(String[] args) {
        // Parameters needed for the call to initialize
        String merchantId = "<your merchantId>";
        String merchantSiteId = "<your merchantSiteId>";
        String merchantKey = "<your merchantKey>";

        // Parameters used for the other calls
        String userTokenId = "userToken";
        String clientRequestId = "<unique request ID in merchant system>";
        String clientUniqueId = "<unique transaction ID in merchant system>";
        String currency = "BGN";
        String amount = "11.11";

        deviceDetails.setDeviceType("TABLET");
        deviceDetails.setDeviceName("iPad");
        deviceDetails.setDeviceOS("iOS U");
        deviceDetails.setBrowser("safari U");
        deviceDetails.setIpAddress("<customer's IP address>");

        userDetails.setFirstName("Pat");
        userDetails.setLastName("Brown");
        userDetails.setCountry("GB");
        userDetails.setCity("London");

        shippingAddress.setCity("London");
        shippingAddress.setCountry("GB");
        shippingAddress.setAddress("33 Shipping Str. Updated.");
        shippingAddress.setFirstName("First");
        shippingAddress.setLastName("Last");

        billingAddress.setCity("London");
        billingAddress.setCountry("GB");
        billingAddress.setAddress("340689 Billing Str.");
        billingAddress.setZip("48957");
        billingAddress.setEmail("[email protected]");
        billingAddress.setPhone("359989595");
        billingAddress.setFirstName("Pat");
        billingAddress.setLastName("Brown");

        dynamicDescriptor.setMerchantName("Merchant Name");
        dynamicDescriptor.setMerchantPhone("555555");

        merchantDetails.setCustomField1("customField1-value");

        card.setThreeD(threeD);
        card.setCardHolderName("Name");
        card.setExpirationMonth("10");
        card.setExpirationYear("20");
        card.setCardNumber("4000020951595032");
        card.setCVV("111");

        paymentOption.setCard(card);

        subMerchant.setCity("Berlin");
        subMerchant.setCountryCode("DE");

            safecharge.initialize(merchantId, merchantSiteId, merchantKey, Constants.HashAlgorithm.SHA256);


            PaymentResponse paymentResponse = safecharge.payment(userTokenId, clientUniqueId, clientRequestId, paymentOption, null, currency,
                    amount, null, deviceDetails, userDetails, shippingAddress, billingAddress,
                    dynamicDescriptor, merchantDetails, null, urlDetails, null, null, null,
                    null, null, false, null, subMerchant);
    }

Java SDK