### Java SDK: Get Session Token Request

Source: https://github.com/nuvei/nuvei-server-java/blob/master/README.md

Example of setting up the request executor, merchant information, and building a GetSessionTokenRequest to interact with the SafeCharge API. Ensure you replace placeholder values with your actual merchant credentials.

```java
import com.safecharge.biz.SafechargeRequestExecutor;
import com.safecharge.model.MerchantInfo;
import com.safecharge.request.GetSessionTokenRequest;
import com.safecharge.request.SafechargeRequest;
import com.safecharge.response.SafechargeResponse;
import com.safecharge.util.APIConstants;
import com.safecharge.util.Constants;

public class Sample {

    public static void main(String[] args) {
        SafechargeRequestExecutor requestExecutor = SafechargeRequestExecutor.getInstance();

        MerchantInfo merchantInfo = new MerchantInfo("MERCHANT_KEY_PROVIDED_BY_SAFECHARGE", "MERCHANT_ID_PROVIDED_BY_SAFECHARGE",
                "MERCHANT_SITE_ID_PROVIDED_BY_SAFECHARGE", APIConstants.INTEGRATION_HOST, Constants.HashAlgorithm.SHA256);

        SafechargeBaseRequest safechargeRequest = GetSessionTokenRequest.builder()
                                                                    .addMerchantInfo(merchantInfo)
                                                                    .build();

        SafechargeResponse response = requestExecutor.executeRequest(safechargeRequest);
        System.out.println("Received sessionToken = " + response.getSessionToken());
    }
}
```

--------------------------------

### SimpleCreditCardPayment

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Helper class demonstrating the classic two-step (get session token → execute payment) flow for credit card payments.

```APIDOC
## SimpleCreditCardPayment — Simple Auth / Sale Helpers

Helper class demonstrating the classic two-step (get session token → execute payment) flow for credit card payments.

```java
import com.safecharge.biz.simple.payment.SimpleCreditCardPayment;
import com.safecharge.model.CardData;
import com.safecharge.model.MerchantInfo;
import com.safecharge.response.PaymentsResponse;
import com.safecharge.util.APIConstants;
import com.safecharge.util.Constants;

MerchantInfo merchantInfo = new MerchantInfo(
    "MERCHANT_SECRET_KEY", "MERCHANT_ID", "MERCHANT_SITE_ID",
    APIConstants.INTEGRATION_HOST, Constants.HashAlgorithm.SHA256
);

CardData cardData = new CardData();
cardData.setCardNumber("4111111111111111");
cardData.setCardHolderName("Test User");
cardData.setExpirationMonth("12");
cardData.setExpirationYear("2026");
cardData.setCVV("123");

SimpleCreditCardPayment simplePay = new SimpleCreditCardPayment(merchantInfo);

// Sale: authorize + capture in one step
PaymentsResponse saleResponse = simplePay.executeSalePayment(cardData, "75.00", "USD", "0", null);
if (saleResponse != null && Constants.APIResponseStatus.SUCCESS.equals(saleResponse.getStatus())) {
    System.out.println("Sale approved!");
}

// Auth only: reserve funds, settle separately
PaymentsResponse authResponse = simplePay.executeAuthPayment(cardData, "200.00", "USD", "0", null);
if (authResponse != null) {
    System.out.println("Auth transaction ID: " + authResponse.getTransactionId());
}
```
```

--------------------------------

### Get Dynamic Currency Conversion Details

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Retrieves DCC conversion rates for a given card and currency pair. Requires client unique ID, client request ID, card number, original amount and currency, and target currency.

```java
import com.safecharge.response.DccDetailsResponse;

try {
    DccDetailsResponse response = safecharge.getDccDetails(
        "unique_dcc_001",   // clientUniqueId
        "req_dcc_001",      // clientRequestId
        "4111111111111111", // cardNumber
        null,               // apm
        "100.00",           // originalAmount
        "USD",              // originalCurrency
        "GBP",              // currency
        null                // country
    );

    System.out.println("Converted amount: " + response.getDccData().getConvertedAmount());
    System.out.println("Rate: " + response.getDccData().getRateByCurrencies());
} catch (SafechargeException e) {
    System.err.println("Exception: " + e.getMessage());
}
```

--------------------------------

### Get Session Token (Low-Level)

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Obtains a one-time session token required for subsequent API calls when using `SafechargeRequestExecutor` directly.

```APIDOC
## getSessionToken — Obtain Session Token (Low-Level)

### Description
Obtains a one-time session token required by all other API calls. Used directly with `SafechargeRequestExecutor`.

### Method
`SafechargeRequestExecutor.executeRequest(GetSessionTokenRequest)`

### Parameters
#### Request Body
- **merchantInfo** (MerchantInfo) - Required - Contains merchant credentials and API host details.
  - **secretKey** (string) - Required - The merchant's secret key.
  - **merchantId** (string) - Required - The merchant's unique identifier.
  - **siteId** (string) - Required - The merchant site identifier.
  - **apiHost** (string) - Required - The host address for the SafeCharge API.
  - **hashAlgorithm** (Constants.HashAlgorithm) - Required - The hashing algorithm to use for requests.

### Request Example
```java
import com.safecharge.biz.SafechargeRequestExecutor;
import com.safecharge.model.MerchantInfo;
import com.safecharge.request.GetSessionTokenRequest;
import com.safecharge.response.SafechargeResponse;
import com.safecharge.util.APIConstants;
import com.safecharge.util.Constants;

MerchantInfo merchantInfo = new MerchantInfo(
    "MERCHANT_SECRET_KEY",
    "MERCHANT_ID",
    "MERCHANT_SITE_ID",
    APIConstants.INTEGRATION_HOST,
    Constants.HashAlgorithm.SHA256
);

SafechargeRequestExecutor executor = SafechargeRequestExecutor.getInstance();

SafechargeResponse tokenResponse = executor.executeRequest(
    GetSessionTokenRequest.builder()
        .addMerchantInfo(merchantInfo)
        .build()
);
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the operation ('SUCCESS' or 'ERROR').
- **sessionToken** (string) - The obtained session token if the status is 'SUCCESS'.

#### Error Response
- **status** (string) - 'ERROR'.
- **errCode** (string) - The error code.
- **reason** (string) - A description of the error.

### Response Example
```json
{
  "status": "SUCCESS",
  "sessionToken": "your_session_token_here"
}
```

```json
{
  "status": "ERROR",
  "errCode": "some_error_code",
  "reason": "Error description"
}
```
```

--------------------------------

### Initialize Safecharge SDK (High-Level Façade)

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Use the `Safecharge` façade class for a simplified integration. Call `initialize()` once to authenticate and obtain a session token automatically. Ensure proper error handling for initialization failures.

```java
import com.safecharge.biz.Safecharge;
import com.safecharge.exception.SafechargeException;
import com.safecharge.model.*;
import com.safecharge.response.*;
import com.safecharge.util.APIConstants;
import com.safecharge.util.Constants;

Safecharge safecharge = new Safecharge();

try {
    safecharge.initialize(
        "MERCHANT_ID",          // merchantId
        "MERCHANT_SITE_ID",     // siteId
        "MERCHANT_SECRET_KEY",  // merchantKey
        APIConstants.INTEGRATION_HOST,
        Constants.HashAlgorithm.SHA256
    );
} catch (SafechargeException e) {
    System.err.println("Init failed: " + e.getMessage());
}
```

--------------------------------

### Initialize Safecharge SDK

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Initializes the Safecharge SDK with merchant credentials and API host. This method should be called once at the beginning of your application.

```APIDOC
## Initialize Safecharge SDK

### Description
Initializes the Safecharge SDK with merchant credentials and API host. This method should be called once at the beginning of your application.

### Method
`Safecharge.initialize()`

### Parameters
- **merchantId** (string) - Required - The merchant's unique identifier.
- **siteId** (string) - Required - The merchant site identifier.
- **merchantKey** (string) - Required - The merchant's secret key for authentication.
- **apiHost** (string) - Required - The host address for the Safecharge API.
- **hashAlgorithm** (Constants.HashAlgorithm) - Required - The hashing algorithm to use for requests.

### Request Example
```java
import com.safecharge.biz.Safecharge;
import com.safecharge.exception.SafechargeException;
import com.safecharge.util.APIConstants;
import com.safecharge.util.Constants;

Safecharge safecharge = new Safecharge();

try {
    safecharge.initialize(
        "MERCHANT_ID",          // merchantId
        "MERCHANT_SITE_ID",     // siteId
        "MERCHANT_SECRET_KEY",  // merchantKey
        APIConstants.INTEGRATION_HOST,
        Constants.HashAlgorithm.SHA256
    );
} catch (SafechargeException e) {
    System.err.println("Init failed: " + e.getMessage());
}
```

### Response
This method does not return a value directly but throws a `SafechargeException` on failure.
```

--------------------------------

### Simple Credit Card Payment (Auth/Sale)

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Demonstrates the classic two-step flow for credit card payments using helper classes. Supports both authorization and sale (authorize + capture) operations.

```java
import com.safecharge.biz.simple.payment.SimpleCreditCardPayment;
import com.safecharge.model.CardData;
import com.safecharge.model.MerchantInfo;
import com.safecharge.response.PaymentsResponse;
import com.safecharge.util.APIConstants;
import com.safecharge.util.Constants;

MerchantInfo merchantInfo = new MerchantInfo(
    "MERCHANT_SECRET_KEY", "MERCHANT_ID", "MERCHANT_SITE_ID",
    APIConstants.INTEGRATION_HOST, Constants.HashAlgorithm.SHA256
);

CardData cardData = new CardData();
cardData.setCardNumber("4111111111111111");
cardData.setCardHolderName("Test User");
cardData.setExpirationMonth("12");
cardData.setExpirationYear("2026");
cardData.setCVV("123");

SimpleCreditCardPayment simplePay = new SimpleCreditCardPayment(merchantInfo);

// Sale: authorize + capture in one step
PaymentsResponse saleResponse = simplePay.executeSalePayment(cardData, "75.00", "USD", "0", null);
if (saleResponse != null && Constants.APIResponseStatus.SUCCESS.equals(saleResponse.getStatus())) {
    System.out.println("Sale approved!");
}

// Auth only: reserve funds, settle separately
PaymentsResponse authResponse = simplePay.executeAuthPayment(cardData, "200.00", "USD", "0", null);
if (authResponse != null) {
    System.out.println("Auth transaction ID: " + authResponse.getTransactionId());
}
```

--------------------------------

### Initialize Payment for 3DS Flows

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Initiates a payment process, typically used as the first step in a 3D Secure v2 flow. Requires card details, device information, and a notification URL for the 3DS method.

```java
import com.safecharge.model.*;
import com.safecharge.response.InitPaymentResponse;

InitPaymentCard initCard = new InitPaymentCard();
initCard.setCardNumber("4111111111111111");
initCard.setCardHolderName("Jane Doe");
initCard.setExpirationMonth("06");
initCard.setExpirationYear("2027");
initCard.setCVV("456");

InitPaymentThreeD threeD = new InitPaymentThreeD();
threeD.setMethodNotificationUrl("https://example.com/3ds-method");

InitPaymentPaymentOption initPaymentOption = new InitPaymentPaymentOption();
initPaymentOption.setCard(initCard);

DeviceDetails deviceDetails = new DeviceDetails();
deviceDetails.setIpAddress("192.168.1.100");
deviceDetails.setBrowser("Chrome");

try {
    InitPaymentResponse response = safecharge.initPayment(
        "user_token_123",
        "unique_txn_002",
        "req_002",
        "USD",
        "49.00",
        deviceDetails,
        initPaymentOption,
        null,       // urlDetails
        null,       // customData
        null,       // billingAddress
        null,       // userId
        null,       // aftOverride
        null,       // recipientDetails
        null        // relatedTransactionId
    );

    System.out.println("Status: " + response.getStatus());
    System.out.println("Transaction ID: " + response.getTransactionId());
} catch (SafechargeException e) {
    System.err.println("Exception: " + e.getMessage());
}
```

--------------------------------

### Add Credit Card to User Payment Options (Low-Level Builder)

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Directly uses the builder pattern to add a credit card as a stored UPO for future payments. Requires merchant information, session token, user token, and card details.

```java
import com.safecharge.request.AddUPOCreditCardRequest;
import com.safecharge.request.SafechargeBaseRequest;
import com.safecharge.response.AddUPOCreditCardResponse;
import com.safecharge.model.MerchantInfo;
import com.safecharge.util.APIConstants;
import com.safecharge.util.Constants;

MerchantInfo merchantInfo = new MerchantInfo(
    "MERCHANT_SECRET_KEY", "MERCHANT_ID", "MERCHANT_SITE_ID",
    APIConstants.INTEGRATION_HOST, Constants.HashAlgorithm.SHA256
);

SafechargeBaseRequest request = AddUPOCreditCardRequest.builder()
    .addMerchantInfo(merchantInfo)
    .addSessionToken(sessionToken)
    .addUserTokenId("user_token_123")
    .addCcCardNumber("4111111111111111")
    .addCcExpMonth("12")
    .addCCExpYear("2026")
    .addCcNameOnCard("John Smith")
    .addBillingAddress(
        "John", "Smith", "123 Main St", "5551234567",
        "10001", "New York", "US", "NY",
        "john.smith@example.com", "en_US", "1985-06-15", ""
    )
    .build();

AddUPOCreditCardResponse response =
    (AddUPOCreditCardResponse) SafechargeRequestExecutor.getInstance().execute(request);

if (Constants.APIResponseStatus.SUCCESS.equals(response.getStatus())) {
    System.out.println("Card saved. UPO ID: " + response.getUserPaymentOptionId());
} else {
    System.err.println("Failed: " + response.getReason());
}
```

--------------------------------

### initPayment — Initialize Payment for 3DS Flows

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Initiates a payment process, typically used as the first step in a 3D Secure v2 flow before calling `authorize3d`.

```APIDOC
## initPayment — Initialize Payment for 3DS Flows

Initiates a payment process, typically used as the first step in a 3D Secure v2 flow before calling `authorize3d`.

```java
import com.safecharge.model.*;
import com.safecharge.response.InitPaymentResponse;

InitPaymentCard initCard = new InitPaymentCard();
initCard.setCardNumber("4111111111111111");
initCard.setCardHolderName("Jane Doe");
initCard.setExpirationMonth("06");
initCard.setExpirationYear("2027");
initCard.setCVV("456");

InitPaymentThreeD threeD = new InitPaymentThreeD();
threeD.setMethodNotificationUrl("https://example.com/3ds-method");

InitPaymentPaymentOption initPaymentOption = new InitPaymentPaymentOption();
initPaymentOption.setCard(initCard);

DeviceDetails deviceDetails = new DeviceDetails();
deviceDetails.setIpAddress("192.168.1.100");
deviceDetails.setBrowser("Chrome");

try {
    InitPaymentResponse response = safecharge.initPayment(
        "user_token_123",
        "unique_txn_002",
        "req_002",
        "USD",
        "49.00",
        deviceDetails,
        initPaymentOption,
        null,       // urlDetails
        null,       // customData
        null,       // billingAddress
        null,       // userId
        null,       // aftOverride
        null,       // recipientDetails
        null        // relatedTransactionId
    );

    System.out.println("Status: " + response.getStatus());
    System.out.println("Transaction ID: " + response.getTransactionId());
} catch (SafechargeException e) {
    System.err.println("Exception: " + e.getMessage());
}
```
```

--------------------------------

### Perform 3D Secure Authorization

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Initiates the 3D Secure v2 authorization process after `initPayment`. This method can return either a frictionless or challenge outcome. Ensure all card and 3D Secure parameters are correctly set.

```java
import com.safecharge.model.*;
import com.safecharge.response.Authorize3dResponse;
import com.safecharge.util.Constants;

Card card = new Card();
card.setCardNumber("4111111111111111");
card.setCardHolderName("Bob Brown");
card.setExpirationMonth("09");
card.setExpirationYear("2025");
card.setCVV("789");

V2AdditionalParams v2Params = new V2AdditionalParams();
v2Params.setChallengePreference("01");
v2Params.setNotificationUrl("https://example.com/3ds-notify");

ThreeD threeD = new ThreeD();
threeD.setV2AdditionalParams(v2Params);
card.setThreeD(threeD);

PaymentOption paymentOption = new PaymentOption();
paymentOption.setCard(card);

try {
    Authorize3dResponse response = safecharge.authorize3d(
        "user_token_bob",       // userTokenId
        "unique_3d_001",        // clientUniqueId
        "req_3d_001",           // clientRequestId
        paymentOption,
        0,                      // isRebilling
        "USD", "200.00",
        null, null,             // amountDetails, items
        null, null,             // deviceDetails, userDetails
        null, null,             // shippingAddress, billingAddress
        null, null, null,       // dynamicDescriptor, merchantDetails, addendums
        null, null, null,       // urlDetails, customSiteName, productId
        null,                   // customData
        "INIT_PAYMENT_TXN_ID",  // relatedTransactionId
        Constants.TransactionType.Sale,
        false, null, null,      // autoPayment3D, subMerchant, userId
        null, null, null, null  // externalSchemeDetails, currencyConversion, isPartialApproval, digitalAssetType
    );

    System.out.println("3D Status: " + response.getStatus());
    System.out.println("Transaction ID: " + response.getTransactionId());
} catch (SafechargeException e) {
    System.err.println("Exception: " + e.getMessage());
}
```

--------------------------------

### GetSubscriptionPlans

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Retrieves available subscription plans. This can be used to present different subscription options to customers.

```APIDOC
## POST GetSubscriptionPlans

### Description
Retrieves a list of available subscription plans offered by the merchant. This information can be used to present various subscription options and pricing tiers to customers.

### Method
POST

### Endpoint
getSubscriptionPlans.do

### Request Body
- **request** (GetSubscriptionPlansRequest) - Required - The request object, potentially containing filters or merchant identifiers, to retrieve subscription plans.
```

--------------------------------

### Create Order with OpenOrder

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Use this to create an order in SafeCharge's system without processing payment. Primarily used with the Web SDK (Cashier) to pre-load order details.

```java
import com.safecharge.model.*;
import com.safecharge.response.OpenOrderResponse;
import com.safecharge.util.Constants;

RestApiUserDetails userDetails = new RestApiUserDetails();
userDetails.setFirstName("Alice");
userDetails.setLastName("Johnson");
userDetails.setEmail("alice@example.com");
userDetails.setPhone("5551234567");
userDetails.setCountry("DE");
userDetails.setCity("Berlin");

UrlDetails urlDetails = new UrlDetails();
urlDetails.setSuccessUrl("https://shop.example.com/success");
urlDetails.setFailureUrl("https://shop.example.com/failure");
urlDetails.setNotificationUrl("https://shop.example.com/ipn");

try {
    OpenOrderResponse response = safecharge.openOrder(
        "user_token_alice",     // userTokenId
        "req_003",              // clientRequestId
        "order_003",            // clientUniqueId
        null,                   // customSiteName
        "PRODUCT-SKU-42",       // productId
        null,                   // paymentOption
        Constants.TransactionType.Sale,
        "EUR",
        "150.00",
        null,                   // items
        null,                   // deviceDetails
        userDetails,
        null,                   // shippingAddress
        null,                   // billingAddress
        null,                   // dynamicDescriptor
        null,                   // merchantDetails
        urlDetails,
        null, null, null, null, // userPaymentOption, paymentMethod, amountDetails, addendums
        null, false, null, null, null, 0, null, null, null, null,
        null, null, null, null, null, null, null
    );

    System.out.println("Order token: " + response.getSessionToken());
    System.out.println("Order ID: " + response.getOrderId());
} catch (SafechargeException e) {
    System.err.println("Exception: " + e.getMessage());
}
```

--------------------------------

### initPayment

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Initializes a payment process, often used as the first step in a multi-phase transaction flow, such as 3D Secure authentication.

```APIDOC
## POST initPayment

### Description
Initializes a payment process. This endpoint is typically the first step in multi-phase transaction flows, such as those involving 3D Secure authentication, preparing the system for subsequent actions.

### Method
POST

### Endpoint
initPayment.do

### Request Body
- **request** (InitPaymentRequest) - Required - The request object containing parameters to initiate the payment.
```

--------------------------------

### Custom HTTP Client Configuration

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Builds a custom Apache HttpClient for the request executor, allowing configuration of timeouts, connection pooling, proxy, and SSL. Use defaults or customize as needed.

```java
import com.safecharge.biz.SafechargeClientBuilder;
import com.safecharge.biz.SafechargeRequestExecutor;
import com.safecharge.model.Proxy;
import org.apache.http.client.HttpClient;
import java.util.concurrent.TimeUnit;

// Option 1: Use defaults
SafechargeRequestExecutor executor = SafechargeRequestExecutor.getInstance();
executor.init(); // initializes with default 30s timeout, 100 max connections

// Option 2: Custom configuration
HttpClient customClient = new SafechargeClientBuilder()
    .setDefaultRequestConfig()          // 30s socket/connect/request timeouts
    .setDefaultConnectionManager()      // pooling: max 100 total, 10 per route
    .setDefaultSSLSocketFactory()       // TLSv1.1 / TLSv1.2
    .setConnectionTTL(60, TimeUnit.SECONDS)
    .build();

executor.init(customClient);

// Option 3: With proxy
Proxy proxy = new Proxy();
proxy.setHost("proxy.example.com");
proxy.setPort(8080);
proxy.setProtocol("http");

HttpClient proxyClient = new SafechargeClientBuilder()
    .setDefaultRequestConfig()
    .setDefaultConnectionManager()
    .setDefaultSSLSocketFactory()
    .setProxy(proxy)
    .build();

executor.init(proxyClient);
```

--------------------------------

### Perform a Unified Payment with Card

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Use this for the primary payment endpoint to process various payment types like credit cards. Ensure all required fields for card, billing address, and URL details are populated.

```java
import com.safecharge.model.*;
import com.safecharge.response.PaymentResponse;
import com.safecharge.util.Constants;

// Build card payment option
Card card = new Card();
card.setCardNumber("4111111111111111");
card.setCardHolderName("John Smith");
card.setExpirationMonth("12");
card.setExpirationYear("2026");
card.setCVV("123");

PaymentOption paymentOption = new PaymentOption();
paymentOption.setCard(card);

// Build billing address
UserAddress billingAddress = new UserAddress();
billingAddress.setFirstName("John");
billingAddress.setLastName("Smith");
billingAddress.setEmail("john.smith@example.com");
billingAddress.setCountry("US");
billingAddress.setCity("New York");

// Build URL details for DMN callbacks
UrlDetails urlDetails = new UrlDetails();
urlDetails.setSuccessUrl("https://example.com/success");
urlDetails.setFailureUrl("https://example.com/failure");
urlDetails.setNotificationUrl("https://example.com/dmn");

try {
    PaymentResponse response = safecharge.payment(
        "user_token_123",       // userTokenId
        "unique_txn_001",       // clientUniqueId
        "req_001",              // clientRequestId
        paymentOption,
        0,                      // isRebilling (0 = initial)
        "USD",                  // currency
        "99.99",                // amount
        null,                   // amountDetails
        null,                   // items
        null,                   // deviceDetails
        null,                   // userDetails
        null,                   // shippingAddress
        billingAddress,
        null,                   // dynamicDescriptor
        null,                   // merchantDetails
        null,                   // addendums
        urlDetails,
        null, null, null, null, // customSiteName, productId, customData, relatedTransactionId
        Constants.TransactionType.Sale,
        false,                  // autoPayment3D
        null, null, null, null, // isMoto, subMerchant, rebillingType, authenticationOnlyType
        null, null, null, null, // userId, externalSchemeDetails, currencyConversion, isPartialApproval
        null, null, null, null, // paymentFlow, redirectFlowUITheme, aftOverride, recipientDetails
        null, null, null, null, null // companyDetails, shippingTrackingDetails, cvvNotUsed, serviceDueDate, digitalAssetType
    );

    if (Constants.APIResponseStatus.SUCCESS.equals(response.getStatus())) {
        System.out.println("Payment approved! Transaction ID: " + response.getTransactionId());
    } else {
        System.err.println("Payment failed: " + response.getReason());
    }
} catch (SafechargeException e) {
    System.err.println("Exception: " + e.getMessage());
}
```

--------------------------------

### CreateUser

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Creates a new user profile. This endpoint is used to register new users within the system.

```APIDOC
## POST CreateUser

### Description
Creates a new user profile within the system. This endpoint is used for registering new customers or users who will interact with the payment services.

### Method
POST

### Endpoint
createUser.do

### Request Body
- **request** (CreateUserRequest) - Required - The request object containing the details for the new user.
```

--------------------------------

### openOrder

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Opens a new order. This is used to create an order record before proceeding with payment or other related actions.

```APIDOC
## POST openOrder

### Description
Opens a new order. This endpoint is used to create an order record in the system, which can then be associated with subsequent payment or fulfillment actions.

### Method
POST

### Endpoint
openOrder.do

### Request Body
- **request** (OpenOrderRequest) - Required - The request object containing details for opening a new order.
```

--------------------------------

### addUpoApm

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Adds an alternative payment method (e.g., PayPal, Neteller, Skrill) to a user's saved payment options.

```APIDOC
## addUpoApm — Add APM to User Payment Options

Adds an alternative payment method (e.g., PayPal, Neteller, Skrill) to a user's saved payment options.

```java
import java.util.HashMap;
import java.util.Map;
import com.safecharge.model.UserDetailsCashier;
import com.safecharge.response.AddUPOAPMResponse;

Map<String, String> apmData = new HashMap<>();
apmData.put("email", "user@paypal.example.com");  // PayPal account email

try {
    AddUPOAPMResponse response = safecharge.addUpoApm(
        "user_token_123",       // userTokenId
        "apmgw_PayPal",         // paymentMethodName
        apmData,
        null                    // billingAddress (optional)
    );

    System.out.println("UPO added. UPO ID: " + response.getUserPaymentOptionId());
} catch (SafechargeException e) {
    System.err.println("Exception: " + e.getMessage());
}
```
```

--------------------------------

### openOrder

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Creates an order in SafeCharge's system without processing payment. Primarily used with the Web SDK (Cashier) to pre-load order details.

```APIDOC
## openOrder — Create an Order

Creates an order in SafeCharge's system without processing payment. Primarily used with the Web SDK (Cashier) to pre-load order details.

```java
import com.safecharge.model.*;
import com.safecharge.response.OpenOrderResponse;
import com.safecharge.util.Constants;

RestApiUserDetails userDetails = new RestApiUserDetails();
userDetails.setFirstName("Alice");
userDetails.setLastName("Johnson");
userDetails.setEmail("alice@example.com");
userDetails.setPhone("5551234567");
userDetails.setCountry("DE");
userDetails.setCity("Berlin");

UrlDetails urlDetails = new UrlDetails();
urlDetails.setSuccessUrl("https://shop.example.com/success");
urlDetails.setFailureUrl("https://shop.example.com/failure");
urlDetails.setNotificationUrl("https://shop.example.com/ipn");

try {
    OpenOrderResponse response = safecharge.openOrder(
        "user_token_alice",     // userTokenId
        "req_003",              // clientRequestId
        "order_003",            // clientUniqueId
        null,                   // customSiteName
        "PRODUCT-SKU-42",       // productId
        null,                   // paymentOption
        Constants.TransactionType.Sale,
        "EUR",
        "150.00",
        null,                   // items
        null,                   // deviceDetails
        userDetails,
        null,                   // shippingAddress
        null,                   // billingAddress
        null,                   // dynamicDescriptor
        null,                   // merchantDetails
        urlDetails,
        null, null, null, null, // userPaymentOption, paymentMethod, amountDetails, addendums
        null, false, null, null, null, 0, null, null, null, null,
        null, null, null, null, null, null, null
    );

    System.out.println("Order token: " + response.getSessionToken());
    System.out.println("Order ID: " + response.getOrderId());
} catch (SafechargeException e) {
    System.err.println("Exception: " + e.getMessage());
}
```
```

--------------------------------

### List Available Merchant Payment Methods

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Retrieves enabled payment methods for the merchant. Can be filtered by country, currency, and language. Useful for displaying available payment options to users.

```java
import com.safecharge.response.GetMerchantPaymentMethodsResponse;

try {
    GetMerchantPaymentMethodsResponse response = safecharge.getMerchantPaymentMethods(
        "req_pm_001",   // clientRequestId
        "USD",          // currencyCode
        "US",           // countryCode
        "en",           // languageCode
        "DEPOSIT"       // type: DEPOSIT or WITHDRAWAL
    );

    if (Constants.APIResponseStatus.SUCCESS.equals(response.getStatus())) {
        response.getPaymentMethods().forEach(pm ->
            System.out.println("Method: " + pm.getPaymentMethod() + ", ID: " + pm.getPaymentMethodDisplayName())
        );
    }
} catch (SafechargeException e) {
    System.err.println("Exception: " + e.getMessage());
}
```

--------------------------------

### Add APM to User Payment Options

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Adds an alternative payment method (e.g., PayPal, Neteller, Skrill) to a user's saved payment options. Requires user token, payment method name, and APM-specific data.

```java
import java.util.HashMap;
import java.util.Map;
import com.safecharge.model.UserDetailsCashier;
import com.safecharge.response.AddUPOAPMResponse;

Map<String, String> apmData = new HashMap<>();
apmData.put("email", "user@paypal.example.com");  // PayPal account email

try {
    AddUPOAPMResponse response = safecharge.addUpoApm(
        "user_token_123",       // userTokenId
        "apmgw_PayPal",         // paymentMethodName
        apmData,
        null                    // billingAddress (optional)
    );

    System.out.println("UPO added. UPO ID: " + response.getUserPaymentOptionId());
} catch (SafechargeException e) {
    System.err.println("Exception: " + e.getMessage());
}
```

--------------------------------

### AddUPOCreditCardRequest

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Directly uses the builder pattern to add a credit card as a stored UPO for future payments.

```APIDOC
## AddUPOCreditCardRequest — Add Credit Card to User Payment Options (Low-Level Builder)

Directly uses the builder pattern to add a credit card as a stored UPO for future payments.

```java
import com.safecharge.request.AddUPOCreditCardRequest;
import com.safecharge.request.SafechargeBaseRequest;
import com.safecharge.response.AddUPOCreditCardResponse;
import com.safecharge.model.MerchantInfo;
import com.safecharge.util.APIConstants;
import com.safecharge.util.Constants;

MerchantInfo merchantInfo = new MerchantInfo(
    "MERCHANT_SECRET_KEY", "MERCHANT_ID", "MERCHANT_SITE_ID",
    APIConstants.INTEGRATION_HOST, Constants.HashAlgorithm.SHA256
);

SafechargeBaseRequest request = AddUPOCreditCardRequest.builder()
    .addMerchantInfo(merchantInfo)
    .addSessionToken(sessionToken)
    .addUserTokenId("user_token_123")
    .addCcCardNumber("4111111111111111")
    .addCcExpMonth("12")
    .addCCExpYear("2026")
    .addCcNameOnCard("John Smith")
    .addBillingAddress(
        "John", "Smith", "123 Main St", "5551234567",
        "10001", "New York", "US", "NY",
        "john.smith@example.com", "en_US", "1985-06-15", ""
    )
    .build();

AddUPOCreditCardResponse response =
    (AddUPOCreditCardResponse) SafechargeRequestExecutor.getInstance().execute(request);

if (Constants.APIResponseStatus.SUCCESS.equals(response.getStatus())) {
    System.out.println("Card saved. UPO ID: " + response.getUserPaymentOptionId());
} else {
    System.err.println("Failed: " + response.getReason());
}
```
```

--------------------------------

### EnableUPO

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Enables a suspended User Payment Option (UPO) entry. This reactivates a previously suspended payment method.

```APIDOC
## POST EnableUPO

### Description
Enables a suspended User Payment Option (UPO) entry. This action reactivates a payment method that was previously suspended, allowing it to be used for transactions again.

### Method
POST

### Endpoint
enableUPO.do

### Request Body
- **request** (EnableUPORequest) - Required - The request object specifying which UPO entry to enable.
```

--------------------------------

### authorize3d

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Performs the authorization step in a 3D Secure v2 flow after initPayment. This method can return either a frictionless or a challenge outcome, depending on the authentication process.

```APIDOC
## authorize3d — 3D Secure Authorization

Performs the authorization step in a 3D Secure v2 flow after `initPayment`. Returns frictionless or challenge outcome.

```java
import com.safecharge.model.*;
import com.safecharge.response.Authorize3dResponse;
import com.safecharge.util.Constants;

Card card = new Card();
card.setCardNumber("4111111111111111");
card.setCardHolderName("Bob Brown");
card.setExpirationMonth("09");
card.setExpirationYear("2025");
card.setCVV("789");

V2AdditionalParams v2Params = new V2AdditionalParams();
v2Params.setChallengePreference("01");
v2Params.setNotificationUrl("https://example.com/3ds-notify");

ThreeD threeD = new ThreeD();
threeD.setV2AdditionalParams(v2Params);
card.setThreeD(threeD);

PaymentOption paymentOption = new PaymentOption();
paymentOption.setCard(card);

try {
    Authorize3dResponse response = safecharge.authorize3d(
        "user_token_bob",       // userTokenId
        "unique_3d_001",        // clientUniqueId
        "req_3d_001",           // clientRequestId
        paymentOption,
        0,                      // isRebilling
        "USD", "200.00",
        null, null,             // amountDetails, items
        null, null,             // deviceDetails, userDetails
        null, null,             // shippingAddress, billingAddress
        null, null, null,       // dynamicDescriptor, merchantDetails, addendums
        null, null, null,       // urlDetails, customSiteName, productId
        null,                   // customData
        "INIT_PAYMENT_TXN_ID",  // relatedTransactionId
        Constants.TransactionType.Sale,
        false, null, null,      // autoPayment3D, subMerchant, userId
        null, null, null, null  // externalSchemeDetails, currencyConversion, isPartialApproval, digitalAssetType
    );

    System.out.println("3D Status: " + response.getStatus());
    System.out.println("Transaction ID: " + response.getTransactionId());
} catch (SafechargeException e) {
    System.err.println("Exception: " + e.getMessage());
}
```
```

--------------------------------

### getCardDetails

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Returns card type, brand, and the card's billing currency for Dynamic Currency Conversion (DCC).

```APIDOC
## getCardDetails — Retrieve Card Details and DCC Currency

Returns card type, brand, and the card's billing currency for Dynamic Currency Conversion (DCC).

```java
import com.safecharge.response.CardDetailsResponse;

try {
    CardDetailsResponse response = safecharge.getCardDetails(
        "unique_cd_001",    // clientUniqueId
        "req_cd_001",       // clientRequestId
        "411111"            // cardNumber or BIN
    );

    System.out.println("Card type: " + response.getCardType());
    System.out.println("Card brand: " + response.getBrand());
    System.out.println("Issuer country: " + response.getIssuerCountry());
} catch (SafechargeException e) {
    System.err.println("Exception: " + e.getMessage());
}
```
```

--------------------------------

### SafechargeClientBuilder

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Builds a custom Apache HttpClient for the request executor, allowing configuration of timeouts, connection pooling, proxy, and SSL.

```APIDOC
## SafechargeClientBuilder — Custom HTTP Client Configuration

Builds a custom Apache `HttpClient` for the request executor, allowing configuration of timeouts, connection pooling, proxy, and SSL.

```java
import com.safecharge.biz.SafechargeClientBuilder;
import com.safecharge.biz.SafechargeRequestExecutor;
import com.safecharge.model.Proxy;
import org.apache.http.client.HttpClient;
import java.util.concurrent.TimeUnit;

// Option 1: Use defaults
SafechargeRequestExecutor executor = SafechargeRequestExecutor.getInstance();
executor.init(); // initializes with default 30s timeout, 100 max connections

// Option 2: Custom configuration
HttpClient customClient = new SafechargeClientBuilder()
    .setDefaultRequestConfig()          // 30s socket/connect/request timeouts
    .setDefaultConnectionManager()      // pooling: max 100 total, 10 per route
    .setDefaultSSLSocketFactory()       // TLSv1.1 / TLSv1.2
    .setConnectionTTL(60, TimeUnit.SECONDS)
    .build();

executor.init(customClient);

// Option 3: With proxy
Proxy proxy = new Proxy();
proxy.setHost("proxy.example.com");
proxy.setPort(8080);
proxy.setProtocol("http");

HttpClient proxyClient = new SafechargeClientBuilder()
    .setDefaultRequestConfig()
    .setDefaultConnectionManager()
    .setDefaultSSLSocketFactory()
    .setProxy(proxy)
    .build();

executor.init(proxyClient);
```
```

--------------------------------

### accountCapture

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Captures bank account details from a consumer and stores them as a UPO for subsequent payout operations.

```APIDOC
## accountCapture — Capture Bank Account for Payout

Captures bank account details from a consumer and stores them as a UPO for subsequent payout operations.

```java
import com.safecharge.model.*;
import com.safecharge.response.AccountCaptureResponse;

UserDetails userDetails = new UserDetails();
userDetails.setFirstName("Carol");
userDetails.setLastName("White");
userDetails.setEmail("carol@example.com");
userDetails.setCountry("DE");

try {
    AccountCaptureResponse response = safecharge.accountCapture(
        "req_ac_001",           // clientRequestId
        "user_token_carol",     // userTokenId
        "apmgw_SEPA",           // paymentMethod
        "EUR",                  // currencyCode
        "DE",                   // country
        "de",                   // languageCode
        "0",                    // amount (0 = verification only)
        "https://example.com/ac-dmn", // notificationUrl
        null,                   // deviceDetails
        userDetails,
        null                    // urlDetails
    );

    System.out.println("Account capture status: " + response.getStatus());
    System.out.println("Redirect URL: " + response.getRedirectURL());
} catch (SafechargeException e) {
    System.err.println("Exception: " + e.getMessage());
}
```
```

--------------------------------

### Retrieve Card Details and DCC Currency

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Returns card type, brand, and the card's billing currency for Dynamic Currency Conversion (DCC). Requires client unique ID, client request ID, and card number or BIN.

```java
import com.safecharge.response.CardDetailsResponse;

try {
    CardDetailsResponse response = safecharge.getCardDetails(
        "unique_cd_001",    // clientUniqueId
        "req_cd_001",       // clientRequestId
        "411111"            // cardNumber or BIN
    );

    System.out.println("Card type: " + response.getCardType());
    System.out.println("Card brand: " + response.getBrand());
    System.out.println("Issuer country: " + response.getIssuerCountry());
} catch (SafechargeException e) {
    System.err.println("Exception: " + e.getMessage());
}
```

--------------------------------

### GetUserUPOs

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Retrieves a list of all User Payment Options (UPOs) for a specific user. Useful for displaying saved payment methods.

```APIDOC
## POST GetUserUPOs

### Description
Retrieves a list of all User Payment Options (UPOs) associated with a specific user. This is commonly used to display a user's saved payment methods during checkout or in their account settings.

### Method
POST

### Endpoint
getUserUPOs.do

### Request Body
- **request** (GetUserUPOsRequest) - Required - The request object containing user identification details.
```

--------------------------------

### Verify 3D Secure Challenge Result

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Call this after a 3D Secure challenge to verify the result before completing payment. Ensure all required card and billing details are provided.

```java
import com.safecharge.model.*;
import com.safecharge.response.Verify3dResponse;

Verify3dCard verify3dCard = new Verify3dCard();
verify3dCard.setCardNumber("4111111111111111");
verify3dCard.setCardHolderName("Bob Brown");
verify3dCard.setExpirationMonth("09");
verify3dCard.setExpirationYear("2025");
verify3dCard.setCVV("789");

Verify3dPaymentOption paymentOption = new Verify3dPaymentOption();
paymentOption.setCard(verify3dCard);

UserAddress billing = new UserAddress();
billing.setFirstName("Bob");
billing.setLastName("Brown");
billing.setCountry("GB");

try {
    Verify3dResponse response = safecharge.verify3d(
        "unique_v3d_001",       // clientUniqueId
        "req_v3d_001",          // clientRequestId
        "200.00", "USD",
        billing,
        null, null, null,       // customData, customSiteName, merchantDetails
        "AUTH_3D_TXN_ID",       // relatedTransactionId
        null,                   // subMerchant
        null, "user_token_bob", // userId, userTokenId
        paymentOption,
        null                    // digitalAssetType
    );

    System.out.println("Verify3D status: " + response.getStatus());
    System.out.println("ECI: " + response.getPaymentOption().getCard().getThreeD().getEci());
} catch (SafechargeException e) {
    System.err.println("Exception: " + e.getMessage());
}
```

--------------------------------

### CreateSubscription

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Creates a new subscription for a customer. This is used for recurring billing scenarios.

```APIDOC
## POST CreateSubscription

### Description
Creates a new subscription for a customer. This endpoint is essential for setting up recurring billing arrangements, such as monthly service fees or membership renewals.

### Method
POST

### Endpoint
createSubscription.do

### Request Body
- **request** (CreateSubscriptionRequest) - Required - The request object containing the details for creating the subscription.
```

--------------------------------

### Obtain Session Token (Low-Level)

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Use `SafechargeRequestExecutor` to obtain a session token, which is required for all subsequent API calls. This method is for direct use of the executor and requires manual construction of the request.

```java
import com.safecharge.biz.SafechargeRequestExecutor;
import com.safecharge.model.MerchantInfo;
import com.safecharge.request.GetSessionTokenRequest;
import com.safecharge.response.SafechargeResponse;
import com.safecharge.util.APIConstants;
import com.safecharge.util.Constants;

MerchantInfo merchantInfo = new MerchantInfo(
    "MERCHANT_SECRET_KEY",
    "MERCHANT_ID",
    "MERCHANT_SITE_ID",
    APIConstants.INTEGRATION_HOST,
    Constants.HashAlgorithm.SHA256
);

SafechargeRequestExecutor executor = SafechargeRequestExecutor.getInstance();

SafechargeResponse tokenResponse = executor.executeRequest(
    GetSessionTokenRequest.builder()
        .addMerchantInfo(merchantInfo)
        .build()
);

if (Constants.APIResponseStatus.SUCCESS.equals(tokenResponse.getStatus())) {
    String sessionToken = tokenResponse.getSessionToken();
    System.out.println("Session token: " + sessionToken);
} else {
    System.err.println("Error " + tokenResponse.getErrCode() + ": " + tokenResponse.getReason());
}
```

--------------------------------

### Capture Bank Account for Payout

Source: https://context7.com/nuvei/nuvei-server-java/llms.txt

Captures bank account details from a consumer and stores them as a UPO for subsequent payout operations. Requires user details and a notification URL.

```java
import com.safecharge.model.*;
import com.safecharge.response.AccountCaptureResponse;

UserDetails userDetails = new UserDetails();
userDetails.setFirstName("Carol");
userDetails.setLastName("White");
userDetails.setEmail("carol@example.com");
userDetails.setCountry("DE");

try {
    AccountCaptureResponse response = safecharge.accountCapture(
        "req_ac_001",           // clientRequestId
        "user_token_carol",     // userTokenId
        "apmgw_SEPA",           // paymentMethod
        "EUR",                  // currencyCode
        "DE",                   // country
        "de",                   // languageCode
        "0",                    // amount (0 = verification only)
        "https://example.com/ac-dmn", // notificationUrl
        null,                   // deviceDetails
        userDetails,
        null                    // urlDetails
    );

    System.out.println("Account capture status: " + response.getStatus());
    System.out.println("Redirect URL: " + response.getRedirectURL());
} catch (SafechargeException e) {
    System.err.println("Exception: " + e.getMessage());
}
```