# Kaito Merchant API

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.


Version: 2.0.0
License: Apache 2.0

## Servers

Production
```
https://api.kai2.io
```

Sandbox
```
https://sandbox.api.kai2.io
```

## Security

### oAuth2

OAuth2 client credentials. All requests must also be made over mTLS.

Type: oauth2

## Download OpenAPI description

[Kaito Merchant API](https://developer.kai2.io/_bundle/merchant.yaml)

## Charges

Create and manage payment charges

### Create merchant charge

 - [POST /v1/charges](https://developer.kai2.io/merchant/charges/paths/~1v1~1charges/post.md): 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

### List charges

 - [GET /v1/charges](https://developer.kai2.io/merchant/charges/paths/~1v1~1charges/get.md)

### Get charge

 - [GET /v1/charges/{chargeId}](https://developer.kai2.io/merchant/charges/paths/~1v1~1charges~1%7Bchargeid%7D/get.md)

### Cancel charge

 - [DELETE /v1/charges/{chargeId}](https://developer.kai2.io/merchant/charges/paths/~1v1~1charges~1%7Bchargeid%7D/delete.md): Cancel a pending charge. Only works if status is requires_payment.

## Refunds

Process refunds

### Create refund

 - [POST /v1/refunds](https://developer.kai2.io/merchant/refunds/paths/~1v1~1refunds/post.md): Refund a charge (full or partial)

### List refunds

 - [GET /v1/refunds](https://developer.kai2.io/merchant/refunds/paths/~1v1~1refunds/get.md)

## Merchants

Manage merchant accounts

### Create merchant

 - [POST /v1/merchants](https://developer.kai2.io/merchant/merchants/paths/~1v1~1merchants/post.md)

### List merchants

 - [GET /v1/merchants](https://developer.kai2.io/merchant/merchants/paths/~1v1~1merchants/get.md)

### Get merchant

 - [GET /v1/merchants/{merchantId}](https://developer.kai2.io/merchant/merchants/paths/~1v1~1merchants~1%7Bmerchantid%7D/get.md)

## Settlements

View settlement history

### List settlements

 - [GET /v1/settlements](https://developer.kai2.io/merchant/settlements/paths/~1v1~1settlements/get.md)

### Get settlement by ID

 - [GET /v1/settlements/{settlementId}](https://developer.kai2.io/merchant/settlements/paths/~1v1~1settlements~1%7Bsettlementid%7D/get.md)

## Balances

View account balances

### Get balance accounts

 - [GET /v1/balances](https://developer.kai2.io/merchant/balances/paths/~1v1~1balances/get.md)

## Reconciliation

Download reconciliation reports

### Download reconciliation report

 - [GET /v1/reconciliation](https://developer.kai2.io/merchant/reconciliation/paths/~1v1~1reconciliation/get.md)

## Fees

View fee breakdown

### Get fee summary

 - [GET /v1/fees](https://developer.kai2.io/merchant/fees/paths/~1v1~1fees/get.md)