Setting up the Merchant via API
Automate merchant onboarding with Koard's REST API. This guide walks through creating the merchant account, provisioning a terminal, associating it with a location, and issuing SDK credentials without using the Merchant Management System UI.
Prerequisites
- Koard API key with permission to manage merchant accounts
- Processor configuration IDs that the merchant should use
- Location identifiers (either newly created via API or existing records) linked to the merchant
- Dedicated test device enrolled in the appropriate Apple sandbox for Tap to Pay validation
For each request, send Authorization: Bearer {API_KEY} and specify the target environment (https://api.uat.koard.com for sandbox or https://api.koard.com for production).
Create the merchant account
Use POST /v2/accounts to create the merchant record tied to your processor configuration. The payload must include the account type, name, description, and an address object.
Request
curl https://api.uat.koard.com/v2/accounts
-H "Authorization: Bearer $KOARD_API_KEY"
-H "Content-Type: application/json"
-d '{
"type": "merchant",
"name": "Bluebird Coffee Roasters",
"description": "Retail coffee shop using Tap to Pay on iPhone",
"address": {
"street_line1": "123 Market Street",
"city": "San Francisco",
"state": "CA",
"zip": "94105"
},
"tax_id": "12-3456789",
"mcc": "5812",
"available_processor_configs": ["prc_live_payroc_us"]
}'
200 Response
{
"id": "100200300001",
"type": "merchant",
"name": "Bluebird Coffee Roasters",
"description": "Retail coffee shop using Tap to Pay on iPhone",
"status": "active",
"tax_id": "12-3456789",
"mcc": "5812",
"address": {
"street_line1": "123 Market Street",
"city": "San Francisco",
"state": "CA",
"zip": "94105"
},
"available_processor_configs": ["prc_live_payroc_us"],
"created_at": "2024-10-15T18:21:04.123Z"
}
Store the returned id—you will use it when you create the terminal and credentials. In the examples that follow we will reference the ID 100200300001.
Create a terminal profile
Provision a terminal with POST /v2/terminals. Provide the merchant's processor details using the processor-specific VAR sheet format.
Request
curl https://api.uat.koard.com/v2/terminals
-X POST
-H "Authorization: Bearer $KOARD_API_KEY"
-H "Content-Type: application/json"
-d '{
"account_id": "100200300001",
"processor_config_id": "prc_live_payroc_us",
"terminal_name": "Front Counter iPhone",
"var_sheet": {
"acquirerBin": "123456",
"merchantNumber": "123456789012",
"storeNumber": "0001",
"terminalNumber": "0001",
"merchantCategoryCode": "5812",
"merchantName": "Bluebird Coffee Roasters",
"merchantLocation": "San Francisco",
"merchantState": "CA",
"cityCode": "94105",
"acceptorStreetAddress": "123 Market Street",
"industryCode": "R",
"acceptorPhone": "4155551234",
"acceptorCustomerServicePhone": "4155551234"
}
}'
201 Response
{
"terminal_id": "500600700001",
"name": "Front Counter iPhone",
"account_id": "100200300001",
"mid": "123456789012",
"tid": "0001",
"processor_config_id": "prc_live_payroc_us",
"status": "active",
"created_at": "2024-10-15T18:21:05.015Z",
"var_sheet": {
"acquirerBin": "123456",
"merchantNumber": "123456789012",
"storeNumber": "0001",
"terminalNumber": "0001",
"merchantCategoryCode": "5812",
"merchantName": "Bluebird Coffee Roasters",
"merchantLocation": "San Francisco",
"merchantState": "CA",
"cityCode": "94105",
"acceptorStreetAddress": "123 Market Street",
"industryCode": "R",
"acceptorPhone": "4155551234",
"acceptorCustomerServicePhone": "4155551234"
}
}
The response contains the terminal configuration with an auto-generated terminal_id. See the API reference for the full TSYSVarSheet schema with all required and optional fields.
Assign the terminal to a merchant location
Update an existing location with PUT /v1/locations/{location_id} so that the location references the new terminal ID. Include any additional fields you need to change (for example, contact info or status).
Request
curl https://api.uat.koard.com/v1/locations/300400500001
-X PUT
-H "Authorization: Bearer $KOARD_API_KEY"
-H "Content-Type: application/json"
-d '{
"name": "Bluebird Coffee HQ",
"terminal_id": "500600700001",
"processor_config_id": "prc_live_payroc_us",
"status": "active"
}'
200 Response
{
"id": "300400500001",
"name": "Bluebird Coffee HQ",
"account_id": "100200300001",
"terminal_id": "500600700001",
"processor_config_id": "prc_live_payroc_us",
"status": "active",
"updated_at": "2024-10-15T18:21:06.287Z"
}
If you do not yet have a location record, create one first with POST /v1/locations, then repeat this update call to attach the terminal.
Issue merchant SDK credentials
Generate the merchant's SDK login credentials using POST /v1/accounts/credentials. You may supply a custom code and pin, or let Koard create randomized values by omitting them.
Request
curl https://api.uat.koard.com/v1/accounts/credentials
-X POST
-H "Authorization: Bearer $KOARD_API_KEY"
-H "Content-Type: application/json"
-d '{
"account_id": "100200300001"
}'
200 Response
{
"id": "900100200003",
"account_id": "100200300001",
"code": "483920123456",
"pin": "739051",
"is_active": true,
"created_at": "2024-10-15T18:21:07.431Z"
}
The response returns the code and pin only once. Store them securely and deliver them to your merchant through a trusted channel so they can authenticate with the Koard SDK.
Next steps
- Verify the credentials by logging into the Koard iOS SDK test harness.
- Run a test payment in the UAT environment to confirm the terminal and location configuration.
- When ready for production, repeat the flow against
https://api.koard.comwith live processor credentials.
