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

# Python

## Introduction

The Mangopay Python SDK makes working with the Mangopay API easier in a Python environment.

The SDK package is available on Pythony Package Index (PyPI): [mangopay4-python-sdk](https://pypi.org/project/mangopay4-python-sdk/)

> **Warning**
>
> **Caution – Use only the mangopay4 package (late Nov 2025)**
>
> Please ensure you use **only** the package with **mangopay4** in the name (this is the package name and has no connection with the SDK version number).
>
> **Any other package must not be used.** You need to update your package manually.
>
> Since November 25, 2025, Mangopay's official SDKs are no longer accessible on GitHub (with the exception of PHP for publication reasons).

> **Info**
>
> **Prerequisites**
>
> To run the Mangopay Python SDK, you’ll need:
>
> * A `ClientId` and an API key – if you don't have these, [contact Sales](https://mangopay.com/contact) to get access to the [Mangopay Dashboard](https://hub.mangopay.com/)
> * Python 3.14 (recommended) down to 3.10 (not recommended) installed:
>   * pip package manager
>   * requests library
>   * simplejson library
>   * blinker library
>   * six library
>   * pytz library

## Getting started

#### 1. Install the SDK

By installing this package with pip3, all dependencies are installed for you:

```python
pip3 install mangopay4-python-sdk
```

#### 2. Initialize and configure the SDK

```python
import mangopay

mangopay.client_id='your-client-id'
mangopay.apikey='your-api-key'

from mangopay.api import APIRequest
handler = APIRequest(sandbox=True)
```

The configuration object of the SDK supports all the following properties:

<table>
  <thead>
    <tr>
      <th class="header">
        Key
      </th>

      <th class="header">
        Type
      </th>

      <th class="header">
        Default value
      </th>

      <th class="header">
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td class="table-content">
        `client_id`
      </td>

      <td class="table-content">
        string
      </td>

      <td class="table-content">
        None
      </td>

      <td class="table-content">
        Your Mangopay ClientId – can be found in the 

        [Dashboard](https://hub.mangopay.com/)

        .
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `apiKey`
      </td>

      <td class="table-content">
        string
      </td>

      <td class="table-content">
        None
      </td>

      <td class="table-content">
        Your Mangopay API key – can be found in the 

        [Dashboard](https://hub.mangopay.com/)

        .
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `api_url`
      </td>

      <td class="table-content">
        string
      </td>

      <td class="table-content">
        [https://api.mangopay.com/](https://api.mangopay.com/)
      </td>

      <td class="table-content">
        The API production URL. 
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `api_sandbox_url`
      </td>

      <td class="table-content">
        string
      </td>

      <td class="table-content">
        [https://api.sandbox.mangopay.com/v2.01/](https://api.sandbox.mangopay.com/v2.01/)
      </td>

      <td class="table-content">
        The API sandbox URL. 
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `sandbox`
      </td>

      <td class="table-content">
        boolean
      </td>

      <td class="table-content">
        `None`
      </td>

      <td class="table-content">
        To set it to Sandbox, set it as True. To set it to Production, set it as False.
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `timeout`
      </td>

      <td class="table-content">
        float
      </td>

      <td class="table-content">
        `30.0`
      </td>

      <td class="table-content">
        Request timeout in seconds.
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `storage_strategy`
      </td>

      <td class="table-content">
        string
      </td>

      <td class="table-content">
        `StaticStorageStrategy()`
      </td>

      <td class="table-content">
        Mechanism of how the caching works. There are 2 options: 

        `StaticStorageStrategy()`

         for in-memory cache and 

        `FileStorageStrategy()`

         for file-based cache.
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `proxies`
      </td>

      <td class="table-content">
        string
      </td>

      <td class="table-content">
        `None`
      </td>

      <td class="table-content">
        Dictionary mapping protocol or protocol and host name to the URL of the proxy.
      </td>
    </tr>
  </tbody>
</table>

## SDK usage

All endpoints are documented with the related Python SDK method throughout the Mangopay documentation. You should adjust the code examples provided for your usage.

### API handler

When creating a new handler, there are multiple settings to specify depending on your needs.

#### Proxy support

You can use proxies for https, http and ftp protocols:

```python
http_proxy  = "http://10.10.1.10:3128"
https_proxy = "https://10.10.1.11:1080"
ftp_proxy   = "ftp://10.10.1.10:3128"

proxyDict = {
          "http": http_proxy,
          "https": https_proxy,
          "ftp": ftp_proxy
            }

 handler = APIRequest(sandbox=True, proxies=proxyDict)
```

#### Storage strategy

There are two storage strategies that can be used for OAuth tokens:

* `StaticStorageStrategy()` saves the token in memory. If no storage strategy is specified, this method is used by default.
* `FileStorageStrategy()` saves the token in a temporary file.

```python
handler = APIRequest(sandbox=True, storage_strategy=FileStorageStrategy())
```

#### Requests timeout

You can set the amount of time in seconds after that the requests will timeout:

```python
handler = APIRequest(sandbox=True, timeout=20.0)
```

### Idempotency support

To make a request with idempotency support, add `idempotency_key` parameter to your function.

For more information, see the [Idempotency](/api-reference/overview/idempotency) article.

####

**`Call - Create a payout with an idempotency key`**

```python Call - Create a payout with an idempotency key
from pprint import pprint
import mangopay

mangopay.client_id='your-client-id'
mangopay.apikey='your-api-key'

from mangopay.api import APIRequest
handler = APIRequest(sandbox=True)

from mangopay.resources import BankWirePayOut
from mangopay.utils import Money

natural_user_id = '213753890'

natural_user_wallet_id = '213754077'

payout = BankWirePayOut(
    author_id = natural_user_id,
    debited_funds = Money(amount=500, currency='EUR'),
    fees = Money(amount=0, currency='EUR'),
    debited_wallet_id = natural_user_wallet_id,
    bank_account_id = '214651521',
    tag = 'Created using Mangopay Python SDK'
)

key = 'ok7urhkW45-pTHf4456-8d'

create_payout = payout.save(idempotency_key=key)

pprint(create_payout)
```

In order to retrieve the request made using this  idempotency:

**`Call - View an API response using idempotency key`**

```python Call - View an API response using idempotency key
from pprint import pprint
import mangopay

mangopay.client_id='your-client-id'
mangopay.apikey='your-api-key'

from mangopay.api import APIRequest
handler = APIRequest(sandbox=True)

from mangopay.resources import IdempotencyResponse

key = 'ok7urhkW45-pTHf4456-8d'

idempotency_response = IdempotencyResponse.get(key)

pprint(vars(idempotency_response))
```

**`Output`**

```python Output
{'_data': {'content_length': '650',
           'content_type': 'application/json; charset=utf-8',
           'date': 'Thu, 15 Feb 2024 17:01:37 GMT',
           'resource': {'AuthorId': '213753890',
                        'BankAccountId': '214651521',
                        'BankWireRef': None,
                        'CreationDate': 1708016496,
                        'CreditedFunds': {'Amount': 500, 'Currency': 'EUR'},
                        'CreditedUserId': None,
                        'CreditedWalletId': None,
                        'DebitedFunds': {'Amount': 500, 'Currency': 'EUR'},
                        'DebitedWalletId': '213754077',
                        'EndToEndId': 'b9bf7c8bcb9c4748a9eb7c35a4499139',
                        'ExecutionDate': None,
                        'FallbackReason': None,
                        'Fees': {'Amount': 0, 'Currency': 'EUR'},
                        'Id': 'po_m_01HPPVEWB3NDWBYH0DMZJS4Z6Y',
                        'ModeApplied': 'PENDING_RESPONSE',
                        'ModeRequested': None,
                        'Nature': 'REGULAR',
                        'PaymentType': 'BANK_WIRE',
                        'ResultCode': None,
                        'ResultMessage': None,
                        'Status': 'CREATED',
                        'Tag': 'Created using Mangopay Python SDK',
                        'Type': 'PAYOUT'},
           'status': '200'},
 '_handler': <mangopay.api.APIRequest object at 0x1061fb6e0>}
```

### Pagination

> **Note**
>
> **Note - Listing elements**
>
> If you do not specify the `page` and the `per_page` parameters, only the first 10 elements will be displayed.

For endpoints that support [pagination](/api-reference/overview/pagination), you can use an object containing the `page` and `per_page` keys.

As a result, the output is paginated, and the total number of items and the total number of pages is provided.

For example, with the List all Users endpoint:

```python
# Set per_page to however many users you want displayed
users = User.all(page=1, per_page=50) # Set per_page as the minimum number of user you want to see.
# users = User.all() # Only shows the first 10 users
```

### Filtering

For endpoints that support  [filtering](/api-reference/overview/filtering-sorting), you can use an object containing the filtering parameters.

For example, with the List Transaction for a Wallet endpoint:

```python
transactions = Transaction.all(
                               user_id = legal_user.id,
		  wallet_id = user_wallet.id,
                               status='SUCCEEDED', # A specific filter
                               sort='CreationDate:asc' # A sorting parameter
) 
```

### Unit tests

The project is managed with [Poetry](https://python-poetry.org/). To set up a local development environment:

```shell
poetry install --extras dev
```

This installs the runtime dependencies as well as the `dev` extras (test runner, coverage, mocking, TLS helpers) defined in `pyproject.toml`. The resolved versions are pinned in `poetry.lock`.

To run the test suite:

```shell
poetry run coverage run -m unittest discover
poetry run coverage xml
```

## Error handling

The SDK provides the `APIError` class to wrap HTTP errors returned by the API. You can use a Python `try` block and `exception` blocks to handle API errors, for example:

```python
try:
    Wallet.get(user_wallet.id, ScaContext='USER_PRESENT')
except APIError as ex:
    print(ex.headers.get('www-authenticate'))
```