Skip to content
/Settlements

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

Settlements

View settlement history

Operations

List settlements

Request

Security
oAuth2
Query
fromstring(date)
tostring(date)
statusstring(SettlementStatus)
Enum"pending""processing""completed""failed"
currencystring
limitinteger
Default 50
cursorstring
curl -i -X GET \
  'https://developer.kaito.io/_mock/merchant/v1/settlements?from=2019-08-24&to=2019-08-24&status=pending&currency=string&limit=50&cursor=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Settlements list

Headers
X-Trace-Idstring(TraceId)

Correlation id for troubleshooting

Example: "trc_01JH8K5P3V9M2K5Q7W6J3Z1A9B"
Bodyapplication/json
itemsArray of objects(Settlement)required
items[].​settlementIdstringrequired
Example: "stl_01JH..."
items[].​datestring(date)required
items[].​currencystringrequired
Example: "USD"
items[].​grossnumberrequired

Total amount before fees

Example: 10000
items[].​feesnumberrequired

Total fees deducted

Example: 150
items[].​netnumberrequired

Amount settled (gross - fees)

Example: 9850
items[].​statusstring(SettlementStatus)required
Enum"pending""processing""completed""failed"
items[].​transactionCountinteger

Number of transactions included

Example: 250
items[].​bankAccountobject(BankAccountInfo)
items[].​settledAtstring or null(date-time)
items[].​createdAtstring(date-time)
paginationobject(Pagination)
summaryobject(SettlementSummary)
Response
application/json
{
  "items": [
    { … }
  ],
  "pagination": {
    "nextCursor": "cursor_abc123"
  },
  "summary": {
    "totalGross": 0,
    "totalFees": 0,
    "totalNet": 0,
    "count": 0
  }
}

Get settlement by ID

Request

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

Responses

Settlement details

Headers
X-Trace-Idstring(TraceId)

Correlation id for troubleshooting

Example: "trc_01JH8K5P3V9M2K5Q7W6J3Z1A9B"
Bodyapplication/json
settlementIdstringrequired
Example: "stl_01JH..."
datestring(date)required
currencystringrequired
Example: "USD"
grossnumberrequired

Total amount before fees

Example: 10000
feesnumberrequired

Total fees deducted

Example: 150
netnumberrequired

Amount settled (gross - fees)

Example: 9850
statusstring(SettlementStatus)required
Enum"pending""processing""completed""failed"
transactionCountinteger

Number of transactions included

Example: 250
bankAccountobject(BankAccountInfo)
settledAtstring or null(date-time)
createdAtstring(date-time)
Response
application/json
{
  "settlementId": "stl_01JH...",
  "date": "2019-08-24",
  "currency": "USD",
  "gross": 10000,
  "fees": 150,
  "net": 9850,
  "status": "pending",
  "transactionCount": 250,
  "bankAccount": {
    "last4": "1234",
    "bankName": "Bank of America"
  },
  "settledAt": "2019-08-24T14:15:22Z",
  "createdAt": "2019-08-24T14:15:22Z"
}

Balances

View account balances

Operations

Reconciliation

Download reconciliation reports

Operations

Fees

View fee breakdown

Operations