Integrating MANGOPAY for a Crowdfunding platform

I am developing a Crowdfunding platform. How to implement MANGOPAY?

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

Introduction

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

Typical crowdfunding 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 project owners

1. Create a project owner

Users can be:

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

Create a project owner with the following API call. In this example, the project owner 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 a project owner'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 project owner's bank account

Register the project owner'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 project owner KYC documents

European regulation requires you to create and submit project owner 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 Contributors

1. Create a contributor

Create a contributor by repeating the project owner's creation process (but the UserCategory should be set to "Payer").

Once again, contributors and project owner can be a natural person (natural user) or a legal entity (legal user).

2. Create a contributor's e-wallet

Create a contributor's e-wallet by repeating the project owner's e-wallet creation process.

Payment execution (pay-in)

Project owners and contributors 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}}/CardRegistrationsiban
{  
    “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 crowdfunding platform, you may manage funds between contributors and project owners.

1. Refund

MANGOPAY gives the possibility to refund contributions to failed crowdfunding campaigns, either partially or totally.

Create one or several transfer refunds to allow the contributor to reinvest into another project. Alternatively, refund the credit card payment (transfer refund then pay-in refund).

• Transfer refund : reimbursement to a user e-wallet
• Pay-in refund : reimbursement to a user card

Use the TransferId to create a transfer refund with the following API call:

Create Transfer Refund

POST |  https://api.sandbox.mangopay.com/v2.01/{{CLIENT_ID}}/transfers/{{TransferId}}/refunds
{ 
    “Tag“: “custom meta“,
    “DebitedFunds“: "{{USER-ID}}"
}

Use the PAYIN-ID to create a payIn refund using with following API call:

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 contributors and project owner

A transfer request allows you to move funds from one e-wallet to another. In the crowdfunding flow, funds will be transferred from the contributor’s e-wallet to the project owner's.

Create a transfer using the DebitedWalledID 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“
}

3. Pay-out to the project owner's bank account

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

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

The crowdfunding platform 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 crowdfunding platform. Find out more here.

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 Project owners/Contributors 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