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 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.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("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("<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("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); }
Versions
1.7.7
- Feature: Added
CardAuthMethod
parameter to/initPayment
response.
1.7.6
- Feature: Added
identification
andidentificationType
fields touserDetails
block.
1.7.5
- Feature: Added
deviceManufacturerIdentifier
field indeviceDetails
block for/initPayment
and/payment
. - Feature: Added
country
field that acts as an alias of thecountryCode
field for/createUser.do
and/updateUser.do
. - Feature: Added
initialTransactionId
input parameter for subscription services. - Feature: Added
mcc
output parameter topayment.do
response and DMN.
1.7.4
- Feature: Added
CurrencyConversion
support for/payout
request. - Feature: Added
merchantAdviceCode
response parameter. - Feature: Added
taxId
field toCompanyDetails
class. - Feature: Added
addressLines
andshipAddressLines
toUserAddress
. - Feature: Extended
AddendumsLocalPayment
with fields:vatAmount
nationalConsumptionTaxAmount
taxAmountBase
tipAmount
taxCurrencyCodeBase
airportChargeAmount
1.7.3
- New Method:
getGetMerchantPaymentMethods
in Safecharge class. - Feature: Added
openInExternalBrowser
flag toAccountCapture
,Payment
andGetMerchantPaymentMethods
response. - Feature: Added
appUrl
andappReturnLink
fields toURLDetails
. - Fix: Added
type
andcountryCode
fields toGetMerchantPaymentMethodsRequest
. - Fix: Added
URLDetails
block toAccountCaptureRequest
.
1.7.2
- Full support for
externalTokenProvider
in/initPayment
and/payment
.
1.7.1
billingAddress.state
verification is set to 5 characters.
1.7.0
New Java SDK Methods
getPaymentStatus
getPayoutStatus
accountCapture
getCardDetails
getMcpRates
getDccDetails
addUPOAPM
payout
Enhancements Java SDK Methods
openOrder
initPayment
payment
authorise3d
verify3d
threeD Input Class
threeD Output Class
externalMpi Class
externalToken Class
storedCredentials Class
addendums Class
alternativePaymentMethod (Class)
getMerchantPaymentMethods
Other Enhancements
- Created underlying JSON serialization method – having access to the underlying JSON received by the response is a great asset for the developer.
settleTransaction
now supports theairlines
addendum.- Updated
getPaymentStatus
to return amount and currency (also for partial approval). authCode
is optional for refund, settle, and void.- Removed the
threeDProtocolVersion
parameter from theexternalMpi
block.