Skip to content
/Refunds

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

Create refund

Request

Refund a charge (full or partial)

Security
oAuth2
Headers
Idempotency-Keystring

A unique key to make POST requests idempotent.

Bodyapplication/jsonrequired
chargeIdstringrequired
amountnumber or null

Partial refund amount (full refund if omitted)

reasonstring(RefundReason)
Enum"duplicate""fraudulent""requested_by_customer""other"
curl -i -X POST \
  https://developer.kaito.io/_mock/merchant/v1/refunds \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: string' \
  -d '{
    "chargeId": "string",
    "amount": 0,
    "reason": "duplicate"
  }'

Responses

Refund created

Headers
X-Trace-Idstring(TraceId)

Correlation id for troubleshooting

Example: "trc_01JH8K5P3V9M2K5Q7W6J3Z1A9B"
Bodyapplication/json
refundIdstringrequired
Example: "rfd_01JH..."
chargeIdstringrequired
amountnumberrequired
currencystring
statusstring(RefundStatus)required
Enum"pending""succeeded""failed"
reasonstring(RefundReason)
Enum"duplicate""fraudulent""requested_by_customer""other"
createdAtstring(date-time)required
Response
application/json
{
  "refundId": "rfd_01JH...",
  "chargeId": "string",
  "amount": 0,
  "currency": "string",
  "status": "pending",
  "reason": "duplicate",
  "createdAt": "2019-08-24T14:15:22Z"
}

List refunds

Request

Security
oAuth2
Query
chargeIdstring
statusstring(RefundStatus)
Enum"pending""succeeded""failed"
limitinteger
Default 50
cursorstring
curl -i -X GET \
  'https://developer.kaito.io/_mock/merchant/v1/refunds?chargeId=string&status=pending&limit=50&cursor=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Refunds list

Headers
X-Trace-Idstring(TraceId)

Correlation id for troubleshooting

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

Merchants

Manage merchant accounts

Operations

Settlements

View settlement history

Operations

Balances

View account balances

Operations

Reconciliation

Download reconciliation reports

Operations

Fees

View fee breakdown

Operations