/api/v2/merchant/create

Time	Status	User Agent
Retrieving recent requests…

Time

Status

User Agent

Retrieving recent requests…

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

{
  "feesProgram": "CashDiscount",
  "firstName": "Sarah",
  "lastName": "Hernandez",
  "dba": "The Corner Bakery",
  "pos": "Clover",
  "agentProfileId": 204,
  "email": "[email protected]",
  "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

{
  "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

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": "[email protected]",
    "boardingSettingsId": 15
  }'