Integration optionsServer-side SDKs

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

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

Prerequisites

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

  • A ClientId and an API key – if you don’t have these, contact Sales to get access to the Mangopay Dashboard
  • Python 3.13 (recommended) down to 3.9 (not recommended) installed:
    • pip package manager
    • requests library
    • blinker library

Getting started

1. Install the SDK

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

1pip3 install mangopay4-python-sdk

2. Initialize and configure the SDK

1import mangopay
2
3mangopay.client_id='your-client-id'
4mangopay.apikey='your-api-key'
5
6from mangopay.api import APIRequest
7handler = APIRequest(sandbox=True)

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

KeyTypeDefault valueDescription
client_idstringNoneYour Mangopay ClientId – can be found in the Dashboard.
apiKeystringNoneYour Mangopay API key – can be found in the Dashboard.
api_urlstringhttps://api.mangopay.com/The API production URL.
api_sandbox_urlstringhttps://api.sandbox.mangopay.com/v2.01/The API sandbox URL.
sandboxbooleanNoneTo set it to Sandbox, set it as True. To set it to Production, set it as False.
timeoutfloat30.0Request timeout in seconds.
storage_strategystringStaticStorageStrategy()Mechanism of how the caching works. There are 2 options: StaticStorageStrategy() for in-memory cache and FileStorageStrategy() for file-based cache.
proxiesstringNoneDictionary mapping protocol or protocol and host name to the URL of the proxy.

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:

1http_proxy  = "http://10.10.1.10:3128"
2https_proxy = "https://10.10.1.11:1080"
3ftp_proxy   = "ftp://10.10.1.10:3128"
4
5proxyDict = {
6          "http": http_proxy,
7          "https": https_proxy,
8          "ftp": ftp_proxy
9            }
10
11 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.
1handler = APIRequest(sandbox=True, storage_strategy=FileStorageStrategy())

Requests timeout

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

1handler = 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 article.

Call - Create a payout with an idempotency key
1from pprint import pprint
2import mangopay
3
4mangopay.client_id='your-client-id'
5mangopay.apikey='your-api-key'
6
7from mangopay.api import APIRequest
8handler = APIRequest(sandbox=True)
9
10from mangopay.resources import BankWirePayOut
11from mangopay.utils import Money
12
13natural_user_id = '213753890'
14
15natural_user_wallet_id = '213754077'
16
17payout = BankWirePayOut(
18    author_id = natural_user_id,
19    debited_funds = Money(amount=500, currency='EUR'),
20    fees = Money(amount=0, currency='EUR'),
21    debited_wallet_id = natural_user_wallet_id,
22    bank_account_id = '214651521',
23    tag = 'Created using Mangopay Python SDK'
24)
25
26key = 'ok7urhkW45-pTHf4456-8d'
27
28create_payout = payout.save(idempotency_key=key)
29
30pprint(create_payout)

In order to retrieve the request made using this  idempotency:

Call - View an API response using idempotency key
1from pprint import pprint
2import mangopay
3
4mangopay.client_id='your-client-id'
5mangopay.apikey='your-api-key'
6
7from mangopay.api import APIRequest
8handler = APIRequest(sandbox=True)
9
10from mangopay.resources import IdempotencyResponse
11
12key = 'ok7urhkW45-pTHf4456-8d'
13
14idempotency_response = IdempotencyResponse.get(key)
15
16pprint(vars(idempotency_response))
Output
1{'_data': {'content_length': '650',
2           'content_type': 'application/json; charset=utf-8',
3           'date': 'Thu, 15 Feb 2024 17:01:37 GMT',
4           'resource': {'AuthorId': '213753890',
5                        'BankAccountId': '214651521',
6                        'BankWireRef': None,
7                        'CreationDate': 1708016496,
8                        'CreditedFunds': {'Amount': 500, 'Currency': 'EUR'},
9                        'CreditedUserId': None,
10                        'CreditedWalletId': None,
11                        'DebitedFunds': {'Amount': 500, 'Currency': 'EUR'},
12                        'DebitedWalletId': '213754077',
13                        'EndToEndId': 'b9bf7c8bcb9c4748a9eb7c35a4499139',
14                        'ExecutionDate': None,
15                        'FallbackReason': None,
16                        'Fees': {'Amount': 0, 'Currency': 'EUR'},
17                        'Id': 'po_m_01HPPVEWB3NDWBYH0DMZJS4Z6Y',
18                        'ModeApplied': 'PENDING_RESPONSE',
19                        'ModeRequested': None,
20                        'Nature': 'REGULAR',
21                        'PaymentType': 'BANK_WIRE',
22                        'ResultCode': None,
23                        'ResultMessage': None,
24                        'Status': 'CREATED',
25                        'Tag': 'Created using Mangopay Python SDK',
26                        'Type': 'PAYOUT'},
27           'status': '200'},
28 '_handler': <mangopay.api.APIRequest object at 0x1061fb6e0>}

Pagination

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, 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:

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

Filtering

For endpoints that support filtering, you can use an object containing the filtering parameters.

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

1transactions = Transaction.all(
2                               user_id = legal_user.id,
3		  wallet_id = user_wallet.id,
4                               status='SUCCEEDED', # A specific filter
5                               sort='CreationDate:asc' # A sorting parameter
6)

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:

1try:
2    Wallet.get(user_wallet.id, ScaContext='USER_PRESENT')
3except APIError as ex:
4    print(ex.headers.get('www-authenticate'))