Skip to content

Complete Cloud device API migration guide #2049

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gcatanese merged 3 commits into from
Aug 24, 2026
Merged

Complete Cloud device API migration guide #2049

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b4bdec1
Document Cloud device migration differences
gcatanese Aug 24, 2026
1bcd0d5
Correct Cloud device migration mappings
gcatanese Aug 24, 2026
f07f2f3
Clarify SaleToAcquirerData encoding
gcatanese Aug 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions doc/MigratingToCloudDeviceApi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,13 +130,44 @@ Several enum classes are named differently in the Cloud device API to match the

**Note**: enums that already end with `Type` in the spec (for example, `MessageType`, `TokenRequestedType`, `AccountType`) are **not** renamed.

#### Enum value differences

Some Java enum constants were renamed, added, or removed. Update references to these constants when migrating:

| Enum | Changes in the Cloud device API |
|------|---------------------------------|
| `CharacterStyleType` -> `CharacterStyle` | `UNDERLINED` (`"Underlined"`) is renamed to `UNDERLINE` (`"Underline"`). |
| `MessageCategoryType` -> `MessageCategory` | `BATCH`, `CARD_READER_APDU`, `CARD_READER_INIT`, `CARD_READER_POWER_OFF`, `PIN`, `SOUND`, and `TRANSMIT` are removed. `NONE` is added. |
| `EventToNotifyType` -> `EventToNotify` | `NETWORK_CONNECTED` and `NETWORK_DISCONNECTED` are removed. `USE_ANOTHER_CARD_FOR_PREAUTH` is added. |
| `IdentificationType` | `ISO_TRACK_2` is renamed to `ISO_TRACK2`. Its serialized value, `"ISOTrack2"`, is unchanged. |
| `PINFormatType` -> `PINFormat` | `ISO_0`, `ISO_1`, `ISO_2`, and `ISO_3` are renamed to `ISO0`, `ISO1`, `ISO2`, and `ISO3`. Their serialized values are unchanged. |
| `ReversalReasonType` -> `ReversalReason` | `UNABLE_2_COMPL` is renamed to `UNABLE2_COMPL`. Its serialized value, `"Unable2Compl"`, is unchanged. |
| `AuthenticationMethodType` -> `PaymentResult.AuthenticationMethodEnum` | `ONLINE_PIN` (`"OnlinePIN"`) is added. |

#### Other enum class changes

`CheckTypeCodeType` is renamed to `TypeCode`.

Some standalone Terminal (Cloud) API enums are replaced by enums nested in the models that use them:

| Terminal (Cloud) API (nexo) | Cloud device API (tapi) |
|-----------------------------|-------------------------|
| `EntryModeType` | `CardData.EntryModeEnum`, `LoyaltyAccountID.EntryModeEnum`, `StoredValueAccountID.EntryModeEnum` |
| `ForceEntryModeType` | `CardAcquisitionTransaction.ForceEntryModeEnum`, `TransactionConditions.ForceEntryModeEnum` |
| `CustomerOrderReqType` | `LoginRequest.CustomerOrderReqEnum`, `SaleData.CustomerOrderReqEnum` |
| `TotalDetailsType` | `GetTotalsRequest.TotalDetailsEnum` |
| `AuthenticationMethodType` | `PaymentResult.AuthenticationMethodEnum` |
| `ServicesEnabledType` | `EnableServiceRequest.ServicesEnabledEnum` |

#### Model classes

Some classes are also renamed to adopt the name of the model in the OpenAPI specification.

| Terminal (Cloud) API (nexo) | Cloud device API (tapi) |
|--------------------------------|---------------------------|
| `TransactionIdentification` | `TransactionIDType` |
| `SignaturePoint` | `Point` |
| `CardholderPIN` | `CardHolderPIN` |

#### Setter/getter naming

Expand All @@ -149,6 +180,8 @@ Some attribute accessors differ due to the way the code generator handles certai
| `POIData` | `getPOIReconciliationID()` | `getPoIReconciliationID()` |
| `POIData` | `setPOIReconciliationID()` | `setPoIReconciliationID()` |
| `CardData` | `getMaskedPAN()` | `getMaskedPan()` |
| `ICCResetData` | `getATRValue()` | `getAtRValue()` |
| `ICCResetData` | `setATRValue()` | `setAtRValue()` |

### Type changes

Expand Down Expand Up @@ -203,6 +236,18 @@ instalment.setFirstPaymentDate(LocalDate.of(2025, 1, 15));
- In `CurrencyConversion`: the `rate` and `markup` fields are `String` instead of `BigDecimal`
- In `POIData`: `poIReconciliationID` is `Integer` instead of `String`

#### `CurrencyConversion.convertedAmount`: `Amount` -> `ConvertedAmount`

The `CurrencyConversion.convertedAmount` field uses the `ConvertedAmount` model in the Cloud device API instead of `Amount`.

#### `SaleToAcquirerData`: object -> `String`

In the Terminal (Cloud) API, `SaleData.saleToAcquirerData` is a `SaleToAcquirerData` object. In the Cloud device API, it is a `String` containing Base64-encoded JSON. Use the existing `SaleToAcquirerData.toBase64()` helper to serialize and encode the object before setting it:

```java
saleData.setSaleToAcquirerData(saleToAcquirerData.toBase64());
```

#### Boolean helper methods

The Terminal (Cloud) API `nexo` models include boolean helper methods with default values (for example, `PaymentResult.isOnlineFlag()` defaulting to `true`). The Cloud device API `tapi` models do not include these convenience methods, so null checks are needed.
Expand Down