### Build iyzipay-java using Maven Wrapper

Source: https://github.com/iyzico/iyzipay-java/blob/master/README.md

This command demonstrates how to build the iyzipay-java project using the Maven Wrapper script, which is useful if Maven is not installed locally. It cleans and installs the project.

```bash
./mvnw clean install
```

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

### Manual JAR Installation Dependencies for iyzipay-java

Source: https://github.com/iyzico/iyzipay-java/blob/master/README.md

This section lists the JAR files required for manual installation of the iyzipay-java library and its dependencies, Gson and Commons Lang. It provides links to download specific versions.

```text
* The iyzipay JAR from https://github.com/iyzico/iyzipay-java/releases/latest
* Gson 2.5 from http://mvnrepository.com/artifact/com.google.code.gson/gson/2.5
* Commons lang 3.4 from http://mvnrepository.com/artifact/org.apache.commons/commons-lang3/3.4
```

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

### Get Installment Options using iyzipay-java

Source: https://context7.com/iyzico/iyzipay-java/llms.txt

Fetches available installment payment options for a given card BIN and purchase price. It returns details for each bank, including available installment numbers and total prices for each option. Requires the BIN number and price.

```java
import com.iyzipay.model.InstallmentInfo;
import com.iyzipay.model.Locale;
import com.iyzipay.request.RetrieveInstallmentInfoRequest;
import java.math.BigDecimal;

RetrieveInstallmentInfoRequest request = new RetrieveInstallmentInfoRequest();
request.setLocale(Locale.TR.getValue());
request.setConversationId("123456789");
request.setBinNumber("554960");
request.setPrice(new BigDecimal("100"));

InstallmentInfo installmentInfo = InstallmentInfo.retrieve(request, options);

if (Status.SUCCESS.getValue().equals(installmentInfo.getStatus())) {
    for (var detail : installmentInfo.getInstallmentDetails()) {
        System.out.println("Bank: " + detail.getBankName());
        for (var price : detail.getInstallmentPrices()) {
            System.out.println("  Installment: " + price.getInstallmentNumber());
            System.out.println("  Total Price: " + price.getTotalPrice());
        }
    }
}
```

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

### Initialize Checkout Form with Java

Source: https://context7.com/iyzico/iyzipay-java/llms.txt

Initializes iyzico's hosted payment page, providing a secure checkout experience. It returns a payment page URL and embeddable content. This requires a CreateCheckoutFormInitializeRequest with payment details, buyer information, and enabled installment options.

```java
import com.iyzipay.model.*;
import com.iyzipay.request.CreateCheckoutFormInitializeRequest;
import java.math.BigDecimal;
import java.util.ArrayList;
import java.util.List;

CreateCheckoutFormInitializeRequest request = new CreateCheckoutFormInitializeRequest();
request.setLocale(Locale.TR.getValue());
request.setConversationId("123456789");
request.setPrice(new BigDecimal("1"));
request.setPaidPrice(new BigDecimal("1.2"));
request.setCurrency(Currency.TRY.name());
request.setBasketId("B67832");
request.setPaymentGroup(PaymentGroup.PRODUCT.name());
request.setCallbackUrl("https://www.merchant.com/callback");
request.setDebitCardAllowed(Boolean.TRUE);

List<Integer> enabledInstallments = new ArrayList<Integer>();
enabledInstallments.add(2);
enabledInstallments.add(3);
enabledInstallments.add(6);
enabledInstallments.add(9);
request.setEnabledInstallments(enabledInstallments);

// Set buyer, addresses, and basket items
Buyer buyer = new Buyer();
buyer.setId("BY789");
buyer.setName("John");
buyer.setSurname("Doe");
buyer.setEmail("email@email.com");
buyer.setIdentityNumber("74300864791");
buyer.setIp("85.34.78.112");
buyer.setCity("Istanbul");
buyer.setCountry("Turkey");
request.setBuyer(buyer);

// ... set addresses and basket items ...

CheckoutFormInitialize checkoutFormInitialize = CheckoutFormInitialize.create(request, options);

if (Status.SUCCESS.getValue().equals(checkoutFormInitialize.getStatus())) {
    String checkoutFormContent = checkoutFormInitialize.getCheckoutFormContent();
    String paymentPageUrl = checkoutFormInitialize.getPaymentPageUrl();
    System.out.println("Payment Page URL: " + paymentPageUrl);
}
```

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

### GET /payment/retrieve - Retrieve Payment Details

Source: https://context7.com/iyzico/iyzipay-java/llms.txt

This endpoint allows you to retrieve the details of a previously processed payment. You can search for a payment using either its unique payment ID or its conversation ID.

```APIDOC
## GET /payment/retrieve - Retrieve Payment Details

### Description
Retrieve details of a previously processed payment using payment ID or conversation ID.

### Method
GET

### Endpoint
/payment/retrieve

### Parameters
#### Query Parameters
- **locale** (string) - Optional - The locale for the request (e.g., 'tr').
- **conversationId** (string) - Required - A unique identifier for the conversation.
- **paymentId** (string) - Optional - The unique identifier for the payment.
- **paymentConversationId** (string) - Optional - The conversation ID associated with the payment.

### Request Example
```json
{
  "locale": "tr",
  "conversationId": "123456789",
  "paymentId": "1",
  "paymentConversationId": "123456789"
}
```

### Response
#### Success Response (200)
- **status** (string) - The status of the payment (e.g., 'SUCCESS').
- **paymentStatus** (string) - The current status of the payment.
- **price** (string) - The original price of the payment.
- **currency** (string) - The currency of the payment.
- **errorMessage** (string) - Error message if the retrieval failed.

#### Response Example
```json
{
  "status": "SUCCESS",
  "paymentStatus": "SUCCESSFUL",
  "price": "1",
  "currency": "TRY",
  "errorMessage": null
}
```
```

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

### Run Maven Tests with Specific Parameters

Source: https://github.com/iyzico/iyzipay-java/blob/master/README.md

These commands demonstrate how to run specific test classes or methods within the iyzipay-java project using Maven. They allow you to specify the base URL, API key, and secret key for the test environment. This is useful for targeted testing of payment or APM functionalities.

```bash
mvn test -Dtest=PaymentSample -DbaseUrl=https://sandbox-api.iyzipay.com -DapiKey=yourApiKey -DsecretKey=yourSecretKey
mvn test -Dtest=PaymentSample#should_create_payment -DbaseUrl=https://sandbox-api.iyzipay.com -DapiKey=yourApiKey -DsecretKey=yourSecretKey
./mvnw test -Dtest=PaymentSample -DbaseUrl=https://sandbox-api.iyzipay.com -DapiKey=yourApiKey -DsecretKey=yourSecretKey
./mvnw test -Dtest=PaymentSample#should_create_payment -DbaseUrl=https://sandbox-api.iyzipay.com -DapiKey=yourApiKey -DsecretKey=yourSecretKey
```

```bash
mvn test -Dtest=ApmSample -DbaseUrl=https://sandbox-api.iyzipay.com -DapiKey=yourApiKey -DsecretKey=yourSecretKey
mvn test -Dtest=ApmSample#should_initialize_apm_payment -DbaseUrl=https://sandbox-api.iyzipay.com -DapiKey=yourApiKey -DsecretKey=yourSecretKey
./mvnw test -Dtest=ApmSample -DbaseUrl=https://sandbox-api.iyzipay.com -DapiKey=yourApiKey -DsecretKey=yourSecretKey
./mvnw test -Dtest=ApmSample#should_initialize_apm_payment -DbaseUrl=https://sandbox-api.iyzipay.com -DapiKey=yourApiKey -DsecretKey=yourSecretKey
```

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

### Initialize 3D Secure Payment with Java

Source: https://context7.com/iyzico/iyzipay-java/llms.txt

Initializes a 3D Secure payment flow by creating a payment request and calling the ThreedsInitialize.create method. It returns HTML content for user redirection to the bank's authentication page. Requires payment details, card information, buyer details, and iyzico options.

```java
import com.iyzipay.model.*;
import com.iyzipay.request.CreatePaymentRequest;
import java.math.BigDecimal;
import java.util.ArrayList;
import java.util.List;

CreatePaymentRequest request = new CreatePaymentRequest();
request.setLocale(Locale.TR.getValue());
request.setConversationId("123456789");
request.setPrice(new BigDecimal("1"));
request.setPaidPrice(new BigDecimal("1.2"));
request.setCurrency(Currency.TRY.name());
request.setInstallment(1);
request.setBasketId("B67832");
request.setPaymentChannel(PaymentChannel.WEB.name());
request.setPaymentGroup(PaymentGroup.PRODUCT.name());
request.setCallbackUrl("https://www.merchant.com/callback");

PaymentCard paymentCard = new PaymentCard();
paymentCard.setCardHolderName("John Doe");
paymentCard.setCardNumber("5528790000000008");
paymentCard.setExpireMonth("12");
paymentCard.setExpireYear("2030");
paymentCard.setCvc("123");
paymentCard.setRegisterCard(0);
request.setPaymentCard(paymentCard);

// Set buyer, addresses, and basket items as shown in Payment.create example
Buyer buyer = new Buyer();
buyer.setId("BY789");
buyer.setName("John");
buyer.setSurname("Doe");
buyer.setEmail("email@email.com");
buyer.setIdentityNumber("74300864791");
buyer.setIp("85.34.78.112");
buyer.setCity("Istanbul");
buyer.setCountry("Turkey");
request.setBuyer(buyer);

// ... set addresses and basket items ...

ThreedsInitialize threedsInitialize = ThreedsInitialize.create(request, options);

if (Status.SUCCESS.getValue().equals(threedsInitialize.getStatus())) {
    // Decode and render HTML content to redirect user to 3DS page
    String htmlContent = threedsInitialize.getHtmlContent();
    boolean signatureValid = threedsInitialize.verifySignature(options.getSecretKey());
    System.out.println("3DS HTML Content received, signature valid: " + signatureValid);
}
```

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

### ThreedsInitialize.create - Initialize 3D Secure Payment

Source: https://context7.com/iyzico/iyzipay-java/llms.txt

Initializes a 3D Secure payment flow. This method returns HTML content that should be used to redirect the user to the bank's 3DS authentication page.

```APIDOC
## POST /payment/initialize/3ds

### Description
Initializes a 3D Secure payment flow. Returns HTML content to redirect the user to the bank's 3DS authentication page.

### Method
POST

### Endpoint
/payment/initialize/3ds

### Parameters
#### Request Body
- **locale** (string) - Required - The locale for the transaction (e.g., 'tr', 'en').
- **conversationId** (string) - Required - Unique identifier for the conversation.
- **price** (decimal) - Required - The total price of the transaction.
- **paidPrice** (decimal) - Required - The price to be paid after discounts/fees.
- **currency** (string) - Required - The currency of the transaction (e.g., 'TRY', 'EUR').
- **installment** (integer) - Optional - The number of installments.
- **basketId** (string) - Required - Unique identifier for the basket.
- **paymentChannel** (string) - Required - The payment channel (e.g., 'WEB', 'MOBILE').
- **paymentGroup** (string) - Required - The payment group (e.g., 'PRODUCT', 'LISTING').
- **callbackUrl** (string) - Required - The URL to redirect the user after payment.
- **paymentCard** (object) - Required - Details of the payment card.
  - **cardHolderName** (string) - Required - Name of the cardholder.
  - **cardNumber** (string) - Required - The credit card number.
  - **expireMonth** (string) - Required - Expiry month of the card (MM).
  - **expireYear** (string) - Required - Expiry year of the card (YYYY).
  - **cvc** (string) - Required - The CVC code of the card.
  - **registerCard** (integer) - Optional - Whether to register the card (1 for yes, 0 for no).
- **buyer** (object) - Required - Information about the buyer.
  - **id** (string) - Required - Buyer's unique identifier.
  - **name** (string) - Required - Buyer's first name.
  - **surname** (string) - Required - Buyer's last name.
  - **email** (string) - Required - Buyer's email address.
  - **identityNumber** (string) - Required - Buyer's identity number.
  - **ip** (string) - Required - Buyer's IP address.
  - **city** (string) - Required - Buyer's city.
  - **country** (string) - Required - Buyer's country.

### Request Example
```json
{
  "locale": "tr",
  "conversationId": "123456789",
  "price": "1",
  "paidPrice": "1.2",
  "currency": "TRY",
  "installment": 1,
  "basketId": "B67832",
  "paymentChannel": "WEB",
  "paymentGroup": "PRODUCT",
  "callbackUrl": "https://www.merchant.com/callback",
  "paymentCard": {
    "cardHolderName": "John Doe",
    "cardNumber": "5528790000000008",
    "expireMonth": "12",
    "expireYear": "2030",
    "cvc": "123",
    "registerCard": 0
  },
  "buyer": {
    "id": "BY789",
    "name": "John",
    "surname": "Doe",
    "email": "email@email.com",
    "identityNumber": "74300864791",
    "ip": "85.34.78.112",
    "city": "Istanbul",
    "country": "Turkey"
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - Status of the operation ('success' or 'failure').
- **htmlContent** (string) - HTML content to redirect the user to the bank's 3DS page.
- **signature** (string) - Signature of the response for verification.

#### Response Example
```json
{
  "status": "success",
  "htmlContent": "<html>...</html>",
  "signature": "..."
}
```
```

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

### Create Payment Request in Java using iyzipay-java

Source: https://github.com/iyzico/iyzipay-java/blob/master/README.md

This comprehensive Java code snippet illustrates how to create a payment request using the iyzipay-java library. It configures options, payment details, card information, buyer details, addresses, and basket items before initiating the payment creation process.

```java
Options options = new Options();
options.setApiKey("your api key");
options.setSecretKey("your secret key");
options.setBaseUrl("https://sandbox-api.iyzipay.com");

CreatePaymentRequest request = new CreatePaymentRequest();
request.setLocale(Locale.TR.getValue());
request.setConversationId("123456789");
request.setPrice(new BigDecimal("1"));
request.setPaidPrice(new BigDecimal("1.2"));
request.setCurrency(Currency.TRY.name());
request.setInstallment(1);
request.setBasketId("B67832");
request.setPaymentChannel(PaymentChannel.WEB.name());
request.setPaymentGroup(PaymentGroup.PRODUCT.name());

PaymentCard paymentCard = new PaymentCard();
paymentCard.setCardHolderName("John Doe");
paymentCard.setCardNumber("5528790000000008");
paymentCard.setExpireMonth("12");
paymentCard.setExpireYear("2030");
paymentCard.setCvc("123");
paymentCard.setRegisterCard(0);
request.setPaymentCard(paymentCard);

Buyer buyer = new Buyer();
buyer.setId("BY789");
buyer.setName("John");
buyer.setSurname("Doe");
buyer.setGsmNumber("+905350000000");
buyer.setEmail("email@email.com");
buyer.setIdentityNumber("74300864791");
buyer.setLastLoginDate("2015-10-05 12:43:35");
buyer.setRegistrationDate("2013-04-21 15:12:09");
buyer.setRegistrationAddress("Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1");
buyer.setIp("85.34.78.112");
buyer.setCity("Istanbul");
buyer.setCountry("Turkey");
buyer.setZipCode("34732");
request.setBuyer(buyer);

Address shippingAddress = new Address();
shippingAddress.setContactName("Jane Doe");
shippingAddress.setCity("Istanbul");
shippingAddress.setCountry("Turkey");
shippingAddress.setAddress("Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1");
shippingAddress.setZipCode("34742");
request.setShippingAddress(shippingAddress);

Address billingAddress = new Address();
billingAddress.setContactName("Jane Doe");
billingAddress.setCity("Istanbul");
billingAddress.setCountry("Turkey");
billingAddress.setAddress("Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1");
billingAddress.setZipCode("34742");
request.setBillingAddress(billingAddress);

List<BasketItem> basketItems = new ArrayList<BasketItem>();
BasketItem firstBasketItem = new BasketItem();
firstBasketItem.setId("BI101");
firstBasketItem.setName("Binocular");
firstBasketItem.setCategory1("Collectibles");
firstBasketItem.setCategory2("Accessories");
firstBasketItem.setItemType(BasketItemType.PHYSICAL.name());
firstBasketItem.setPrice(new BigDecimal("0.3"));
basketItems.add(firstBasketItem);

BasketItem secondBasketItem = new BasketItem();
secondBasketItem.setId("BI102");
secondBasketItem.setName("Game code");
secondBasketItem.setCategory1("Game");
secondBasketItem.setCategory2("Online Game Items");
secondBasketItem.setItemType(BasketItemType.VIRTUAL.name());
secondBasketItem.setPrice(new BigDecimal("0.5"));
basketItems.add(secondBasketItem);

BasketItem thirdBasketItem = new BasketItem();
thirdBasketItem.setId("BI103");
thirdBasketItem.setName("Usb");
thirdBasketItem.setCategory1("Electronics");
thirdBasketItem.setCategory2("Usb / Cable");
thirdBasketItem.setItemType(BasketItemType.PHYSICAL.name());
thirdBasketItem.setPrice(new BigDecimal("0.2"));
basketItems.add(thirdBasketItem);
request.setBasketItems(basketItems);

Payment payment = Payment.create(request, options);
```

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

### Configure iyzico API Options in Java

Source: https://context7.com/iyzico/iyzipay-java/llms.txt

Set up the API client configuration for iyzico by initializing the Options class with your API key, secret key, and base URL. This is essential for authenticating and communicating with the iyzico API. Proxy configuration is optional.

```java
import com.iyzipay.Options;

Options options = new Options();
options.setApiKey("your-api-key");
options.setSecretKey("your-secret-key");
options.setBaseUrl("https://sandbox-api.iyzipay.com"); // Use https://api.iyzipay.com for production

// Optional: Configure proxy if needed
options.setProxyHost("proxy.example.com");
options.setProxyPort(8080);
```

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

### Initialize Alternative Payment Method (APM) with Java

Source: https://context7.com/iyzico/iyzipay-java/llms.txt

Initializes an alternative payment method (APM) such as SOFORT for cross-border payments. This method requires setting various payment details, merchant callback URLs, and the APM type. It returns a redirect URL upon successful initialization, and the signature should be verified.

```java
import com.iyzipay.model.*;
import com.iyzipay.request.CreateApmInitializeRequest;
import java.math.BigDecimal;

CreateApmInitializeRequest request = new CreateApmInitializeRequest();
request.setLocale(Locale.TR.getValue());
request.setConversationId("123456789");
request.setPrice(new BigDecimal("1"));
request.setPaidPrice(new BigDecimal("1.2"));
request.setCurrency(Currency.EUR.name());
request.setCountryCode("DE");
request.setPaymentChannel(PaymentChannel.WEB.name());
request.setPaymentGroup(PaymentGroup.PRODUCT.name());
request.setAccountHolderName("John Doe");
request.setMerchantCallbackUrl("https://www.merchant.com/callback");
request.setMerchantErrorUrl("https://www.merchant.com/error");
request.setMerchantNotificationUrl("https://www.merchant.com/notification");
request.setApmType(ApmType.SOFORT.name());

// Set buyer, addresses, and basket items...

Apm apmInitialize = Apm.create(request, options);

if (Status.SUCCESS.getValue().equals(apmInitialize.getStatus())) {
    String redirectUrl = apmInitialize.getRedirectUrl();
    System.out.println("Redirect user to: " + redirectUrl);
    boolean signatureValid = apmInitialize.verifySignatureForCreate(options.getSecretKey());
}
```

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

### CheckoutFormInitialize.create - Initialize Checkout Form

Source: https://context7.com/iyzico/iyzipay-java/llms.txt

Initializes iyzico's hosted payment page. This method returns a URL and embeddable content for a secure checkout experience, allowing users to complete payments without leaving your site.

```APIDOC
## POST /payment/initialize/checkoutform

### Description
Initializes iyzico's hosted payment page. Returns a URL and embeddable content for a secure checkout experience.

### Method
POST

### Endpoint
/payment/initialize/checkoutform

### Parameters
#### Request Body
- **locale** (string) - Required - The locale for the transaction (e.g., 'tr', 'en').
- **conversationId** (string) - Required - Unique identifier for the conversation.
- **price** (decimal) - Required - The total price of the transaction.
- **paidPrice** (decimal) - Required - The price to be paid after discounts/fees.
- **currency** (string) - Required - The currency of the transaction (e.g., 'TRY', 'EUR').
- **basketId** (string) - Required - Unique identifier for the basket.
- **paymentGroup** (string) - Required - The payment group (e.g., 'PRODUCT', 'LISTING').
- **callbackUrl** (string) - Required - The URL to redirect the user after payment.
- **debitCardAllowed** (boolean) - Optional - Whether debit cards are allowed for payment.
- **enabledInstallments** (array of integers) - Optional - A list of enabled installment numbers.
- **buyer** (object) - Required - Information about the buyer.
  - **id** (string) - Required - Buyer's unique identifier.
  - **name** (string) - Required - Buyer's first name.
  - **surname** (string) - Required - Buyer's last name.
  - **email** (string) - Required - Buyer's email address.
  - **identityNumber** (string) - Required - Buyer's identity number.
  - **ip** (string) - Required - Buyer's IP address.
  - **city** (string) - Required - Buyer's city.
  - **country** (string) - Required - Buyer's country.

### Request Example
```json
{
  "locale": "tr",
  "conversationId": "123456789",
  "price": "1",
  "paidPrice": "1.2",
  "currency": "TRY",
  "basketId": "B67832",
  "paymentGroup": "PRODUCT",
  "callbackUrl": "https://www.merchant.com/callback",
  "debitCardAllowed": true,
  "enabledInstallments": [2, 3, 6, 9],
  "buyer": {
    "id": "BY789",
    "name": "John",
    "surname": "Doe",
    "email": "email@email.com",
    "identityNumber": "74300864791",
    "ip": "85.34.78.112",
    "city": "Istanbul",
    "country": "Turkey"
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - Status of the operation ('success' or 'failure').
- **checkoutFormContent** (string) - Embeddable HTML content for the checkout form.
- **paymentPageUrl** (string) - The URL of the iyzico payment page.
- **signature** (string) - Signature of the response for verification.

#### Response Example
```json
{
  "status": "success",
  "checkoutFormContent": "<form>...</form>",
  "paymentPageUrl": "https://sandbox-checkout.iyzipay.com/pay/12345",
  "signature": "..."
}
```
```

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

### JUnit 4.12 Dependency for iyzipay-java Samples

Source: https://github.com/iyzico/iyzipay-java/blob/master/README.md

This snippet specifies the JUnit 4.12 JAR required for running sample tests within the iyzipay-java project. It provides a link to download the specified version.

```text
* JUnit 4.12 from http://mvnrepository.com/artifact/junit/junit/4.12
```

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

### Gradle Dependency for iyzipay-java

Source: https://github.com/iyzico/iyzipay-java/blob/master/README.md

This snippet demonstrates how to include the iyzipay-java library in a Gradle project's build file. It specifies the dependency coordinates for seamless integration.

```groovy
compile "com.iyzipay:iyzipay-java:2.0.141"
```

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

### Create Direct Payment with Java

Source: https://context7.com/iyzico/iyzipay-java/llms.txt

Processes a direct credit/debit card payment. Requires comprehensive details including card information, buyer and address details, and basket items. Returns the payment status and transaction details upon successful processing. Dependencies include iyzico model and request classes.

```java
import com.iyzipay.model.*;
import com.iyzipay.request.CreatePaymentRequest;
import java.math.BigDecimal;
import java.util.ArrayList;
import java.util.List;

CreatePaymentRequest request = new CreatePaymentRequest();
request.setLocale(Locale.TR.getValue());
request.setConversationId("123456789");
request.setPrice(new BigDecimal("1"));
request.setPaidPrice(new BigDecimal("1.2"));
request.setCurrency(Currency.TRY.name());
request.setInstallment(1);
request.setBasketId("B67832");
request.setPaymentChannel(PaymentChannel.WEB.name());
request.setPaymentGroup(PaymentGroup.PRODUCT.name());

PaymentCard paymentCard = new PaymentCard();
paymentCard.setCardHolderName("John Doe");
paymentCard.setCardNumber("5528790000000008");
paymentCard.setExpireMonth("12");
paymentCard.setExpireYear("2030");
paymentCard.setCvc("123");
paymentCard.setRegisterCard(0);
request.setPaymentCard(paymentCard);

Buyer buyer = new Buyer();
buyer.setId("BY789");
buyer.setName("John");
buyer.setSurname("Doe");
buyer.setGsmNumber("+905350000000");
buyer.setEmail("email@email.com");
buyer.setIdentityNumber("74300864791");
buyer.setLastLoginDate("2015-10-05 12:43:35");
buyer.setRegistrationDate("2013-04-21 15:12:09");
buyer.setRegistrationAddress("Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1");
buyer.setIp("85.34.78.112");
buyer.setCity("Istanbul");
buyer.setCountry("Turkey");
buyer.setZipCode("34732");
request.setBuyer(buyer);

Address shippingAddress = new Address();
shippingAddress.setContactName("Jane Doe");
shippingAddress.setCity("Istanbul");
shippingAddress.setCountry("Turkey");
shippingAddress.setAddress("Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1");
shippingAddress.setZipCode("34742");
request.setShippingAddress(shippingAddress);

Address billingAddress = new Address();
billingAddress.setContactName("Jane Doe");
billingAddress.setCity("Istanbul");
billingAddress.setCountry("Turkey");
billingAddress.setAddress("Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1");
billingAddress.setZipCode("34742");
request.setBillingAddress(billingAddress);

List<BasketItem> basketItems = new ArrayList<BasketItem>();
BasketItem firstBasketItem = new BasketItem();
firstBasketItem.setId("BI101");
firstBasketItem.setName("Binocular");
firstBasketItem.setCategory1("Collectibles");
firstBasketItem.setCategory2("Accessories");
firstBasketItem.setItemType(BasketItemType.PHYSICAL.name());
firstBasketItem.setPrice(new BigDecimal("0.3"));
basketItems.add(firstBasketItem);

BasketItem secondBasketItem = new BasketItem();
secondBasketItem.setId("BI102");
secondBasketItem.setName("Game code");
secondBasketItem.setCategory1("Game");
secondBasketItem.setCategory2("Online Game Items");
secondBasketItem.setItemType(BasketItemType.VIRTUAL.name());
secondBasketItem.setPrice(new BigDecimal("0.5"));
basketItems.add(secondBasketItem);

BasketItem thirdBasketItem = new BasketItem();
thirdBasketItem.setId("BI103");
thirdBasketItem.setName("Usb");
thirdBasketItem.setCategory1("Electronics");
thirdBasketItem.setCategory2("Usb / Cable");
thirdBasketItem.setItemType(BasketItemType.PHYSICAL.name());
thirdBasketItem.setPrice(new BigDecimal("0.2"));
basketItems.add(thirdBasketItem);
request.setBasketItems(basketItems);

Payment payment = Payment.create(request, options);

if (Status.SUCCESS.getValue().equals(payment.getStatus())) {
    System.out.println("Payment ID: " + payment.getPaymentId());
    System.out.println("Paid Price: " + payment.getPaidPrice());
    boolean signatureValid = payment.verifySignature(options.getSecretKey());
    System.out.println("Signature Valid: " + signatureValid);
} else {
    System.out.println("Error: " + payment.getErrorMessage());
}
```

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

### POST /payment - Create Direct Payment

Source: https://context7.com/iyzico/iyzipay-java/llms.txt

This endpoint allows you to process a credit or debit card payment directly. It requires comprehensive details including payment card information, buyer identification, billing and shipping addresses, and a list of basket items. The response includes the payment result and transaction details.

```APIDOC
## POST /payment - Create Direct Payment

### Description
Process a credit/debit card payment directly. Requires payment card details, buyer information, billing/shipping addresses, and basket items. Returns payment result with transaction details.

### Method
POST

### Endpoint
/payment

### Parameters
#### Request Body
- **locale** (string) - Required - The locale for the transaction (e.g., 'tr').
- **conversationId** (string) - Required - A unique identifier for the conversation.
- **price** (BigDecimal) - Required - The total price of the payment.
- **paidPrice** (BigDecimal) - Required - The price to be paid after discounts/commissions.
- **currency** (string) - Required - The currency of the transaction (e.g., 'TRY').
- **installment** (integer) - Optional - The number of installments for the payment.
- **basketId** (string) - Required - The unique identifier for the basket.
- **paymentChannel** (string) - Required - The channel through which the payment is made (e.g., 'WEB').
- **paymentGroup** (string) - Required - The group of the payment (e.g., 'PRODUCT').
- **paymentCard** (object) - Required - Details of the payment card.
  - **cardHolderName** (string) - Required - Name of the cardholder.
  - **cardNumber** (string) - Required - The credit card number.
  - **expireMonth** (string) - Required - The expiration month of the card (MM).
  - **expireYear** (string) - Required - The expiration year of the card (YYYY).
  - **cvc** (string) - Required - The CVC code of the card.
  - **registerCard** (integer) - Optional - Flag to register the card (0 for no, 1 for yes).
- **buyer** (object) - Required - Information about the buyer.
  - **id** (string) - Required - Unique buyer identifier.
  - **name** (string) - Required - Buyer's first name.
  - **surname** (string) - Required - Buyer's last name.
  - **gsmNumber** (string) - Required - Buyer's GSM number.
  - **email** (string) - Required - Buyer's email address.
  - **identityNumber** (string) - Required - Buyer's identity number.
  - **lastLoginDate** (string) - Optional - Buyer's last login date.
  - **registrationDate** (string) - Optional - Buyer's registration date.
  - **registrationAddress** (string) - Optional - Buyer's registration address.
  - **ip** (string) - Required - Buyer's IP address.
  - **city** (string) - Required - Buyer's city.
  - **country** (string) - Required - Buyer's country.
  - **zipCode** (string) - Required - Buyer's zip code.
- **shippingAddress** (object) - Required - Shipping address details.
  - **contactName** (string) - Required - Contact person for shipping.
  - **city** (string) - Required - Shipping city.
  - **country** (string) - Required - Shipping country.
  - **address** (string) - Required - Shipping address.
  - **zipCode** (string) - Required - Shipping zip code.
- **billingAddress** (object) - Required - Billing address details.
  - **contactName** (string) - Required - Contact person for billing.
  - **city** (string) - Required - Billing city.
  - **country** (string) - Required - Billing country.
  - **address** (string) - Required - Billing address.
  - **zipCode** (string) - Required - Billing zip code.
- **basketItems** (array) - Required - List of items in the basket.
  - **id** (string) - Required - Item ID.
  - **name** (string) - Required - Item name.
  - **category1** (string) - Required - Primary category.
  - **category2** (string) - Optional - Secondary category.
  - **itemType** (string) - Required - Type of item (e.g., 'PHYSICAL', 'VIRTUAL').
  - **price** (BigDecimal) - Required - Price of the item.

### Request Example
```json
{
  "locale": "tr",
  "conversationId": "123456789",
  "price": "1",
  "paidPrice": "1.2",
  "currency": "TRY",
  "installment": 1,
  "basketId": "B67832",
  "paymentChannel": "WEB",
  "paymentGroup": "PRODUCT",
  "paymentCard": {
    "cardHolderName": "John Doe",
    "cardNumber": "5528790000000008",
    "expireMonth": "12",
    "expireYear": "2030",
    "cvc": "123",
    "registerCard": 0
  },
  "buyer": {
    "id": "BY789",
    "name": "John",
    "surname": "Doe",
    "gsmNumber": "+905350000000",
    "email": "email@email.com",
    "identityNumber": "74300864791",
    "lastLoginDate": "2015-10-05 12:43:35",
    "registrationDate": "2013-04-21 15:12:09",
    "registrationAddress": "Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
    "ip": "85.34.78.112",
    "city": "Istanbul",
    "country": "Turkey",
    "zipCode": "34732"
  },
  "shippingAddress": {
    "contactName": "Jane Doe",
    "city": "Istanbul",
    "country": "Turkey",
    "address": "Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
    "zipCode": "34742"
  },
  "billingAddress": {
    "contactName": "Jane Doe",
    "city": "Istanbul",
    "country": "Turkey",
    "address": "Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1",
    "zipCode": "34742"
  },
  "basketItems": [
    {
      "id": "BI101",
      "name": "Binocular",
      "category1": "Collectibles",
      "category2": "Accessories",
      "itemType": "PHYSICAL",
      "price": "0.3"
    },
    {
      "id": "BI102",
      "name": "Game code",
      "category1": "Game",
      "category2": "Online Game Items",
      "itemType": "VIRTUAL",
      "price": "0.5"
    },
    {
      "id": "BI103",
      "name": "Usb",
      "category1": "Electronics",
      "category2": "Usb / Cable",
      "itemType": "PHYSICAL",
      "price": "0.2"
    }
  ]
}
```

### Response
#### Success Response (200)
- **status** (string) - The status of the payment (e.g., 'SUCCESS').
- **paymentId** (string) - The unique identifier for the payment.
- **paidPrice** (string) - The price that was actually paid.
- **errorMessage** (string) - Error message if the payment failed.

#### Response Example
```json
{
  "status": "SUCCESS",
  "paymentId": "1234567890",
  "paidPrice": "1.2",
  "errorMessage": null
}
```
```

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

### Maven Dependency for iyzipay-java

Source: https://github.com/iyzico/iyzipay-java/blob/master/README.md

This snippet shows how to add the iyzipay-java library as a dependency in a Maven project's POM file. It specifies the group ID, artifact ID, and version required for integration.

```xml
<dependency>
  <groupId>com.iyzipay</groupId>
  <artifactId>iyzipay-java</artifactId>
  <version>2.0.141</version>
</dependency>
```

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

### POST /iyzipay/api/payment/initialize/apm

Source: https://context7.com/iyzico/iyzipay-java/llms.txt

Initializes an alternative payment method (APM) for cross-border payments, such as SOFORT. This is a crucial step before redirecting the user to the payment provider's page.

```APIDOC
## POST /iyzipay/api/payment/initialize/apm

### Description
Initializes an alternative payment method (APM) like SOFORT for cross-border payments. This endpoint is used to start the payment process for non-card payment methods.

### Method
POST

### Endpoint
/iyzipay/api/payment/initialize/apm

### Parameters
#### Request Body
- **locale** (string) - Required - Locale of the API response. Use Locale.TR.getValue() for Turkish.
- **conversationId** (string) - Required - Unique identifier for the conversation.
- **price** (BigDecimal) - Required - The total price of the transaction.
- **paidPrice** (BigDecimal) - Required - The price that will be paid by the customer.
- **currency** (string) - Required - Currency of the transaction (e.g., Currency.EUR.name()).
- **countryCode** (string) - Required - ISO 3166-1 alpha-2 country code (e.g., "DE").
- **paymentChannel** (string) - Required - The payment channel (e.g., PaymentChannel.WEB.name()).
- **paymentGroup** (string) - Required - The payment group (e.g., PaymentGroup.PRODUCT.name()).
- **accountHolderName** (string) - Required - The name of the account holder.
- **merchantCallbackUrl** (string) - Required - The URL where the user will be redirected after a successful payment.
- **merchantErrorUrl** (string) - Required - The URL where the user will be redirected if an error occurs.
- **merchantNotificationUrl** (string) - Required - The URL where the merchant will receive payment notifications.
- **apmType** (string) - Required - The type of alternative payment method (e.g., ApmType.SOFORT.name()).

### Request Example
```json
{
  "locale": "tr",
  "conversationId": "123456789",
  "price": "1",
  "paidPrice": "1.2",
  "currency": "EUR",
  "countryCode": "DE",
  "paymentChannel": "WEB",
  "paymentGroup": "PRODUCT",
  "accountHolderName": "John Doe",
  "merchantCallbackUrl": "https://www.merchant.com/callback",
  "merchantErrorUrl": "https://www.merchant.com/error",
  "merchantNotificationUrl": "https://www.merchant.com/notification",
  "apmType": "SOFORT"
}
```

### Response
#### Success Response (200)
- **status** (string) - The status of the operation (e.g., "success").
- **locale** (string) - Locale of the API response.
- **systemTime** (long) - System time of the API response.
- **conversationId** (string) - Unique identifier for the conversation.
- **authStatus** (string) - Authorization status.
- **is3DForceOpenCanvas** (boolean) - Indicates if 3D Secure should force open canvas.
- **merchantOid** (string) - Merchant's order ID.
- **redirectUrl** (string) - The URL to redirect the user to for completing the payment.
- **signature** (string) - Signature of the response for verification.

#### Response Example
```json
{
  "status": "success",
  "locale": "tr",
  "systemTime": 1678886400000,
  "conversationId": "123456789",
  "authStatus": "AUTH",
  "is3DForceOpenCanvas": false,
  "merchantOid": "merchant_order_id_123",
  "redirectUrl": "https://payment-gateway.com/redirect/to/apm?token=xyz",
  "signature": "generated_signature_string"
}
```

### Error Handling
- Check the `status` field in the response. If it is not "success", refer to the error messages for details.
- Always verify the response signature using `verifySignatureForCreate()` method.
```

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

### Lookup Card BIN Information using iyzipay-java

Source: https://context7.com/iyzico/iyzipay-java/llms.txt

Retrieves information about a card based on its first 6 digits (BIN number). This includes the issuing bank, card type (credit/debit), association (Visa, Mastercard), and card family. Requires the BIN number.

```java
import com.iyzipay.model.BinNumber;
import com.iyzipay.model.Locale;
import com.iyzipay.request.RetrieveBinNumberRequest;

RetrieveBinNumberRequest request = new RetrieveBinNumberRequest();
request.setLocale(Locale.TR.getValue());
request.setConversationId("123456789");
request.setBinNumber("554960");

BinNumber binNumber = BinNumber.retrieve(request, options);

if (Status.SUCCESS.getValue().equals(binNumber.getStatus())) {
    System.out.println("BIN: " + binNumber.getBinNumber());
    System.out.println("Card Type: " + binNumber.getCardType());        // CREDIT_CARD or DEBIT_CARD
    System.out.println("Association: " + binNumber.getCardAssociation()); // VISA, MASTER_CARD, etc.
    System.out.println("Card Family: " + binNumber.getCardFamily());    // Bonus, World, etc.
    System.out.println("Bank Name: " + binNumber.getBankName());
    System.out.println("Bank Code: " + binNumber.getBankCode());
}
```

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

### Store Card for Future Payments - Java

Source: https://context7.com/iyzico/iyzipay-java/llms.txt

Stores a credit card securely for future use, returning a card token and user key. Requires card details, email, and external user ID. Provides card type, association, and bank information upon success.

```java
import com.iyzipay.model.Card;
import com.iyzipay.model.CardInformation;
import com.iyzipay.model.Locale;
import com.iyzipay.request.CreateCardRequest;

CreateCardRequest request = new CreateCardRequest();
request.setLocale(Locale.TR.getValue());
request.setConversationId("123456789");
request.setEmail("email@email.com");
request.setExternalId("external-user-id");

CardInformation cardInformation = new CardInformation();
cardInformation.setCardAlias("My Visa Card");
cardInformation.setCardHolderName("John Doe");
cardInformation.setCardNumber("5528790000000008");
cardInformation.setExpireMonth("12");
cardInformation.setExpireYear("2030");
request.setCard(cardInformation);

Card card = Card.create(request, options);

if (Status.SUCCESS.getValue().equals(card.getStatus())) {
    String cardUserKey = card.getCardUserKey();
    String cardToken = card.getCardToken();
    System.out.println("Card stored. User Key: " + cardUserKey + ", Token: " + cardToken);
    System.out.println("Card Type: " + card.getCardType());
    System.out.println("Card Association: " + card.getCardAssociation());
    System.out.println("Bank: " + card.getCardBankName());
}
```

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

### Create Sub-Merchant using iyzipay-java

Source: https://context7.com/iyzico/iyzipay-java/llms.txt

Creates a sub-merchant account, essential for marketplace payment splitting. Supports different entity types (personal, private company, limited company) and requires details like external ID, contact information, address, and bank details (IBAN).

```java
import com.iyzipay.model.SubMerchant;
import com.iyzipay.model.SubMerchantType;
import com.iyzipay.model.Currency;
import com.iyzipay.model.Locale;
import com.iyzipay.request.CreateSubMerchantRequest;

// Personal Sub-Merchant
CreateSubMerchantRequest request = new CreateSubMerchantRequest();
request.setLocale(Locale.TR.getValue());
request.setConversationId("123456789");
request.setSubMerchantExternalId("B49224");
request.setSubMerchantType(SubMerchantType.PERSONAL.name());
request.setAddress("Nidakule Göztepe, Merdivenköy Mah. Bora Sok. No:1");
request.setContactName("John");
request.setContactSurname("Doe");
request.setEmail("email@submerchantemail.com");
request.setGsmNumber("+905350000000");
request.setName("John's market");
request.setIban("TR180006200119000006672315");
request.setIdentityNumber("31300864726");
request.setCurrency(Currency.TRY.name());

SubMerchant subMerchant = SubMerchant.create(request, options);

if (Status.SUCCESS.getValue().equals(subMerchant.getStatus())) {
    System.out.println("Sub-merchant created");
    System.out.println("Sub-merchant Key: " + subMerchant.getSubMerchantKey());
}
```