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

# Python SDK

**Package:** [mangopay4-python-sdk](https://pypi.org/project/mangopay4-python-sdk)

---

## 4.1.0 - Oct 1, 2026

#### [4.1.0 - Oct 1, 2026](/release-notes/sdk/python/4-1-0)

Added

* Extended Preauthorization feature to rename Deposit Preauthorization
* Settlement hook event types
* `ProfilingAttemptReference` on SCA users

Deprecated

* Deposit Preauthorization feature deprecated

Fixed

* `__str__` representations of several resources

## 4.0.1 - Sep 14, 2026

#### [4.0.1 - Sep 14, 2026](/release-notes/sdk/python/4-0-1)

Fixed

* Python 3.14 support

## 4.0.0 - Sep 2, 2026

#### [4.0.0 - Sep 2, 2026](/release-notes/sdk/python/4-0-0)

Breaking change

* Python version support bumped, dropping 3.9
* Minimum dependency versions
* Removed setup.py install, sample console script, and dependency upper bounds

Changed

* Build system migration to Poetry

## 3.60.0 - Sep 1, 2026

#### [3.60.0 - Sep 1, 2026](/release-notes/sdk/python/3-60-0)

Added

* `KycInformation` containing `KycRenewalDeadline` on the Regulatory endpoint
* `AccountFunding` on Card Direct pay-ins

## 3.59.0 - Aug 18, 2026

#### [3.59.0 - Aug 18, 2026](/release-notes/sdk/python/3-59-0)

Added

* Support for multi-session PSC flow on hosted KYB for Business
* Identity verification event types
* GET List Intent external providers
* `Tag` on intent splits

## 3.58.0 - Jul 14, 2026

#### [3.58.0 - Jul 14, 2026](/release-notes/sdk/python/3-58-0)

Fixed

* Echo Settlement validation errors response mapping

Deprecated

* Non-SCA user endpoints
* Deposit-preauthorization complement flow

## 3.57.0 - Jun 24, 2026

#### [3.57.0 - Jun 24, 2026](/release-notes/sdk/python/3-57-0)

Added

* `FlowDescriptor` for declaring pay-in `Beneficiaries`
* Apple Pay and Google Pay recurring pay-ins
* Support for PayPal deposit preauthorizations
* Support for `DateRangeBy` on reports
* Support for `Email` on webhooks
* Recipients pagination

Deprecated

* Older recurring pay-in and deposit-preauthorization classes

## 3.56.0 - Mar 30, 2026

#### [3.56.0 - Mar 30, 2026](/release-notes/sdk/python/3-56-0)

Breaking change

* Payconiq PayIn removed following discontinuation

Added

* Klarna discount property on line items

---

## 3.55.0 - Mar 23, 2026

### Added

#### Support for mTLS authentication

To support mTLS authentication for [SCA on platforms](/guides/sca/platform), which is required for platforms taking [SCA-triggering action under proxy](/guides/sca/proxy-management):

* Added `mtls_cert`, `mtls_private_key` properties
* Moved `requests_session = requests.Session()` from being global to being instantiated per handler (`self._session = requests.Session()`)
* Updated the requests logic to add the mTLS certificate if present
* Updated `README.md` file with details on [how to configure mTLS for the SDK](/guides/sca/platform#4-integrate-mtls-in-the-sdk)

**Note:** The SDK requires **TLS 1.2+** for TLS compliance, even for non-mTLS connections, in line with [Mangopay's security guidelines](/security#2-a-tls-and-https).

## 3.54.1 - Feb 19, 2026

### Added

#### ChargeBearer body parameter on payouts

On [POST Create a Payout](/api-reference/payouts/create-payout), platforms can now request to pay all SWIFT fees using the `OUR` value of the new `ChargeBearer` property ([API release note](/release-notes/api/2026-02-16)):

* Added `charge_bearer` param (CharField) to `BankWirePayOut` class
* Updated tests

### Added

#### AuthenticationType response property on card pay-ins

The `AuthenticationResult.AuthenticationType` response property is now returned on card pay-ins ([API release note](/release-notes/api/2026-02-23)):

* Added the `AuthenticationResult` class
* Added the `AuthenticationResultField` class
* Added `authentication_result` param (AuthenticationResultField) to `PreAuthorization`, `CardValidation`, `Deposit`, `PayIn` classes
* Updated tests

### Added

#### TelephoneOrder body parameter on recurring card pay-ins (CIT and MIT)

To support the `TelephoneOrder` property on [POST Create a Recurring PayIn](/api-reference/recurring-card-payins/create-recurring-card-payin) (both CIT and MIT payloads):

* Added `payment_category` (CharField) to `RecurringPayInCIT` and `RecurringPayInMIT` classes
* Updated tests

## 3.54.0 - Feb 12, 2026

### FX

### Breaking change

#### Custom fees

To support percentage-based FX fees ([API release note](/release-notes/api/2026-02-11)):

> **Warning**
>
> **Caution - Breaking change**
>
> * The `InstantConversion.Fees` type is now `CustomFeesField` instead of `MoneyField`

* Added `Fees, RequestedFees` to `ConversionQuote`
* Added `RequestedFees` to `Conversion`

### Added

#### User margin

To support the FX user margin ([API release note](/release-notes/api/2026-02-11)):

* Added `UserMargin` to `ConversionQuote`, `InstantConversion`
* Added `MarginsResponse` to `ConversionQuote`, `Conversion`

### Echo

### Breaking change

#### Settlement upload endpoints

To support the new behavior of the [POST Create a Settlement](/api-reference/settlements/create-settlement) endpoint to obtain an `UploadUrl`:

* Updated settlement\_sample.csv and tests
* Added `file_name` and `upload_url` to `Settlement`

> **Warning**
>
> **Caution - Breaking change**
>
> * Replaced `upload` method in `Settlement` with `generate_upload_url`:
>
> ```py Python
> settlement = Settlement(file_name='settlement_sample.csv')
> created = SettlementTestLive._settlement = Settlement(**settlement.generate_upload_url())
> ```

> **Warning**
>
> **Caution - Breaking change**
>
> * Replaced `update` method in `Settlement` with: `generate_new_upload_url`
>
> ```py Python
> dto = Settlement(id=settlement.settlement_id, file_name='updated_settlement_sample.csv')
> result = Settlement(**dto.generate_new_upload_url())
> ```

### Added

#### GET validations for a Settlement endpoint

To support the [GET View validation errors for a Settlement](/api-reference/settlements/view-settlement-validations) endpoint:

* Added `SettlementValidation` class
* Added `get` method to `SettlementValidation`

**`Python`**

```py Python
validations = SettlementValidation.get(settlement.settlement_id, page=1, per_page=10)
```

#### PUT Cancel a Settlement endpoint

To support the [PUT Cancel a Settlement](/api-reference/settlements/cancel-settlement) endpoint:

* Changes: added `cancel` method to `Settlement`

**`Python`**

```py Python
cancelled = Settlement.cancel(settlement.settlement_id)
```

#### Intent unfunded amounts and source wallet

* Added `SplitOriginWalletId` to `PayInIntentSplit`
* Added `UnfundedAmount` to `PayInIntent`

#### POST Create an Intent Refund

To support [POST Create an Intent Refund](/api-reference/intents/create-intent-refund):

* Added `Refund` and `Capture` to `PayInIntent`
* Added `create_refund` method to `PayInIntent`

**`Python`**

```py Python
PayInIntent.create_refund(intent.id, **dto)
```

#### POST Reverse an Intent Refund

To support [POST Reverse an Intent Refund](/api-reference/intents/create-intent-refund):

* Added `reverse_refund` method to `PayInIntent`

**`Python`**

```py Python
PayInIntent.reverse_refund(intent.id, intent.refund.id, **dto)
```

#### POST Create an Intent Dispute

To support [POST Create an Intent Dispute](/api-reference/intents/create-intent-refund):

* Added `Dispute` to `PayInIntent`
* Added `create_dispute` method to `PayInIntent`

**`Python`**

```py Python
PayInIntent.create_dispute(intent.id, intent.capture.id, **dto)
```

#### PUT Update an Intent Dispute

To support [PUT Update an Intent Dispute](/api-reference/intents/create-intent-dispute):

* Added `decision` to `PayInIntent`
* Added `update_dispute_outcome` method to `PayInIntent`

**`Python`**

```py Python
PayInIntent.update_dispute_outcome(intent.id, intent.capture.id, intent.dispute.id, **update_outcome_dto)
```

## 3.53.0 - Jan 30, 2026

### Added

#### Support for new SCA status endpoint

The SDK now supports the new [GET View the SCA status of a User](/api-reference/users/view-user-sca-status) endpoint.

Added ConsentScopeField in mangopay/fields.py:

```python
class ConsentScopeField(Field):
    def python_value(self, value):
        if value is not None:
            return ConsentScope(contact_information_update=value.get('ContactInformationUpdate', None),
                                recipient_registration=value.get('RecipientRegistration', None),
                                transfer=value.get('Transfer', None),
                                view_account_information=value.get('ViewAccountInformation', None))

        return value

    def api_value(self, value):
        value = super(ConsentScopeField, self).api_value(value)

        if isinstance(value, ConsentScope):
            result = {}
            if value.contact_information_update is not None:
                result['ContactInformationUpdate'] = value.contact_information_update
            if value.recipient_registration is not None:
                result['RecipientRegistration'] = value.recipient_registration
            if value.transfer is not None:
                result['Transfer'] = value.transfer
            if value.view_account_information is not None:
                result['ViewAccountInformation'] = value.view_account_information
            return result

        return value
```

Added ScaStatus class in mangopay/resources.py:

```python
@python_2_unicode_compatible
class ScaStatus(BaseModel):
    user_status = CharField(api_name='UserStatus')
    is_enrolled = BooleanField(api_name='IsEnrolled')
    last_enrollment_date = DateTimeField(api_name='LastEnrollmentDate')
    last_consent_collection_date = DateTimeField(api_name='LastConsentCollectionDate')
    consent_scope = ConsentScopeField(api_name='ConsentScope')

    class Meta:
        verbose_name = 'sca_status'
        verbose_name_plural = 'sca_statuses'
        url = {
            'GET': '/sca/users/%(id)s/sca-status',
        }

    @staticmethod
    def get(user_id, *args, **kwargs):
        kwargs['id'] = user_id
        select = SelectQuery(ScaStatus, *args, **kwargs)
        select.identifier = 'GET'
        return select.get("", *args, **kwargs)
```

Corresponding tests updated in tests/test\_users.py.

#### New event types

Added new constants to mangopay/constants.py:

```python
EVENT_TYPE_CHOICES = Choices(
('SCA_CONTACT_INFORMATION_UPDATE_CONSENT_GIVEN', 'sca_contact_information_update_consent_given', 'Sca Contact Information Update Consent Given'),
('SCA_CONTACT_INFORMATION_UPDATE_CONSENT_REVOKED', 'sca_contact_information_update_consent_revoked', 'Sca Contact Information Update Consent Revoked'),
('SCA_TRANSFER_CONSENT_GIVEN', 'sca_transfer_consent_given', 'Sca Transfer Consent Given'),
('SCA_TRANSFER_CONSENT_REVOKED', 'sca_transfer_consent_revoked', 'Sca Transfer Consent Revoked'),
('SCA_RECIPIENT_REGISTRATION_CONSENT_GIVEN', 'sca_recipient_registration_consent_given', 'Sca Recipient Registration Consent Given'),
('SCA_RECIPIENT_REGISTRATION_CONSENT_REVOKED', 'sca_recipient_registration_consent_revoked', 'Sca Recipient Registration Consent Revoked'),
('SCA_VIEW_ACCOUNT_INFORMATION_CONSENT_GIVEN', 'sca_view_account_information_consent_given', 'Sca View Account Information Consent Given'),
('SCA_VIEW_ACCOUNT_INFORMATION_CONSENT_REVOKED', 'sca_view_account_information_consent_revoked', 'Sca View Account Information Consent Revoked'),
('SCA_EMAIL_VERIFIED', 'sca_email_verified', 'Sca Email Verified'),
('SCA_PHONE_NUMBER_VERIFIED', 'sca_phone_number_verified', 'Sca Phone Number Verified'),
)
```

#### RecipientId property on payouts

To support the sending of `RecipientId` on payouts, in mangopay/resources.py:

* Moved the Recipient class before the BankWirePayOut class in order to be able to reference the recipient inside the payout
* Inside the BankWirePayOut class, made `bank_account` nullable
* Inside the BankWirePayOut class added reference to recipient:

```python
recipient = ForeignKeyField(Recipient, api_name='RecipientId')
```

Added PayOutsTestLive class in tests/test\_payouts.py.

### Fixed

#### User-Agent header

In mangopay/**init**.py The SDK now tries to use importlib.metadata.version to get the package version and falls back to the previous method:

```python
client_id = None
apikey = None
api_url = 'https://api.mangopay.com/v2.01/'
api_sandbox_url = 'https://api.sandbox.mangopay.com/v2.01/'
temp_dir = None
api_version = 2.01
sandbox = True
uk_header_flag = False

package_version = None
try:
    # try importlib.metadata first
    from importlib.metadata import version
    package_version = version('mangopay4-python-sdk')
except Exception:
    # fallback for development/editable installs
    try:
        with open('./setup.py', 'r') as f:
            for line in f:
                if line.startswith('    version'):
                    package_version = line.split('=')[1].replace("'", "").replace(",", "").replace("n", "").strip()
    except:
        None

from .api import APIRequest  # noqa
from .utils import memoize
def _get_default_handler():
    return APIRequest()
get_default_handler = memoize(_get_default_handler, {}, 0)
```

## 3.52.0 - Nov 26, 2025

### Changed

* changed naming convention to mangopay4

## 3.51.1 - Nov 25, 2025

### Added

* Support for `ScaContext` on [POST Create a Recipient](/api-reference/recipients/create-recipient) for platforms taking action by [proxy with consent](/guides/sca/proxy-management) from the user ([API release note](/release-notes/api/2025-11-17))

## 3.51.0 - Oct 27, 2025

### Added

* New [POST Manage proxy consent for a User](/api-reference/users/manage-proxy-consent) endpoint to obtain and manage user consent via the hosted SCA experience (if proxy is activated). A proxy and user consent are now required to use the `USER_NOT_PRESENT` value for `ScaContext` ([API release note](/release-notes/api/2025-10-23))
* `ScaContext` request parameter newly added on all user POST and PUT endpoints, enabling the platform to request these actions with `USER_NOT_PRESENT` – provided the proxy is in place, activated, and the user has given consent ([API release note](/release-notes/api/2025-10-23#sca%3A-scacontext-request-parameter-on-user-endpoints))
* Support for the [GET List Wallets for a User](/api-reference/wallets/list-wallets-user) endpoint
* Support for the `Licensor` property on [GET View a Client](/api-reference/client/view-client)
* Support for [GET View card details for a Web Card PayIn](/api-reference/web-card-payins/view-card-details-web-card-payin) endpoint

### Changed

* `x-tenant-id` deprecated as no longer necessary for UK platforms; the parameter is ignored by Mangopay

## 3.50.0 - Oct 1, 2025

### Added

* [Verification of Payee (VOP)](/guides/vop/recipients-payouts) API response fields (`RecipientVerificationOfPayee` and sub-properties) on the endpoints [GET View a Recipient](/api-reference/recipients/view-recipient), [POST Create a Recipient](/api-reference/recipients/create-recipient), [POST Create a Payout](/api-reference/payouts/create-payout) ([API release note](/release-notes/api/2025-09-30))
* Support for the [POST Cancel an Intent](/api-reference/intents/cancel-intent) endpoint for [Echo](/guides/echo), Mangopay's solution for platforms working with another third-party PSP for funds acquisition
* Support for [POST Submit data for a PayPal PayIn](/api-reference/paypal/submit-data-paypal-payin) endpoint

## 3.49.4 - Sep 23, 2025

### Added

* Webhook event types for [Echo](/guides/echo), Mangopay's solution for third-party PSP integrations: `INTENT_AUTHORIZED`,`INTENT_CAPTURED`,`INTENT_REFUNDED`,`INTENT_REFUND_REVERSED`,`INTENT_DISPUTE_CREATED`,`INTENT_DISPUTE_DEFENDED`,`INTENT_DISPUTE_WON`,`INTENT_DISPUTE_LOST`,`INTENT_SETTLED_NOT_PAID`,`INTENT_PAID`,`SPLIT_CREATED`,`SPLIT_PENDING_FUNDS_RECEPTION`,`SPLIT_AVAILABLE`,`SPLIT_REJECTED`,`SPLIT_REVERSED` #448
* Support for `VirtualAccountPurpose` on Banking Alias object

## 3.49.3 - Sep 8, 2025

### Added

* Support for `ProfilingAttemptReference` on all payment methods

## 3.49.2 - Sep 3, 2025

### Added

* Support for missing fields on TransferRefund

### Changed

* Casing of 3 fields to harmonise on snake\_case ⚠️ **Breaking change** for Conversion `quote_Id`, Document(KYC) `processed_date`, and Ubo `is_active`
* OAuth token refresh buffer before expiry updated to 30s
* Updated testing library to pynose

### Fixed

* Tests

## 3.49.1 - Aug 14, 2025

### Added

* Support for [POST Create a Quoted Conversion between Client Wallets](/api-reference/conversions/create-quoted-conversion-client-wallets) and [POST Create an Instant Conversion between Client Wallets](/api-reference/conversions/create-instant-conversion-client-wallets)
* Support for [POST Create a Bank Wire to the Repudiation Wallet](/api-reference/dispute-settlement/create-bank-wire-payin-to-repudiation-wallet)
* Support for [GET List Disputes pending settlement](/api-reference/disputes/list-disputes-settlement)

## 3.49.0 - Aug 7, 2025

### Added

Support for new Splits endpoints for Echo ([API release note](/release-notes/api/2025-07-16)):

* [PUT Update an Intent Split](/api-reference/intents/update-intent-split)
* [POST Execute an Intent Split](/api-reference/intents/execute-intent-split)
* [POST Reverse an Intent Split](/api-reference/intents/reverse-intent-split)
* [GET View an Intent Split](/api-reference/intents/view-intent-split)

New `ReportTypes` for Echo ([API release note](/release-notes/api/2025-08-06)):

* `ECHO_INTENT`
* `ECHO_INTENT_ACTION`
* `ECHO_SETTLEMENT`
* `ECHO_SPLIT`

## 3.48.1 - Jul 28, 2025

### Added

* `Sku` parameter on LineItem, for [Klarna PayIns](/api-reference/klarna/create-klarna-payin)
* handle new endpoint [View supported banks for Pay by Bank](/api-reference/pay-by-bank/view-supported-banks-pay-by-bank), to enable presentation of banks to user before Pay by Bank payment request

## 3.48.0 - Jul 18, 2025

### Added

Endpoints for [Mangopay Echo](/guides/echo), a solution for platforms working with another third-party PSP for funds acquisition (including via the Mirakl Connector):

* [POST Create an Intent](/api-reference/intents/create-intent)
* [GET View an Intent](/api-reference/intents/view-intent)
* [POST Create a Capture for an Intent](/api-reference/intents/create-intent-capture)
* [POST Create a Settlement](/api-reference/settlements/create-settlement)
* [PUT Update a Settlement](/api-reference/settlements/update-settlement)
* [GET View a Settlement](/api-reference/settlements/view-settlement)
* [POST Create an Intent Split](/api-reference/intents/create-intent-split)

## 3.47.0 - Jul 2, 2025

### Added

* New endpoint [POST Create a Bizum PayIn](/api-reference/bizum/create-bizum-payin)
* New webhook event types for SCA enrollment ([API release note](/release-notes/api/2025-06-23)), note that these are triggered on enrollment not authentication:
* `SCA_ENROLLMENT_SUCCEEDED`
* `SCA_ENROLLMENT_FAILED`
* `SCA_ENROLLMENT_EXPIRED`
* New webhook event types for `UserCategory` change ([API release note](/release-notes/api/2025-06-23)):
* `USER_CATEGORY_UPDATED_TO_OWNER`
* `USER_CATEGORY_UPDATED_TO_PAYER`
* `USER_CATEGORY_UPDATED_TO_PLATFORM`
* Support for `PLATFORM` value to `UserCategory` enum
* Support for [GET List Transactions for a Card Fingerprint](/api-reference/transactions/list-transactions-card-fingerprint)
* Support for [GET List Transactions for a Dispute](/api-reference/transactions/list-transactions-dispute)

## 3.46.1 - Jun 16, 2025

### Added

* [US and CA virtual accounts](/release-notes/api/2025-06-12) for local pay-in collection

## 3.46.0 - Jun 10, 2025

### Added

Endpoints for [new Reporting Service](/release-notes/api/2025-06-05) feature:

* [POST Create a Report](/api-reference/reporting/create-report)
* [GET View a Report](/api-reference/reporting/view-report)
* [GET List all Reports](/api-reference/reporting/list-reports)

Webhook [event types](/webhooks/event-types) for new Reporting Service:

* `REPORT_GENERATED`
* `REPORT_FAILED`

Support for [GET List Disputes for a PayIn](/api-reference/disputes/list-disputes-payin) endpoint.

## 3.45.1 - Jun 6, 2025

### Added

* Support for `RecipientScope` query parameter on [GET List Recipients for a User](/api-reference/recipients/list-recipients-user)
* [POST Validate the format of User data](/api-reference/user-data-format/validate-user-data-format)

### Fixed

* `Status` enum value on Identity Verification object changed from `OUTDATED` to `OUT_OF_DATE`