Crowdfunding: Quickstart

This document specifies the workflow and basic functionalities used by crowdfunding platforms to process payments with MANGOPAY’s API. For

specific needs, please contact our team.

2

C R O W D F U N D I N G P L AT F O R M

U S E R

P R O J E CT O W N E R

C O NT R I B U TO R

E-WA L L E T

C A M PA I G N

PAY- I N

T R A N S F E R

PAYO U T

F E E

F E E E -WA L L E T

R E F U N D

Online platform where projects are funded by contributors. Transactions are processed by the platform. (You)

Natural person (natural user) or a legal person (legal user).

User who owns a project.

User who contributes to a project.

Digital wallet on which electronic money is stored.

Period during which a project can be funded.

Deposit of funds by a user on an e-wallet.

Movement of funds from one e-wallet to another.

Withdrawal of funds from an e-wallet to a end-user’s bank account.

Commission calculated and collected by the crowdfunding platform.

E-wallet owned by the crowdfunding platform to collect fees.

Reimbursement to a user.

Glossary

3

K YC(Know your customer)

C L I E NT I D

U S E R I D

D A S H B O A R D

Verification process of your users’ identity, part of European anti-money laundering regulation.

ID of the platform operator in MANGOPAY’s environment.

ID of the end-user in MANGOPAY’s environment.

Personalised interface providing the platform with full access to their activity in MANGOPAY’s API.

4

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

Pay-In Fund management Payout to end beneficiary bank

I NT R O D U CT I O N

Typical crowdfunding workflow

5

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:

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.

MANGOPAY Setup

6

123456789101112131415161718

N.B. Project owners and contributors are indistinctly registered as users within MANGOPAY’s API.

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.

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

1. C R E AT E A P R O J E CT O W N E R

I NT E G R AT I O N

Register project owner

Create “Natural“ user

POST https://api.sandbox.mangopay.com/v2.01/{{CLIENT_ID}}/users/natural

{ “FirstName“: “Cyrano»“ “LastName“: “de Bergerac“, “Address“: { “AddressLine1“:“77 Lewis Sreet“, “AddressLine2“: “MGP Land“, “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“}

7

1234567891011121314

2. C R E AT E A P R O J E CT O W N E R’S E -WA L L E T

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.

3. R E G I S T E R A P R O J E CT O W N E R’S B A N K A C C O U NT

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

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

123456

Create Wallet

Create BankAccount (IBAN)

POST https://api.sandbox.mangopay.com/v2.01/{{CLIENT_ID}}/wallets

POST https://api.sandbox.mangopay.com/v2.01/{{CLIENT_ID}}/users/{{USER-ID}}/ bankaccounts/iban

{ “Owners“: [“{{USER-ID}}“], “Description“: “A very cool wallet“, “Currency“: “EUR“, “Tag“: “Postman create a wallet“}

{ “OwnerName“: “Cyrano de Bergerac“, “OwnerAddress“: { “AddressLine1“:“77 Lewis road“, “AddressLine2“: “Lewis loop“, “City“: “Paris“, “Region“:“Ile de Frog“, “PostalCode“:“75010“, “Country“:“FR“ }, “IBAN“: “FR7618829754160173622224154“, “BIC“: “CMBRFR2BCME“, “Tag“: “Postman create a bank account“}

8

1234

4. C R E AT E A N D S U B M IT P R O J E CT O W N E R KYC D O C U M E NT S

European regulation requires you to create and submit project owner KYC documents.Find more general information here. Find more technical information here.

Project owners will have to upload the following documents to payout:

N.B. 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.

• Creation of a KYC Document in MANGOPAY’s environment.

• Creation of a KYC Page in the recently created document.

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

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

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

Natural user Legal user

IDENTITY PROOF GENERAL MANAGER ID CARDARTICLES OF ASSOCIATION SHAREHOLDER DECLARATIONREGISTRATION PROOF

9

123

12

3

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

N.B. 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.

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. C R E AT E A C O NT R I B U TO R

Create a contributor by repeating the project owner’s creation process. Once again, contributors and projects owner can be a natural person (natural user) or a legal entity (legal user).

2. C R E AT E A C O NT R I B U TO R’S E -WA L L E T

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

Create a KYC Page

Submit a KYC Document

{“File“: “/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAUDBAQEAwUEBAQFBQUGBwwIBwcHBw8LCwkMEQ8SEhEP ERETFhwXExQaFRERGCEYGh0dHx8fExciJCIeJBweHx7/2wBDAQUFBQcGBw4ICA4eFBEUHh4eHh4e Hh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh7/wAARCAFAAYUDASIA ... (truncate example)“}

{“Tag“: “custom meta“,“Status“: “VALIDATION_ASKED“}

POST https://api.sandbox.mangopay.com/v2.01/{{CLIENT_ID}}/users/{{USER-ID}}/kyc/documents/ {{KYCDocumentId}}/pages/

PUT https://api.sandbox.mangopay.com/v2.01/{{CLIENT_ID}}/users/{{USER-ID}}/kyc/documents/ {{KYCDocumentId}}

10

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- I N BY R E G I S T E R E D C A R D

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

Step 1 : Register the cardStep 2 : Process payments Step 1 : Create a 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.

In MANGOPAY’s response, you will receive:

PreregistrationData AccessKey CardRegistrationURL

These 3 parameters will be used in the next step to post the card info.

Create card registration

POST https://api.sandbox.mangopay.com/v2.01/{{CLIENT_ID}}/CardRegistrationsiban

12345

{ “UserId“: “{{USER-ID}}“, “Currency“: “EUR“, “CardType»: “CB_VISA_MASTERCARD“}

Post card info

POST https://homologation-webpayment.payline.com/webpayment/getToken

KEY

data

accessKeyRef

returnURL

cardNumber

cardExpirationDate

cardCvx

VALUE

{{PreregistrationData}}

{{AccessKey}}

4706750000000025

1019

833

11

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

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.

N.B : User contributors pay into their respective e-wallets but funds should NOT be escrowed there. You should directly transfer the funds to the project’s e-wallet.

1234567891011121314

1234

{

“RegistrationData“ : “{{CardReg_RegistrationData}}“}

Update card registration

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

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“: “https://www.test.com“, “SecureMode“ :“DEFAULT“, “CardID“: “{{CARD-ID}}“, “Tag“: “Postman create a payin card direct“, “StatementDescriptor“: “bob“}

12

Funds ManagementAs 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:

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

1234567891011

{ “AuthorId“: “{{USER-ID}}“, “DebitedFunds“: { “Currency“: “EUR“, “Amount“: 100 }, “Fees“: { “Currency“: “EUR“, “Amount“: 0 }}

Create a Transfer Refund

POST https://api.sandbox.mangopay.com/v2.01/{{CLIENT_ID}}/transfers/{{TransferId}}/refunds

12345

{ “Tag“: “{{custom meta}}“, “AuthorId“: “{{USER-ID}}“}

13

3 . PAY-O U T TO T H E P R O J E CT O W N E R’S B A N K A C C O U NT

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.

2. TRANSFER FUNDS BE TWEEN CONTRIBUTORS AND THE 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 Payout BankWire

POST https://api.sandbox.mangopay.com/v2.01/{{CLIENT_ID}}/payouts/bankwire

1234567891011121314

{ “AuthorId»: “{{USER-ID}}“, “DebitedFunds“: { “Currency“: “EUR“, “Amount“: 1500 }, “Fees“: { “Currency“: “EUR“, “Amount“: 0 }, “DebitedWalletId“: “{{WALLET-ID}}“, “BankAccountId“: “{{BANKACCOUNT-ID}}“, “BankWireRef“: “Postman“}

Create Transfer

POST https://api.sandbox.mangopay.com/v2.01/{{CLIENT_ID}}/transfers

1234567891011121314

{ “AuthorId“: “{{USER-ID}}“, “DebitedFund“: { “Currency“: “EUR“, “Amount“: 10000 }, “Fees“: { “Currency“: “EUR“, “Amount“: 0 }, “DebitedWalletId“: “{{WALLET-ID}}“, “CreditedWalletId“: “{{WALLET-ID}}“, “Tag“: “Postman create a transfer“}

N.B. 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.

14

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

S T E P 1 : G E T T H E P O S T M A N C O L L E CT I O N

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.

S T E P 2 : C R E AT E YO U R P O S T M A N E N V I R O N M E NT

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.

T E S T I N G M A N G O PAY’S A P I W IT H

Postman

15

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.013“ 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.

S T E P 3 : S E N D A C A L L TO C R E AT E YO U R F I R S T U S E R

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 quickstart collection then click on create “natural” user under the Register Project owner/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.