Violet’s Onboarding APIs let Channels pre-provision merchant data before a merchant completes the Violet Connect flow. These APIs allow you to pass metadata—such as your internal Merchant ID or external Payment Provider credentials—to programmatically associate merchant and payout details prior to onboarding a Merchant via Violet Connect.

What Are Onboarding APIs?

The Onboarding APIs are designed to:

Pass data about merchants in your system before they formally exist in Violet (i.e. prior to going through Violet Connect).
Associate internal merchant identifiers (channel_merchant_id) with Violet merchants
Attach metadata such as payout account credentials (e.g. Stripe Account IDs) to be used by Violet during Violet Connect onboarding.
Retrieve and update onboarding records during the pre-connect phase

Once a merchant completes Violet Connect, this onboarding data is automatically merged into the Violet Merchant record. From that point on, use Merchant APIs to interact with merchant data.

Onboarding Flow Diagram

This is a sample flow of how our Onboarding APIs interact with Violet Connect during Merchant Onboarding.

Types of Onboarding Data

Merchant Identity

Use channel_merchant_id to uniquely identify the merchant in your system. This ensures that the merchant onboarding in your system is correctly linked to their Violet Connect onboarding process.

Example use case:

Matching a merchant who’s onboarded to your marketplace with their corresponding record in Violet

Payout Data

You can attach payout account credentials such as a Stripe Connect account_id before the merchant is created in Violet. If you sent the channel_merchant_id or merchant_onboarding_id to Violet Connect while onboarding this merchant, Violet will automatically create a Violet Payout Account associated with this Stripe Account during onboarding.

Available Onboarding APIs

Violet provides the following endpoints to manage onboarding records:

Endpoint	Method	Purpose
`/v1/merchants/onboard`	`POST`	Create a new onboarding record
`/v1/merchants/onboard/:merchant_onboarding_id`	`PUT`	Update by onboarding record ID
`/v1/merchants/onboard/:merchant_onboarding_id`	`GET`	Get a specific onboarding record

Once onboarding is complete, these records are removed and replaced by standard Merchant and Payout Account objects.

Each of these APIs returns a MerchantOnboardingRecord. The merchant_onboarding_id can be passed into Violet Connect to tell Violet to use the pre-provided data during onboarding.

{
	"merchant_onboarding_id": 10000,
	"channel_merchant_id": "chnl_123456789",
	"app_id": 10193,
	"date_created": "2024-06-24T15:30:55+0000",
	"date_last_modified": "2024-06-24T15:30:57+0000"
}

Field	Type	Description
`merchant_onboarding_id`	Integer	Unique identifier for the onboarding record generated by Violet. Used to track and update merchant data that will be used by Violet during onboarding.
`channel_merchant_id`	String	Unique identifier for the merchant in your system. Used to link your merchant record with the one created in Violet.
`app_id`	Integer	Identifier for your application within Violet. Determines which channel or integration this onboarding record is associated with.
`date_created`	Date	Timestamp indicating when the onboarding record was first created. Format: `YYYY-MM-DDTHH:MM:SS+ZZZZ`
`date_last_modified`	Date	Timestamp of the most recent update to the onboarding record. Format: `YYYY-MM-DDTHH:MM:SS+ZZZZ`

Create Merchant Onboarding Record

Creates a new onboarding record with a unique identifier for the merchant in your system.

POST /v1/merchants/onboard

{
	"channel_merchant_id": "chnl_123456789",
}

Request Body Parameters

Field	Required	Description
`channel_merchant_id`	Yes	Unique identifier of this merchant in the channel’s systems.

Sample Response

    {
    	"merchant_onboarding_id": 10000,
    	"channel_merchant_id": "chnl_123456789",
    	"app_id": 10385,
    	"date_created": "2024-06-24T15:30:55+0000",
    	"date_last_modified": "2024-06-24T15:30:57+0000"
    }

Optional: Adding Payout Account Data

You can include payout account information (e.g. a Stripe Connect ID) when creating a merchant onboarding record to associate a pre-existing Payment Provider account with a Violet Merchant during Violet Connect.

Sample Request

    POST /v1/merchants/onboard

    {
    	"channel_merchant_id": "chnl_123456789",
    	"payout_details": {
    		"payment_provider": "STRIPE",
    		"payment_provider_metadata": {
    			"stripe_account_id": "acct_123456789"
    		}
    	}
    }

Payout Detail Parameters

Field	Required	Description
`payout_details`	Yes	Wrapper object that contains information needed for payout account onboarding.
`payment_provider`	Yes	Payment provider that this underlying payout account was created on. The metadata fields correspond to the payment provider.
`payment_provider_metadata`	Yes	Wrapper object that contains information specifically required to onboard payout accounts for the given payment provider.
`stripe_account_id`	Yes	Account identifier of this merchant’s Stripe Connect account in Stripe’s systems.

If your Stripe Platform Account has not been set up with Violet, Violet will not subscribe to any webhook updates sent from Stripe for the provided Stripe Connect account.

Sample Response

    {
    	"merchant_onboarding_id": 10000,
    	"channel_merchant_id": "chnl_123456789",
    	"app_id": 10385,
    	"payout_details": {
            "payment_provider": "STRIPE",
            "payment_provider_metadata": {
                "stripe_account_id": "acct_123456789"
            }
        },
    	"date_created": "2024-06-24T15:30:55+0000",
    	"date_last_modified": "2024-06-24T15:30:57+0000"
    }

Update Merchant Onboarding Record

Updates an onboarding record using the merchant_onboarding_id.

PUT /v1/merchants/onboard/:merchant_onboarding_id

Sample Request

This call will update an existing Merchant Onboarding record with additional Payout Details:

 PUT /v1/merchants/onboard/merchant_onboarding_id/10000

 {
	"channel_merchant_id": "chnl_999999999"
	"payout_details": {
        "payment_provider": "STRIPE",
        "payment_provider_metadata": {
            "stripe_account_id": "acct_123456789"
        }
    }
}

Sample Response

    {
    	"merchant_onboarding_id": 10000,
    	"channel_merchant_id": "chnl_999999999",
    	"app_id": 10385,
    	"payout_details": {
            "payment_provider": "STRIPE",
            "metadata": {
                "stripe_account_id": "acct_123456789"
            }
        },,
    	"date_created": "2024-06-24T15:30:55+0000",
    	"date_last_modified": "2024-06-24T15:30:57+0000"
    }

Potential Errors

Request	Error Code	Error Title	Error Message	Reason	How to Fix
`PUT`	4429	merchant_onboarding_record_not_found	Merchant onboarding record with ID not found.	The provided `merchant_onboarding_id` doesn’t exist in our system.	Create a new `merchant_onboarding_record` using the `POST /merchant/onboarding` API.
`POST`	2514	merchant_already_onboarded	This merchant already exists in Violet (Merchant Id: ). Once a merchant has been onboarded, you must directly interact with the Merchant endpoints available here to retrieve or update merchant details.	Call is made after the merchant has already been onboarded through Violet Connect and that merchant in Violet has the same `channel_merchant_id` as this merchant onboarding update request.	Directly interact with the Merchant endpoints available in Violet Docs to retrieve/update merchant details.

Update Limitations

Field	Can be updated?	Behavior if passed in	Notes
`merchant_onboarding_id`	No	Used for record retrieval	If a `merchant_onboarding_id` is passed in and a record is not found, a `merchant_onboarding_record_not_found` exception will be thrown.
`channel_merchant_id`	Yes	Updated
`date_created`	No	Ignored
`date_last_modified`	No	Ignored

Retrieve a specific Merchant Onboarding Record

Returns the Merchant Onboarding Record for the given merchant_onboarding_id.

GET /v1/merchants/onboard/:merchant_onboarding_id

Request Parameters

Field	Type	Required	Description
`merchant_onboarding_id`	Path Parameter	Yes	The unique identifier for this merchant’s onboarding record. This value was returned as a part of the Create External Account call.

Violet will respond with the following if a merchant onboarding record matching the given id is found.

Sample Response

{
    "merchant_onboarding_id": 10000,
    "app_id": 10385,
    "channel_merchant_id": "chnl_123456789",
    "payout_details": {
            "payment_provider": "STRIPE",
            "metadata": {
                "stripe_account_id": "acct_123456789"
            }
    }
    "date_created": "2024-06-24T15:30:55+0000",
    "date_last_modified": "2024-06-24T15:30:57+0000"
}

Potential Errors

Request	Error Code	Error Title	Error Message	Reason	How to Fix
`PUT`	4429	merchant_onboarding_record_not_found	Merchant onboarding record with ID not found.	The provided `merchant_onboarding_id` doesn’t exist in our system.	Create a new `merchant_onboarding_record` using the `POST /merchant/onboarding` API.
`POST`	2514	merchant_already_onboarded	This merchant already exists in Violet (Merchant Id: ). Once a merchant has been onboarded, you must directly interact with the Merchant endpoints available here to retrieve or update merchant details.	Call is made after the merchant has already been onboarded through Violet Connect and that merchant in Violet has the same `channel_merchant_id` as this merchant onboarding update request.	Directly interact with the Merchant endpoints available in Violet Docs to retrieve/update merchant details.

During Violet Connect

If you’ve sent Violet onboarding data ahead of time—such as merchant identifiers or payout credentials—you’ll need to ensure that data is correctly matched when the merchant begins the Violet Connect process.

Violet Connect

Each channel has a custom Violet Connect URL to onboard merchants. To associate an in-progress onboarding record with a merchant during Connect, include either the channel_merchant_id or the merchant_onboarding_id as a query parameter in the Connect link.

To onboard a merchant, each channel has a custom Violet Connect link. To learn about Violet Connect in more detail, refer to our documentation.

For example, the Violet Connect URL could be:

https://connect.violet.io/<channel_custom_url>/login?channel_merchant_id=chnl_123456789

or it could be

https://connect.violet.io/<channel_custom_url>/login?merchant_onboarding_id=10002

When the merchant completes Violet Connect, Violet will automatically link the onboarding record to the new Merchant. After this point, the onboarding record is removed, and further updates must be made via the Merchant APIs.

Merchant Webhooks

Upon successful onboarding, Violet emits the following webhook events:

MERCHANT_CONNECTED – Sent when the merchant completes Violet Connect

Scenario Specific:

MERCHANT_PAYOUT_ACCOUNT_CREATED – Sent if payout details were provided during onboarding and a payout account was successfully created

Learn more about these events and their payloads in our Merchant Webhooks and Payment Webhooks documentation.

Introduction

Getting Started

Checkout

Payments

Violet Connect

Relay

Product Info

Support

Pre-provisioning Merchant Data for Violet Connect

What Are Onboarding APIs?

Onboarding Flow Diagram

Types of Onboarding Data

Merchant Identity

Payout Data

Available Onboarding APIs

Create Merchant Onboarding Record

Update Merchant Onboarding Record

Potential Errors

Update Limitations

Retrieve a specific Merchant Onboarding Record

Potential Errors

During Violet Connect

Violet Connect

Merchant Webhooks

Introduction

Getting Started

Checkout

Payments

Violet Connect

Relay

Product Info

Support

​What Are Onboarding APIs?

​Onboarding Flow Diagram

​Types of Onboarding Data

​Merchant Identity

​Payout Data

​Available Onboarding APIs

​Create Merchant Onboarding Record

​Update Merchant Onboarding Record

​Potential Errors

​Update Limitations

​Retrieve a specific Merchant Onboarding Record

​Potential Errors

​During Violet Connect

​Violet Connect

​Merchant Webhooks

What Are Onboarding APIs?

Onboarding Flow Diagram

Types of Onboarding Data

Merchant Identity

Payout Data

Available Onboarding APIs

Create Merchant Onboarding Record

Update Merchant Onboarding Record

Potential Errors

Update Limitations

Retrieve a specific Merchant Onboarding Record

Potential Errors

During Violet Connect

Violet Connect

Merchant Webhooks