> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mangopay.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mangopay.com/_mcp/server.

# PHP SDK - 4.0.0

May 6, 2026

> **Warning**
>
> **Caution – Major version change with breaking changes**
>
> This SDK major version increase changes how nested response properties are typed and mapped — properties previously returned as raw `stdClass` objects are now hydrated as typed Mangopay entities. Review the notes below and test your integration before upgrading in Production.

## Sub-object casting

### Breaking change

#### Typed sub-object mapping

Added missing `GetSubObjects()` mappings across response and request DTOs. Properties that were previously returned as raw `stdClass` objects are now hydrated as typed Mangopay entities.

Code that read nested properties as plain objects, such as via array-style access, `property_exists`, or by passing them to functions that expect `stdClass`, must be updated to use the typed classes.

Affected classes:

* `BankingAliasIBAN` (`LocalAccountDetails` → `LocalAccountDetailsBankingAlias`)
* `BanksByCountry` (`Banks` → `Bank[]`)
* `CardPreAuthorization` (added `BrowserInfo` → `BrowserInfo`, `Shipping` → `Shipping`)
* `CardValidation` (added `CardInfo` → `CardInfo`)
* `Check` (`Data`, `Reasons` → `CheckData[]`)
* `Conversion` (`DebitedFunds`, `CreditedFunds`, `Fees` → `Money`; `RequestedFees` → `CustomFees`; `ConversionRateResponse` → `ConversionRate`; `MarginsResponse` → `MarginsResponse`)
* `ConversionQuote` (`DebitedFunds`, `CreditedFunds` → `Money`; `Fees`, `RequestedFees` → `CustomFees`; `ConversionRateResponse` → `ConversionRate`; `UserMargin` → `UserMargin`; `MarginsResponse` → `MarginsResponse`)
* `CreateClientWalletsInstantConversion` (`DebitedFunds`, `CreditedFunds` → `Money`)
* `CreateInstantConversion` (`DebitedFunds`, `CreditedFunds` → `Money`; `Fees` → `CustomFees`; `UserMargin` → `UserMargin`)
* `IdentityVerification` (`Checks` → `Check[]`)
* `InstantPayout` now extends `Libraries\Dto`; `UnreachableReason` → `FallbackReason`
* `IntentSplits` (`Splits` → `PayInIntentSplit[]`)
* `InternationalAccountDetails` (`Address` → `VirtualAccountAddress`, `Account` → `InternationalAccount`)
* `LocalAccountDetails` (`Address` → `VirtualAccountAddress`, `Account` → `LocalAccount`)
* `MarginsResponse` (`Mangopay`, `User` → `UserMargin`)
* `PayIn` (`AuthenticationResult` → `AuthenticationResult`)
* `PayInExecutionDetailsExternalInstruction` (`DebitedBankAccount` → `DebitedBankAccount`)
* `PayInIntent` (`LineItems` → `PayInIntentLineItem[]`; `Captures` → `PayInIntentCapture[]`; `Capture` → `PayInIntentCapture`; `Refunds` → `PayInIntentRefund[]`; `Refund` → `PayInIntentRefund`; `Disputes` → `PayInIntentDispute[]`; `Dispute` → `PayInIntentDispute`; `Splits` → `PayInIntentSplitInfo[]`)
* `PayInIntentCapture`, `PayInIntentDispute`, `PayInIntentRefund`, `PayInIntentSplitInfo` (`LineItems` → `PayInIntentLineItem[]`)
* `PayInPaymentDetailsBlik` (`BrowserInfo` → `BrowserInfo`)
* `PayInPaymentDetailsCard` (`BrowserInfo` → `BrowserInfo`, `Shipping` → `Shipping`)
* `PayInRecurringRegistration` (`FirstTransactionDebitedFunds`, `FirstTransactionFees`, `NextTransactionDebitedFunds`, `NextTransactionFees` → `Money`; `Billing` → `Billing`; `Shipping` → `Shipping`)
* `PayInRecurringRegistrationGet` (`CurrentState` → `RecurringPayInCurrentState`)
* `PayInRecurringRegistrationRequestResponse` (`TotalAmount` → `Money`)
* `PayInRecurringRegistrationUpdate` (`Shipping` → `Shipping`, `Billing` → `Billing`)
* `PayOutEligibilityRequest` (`DebitedFunds`, `Fees` → `Money`)
* `PayOutEligibilityResponse` (`InstantPayout` → `InstantPayout`)
* `RecurringPayInCIT` (`BrowserInfo` → `BrowserInfo`; `DebitedFunds`, `Fees` → `Money`)
* `RecurringPayInCurrentState` (`CumulatedDebitedAmount`, `CumulatedFeesAmount` → `Money`)
* `RecurringPayInMIT` (`DebitedFunds`, `Fees` → `Money`)
* `RecurringPayPalPayInCIT` (`Shipping` → `Shipping`)
* `RecurringPayPalPayInMIT` (`DebitedFunds`, `Fees` → `Money`; `Shipping` → `Shipping`)
* `Report` (`Filters` → `ReportFilters`)
* `ReportRequest` (`Filters` → `FilterReports`)
* `ScaStatus` (`ConsentScope` → `ConsentScope`)
* `SettlementValidation` (`FooterErrors` → `SettlementValidationFooter[]`; `LinesErrors` → `SettlementValidationLine[]`)
* `SupportedBank` (`Countries` → `BanksByCountry[]`)
* `VirtualAccount` (`LocalAccountDetails` → `LocalAccountDetails`; `Capabilities` → `VirtualAccountCapabilities`)
* `VirtualAccountAvailabilities` (`Collection`, `UserOwned` → `VirtualAccountAvailability[]`)

---

## Virtual Account details

### Breaking change

#### `VirtualAccount.InternationalAccountDetails` type fix

The `VirtualAccount.$InternationalAccountDetails` property is now correctly typed as `InternationalAccountDetails[]` instead of a single `InternationalAccountDetails` object, matching the API response.

Code that previously accessed this property as a single object must be updated to iterate the array.

Previously:

**`PHP`**

```php PHP
$virtualAccount->InternationalAccountDetails->Iban;
```

Now:

**`PHP`**

```php PHP
$virtualAccount->InternationalAccountDetails[0]->Iban;
```