Marketplace: Quickstart

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.

2

M A R K E T P L A C E

U S E R

S E L L E R

B U Y E R

E-WA L L E T

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

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

Online platform where products and services are exchanged by third parties. Transactions are processed by the platform. (You)

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

User selling a product or a service.

User buying a product or a service.

Digital wallet on which electronic money is stored.

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

E-wallet owned by the marketplace to collect fees.

Reimbursement to a user.

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.

Glossary

3

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

Pay-In Transfer, Fees payment

Payout to end beneficiary bank

account

I NT R O D U CT I O N

Typical marketplace workflow

4

Authentification

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

5

123456789101112131415161718

N.B. Sellers and buyers are indistinctly registered as users within MANGOPAY’s 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.

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

1 . C R E AT E A S E L L E R

I NT R O D U CT I O N

Register sellers

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

6

1234567891011121314

2. C R E AT E A S E L L 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 S E L L E R’S B A N K A C C O U NT

Register the seller’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“}

7

1234

4. C R E AT E A N D S U B M IT S E L L E R KYC D O C U M E NT S

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

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

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

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

8

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 Buyers

1. C R E AT E A B U Y E R

Create a buyer by repeating the seller’s creation process. Once again, buyers and sellers can be a natural person (natural user) or a legal entity (legal user).

2. C R E AT E A B U Y E R’S E -WA L L E T

Create a buyer’s e-wallet by repeating the seller’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}}

9

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

MANGOPAY’s response will include:

PreregistrationData AccessKey CardRegistrationURL

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

Create a 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

10

1234567891011121314

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.

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

11

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

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 DebitedWalledID and CreditedWalletID.

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

12

3 . PAYO U T TO T H E S E L L E R’S B A N K A C C O U NT

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.

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

Create Payout BankWire

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

1234567891011121314

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

13

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

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

Postman

14

1. Open the «Environment options» panel by clicking on the gear icon then click Manage Environments. Click Add to create a new environment.

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.

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