Stripe is an integrated payment solution and vendor payout option between the Omnyfy Marketplace and the Vendors on the platform. This comes out of the box for any Omnyfy Implementation, however if you are not using Stripe as your payment method or you are not taking any payments for Vendor Subscription plans, then you can skip this step.

This step includes configuration within your Stripe account and within the Omnyfy platform, so it will be handy to have 2 tabs open with both interfaces.

A very important thing to note is that during this set up process, you will need to either remove any HTTP Authorisations or whitelist any Stripe Webhook URLs if you have any access restrictions - or you will not be able to set up the webhooks and redirections properly.


1. Set up a Stripe account

First, you will need to ensure you have a stripe account. Simply go to https://stripe.com/ and sign up. You will need to verify your e-mail address as soon as you submit the sign up form.

NOTE: If you already have a Stripe account, you cannot use this here unless it was already tailor made for the Marketplace.

Once you verify your e-mail address, you will need to ensure that you populate the necessary business information to activate your account. This is a critical step and needs to be done before it takes real money.


2. Module Configuration

Before you start configuring anything, please take note of the mode that you are in (Test Mode or Live Mode). There is a toggle to show Test Data. Please ensure that if you are configuring for the Live Environment, that the toggle is not set to "Viewing test data" so that you copy Live Keys and configurations - Likewise with Test Environment with Test Data, ensure you have "Viewing test data" set. See below the flags to check.

Once you are ready to configure Stripe with Omnyfy, start by obtaining the API keys. In Stripe, go to Developers > API keys. Here you will see 2 keys that will need to be copied: Publishable Key and Secret Key.

PAYMENT GATEWAY

If you are not taking customer payments or Vendor payouts with Stripe and only using Stripe for Vendor Subscriptions Plans, you can skip this step and go to the next configuration step

Once you have copied the correct keys, in another tab/window, log in as an admin for the marketplace back end. Then go to Stores > Settings > Configuration > Sales > Payment Methods > Stripe > Configure > Basic.

Field Name

Notes

Module Version

Dictates the version of the Stripe Payment module installed on the platform

Mode

Setting this will alter some of the behaviours of the payments.

Test: Purchases completed with a test card and not actually spend real money. You will also be able to test a variety of other example credit card scenarios.

Live: Will require real debit/credit cards to process an order and deals with real transactions. Only apply this when you are ready to launch your marketplace.

Publishable API Key

Copy and paste the token from your Stripe account

Secret API Key

Copy and paste the token from your Stripe account

Webhooks

Before selecting "Configure, you will need to first "Save Config" for this configuration to save the keys to the platform. Once saved, you can select "Configure" to then use the keys to access Stripe and configure your webhooks.

You can also visit the link under the Configure button to see if the Webhooks are working. It should show up with a message

Webhooks Signing Secret

This field will be covered in a later step for configuring the webhook with the endpoint events from Stripe.

VENDOR SUBSCRIPTION PLANS LINKING

If you are not going to take payments for Vendor Subscription Plans, you can skip this step.

Copy and paste the Publishable and Secret API Keys from the Stripe dashboard. Then in the Omnyfy admin, go to Stores > Settings > Configuration > Omnyfy > Stripe API (for subscription).

Field Name

Notes

Publishable API Key

Copy and paste the token from your Stripe account

Secret API Key

Copy and paste the token from your Stripe account

Debug

Allows Debug Mode enabled (for developer use)

Prorate

Leave as default "Yes"



3. Vendor Payout Linking

Once you have done that, you will need to now configure the Client ID. To get the Client ID information, you will need to go to Stripe and ensure your account is activated. If not, you can only connect with Test Mode. Within your Stripe account, go to Settings > Connect.

Select Marketplace when the prompt appears and it should take you to the next steps. If you haven't yet activated your account, you can still set this up in test mode by simply going back to Settings > Connect > Settings (only appears after you have started setting things up).

See below the steps to activate your account for Connect on the Live environment.

  1. When in the settings page (Settings > Connect > Settings), choose "Start" to begin activation

  2. Choose "Get Started" for Marketplace Model.


  3. Select Platform or marketplace

  4. Select the industry (mostly "E-commerce products" since it's a Marketplace).

  5. Choose "From your platform's website or app".

  6. Choose "Your platform's name" - this will be used to invoice

  7. Choose "Your Platform"

  8. Choose the applicable option for your marketplace for the next steps

  9. Review your responses and edit anything before submitting

  10. Now you will be connected. You can go back into Settings > Connect > Settings

From here you can scroll down to Integration > Test mode client ID. Copy this field and in the Omnyfy Platform, go to Stores > Settings > Configuration > Omnyfy > Stripe Config

Field Name

Notes

Client ID

Copy and paste the Client ID from Stripe

Connect Account Webhook Signing secret

This is used in a later step when configuring the webhooks with the Connected Account.


4. Setting up the Marketplace Branding on Stripe

Now that you can access the Connect settings, you will be able to see the Branding section in Stripe that allows you to customise the colour scheme and label. See below:

This section can be edited as you wish, and you will be able to see a preview below of what it looks like. This branding is mainly used when a Vendor sets up their KYC through the platform during their Profile creation process.


5. Configuring Stripe Redirection and OAuth

While you're on this page, you will need to allow OAuth for Stripe KYC management. This can be found in Settings > Connect > Settings > Integration > OAuth Settings.

Please enable OAuth for Express accounts.

The next step would be to configure the Stripe Redirection that is used after Vendors set up their KYC through their Profile creation. This can just be added through the Stripe account by going to Settings > Connect > Settings > Integration > Redirects > + Add URI

Here you need to add your own URL for your marketplace in this format:

http(s)://{admin-project-host}/{admin_url}/omnyfy_vendor/vendor/index

EG: https://admin.marketplacedemo.com/admin_abc123/omnyfy_vendor/vendor/index

This will redirect vendors to this URL after they complete their KYC.


6. Basic Webhook Configurations

Ensure that you have already completed the webhook "Configure" field in step 2. This would have automatically created the webhook endpoint in Stripe with all of the events, however we do not need everything. In Stripe, go to Developers > Webhook.

NOTE: Should the "Configure" action from the platform fail to automatically create the webhook endpoint for your marketplace, this can still be done by adding an endpoint from the top right of "Endpoints receiving events from your account". Simply add http(s)://{project-host}/stripe/webhooks - replacing {project-host} with your admin domain.

NOTE: Please also take note that the URLs should be the admin domain WITHOUT the admin directory. EG: http(s)://{project-host}/stripe/webhooks. This URL structure will be used later so keep this in mind.

Now we will need to update the correct webhooks for this endpoint. Select your endpoint. Once inside, go to the Webhook details section and select "Update details..."

On the pop up, go to the Events to send section and choose "Clear". This will wipe the list of events displayed.

Now you will need to add the following events that include:

  • Charge

  • Sources

  • Payment Intent

  • Invoice

Simply select the dropdown, and type the events as above. You will see a grouping of events that you can add together. Here are the examples.

Once you have added those events, you should see a total of 40 events added on the list if you scroll down the pop up

Now select Update endpoint.

Once the endpoint has been updated, you can scroll down to get the "Signing secret" from that endpoint and paste it in the configuration for Omnyfy's Payment Gateway configuration as per step 2 (Stores > Settings > Configuration > Sales > Payment Methods > Stripe > Configure > Basic > Signing Secret).


7. Webhook Configurations for Subscriptions

Using the same method as in step 5, you will need to add the following endpoints and specific events for each one (not the group of events):

Endpoint URL

(All starting with http(s)://{project-host}/)

Specific Event

/omnyfy_stripe/invoice_payment/succeed/

invoice.payment_succeeded

/omnyfy_stripe/invoice_payment/failed/

invoice.payment_failed

/omnyfy_stripe/subscription/created/

customer.subscription.created

/omnyfy_stripe/subscription/updated/

customer.subscription.updated

/omnyfy_stripe/subscription/deleted/

customer.subscription.deleted

Just as a reminder, that your Endpoint URL should start with your Admin URL in place of {project-host}, not your main URL - but should NOT include your admin directory. The description field is optional.

See example below the single event:

You can test each webhook by selecting "Send test webhook" in Stripe. Here you can see a pop up for what event to test (since each of these webhooks are only looking at a single event, the event will be automatically selected).

Here you can see a pop up for what event to test (since each of these webhooks are only looking at a single event, the event will be automatically selected). Simply select "Send test webhook" and it will trigger the webhook and get a response.


8. Webhook Configurations for Payouts

This configuration will be similar to step 5, however you will be managing the endpoints from the Connect applications. In Stripe, go to Developers > Webhooks > Endpoints receiving events from Connect applications > + Add endpoint.

Here you will need to add the following:

Endpoint URL

Specific Events

http(s)://{project-host}/omnyfy_stripe/webhooks

(remember that you need to add the Admin URL in place of {project-host})

  • payout.canceled

  • payout.created

  • payout.failed

  • payout.paid

  • payout.updated

  • account.updated

(NOTE: You can select the entire Payout group of events)

See example below:

Select "Add endpoint".

Once you have saved it, you can copy the Signing secret below.

You will need to paste this in Omnyfy under Stores > Settings > Configuration > Omnyfy > Stripe Config > Connect Account Webhook Signing secret.

Save your configuration and test your webhook on Stripe using the "Send test webhook".

Note: Webhooks signing secret - This is an optional key that you can use to verify the origin of webhooks sent to your website. Although the setting is optional, you should set it to ensure that the webhooks you receive are sent by Stripe, rather than a third party. You can retrieve the signing key from the specific webhook that you configured for your website. If you configure the same webhook endpoint for both live and test mode, the signing secret will be different for each mode.


9. Setting Payouts to be Manual Transfer

One last setting related to Payouts, you need to set the Payout Schedule to be Manual. This is important as by default, your money in stripe can automatically be sent to your bank account - and could leave you with no money remaining in Stripe to payout your vendors.

Go to Stripe, and select Settings > Business settings > Your business > Bank accounts and scheduling.

From here, go to Payout Schedule, and select "Manual". Then select "Save" (you may be asked to input your password again for security reasons).

Once that's done, Stripe should be totally configured for your marketplace.


Did this answer your question?