DocsAPI Reference

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 /v1/terminals/{terminal_id}. Choose a unique terminal identifier (for example, 500600700001) and provide the merchant's processor details.

Request 

curl https://api.uat.koard.com/v1/terminals/500600700001 

-X POST 

-H "Authorization: Bearer $KOARD_API_KEY" 

-H "Content-Type: application/json" 

-d '{
"name": "Front Counter iPhone",
"account_id": "100200300001",
"mid": "1234567890",
"tid": "00012345",
"processor_config_id": "prc_live_payroc_us",
"terminal_capability": "5",
"country_code": "US",
"currency_code": "840"
}'

200 Response 

{
"terminal_id": "500600700001",
"name": "Front Counter iPhone",
"account_id": "100200300001",
"mid": "1234567890",
"tid": "00012345",
"processor_config_id": "prc_live_payroc_us",
"terminal_capability": "5",
"country_code": "US",
"currency_code": "840",
"status": "active",
"created_at": "2024-10-15T18:21:05.015Z"
}

The response contains the terminal configuration, including the canonical terminal_id field used when binding the terminal to a location (500600700001 in this example).

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.com with live processor credentials.
/v2/accounts:
  post:
    summary: Create Account
    description: Create a new account with optional MMS setup (Clerk org, SVIX, API key)
    requestBody:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/AccountCreateRequestV2"

AccountCreateRequestV2:
  properties:
    type:
      $ref: "#/components/schemas/AccountType"
    name:
      type: string
    description:
      type: string
    address:
      $ref: "#/components/schemas/Address"
    tax_id:
      title: Tax Id
    mcc:
      title: Mcc
  type: object
  required:
    - type
    - name
    - description
    - address

/v1/terminals/{terminal_id}:
  post:
    summary: Create Terminal
    description: Create a new terminal configuration.
    requestBody:
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/TerminalConfigCreate"

TerminalConfigCreate:
  properties:
    name:
      type: string
    account_id:
      type: string
    mid:
      type: string
    tid:
      type: string
    processor_config_id:
      type: string
  required:
    - name
    - account_id
    - mid
    - tid
    - processor_config_id

/v1/locations/{location_id}:
  put:
    summary: Update Location
    requestBody:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/LocationUpdate"

LocationUpdate:
  properties:
    terminal_id:
      title: Terminal Id
      type:
        - string
        - "null"
    processor_config_id:
      title: Processor Config Id
      type:
        - string
        - "null"
    status:
      title: Status
  title: LocationUpdate

"/v1/accounts/credentials":
  post:
    summary: Create Account Credential
    description: |
      Create a new account credential. If no data is provided, a random code and PIN will be generated.
    requestBody:
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/CredentialCreateWithAccount"

CredentialCreateWithAccount:
  properties:
    code:
      maxLength: 12
      minLength: 12
    pin:
      maxLength: 6
      minLength: 6
    account_id:
      title: Account Id
  description: Extended model with account_id for creating credentials