### Installation

Source: https://context7.com/trolley/java-sdk/llms.txt

Add the Trolley Java SDK dependency to your Maven project for payment processing integration.

```APIDOC
## Installation

Add the Trolley Java SDK dependency to your Maven project for payment processing integration.

```xml
<dependency>
    <groupId>com.trolley</groupId>
    <artifactId>java-sdk</artifactId>
    <version>2.1.1</version>
</dependency>
```
```

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

### Initialize Trolley Gateway Configuration and Client

Source: https://context7.com/trolley/java-sdk/llms.txt

Configure the Trolley SDK with your API keys and environment settings. This example shows how to create a Configuration object and initialize the main Gateway client, which provides access to all API endpoints.

```java
import com.trolley.Configuration;
import com.trolley.Gateway;
import com.trolley.Exceptions.*;

public class TrolleyExample {
    public static void main(String[] args) {
        // Production configuration with API keys
        Configuration config = new Configuration(
            "YOUR_PUBLIC_KEY",
            "YOUR_SECRET_KEY"
        );

        // Optional: Provide a custom HttpClient
        // HttpClient customClient = HttpClients.createDefault();
        // Configuration config = new Configuration("PUBLIC_KEY", "SECRET_KEY", customClient);

        // Optional: Use development environment with custom base URL
        // Requires .env file with BASE_URL=https://localhost:3000
        // Configuration devConfig = new Configuration("PUBLIC_KEY", "SECRET_KEY", "development");

        // Create the gateway to access all API endpoints
        Gateway client = new Gateway(config);

        try {
            // Access any gateway: recipient, batch, payment, recipientAccount,
            // balances, offlinePayment, invoice, invoiceLine, invoicePayment
            System.out.println("Gateway initialized successfully");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

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

### Install Trolley Java SDK via Maven

Source: https://github.com/trolley/java-sdk/blob/master/README.md

Add the Trolley Java SDK dependency to your project's pom.xml file to enable integration with the Trolley API.

```xml
<dependency>
    <groupId>com.trolley</groupId>
    <artifactId>java-sdk</artifactId>
    <version>2.1.1</version>
</dependency>
```

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

### Create, Update, and Delete Invoices with Trolley Java SDK

Source: https://context7.com/trolley/java-sdk/llms.txt

Provides examples for managing invoices, including creating new ones, updating existing invoices, and deleting single or multiple invoices. This functionality requires the Trolley Java SDK and API authentication.

```java
import com.trolley.Configuration;
import com.trolley.Gateway;
import com.trolley.types.Invoice;
import java.util.ArrayList;
import java.util.List;

Configuration config = new Configuration("PUBLIC_KEY", "SECRET_KEY");
Gateway client = new Gateway(config);

try {
    // Create an invoice
    Invoice invoiceRequest = new Invoice();
    // Set invoice properties as needed
    Invoice created = client.invoice.create(invoiceRequest);
    System.out.println("Invoice ID: " + created.getInvoiceId());

    // Update an invoice
    Invoice updateRequest = new Invoice();
    // Set fields to update
    Invoice updated = client.invoice.update(created.getInvoiceId(), updateRequest);
    System.out.println("Updated invoice: " + updated.getInvoiceId());

    // Delete a single invoice
    boolean deleted = client.invoice.delete(created.getInvoiceId());
    System.out.println("Invoice deleted: " + deleted);

    // Delete multiple invoices
    List<String> invoiceIds = new ArrayList<>();
    invoiceIds.add("INV-123");
    invoiceIds.add("INV-456");
    boolean bulkDeleted = client.invoice.delete(invoiceIds);
    System.out.println("Bulk delete successful: " + bulkDeleted);
} catch (Exception e) {
    e.printStackTrace();
}
```

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

### Retrieve Recipient Activity Logs - Java

Source: https://context7.com/trolley/java-sdk/llms.txt

Fetches activity logs for a given recipient ID. This example demonstrates both manual pagination (specifying page and limit) and auto-pagination using an iterator. It initializes the Trolley client and processes logs, printing relevant information.

```java
import com.trolley.Configuration;
import com.trolley.Gateway;
import com.trolley.types.Log;
import com.trolley.types.supporting.Logs;
import com.trolley.types.supporting.LogsIterator;

Configuration config = new Configuration("PUBLIC_KEY", "SECRET_KEY");
Gateway client = new Gateway(config);

try {
    String recipientId = "R-1a2B3c4D5e6F7g8H9i0J1k";

    // Manual pagination
    Logs logs = client.recipient.getAllLogs(recipientId, 1, 10);
    System.out.println("Total logs: " + logs.getMeta().getRecords());
    for (Log log : logs.getLogs()) {
        System.out.println("Log via: " + log.getVia());
    }

    // Auto-pagination with iterator
    LogsIterator logsIterator = client.recipient.getAllLogs(recipientId);
    while (logsIterator.hasNext()) {
        Log log = logsIterator.next();
        System.out.println("Activity: " + log.getVia());
    }
} catch (Exception e) {
    e.printStackTrace();
}
```

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

### Find Recipient Accounts - Java

Source: https://context7.com/trolley/java-sdk/llms.txt

Retrieves bank accounts associated with a recipient. This example shows how to fetch all accounts for a recipient using `findAll` and how to retrieve a specific account by its ID using the `find` method. It initializes the client and iterates through the results, printing account details.

```java
import com.trolley.Configuration;
import com.trolley.Gateway;
import com.trolley.types.RecipientAccount;
import java.util.List;

Configuration config = new Configuration("PUBLIC_KEY", "SECRET_KEY");
Gateway client = new Gateway(config);

try {
    String recipientId = "R-1a2B3c4D5e6F7g8H9i0J1k";

    // Get all accounts for a recipient
    List<RecipientAccount> accounts = client.recipientAccount.findAll(recipientId);
    System.out.println("Total accounts: " + accounts.size());
    for (RecipientAccount account : accounts) {
        System.out.println("Account: " + account.getId() +
                           " - " + account.getCountry() +
                           " - Primary: " + account.getPrimary());
    }

    // Get a specific account
    RecipientAccount account = client.recipientAccount.find(recipientId, "A-abc123def456");
    System.out.println("Account holder: " + account.getAccountHolderName());
    System.out.println("Currency: " + account.getCurrency());
} catch (Exception e) {
    e.printStackTrace();
}
```

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

### GET /batches/{batchId}

Source: https://github.com/trolley/java-sdk/blob/master/docs/classes/batchgateway.md

Retrieves details for a specific batch by its ID.

```APIDOC
## GET /batches/{batchId}

### Description
Retrieves a batch based on the provided batch ID.

### Method
GET

### Endpoint
/batches/{batchId}

### Parameters
#### Path Parameters
- **batchId** (string) - Required - Trolley batch id (e.g. "B-xx999bb")

### Response
#### Success Response (200)
- **batch** (Batch) - The requested batch object.
```

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

### GET /recipients/{recipientId}/accounts

Source: https://github.com/trolley/java-sdk/blob/master/docs/classes/recipientaccountgateway.md

Fetch all of the accounts for a given Trolley recipient.

```APIDOC
## GET /recipients/{recipientId}/accounts

### Description
Fetch all of the accounts for a given Trolley recipient.

### Method
GET

### Endpoint
/recipients/{recipientId}/accounts

### Parameters
#### Path Parameters
- **recipientId** (string) - Required - The Trolley recipient ID (e.g. R-xyzzy)

### Response
#### Success Response (200)
- **List<RecipientAccount>** (array) - A list of recipient account objects.

#### Response Example
[
  {
    "id": "A-123",
    "type": "bank-transfer",
    "country": "CA"
  }
]
```

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

### Create Recipient Bank Account - Java

Source: https://context7.com/trolley/java-sdk/llms.txt

Creates a new bank account or payment method for a recipient. This example shows how to create both a European bank account with IBAN and a Canadian bank account using routing and branch information. It configures the RecipientAccount object with necessary details and calls the create method.

```java
import com.trolley.Configuration;
import com.trolley.Gateway;
import com.trolley.types.RecipientAccount;

Configuration config = new Configuration("PUBLIC_KEY", "SECRET_KEY");
Gateway client = new Gateway(config);

try {
    // Create a European bank account with IBAN
    RecipientAccount accountRequest = new RecipientAccount();
    accountRequest.setType("bank-transfer");
    accountRequest.setPrimary(true);
    accountRequest.setCountry("DE");
    accountRequest.setCurrency("EUR");
    accountRequest.setIban("DE89 3704 0044 0532 0130 00");
    accountRequest.setAccountHolderName("John Smith");

    RecipientAccount account = client.recipientAccount.create(
        "R-1a2B3c4D5e6F7g8H9i0J1k",
        accountRequest
    );
    System.out.println("Account ID: " + account.getId());
    System.out.println("Account Holder: " + account.getAccountHolderName());
    System.out.println("Country: " + account.getCountry());

    // Create a Canadian bank account with routing info
    RecipientAccount caAccount = new RecipientAccount();
    caAccount.setType("bank-transfer");
    caAccount.setPrimary(false);
    caAccount.setCountry("CA");
    caAccount.setCurrency("CAD");
    caAccount.setAccountNum("012345678");
    caAccount.setBankId("004");
    caAccount.setBranchId("47261");
    caAccount.setAccountHolderName("John Smith");

    RecipientAccount caResult = client.recipientAccount.create(
        "R-1a2B3c4D5e6F7g8H9i0J1k",
        caAccount
    );
    System.out.println("CA Account ID: " + caResult.getId());
} catch (Exception e) {
    e.printStackTrace();
}
```

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

### GET /payments/{paymentId}

Source: https://github.com/trolley/java-sdk/blob/master/docs/classes/paymentgateway.md

Retrieves details for a specific payment by its ID.

```APIDOC
## GET /payments/{paymentId}

### Description
Find a specific payment.

### Method
GET

### Endpoint
/payments/{paymentId}

### Parameters
#### Path Parameters
- **paymentId** (string) - Required - Trolley payment id (e.g. "P-aabccc")

### Response
#### Success Response (200)
- **Payment** (object) - The payment details
```

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

### Get Batch Summary in Java

Source: https://github.com/trolley/java-sdk/blob/master/docs/classes/batchgateway.md

Retrieves a summarized transaction total for a given batch. This is useful for quick overviews of batch financial activity. It requires a batch ID and returns a String representation of the batch summary.

```java
BatchSummary batchSummary = client.batch.summary("B-13dejc8ubc");
```

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

### GET /payments/search

Source: https://github.com/trolley/java-sdk/blob/master/docs/classes/paymentgateway.md

Searches for payments within a specific batch with optional pagination and filtering.

```APIDOC
## GET /payments/search

### Description
Search for payments in a given batch.

### Method
GET

### Endpoint
/payments/search

### Parameters
#### Query Parameters
- **batchId** (string) - Required - Trolley payment id (e.g. "B-xx999bb")
- **page** (number) - Optional - Page number (1 based, default: 1)
- **pageSize** (number) - Optional - Page size (0...1000, default: 10)
- **term** (string) - Optional - Search terms

### Response
#### Success Response (200)
- **Payment[]** (array) - List of matching payments
```

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

### GET /v1/recipients/{recipientId}/logs

Source: https://context7.com/trolley/java-sdk/llms.txt

Retrieves activity logs for a recipient with support for pagination.

```APIDOC
## GET /v1/recipients/{recipientId}/logs

### Description
Retrieve activity logs for a recipient with support for both auto-pagination and manual pagination.

### Method
GET

### Endpoint
/v1/recipients/{recipientId}/logs

### Parameters
#### Path Parameters
- **recipientId** (string) - Required - The unique identifier of the recipient.

#### Query Parameters
- **page** (integer) - Optional - The page number for manual pagination.
- **pageSize** (integer) - Optional - The number of records per page.

### Response
#### Success Response (200)
- **logs** (List<Log>) - A list of activity log entries.
- **meta** (Object) - Metadata containing total record counts.
```

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

### GET /recipients/{recipientId}/accounts/{accountId}

Source: https://github.com/trolley/java-sdk/blob/master/docs/classes/recipientaccountgateway.md

Fetch a specific account for a given Trolley recipient.

```APIDOC
## GET /recipients/{recipientId}/accounts/{accountId}

### Description
Fetch a specific account for a given Trolley recipient.

### Method
GET

### Endpoint
/recipients/{recipientId}/accounts/{accountId}

### Parameters
#### Path Parameters
- **recipientId** (string) - Required - The Trolley recipient ID
- **accountId** (string) - Required - The Trolley account ID

### Response
#### Success Response (200)
- **RecipientAccount** (object) - The requested recipient account details.
```

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

### GET /v1/recipients/{recipientId}/accounts

Source: https://context7.com/trolley/java-sdk/llms.txt

Retrieves all accounts for a recipient or a specific account by ID.

```APIDOC
## GET /v1/recipients/{recipientId}/accounts

### Description
Retrieve all accounts for a recipient or fetch a specific account by ID.

### Method
GET

### Endpoint
/v1/recipients/{recipientId}/accounts/{accountId}

### Parameters
#### Path Parameters
- **recipientId** (string) - Required - The unique identifier of the recipient.
- **accountId** (string) - Optional - The unique identifier of the specific account.

### Response
#### Success Response (200)
- **account** (Object) - The recipient account details.
```

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

### GET /batches/{batchId}/payments

Source: https://github.com/trolley/java-sdk/blob/master/docs/classes/batchgateway.md

Returns a paginated list of payments associated with a specific batch.

```APIDOC
## GET /batches/{batchId}/payments

### Description
Returns a paginated list of payments for the specified batch.

### Method
GET

### Endpoint
/batches/{batchId}/payments

### Parameters
#### Path Parameters
- **batchId** (string) - Required - Trolley batch id

#### Query Parameters
- **page** (number) - Optional - Starting at 1
- **pageSize** (number) - Optional - In the range 0-1000

### Response
#### Success Response (200)
- **payments** (Array) - List of payment objects.
```

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

### Configuration and Gateway Initialization

Source: https://context7.com/trolley/java-sdk/llms.txt

Configure the SDK with API keys and environment settings, then initialize the Gateway client to access API endpoints.

```APIDOC
## Configuration and Gateway Initialization

The Configuration class handles API authentication and environment settings. Create a Gateway instance with your API keys to access all SDK functionality.

```java
import com.trolley.Configuration;
import com.trolley.Gateway;
import com.trolley.Exceptions.*;

public class TrolleyExample {
    public static void main(String[] args) {
        // Production configuration with API keys
        Configuration config = new Configuration(
            "YOUR_PUBLIC_KEY",
            "YOUR_SECRET_KEY"
        );

        // Optional: Provide a custom HttpClient
        // HttpClient customClient = HttpClients.createDefault();
        // Configuration config = new Configuration("PUBLIC_KEY", "SECRET_KEY", customClient);

        // Optional: Use development environment with custom base URL
        // Requires .env file with BASE_URL=https://localhost:3000
        // Configuration devConfig = new Configuration("PUBLIC_KEY", "SECRET_KEY", "development");

        // Create the gateway to access all API endpoints
        Gateway client = new Gateway(config);

        try {
            // Access any gateway: recipient, batch, payment, recipientAccount,
            // balances, offlinePayment, invoice, invoiceLine, invoicePayment
            System.out.println("Gateway initialized successfully");
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```
```

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

### Initialize Trolley Client and Fetch Recipient

Source: https://github.com/trolley/java-sdk/blob/master/README.md

Demonstrates how to configure the SDK with credentials and instantiate a Gateway client to perform API operations like retrieving recipient details.

```java
import com.trolley.java-sdk.*;
import com.trolley.Exceptions.*;

public class TrolleyExample {
    public static void main(String[] args) {
        Configuration config = new Configuration("<YOUR_ACCESS_KEY>","<YOUR_SECRET_KEY>");
        Gateway client = new Gateway(config);

        try {
            Recipient recipient = client.recipient.find("R-1a2B3c4D5e6F7g8H9i0J1k");
            System.out.println(recipient.getId());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

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

### Configure Custom API Base URL

Source: https://github.com/trolley/java-sdk/blob/master/README.md

Explains how to point the SDK to a custom API base URL, such as a local mock server, by setting an environment variable and initializing the configuration in development mode.

```properties
BASE_URL=https://localhost:3000
```

```java
Configuration config = new Configuration("ACCESS_KEY","SECRET_KEY", "development");
Gateway client = new Gateway(config);
```

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

### GET /v1/recipients/{recipientId}/payments

Source: https://context7.com/trolley/java-sdk/llms.txt

Retrieves a list of all payments associated with a specific recipient.

```APIDOC
## GET /v1/recipients/{recipientId}/payments

### Description
Retrieve all payments associated with a specific recipient.

### Method
GET

### Endpoint
/v1/recipients/{recipientId}/payments

### Parameters
#### Path Parameters
- **recipientId** (string) - Required - The unique identifier of the recipient.

### Response
#### Success Response (200)
- **payments** (List<Payment>) - A list of payment objects associated with the recipient.

#### Response Example
[
  {
    "id": "P-123",
    "amount": "100.00",
    "currency": "USD",
    "status": "paid"
  }
]
```

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

### Create Payment Batches in Java

Source: https://context7.com/trolley/java-sdk/llms.txt

Shows how to create new payment batches using the Trolley Java SDK. This includes creating a simple batch and a batch with a list of payments already included. Batches are used to group payments for processing.

```java
import com.trolley.Configuration;
import com.trolley.Gateway;
import com.trolley.types.Batch;
import com.trolley.types.Payment;
import com.trolley.types.Recipient;
import java.util.ArrayList;
import java.util.List;

Configuration config = new Configuration("PUBLIC_KEY", "SECRET_KEY");
Gateway client = new Gateway(config);

try {
    // Create a simple batch
    Batch batchRequest = new Batch();
    batchRequest.setCurrency("USD");
    batchRequest.setDescription("Monthly payroll - January 2024");

    Batch batch = client.batch.create(batchRequest);
    System.out.println("Batch ID: " + batch.getId());
    System.out.println("Currency: " + batch.getCurrency());

    // Create a batch with payments included
    List<Payment> payments = new ArrayList<>();

    Payment payment1 = new Payment();
    payment1.setAmount("100.00");
    payment1.setCurrency("USD");
    Recipient recipient1 = new Recipient();
    recipient1.setId("R-abc123");
    payment1.setRecipient(recipient1);
    payments.add(payment1);

    Payment payment2 = new Payment();
    payment2.setAmount("250.00");
    payment2.setCurrency("USD");
    Recipient recipient2 = new Recipient();
    recipient2.setId("R-def456");
    payment2.setRecipient(recipient2);
    payments.add(payment2);

    Batch batchWithPayments = new Batch();
    batchWithPayments.setPayments(payments);
    batchWithPayments.setDescription("Contractor payments");

    Batch createdBatch = client.batch.create(batchWithPayments);
    System.out.println("Created batch with " + createdBatch.getPayments().size() + " payments");
    for (Payment p : createdBatch.getPayments()) {
        System.out.println("Payment: " + p.getId() + " - $" + p.getAmount());
    }
} catch (Exception e) {
    e.printStackTrace();
}
```

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

### Search Batches with Pagination

Source: https://context7.com/trolley/java-sdk/llms.txt

Demonstrates how to search for batches using the BatchGateway. It supports both automatic pagination via an iterator and manual pagination by specifying page and size parameters.

```java
import com.trolley.Configuration;
import com.trolley.Gateway;
import com.trolley.types.Batch;
import com.trolley.types.supporting.Batches;
import com.trolley.types.supporting.BatchesIterator;

Configuration config = new Configuration("PUBLIC_KEY", "SECRET_KEY");
Gateway client = new Gateway(config);

try {
    // Auto-pagination with iterator
    BatchesIterator batchIterator = client.batch.search("payroll");
    while (batchIterator.hasNext()) {
        Batch batch = batchIterator.next();
        System.out.println("Batch: " + batch.getId() + " - " + batch.getDescription());
    }

    // Manual pagination
    Batches batches = client.batch.search(1, 10, "");
    System.out.println("Page " + batches.getMeta().getPage() +
                       " of " + batches.getMeta().getPages());
    for (Batch b : batches.getBatches()) {
        System.out.println("Batch ID: " + b.getId());
    }
} catch (Exception e) {
    e.printStackTrace();
}
```

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

### Configuration Parameters

Source: https://github.com/trolley/java-sdk/blob/master/docs/types/configurationparams.md

This section describes the properties available for configuring the Trolley Java SDK.

```APIDOC
## Configuration Parameters

### Description
This endpoint details the configuration parameters for the Trolley Java SDK.

### Method
N/A (Configuration Class)

### Endpoint
N/A (Configuration Class)

### Parameters
#### Request Body
- **environment** (string) - Optional - The environment that you're using, most likely one of "production" or "sandbox". Possible values: "production", "sandbox", "integration", "development".
- **public_key** (string) - Required - The Trolley public key.
- **private_key** (string) - Required - The Trolley private key.

### Request Example
```json
{
  "environment": "sandbox",
  "public_key": "pk_test_xxxxxxxxxxxxxxxxxxxx",
  "private_key": "sk_test_xxxxxxxxxxxxxxxxxxxx"
}
```

### Response
#### Success Response (N/A for configuration)
N/A

#### Response Example
N/A
```

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

### Manage Batch Lifecycle: Summary, Quote, and Processing

Source: https://context7.com/trolley/java-sdk/llms.txt

Shows how to retrieve a batch summary, generate an FX quote for a batch, and initiate the batch processing workflow. Includes error handling for validation issues using MalformedException.

```java
import com.trolley.Configuration;
import com.trolley.Gateway;
import com.trolley.types.Batch;
import com.trolley.types.supporting.BatchSummary;
import com.trolley.Exceptions.MalformedException;
import com.fasterxml.jackson.databind.JsonNode;

Configuration config = new Configuration("PUBLIC_KEY", "SECRET_KEY");
Gateway client = new Gateway(config);

try {
    String batchId = "B-abc123def456";

    // Get batch summary with totals
    BatchSummary summary = client.batch.summary(batchId);
    System.out.println("Batch Summary retrieved");

    // Generate FX quote for the batch
    try {
        String quoteResponse = client.batch.generateQuote(batchId);
        System.out.println("Quote generated: " + quoteResponse);

        // Start processing the batch
        String processResponse = client.batch.processBatch(batchId);
        System.out.println("Processing started: " + processResponse);
    } catch (MalformedException e) {
        // Handle validation errors
        for (JsonNode node : e.getErrorResponse().get("errors")) {
            System.out.println("Error: " + node.get("message"));
        }
    }
} catch (Exception e) {
    e.printStackTrace();
}
```

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

### Fetch and Search Invoices with Trolley Java SDK

Source: https://context7.com/trolley/java-sdk/llms.txt

Demonstrates how to fetch a specific invoice by ID or search for invoices using various criteria like recipient IDs, invoice dates, and tags. It showcases both auto-pagination with InvoicesIterator and manual pagination with Invoices objects. Requires Trolley SDK configuration with API keys.

```java
import com.trolley.Configuration;
import com.trolley.Gateway;
import com.trolley.types.Invoice;
import com.trolley.types.Invoice.SearchBy;
import com.trolley.types.Invoices;
import com.trolley.types.supporting.InvoicesIterator;
import java.util.Arrays;
import java.util.List;

Configuration config = new Configuration("PUBLIC_KEY", "SECRET_KEY");
Gateway client = new Gateway(config);

try {
    // Fetch a specific invoice
    Invoice invoice = client.invoice.fetch("INV-abc123");
    System.out.println("Invoice: " + invoice.getInvoiceId());

    // Search by recipient IDs (auto-pagination)
    List<String> recipientIds = Arrays.asList("R-abc123", "R-def456");
    InvoicesIterator invoicesIterator = client.invoice.search(
        SearchBy.RECIPIENT_ID,
        recipientIds,
        null
    );
    while (invoicesIterator.hasNext()) {
        Invoice inv = invoicesIterator.next();
        System.out.println("Found invoice: " + inv.getInvoiceId());
    }

    // Search by invoice date (manual pagination)
    Invoices invoices = client.invoice.search(
        SearchBy.INVOICE_DATE,
        null,
        "2024-01-01",
        1,  // page
        10  // pageSize
    );
    System.out.println("Found " + invoices.getMeta().getRecords() + " invoices");

    // Search by tags
    List<String> tags = Arrays.asList("contractor", "2024");
    InvoicesIterator taggedInvoices = client.invoice.search(
        SearchBy.TAGS,
        tags,
        null
    );
} catch (Exception e) {
    e.printStackTrace();
}
```

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

### Find and Search Payments with Trolley Java SDK

Source: https://context7.com/trolley/java-sdk/llms.txt

Demonstrates how to find a specific payment by ID and search for payments within a batch using auto-pagination or manual pagination. Requires the Trolley SDK and API keys for configuration.

```java
import com.trolley.Configuration;
import com.trolley.Gateway;
import com.trolley.types.Payment;
import com.trolley.types.supporting.Payments;
import com.trolley.types.supporting.PaymentsIterator;

Configuration config = new Configuration("PUBLIC_KEY", "SECRET_KEY");
Gateway client = new Gateway(config);

try {
    // Find a specific payment
    Payment payment = client.payment.find("P-payment123");
    System.out.println("Payment: " + payment.getId());
    System.out.println("Amount: " + payment.getAmount() + " " + payment.getCurrency());
    System.out.println("Status: " + payment.getStatus());
    System.out.println("Check Number: " + payment.getCheckNumber()); // null if not a check

    // Search payments in a batch with auto-pagination
    String batchId = "B-abc123def456";
    PaymentsIterator payments = client.payment.search(batchId, "");
    while (payments.hasNext()) {
        Payment p = payments.next();
        System.out.println("Payment: " + p.getId() + " - $" + p.getAmount());
    }

    // Manual pagination
    Payments paymentsPage = client.payment.search(batchId, 1, 10, "");
    System.out.println("Total payments: " + paymentsPage.getMeta().getRecords());
    for (Payment p : paymentsPage.getPayments()) {
        System.out.println("Payment ID: " + p.getId());
    }
} catch (Exception e) {
    e.printStackTrace();
}
```

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

### BatchGateway.create

Source: https://context7.com/trolley/java-sdk/llms.txt

This section explains how to create new payment batches using the Trolley Java SDK. Batches can be created empty or pre-populated with payments.

```APIDOC
## BatchGateway.create

### Description
Create a new payment batch, optionally with payments included. Batches group payments together for processing.

### Method
POST

### Endpoint
`/v1/batches`

### Parameters
#### Request Body
- **currency** (string) - Optional - The currency for the batch (e.g., "USD").
- **description** (string) - Optional - A description for the batch.
- **payments** (array of Payment objects) - Optional - A list of payments to include in the batch.
    - **amount** (string) - Required - The payment amount.
    - **currency** (string) - Required - The payment currency.
    - **recipient** (Recipient object) - Required - The recipient of the payment.
        - **id** (string) - Required - The ID of the recipient.

### Request Example (Simple Batch)
```java
// Assuming 'client' is an initialized Gateway object
Batch batchRequest = new Batch();
batchRequest.setCurrency("USD");
batchRequest.setDescription("Monthly payroll - January 2024");
client.batch.create(batchRequest);
```

### Request Example (Batch with Payments)
```java
// Assuming 'client' is an initialized Gateway object
List<Payment> payments = new ArrayList<>();

Payment payment1 = new Payment();
payment1.setAmount("100.00");
payment1.setCurrency("USD");
Recipient recipient1 = new Recipient();
recipient1.setId("R-abc123");
payment1.setRecipient(recipient1);
payments.add(payment1);

Batch batchWithPayments = new Batch();
batchWithPayments.setPayments(payments);
batchWithPayments.setDescription("Contractor payments");
client.batch.create(batchWithPayments);
```

### Response
#### Success Response (201 Created)
- **id** (string) - The ID of the created batch.
- **currency** (string) - The currency of the batch.
- **description** (string) - The description of the batch.
- **payments** (array of Payment objects) - The list of payments included in the batch.

#### Response Example
```json
{
  "id": "B-xyz789",
  "currency": "USD",
  "description": "Contractor payments",
  "payments": [
    {
      "id": "P-12345",
      "amount": "100.00",
      "currency": "USD",
      "recipient": {
        "id": "R-abc123"
      }
    }
  ]
}
```
```

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

### Find, Update, and Delete Batches in Java

Source: https://context7.com/trolley/java-sdk/llms.txt

Illustrates how to retrieve a specific payment batch by its ID, update its description, and delete it using the Trolley Java SDK. It also covers how to perform a bulk delete operation on multiple batches.

```java
import com.trolley.Configuration;
import com.trolley.Gateway;
import com.trolley.types.Batch;
import java.util.ArrayList;

Configuration config = new Configuration("PUBLIC_KEY", "SECRET_KEY");
Gateway client = new Gateway(config);

try {
    // Find a batch by ID
    Batch batch = client.batch.find("B-abc123def456");
    System.out.println("Batch: " + batch.getId());
    System.out.println("Description: " + batch.getDescription());
    System.out.println("Status: " + batch.getStatus());

    // Update a batch
    Batch updateRequest = new Batch();
    updateRequest.setDescription("Updated description");
    boolean updated = client.batch.update(batch.getId(), updateRequest);
    System.out.println("Update successful: " + updated);

    // Delete a single batch
    boolean deleted = client.batch.delete("B-abc123def456");
    System.out.println("Deleted: " + deleted);

    // Delete multiple batches
    ArrayList<Batch> batchesToDelete = new ArrayList<>();
    Batch b1 = new Batch();
    b1.setId("B-batch1");
    Batch b2 = new Batch();
    b2.setId("B-batch2");
    batchesToDelete.add(b1);
    batchesToDelete.add(b2);

    boolean bulkDeleted = client.batch.delete(batchesToDelete);
    System.out.println("Bulk delete successful: " + bulkDeleted);
} catch (Exception e) {
    e.printStackTrace();
}
```

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

### Retrieve Account Balances with Trolley Java SDK

Source: https://context7.com/trolley/java-sdk/llms.txt

Shows how to retrieve account balances for both Trolley and PayPal accounts using the Trolley Java SDK. This requires the SDK and valid API credentials.

```java
import com.trolley.Configuration;
import com.trolley.Gateway;
import com.trolley.types.Balances;
import java.util.List;

Configuration config = new Configuration("PUBLIC_KEY", "SECRET_KEY");
Gateway client = new Gateway(config);

try {
    // Get all account balances
    List<Balances> allBalances = client.balances.getAllBalances();
    for (Balances balance : allBalances) {
        System.out.println("Account balance: " + balance);
    }

    // Get Trolley account balances only
    List<Balances> trolleyBalances = client.balances.getTrolleyAccountBalances();
    System.out.println("Trolley accounts: " + trolleyBalances.size());

    // Get PayPal account balances only
    List<Balances> paypalBalances = client.balances.getPaypalAccountBalances();
    System.out.println("PayPal accounts: " + paypalBalances.size());
} catch (Exception e) {
    e.printStackTrace();
}
```

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

### POST /batches

Source: https://github.com/trolley/java-sdk/blob/master/docs/classes/batchgateway.md

Creates a new batch with optional payments.

```APIDOC
## POST /batches

### Description
Creates a new batch in the system.

### Method
POST

### Endpoint
/batches

### Parameters
#### Request Body
- **batch** (Batch) - Required - The batch object containing source currency and description.

### Request Example
{
  "sourceCurrency": "USD",
  "description": "Docs Create"
}

### Response
#### Success Response (200)
- **batch** (Batch) - The created batch object.
```

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

### Create Payment with Trolley Java SDK

Source: https://github.com/trolley/java-sdk/blob/master/docs/classes/paymentgateway.md

Creates a new payment within a specified batch using the Trolley Java SDK. Requires a batch ID and payment details in the body. Returns the created Payment object.

```java
Payment payment = client.payment.create("B-1wed33", "{\"sourceAmount\":\"10.00\", \"recipient\": {\"id\": \"R-123rd343\"}}");
```

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

### Search Payments in Batch with Trolley Java SDK

Source: https://github.com/trolley/java-sdk/blob/master/docs/classes/paymentgateway.md

Searches for payments within a specific batch using the Trolley Java SDK. Supports pagination and term filtering. Requires the batch ID and optionally accepts page number, page size, and search terms. Returns an array of Payment objects.

```java
Payment[] payments = client.payment.search("B-xx999bb", 1, 10, "");
```

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

### Create Batch in Java

Source: https://github.com/trolley/java-sdk/blob/master/docs/classes/batchgateway.md

Creates a new batch with optional payments using the Trolley Java SDK. This method interfaces with the 'Create a Batch' API endpoint. It requires a Batch object as input and returns the created Batch object.

```java
Batch batch = client.batch.create("{\"sourceCurrency\": \"USD\", \"description\":\"Docs Create\"}");
```

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

### Create a New Recipient with Trolley Java SDK

Source: https://context7.com/trolley/java-sdk/llms.txt

This snippet demonstrates how to create a new payment recipient using the RecipientGateway. It includes setting recipient details, contact information, and government IDs for compliance purposes. The created recipient's ID, name, and status are then printed.

```java
import com.trolley.Configuration;
import com.trolley.Gateway;
import com.trolley.types.Recipient;
import com.trolley.types.supporting.GovernmentId;
import java.util.Arrays;
import java.util.ArrayList;

Configuration config = new Configuration("PUBLIC_KEY", "SECRET_KEY");
Gateway client = new Gateway(config);

// Create a new recipient with full details
Recipient recipientRequest = new Recipient();
recipientRequest.setType("individual");
recipientRequest.setFirstName("John");
recipientRequest.setLastName("Smith");
recipientRequest.setEmail("john.smith@example.com");
recipientRequest.setContactEmails(Arrays.asList("john1@example.com", "john2@example.com"));

// Add government ID for compliance
GovernmentId govId = new GovernmentId();
govId.setCountry("US");
govId.setType("SSN");
govId.setValue("123456789");
ArrayList<GovernmentId> govIds = new ArrayList<>();
govIds.add(govId);
recipientRequest.setGovernmentIds(govIds);

try {
    Recipient recipient = client.recipient.create(recipientRequest);
    System.out.println("Created recipient ID: " + recipient.getId());
    System.out.println("First Name: " + recipient.getFirstName());
    System.out.println("Status: " + recipient.getStatus());
    System.out.println("Compliance Status: " + recipient.getComplianceStatus());
    // Output: Created recipient ID: R-1a2B3c4D5e6F7g8H9i0J1k
    // Output: First Name: John
    // Output: Status: active
    // Output: Compliance Status: PENDING
} catch (Exception e) {
    e.printStackTrace();
}
```

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

### List Payments for Batch in Java

Source: https://github.com/trolley/java-sdk/blob/master/docs/classes/batchgateway.md

Returns a paginated list of payments associated with a specific batch. This method allows for efficient retrieval of payment details, supporting custom page and page size parameters. It takes a batch ID and optional pagination parameters, returning an array of Payment objects.

```java
client.batch.paymentList(batchId, page, pageSize);
```

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

### Handle Trolley Java SDK Exceptions

Source: https://context7.com/trolley/java-sdk/llms.txt

Illustrates how to catch and handle specific exception types provided by the Trolley Java SDK, which correspond to various API error scenarios like authentication, authorization, not found, rate limiting, and service maintenance. This allows for precise error reporting and recovery.

```java
import com.trolley.Configuration;
import com.trolley.Gateway;
import com.trolley.types.Recipient;
import com.trolley.Exceptions.*;
import com.fasterxml.jackson.databind.JsonNode;

Configuration config = new Configuration("PUBLIC_KEY", "SECRET_KEY");
Gateway client = new Gateway(config);

try {
    Recipient recipient = client.recipient.find("R-invalid-id");
} catch (AuthenticationException e) {
    // Invalid API credentials (401)
    System.err.println("Authentication failed: Check your API keys");
} catch (AuthorizationException e) {
    // Insufficient permissions (403)
    System.err.println("Authorization failed: Insufficient permissions");
} catch (NotFoundException e) {
    // Resource not found (404)
    System.err.println("Recipient not found");
} catch (MalformedException e) {
    // Validation error (400)
    System.err.println("Validation error:");
    for (JsonNode node : e.getErrorResponse().get("errors")) {
        System.err.println("  - " + node.get("message"));
    }
} catch (TooManyRequestsException e) {
    // Rate limit exceeded (429)
    System.err.println("Rate limit exceeded, please retry later");
} catch (DownForMaintenanceException e) {
    // Service unavailable (503)
    System.err.println("Service is under maintenance");
} catch (InvalidFieldException e) {
    // SDK-level validation error
    System.err.println("Invalid field: " + e.getMessage());
} catch (Exception e) {
    // Unexpected error
    System.err.println("Unexpected error: " + e.getMessage());
}
```

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

### Create Recipient Account - Java

Source: https://github.com/trolley/java-sdk/blob/master/docs/classes/recipientaccountgateway.md

Creates a new bank account for a given Trolley recipient. It requires the recipient ID and account details in a JSON string format. Returns the created RecipientAccount object.

```java
RecipientAccount recipientAccount = client.recipientAccount.create("R-112e2c3x","{\"type\":\"bank-transfer\",\"primary\":\"true\",\"country\":\"CA\",\"currency\":\"CAD\",\"accountNum\":\"012345678\",\"bankId\":\"004\",\"branchId\":\"47261\",\"accountHolderName\":\"John Smith\"}");
```

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

### Perform Payment CRUD Operations

Source: https://context7.com/trolley/java-sdk/llms.txt

Illustrates how to create, update, and delete payments within a specific batch. Note that deletion is only supported for non-processed payments.

```java
import com.trolley.Configuration;
import com.trolley.Gateway;
import com.trolley.types.Payment;
import com.trolley.types.Recipient;

Configuration config = new Configuration("PUBLIC_KEY", "SECRET_KEY");
Gateway client = new Gateway(config);

try {
    String batchId = "B-abc123def456";

    // Create a payment in a batch
    Payment paymentRequest = new Payment();
    paymentRequest.setSourceAmount("100.00");
    paymentRequest.setMemo("January commission payment");

    Recipient recipientRef = new Recipient();
    recipientRef.setId("R-recipient123");
    paymentRequest.setRecipient(recipientRef);

    Payment payment = client.payment.create(paymentRequest, batchId);
    System.out.println("Payment ID: " + payment.getId());
    System.out.println("Amount: " + payment.getAmount());

    // Update a payment
    Payment updateRequest = new Payment();
    updateRequest.setSourceAmount("150.00");
    boolean updated = client.payment.update(payment.getId(), updateRequest, batchId);
    System.out.println("Payment updated: " + updated);

    // Delete a payment (only non-processed payments can be deleted)
    boolean deleted = client.payment.delete(payment.getId(), batchId);
    System.out.println("Payment deleted: " + deleted);
} catch (Exception e) {
    e.printStackTrace();
}
```

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

### Exceptions Overview

Source: https://github.com/trolley/java-sdk/blob/master/docs/packages/exceptions.md

This section lists the available exception classes within the Trolley Java SDK's exceptions package.

```APIDOC
## Package: Exceptions

This package contains custom exception classes used by the Trolley Java SDK to handle various error conditions.

### Classes

*   **Authentication**: Represents authentication-related errors.
*   **Authorization**: Represents authorization-related errors.
*   **DownForMaintenance**: Indicates that the service is temporarily unavailable due to maintenance.
*   **Malformed**: Signifies that a request or data is malformed.
*   **NotFound**: Indicates that a requested resource was not found.
*   **Unexpected**: A general-purpose exception for unexpected errors.
*   **TooManyRequests**: Represents rate limiting errors.
*   **InvalidField**: Indicates that a specific field in the request is invalid.
*   **InvalidServer**: Signifies an issue with the server itself.
*   **InvalidStatusCode**: Represents errors related to unexpected HTTP status codes.
```

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

### Search Recipients with Pagination - Java

Source: https://context7.com/trolley/java-sdk/llms.txt

Searches for recipients based on a query, supporting both auto-pagination using an iterator and manual pagination. The auto-pagination fetches subsequent pages automatically, while manual pagination requires specifying page number and size. This function requires a configured Trolley SDK and returns recipient data, including metadata for pagination.

```java
import com.trolley.Configuration;
import com.trolley.Gateway;
import com.trolley.types.Recipient;
import com.trolley.types.supporting.Recipients;
import com.trolley.types.supporting.RecipientsIterator;

Configuration config = new Configuration("PUBLIC_KEY", "SECRET_KEY");
Gateway client = new Gateway(config);

try {
    // Auto-pagination with iterator (10 items per page)
    RecipientsIterator recipientsIterator = client.recipient.search("Smith");
    int count = 0;
    while (recipientsIterator.hasNext()) {
        Recipient recipient = recipientsIterator.next();
        System.out.println("Found: " + recipient.getId() + " - " + recipient.getFirstName());
        count++;
    }
    System.out.println("Total recipients found: " + count);

    // Manual pagination
    int page = 1;
    int pageSize = 10;
    String searchTerm = ""; // Empty string for all recipients
    Recipients recipients = client.recipient.search(page, pageSize, searchTerm);

    System.out.println("Page " + recipients.getMeta().getPage() +
                       " of " + recipients.getMeta().getPages());
    for (Recipient r : recipients.getRecipients()) {
        System.out.println("Recipient: " + r.getId());
    }
} catch (Exception e) {
    e.printStackTrace();
}
```

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

### Authentication Exception Class

Source: https://github.com/trolley/java-sdk/blob/master/docs/classes/exceptions.authentication.md

Details about the Authentication exception class, including its hierarchy and static properties.

```APIDOC
## Class: Authentication

### Hierarchy

↳  [BaseException](exceptions.baseexception.md)

**↳ Authentication**

### Index

### Properties

* [name](exceptions.authentication.md#name)

---

<a id="name">

### «Static» name

**●  name**:  *`string`*

*AuthenticationException*

*Defined in PaymentRails.Exceptions.AuthenticationException*

---
```

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

### Update and Delete Recipient Accounts in Java

Source: https://context7.com/trolley/java-sdk/llms.txt

Demonstrates how to update an existing recipient account by modifying its properties and how to delete a recipient account using the Trolley Java SDK. Note that updating certain properties may result in a new account ID.

```java
import com.trolley.Configuration;
import com.trolley.Gateway;
import com.trolley.types.RecipientAccount;

Configuration config = new Configuration("PUBLIC_KEY", "SECRET_KEY");
Gateway client = new Gateway(config);

try {
    String recipientId = "R-1a2B3c4D5e6F7g8H9i0J1k";
    String accountId = "A-abc123def456";

    // Update account (changing primary status)
    RecipientAccount updateRequest = new RecipientAccount();
    updateRequest.setPrimary(false);
    RecipientAccount updated = client.recipientAccount.update(
        recipientId,
        accountId,
        updateRequest
    );
    System.out.println("Updated account: " + updated.getId());

    // Delete an account
    boolean deleted = client.recipientAccount.delete(recipientId, accountId);
    System.out.println("Account deleted: " + deleted);
} catch (Exception e) {
    e.printStackTrace();
}
```

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

### BatchGateway.find, update, and delete

Source: https://context7.com/trolley/java-sdk/llms.txt

This section covers retrieving, updating, and deleting payment batches using the Trolley Java SDK. It includes operations for single and bulk deletion.

```APIDOC
## BatchGateway.find, update, and delete

### Description
Retrieve, update, or delete batches. Supports both single and bulk delete operations.

### Method
GET (find), PUT (update), DELETE (single), POST (bulk delete)

### Endpoint
`/v1/batches/{batchId}` (find, update, delete single)
`/v1/batches/bulk-delete` (delete multiple)

### Parameters
#### Path Parameters (for find, update, delete single)
- **batchId** (string) - Required - The ID of the batch.

#### Request Body (for update)
- **description** (string) - Optional - The updated description for the batch.

#### Request Body (for bulk delete)
- **batches** (array of Batch objects) - Required - A list of batch objects, each containing at least an `id` field.
    - **id** (string) - Required - The ID of the batch to delete.

### Request Example (Find)
```java
// Assuming 'client' is an initialized Gateway object
client.batch.find("B-abc123def456");
```

### Request Example (Update)
```java
// Assuming 'client' is an initialized Gateway object
Batch updateRequest = new Batch();
updateRequest.setDescription("Updated description");
client.batch.update("B-abc123def456", updateRequest);
```

### Request Example (Delete Single)
```java
// Assuming 'client' is an initialized Gateway object
client.batch.delete("B-abc123def456");
```

### Request Example (Delete Multiple)
```java
// Assuming 'client' is an initialized Gateway object
ArrayList<Batch> batchesToDelete = new ArrayList<>();
Batch b1 = new Batch();
b1.setId("B-batch1");
Batch b2 = new Batch();
b2.setId("B-batch2");
batchesToDelete.add(b1);
batchesToDelete.add(b2);
client.batch.delete(batchesToDelete);
```

### Response
#### Success Response (Find)
- **id** (string) - The ID of the batch.
- **description** (string) - The description of the batch.
- **status** (string) - The status of the batch.

#### Success Response (Update)
- **boolean** - True if the update was successful, false otherwise.

#### Success Response (Delete Single/Multiple)
- **boolean** - True if the deletion(s) were successful, false otherwise.

#### Response Example (Find)
```json
{
  "id": "B-abc123def456",
  "description": "Original description",
  "status": "processing"
}
```

#### Response Example (Update/Delete)
```json
{
  "success": true
}
```
```