Sellers onboarding

Learn about the different options to onboard your sellers.

Stripe recommends creating Express accounts with the transfers capability to onboard your sellers.

With Express accounts, you can quickly onboard your sellers so they can be paid immediately. You can customize the branding of the Express onboarding flow and dashboard.

Custom accounts are also supported. You will have to develop your own form to collect the required information.

Standard accounts are not supported as they do not allow for Transfers to be created between the platform and the Connected accounts which is required for accepting payments on Mirakl.

Built-in integration

The onboarding job fetches newly created Mirakl Sellers via S20 and adds the onboarding link to the Custom Field created during the configuration via S07.
This link is located in the My Account section of their Mirakl back office. It redirects the seller to a hosted page where Stripe collects the required information and documents as well as the external bank account used to pay the seller out.

The seller is redirected back to the connector where a record is created to map the Mirakl Seller with their corresponding Stripe Express account.

The value of settings[payouts][schedule] is set to manual as required by the payouts workflow.

The seller is redirected back to the REDIRECT_ONBOARDING.

For successful connections, the following values are passed back in the redirect URL:

success=true&mirakl_shop_id=<SHOP_ID>
success=true&mirakl_shop_id=<SHOP_ID>

For failed connections, the following values are passed back in the redirect URL:

error=true&error_code=<ERROR_CODE>&error_description=<ERROR_DESCRIPTION>
error=true&error_code=<ERROR_CODE>&error_description=<ERROR_DESCRIPTION>

The list of error codes is available in the Oauth reference to which we add the following:

Parameter	Description
missing_code	The mandatory `code` parameter is missing from the query.
missing_state	The mandatory `state` parameter is missing from the query.
no_matching_state	The `state` returned by Stripe does not match any of the connector's internal states.
already_existing_shop	The Shop ID provided is already mapped to a Stripe account in the connector.

Onboard sellers without the connector

You can onboard sellers with your own integration of Express or Custom accounts.

Express accounts

The connector provides an API to generate a secure Express onboarding link with a Mirakl Shop ID as parameter:

curl \
  -X POST "https://connector-url/api/onboarding" \
  -H "accept: application/json" \
  -H "X-AUTH-TOKEN: <OPERATOR_PASSWORD>" \
  -H "Content-Type: application/json" \
  -d "{ \"miraklShopId\": <SHOP_ID>}"
curl \
  -X POST "https://connector-url/api/onboarding" \
  -H "accept: application/json" \
  -H "X-AUTH-TOKEN: <OPERATOR_PASSWORD>" \
  -H "Content-Type: application/json" \
  -d "{ \"miraklShopId\": <SHOP_ID>}"

The response contains a json object:

{
  "redirect_url": "https://connect.stripe.com/express/oauth/authorize?redirect_uri=https%3A%2F%2Fconnector-url%2Fapi%2Fpublic%2Fonboarding%2Fcreate_mapping&state=xxx&client_id=ca_xxx"
}
{
  "redirect_url": "https://connect.stripe.com/express/oauth/authorize?redirect_uri=https%3A%2F%2Fconnector-url%2Fapi%2Fpublic%2Fonboarding%2Fcreate_mapping&state=xxx&client_id=ca_xxx"
}

Redirect the seller to the link generated. The rest of the flow matches steps 3 and 4 of the built-in integration.

Custom accounts

Integrate Custom accounts by following our documentation.
Manually map the Custom account created with a Mirakl Shop ID by using the following endpoint:

curl \
	-X POST "https://connector-url/api/mappings" \
	-H "accept: application/json" \
	-H "X-AUTH-TOKEN: <OPERATOR_PASSWORD>" \
	-H "Content-Type: application/json" \
	-d "{ \"miraklShopId\": <SHOP_ID>, \"stripeUserId\": \"<ACCOUNT_ID>\"}"
curl \
	-X POST "https://connector-url/api/mappings" \
	-H "accept: application/json" \
	-H "X-AUTH-TOKEN: <OPERATOR_PASSWORD>" \
	-H "Content-Type: application/json" \
	-d "{ \"miraklShopId\": <SHOP_ID>, \"stripeUserId\": \"<ACCOUNT_ID>\"}"

You can see the full specifications of this endpoint including the list of errors codes by opening the base URL of your installed connector.

Accounts synchronization

The webhook endpoint you created during the configuration allows the connector to receive notification of account.updated events sent by Stripe.

If enabled, the connector notifies the OPERATOR_NOTIFICATION_URL. This notification can be used to trigger a communication to the seller letting him know that further information has to be submitted back to Stripe.

The Custom Field used for onboarding is used to provide a link to the seller’s Express dashboard in case further information is required by Stripe.