Integrating MANGOPAY for a Marketplace

I am developing a Marketplace. How to implement MANGOPAY?

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

Video tutorial

Check out our tutorial on how to integrate a marketplace with MANGOPAY, we'll guide through our product and its integration.

Introduction

MANGOPAY is a payment solution which enables marketplaces to easily process third-party payments. The typical workflow is described below.

Typical marketplace workflow

MANGOPAY Set-up

Your first step is to register your platform and create a sandbox account.

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:

Integration

Register sellers

1. Create a seller

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 (Owner)

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“
    "TermsAndConditionsAccepted": true,
    "UserCategory": "Owner"
}

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

2. Create a seller'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 seller'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“: “BNPAFRPP“,  
    “Tag“: “Postman create a bank account“
}

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.

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)“
}

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.

Register Buyers

1. Create a buyer

Create a buyer by repeating the seller creation process (but the UserCategory should be set to "Payer").

Once again, buyers and sellers can be a natural person (natural user) or a legal entity (legal user).

2. Create a buyer's e-wallet

Create a buyer’s e-wallet by repeating the seller’s e-wallet creation process.

Payment execution (pay-in)

Sellers and buyers have now been registered within our API. The next step is to send funds to a user’s e-wallet.

1. Pay-In by registered card

We recommend using our direct pay-in endpoint for a seamless integration and one-click payments. This is a two-step process:

• Step 1: Register the card
• Step 2: Process payments

Step 1: Create a card registration object to store reusable and non-sensitive card details (tokens) within MANGOPAY's environment. This object is linked to the user with the USER-ID.

Create card registration

POST | https://api.sandbox.mangopay.com/v2.01/{{CLIENT_ID}}/CardRegistrations
{  
    “UserId“: “{{USER-ID}}“, 
    “Currency“: “EUR“,  
    “CardType»: “CB_VISA_MASTERCARD“
}

MANGOPAY’s response will include:

1. PreregistrationData
2. AccessKey
3. CardRegistrationURL

Use these 3 parameters in the next step to post the card info.

Once a token is created, complete the card registration (CardRegID) by sending the RegistrationData to MANGOPAY.

Update card registration 

PUT | https://api.sandbox.mangopay.com/v2.01/{{CLIENT_ID}}/cardregistrations/{{CardReg_Id}}
{
    “RegistrationData“ : “{{CardReg_RegistrationData}}“
}

The registered card may be used multiple times (one-click payment).

Step 2: Process payments with the registered card via the direct pay-in. The API call contains the cardID, currency, amount (in cents), and any additional information you may want to send.

Create a Payin Card/Direct

POST | https://api.sandbox.mangopay.com/v2.01/{{CLIENT_ID}}/payins/card/direct
{ 
    “AuthorId“: “{{USER-ID}}“,
    “DebitedFunds“: {
            “Currency“: “EUR“,
            “Amount“: 100
            }, 
    “Fees“: {  
            “Currency“: “EUR“,
            “Amount“: 0
            }, 
    “CreditedWalletId“: “{{WALLET-ID}}“,  
    “SecureModeReturnURL“: “http://test.com/“,
    “SecureMode“ :“DEFAULT“,  
    “CardID“: “{{CARD-ID}}“,  
    “Tag“: “Postman create a payin card direct“,
    “StatementDescriptor“: “Payin“
}

Funds Management

As a marketplace, you may manage funds between buyers and sellers.

1. Refund

MANGOPAY gives the possibility to refund payments, either partially or totally.

Create a refund using the PAYIN-ID.

Create PayIn Refund

POST |  https://api.sandbox.mangopay.com/v2.01/{{CLIENT_ID}}/payins/{{PAYIN-ID}}/refunds
{ 
    “AuthorId“: “{{USER-ID}}“,
    “DebitedFunds“: {
        “Currency“: “EUR“, 
        “Amount“: 100
    }, 
    “Fees“: {  
        “Currency“: “EUR“,
        “Amount“: 0
    }
}

2. Transfer funds between buyers' and sellers'

A transfer request allows you to move funds from one e-wallet to another. In the marketplace flow, funds will be transferred from the buyer’s e-wallet to the seller’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.

3. Pay-out to the seller's bank account

The last step of the marketplace transaction flow is the payout.

Create a payout from the seller’s DebitedWalletID to the seller’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“ 
}

Testing MANGOPAY API with Postman

Test the MANGOPAY API calls in seconds.

What is Postman?

Postman is an app for easy RESTful API exploration. It allows you to test API calls without writing the code or installing the SDKs.

Step 1: Get the Postman collection

1. If you have not already, visit https://www.getpostman.com/ and install the preferred version for your system.
2. Click the Run in Postman button below to open Postman and import MANGOPAY’s API Postman collection.

Step 2: Create your Postman environment

Our collection makes use of Postman's environment variables to easily manage your API credentials. Start by creating a sandbox environment.

1. Open the "Environment options" panel by clicking on the gear icon, then click Manage Environments. To create a new environment, click Add.
2. Name your environment something that indicates it is using sandbox credentials, for example "MANGOPAY Sandbox".
3. Add a variable/value pair with "CLIENT_ID" as the variable and your client ID as the value.
4. Add a variable/value pair with "API_KEY" as the variable and your api key as the value.
5. Add a variable/value pair with "SERVEUR_URL" as the variable and "https://api.sandbox.mangopay.com" as the value.
6. Add a variable/value pair with "VERSION" as the variable and "V2.01" as the value.
7. When you are finished adding variable/value pairs, click Add. Now, any test calls you make using this environment will automatically fill in the CLIENT_ID , SERVEUR_URL, VERSION, api_key with your sandbox credentials.

Step 3: Send a call to create your first user

Send a call to create your first user using your sandbox environment.

1. Click the dropdown menu next to the gear icon and choose your sandbox environment from the menu.
2. Open the collection then click on create “natural” user under the Register sellers/buyers folder
3. Click “Send”. Postman will use your Basic Auth credentials to make the call.

The MANGOPAY API collection also includes folders for all MANGOPAY v2.01 API endpoints with pre-configured calls. Please find it here

Glossary