Account Hierarchy and Credentials
Choose the merchant that owns the payment before creating its terminals, locations, or SDK credentials. See Creating Merchant and Partner Accounts for the request variants and required fields.
Accounts and Ownership
| Account | Purpose |
|---|---|
| PSP | An existing service-provider account can manage the customer operations available to its hierarchy and permissions. |
| Partner | Organizes descendant partners and merchants. It does not use merchant tax, MCC, surcharge, or tax-default fields. |
| Merchant | The business accepting payments. Its terminals, locations, credentials, and transactions belong to this account. Merchant accounts cannot create child accounts. |
A provider or partner integration creates partner and merchant accounts with POST /v2/accounts. If parent_id is omitted, the authenticated account is the parent. An explicit parent must be an accessible account that can have children.
For example, a software partner can have separate Coffee Shop and Restaurant merchant accounts, each with its own locations and processor credentials. Authenticate the intended merchant before loading locations; a parent's access to descendants is not an active payment-location selection.
Merchant vs. Partner Creation
Merchant creation requires a name, tax ID, MCC, and US address with city, state, and ZIP. Partner creation requires its type and name; omit merchant tax/MCC and payment-default fields. Use the separate request variants in the Accounts API reference.
Processor access must be inherited or assigned from the parent's available configurations in the same environment. An empty configuration list does not mean “no processor access.” Follow the account creation guide for the full rules.
Three Different Credentials
| Credential | Used by | Purpose |
|---|---|---|
| Backend REST API key | Your server | Authorized provisioning, management, reporting, and recovery operations through X-Koard-apikey. |
| Scoped SDK client key | Your mobile app | SDK initialization for the intended platform and environment. Use the key assigned for the app, with its intended permissions. |
| Merchant code/PIN or issued alias | SDK merchant login | Establishes the merchant session used for checkout and location selection. |
Do not ship a privileged backend key in the mobile app. An SDK client key does not replace merchant login, and merchant login credentials do not authenticate backend provisioning requests.
Account creation does not automatically create these credentials. Use API Key Management when issuing REST keys, and the merchant credential step for SDK login credentials. Save a newly generated key and PIN through a trusted channel when they are returned; do not assume they can be retrieved later.
Access and Environment
An API key's account hierarchy and explicit permissions determine which operations it can perform. A write permission does not imply read access. Your backend must enforce its own user-to-merchant authorization before using its key for a customer request. See Authentication.
UAT and production have separate keys and configuration. Retain the environment with every stored account, location, terminal, and operation ID.
Next Steps
- Create the merchant or partner.
- Board the terminal and link a location.
- Run the iOS or Android quickstart.
