MangoPay presents itself as "Payments for Marketplaces", but it's far from being just a payment provider, adding a wallet management and KYC (know your costumer) processes management, enabling a whole new range of service offerings.
Having analysed their offer recently, here's the breakdown of the use cases with some warnings from our design experience.
The basic concepts are:
wallet A wallet that receives money or from which a money is sent. Think of it as a bank account.
transaction A movement of money between to models.
pay-in A transaction from outside MangoPay to a wallet (eg: credit card payment, bank transfer).
pay-out A transaction out of MangoPay from a wallet (eg: to another bank account).
user
A MangoPay user. Each wallet is owned by a user. You'll get a MangoPay user as part of your enrolment process. Always use your MangoPay user for the wallets you create unless you are required to do otherwise. See Use case 4 for more details.
MangoPay can be used as a simple payment provider. On this situation you have a single wallet and any payment done to you is a pay-in and any withdraw to the account is a pay-out.
You can choose to apply the fees to either the pay-ins or pay-outs.
If you are a site that sells products from various providers you can use a wallet per provider to keep the money as if in escrow.
You can then show each user it's wallet content, ut only allow pay-outs when a service is provided or a product is shipped.
If you have a full marketplace where users trade money between themselves, you can use MangoPay to create a wallet per user so that, in practice, all the wallet related operations are not handled by you.
If you find yourself obligated to do KYC (Know Your Client) processes (eg: for regulatory reasons or fraud prevention), you only need to create a MangoPay user and then upload the required documents through the API.
Be careful that before the KYC process is successfully finished, all the money on the wallets for those users is frozen. It's not possible to do pay-outs, transactions that take money out of those wallets or even cancel transactions that put money on the wallet.
If possible, don't ever create/use a wallet with a non-KYC approved user. It will save you some grief.
If you use Python 3 the next release (as of August, 2015) will have full support for it. You can already use that code if you install from the github repository at https://github.com/MangoPay/mangopay2-python-sdk/
When designing a payment process through MangoPay, always be careful where you charge the fees, so you can make sure you get the fees back from the MangoPay-only managed fee wallet on a refund operation. You can't execute refunds on wallets where the KYC process is still ongoing for example.
The fee wallet is not visible to you (not even through the API). The fee you charge on the transactions is paid to you monthly after the MangoPay fees are deducted and will not be available or visible before that.
Thanks to Svetlana and Carrie from MangoPay for the provided assistance.
