Integrating MANGOPAY for an Marketplace Payment Extension for e-retailers project


I am developing a transactional platform, or expanding an e-commerce site into a marketplace, and am looking to managing the escrowing and disbursement of funds. How to implement MANGOPAY?

This document specifies the workflow and basic functionalities used by a Marketplace Payment Extension integration to process payments with MANGOPAY’s API. For specific needs, please contact our team.

What is a Marketplace Payment Extension integration


In the Marketplace Payment Extension setup, you use the MANGOPAY platform to process the escrowing and distribution of funds, but not the acquisition of funds.


An Marketplace Payment Extension system works in two phases :


The Acquisition / PayIn phase: managed by relevant funds acquirer

  • The acquisition of incoming payments (product sales, subscriptions...) is managed by the acquirer and the PSP (payment service provider) of your choosing (PayIns)
  • Relevant funds are transfered from the acquisition bank account to a MANGOPAY escrowing e-wallet by the end of the next business day after the reception of the funds

The Escrow / Redistribution / Pay-out phase: managed by MANGOPAY

  • The MANGOPAY platform hold funds on escrow e-wallet within platform
  • Funds that are due to vendors are transferred to their e-wallets on the platform
  • The execution of transfers from e-wallet on the platform to vendor bank accounts (pay-outs)


alt



Key Considerations


What are important legal considerations relating to an Marketplace Payment Extension integation ?


Platform operators that collect funds on behalf of third parties, such as platform vendors, are submitted to a range of legal obligations. The MANGOPAY Marketplace Payment Extension integation helps platform operators be compliant with these obligations.

Amongst these :

  • The obligation to hold funds not belonging to the platform in escrow before they are distributed to recipients
  • The compliance of your structure which will be declared as a Payment Institution Agent
  • The KYC authentication of your vendors to allow them to received funds


When do you need to send the marketplace-bound revenues to MANGOPAY?


In the Marketplace Payment Extension setup, you can keep (or build) your integration with an acquisition PSP and you must send all the marketplace-bound revenues to the MANGOPAY escrowing e-wallet at the end of the next business day after the reception of the funds on your acquisition bank account at the latest.


Which funds are concerned?


All funds held on behalf of a third party are subject to legal requirements, this is true for most marketplaces where the platform is not the merchant of record.


For example, let’s say you have 3 types of baskets:

  • 100% e-commerce, the platform is selling its own goods
  • 100 % marketplace, the platform is facilitating a vendors / buyer transaction but is not the mechant of record
  • Mixed basket (some articles are from the marketplace, some others from the e-commerce part)


All of these baskets can be acquired by the PSP of your choice and all the funds will end up on an acquisition bank account opened to your name. However, in order to stay compliant with the law, you must send to MANGOPAY all the revenues of the baskets that are 100% marketplace and the marketplace part of the mixed- basket.


Is there a connection to the acquiring PSP?


No, on MANGOPAY’s end, there is no direct connection with the acquisition PSP. The only incoming flows are:

  • The financial flow: A daily bankwire from the acquisition bank account.
  • You connection to the API : You create each vendor’s user, wallets and bank account, as well as send us the KYC documents and initiates the different transfers and pay-outs.



MANGOPAY Set-up


Your first step is to register your platform and create a sandbox account.
alt
Once these steps have been completed, you will have access to MANGOPAY’s API and dashboard.

AUTHENTICATION


Authentication is available with Basic Access Authentication. In production, we recommend using OAuth 2.0. You can find more details here.

  1. Combine the ClientId and API KEY into a string separated by a colon (e.g. "ClientId:API KEY").
  2. Encode the resulting string using Base64.
  3. Complete the Authorization header by adding "Basic" to the encoded string.


Here is an example:

ClientId API KEY String to encode in Base64 Base64 encoded string Authorization Header
Aladdin ghsiu6hjqQjj Aladdin:ghsiu6hjqQjj QWxhZGRpbjpnaHNpdTZoanFRamo= Basic QWxhZGRpbjpnaHNpdTZoanFRamo=


Technical Integration


The following are the key steps in undertaking an Marketplace Payment Extension integration

1. Creation of platform escrow e-wallet


The first step in the process is the creation of a MANGOPAY account with a designated escrow e-wallet and associated user.

In the production environment, this process is undertaken during account creation with our support teams. In the sandbox environment, once you have an active account and access to the dashboard, an escrow e-wallet and its associated user can be created manually .


As described above, it is a legal obligation that funds collected destined to be redistributed be transfered to the escrow wallet by the end of the next business day after the reception of the funds.

This bankwire will be from the relevant acquiring account to the MANGOPAY platform which will reconcile funds, and credit the escrow e-wallet. There are two main ways to transfer funds to the escrow e-wallet.


1. Bankwire Payin


In this process a bankwire is made to the account designated by MANGOPAY, with a reference.


A call must be made to the following API endpoint which will notify MANGOPAY that an incoming bankwire is to be expected.

https://docs.mangopay.com/endpoints/v2.01/payins#e280_create-a-bankwire-direct-payin

The response to this call will include the designated account and reference that must be used to create the bankwire.


Example of the response to the call, highlighting relevant information :


Destination account

"Type": "IBAN",
"OwnerName": "MANGOPAY",
"IBAN": "FR7618829754160173622224251",
"BIC": "CMBRFR2BCME"


Banking reference to add to bankwire

"WireReference": "MG4yogknpq"


A bankwire will hence need to be made to the above bank account with the associated reference. Once the funds are received by MANGOPAY, these will be reconciled and credited to the escrow e-wallet.

Every day, when we receive your daily bankwire to your escrow wallet, we can notify you via web-hooks.



2. Bankwire using an IBAN created for the escrow e-wallet


Alternatively the transfer can be made by creating a banking alias for the relevant escrow e-wallet, and transfering funds to this banking alias. Please note that if the escrow wallet is in EUR, this is the most efficient way to manage your PayIns.


The creation of a banking alias, in this case an IBAN, is carried out by the following call :
https://docs.mangopay.com/endpoints/v2.01/banking-aliases#e851_create-an-iban-banking-alias


Example of the call to create a banking alias :

{"CreditedUserId": "8494522",
"OwnerName": "Jane Doe",
"Country":"FR"
}



Example of the response to the call, showing the banking alias object :

{
    “OwnerName”: “Jane Doe”,
    “IBAN”: “LU70586610LGNP2XHH2W”,
    “BIC”: “CMBRFR2BCPA”,
    “CreditedUserId”: “5608303",
    “Country”: “LU”,
    “CreationDate”: 1599839717,
    “Active”: true,
    “Type”: “IBAN”,
    “Id”: “6626638",
    “WalletId”: “5608304"
}



Once the IBAN is created for the escrow e-wallet, the daily transfers can be made to this IBAN with no further identification. Funds will automatically be credited to the escrow e-wallet once received.


2. Vendor Creation


For the implementation of an Marketplace Payment Extension set-up, all vendors need to have an account created in MANGOPAY. 


The acount creation process has four main steps :

  1. Create a Vendor
  2. Create a Vendor's e-wallet
  3. Register a Vendor's bank account
  4. Create and submit KYC documents
    These steps will be analysed below.


Updating Vendor Information : Please note that all Vendors information should be up to date, and this should be taken into account in your configuration. Processes for updating Vendor information are included in the relevant API reference sections.


1. Create a Vendor

Sellers and buyers are indistinctly registered as users within the MANGOPAY API.


Users can be:

  • Natural: a natural person
  • Legal: a business, organisation, sole trader


Create sellers with the following API call. In this example, the seller is a natural user. Please refer to our documentation to create a legal user.


Create "Natural" user

   POST | https://api.sandbox.mangopay.com/v2.01/{{CLIENT_ID}}/users/natural
    {  
        “FirstName“: “Cyrano“
        “LastName“: “de Bergerac“, 
        “Address“: {
            “AddressLine1“:“Street 7“,
            “AddressLine2“: ““,
            “City“: “Paris“,
            “Region“:“Ile de France“,
             “PostalCode“:“75009“,
            “Country“:“FR“ 
        },
        “Birthday“: -258443002,
        “Nationality“: “FR“,
        “CountryOfResidence“: “FR“,
        “Email“: “cyrano@bergerac.com“,
        “Capacity“: “NORMAL“,
        “Tag“: “Postman create a user“
    }


Store the received user information, particularly the user-id, as it is required for all user actions.


2. Create a Vendor's e-wallet


Use the user-id to setup an e-wallet which enables the user to store e-money. The e-wallet is owned by the respective user.


Create Wallet

    POST | https://api.sandbox.mangopay.com/v2.01/{{CLIENT_ID}}/wallets
    {  
        “Owners“: [“{{USER-ID}}“], 
        “Description“: “A very cool wallet“,
        “Currency“: “EUR“,
        “Tag“: “Postman create a wallet“
    }


3. Register a Vendor's bank account


Register the seller’s bank account to payout the funds from his e-wallet(s).


Create BankAccount (IBAN)

POST | https://api.sandbox.mangopay.com/v2.01/{{CLIENT_ID}}/users/{{USER-ID}}/ bankaccounts/iban
{  
    “OwnerName“: “Cyrano de Bergerac“,
    “OwnerAddress“: {
            “AddressLine1“:“Street 7“,
            “AddressLine2“: ““,
            “City“: “Paris“,  
            “Region“:“Ile de Frog“,
            “PostalCode“:“75010“,
            “Country“:“FR“
    },  
    “IBAN“: “FR7630004000031234567890143“,
    “BIC“: “CRLYFRPP“,  
    “Tag“: “Postman create a bank account“
}


You will need to input an existing and valid BIC/IBAN in the sandbox.


4. Create and submit KYC documents


European regulation requires you to create and submit seller KYC documents.

Find more general information here. Find more technical information here.


Natural user : Legal user :
IDENTITY PROOF GENERAL MANAGER ID CARD
ARTICLES OF ASSOCIATION
SHAREHOLDER DECARATION
REGISTRATION PROOF


KYC documents uploaded to the sandbox will need to be validated on the dashboard.


The process to send a KYC document is divided into 3 parts.

  • Step 1 : Creation of a KYC Document
  • Step 2: Creation of KYC Pages within the document
  • Step 3: Submission of the KYC Document

The documents will be validated by our compliance team.

Step 1: Create a KYC document with the following API call.

Create a KYC Document

    POST | https://api.sandbox.mangopay.com/v2.01/{{CLIENT_ID}}/users/{{USER-ID}}/kyc/documents/
    {  
        “Tag“: “custom meta“, 
        “Type“: “IDENTITY_PROOF“ 
    }


Store MANGOPAY’s response on your side, particularly the KYCDocumentId.

Step 2: Create a KYC page using the KYCDocumentId and the USER-ID. Repeat this step as many times as there are pages.

Create a KYC Page

    POST | https://api.sandbox.mangopay.com/v2.01/{{CLIENT_ID}}/users/{{USER-ID}}/kyc/documents/{{KYCDocumentId}}/pages/
    { 
        “File“:“/9j/4AAQSwAARCAFAAYUDASIA ... (truncate example)“
    }


The file should be encoded in base64 and grouped into one document.


Step 3: Submit the KYC document for validation with the following API call.

Submit a KYC Document


PUT | https://api.sandbox.mangopay.com/v2.01/{{CLIENT_ID}}/users/{{USER-ID}}/kyc/documents/{{KYCDocumentId}}
{  
    “Tag“: “custom meta“,
    “Status“: “VALIDATION_ASKED“
}


After submission, the object will be waiting to be “VALIDATED”.
If you wish to be notified in case of a change of status, you can setup hook notifications.



3. Vendor Transfer and Payout :



The third phase of a Marketplace Payment Extension integration is the transfer of funds from the escrow e-wallet to the e-wallet of the vendor. This is a movement of funds internal to the MANGOPAY platform.

Then, depending on your business rules, you can trigger a transfer to the vendor's bank account external to the platform.

1. Transfer funds between escrow e-wallet and vendors' e-wallets


A transfer request allows you to move funds from one e-wallet to another. In the Marketplace Payment Extension flow, funds will be transferred from the escrow e-wallet to the vendor’s.
Create a transfer using the DebitedWalletID and CreditedWalletID.

Create Transfer

    POST |  https://api.sandbox.mangopay.com/v2.01/{{CLIENT_ID}}/transfers
    { 
        “AuthorId“: “{{USER-ID}}“,
        “DebitedFund“: {
            “Currency“: “EUR“, 
            “Amount“: 10000
        }, 
        “Fees“: { 
            “Currency“: “EUR“,
            “Amount“: 1000
        },
        “DebitedWalletId“: “{{WALLET-ID}}“,
        “CreditedWalletId“: “{{WALLET-ID}}“, 
        “Tag“: “Postman create a transfer“
    }


The marketplace can collect Fees on any transaction (pay-in, transfer, pay-out, refund). Platforms fees are automatically placed on your “Fee e-wallet”. Fees are calculated and owned by the marketplace. Find out more here.


2. Pay-out to the vendor's bank account


The last step of the Marketplace Payment Extension transaction flow is the payout.
Create a payout from the vendor's DebitedWalletID to the vendor’s bank account.

Create Payout BankWire

    POST | https://api.sandbox.mangopay.com/v2.01/{{CLIENT_ID}}/payouts/bankwire
    { 
        “AuthorId»: “{{USER-ID}}“, 
        “DebitedFunds“: {
            “Currency“: “EUR“, 
            “Amount“: 9000
        }, 
        “Fees“: {
            “Currency“: “EUR“,
            “Amount“: 0
        }, 
        “DebitedWalletId“: “{{WALLET-ID}}“,
        “BankAccountId“: “{{BANKACCOUNT-ID}}“,
        “BankWireRef“: “Postman“ 
    }


Live chat
No agent is free at the moment please send us a request through our contact form