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 merchantsAttach 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:
/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"
}
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
channel_merchant_id
Yes
Unique identifier of this merchant in the channel’s systems.
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.
Payout Detail Parameters
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.
Update Merchant Onboarding Record
Updates an onboarding record using the merchant_onboarding_id
.
PUT /v1/merchants/onboard/:merchant_onboarding_id
Potential Errors
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
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
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.
Potential Errors
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
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.
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.
Last updated
Was this helpful?