Setting up the Merchant via API
Create a merchant account, identify its processor configuration, board a terminal, link a location, issue merchant SDK login credentials, and create the app key. Use a backend API key with the permissions and account hierarchy access required by each endpoint.
Use https://api.uat.koard.com and UAT processor credentials for testing. Production uses https://api.koard.com with separate keys and assigned merchant identifiers. Example values are placeholders, not certification credentials.
Before You Start
Use this walkthrough for backend provisioning. For manual setup, choose dashboard merchant setup instead. If the merchant, terminal, location, and credentials already exist, continue to Next Step.
If you need your first backend API key, create it using the dashboard key workflow, then continue at step 1 here. Keep that key on your server; the app uses its own separate key.
1. Create the Merchant Account
Use the merchant request variant. tax_id and mcc are required for merchants and must be omitted when creating a partner. See Creating Merchant and Partner Accounts for the differences and parent-account rules.
curl -X POST 'https://api.uat.koard.com/v2/accounts' \
-H 'X-Koard-apikey: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"type": "merchant",
"name": "Example Coffee",
"description": "Retail coffee shop",
"address": {
"street_line1": "123 Main Street",
"city": "New York",
"state": "NY",
"zip": "10016",
"country": "USA"
},
"tax_id": "12-3456789",
"mcc": "5812"
}'
The response is 201 Created. Store the returned account id as YOUR_MERCHANT_ACCOUNT_ID. Merchant creation requires type, name, tax_id, mcc, and a US address with city, state, and zip. description is optional.
The new merchant can use the processor configurations available to your account. To limit a merchant to specific configurations, see available_processor_configs in Creating Merchant and Partner Accounts.
Account creation does not automatically issue a REST API key. If the merchant needs one, create it separately through API Key Management with the required permissions. An API key and merchant SDK login credentials are different credentials.
2. Identify the Processor Configuration
A terminal is boarded against one processor configuration, so find its ID before you board the terminal. List the configurations available to your account:
curl 'https://api.uat.koard.com/v1/processor-configs' \
-H 'X-Koard-apikey: YOUR_API_KEY'
Choose the configuration for the merchant's processor in this environment and store its id. You send it as processor_config_id in step 3. If the configuration you need is not in the response, contact support@koard.com. Available Processor Configurations explains the response and how access is assigned.
3. Board the Terminal
Each processor has its own request format. Open the boarding guide for the configuration you chose in step 2 and send the fields it lists. A configuration ID for one processor cannot be combined with another processor's VAR sheet.
| Processor configuration | Boarding guide |
|---|---|
| TSYS Sierra, Netevia | TSYS Sierra |
| Fiserv | Overview, Nashville, Nashville North (Global), Omaha |
| Worldpay | Worldpay |
| Elavon | Elavon |
| Payroc | Payroc |
The request below boards a TSYS terminal. Replace the processor configuration ID and all VAR-sheet identifiers with assigned values; retain leading zeros.
curl -X POST 'https://api.uat.koard.com/v2/terminals' \
-H 'X-Koard-apikey: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '
{
"account_id": "YOUR_MERCHANT_ACCOUNT_ID",
"processor_config_id": "YOUR_TSYS_PROCESSOR_CONFIG_ID",
"name": "Front Counter POS",
"var_sheet": {
"acquirer_bin": "123456",
"merchant_number": "123456789012",
"store_number": "0001",
"terminal_number": "0002",
"merchant_category_code": "5812",
"merchant_name": "Example Coffee",
"merchant_location": "New York",
"merchant_state": "NY",
"city_code": "10016",
"acceptor_street_address": "123 Main Street",
"industry_code": "R",
"acceptor_phone": "2125550100",
"acceptor_customer_service_phone": "2125550101",
"currency_code": "840",
"country_code": "USA",
"language_indicator": "00",
"time_zone_diff": "705"
}
}
'
The response is 201 Created and contains the boarded terminal. Store its terminal_id. Use name, not terminal_name, in the request. A boarded terminal is distinct from an Apple reader terminal profile.
4. Create or Update the Location
curl -X POST 'https://api.uat.koard.com/v1/locations' \
-H 'X-Koard-apikey: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"account_id": "YOUR_MERCHANT_ACCOUNT_ID",
"name": "Main Store",
"terminal_id": "YOUR_RETURNED_TERMINAL_ID",
"processor_config_id": "YOUR_TSYS_PROCESSOR_CONFIG_ID",
"address": {
"street_line1": "123 Main Street",
"city": "New York",
"state": "NY",
"zip": "10016",
"country": "USA"
}
}'
Store the returned location id. For an existing location, use PUT /v1/locations/{location_id} and send only changed fields, such as terminal_id. Keep the location and terminal on the same merchant account and use the intended processor configuration.
5. Issue Merchant SDK Credentials
curl -X POST 'https://api.uat.koard.com/v1/accounts/credentials' \
-H 'X-Koard-apikey: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"account_id": "YOUR_MERCHANT_ACCOUNT_ID"}'
The response is 201 Created. It contains code and a plaintext pin. Deliver them through a trusted channel. The plaintext PIN is returned on creation only; subsequent credential reads return metadata and the code, not the PIN.
- List active credentials:
GET /v1/accounts/{account_id}/credentials. - Read one credential:
GET /v1/accounts/credentials/{credential_id}.
6. Create the App Key
Your app initializes the Koard SDK with its own API key, separate from the backend key used in the steps above. Create it in UAT with the tap permission for the app's platform: payments:tap-ios or payments:tap-android. Getting an API Key walks through it.
7. Verify Merchant Setup
| Ready item | Verify before leaving this guide |
|---|---|
| Merchant account ID | Saved from step 1. |
| Processor configuration ID | Chosen in step 2 for this processor and environment. |
| Terminal ID | Saved from step 3 and owned by this merchant. |
| Location ID | Saved from step 4, on this merchant, linked to the intended terminal. |
| Merchant code and PIN | Saved from step 5 through a trusted channel. |
| App key | Created in step 6 in UAT, with the tap permission for the app's platform. |
Your app must provide an active-location selector in settings. After merchant login, load that merchant's locations and pass the operator's selected location_id to the SDK. The location's linked terminal determines payment routing. A terminal ID cannot replace a location ID, and another merchant's saved selection must be cleared.
Continue with the platform quickstart for login, location selection, account linking or enrollment, and reader readiness. Provisioning is complete; reuse the records from steps 1 through 6.
Next Step
Continue at step 2 of the iOS Quickstart or Android Quickstart.

