Creating Merchant and Partner Accounts

Use POST /v2/accounts to create a merchant or partner under your account hierarchy. Your authenticated account must be a PSP or partner with access to the intended parent. A merchant account cannot create child accounts.

Choose the matching request variant in the Accounts API reference. Account creation returns 201 Created and the new account's id. Issue a REST API key separately when needed through API Key Management.

Field	Merchant creation	Partner creation
`type`	`merchant`	`partner`
`name`	Required business name	Required partner name
`description`	Optional	Optional
`tax_id`	Required merchant tax ID	Omit
`mcc`	Required four-digit merchant category code	Omit
`address`	Required US business address with `city`, `state`, and `zip`	Optional
`surcharge_rate`, `surcharge_basis`, `surcharge_confirmation_required`	Optional merchant defaults	Omit
`tax_rate`, `tax_basis`	Optional merchant defaults	Omit
`parent_id`	Optional accessible parent account	Optional accessible parent account
`available_processor_configs`	Optional assigned configuration IDs	Optional assigned configuration IDs

When parent_id is omitted, the caller's account becomes the parent. An explicit parent must be your account or an accessible descendant and must be able to have children. Merchant accounts cannot be parents.

Omitting available_processor_configs inherits the parent's configuration access. Supply assigned IDs from the same environment when narrowing access; do not use an empty list to mean “no processor access.”

Create a Merchant

Send this JSON body to POST /v2/accounts with your backend API key:

{
  "type": "merchant",
  "name": "Example Coffee",
  "tax_id": "12-3456789",
  "mcc": "5812",
  "address": {
    "street_line1": "123 Main Street",
    "city": "New York",
    "state": "NY",
    "zip": "10016",
    "country": "USA"
  }
}

The merchant tax ID, MCC, and address requirements apply in addition to the shared request's type and name. A missing or empty tax ID, missing MCC, or incomplete merchant address is rejected. The country defaults to the US when omitted; boarding is currently US only. Merchant defaults configure this merchant's payment behavior and do not configure its parent.

Continue with Setting up the Merchant via API to board a terminal, associate a location, and issue SDK credentials.

Create a Partner

Send this JSON body to the same endpoint:

{
  "type": "partner",
  "name": "Example Software Partner",
  "description": "Manages descendant merchant accounts"
}

A partner organizes descendant accounts. Omit tax_id, mcc, surcharge settings, and tax-default fields. These fields describe a merchant's payment configuration. Create each merchant as its own account under the partner and board terminals for that merchant.

Setting up the Merchant via API

Available Processor Configurations