Pre-provisioning Merchant Data

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

/v1/merchants/onboard

GET

List all onboarding records currently in progress

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. This field can also be passed in as metadata.

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",
    "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"
}

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",
    "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"
}

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.

View all Merchant Onboarding Records

Returns a paginated list of all onboarding records you’ve created.

GET /v1/merchants/onboard

Request Parameters

Field
Type
Required
Description

size

Query Parameter

No

Maximum number of items to be returned in the response. By default, 20 elements will be returned. The total_pages and total_elements in the response will denote the total number of elements available.

page

Query Parameter

No

Maximum number of items to be returned in the response. By default, the first page of data will be returned. The total_pages and total_elements in the response will denote the total number of elements available.

Violet will respond with a Page of Merchant Onboarding Records that exist. For this example, let’s assume there 3 accounts currently in the onboarding phase.

Sample Response
{
    "content": [
      {
				"merchant_onboarding_id": 10000,
				"app_id": 10385,
				"channel_merchant_id": "chnl_123456789",
				"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"
			},
			{
				"merchant_onboarding_id": 10001,
				"app_id": 10385,
				"channel_merchant_id": "chnl_1111111111",
				"payout_details": {
                    "payment_provider": "STRIPE",
                    "payment_provider_metadata": {
                        "stripe_account_id": "acct_1111111111"
                    }
                },
				"date_created": "2024-06-24T15:30:55+0000",
				"date_last_modified": "2024-06-24T15:30:57+0000"
			},
			{
				"merchant_onboarding_id": 10003,
				"app_id": 10385,
				"channel_merchant_id": "chnl_222222222",
				"payout_details": {
                    "payment_provider": "STRIPE",
                    "payment_provider_metadata": {
                        "stripe_account_id": "acct_222222222"
                    }
				},
				"date_created": "2024-06-24T15:30:55+0000",
				"date_last_modified": "2024-06-24T15:30:57+0000"
			}
    ],
    "pageable": {
        "page_number": 0,
        "page_size": 3,
        "sort": {
            "unsorted": false,
            "sorted": true,
            "empty": false
        },
        "offset": 0,
        "paged": true,
        "unpaged": false
    },
    "total_pages": 1,
    "total_elements": 3,
    "last": false,
    "number_of_elements": 3,
    "first": true,
    "size": 3,
    "number": 0,
    "sort": {
        "unsorted": false,
        "sorted": true,
        "empty": false
    },
    "empty": false
}

If no merchants are in the onboarding state, a page with empty content will be returned.

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.

PreviousGuidesNextViolet Connect Step-by-Step

Last updated

Was this helpful?