• Why

• Which context

• Interfaces

• Configurations

• Workflows

  • KYC/KYB management and validation process

• Special rules

  • Which PSP should I choose?

    • Geographical choice

    • Functional choice

    • Expertise & Price Choice

    • Overview of PSPs available on Second and features

  • KYC/KYB process

Why

Marketplaces & traditional e-commerces differ in that in marketplaces, three parties are involved (vendor, buyer and platform operator) whereas in traditional e-commerces, two parties are involved (vendor/operator and buyer).

A payment service provider (PSP) or payment gateway hence becomes essential to bring payment solutions on marketplaces.

PSPs are used for:

• accepting electronic payments thourgh different payment methods

  • credit card

  • bank-based payments

    • direct debit

    • traditional wire transfer

    • real-time wire transfer

PSPs workflows are adapted to match marketplace-specific requirements:

• Secure recollection of funds & escrowing (secure delayed payment)

• Fraud management, KYC (Know Your Customers) & KYB (Know Your Business Procedures)

• Askers & offerors security and trust

Various PSPs can be used to perform transactions on marketplaces.

Which context

For all services.

Interfaces

Learn more on interfaces here:

• Stripe (PSP) - Business rules

• Mangopay (PSP) - Business rules

Configurations

Learn more on how to configure the bundle here:

• SBO > Other > Feature > Stripe

• SBO > Other > Feature > Payment Methods

Workflows

Workflows are identical throughout the 3 PSPs Second offers:

KYC/KYB management and validation process

The primary objective of the marketplace is to enhance user registration and increase the number of bookings. To streamline the booking process on the platform, Know Your Customer (KYC) verification is required only when a vendor wishes to accept a booking.

Customers can navigate the platform, search for listings, and make booking requests without undergoing KYC verification. This allows for an uninterrupted and user-friendly experience, encouraging more interaction with the marketplace.

Vendors, on the other hand, can easily create listings without initial verification. However, when a vendor decides to accept a booking request, they must complete the KYC validation process. The specifics of the KYC validation are determined by the payment service provider configured within the platform.

This approach ensures that while customers enjoy a seamless experience, necessary security and verification standards are upheld for vendors. By implementing this method, the marketplace maintains a balance between user convenience and security requirements.

Special rules

Which PSP should I choose?

There are different criteria to take into account when choosing which PSP to integrate. We can classify them into 3 main categories:

• Geographical

• Functional

• Expertise & Price.

Geographical choice

Geographically, it is key to check if the PSP can:

• Operate in the countries where the marketplace will be hosting its activities

• Comply with the laws of the concerned countries.

For example, is my customer's company on the list of countries allowed by the PSP?

Does the PSP accept bidders from “country”?

Functional choice

Functionally, one should verify if the features offered by the PSP covers:

• The types of payment workflow (escrow, direct payment etc..)

• The different payment methods (credit card, transfer, etc.)

• KYC/KYB management

• The functionalities offered by the PSP dashboard

Expertise & Price choice

The last criteria is the expertise & price of the PSP. While price is a fairly straight forward criteria, it usually scales with the following services:

• The number of customers

• The type of customers

• The support provided

Overview of PSPs available on Second and features

KYC/KYB process

KYC, or Know Your Customer, and KYB, or Know Your Business, are processes required to verify the identity of customers as per legal requirements and regulations. These processes are carried out by authorized companies, which usually are the PSPs. Marketplaces are however under the obligation of respecting this process before allowing users to receive payments.

These processes applies to:

• All users who require the PSP’s services

• Individuals or legal entities

• Both askers and offerers

To benefit from the services provided by a PSP, users need to provide a certain amount of information.

Offerors provide :

• Identity information about the individual opening the account

• Company identity information if the account is registered as a legal entity

The KYC / KYB being a list of information concerning platform users, the required information may differ according to certain identity criteria such as:

• Business type (individual or enterprise)

• Business structure (private company, association etc...)

• User country

The PSP-specific KYB/KYC processes are described the related PSP documentation.

• Why

• For which services

• Interfaces

• Configurations

• Workflows

  • Workflows of Stripe’s identity verification of users

  • User registration and profile identity edition

  • User profile bank account edition

  • Listing deposit

  • Booking check

  • Booking confirmation

  • Booking cancellation

  • Booking acceptation

  • Booking validation

  • Booking bank wire check

  • Escrow management

• Special rules

  • Stripe fees for admins

  • Stripe KYC/KYB process

  • Escrow management

Why

Stripe is a payment service provider. Its services allow users to pay on the platform and administrators to handle payouts.

Learn more about the PSP available in Second: Payment Service Provider Feature (PSP) - Business rules

Stripe is the default PSP enabled.

For which services

For all services

Interfaces

Please, find all interface documentation related to the Stripe bundle, here:

SBO:

• Payments management - Update Payout

Front:

• Booking request (Time-Based rendering type) - The Payment Page

Configurations

SBO > Other > Feature > Stripe

Workflows

Workflows of Stripe’s identity verification of users

Workflow of Stripe’s identity verification for users registered in France

Workflow of Stripe’s identity verification for users registered in the US

User registration and profile identity edition

User profile bank account edition

Listing deposit

Booking check

Booking confirmation

Booking cancellation

Booking acceptation

Booking validation

Booking bank wire check

Escrow management

Stripe Payment Methods

Direct Debit Payment

The direct debit payment option is available only when Stripe is selected as the payment service provider and when the booking start date is at least 14 days after the current date. Administrators need to manage this payment method through the SBO by modifying the "Payment Methods" Configuration.

For direct debit payments, the account holder's name, email address, and either the IBAN or bank account number are required.

When a customer selects Direct Debit as the payment method and click o "Pay", the booking request status is set to "Pending" until it is accepted by the vendor. Once the vendor accepts the request, the booking status temporarily changes to "Waiting for Payment". This brief period allows Stripe to process the payment transaction and send a confirmation to the platform. Upon receiving the confirmation, the status updates to "Paid". At this point, a mandate is issued, notifying the customer of the direct debit on their account.

If there are no issues with the payment transaction, the booking status will be updated to "Paid."

Payment Error (Direct Debit)

If there is an error in the payment during a direct debit transaction, the booking status will be updated to "Status: Payment declined" when the vendor attempts to accept the booking.

In this scenario, the customer is required to create a new booking request.

Credit card payment

If the administrator activates credit card payments for Stripe on SCND, users will have the ability to complete bookings using a valid credit card. The credit card payment option will be presented after the checkout overview.

The user then enters his payment information (figure 11.2):

• credit card number

• expiration date

• CVC

Once the credit card payment is successfully processed, the system redirects the user to the booking page, where the booking status is set to "Pending." Upon vendor approval, the status automatically updates to "Paid." If a payment error occurs, the booking request is not completed, and the customer must resubmit the booking request and payment.

Special rules

Stripe fees for admins

These fees are applied to all the payment transactions made on the platform.

• For european cards: 1,4 % + 0,25 €

• For non-european cards: 2,9 % + 0,25 €

Stripe KYC/KYB process

The validation process is partially managed by Stripe.

Once the user has filled in identity information: Identity , by clicking the button save, he will be redirected to a dedicated Stripe page that automatically manages the list of information that will be requested from the user.

The user will have:

• To verify his ID by taking a picture (figure 1)

• Certify his address (figure 2)

• Summary of his data (figure 3), once the user clicks the button “done”, he will be back on the platform.

Escrow management

Stripe offers a workflow dedicated to the marketplace.

However, this workflow does not work for all countries that Stripe offers.

Second has integrated a workflow that allows the user to achieve the same result while working on all the countries that Stripe allows.

This workflow will revolve around the offeror's wallet, see: https://second-documentation.atlassian.net/wiki/spaces/SCNDFD/pages/6943049240#Escrow-management

• During a pay-in, Stripe will transfer the total amount of the booking minus the fees to the wallet of the offeror.

• Stripe collects these fees at that time and Stripe's fees just like other PSPs are based on the total amount of a pay-in.

• This money will remain in escrow until the payout is made by the super administrator from the SBO.

• Stripe will send the money to the offeror’s bank account and notify the platform in case of success or failure.

• At the same time, the platform's fees will be available on the platform’s wallet.

Just like other PSPs, when a cancellation is made with a refund, it is automatic since the payment is by card.

• Why / Which context

• Steps to reproduce

  • 1. Login into your Stripe dashboard

  • 2. Make a booking on your platform

  • 3. Create a new simulation on the Stripe dashboard

  • 4. Accept the subscription request and enable payments

  • 5. Test the active period

  • 6. Test the next subscription period

• Commands

  • Reminder

• Status

  • Subscription period

    • Workflow

    • Status

  • Subscription status

Why / Which context

The subscription feature allows automatic recurring payment for one booking.

Payments are automatic in production, but in environment tests, it will take a few days to complete a workflow. It is the reason why we implemented a Stripe tool to handle delays and fake dates.

Steps to reproduce

During this process, you will switch between the Stripe dashboard and your platform.

1. Login into your Stripe dashboard

Log in to your Stripe account: https://dashboard.stripe.com

Once you are connected, switch to Test mode thanks to the button (figure 1) at the top right corner of your Stripe dashboard.

2. Make a booking on your platform

Go on your platform and log in as an asker, then create a booking request.

Learn more about the process of booking requests here: Booking confirmation pages (Subscription)

Once you are on the checkout booking page, please take the ID checkout number in the URL (figure 2).

3. Create a new simulation on the Stripe dashboard

Click on “test clocks” (figure 3), and you will be redirected to the subscription test environment of the Stripe dashboard.

Click on the button “New simulation” (figure 4), and a modal will appear (figure 5).

You will have to fill the field (figure 5) “Nom de la simulation” as follow: Subscription#IDcheckout and click on the button “Créer”

Go back to the Checkout page and proceed to the payment. Once the payment is done, you should see “Client” (figure 6) on the new subscription page created on the Stripe dashboard

4. Accept the subscription request and enable payments

Once the payment has been made by the asker, the offeror can accept the subscription.

Then on the Stripe dashboard, you should proceed to the payin.

By default, the Payin is done x days before the start date of the subscription period. This is set with the following configuration: subscription_automatic.

To test it quicker you can force the payin. In the Stripe dashboard, go on the subscription that matches your booking and click on Subscription (figure 7).

In the Invoice section, click on the label “brouillon” or draft, (figure 8 ) it will send you to the invoices menu of the Stripe dashboard.

Then click on the “charging the customer” (figure 9) button

The status of the subscription period will be Paid.

5. Test the active period

Go in the SBO and fill the arguments in the command subscription.status

Arguments: --test --id=1868442188 --clock=P1Y1MT1H1M

The same process to enable the payout: the command cocorico:subscription:validate.

Arguments: --test --delay-weekly=-P1M

6. Test the next subscription period

To finish the complete workflow you should test the next period.

Once the period T is active it will create the next subscription period is pending.

You can go on the Stripe dashboard and charge the customer for the new next period. For the subscription, you want to test you will see a new draft payment. Same as before, you can click on this label and charge the customer.

The payment will have the paid status. Then you can reproduce point 5. test the active period.

The expected behavior is:

• The current subscription period is done

• The next subscription period is active

• The payout is available

7. Test a payment failure

In some cases, a subscription payment may not be approved. If this happens, it's important to update the payment method to a valid one. To test this scenario, we need to access the draft invoice in Stripe Dashboard (Test mode > Billing) before the next billing cycle begins.

Click and open the invoice and attempt a new payment method by pressing the button "Charge Customer". Add a "Decline after attaching Stripe card" (4000000000000341). To complete the process, we need to check the following message displayed in Stripe:

Return to the asker account and refresh the page. A button "Update card details" should be displayed.

Commands

• second:stripe:webhook

  • This command allows you to configure the Stripe webhook dashboard. Before a day of test please run this command

  • No arguments

• second:subscription:expire

  • Simulate a subscription request that has not been accepted or declined

  • No arguments

• second:subscription:status

  • Simulate the day of the platform to test payin and status

  • Args: --test --id=1868442188 --clock=P1M

• second:subscription:validate

  • Simulate the day of the platform to test payout and status and enable another subscription period

  • Args: --test --delay-weekly=-P1M

Reminder

Status

Subscription period

Workflow

The subscription period workflow for a Accepted susbcription request is:

Pending > Accepted > Paid > Active > Done

Status

• Pending: the next period, it is waiting for subscription acceptance or for payment

• Canceled: the next period was canceled by the asker

• Declined: the subscription request was canceled by the offerer

• PaymentError: the next period has a payment issue

• Paid: the next period was paid successfully but the period didn’t start yet (payment attempt delay)

• Active: the next period becomes active when the period starts (new cron command required)

• Done: the current period becomes done when the period ends (new cron command required)

• Canceled: the current period is paid or pending, and the active period (if any) becomes Done when the period ends.

Subscription status

• Pending: the subscription request is waiting for the offerer acceptation

• Canceled: the subscription request was canceled by the asker

• Declined: the subscription request was canceled by the offerer

• Accepted: the subscription request was accepted by the offerer

• PaymentError: the next subscription period has a payment issue

• Paid: the first period was paid successfully but the period didn’t start yet (payment attempt delay)

• Active: the next period starts and it’s paid (new cron command required)

• Canceled: the next period was canceled and ( there is no current paid period or the current paid period ends ) (new cron command required)

• Why

• For which services

• Interfaces

• Configurations

• Workflows

  • Mangopay booking workflow

  • Mangopay card registration and preauthorization

  • Mangopay preauthorized pay-in activity

  • Mangopay pay-in refund activity

  • Mangopay transfer activity

  • Escrow management

• Special rules

  • Mangopay fees

  • KYC/KYB process

  • Escrow management

Why

Mangopay is a payment service provider. Its services allow users to pay on the platform and administrators to handle payouts.

Learn more about the PSP available in Second: Payment Service Provider (PSP) - Business rules

For which services

For all services

Interfaces

Please, find all interface documentation related to the Mangopay bundle, here:

SBO:

• Payments management - Update Payout

Front:

• Booking request (Time-Based rendering type) - The Payment Page

Configurations

SBO > Other > Feature > Payments

Workflows

You can find all workflows related to the Mangopay bundle.

Mangopay booking workflow

Mangopay card registration and preauthorization

Mangopay preauthorized pay-in activity

Mangopay pay-in refund activity

Mangopay transfer activity

Escrow management

Mangopay payment methods

Bankwire payment

To select payment by bank wire transfer, the user clicks the bank wire transfer block (figure 12).

The user is then redirected to the confirmation page.

Bank wire payment configurations

Once an offerer accepts a booking in any bundle with bank wire as the payment method, the status is set to "Waiting for Payment." This status remains in effect until the configuration cocorico_booking.acceptation_delay is triggered. During this waiting period, a countdown timer is visible, indicating the time remaining before the acceptance delay is reached. If payment is not received before this deadline, the booking status is automatically changed to "Expired."

It's important to note that any changes to the configuration value cocorico_booking.min_start_time_delay will have an impact on the duration of the "Waiting for Payment" status, potentially making it longer or shorter.

Card payment

For card payments on Mangopay, the workflow follows the same process as outlined for Stripe. For additional details, refer to the section "Stripe - Credit Card Payment."

Special rules

Mangopay fees

• Pay-in: 1,8% + 0,18€ per transaction without VAT

• Payout: Free per transaction, in SEPA zone

Verification of physical person: Free

Verification of legal entity: 2,5€

Dispute lost: 15€

If the proof of identity verification refusal rate exceeds 15% per month, MANGOPAY will charge you €1 for any additional documents.

KYC/KYB process

The validation process will be fully integrated within Second and will be as follows:

The user fills in their information on the Identity page: User profile dashboard (All rendering type) - Identity

If and only if the user is an offeror (has an ad or in the non-switch platform is defined as an offerer) he will be able to add the necessary documents for his validation by the PSP.

• Proof of Identity

• Proof of registration (for Enterprise only)

• Articles of association (for Enterprise only)

• UBO declaration (for Enterprise only)

If an offeror that is KYC/KYB validated, changes any of the following information in Identity:

• First name

• Last name

• Birthdate

• Company information

• Country of residence or birth residence

His validated status is canceled and he will have to start the process again.

The payment provider status (figure 2) can be seen at the top of the payment details page.

Escrow management

Mangopay is based on the concept of One user = One wallet.

In the case of a booking, Second will use the wallet of an asker and the wallet of an offeror.

A wallet is credited upon receipt of a pay-in whether it is by credit card or bank transfer.

This money will be held in escrow until the booking is validated by Second based platform.

At that time a wallet-to-wallet transfer will be made.

The bidder's wallet will receive the total amount of the booking minus the platform's fees.

A fee wallet will receive the platform's commissions.

Once the super administrator from the platform has activated the payout from the platform, Mangopay will send the money to the bidder's bank account. The super administrator will notify in case of success or failure.

In case of a cancellation on a reservation paid by credit card, the asker is automatically refunded and the wallet-to-wallet transfer plus commission transfer is done directly and the super administrator from the platform will be able to finalize the operation by authorizing the PayOut.

In the case of a reservation paid by bank transfer, the difference is that the administrator will have to make the refund by authorizing a PayOut from the SBO...

• Why / Which context

• Steps to reproduce

  • Make a booking on your platform

  • Accept the subscription request and enable payments

  • Test the active period

  • The asker needs to confirm the payin

  • Test the next subscription period

• Commands

  • Reminder

• Status

  • Subscription period

    • Workflow

    • Status

  • Subscription status

Why / Which context

The inter-user subscription allows automatic recurring payment for one booking.

Payments are automatic in production, but in environment tests, it will take a few days to complete a workflow.

Steps to reproduce

You do not need to have access to the Mangopay dashboard, all is handled through Second platform.

Make a booking on your platform

Go on your platform and log in as an asker and create a booking request.

Learn more on the process of booking requests here: Booking confirmation pages (Subscription Feature)

And fill in the credit card information.

The bank-wire payment is not available for subscription services.

Accept the subscription request and enable payments

Once the payment has been made by the asker, the offeror can accept the subscription.

Learn more on the process of booking management here: Bookings dashboard (Subscription Feature)

By default, the Payin is done 2 days before the start date of the subscription period. This is set with the following configuration: subscription_automatic.

The status of the subscription period will be Paid but the payin will not be done.

Test the active period

Go in the SBO and fill the arguments in the command subscription.status

Arguments: --test --id=1868442188 --clock=P1Y1MT1H1M

The same process to enable the payout: the command cocorico:subscription:validate.

Arguments: --test --delay-weekly=-P1M

No space between the = and the Clock naming convention

Do not forget the - before the period

The asker need to confirm the payin

Once the offeror accept the booking, the asker will have to confirm the booking.

He have to fill a 2nd time his payment information. This is for security reasons but he will not be charge twice.

This security confirmation appears only for the first period. Once it is done you do not have to do it again.

Test the next subscription period

To finish the complete workflow you should test the next period.

Once the period T is active it will create the next subscription period is pending.

You can reproduce the point 5. test the active period.

The expected behavior is:

• The current subscription period is done

• The next subscription period is active

• The payout is available

You can reproduce steps 5 as many as you want in order to test several subscription period.

Commands

• second:subscription:expire

  • Simulate a subscription request that has not been accepted or declined

  • No arguments

• second:subscription:status

  • Simulate the day of the platform to test payin and status

  • Args: --test --id=1868442188 --clock=P1M

• second:subscription:validate

  • Simulate the day of the platform to test payout and status and enable another subscription period

  • Args: --test --delay-weekly=-P1M

    

Reminder

No space between the = and the Clock naming convention

Do not forget the - before the period

Status

Subscription period

Workflow

The subscription period workflow for a Accepted subscription request is:

Pending > Accepted > Paid > Active > Done

Status

• Pending: the next period, it is waiting for subscription acceptance or for payment

• Canceled: the next period was canceled by the asker

• Declined: the subscription request was canceled by the offerer

• PaymentError: the next period has a payment issue

• Paid: the next period was paid successfully but the period didn’t start yet (payment attempt delay)

• Active: the next period becomes active when the period starts (new cron command required)

• Done: the current period becomes done when the period ends (new cron command required)

• Canceled: the current period is paid or pending, and the active period (if any) becomes Done when the period ends.

Subscription status

• Pending: the subscription request is waiting for the offerer acceptation

• Canceled: the subscription request was canceled by the asker

• Declined: the subscription request was canceled by the offerer

• Accepted: the subscription request was accepted by the offerer

• PaymentError: the next subscription period has a payment issue

• Paid: the first period was paid successfully but the period didn’t start yet (payment attempt delay)

• Active: the next period starts and it’s paid (new cron command required)

• Canceled: the next period was canceled and ( there is no current paid period or the current paid period ends ) (new cron command required)

• Why

• Which context

• Interfaces

• Configurations

  • Access rights

• Workflows

• Special rules

Why

Banking aliases allow you to create a way to pay funds directly into a wallet, without having to declare the payin beforehand. For example, if you create an IBAN banking alias for a wallet, you'll be given a unique IBAN and BIC for this wallet. Any funds that we receive for this IBAN and BIC will be automatically credited to the wallet

Which context

As RPFs normally are from services with a high value in price, the banking alias comes up as a solution to avoid additional fees from debit or credit card payments.

Interfaces

Please, find all interface documentation related to the MangoPay Bank Wire Transfer Payment, here:

Mangopay bundle:

• Mangopay rendering type (PSP) - Business rules

Configurations

• SBO > Other > Feature > Payment

Access rights

Workflows

Special rules

There are no special rules for Bank Wire Transfer Payments.