> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mangopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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): <a href="https://pypi.org/project/mangopay4-python-sdk/" target="_blank">mangopay4-python-sdk</a>

<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).
</Warning>

<Info>
  **Prerequisites**

  To run the Mangopay Python SDK, you’ll need:

  * A `ClientId` and an API key – if you don't have these, <a href="https://mangopay.com/contact" target="_blank">contact Sales</a> to get access to the <a href="https://hub.mangopay.com/" target="_blank">Mangopay Dashboard</a>
  * Python 3.13 (recommended) down to 3.9 (not recommended) installed:
    * pip package manager
    * requests library
    * blinker library
</Info>

## Getting started

#### 1. Install the SDK

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

```python theme={null}
pip3 install mangopay4-python-sdk
```

#### 2. Initialize and configure the SDK

```python theme={null}
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 <a href="https://hub.mangopay.com/" target="_blank">Dashboard</a>.</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 <a href="https://hub.mangopay.com/" target="_blank">Dashboard</a>.</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 theme={null}
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 theme={null}
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 theme={null}
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 <a href="/api-reference/overview/idempotency">Idempotency</a> article.

####

```python Call - Create a payout with an idempotency key theme={null}
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:

```python Call - View an API response using idempotency key theme={null}
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))
```

```python Output theme={null}
{'_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.
</Note>

For endpoints that support <a href="/api-reference/overview/pagination">pagination</a>, 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 theme={null}
# 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  <a href="/api-reference/overview/filtering-sorting">filtering</a>, you can use an object containing the filtering parameters.

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

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

## 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 theme={null}
try:
    Wallet.get(user_wallet.id, ScaContext='USER_PRESENT')
except APIError as ex:
    print(ex.headers.get('www-authenticate'))
```