Marketplace Payments Integration Guide

A marketplace platform is an online platform where multiple vendors can sell their products or services to a wide customer base. The role of the marketplace is to bring together the right sellers and the right customers to drive sales through a multi-vendor platform. Sellers gain visibility and sell their products, and the marketplace owner earns a commission from each sale.

Before getting started, you should familiarize yourself with a typical marketplace workflow. The workflow of a marketplace order involves the following steps:

Order Payment: When shoppers places an order, they pay in full the marketplace provider. The order can include items from different sellers. The marketplace provider holds the funds until the order is successfully delivered by the sellers.
Fulfillment and Delivery: The sellers fulfill the order and ship the products to the customer. Each seller must confirm shipment within the marketplace platform.
Payment Release: Once the order is confirmed as delivered, the marketplace releases the payout to the sellers. This process can vary in time depending on the marketplace’s policies.
Payment Transfer: The marketplace transfers the funds to the seller’s account. The funds are transferred from an escrow account that was previously pre-funded by the Marketplace provider.
Fees Deduction: The marketplace deducts any fees or commissions from the payout. These fees are for using the marketplace platform and services.
Seller Receives Payout: After all fees are deducted, the seller receives the net amount in their account.

Please note that the exact process can vary depending on the Marketplace platform and your policies. Some Marketplaces may have a minimum payout threshold or specific payout schedules (e.g., weekly, bi-weekly, monthly). With Marketplace Payments you have full flexibility to implement your own payout process.

Marketplace Payments is the API solution built for marketplace platforms that allows to manage the end to end life cycle of a marketplace order. Possible actions are:

Seller onboarding: create an account for your vendors saving billing and payment details for later use
Payment collection: get paid in full for the orders providing different payment options at checkout to the shoppers
Payouts: disburse the money to one or more sellers with a single request

Follow the detailed integration steps in the tutorials below to know more.

Integration Steps

Marketplace Payments is not enabled by default. To enable the feature, please contact your account manager.

The integration with Marketplace Payments is done using the following endpoints:

v1/marketplace/sellers: used to manage the sellers entities
v1/checkouts or v1/payments: used to collect the payments from the shopper
v1/marketplace/payouts: used to issue payouts to the sellers

Seller Onboarding

Onboard your sellers on the platform.

Select

Payment collection

Collect payments for the orders using the standard payment rails.

Select

Payouts

Payout one or more of your sellers with a single API request.

Select

Seller Onboarding

With the Seller Onboarding API you will be able to manage your sellers on your platform. The Sellers API allows you to add new sellers. A seller has a unique identifier that can be used during the payment collection of a marketplace order and to issue payouts.

How it works

Create seller

Send a create seller request containing billing and payment details of the seller.

Transactions:

Create a seller

Payment Collection

It is responsibility of the Marketplace provider to collect the funds from the shopper and notify the sellers of the payment result to proceed with the order fulfillment.

With Marketplace Payments it is possible to collect funds with any of the payment methods available on the platform. To collect the payments for the orders placed in your Marketplace platform you can use the multiple options available like COPYandPAY, Server-to-Server or even MobileSDK. Similarly, payments can be managed directly via Backoffice API as any other e-commerce order.

What must be considered is to include sellers information and identifiers in the create checkout request. This information is essential to perform a corrent reporting and keep track of the orders. See the example request below.

How it works

In this tutorial only the COPYandPAY integration is shown. Similar concepts and guidelines apply also for Server-to-Server and MobileSDK.

Prepare the checkout

Send the request parameters server-to-server to prepare the payment form.

Create the payment form(s)

Display the payment form on your checkout page and the shopper submits the payment information.

Get the payment status

Find out if the payment was successful.

1. Prepare the checkout

First, perform a server-to-server POST request to prepare the checkout with the required data, including the order type, amount and currency. Since this is a Marketplace order it is recommended to include also the individual seller information at line item level. The response to a successful request is a JSON string with an id, which is required in the second step to create the payment form.

For a full list of parameters that can be sent in the prepare checkout request, please see the API Reference

Please note that for a HTTP POST request all the parameters are expected to go into the message body and not into the URL.

2. Create the payment form

To create the payment form you just need to add the following lines of HTML/JavaScript to your page and populating the following variables

The checkout's id that you got in the response from step 1

<script src="https://eu-test.oppwa.com/v1/paymentWidgets.js?checkoutId={checkoutId}"></script>

The shopperResultUrl, which is the page on your site where the customer should be redirected to after the payment is processed and the brands that will be available.
```
<form action="{shopperResultUrl}" class="paymentWidgets" data-brands="VISA MASTER AMEX"></form>
```

A checkout id expires when a payment has been finalized successfully by user, but not later than 30 minutes. Before it expires, it can be used multiple times in order to render a payment form and updated with additional data.

3. Get the payment status

Once the payment has been processed, the customer is redirected to your shopperResultUrl along with a GET parameter resourcePath.

Important: The baseUrl must end in a "/", e.g. "https://eu-test.oppwa.com/".

Then, to get the status of the payment, you should make a GET request to the baseUrl + resourcePath, including your authentication parameters.

Example of a resourcePath:

resourcePath=/v1/checkouts/{checkoutId}/payment

Once a status response is successful the checkout identifier can't be used anymore. In this case the Transaction Reports endpoint can be used to get the transaction status using the payment id.

IMPORTANT: A throttling rule applies for get payment status calls. Per checkout, it is allowed to send two get payment requests in a minute.

Marketplace Payments Integration Guide

Integration Steps

Seller Onboarding

Payment collection

Payouts

Seller Onboarding

How it works

Create seller

Create a seller

Payment Collection

How it works

Prepare the checkout

Create the payment form(s)

Get the payment status

1. Prepare the checkout

2. Create the payment form

3. Get the payment status

Payouts

How it works

Send payouts

Send one or more payouts