> This is Payabli documentation. For a complete page index, fetch https://docs.payabli.com/llms.txt — append .md to any page URL for lightweight markdown. For section-level indexes, query parameters, and other AI-optimized access methods, see https://docs.payabli.com/ai-agents.md

# Java SDK changelog

This is the changelog for the Payabli Java SDK. It includes updates, bug fixes, and new features.

## October 27, 2026

## v1.0.24

This release includes breaking changes. It corrects the organization details types to match the API, renames the ticket amount fields on paypoint credentials, and adds an organizations client for the intelligent boarding API (beta). See [October 20, 2026](/changelog/api-changelog/2026/10/20) and [October 22, 2026](/changelog/api-changelog/2026/10/22) and [October 27, 2026](/changelog/api-changelog/2026/10/27) for more information.

### Basic organization details return a response envelope

`organization().getBasicOrganization` and `organization().getBasicOrganizationById` now return `GetBasicOrganizationResponse` instead of `OrganizationQueryRecord`. The organization details are in `getResponseData()`, alongside `getIsSuccess()` and `getResponseText()`.

```java
// Before
OrganizationQueryRecord org = client.organization().getBasicOrganization("my-org");

// After
GetBasicOrganizationResponse basic = client.organization().getBasicOrganization("my-org");
Optional<OrganizationQueryRecord> org = basic.getResponseData();
```

### Organization details types match the API

`OrganizationQueryRecord` changes these return types:

* `getBillingInfo()` now returns `Optional<InstrumentResponse>` instead of `Optional<Instrument>`. `InstrumentResponse` has `getAchAccount()`, `getAchRouting()`, `getBillingAddress()`, `getBillingCity()`, `getBillingCountry()`, `getBillingState()`, and `getBillingZip()` (`Optional<String>`).
* `getContacts()` now returns `Optional<List<ContactsResponse>>` instead of `Optional<List<Contacts>>`. `ContactsResponse` has `getContactName()`, `getContactEmail()`, `getContactTitle()`, and `getContactPhone()`.
* `getOrgLogo()` now returns `Optional<String>`, the logo's URL, instead of `Optional<FileContent>`.

It also adds `getOrgFavicon()` (`Optional<String>`), the URL of the organization's favicon. The method names are unchanged, but their JSON names now match the PascalCase names the API returns, such as `OrgId` and `BillingInfo`.

### Ticket amount fields renamed

`PayabliCredentialsPascal` renames `getMaxTicket()` to `getMaxticket()` and `getMinTicket()` to `getMinticket()` (`Optional<Double>`). The builder methods are now `maxticket` and `minticket`.

```java
// Before
PayabliCredentialsPascal credentials = PayabliCredentialsPascal.builder().maxTicket(1000.0).minTicket(1.0).build();

// After
PayabliCredentialsPascal credentials = PayabliCredentialsPascal.builder().maxticket(1000.0).minticket(1.0).build();
```

### Organizations client (beta)

The client adds `organizations()`, with `listOrganizations`, `createOrganization`, `getOrganization`, and `updateOrganization`. `createOrganization` takes `CreateOrganizationOrganizationsRequest`, which wraps `CreateOrganizationWithInlineBusiness`, `CreateOrganizationWithBusinessReference`, or `CreateOrganizationAllFields`. The methods return envelope types, such as `PaypointDetailEnvelope`. These endpoints only accept OAuth. See [OAuth authentication](/developers/oauth-authentication).

```java
PaypointDetailEnvelope detail = client.organizations().getOrganization("org-reference");
```

### Other changes

* `MethodsListOut` adds `getRtp()` and `getWire()` (`Optional<Boolean>`).
* `PaypointSummaryResponse` adds `getExternalId()` (`Optional<String>`).
* `paypoints().listPaypoints` now throws `BadRequestError` for HTTP `400`.

## October 19, 2026

## v1.0.23

This release includes breaking changes. It adds clients for the intelligent boarding API (beta) and marks the legacy boarding methods as deprecated. See [October 19, 2026](/changelog/api-changelog/2026/10/19) for more information.

### Intelligent boarding clients (beta)

`PayabliApiClient` adds the `businesses()`, `people()`, `paypoints()`, `paymentMethods()`, `boardingTemplates()`, and `applications()` clients. The async and raw clients have them too. Their methods return envelope types, such as `BusinessDetailEnvelope`.

These endpoints only accept OAuth. Set your OAuth `clientId` and `clientSecret` on the builder. See [OAuth authentication](/developers/oauth-authentication) and [Manage API credentials](/guides/platform-developer-api-credentials-manage).

```java
PayabliApiClient client = new PayabliApiClientBuilder()
        .clientId("CLIENT_ID")
        .clientSecret("CLIENT_SECRET")
        .build();
BusinessDetailEnvelope business = client.businesses().getBusiness("BUSINESS_REFERENCE");
```

### Legacy boarding methods are deprecated

Legacy boarding will be sunset in Q2 2027. Every method on `boarding()` and `templates()` now has a deprecation warning in its documentation. `export().exportApplications` was already deprecated. The methods don't have the `@Deprecated` annotation, so the compiler doesn't warn you.

### `UnprocessableEntityError.body()` now returns `Object`

The new applications endpoints return a different error body for HTTP `422`, so `UnprocessableEntityError.body()` now returns `Object` instead of `PayabliErrorBody`. Code that reads its fields, such as after `moneyOut().authorizeOut`, `captureOut`, or `payout`, no longer compiles.

```java
// Before
catch (UnprocessableEntityError e) { String text = e.body().getResponseText(); }

// After
catch (UnprocessableEntityError e) { Object body = e.body(); }
```

### Case management bank account services use new types

The `BankAccountServices` builder's `moneyIn` and `moneyOut` now take `List<CaseManagementMoneyInService>` and `List<CaseManagementMoneyOutService>`, and the matching methods return them. The new types have the same constants as `MoneyInService` and `MoneyOutService`.

```java
// Before
BankAccountServices.builder().moneyIn(Arrays.asList(MoneyInService.ACH)).build();

// After
BankAccountServices.builder().moneyIn(Arrays.asList(CaseManagementMoneyInService.ACH)).build();
```

## v1.0.22

This release adds methods to get the next check number and cancel ghost cards, a check number on reissued payouts, invoice data on subscription updates, a 1099 flag on vendors, every payout that paid a bill, and card-present device details. See [October 19, 2026](/changelog/api-changelog/2026/10/19) for more information.

### New methods

* `moneyOut().getNextCheckNumber(long paypointId, String accountId)` returns `NextCheckNumberResponse`, whose `getCheckNumber()` returns `String`.
* `ghostCard().deleteGhostCard(String cardToken)` returns `DeleteGhostCardResponse`. Its `getResponseData()` returns `Optional<DeleteGhostCardResponseData>`, which has `getDeleteType()` and `getCardToken()`.

The async and raw clients have the same methods.

```java
NextCheckNumberResponse next = client.moneyOut().getNextCheckNumber(285L, "ACCOUNT_ID");
DeleteGhostCardResponse deleted = client.ghostCard().deleteGhostCard("CARD_TOKEN");
```

### Request changes

* `ReissueOutRequest` adds `checkNumber(String)` to its builder, and `getCheckNumber()` returns `Optional<String>`.
* `RequestUpdateSchedule`, the request for `subscription().updateSubscription`, adds `invoiceData(BillData)` to its builder. To remove the subscription's invoice data, pass `Nullable.ofNull()` from `io.github.payabli.api.core`:

  ```java
  client.subscription().updateSubscription(396, RequestUpdateSchedule.builder()
          .invoiceData(Nullable.<BillData>ofNull())
          .build());
  ```
* `VendorData` adds `issue1099(Boolean)` to its builder, and `getIssue1099()` returns `Optional<Boolean>`.

### Vendor 1099 flag

`VendorQueryRecord`, `VendorDataResponse`, `TransferOutDetailVendor`, and `PayoutSubscriptionVendor` add the required `getIssue1099()` (`boolean`). `AssociatedVendor`, `VCardGetResponseAssociatedVendor`, `VendorOutData`, and `GetMethodResponseResponseDataVendorsItem` add `getIssue1099()` (`Optional<Boolean>`).

### Payouts that paid a bill

`BillResponseData` and `BillQueryRecord2` add `getTransactions()` (`Optional<List<BillTransactionReference>>`). Each `BillTransactionReference` has `getIdOut()` (`long`) and `getPaymentId()` (`Optional<String>`).

### Card-present device details

* `TransactionQueryRecords` and `TransactionQueryRecordsCustomer` add `getDeviceEntryMode()` (`Optional<String>`), `getEmvAuthData()` (`Optional<EmvAuthData>`, with `getRequestEmvData()` and `getResponseEmvData()`), and `getDeviceData()` (`Optional<QueryDeviceData>`).
* `DeviceQueryRecord` adds the required `getOperationalStatus()` (`DeviceQueryRecordOperationalStatus`, with the constants `ONLINE`, `BUSY`, and `OFFLINE`), plus `getAppVersion()` and `getOsVersion()` (`Optional<String>`).

The new required fields are new builder stages, so existing `builder()` calls for `VendorQueryRecord`, `VendorDataResponse`, `TransferOutDetailVendor`, `PayoutSubscriptionVendor`, and `DeviceQueryRecord` must set them.

## October 14, 2026

## v1.0.21

This release includes breaking changes. The get payout subscription response now uses its own camelCase types. See [October 14, 2026](/changelog/api-changelog/2026/10/14) for more information.

### New types in the get payout subscription response

`PayoutSubscriptionQueryRecord` now returns new types from its vendor, bills, and payment data methods:

| Method             | Before                           | After                                     |
| ------------------ | -------------------------------- | ----------------------------------------- |
| `getVendor()`      | `Optional<VendorQueryRecord>`    | `Optional<PayoutSubscriptionVendor>`      |
| `getBillData()`    | `Optional<List<BillPayOutData>>` | `Optional<List<PayoutSubscriptionBill>>`  |
| `getPaymentData()` | `Optional<QueryPaymentData>`     | `Optional<PayoutSubscriptionPaymentData>` |

`PayoutSubscriptionPaymentData.getPaymentDetails()` returns an `Optional<PayoutSubscriptionPaymentDetails>`. Update any code that names the old types:

```java
// Before
Optional<VendorQueryRecord> vendor = record.getVendor();

// After
Optional<PayoutSubscriptionVendor> vendor = record.getVendor();
```

### New payment data type in list payout subscriptions

`PayoutSubscriptionQueryRecordPascal.getPaymentData()` now returns an `Optional<PayoutSubscriptionPaymentDataPascal>` instead of an `Optional<QueryPaymentData>`.

### New fields on payout subscriptions

`PayoutSubscriptionQueryRecord` and `PayoutSubscriptionQueryRecordPascal` add `getSameDayAch()`, `getDoNotCreateBills()`, `getAllowDuplicatedBills()`, `getAutoConvertSameDayAch()`, and `getSubscriptionType()`. The payment data types add `getWalletType()` and `getPayorSignature()`, and `PayoutSubscriptionPaymentDetails` adds the payout details methods, such as `getOrderId()`.

### Vendor record changes

`VendorQueryRecord.getStoredMethods()` now returns an `Optional<List<VendorStoredMethod>>`. `VendorStoredMethod` adds `getIsDefault()`. `VendorQueryRecord` adds `getVendorPortal()` (`Optional<VendorPortalAccess>`), and `BillingDataResponse` adds `getCountry()`.

## October 5, 2026

## v1.0.20

This release includes breaking changes. The notification log and stored payment method types now match what the API returns, and OCR results have new amount fields. See [September 22, 2026](/changelog/api-changelog/2026/9/22), [September 29, 2026](/changelog/api-changelog/2026/9/29), [October 1, 2026](/changelog/api-changelog/2026/10/1), [October 2, 2026](/changelog/api-changelog/2026/10/2), and [October 5, 2026](/changelog/api-changelog/2026/10/5) for more information.

### Notification log retry methods return new types

`notificationlogs().retryNotificationLog` now returns `NotificationRetryResponse`, which has a single `getMessage()` method, instead of `NotificationLogDetail`. `notificationlogs().bulkRetryNotificationLogs` now returns `String` instead of `void`. The async and raw clients have the same changes.

```java
// Before
NotificationLogDetail log = client.notificationlogs().retryNotificationLog("UUID");

// After
NotificationRetryResponse retry = client.notificationlogs().retryNotificationLog("UUID");
String message = retry.getMessage();
String bulk = client.notificationlogs().bulkRetryNotificationLogs(Arrays.asList("UUID"));
```

### Notification log types share a new base interface

`NotificationLog` and `NotificationLogDetail` now both implement the new `INotificationLogBase` interface, and there's a new `NotificationLogBase` class. `NotificationLogDetail` no longer implements `INotificationLog`.

* `getResponseStatus()` now returns `String` instead of `Optional<String>`. It holds a status message such as `OK`. The HTTP status code is in `getResponseStatusCode()`.
* On `NotificationLogDetail`, `getResponseContent()` now returns `String` instead of `Optional<String>`.
* Both types add the required `getOrganizationName()`, `getPaypointName()`, `getRequestId()`, and `getResponseStatusCode()` (`int`).
* `NotificationLog` adds the required `getNotificationType()`, `getOrganizationLogo()`, `getOrganizationFavIcon()`, and `getPaypointLogo()`.

The new required fields are new builder stages, so existing `builder()` calls for these types must set them.

### Customer fields on stored payment methods

`GetMethodResponseResponseDataCustomersItem` no longer implements `IPayorDataRequest`, and the `IPayorDataRequest` interface has been removed. `getFirstName()` and `getLastName()` are now `getFirstname()` and `getLastname()`.

#### Removed and added fields

Removed: `additionalData`, `billingAddress1`, `billingAddress2`, `billingCity`, `billingCountry`, `billingEmail`, `billingPhone`, `billingState`, `billingZip`, and `shippingAddress2`.

Added: `additionalFields`, `address`, `address1`, `city`, `country`, `customerEvents`, `customerPortal`, `email`, `phone`, `shippingAddress`, `state`, and `zip`.

### New response fields

* `AddMethodResponse` adds `getPageIdentifier()`, and `AddMethodResponseResponseData` adds `getAuthCode()`, `getAvsResponseText()`, `getCvvResponseText()`, and `getVendorId()`.
* `GetMethodResponseResponseData` adds `getWalletType()`.
* `OcrResultData` adds `getTotalAmount()` and `getDiscount()` (`Optional<Double>`).

## September 18, 2026

## v1.0.19

Regenerated the Java SDK to incorporate latest API documentation improvements. See [September 18, 2026](/changelog/api-changelog/2026/9/18) for more information.

## September 16, 2026

## v1.0.18

Regenerated the Java SDK to incorporate latest API documentation improvements. See [September 16, 2026](/changelog/api-changelog/2026/9/16) for more information.

## September 10, 2026

## v1.0.17

Regenerated the Java SDK to incorporate latest API documentation improvements. See [September 10, 2026](/changelog/api-changelog/2026/9/10) for more information.

## September 9, 2026

## v1.0.16

Regenerated the Java SDK to incorporate latest API documentation improvements. See [September 8, 2026](/changelog/api-changelog/2026/9/8) for more information.

## August 28, 2026

## v1.0.15

### New `businessSummary` field on `PaypointData`

`PaypointData` now includes `businessSummary`, a business description from boarding. See [August 28, 2026](/changelog/api-changelog/2026/8/28) for more information.

## July 28, 2026

## v1.0.13

Regenerated the Java SDK to incorporate latest API documentation improvements. See [July 28, 2026](/changelog/api-changelog/2026/7/28) for more information.

## July 27, 2026

## v1.0.12

Added OAuth2 client-credentials support via `PayabliApiClient.withCredentials(clientId, clientSecret)`. The SDK handles the token exchange and refresh automatically:

```java
PayabliApiClient client = PayabliApiClient
        .withCredentials("...", "...")
        .environment(Environment.SANDBOX)
        .build();
```

The existing `new PayabliApiClientBuilder().apiKey(...)` builder flow still works unchanged — no action needed if you're not switching auth methods. See the [Java SDK guide](/developers/platform-sdk-java-guide) and [Authentication](/developers/authentication) to compare both methods.

## July 20, 2026

## v1.0.8

Changed the `VendorQueryRecord.AdditionalData` type from `Optional<Map<String, Map<String, Object>>>` to `Optional<Map<String, String>>` to match the API.

## June 30, 2026

## v1.0.5

Regenerated the Java SDK to incorporate latest API documentation improvements. See [June 30, 2026](/changelog/api-changelog/2026/6/30) for more information.

## June 11, 2026

## v1.0.1

Regenerated the Java SDK to incorporate latest API documentation improvements. See [June 11, 2026](/changelog/api-changelog/2026/6/11) for more information.

## June 8, 2026

## v1.0.0

As part of an ongoing effort to improve the consistency and usability of our SDKs, we've updated the SDK generation process.
This update introduces breaking changes to the SDK.
All breaking changes affect only method signatures and namespacing, not core record types or properties.
SDK initialization, configuration, business logic, and workflows remain unchanged.
For more information on precise method signatures and example usage, please see the [SDK reference on GitHub](https://github.com/payabli/sdk-java/blob/main/reference.md).

### Type package consolidated

All 212 type classes have moved from per-resource `types.*` packages into `io.github.payabli.api.types`. Resource-specific request classes (e.g. `RequestPaymentV2`, `SearchNotificationLogsRequest`) remain in `resources.<resource>.requests.*`.

#### Removed per-resource type packages

| Old package                          | Example types                                                                                |
| ------------------------------------ | -------------------------------------------------------------------------------------------- |
| `resources.moneyin.types`            | `TransRequestBody`, `PayMethodCredit`, `PayorDataRequest`, `PaymentDetail`                   |
| `resources.moneyout.types`           | `RequestOutAuthorize`, `ReissueOutRequest`                                                   |
| `resources.moneyouttypes.types`      | `AuthorizePayoutBody` *(removed)*, `AuthorizePaymentMethod`, `ReissuePayoutBody` *(removed)* |
| `resources.tokenstorage.types`       | `RequestTokenStorage`, `AddMethodResponse`                                                   |
| `resources.subscription.types`       | `SubscriptionRequestBody` *(removed)*, `RequestSchedulePaymentMethod`                        |
| `resources.payoutsubscription.types` | `PayoutSubscriptionRequestBody` *(removed)*                                                  |
| `resources.notification.types`       | `AddNotificationRequest`, `UpdateNotificationRequest`                                        |
| `resources.notificationlogs.types`   | `NotificationLogSearchRequest` *(removed)*                                                   |
| `resources.paymentlink.types`        | `PaymentPageRequestBody` *(removed)* → now `PaymentPageRequestBodyOut`                       |
| `resources.customer.types`           | `CustomerData`                                                                               |
| `resources.bill.types`               | `BillOutData`, `BillItem`                                                                    |
| `resources.invoice.types`            | `InvoiceDataRequest`                                                                         |
| `resources.boarding.types`           | `AddApplicationRequest`, `AchSetup`, `CardSetup`                                             |

### Request body wrapper types removed

The following types are deleted. Their fields are now set directly on the parent request builder.

#### Removed types and their replacements

| Removed type                    | Fields now on                                                                          |
| ------------------------------- | -------------------------------------------------------------------------------------- |
| `SubscriptionRequestBody`       | `RequestSchedule` builder                                                              |
| `PayoutSubscriptionRequestBody` | `RequestPayoutSchedule` builder                                                        |
| `AuthorizePayoutBody`           | `RequestOutAuthorize` builder *(also renamed from `MoneyOutTypesRequestOutAuthorize`)* |
| `ReissuePayoutBody`             | `ReissueOutRequest` builder                                                            |
| `NotificationLogSearchRequest`  | `SearchNotificationLogsRequest` builder                                                |
| `PaymentPageRequestBody`        | `PayLinkDataInvoice` builder fields directly                                           |

### `PayMethodCredit` staged builder enforces field order

The builder now requires `cardexp()` → `cardnumber()` → `method(PayMethodCreditMethod.CARD)` before optional fields are accessible. Passing optional setters before the required chain causes a compile error. Affects `authorize`, `getpaid`, `getpaidv2`, `authorizev2`, and `subscription.newSubscription`.

`RequestCreditPaymentMethod` also gains a required `method(RequestCreditPaymentMethodMethod.ACH)` field for `MoneyIn.credit`.

### Collection type changes

#### Full list

| Field                           | Old type                           | New type                           |
| ------------------------------- | ---------------------------------- | ---------------------------------- |
| `CustomerData.identifierFields` | `List<Optional<String>>`           | `List<String>`                     |
| `BillItem.itemCategories`       | `Optional<List<Optional<String>>>` | `Optional<List<String>>`           |
| `BillOutData.terms`             | `String` (e.g. `"NET30"`)          | `Terms` enum (e.g. `Terms.NET_30`) |
| `BillOutData.vendor`            | `VendorData`                       | `BillOutDataVendor`                |

### Notification log ID type changed

`getNotificationLog`, `retryNotificationLog`, and `bulkRetryNotificationLogs` now accept `String` instead of `UUID` for ID parameters. `bulkRetryNotificationLogs` changes from `List<UUID>` to `List<String>`.

### Subscription date format changed

`ScheduleDetail.startDate` and `ScheduleDetail.endDate` now use ISO 8601 (`yyyy-MM-dd`) instead of `MM-dd-yyyy`.

## May 20, 2026

## v0.0.330

Fixed an issue where the Java SDK wasn't properly deserializing the `ExtraData` field in certain API response models.

## May 11, 2026

## v0.0.329

Regenerated the Java SDK to incorporate latest API documentation improvements. See [May 11, 2026](/changelog/api-changelog/2026/5/11) for more information.

## May 8, 2026

## v0.0.327

Fixed a bug that caused the `CustomerSummary` object to be deserialized incorrectly in customer records.
Fixed a bug that caused the `InvoiceData` object to be deserialized incorrectly in transaction records.
Regenerated the Java SDK to incorporate latest API definition updates.

## April 30, 2026

## v0.0.326

Fixed a bug that caused `moneyIn().getpaidv2` to error when deserializing the response. Regenerated the Java SDK to incorporate latest API definition updates.

## April 13, 2026

## v0.0.321

Regenerated the Java SDK to incorporate latest API documentation improvements. See [April 13, 2026](/changelog/api-changelog/2026/4/13) for more information.

_Showing the 20 most recent of 32 entries. Append `/llms.txt` to the changelog URL for the complete index._