Skip to content
/Merchants

Kaito Merchant API (2.0.0)

Merchant services including payment acceptance, settlements, and financial reporting.

Payment Acceptance: In-person payment acceptance supporting nfc (Tap-to-Pay), qr (QR code), alias (handle resolution), and card_present (chip/swipe).

Charge Flow: Create merchant -> Create charge -> Display QR/NFC -> Confirm via polling or webhook.

Refunds: Full or partial refunds via /refunds.

Banking & Settlements: View settlement history via /settlements, account balances via /balances, and download reconciliation reports in CSV, XLSX, or JSON format. Query /fees for fee breakdown.

Download OpenAPI description
merchant.json
merchant.yaml
Overview
URL
https://developer.kai2.io/support
Kaito Developer Support
support@kai2.io
License
Apache 2.0
Terms of Service
Languages
Servers
Mock server
https://developer.kaito.io/_mock/merchant/
Production
https://api.kai2.io/
Sandbox
https://sandbox.api.kai2.io/

Charges

Create and manage payment charges

Operations

Refunds

Process refunds

Operations

Merchants

Manage merchant accounts

Operations

Create merchant

Request

Security
oAuth2
Headers
Idempotency-Keystring

A unique key to make POST requests idempotent.

Bodyapplication/jsonrequired
namestringrequired
Example: "Coffee Shop"
countrystringrequired
Example: "GT"
mccstringrequired

Merchant Category Code

Example: "5812"
addressobject(Address)
metadataobject
curl -i -X POST \
  https://developer.kaito.io/_mock/merchant/v1/merchants \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: string' \
  -d '{
    "name": "Coffee Shop",
    "country": "GT",
    "mcc": "5812",
    "address": {
      "line1": "string",
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string"
    },
    "metadata": {}
  }'

Responses

Merchant created

Headers
X-Trace-Idstring(TraceId)

Correlation id for troubleshooting

Example: "trc_01JH8K5P3V9M2K5Q7W6J3Z1A9B"
Bodyapplication/json
merchantIdstringrequired
Example: "mrc_01JH..."
namestringrequired
countrystringrequired
mccstringrequired
statusstring(MerchantStatus)required
Enum"active""suspended""pending_review"
addressobject(Address)
createdAtstring(date-time)required
Response
application/json
{
  "merchantId": "mrc_01JH...",
  "name": "string",
  "country": "string",
  "mcc": "string",
  "status": "active",
  "address": {
    "line1": "string",
    "city": "string",
    "state": "string",
    "postalCode": "string",
    "country": "string"
  },
  "createdAt": "2019-08-24T14:15:22Z"
}

List merchants

Request

Security
oAuth2
Query
statusstring(MerchantStatus)
Enum"active""suspended""pending_review"
limitinteger
Default 50
cursorstring
curl -i -X GET \
  'https://developer.kaito.io/_mock/merchant/v1/merchants?status=active&limit=50&cursor=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Merchants list

Headers
X-Trace-Idstring(TraceId)

Correlation id for troubleshooting

Example: "trc_01JH8K5P3V9M2K5Q7W6J3Z1A9B"
Bodyapplication/json
itemsArray of objects(Merchant)
paginationobject(Pagination)
Response
application/json
{
  "items": [
    { … }
  ],
  "pagination": {
    "nextCursor": "cursor_abc123"
  }
}

Get merchant

Request

Security
oAuth2
Path
merchantIdstringrequired
curl -i -X GET \
  'https://developer.kaito.io/_mock/merchant/v1/merchants/{merchantId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Merchant details

Headers
X-Trace-Idstring(TraceId)

Correlation id for troubleshooting

Example: "trc_01JH8K5P3V9M2K5Q7W6J3Z1A9B"
Bodyapplication/json
merchantIdstringrequired
Example: "mrc_01JH..."
namestringrequired
countrystringrequired
mccstringrequired
statusstring(MerchantStatus)required
Enum"active""suspended""pending_review"
addressobject(Address)
createdAtstring(date-time)required
Response
application/json
{
  "merchantId": "mrc_01JH...",
  "name": "string",
  "country": "string",
  "mcc": "string",
  "status": "active",
  "address": {
    "line1": "string",
    "city": "string",
    "state": "string",
    "postalCode": "string",
    "country": "string"
  },
  "createdAt": "2019-08-24T14:15:22Z"
}

Settlements

View settlement history

Operations

Balances

View account balances

Operations

Reconciliation

Download reconciliation reports

Operations

Fees

View fee breakdown

Operations