Skip to content
/Charges

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

Create merchant charge

Request

Creates a charge for in-person payment acceptance.

Payment methods:

  • nfc: Returns NFC payload for Tap-to-Pay
  • qr: Returns QR code data and image URL
  • alias: Resolves alias and creates charge
Security
oAuth2
Headers
Idempotency-Keystring

A unique key to make POST requests idempotent.

Bodyapplication/jsonrequired
merchantIdstringrequired
Example: "mrc_01JH..."
amountnumberrequired
Example: 150
currencystringrequired
Example: "GTQ"
paymentMethodstring(PaymentMethodType)required
  • nfc: Tap-to-Pay via NFC
  • qr: QR code payment
  • alias: Alias/handle resolution
  • card_present: Card present (chip/swipe)
Enum"nfc""qr""alias""card_present"
descriptionstring or null
Example: "Purchase at Store #123"
referencestring or null

External reference (POS transaction ID, order number)

expiresIninteger or null

Expiration time in seconds (default 300 for QR)

Example: 300
metadataobject or null
curl -i -X POST \
  https://developer.kaito.io/_mock/merchant/v1/charges \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: string' \
  -d '{
    "merchantId": "mrc_01JH...",
    "amount": 150,
    "currency": "GTQ",
    "paymentMethod": "nfc",
    "description": "Purchase at Store #123",
    "reference": "string",
    "expiresIn": 300,
    "metadata": {}
  }'

Responses

Charge created

Headers
X-Trace-Idstring(TraceId)

Correlation id for troubleshooting

Example: "trc_01JH8K5P3V9M2K5Q7W6J3Z1A9B"
Bodyapplication/json
chargeIdstringrequired
Example: "chg_01JH..."
merchantIdstringrequired
amountnumberrequired
currencystringrequired
statusstring(ChargeStatus)required
Enum"requires_payment""processing""succeeded""failed""cancelled""refunded"
paymentMethodstring(PaymentMethodType)required
  • nfc: Tap-to-Pay via NFC
  • qr: QR code payment
  • alias: Alias/handle resolution
  • card_present: Card present (chip/swipe)
Enum"nfc""qr""alias""card_present"
descriptionstring or null
referencestring or null
qrobject(QrData)
payerobject(PayerInfo)
txHashstring or null
providerRefstring or null
createdAtstring(date-time)required
paidAtstring or null(date-time)
Response
application/json
{
  "chargeId": "chg_01JH...",
  "merchantId": "string",
  "amount": 0,
  "currency": "string",
  "status": "requires_payment",
  "paymentMethod": "nfc",
  "description": "string",
  "reference": "string",
  "qr": {
    "data": "string",
    "imageUrl": "http://example.com",
    "expiresAt": "2019-08-24T14:15:22Z"
  },
  "payer": {
    "walletId": "string",
    "displayName": "string"
  },
  "txHash": "string",
  "providerRef": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "paidAt": "2019-08-24T14:15:22Z"
}

List charges

Request

Security
oAuth2
Query
merchantIdstring
statusstring(ChargeStatus)
Enum"requires_payment""processing""succeeded""failed""cancelled""refunded"
createdAfterstring(date-time)
createdBeforestring(date-time)
limitinteger
Default 50
cursorstring
curl -i -X GET \
  'https://developer.kaito.io/_mock/merchant/v1/charges?merchantId=string&status=requires_payment&createdAfter=2019-08-24T14%3A15%3A22Z&createdBefore=2019-08-24T14%3A15%3A22Z&limit=50&cursor=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Charges list

Headers
X-Trace-Idstring(TraceId)

Correlation id for troubleshooting

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

Get charge

Request

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

Responses

Charge details

Headers
X-Trace-Idstring(TraceId)

Correlation id for troubleshooting

Example: "trc_01JH8K5P3V9M2K5Q7W6J3Z1A9B"
Bodyapplication/json
chargeIdstringrequired
Example: "chg_01JH..."
merchantIdstringrequired
amountnumberrequired
currencystringrequired
statusstring(ChargeStatus)required
Enum"requires_payment""processing""succeeded""failed""cancelled""refunded"
paymentMethodstring(PaymentMethodType)required
  • nfc: Tap-to-Pay via NFC
  • qr: QR code payment
  • alias: Alias/handle resolution
  • card_present: Card present (chip/swipe)
Enum"nfc""qr""alias""card_present"
descriptionstring or null
referencestring or null
qrobject(QrData)
payerobject(PayerInfo)
txHashstring or null
providerRefstring or null
createdAtstring(date-time)required
paidAtstring or null(date-time)
Response
application/json
{
  "chargeId": "chg_01JH...",
  "merchantId": "string",
  "amount": 0,
  "currency": "string",
  "status": "requires_payment",
  "paymentMethod": "nfc",
  "description": "string",
  "reference": "string",
  "qr": {
    "data": "string",
    "imageUrl": "http://example.com",
    "expiresAt": "2019-08-24T14:15:22Z"
  },
  "payer": {
    "walletId": "string",
    "displayName": "string"
  },
  "txHash": "string",
  "providerRef": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "paidAt": "2019-08-24T14:15:22Z"
}

Refunds

Process refunds

Operations

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