--- updatedAt: 2026-06-09T17:02:41.000Z --- Fetch the complete documentation index at: https://hq.docs.netevia.com/llms.txt. Use this file to discover all available pages before exploring further. # /api/v2/merchant/create ## Create Merchant (V2) Creates a new merchant application in the V2 boarding system, returning a `merchantProfileId` that is used in all subsequent boarding steps. This endpoint establishes the merchant record with core identifying information — the fees program, POS system, agent, and owner name — but does not submit the application to the processor. Use `POST /api/v2/merchant/submit` to complete the full submission after populating all application sections. ### Endpoint `POST /api/v2/merchant/create` ### Authentication Basic HTTP Authentication required. Encode `username:password` in Base64 and pass in the Authorization header: ``` Authorization: Basic {base64(username:password)} ``` ### When to use This is the first step in the V2 merchant onboarding workflow after retrieving the agent profile (`GET /api/v2/agent/profile`) and boarding settings. Call this to create the merchant shell record, then use the returned `merchantProfileId` to populate merchant info, fees, owner details, and equipment via the update endpoints before calling the full submit endpoint. ### Request Body | Field | Type | Required | Description | | ------------------ | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | feesProgram | string (enum) | Yes | Pricing program for the merchant: `Traditional`, `CashDiscount`, `Surcharge`, `ServiceFee`, `DualPricing` | | firstName | string | Yes | Primary owner's first name | | lastName | string | Yes | Primary owner's last name | | dba | string | Yes | Doing Business As name of the merchant | | pos | string (enum) | Yes | Point-of-sale system: `None`, `AptitoPalomaPOS`, `Clover`, `PalomaPOS`, `Aldelo`, `Restoactive`, `PoyntPOS`, `CloverGo`, `UnifiedMpos`, `CustomPos`, `RetailCloud`, `EHopper`, `FreedomPos`, `ClubPos`, `SelfLane`, `OtfPOS`, `NProKiosk`, `GretaPOS` | | agentProfileId | integer (int32) | Yes | Agent profile ID — obtained from `GET /api/v2/agent/profile` | | email | string | No | Merchant owner's email address | | guid | string | No | External system GUID for idempotency or cross-system linking | | boardingSettingsId | integer (int32) | No | Boarding settings template ID — obtained from the boarding settings endpoint | ```json { "feesProgram": "CashDiscount", "firstName": "Sarah", "lastName": "Hernandez", "dba": "The Corner Bakery", "pos": "Clover", "agentProfileId": 204, "email": "sarah.hernandez@cornerbakery.com", "boardingSettingsId": 15 } ``` ### Response **200 OK** | Field | Type | Description | | ---------------------- | ------- | ---------------------------------------------------------------------------------- | | data.merchantProfileId | integer | Newly created merchant profile ID — required for all subsequent boarding API calls | | requestId | integer | Echo of the internal request ID | | success | boolean | `true` if the merchant record was created successfully | | error | string | Error message if `success` is `false` | | validationErrors | array | Field-level validation errors with `field` and `error` properties | ```json { "data": { "merchantProfileId": 30912 }, "requestId": 456, "success": true, "error": null, "validationErrors": [] } ``` ### Error Codes | Code | When it happens | | ---- | ----------------------------------------------------------------------------------------------------------------------------------- | | 400 | Required fields (`feesProgram`, `firstName`, `lastName`, `dba`, `pos`, `agentProfileId`) are missing or contain invalid enum values | | 401 | Invalid or missing Basic Auth credentials | | 403 | User does not have permission for this operation | | 404 | `agentProfileId` does not correspond to a valid agent profile | | 500 | Internal server error while creating the merchant record | ### Common Mistakes * Choosing a `feesProgram` that is not supported by the agent's boarding settings — confirm valid programs via the boarding settings endpoint first. * Sending a `pos` value not in the enum list — POS system names are case-sensitive and must match exactly. * Not capturing the returned `merchantProfileId` — every downstream V2 endpoint (update info, fees, submit) requires this ID. * Calling this endpoint multiple times for the same merchant accidentally creates duplicate merchant records with separate IDs. * Using `BoardingV1_CreateMerchant` (`POST /api/v1/merchant/create`) when integrating new workflows — V2 is preferred for new integrations. ### Related Endpoints * `GET /api/v2/agent/profile` — Retrieve agent profile details and valid `agentProfileId` * `POST /api/v2/merchant/submit` — Submit the complete merchant application after all sections are populated * `GET /api/v2/merchant/info` — Retrieve current merchant profile data after creation ### Example ```bash curl -X POST https://hq.staging.netevia.dev/api/v2/merchant/create \ -H "Authorization: Basic $(echo -n 'username:password' | base64)" \ -H "Content-Type: application/json" \ -d '{ "feesProgram": "CashDiscount", "firstName": "Sarah", "lastName": "Hernandez", "dba": "The Corner Bakery", "pos": "Clover", "agentProfileId": 204, "email": "sarah.hernandez@cornerbakery.com", "boardingSettingsId": 15 }' ``` # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "version": "v2", "title": "Netevia HQ | API Documentation", "description": "Netevia HQ | API Documentation" }, "paths": { "/api/v2/merchant/create": { "post": { "tags": [ "Submit Merchant Application" ], "operationId": "BoardingV2_CreateMerchant", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMerchantRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateMerchantRequest" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/CreateMerchantRequest" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/CreateMerchantRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CreateMerchantRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult1_SubmitMerchantResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiResult1_SubmitMerchantResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/ApiResult1_SubmitMerchantResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/ApiResult1_SubmitMerchantResponse" } }, "data": { "examples": { "response": { "value": { "merchantProfileId": 123 } } } }, "requestId": { "examples": { "response": { "value": 456 } } }, "success": { "examples": { "response": { "value": true } } } } } } } } }, "security": [ { "Basic": [] } ], "servers": [ { "url": "https://hq.staging.netevia.dev" } ], "components": { "securitySchemes": { "Basic": { "type": "http", "description": "Basic HTTP Authentication", "scheme": "basic" } }, "schemas": { "ValidationError": { "type": "object", "properties": { "field": { "type": "string" }, "error": { "type": "string" } } }, "ApiResult1_SubmitMerchantResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SubmitMerchantResponse" }, "requestId": { "format": "int32", "type": "integer" }, "success": { "type": "boolean" }, "error": { "type": "string" }, "validationErrors": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationError" } } } }, "SubmitMerchantResponse": { "type": "object", "properties": { "merchantProfileId": { "format": "int32", "type": "integer" } } }, "CreateMerchantRequest": { "required": [ "feesProgram", "firstName", "lastName", "dba", "pos", "agentProfileId" ], "type": "object", "properties": { "feesProgram": { "enum": [ "Traditional", "CashDiscount", "Surcharge", "ServiceFee", "DualPricing" ], "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "dba": { "type": "string" }, "pos": { "enum": [ "None", "AptitoPalomaPOS", "Clover", "PalomaPOS", "Aldelo", "Restoactive", "PoyntPOS", "CloverGo", "UnifiedMpos", "CustomPos", "RetailCloud", "EHopper", "FreedomPos", "ClubPos", "SelfLane", "OtfPOS", "NProKiosk", "GretaPOS" ], "type": "string" }, "agentProfileId": { "format": "int32", "type": "integer" }, "email": { "type": "string" }, "guid": { "type": "string" }, "boardingSettingsId": { "format": "int32", "type": "integer" } } } } } } ```