• Documentation
  • API Reference
  • Documentation
  • API Reference
Expand All Collapse All
  • Payment Overview
    • Introduction
    • Choosing an Integration Method
  • Accept Payment
    • Payment Page
      • Quick Start
      • Input Parameters
      • Output Parameters
    • Web SDK
      • Quick Start
      • Nuvei Fields
        • Styling
      • Additional Functions
      • APM Payments
      • Tokenization-Only Flow
      • Scenarios
      • Using ReactJS
        • Full Samples
        • Sandbox Examples
      • FAQs
    • Checkout
      • Quick Start
        • UI Customization
        • Payment Customization
        • Advanced Controls
        • Checkout Examples
      • Server-to-Server
      • Payment Scenarios
      • Mobile SDKs (Beta Release)
        • Android Mobile SDK (Beta Release)
        • iOS Mobile SDK (Beta Release)
      • Flow Diagrams
      • Plugins
        • Magento
          • Rebilling with Magento
        • WooCommerce
          • Rebilling with WooCommerce
        • PrestaShop
          • PrestaShop with Web SDK
          • PrestaShop with Checkout
        • OpenCart
        • Shopify (via AsiaBill)
        • Mirakl
        • Salesforce
        • SAP
        • WIX
      • Marketplaces
    • Features
      • Authentication
      • Financial Operations
        • Refund
        • Void
        • Auth and Settle
        • Partial Approval
        • Currency Conversion (DCC and MCP)
        • Payout
      • Card Operations
        • Card-on-File
        • PCI and Tokenization
        • Zero-Authorization
        • Merchant-Initiated Transactions (MIT)
        • Blocking Cards
      • Subscription (Rebilling)
      • 3D-Secure
        • 3D-Secure Explained
        • 3DS Implementations
          • 3DS MPI-Only Web SDK
          • 3DS MPI-Only REST
          • 3DS External MPI
          • 3DS Responses
        • 3DS Functions
          • 3D-Secure Fingerprinting
          • 3D-Secure Authentication Challenge
      • Webhooks (DMNs)
        • Payment Transaction Requests
        • Control Panel Events API
    • Guides
      • Testing Cards, APIs and APMs
        • Testing Cards
        • Testing APIs with Postman
        • Testing APMs
      • Response Handling
      • Alternative Payment Guides (APMs)
      • Airline Ticket Guides
        • Airline Addendum
        • External Authorization Addendum
      • Payment Facilitators (PayFac)
      • Cashier
        • Cashier Events Guide
        • Cashier Features
      • Withdrawal Guide
      • Risk Guide
        • Nuvei Services
        • Transaction Types
        • Credits and Payouts
        • Fraud to Sale Programs
        • Compliance Programs
        • Chargebacks
      • eKYC Guide
      • Server SDKs
        • Java SDK
        • .NET SDK
        • PHP SDK
        • Node.JS SDK
      • Fast Track Onboarding Developer Guide
      • Currency Conversion Guides
        • Multiple Currency Pricing (MCP)
        • Dynamic Currency Conversion (DCC)
          • DCC in Cashier or Payment Page
          • DCC in REST API Workflows
          • DCC in Web SDK Workflows
      • Website Compliance Guides
    • Additional Links
      • FAQs
      • API Reference
      • Release Notes
      • Country and Currency Codes

    Java SDK

    On this page:
    • Requirements
    • Getting the Nuvei SDK for Java
    • Setting Maven Dependencies
    • Initializing the SDK
    • Running Your First Request

    Requirements

    Java

    Java 1.7 or later is required.

    Verify if you have the right 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 SafeCharge-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.5.0</version>
    </dependency>

    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
    <dependencies> ... <dependency>
            <groupId>com.safecharge</groupId>
            <artifactId>safecharge-sdk-java</artifactId>
            <version>1.5.0</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("127.0.0.1");
    
        card.setCardNumber("4000027891380961");
        card.setCardHolderName("John Smith");
        card.setCVV("217");
        card.setExpirationMonth("12");
        card.setExpirationYear("2030");
    
        paymentOption.setCard(card);
    
        billingAddress.setEmail("john.smith@email.com");
        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("127.0.0.1");
    
            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("someone@somesite.com");
            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);
        }
    2022 Nuvei. All rights reserved.