# Create Merchant Application
> Create a new merchant application for an end connected merchant with encrypted company information. **Content-Type**: `application/json` **Authentication**: `X-API-Key` header required **Request Body**: JSON structure containing RSA-encrypted payload **Encrypted Payload Structure (before encryption)** **company_information**: (object, required)
Basic company details object (limited fields – see note below) | Field Name | Type | Required | Description | |----------------------------------------------|---------|----------|--------------------------------------------------------------------------| | email_address | string | Yes | Company email address (max 255 chars, valid email) | | phone_number | string | Yes | Company phone number (9–15 chars) | | billing_address | object | Yes | Company billing address (same structure as registered_address) | | annual_processing_volume | integer | Yes | Annual processing volume, in cents | | average_transaction_value | integer | Yes | Average transaction value, in cents | | highest_transaction_value | integer | Yes | Highest transaction value, in cents (must be ≥ average_transaction_value) | **company_information.registered_address**: (object, required)
Company registered address | Field Name | Type | Required | Description | |------------------------------------------------------|--------|----------|----------------------------| | address_line1 | string | Yes | Address line 1 (max 512) | | address_line2 | string | No | Address line 2 (max 512) | | city | string | Yes | City (max 128) | | state | string | Yes | State (max 128) | | zip | string | Yes | ZIP code (max 64) | | country | string | Yes | Country code (max 128) |
Source: https://help.boltapp.com/api-reference/merchant-onboarding/merchant-applications/create-merchant-application
`POST /v1/merchant_applications`
## OpenAPI definition
This endpoint as it appears in the OpenAPI document, with every schema it references included.
```json
{
"openapi": "3.2.0",
"info": {
"title": "Bolt Connect Merchant Onboarding API",
"version": "1.0.0",
"description": "## Overview\nThis collection provides comprehensive access to Bolt's Platform Connected Merchant Onboarding APIs, designed to enable platform platforms to onboard their sub-merchants seamlessly. The APIs support two primary workflows:\n1. **Direct Onboarding**: Platforms can directly onboard sub-merchants using the merchant application APIs\n2. **Self-Onboarding**: Platforms can generate sharable links for sub-merchants to complete their own onboarding\n\n## API Workflow\nThe typical onboarding workflow follows these steps:\n1. **Get Public Key** (`GET /v1/merchant-application/public-key`):
\nRetrieve RSA public key for encrypting \nsensitive data\n2. **Create Application** (`POST /v1/merchant_applications`):
\nCreate a new merchant application with encrypted company information\n3. **Upload Attachments** (`POST /v1/merchant_applications/{id}/attachments`): Upload required documents (tax verification, bank statements, etc.)\n4. **Update Application** (`PUT /v1/merchant_applications/{id}`):
\nComplete the application with encrypted form submission\n5. **Generate Link** (Optional) (`POST /v1/merchant_applications/onboarding-link`):\nGenerate self-onboarding link for sub-merchants\n\n## Encryption\n Sensitive data in requests must be encrypted using RSA-4096 encryption with the public key obtained from the public key endpoint.\n\n ### Node.js encryption example\n ```javascript\n const crypto = require('crypto');\n const axios = require('axios');\n // Function to fetch public key and encrypt JSON payload\nasync function encryptPayload(baseUrl, apiKey, jsonPayload) {\n try {\n // Step 1: Fetch the public key\n const publicKeyResponse = await axios.get(`${baseUrl}/v1/merchant-application/public-key`);\n const publicKeyBase64 = publicKeyResponse.data.public_key;\n // Step 2: Decode the base64-encoded PEM public key\n const publicKeyPEM = Buffer.from(publicKeyBase64, 'base64').toString('utf8');\n // Step 3: Convert JSON payload to string\n const payloadString = JSON.stringify(jsonPayload);\n // Step 4: Encrypt the payload using RSA-OAEP with SHA-256\n const encryptedBuffer = crypto.publicEncrypt({\n key: publicKeyPEM,\n padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,\n oaepHash: 'sha256'\n }, Buffer.from(payloadString, 'utf8'));\n // Step 5: Encode the encrypted data as base64\n const encryptedPayloadBase64 = encryptedBuffer.toString('base64');\n return {\n encrypted_payload: encryptedPayloadBase64\n };\n } catch (error) {\n console.error('Encryption failed:', error);\n throw error;\n }\n}\n// Example usage:\nconst payload = {\n company_information: {\n email_address: \"company@example.com\",\n phone_number: \"+1234567890\",\n registered_address: {\n address_line1: \"123 Main St\",\n city: \"San Francisco\",\n state: \"CA\",\n zip: \"94105\",\n country: \"US\"\n },\n billing_address: {\n address_line1: \"123 Main St\",\n city: \"San Francisco\",\n state: \"CA\",\n zip: \"94105\",\n country: \"US\"\n },\n annual_processing_volume: 1000000,\n average_transaction_value: 5000,\n highest_transaction_value: 10000\n }\n};\n// Encrypt and send request\nencryptPayload('https://api.boltapp.com', 'your-api-key', payload)\n .then(encryptedData => {\n // Use encryptedData in your API request\n return axios.post(`${baseUrl}/v1/merchant_applications`, encryptedData, {\n headers: {\n 'Content-Type': 'application/json',\n 'X-API-Key': 'your-api-key'\n }\n });\n})\n.then(response => {\n console.log('Merchant application created:', response.data);\n})\n.catch(error => {\n console.error('Request failed:', error);\n});\n ```\n"
},
"servers": [
{
"url": "https://api.boltapp.com"
}
],
"paths": {
"/v1/merchant_applications": {
"post": {
"operationId": "create_merchant_application",
"summary": "Create Merchant Application",
"description": "Create a new merchant application for an end connected merchant with encrypted\ncompany information.\n\n\n**Content-Type**: `application/json`\n\n**Authentication**: `X-API-Key` header required\n\n\n**Request Body**: JSON structure containing RSA-encrypted payload\n\n\n**Encrypted Payload Structure (before encryption)**\n\n**company_information**: (object, required)
\nBasic company details object (limited fields – see note below)\n\n| Field Name | Type | Required | Description |\n|----------------------------------------------|---------|----------|--------------------------------------------------------------------------|\n| email_address | string | Yes | Company email address (max 255 chars, valid email) |\n| phone_number | string | Yes | Company phone number (9–15 chars) |\n| billing_address | object | Yes | Company billing address (same structure as registered_address) |\n| annual_processing_volume | integer | Yes | Annual processing volume, in cents |\n| average_transaction_value | integer | Yes | Average transaction value, in cents |\n| highest_transaction_value | integer | Yes | Highest transaction value, in cents (must be ≥ average_transaction_value) |\n\n**company_information.registered_address**: (object, required)
\nCompany registered address\n\n| Field Name | Type | Required | Description |\n|------------------------------------------------------|--------|----------|----------------------------|\n| address_line1 | string | Yes | Address line 1 (max 512) |\n| address_line2 | string | No | Address line 2 (max 512) |\n| city | string | Yes | City (max 128) |\n| state | string | Yes | State (max 128) |\n| zip | string | Yes | ZIP code (max 64) |\n| country | string | Yes | Country code (max 128) |\n",
"responses": {
"200": {
"description": "Success Response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"merchant_application_id": {
"type": "string"
}
},
"required": [
"merchant_application_id"
]
},
"examples": {
"Success Response": {
"value": {
"merchant_application_id": "scoped_merchant_app_id_12345"
}
}
}
}
}
},
"400": {
"description": "Invalid Request Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Invalid Request Error": {
"value": {
"errors": [
{
"code": 1000001,
"message": "Registered Address is not complete",
"field": "registered_address"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Unauthorized Error": {
"value": {
"errors": [
{
"code": 18,
"message": "This action is forbidden",
"field": ""
}
]
}
}
}
}
}
},
"422": {
"description": "Invalid encryption or payload format",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Invalid encryption or payload format": {
"value": {
"errors": [
{
"code": 10,
"message": "Failed to decrypt payload",
"field": ""
}
]
}
}
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Internal Server Error": {
"value": {
"errors": [
{
"code": 46,
"message": "Internal error",
"field": ""
}
]
}
}
}
}
}
}
},
"tags": [
"Merchant Applications"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"encrypted_data": {
"type": "string",
"description": "Base64-encoded encrypted payload"
},
"nonce": {
"type": "string",
"description": "Base64-encoded 32-byte nonce (if applicable)"
},
"public_key": {
"type": "string",
"description": "Base64-encoded public key PEM (if payload includes key reference)"
}
},
"required": [
"encrypted_data"
]
},
"examples": {
"default": {
"value": {
"encrypted_data": "",
"nonce": "",
"public_key": ""
}
}
}
},
"application/octet-stream": {}
}
},
"security": [
{
"ApiKeyAuth": []
}
]
}
}
},
"components": {
"schemas": {
"ErrorResponse": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "Numeric error code"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"field": {
"type": "string",
"description": "Field related to the error, if applicable"
}
}
}
}
}
}
},
"securitySchemes": {
"ApiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "X-API-Key",
"description": "API key used to authorize requests for non-public endpoints."
}
}
}
}
```