4.0.0: exact validated transaction IDs

Exact transaction IDs

The SDK validates transaction IDs when creating response models and exposes them as exact PHP int values. Applications can pass $model->transactionId directly to existing request DTOs without repeating format validation.

• Preserve precision for large raw JSON integers without conversion through float.
• Throw ResponseFormatException (extends CloudpaymentsException) for missing, malformed, floating-point or out-of-range IDs in a supplied transaction model.
• Validate and hydrate supplied models regardless of Success, including declined payments and 3-D Secure challenges.
• Keep successful confirm/void and other contract-valid responses without a model valid.
• Preserve optional model defaults and safely detect the absence of a 3DS challenge.

CloudPayments documents TransactionId as Long and shows it as a JSON number. Signed decimal-string normalization and the PHP_INT_MIN–PHP_INT_MAX representation limit are SDK behavior. No undocumented digit-count or leading-zero restriction is imposed.

Migration from 3.x

1. Use SDK-returned transaction models, or provide response data when constructing them manually:

   use Excent\Cloudpayments\Response\Models\TransactionModel;
   
   $model = new TransactionModel((object) ['TransactionId' => 123]);

   Empty construction followed by fill() is no longer supported.

2. Handle ResponseFormatException when an API response contains an invalid transaction model. Integer request DTO signatures are unchanged.

3. Custom subclasses that redeclare a response model property must use the native mixed type, for example public mixed $model = null;, with the appropriate PHPDoc type.

PHP requirement remains 8.1+. No new runtime dependencies.

Local validation passed: 154 PHPUnit tests / 412 assertions, PHPStan, PHP CS Fixer, Rector and Composer validation. The release is published from the merged PR after the PHP 8.1–8.5 CI matrix and quality checks succeed.