<!-- Generated from https://kantopay.com/documents by tools/gen-llms-full.js. Do not edit by hand. -->

# KantoPay API

Accept payments and deliver in-game rewards.

- [Build a storefront](https://kantopay.com/documents#storefront) — Browse products and create checkouts using a public storefront token.

- [Connect your game server](https://kantopay.com/documents#reference) — Manage payments and deliver rewards using a secret API key.

- [Set up webhooks](https://kantopay.com/documents#webhooks) — Receive payment events on your server.

Not sure which you need? [Compare the two APIs](https://kantopay.com/documents#compare).

## FAQ

**Do you support subscriptions?**
Not yet. Subscriptions are coming; for now every purchase is a one-time payment.

**Can a paid order be reversed?**
Yes. KantoPay can refund it (a store asks KantoPay support; stores can’t refund from the dashboard or the API), and a buyer can win a chargeback. The order’s `reversal_type` says which, and [`/rewards/revocations`](https://kantopay.com/documents#ep-rrevoke) or the [`order.refunded` event](https://kantopay.com/documents#webhooks-events) tells your server what to take back.

**How do I make sure each server only gets its own rewards?**
Each API key is bound to a single server. A key only receives deliveries routed to that server (plus any product set to deliver to *all* servers), so every server in your network polls safely with its own key.

**What happens if my plugin polls twice?**
Delivery is idempotent. A command stays in the pending pool until acknowledged, and acknowledging is safe to retry.

## Glossary

**QRPh** — the Philippine national QR standard; one QR pays from any participating bank or e-wallet.
**Payment link** — a hosted checkout page (and QR) for a single order, tracked from `pending` to `paid`.
**Reward / command** — the in-game action delivered to a server when an order settles.
**Idempotent** — safe to call more than once; repeats don’t double-charge or double-deliver.

---

## Storefront API

Build your own store on the same catalogue, pricing and checkout as the hosted store: a website, a Discord bot or an in-game menu. Requests need no key, only your public **storefront token** (`kps_…`) from [Dashboard › Servers](https://kantopay.com/dashboard/servers).

**It works from a static site**: plain HTML and JavaScript on GitHub Pages, Netlify, Cloudflare Pages or any web host, with no server of your own.

No secret API key is needed. Two actions take a token of their own: a player’s orders need that player’s `player_token` (from [`/players/link`](https://kantopay.com/documents#ep-plink)), and cancelling an order needs the `cancel_token` its checkout returned.

```
https://api.kantopay.com/v1/shops/kps_63bde17336594cbda90a0b7f5dd460d6/products
```

See one running at [example.kantopay.com](https://example.kantopay.com), a whole store in one HTML file. [Why a token and not your slug?](https://kantopay.com/documents#why-token) · [Capabilities](https://kantopay.com/documents#compare)

### Quick start

Read the catalogue, price the cart, send the buyer to checkout. You need a published product and your storefront token; use your [test token](https://kantopay.com/documents#storefront-test) (`kps_test_…`) while you build, so no real money moves. Pick a language: none of them needs a library or a download.

```bash
# bash, macOS, Linux or Git Bash. Use your test token while you build.
SHOP=https://api.kantopay.com/v1/shops/kps_test_your_token

# 1. What's for sale. Copy a product id; show effective_amount (the price after any sale).
curl -sS $SHOP/products

# 2. Price the cart. Send the same cart to checkout so both price the same thing.
CART='"player_name":"Steve","items":[{"product_id":"PRODUCT_ID","quantity":1}]'
curl -sS -X POST $SHOP/quote -H 'Content-Type: application/json' -d "{$CART}"

# 3. Take the money. Send the buyer to redirect_url; keep order_id.
curl -sS -X POST $SHOP/checkout -H 'Content-Type: application/json' \
  -d "{$CART,\"buyer_email\":\"me@example.com\",\"idempotency_key\":\"order-1\"}"

# Later: is it paid?
curl -sS https://api.kantopay.com/v1/orders/ORDER_ID
```

```javascript
// Run as <script type="module">. Use your test token while you build.
const SHOP = 'https://api.kantopay.com/v1/shops/kps_test_your_token';

async function call(path, body) {
  const res = await fetch(SHOP + path, body ? {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  } : undefined);
  // Every error is { code, message }. Branch on code; show message.
  const data = await res.json()
    .catch(() => ({ code: 'bad_response', message: `HTTP ${res.status}` }));
  if (!res.ok) {
    const err = new Error(data.message);
    throw Object.assign(err, { code: data.code, status: res.status });
  }
  return data;
}

// 1. What's for sale. Show effective_amount (the price after any sale).
const { products } = await call('/products');
if (!products.length) throw new Error('Publish a product in the dashboard first.');

// 2. One cart for the quote AND the checkout, so both price the same thing.
const cart = {
  player_name: 'Steve',
  items: [{ product_id: products[0].id, quantity: 1 }],
  promo_code: 'LAUNCH20',                        // optional
};
const quote = await call('/quote', cart);
// A bad coupon is an answer, not an error: show it and drop it.
if (cart.promo_code && !quote.coupon_ok) {
  console.warn(quote.coupon_message);
  delete cart.promo_code;
}
// blocked: a purchase limit or opening hours. Checkout would refuse too.
if (quote.blocked) throw new Error(quote.blocked.message);
if (quote.below_minimum) throw new Error(`Orders start at ₱${quote.min_charge}.`);
console.log(`Total: ₱${quote.total}`);   // put this on your Pay button

// 3. Take the money. One idempotency key per purchase: a double click makes one order.
const order = await call('/checkout', {
  ...cart,
  buyer_email: 'me@example.com',
  idempotency_key: crypto.randomUUID(),
});
// Keep the order id to check when the buyer comes back, then go to the pay page.
sessionStorage.setItem('kp_order', order.order_id);
location.href = order.redirect_url;
// Back on your site: GET /v1/orders/{order_id} says when it is paid.
```

```python
# Python 3, standard library only. Use your test token while you build.
import json, uuid, urllib.request, urllib.error

SHOP = 'https://api.kantopay.com/v1/shops/kps_test_your_token'

def call(path, body=None):
    req = urllib.request.Request(
        SHOP + path,
        data=json.dumps(body).encode() if body else None,
        headers={'Content-Type': 'application/json'},
    )
    try:
        with urllib.request.urlopen(req) as res:
            return json.load(res)
    except urllib.error.HTTPError as e:
        err = json.load(e)                      # every error is { code, message }
        raise RuntimeError(f"{err['code']}: {err['message']}")

# 1. What's for sale. Show effective_amount (the price after any sale).
products = call('/products')['products']
if not products:
    raise SystemExit('Publish a product in the dashboard first.')

# 2. One cart for the quote AND the checkout, so both price the same thing.
cart = {
    'player_name': 'Steve',
    'items': [{'product_id': products[0]['id'], 'quantity': 1}],
    'promo_code': 'LAUNCH20',                   # optional
}
quote = call('/quote', cart)
if cart.get('promo_code') and not quote['coupon_ok']:
    print(quote['coupon_message'])              # a bad coupon is an answer: show it, drop it
    del cart['promo_code']
if quote['blocked']:
    raise SystemExit(quote['blocked']['message'])
if quote['below_minimum']:
    raise SystemExit(f"Orders start at {quote['min_charge']}.")
print('Total:', quote['total'])                 # money is a string: '69.00'

# 3. Take the money. One idempotency key per purchase.
order = call('/checkout', {**cart, 'buyer_email': 'me@example.com',
                           'idempotency_key': str(uuid.uuid4())})
print('Pay here:', order['redirect_url'])       # send the buyer this link
print('Order:', order['order_id'])              # GET /v1/orders/{order_id} says when it is paid
```

```php
<?php
// PHP 7.4+, no libraries. Use your test token while you build.
const SHOP = 'https://api.kantopay.com/v1/shops/kps_test_your_token';

function call(string $path, ?array $body = null): array {
    $ctx = stream_context_create(['http' => [
        'method'        => $body ? 'POST' : 'GET',
        'header'        => "Content-Type: application/json\r\n",
        'content'       => $body ? json_encode($body) : '',
        'ignore_errors' => true,                // read error bodies too
    ]]);
    $data = json_decode(file_get_contents(SHOP . $path, false, $ctx), true);
    preg_match('{HTTP/\S+ (\d+)}', $http_response_header[0], $m);
    if ($m[1] >= 400) {                         // every error is { code, message }
        throw new RuntimeException("{$data['code']}: {$data['message']}");
    }
    return $data;
}

// 1. What's for sale. Show effective_amount (the price after any sale).
$products = call('/products')['products'];
if (!$products) exit("Publish a product in the dashboard first.\n");

// 2. One cart for the quote AND the checkout, so both price the same thing.
$cart = [
    'player_name' => 'Steve',
    'items'       => [['product_id' => $products[0]['id'], 'quantity' => 1]],
    'promo_code'  => 'LAUNCH20',                // optional
];
$quote = call('/quote', $cart);
if (isset($cart['promo_code']) && !$quote['coupon_ok']) {
    echo $quote['coupon_message'], "\n";        // a bad coupon is an answer: show it, drop it
    unset($cart['promo_code']);
}
if ($quote['blocked']) exit($quote['blocked']['message'] . "\n");
if ($quote['below_minimum']) exit("Orders start at ₱{$quote['min_charge']}.\n");
echo "Total: ₱{$quote['total']}\n";

// 3. Take the money. One idempotency key per purchase.
$order = call('/checkout', $cart + [
    'buyer_email'     => 'me@example.com',
    'idempotency_key' => bin2hex(random_bytes(16)),
]);
echo "Pay here: {$order['redirect_url']}\n";    // send the buyer this link
echo "Order: {$order['order_id']}\n";           // GET /v1/orders/{order_id} says when it is paid
```

**Before you ship: money, verified players, tiered prices, quotes**

**Money is always a string** — `"499.00"`, never `499.0`. A float cannot hold ₱0.10 exactly, and a storefront that rounds is a storefront that loses money. Parse with a decimal library, or keep it as a string until you print it.

**Prove who the player is.** `player_name` is an unverified string — anyone can type anyone’s username. To prove it, your game server calls [`POST /players/link`](https://kantopay.com/documents#reference) with its API key when a player types `/link`, and sends them the returned URL as a clickable message. Your storefront reads `?kp_player=` off that URL and passes it back as `player_token` on `/products`, `/quote` and `/checkout`. A verified token **replaces** the typed name for pricing *and* delivery, so the discount and the goods always land on the same person. Sending no token still works exactly as before; sending one that doesn’t verify is `401 invalid_player_token`, never a quiet fall back to the typed name.

**Tiered products need a player name.** If a product has a `cumulative_group`, its price depends on who is buying — an upgrade costs the difference, not the full tier. Pass `player_name` to `/products` to render the grid correctly, and note that only one product per group may be in a cart at a time. Personalised requests are throttled on the same budget as `/quote`, because the prices reveal what that player has already spent on the ladder.

**Quote before you charge.** `/quote` and `/checkout` run the same pricing code, so the same cart prices the same way. A quote is not a promise: if a sale ends, a coupon runs out or the player buys elsewhere in between, checkout prices the cart again and charges the new total, so show the total on the pay page as final. It also tells you `below_minimum` before the buyer hits the ₱1 floor, so you can disable your Pay button instead of failing at the last step. Cards are offered only from ₱100 (`card_min_charge` on `/v1/shops/{token}`); below that, checkout returns the other methods. The quote also returns `lines` (what each line costs after upgrade pricing, adding up to `subtotal`), `payment_methods` (what checkout will offer for that total), `free_order` (a coupon or gift card covers everything, so checkout settles the order at once with no payment step) and `blocked`: `null`, or the `{code, message}` checkout would refuse with as a `409` — a purchase limit reached, or a product outside its opening hours. Show `blocked.message` and keep Pay disabled.

### Payment status

Poll [`GET /v1/orders/{id}`](https://kantopay.com/documents#ep-v1order) until it reports `paid`. Check `reversal_type` too: an order can be `paid` and later refunded or charged back, and if you grant entitlements on `paid` you need to know when to revoke them. Check `is_test` as well — a [test order](https://kantopay.com/documents#storefront-test) charges no real money, and a client that can’t tell will ship real goods for play money.

### Test orders

Rehearse the whole flow without real money: checkout, payment, settlement and delivery. You need two things from [Dashboard › Servers](https://kantopay.com/dashboard/servers), and neither exists until you make it.

- **A test storefront token** (`kps_test_…`). Use it in place of your token. Every Storefront API read answers as usual, and `GET /v1/shops/{token}` says `"is_test": true`. Checkouts and gift cards made with it are test orders, at the real price.
- **A test server**, whose key starts `kp_test_`. Put that key in the plugin on a test server. It receives the test orders’ deliveries and nothing else, and its in-game purchases (`POST /payments/from-product` and `POST /server/checkout`) are test orders too. It can’t reach your wallet, orders, coupons or gift cards.

A test order is paid on PayMongo’s test system: the payment page has a button that completes the test payment. When it settles, your balance, payouts and sales figures don’t change, no coupon use or gift card is spent, no gift card is made, the buyer gets no email, and nothing is posted to Discord. Your developer webhook gets `sale.paid` with `"test": true`, and each delivery carries `test_mode: true`. Your live servers never receive a test order. Test orders are deleted 30 minutes after they are made.

### Return URLs

After paying, a buyer lands on our receipt at `/pay/{id}`. To bring them back to your own site, list it under **Your website** in the dashboard (up to five `https://` addresses; your verified custom domain counts without being listed), then send `return_url` with [`/checkout`](https://kantopay.com/documents#ep-v1checkout) or [`POST /giftcards`](https://kantopay.com/documents#ep-v1gcbuy).

```
body: JSON.stringify({
  player_name: 'Steve', items: cart,
  return_url: 'https://store.example.com/thanks',
  auto_return: true
})
// After paying, the buyer arrives at
// https://store.example.com/thanks?order_id=9f1e6c1a-…&status=paid
```

The receipt’s **Back to store** button goes to `return_url` with `order_id` and `status` added to its query; any query it already has is kept. `status` is `paid`, or `expired` / `cancelled` when the order ended unpaid. With `auto_return: true` a paid buyer skips the receipt, unless it shows something they must not miss: a gift card’s code, or the button that gets their Discord role.

An address that is not https, or not on one of your websites, is refused with `400 return_url_not_allowed` before any order is made, so a typo shows up on your first test order.

The same buyer checking out the same cart again soon after (within ten minutes, while the first order is unpaid) gets that first order back, with the `return_url` it was made with. Test a new `return_url` with a new cart or player name.

**Don’t trust the query.** Anyone can type `?status=paid` into your address bar, or paste the `order_id` of an older order or of someone else’s receipt. Keep the `order_id` that `/checkout` returned with the buyer’s session, and accept only that one, once. Then read [`GET /v1/orders/{order_id}`](https://kantopay.com/documents#ep-v1order) and check that `status` is `paid`, `amount` is what you expected and `is_test` is false. `shop_slug` is only a sanity check that the order is your store’s.

### Errors and rate limits

Every failure, on every status, is the same two fields. You need exactly one parser.

```
{ "code": "cart_too_large", "message": "A cart can hold at most 50 different items." }
```

Branch on `code`; show `message` to the buyer. A `422` adds a third field, `field`, naming the parameter at fault.

**Each endpoint lists its own responses.** Use the response picker on an endpoint to see each status it documents, with an example body and when it happens.

**Response headers.** `Retry-After`, `X-Request-ID` and `Idempotent-Replay` are exposed to browsers via `Access-Control-Expose-Headers`, so `res.headers.get('retry-after')` works from a page. `X-Request-ID` is unique per request — log it, and quote it if you ever open a support ticket.

**Rate limits here are per IP**, and per endpoint: quote 60/min, checkout 30/min, gift-card purchase 20/min, order lookup and cancel 120/min together. Debounce your quote calls — a quote on every keystroke will hit the cap. (The Server API is limited differently: 120/min *per key*. See [its own limits](https://kantopay.com/documents#server-limits).)

### API-only mode

To run only your own front end, turn off the hosted storefront (`hosted_storefront: false`). Your `/shop/your-slug` pages then return 404; products, the Storefront API, payments and delivery keep working.

The payment page stays on KantoPay: `/checkout` returns its address as `redirect_url`, and [`return_url`](https://kantopay.com/documents#storefront-return) brings the buyer back to your site.

### Embedding

Store pages can’t be shown in an iframe: they send `X-Frame-Options: SAMEORIGIN`, which also protects the dashboard and the payment page. Link to your hosted store instead (`kantopay.com/shop/your-slug`, or your own domain), or build your pages with the [Storefront API](https://kantopay.com/documents#storefront-quickstart).

### Endpoints

Each endpoint sends real requests from **Try it**. Paste your storefront token (`kps_…`, not your slug) into its `token` field.

### GET /v1/shops/{token}

Your store’s identity and the numbers a client needs before it prices anything: `currency`, `min_charge` (the smallest order, ₱1), `card_min_charge` (cards are offered only from this amount, ₱100 — leave the card option out below it, checkout does) and `small_order` (orders under `under` share a per-buyer budget of `max_per_hour` at this shop). `categories` is every category in use across your active products, ready to render as tabs, leaving out any you hid from your store’s navigation. `is_test` is `true` when `{token}` is your [test token](https://kantopay.com/documents#storefront-test).

_Auth: No API key_

Required: `token`.

```bash
curl https://api.kantopay.com/v1/shops/{token}
```

Responses:
- `200`: Valid public storefront token for an open shop, public or not. is_test is true for the test token; categories leaves out any hidden from the store's navigation.
- `404 shop_not_found`: Unknown token, or the slug was sent instead of the storefront token, or the shop is not published

```json
{
  "is_test": false,
  "slug": "123",
  "name": null,
  "description": null,
  "logo_url": null,
  "accent_color": null,
  "currency": "PHP",
  "min_charge": "1",
  "card_min_charge": "100",
  "small_order": { "under": "20", "max_per_hour": 10 },
  "categories": [
    "Keys",
    "Ranks"
  ]
}
```

### GET /v1/shops/{token}/products

Your catalogue. Each product carries `amount` (list price) and `effective_amount` (after any running sale): **show `effective_amount`** as the catalogue price. With `player_name`, show that player `your_price` instead (below). What is actually charged is the `total` from [`/quote`](https://kantopay.com/documents#ep-v1quote) and checkout. Variants carry both too, and inherit the parent’s sale. `cumulative_group` names the upgrade ladder a product sits on, or is `null`. Pass `category` to filter. `has_more` is measured, not guessed — and when it is `true`, `next_offset` tells you the number to send back as `offset` for the next page. Pass `limit` to page in smaller chunks (clamped to 1–250; an out-of-range value is clamped, not rejected). Products come in the order your dashboard lays them out: category by category in your category order (Uncategorised last), then by position inside each, newest first on a tie. Reordering products mid-page-through can repeat or skip one — fine for a shop listing, not for anything that has to be exhaustive.

**Pass `player_name` and every product also gets `your_price` and `owned`** — the price *that* player pays, with credit for what they already own on the ladder. Without it a tiered catalogue shows the wrong number to anyone mid-upgrade: Emerald lists at ₱899, but a player who already bought Diamond pays ₱400. `owned:true` means they have the tier already and the cart will refuse it, so render it as owned rather than as a free item.

_Auth: No API key_

Required: `token`. Optional: `category`, `limit`, `offset`, `player_name`, `player_token`.

```bash
curl https://api.kantopay.com/v1/shops/{token}/products
```

Responses:
- `200`: Plain catalogue read (optional ?category=, ?limit= 1..250, ?offset=)
- `200`: Personalised read: ?player_name=Steve&limit=1 — every product gains your_price and owned; amount/effective_amount stay the public list price
- `400 invalid_query`: A query value is the wrong type, e.g. ?limit=abc (app-wide QueryConfig, src/api/extractor_error_json.rs:63)
- `401 invalid_player_token`: ?player_token= supplied but expired, malformed, or signed for another shop
- `404 shop_not_found`: Unknown storefront token, or its shop is closed
- `429 rate_limited`: Only on personalised reads (player_name or player_token present): more than 60 per minute per IP on the shared quote bucket. The plain catalogue is unthrottled. (`Retry-After: 60`)

```json
{
  "products": [
    {
      "id": "aaaaaaaa-1111-4111-8111-111111111111",
      "name": "Legendary Key",
      "amount": "50.00",
      "effective_amount": "50.00",
      "on_sale": false,
      "sale_percent": null,
      "description": "",
      "image_url": "/uploads/b4a72530-51e7-42dc-b8c3-140bf4899c64.png",
      "category": "Keys",
      "icon": null,
      "sort_order": 0,
      "cumulative_group": null,
      "variants": []
    },
    {
      "id": "bbbbbbbb-2222-4222-8222-222222222222",
      "name": "VIP Rank",
      "amount": "300.00",
      "effective_amount": "300.00",
      "on_sale": false,
      "sale_percent": null,
      "description": "",
      "image_url": "/uploads/9ff499e1-4edd-4acf-9c13-1190edb4fac0.jpg",
      "category": "Ranks",
      "icon": null,
      "sort_order": 2,
      "cumulative_group": "ranks",
      "variants": []
    }
  ],
  "has_more": false,
  "next_offset": null
}
```

### GET /v1/shops/{token}/products/{product_id}

One product, same shape as a row in the list. Useful for a product detail page you can link straight to. A product belonging to a different store returns `product_not_found` even if the id is real.

_Auth: No API key_

Required: `token`, `product_id`.

```bash
curl https://api.kantopay.com/v1/shops/{token}/products/{product_id}
```

Responses:
- `200`: Active product owned by this shop
- `200`: With ?player_name=Steve — adds your_price (list price minus cumulative-group credit, floored at 0) and owned
- `400 invalid_product_id`: product_id in the path is not a UUID
- `400 invalid_query`: A query value is the wrong type, e.g. ?limit=abc
- `401 invalid_player_token`: ?player_token= supplied but expired, malformed, or signed for another shop
- `404 shop_not_found`: Unknown storefront token, or its shop is closed
- `404 product_not_found`: A well-formed product UUID that is not an active product of this shop (deleted, switched off, or another store's). Before 2026-10-04 this answered shop_not_found.
- `429 rate_limited`: Only when player_name or player_token is present: over 60/min per IP on the shared quote bucket (`Retry-After: 60`)

```json
{
  "id": "bbbbbbbb-2222-4222-8222-222222222222",
  "name": "VIP Rank",
  "amount": "300.00",
  "effective_amount": "300.00",
  "on_sale": false,
  "sale_percent": null,
  "description": "",
  "image_url": "/uploads/9ff499e1-4edd-4acf-9c13-1190edb4fac0.jpg",
  "category": "Ranks",
  "icon": null,
  "sort_order": 2,
  "cumulative_group": "ranks",
  "variants": []
}
```

### POST /v1/shops/{token}/quote

Price a cart without charging anything. Read-only: it does **not** redeem the coupon or draw down the gift card — that happens only when the order is paid. An invalid code comes back as `coupon_ok:false` with a reason, not as an error, so you can mark the field without losing the cart. Besides the totals it returns `lines`, `payment_methods`, `free_order`, `is_test` and `blocked`, the refusal checkout would give (see [Quote before you charge](https://kantopay.com/documents#storefront-quickstart)). Use the `items` box for the JSON array.

_Auth: No API key_

Required: `token`, `items`. Optional: `player_name`, `promo_code`, `gift_card_code`.

```bash
curl -X POST https://api.kantopay.com/v1/shops/{token}/quote \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "product_id": "11111111-1111-1111-1111-111111111111",
      "quantity": 1
    }
  ],
  "player_name": "Steve_PH"
}'
```

Responses:
- `200`: Cart priced. Read-only: no coupon is redeemed and no gift card is drawn. An unusable promo/gift-card code is reported per field, not as an error. lines add up to subtotal; payment_methods is what checkout will offer for total; blocked is null or the 409 checkout would give.
- `200`: Priced, but checkout would refuse it: blocked carries the exact 409 code and message (a purchase limit reached, or a product outside its opening hours). Show the message and keep Pay disabled.
- `400 cart_empty`: items is present but an empty array. Omitting it is a different failure — see invalid_json — because items carries no serde default and is rejected before this handler runs.
- `400 invalid_product`: A cart line's product_id is not a UUID, or is not an active product of this shop. Variants are not validated. A variant_id that is malformed, unknown, or belongs to a different product is silently ignored: the line falls back to the parent product's price and its name (shop.rs:5390 and 5435), so you get 200 with the base product rather than this 400. The order stays self-consistent - you are not charged for one thing and given another - but a client sending a stale variant id is never told, and the buyer receives the base item they did not pick. quantity is clamped to 1-100, never rejected.
- `400 cart_too_large`: More than MAX_CART_ITEMS (50) distinct lines in items
- `400 already_owned`: A cumulative-group product the player already owns outright (upgrade price would be ₱0)
- `400 invalid_json`: Body is not valid JSON, or a required field is absent. items (types.rs:593) and a cart line's product_id/quantity (types.rs:575-579) have no serde default, so omitting any of them lands here, not on cart_empty.
- `401 invalid_player_token`: player_token in the body does not verify for this shop
- `404 shop_not_found`: Unknown storefront token, or its shop is closed
- `404 no_such_route`: Wrong verb or a misspelt path under /v1/shops/{token} — caught by that scope's own fallback. (The bare /v1 catch-all only sees mistyped scopes like /v1/shpos/.)
- `413 payload_too_large`: The JSON body is over the 2 MiB limit. (`X-Max-Body-Bytes: 2097152`)
- `415 unsupported_media_type`: Missing or non-JSON Content-Type
- `429 rate_limited`: More than 60 quotes per minute per IP (shared quote bucket) (`Retry-After: 60`)
- `500 internal_error`: Pricing failed — DB error or the blocking task was cancelled (catch-all arm of cart_quote_inner)

```json
{
  "subtotal": "350.00",
  "discount": "70.00",
  "coupon_ok": true,
  "coupon_message": null,
  "gift_card_applied": "0",
  "gift_card_ok": false,
  "gift_card_message": null,
  "total": "280.00",
  "min_charge": "1",
  "below_minimum": false,
  "free_order": false,
  "lines": [
    {
      "product_id": "bbbbbbbb-2222-4222-8222-222222222222",
      "name": "VIP Rank",
      "quantity": 1,
      "amount": "300.00"
    },
    {
      "product_id": "aaaaaaaa-1111-4111-8111-111111111111",
      "name": "Legendary Key",
      "quantity": 1,
      "amount": "50.00"
    }
  ],
  "payment_methods": ["qrph", "gcash", "card"],
  "is_test": false,
  "blocked": null
}
```

### POST /v1/shops/{token}/checkout

Create the order and get `{ "redirect": "…", "redirect_url": "…", "order_id": "…" }` — send the buyer to `redirect_url`, the pay page’s full address (`redirect` is the same page as a path on our host, `/pay/{id}`, which a page on your own domain cannot use as it is), and keep `order_id` to poll [`GET /v1/orders/{id}`](https://kantopay.com/documents#ep-v1order) when they come back. A new order also carries `cancel_token`: keep it if the buyer may [cancel](https://kantopay.com/documents#ep-v1cancel), since only this answer has it. (The id used to be reachable only by pulling it out of the redirect URL, which meant hardcoding the shape of a URL we are free to change.) Same body as `/quote`, but `player_name` is required, and this one really does redeem the coupon and draw the gift card. The target is the buyer’s `/pay/` page; an order a gift card or a 100% coupon pays in full (or the two together) is settled and delivered on the spot and answers the same JSON, its page already the receipt. Send an `idempotency_key` so a double-tapped Pay makes one order: a repeat with the same key and cart gets the first order back with `Idempotent-Replay: true`. `return_url` (an https address on one of your websites, up to 500 characters) is where the buyer goes back to afterwards, with `order_id` and `status` added; `auto_return: true` sends a paid buyer there without stopping at the receipt. See [Send buyers back to your website](https://kantopay.com/documents#storefront-return). **This creates a real order**, so try it with your [test token](https://kantopay.com/documents#storefront-test).

_Auth: No API key_

Required: `token`, `items`, `player_name`. Optional: `buyer_email`, `gift_recipient`, `promo_code`, `gift_card_code`, `return_url`, `auto_return`, `idempotency_key`.

```bash
curl -X POST https://api.kantopay.com/v1/shops/{token}/checkout \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "product_id": "11111111-1111-1111-1111-111111111111",
      "quantity": 1
    }
  ],
  "player_name": "Steve_PH"
}'
```

Responses:
- `200`: Order created. Send the buyer to redirect_url (our /pay/{id} page as a full address, on the host you called) and poll GET /v1/orders/{order_id}. redirect is the same page as a path. Keep cancel_token if the buyer may cancel: POST /v1/orders/{id}/cancel needs it, and only this answer has it.
- `200`: Idempotent replay: the same idempotency_key with the same cart already created an order. Same body as the first call plus the replay header — no second order, no second charge. (`Idempotent-Replay: true`)
- `200`: Paid in full by a gift card, a 100% coupon, or the two together. The order is created, settled and delivered inline, with no payment provider involved, and answers the same JSON; its /pay/ page is already the receipt. Until 2026-10-04 a gift card's answer was a 303 a cross-origin fetch could not follow, and a coupon's was 400 cart_total_zero.
- `400 player_name_required`: player_name is blank after cleaning, or longer than 64 chars (required for checkout, unlike /quote)
- `400 cart_empty`: items is present but an empty array. Omitting it is a different failure — see invalid_json — because items carries no serde default and is rejected before this handler runs.
- `400 invalid_product`: A cart line's product_id is not a UUID, or is not an active product of this shop. Variants are not validated. A variant_id that is malformed, unknown, or belongs to a different product is silently ignored: the line falls back to the parent product's price and its name (shop.rs:5390 and 5435), so you get 200 with the base product rather than this 400. The order stays self-consistent - you are not charged for one thing and given another - but a client sending a stale variant id is never told, and the buyer receives the base item they did not pick. quantity is clamped to 1-100, never rejected.
- `400 cart_too_large`: More than MAX_CART_ITEMS (50) distinct lines in items
- `400 already_owned`: A cumulative-group product the player already owns outright
- `400 coupon_rejected`: promo_code exists but is unusable for this cart. Unlike /quote, checkout rejects hard; message is the coupon engine's own sentence.
- `400 gift_card_rejected`: gift_card_code exists but is unusable (unknown, void, or no balance)
- `400 below_minimum`: Post-coupon, post-gift-card total is above ₱0 but under the ₱1 order floor (min_charge on GET /v1/shops/{token})
- `429 small_order_rate_limited`: More than 10 orders under ₱20 from the same buyer at this shop within an hour (small_order on GET /v1/shops/{token}). Anonymous orders share one bucket per shop. Retry-After is the seconds until the oldest of those orders leaves the hour (it was a fixed 60 before 2026-10-04). (`Retry-After: 1260`)
- `400 cart_total_zero`: The cart itself is worth ₱0 and no coupon or gift card paid for it, so there is nothing to charge or settle. A cart a coupon or gift card zeroed is settled instead (the 200 above).
- `400 return_url_not_allowed`: return_url is not https, is longer than 500 characters, or is not on one of the store's websites (Your website in the dashboard) or its verified custom domain. Checked before any order is made.
- `400 invalid_json`: Body is not valid JSON, or a required field is absent. items (types.rs:593) and a cart line's product_id/quantity (types.rs:575-579) have no serde default, so omitting any of them lands here, not on cart_empty.
- `401 invalid_player_token`: player_token in the body does not verify for this shop
- `404 shop_not_found`: Unknown storefront token, or its shop is closed
- `404 no_such_route`: Wrong method — a GET on /checkout hits the /v1 scope fallback, not a 405
- `409 idempotency_in_progress`: Same idempotency_key is still being processed by an in-flight request (`Retry-After: 2`)
- `413 payload_too_large`: The JSON body is over the 2 MiB limit. (`X-Max-Body-Bytes: 2097152`)
- `415 unsupported_media_type`: Missing or non-JSON Content-Type
- `422 idempotency_key_reuse`: Same idempotency_key replayed with a different cart (fingerprint covers buyer name, lines, promo code, gift-card code, gift recipient)
- `429 rate_limited`: More than 30 checkouts per minute per IP (`Retry-After: 60`)
- `500 internal_error`: The provider intent was created but the order row could not be written; the idempotency reservation is released so an immediate retry works. (Sibling messages from the same handler: "Error processing request.", "Couldn't apply that code.", "Couldn't apply that gift card.", "Failed to complete order.")
- `502 payment_provider_error`: PayMongo did not answer when creating the QRPh intent (after retries). No order was created; the idempotency key is released so a retry is safe.

```json
{
  "redirect": "/pay/9f1e6c1a-53ab-4d0e-9d2e-1f0c7a4b8e21",
  "redirect_url": "https://api.kantopay.com/pay/9f1e6c1a-53ab-4d0e-9d2e-1f0c7a4b8e21",
  "order_id": "9f1e6c1a-53ab-4d0e-9d2e-1f0c7a4b8e21",
  "cancel_token": "3b6f0c2a9d4e81f75a0c6e2d9b1f4a83c7e5d2016f9a8b3c4d5e6f708192a3b4"
}
```

### GET /v1/orders/{id}

Order state: `status` (`active`, `paid`, `expired`, `cancelled`), amount, buyer, `paid_method`, `reversal_type`, `is_test`, and `items` — the line items with `product_id`, `quantity` and the amount each was actually charged, because `product_name` on a multi-line order is just “Cart (3 items)”, which is not a receipt anyone can read. `shop_slug` names the store the order belongs to: any order id resolves here, so a site reading `order_id` off its [return URL](https://kantopay.com/documents#storefront-return) checks it is its own before trusting the order. The order id is the credential — anyone holding the link can already see this, which is why `buyer_email` is deliberately left out.

For a receipt page: `gift_card_code` is the code a paid gift-card order bought (`null` otherwise, and until payment settles). It shows in full for 30 minutes after payment, then only its first and last four characters, with `gift_card_code_masked: true`, the same rule as our own receipt; the recipient’s copy went by email. `delivery` is `{total, delivered, waiting_online, failed}`: how many in-game reward commands the order has, how many ran, how many wait for the player to join, and how many failed. All zero before payment.

_Auth: No API key_

Required: `id`.

```bash
curl https://api.kantopay.com/v1/orders/{id}
```

Responses:
- `200`: Any order id — the UUID is the credential. status is computed: an active order past expires_at reads "expired". buyer_email is deliberately never returned. gift_card_code is null except on a paid gift-card order. delivery counts the order's in-game reward commands.
- `200`: A paid gift-card order more than 30 minutes after payment: the code shows its first and last four characters only, with gift_card_code_masked true. In the first 30 minutes it is the whole code and gift_card_code_masked is false.
- `400 invalid_order_id`: Path segment is not a UUID
- `404 order_not_found`: Well-formed UUID with no matching order
- `429 rate_limited`: More than 120 requests per minute per IP (v1order bucket, shared with /players/me/orders). Checked before the UUID parse. (`Retry-After: 60`)

```json
{
  "id": "9f1e6c1a-53ab-4d0e-9d2e-1f0c7a4b8e21",
  "status": "paid",
  "amount": "300.00",
  "currency": "PHP",
  "product_name": "VIP Rank",
  "description": null,
  "buyer_name": "Steve",
  "recipient_name": null,
  "paid_method": "qrph",
  "discount_amount": null,
  "gift_card_applied": null,
  "reversal_type": null,
  "is_test": false,
  "shop_slug": "craftmc",
  "paid_at": "2026-08-19T04:21:07+00:00",
  "expires_at": "2026-08-20T04:18:55+00:00",
  "created_at": "2026-08-19T04:18:55+00:00",
  "items": [
    {
      "product_id": "bbbbbbbb-2222-4222-8222-222222222222",
      "product_name": "VIP Rank",
      "quantity": 1,
      "amount": "300.00"
    }
  ],
  "gift_card_code": null,
  "gift_card_code_masked": false,
  "delivery": {
    "total": 2,
    "delivered": 1,
    "waiting_online": 1,
    "failed": 0
  }
}
```

### POST /v1/orders/{id}/cancel

The buyer walked away from an unpaid order. Send the order’s `cancel_token` as the `X-Cancel-Token` header or `?token=`. Only the checkout or gift-card buy that made the order answers with it, so keep it if the buyer may cancel; without it the answer is `404 order_not_found`, as for an id that does not exist. Orders made from the dashboard, the API, in game or on Discord have no token: the store cancels those. Cancelling frees the order’s `idempotency_key`, so the same purchase can be made again as a new order. The order’s gift-card balance, coupon use and purchase-limit units stay held until its QR code’s deadline, 30 minutes from checkout, because that QR code can still be paid. Returns `{ "id": "…", "status": "cancelled" }`. Safe to repeat: a cancelled or expired order answers `200` with its status as it stands. A paid order answers `409 order_paid`. A few older orders also have a checkout page at the payment provider; that page is closed first, and if it cannot be closed just then the order stays and the answer is `409 checkout_open`, so try again. A payment that still arrives for the cancelled order’s QR code is recorded and delivered as normal. No body. Shares 120 calls a minute per IP with the read above.

_Auth: Cancel token_

Required: `id`, `token`.

```bash
curl -X POST https://api.kantopay.com/v1/orders/{id}/cancel?token=YOUR_TOKEN
```

Responses:
- `200`: An unpaid order, now cancelled. Its idempotency key is freed; its gift-card, coupon and purchase-limit holds last until its QR code's deadline.
- `200`: Already cancelled or expired: the answer is the order as it stands. Safe to repeat.
- `400 invalid_order_id`: Path segment is not a UUID
- `404 order_not_found`: No matching order, or the cancel token is missing or wrong
- `409 order_paid`: The order is paid. A paid order can only be refunded, by KantoPay, not cancelled.
- `409 checkout_open`: An older order with a checkout page at the payment provider, which could not be closed just now. Nothing changed; try again.
- `429 rate_limited`: More than 120 requests per minute per IP, shared with GET /v1/orders/{id} (`Retry-After: 60`)

```json
{
  "id": "9f1e6c1a-53ab-4d0e-9d2e-1f0c7a4b8e21",
  "status": "cancelled"
}
```

### POST /v1/shops/{token}/giftcards

Sell a gift card. `amount` is in **pesos**, as a string (`"500"` or `"500.00"`, never centavos), and must be one of the denominations from the `GET` below, or inside the custom range if you allow one; a custom amount is never under ₱20, even when you left the minimum blank. Returns `{ "redirect": "…", "redirect_url": "…", "order_id": "…" }` exactly like [`/checkout`](https://kantopay.com/documents#ep-v1checkout) — the card itself is minted when the payment settles, not when this returns, so poll [`GET /v1/orders/{id}`](https://kantopay.com/documents#ep-v1order) and read its `gift_card_code` rather than expecting a code here. Send an `idempotency_key`, one per purchase the buyer means to make, and reuse it for every retry and double tap of that purchase, so they make one order: the repeat gets the first order back with `Idempotent-Replay: true`. Without one, every call makes a new order. `recipient_email` is where the card gets delivered; without one the buyer only ever sees it on the receipt page. `buyer_name` is optional and shows on the order. `return_url` and `auto_return` work as on [`/checkout`](https://kantopay.com/documents#ep-v1checkout), except that `auto_return` has no effect: the receipt with the card’s code always shows, and its Back button goes to your `return_url`. A token that is not an open shop answers `404 shop_not_found`; an amount that is not on sale answers `400 denomination_unavailable`; a `return_url` that is not on one of your websites answers `400 return_url_not_allowed`.

_Auth: No API key_

Required: `token`, `amount`. Optional: `buyer_name`, `recipient_email`, `return_url`, `auto_return`, `idempotency_key`.

```bash
curl -X POST https://api.kantopay.com/v1/shops/{token}/giftcards \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "500.00",
  "buyer_name": "Steve_PH"
}'
```

Responses:
- `200`: Amount accepted and the PayMongo intent + order row were created. Send the buyer to redirect_url. Keep cancel_token if the buyer may cancel.
- `200`: The same idempotency_key and purchase again (a double-tapped Buy): the first order comes back, and no second one is made. (`Idempotent-Replay: true`)
- `400 invalid_name`: buyer_name survives the name allowlist as a multi-byte name whose 40-character cap still exceeds 64 bytes — roughly 33+ Cyrillic or 22+ CJK characters. An all-ASCII name can never reach this branch.
- `400 invalid_amount`: amount is not a decimal, or is <= 0
- `400 denomination_unavailable`: The amount is not an active denomination and custom amounts are off, or it is outside customMin/customMax. A custom amount under ₱20 is refused even when the minimum is blank. The amount is in pesos: 500, not 50000
- `400 return_url_not_allowed`: return_url is not https, is longer than 500 characters, or is not on one of the store's websites or its verified custom domain. Checked before the payment is set up.
- `404 shop_not_found`: The token is not an open shop (before 2026-10-04 this route answered 400 denomination_unavailable here instead)
- `400 invalid_json`: Body is malformed JSON or missing the required `amount` field — rejected by the app-wide JsonConfig (src/api/extractor_error_json.rs:30, installed in main.rs:357) before the handler runs; `message` carries serde's byte offset
- `413 payload_too_large`: Body exceeds the 2 MiB JSON limit (`X-Max-Body-Bytes: 2097152`)
- `415 unsupported_media_type`: Request sent without Content-Type: application/json
- `429 rate_limited`: More than 20 gift-card buys from this IP in 60s (storefront_limiter, key gc:{ip}); checked first, before anything else (`Retry-After: 60`)
- `500 internal_error`: The shop/denomination lookup itself failed (DB error or blocking pool cancelled)
- `500 internal_error`: The PayMongo intent exists but the INSERT into payment_links failed
- `502 payment_provider_error`: create_qrph_intent to PayMongo failed after retries
- `503 service_unavailable`: No database pool configured/available when the handler asks for one (`Retry-After: 2`)

```json
{
  "redirect": "/pay/7c1f0e9a-3d2b-4a55-9f11-2c6b8ad4e001",
  "redirect_url": "https://api.kantopay.com/pay/7c1f0e9a-3d2b-4a55-9f11-2c6b8ad4e001",
  "order_id": "7c1f0e9a-3d2b-4a55-9f11-2c6b8ad4e001",
  "cancel_token": "8d2e4f6a0b1c3d5e7f9a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3e4f5a6"
}
```

### GET /v1/shops/{token}/giftcards/check

What is left on a card. Returns `valid`, `remaining` and `status`. A code that does not exist is a `200` with `valid:false` and `status:"not_found"`, not a 404 — a buyer mistyping their card is an answer, not an error. An expired card reports `status:"expired"` regardless of what is stored, so this can never disagree with what checkout will accept.

Gift-card codes are ~80 bits, so unlike a coupon code they cannot be guessed; that is why this one has no extra throttle and [`/coupons/check`](https://kantopay.com/documents#ep-v1coupon) shares the quote budget.

_Auth: No API key_

Required: `token`, `code`.

```bash
curl https://api.kantopay.com/v1/shops/{token}/giftcards/check?code=YOUR_CODE
```

Responses:
- `200`: Code exists, status is active, has balance left and is not expired
- `200`: No gift card with that code for this shop — an answer, not an error
- `200`: Card exists but is fully spent, voided, or past expires_at (status is reported as `expired` when the date has passed, otherwise the stored value: active | redeemed | void)
- `400 code_required`: ?code= missing or blank — deliberately not reported as valid:false, so a client bug is not mistaken for a rejected card
- `404 shop_not_found`: The storefront token matches no open shop
- `500 internal_error`: Database error, pool exhaustion, or blocking-task cancellation — this handler's catch-all arm collapses all of them into AuthError::Internal, so it never answers 503 here

```json
{
  "valid": true,
  "remaining": "250.00",
  "status": "active"
}
```

### GET /v1/shops/{token}/coupons/check

Is this code any good, and on what terms? Returns `valid` plus the coupon’s own settings — `kind` (`percent` or `fixed`), `value`, `min_amount`, `max_discount`, `expires_at` and `product_ids` — so you can render “20% off orders over ₱250, up to ₱200” the moment a buyer types it, instead of a bare tick.

It answers about the **code**, not about a cart. Whether *this* cart clears the minimum, contains an eligible product, or what the peso discount comes to is what [`/quote`](https://kantopay.com/documents#ep-v1quote) calculates; checkout then creates the order. A rejected code is a `200` with `valid:false` and a `reason` you can show the buyer, for the same reason `/quote` reports it as a field: a mistyped code is an answer, not a broken integration.

The gift-card twin is [`/giftcards/check`](https://kantopay.com/documents#ep-v1gcbalance).

_Auth: No API key_

Required: `token`, `code`.

```bash
curl https://api.kantopay.com/v1/shops/{token}/coupons/check?code=YOUR_CODE
```

Responses:
- `200`: Code exists, is active, unexpired and has redemptions left. `product_ids` empty = applies to the whole cart; `reason` is null
- `200`: Code is rejected — a mistyped code is an answer, not a failure. `reason` is the buyer-facing sentence from coupons::coupon_status: "That code isn't valid." | "That code is no longer active." | "That code has expired." | "That code has reached its usage limit." | "Couldn't check that code."
- `400 code_required`: ?code= missing or blank
- `404 shop_not_found`: The storefront token matches no open shop
- `429 rate_limited`: More than 60 requests/minute from this IP — shares the `quote:{ip}` bucket with POST /quote on purpose, so a coupon guesser gains no extra throughput (`Retry-After: 60`)
- `500 internal_error`: No database configured, or a query failed. Pool exhaustion is a 503, not this.
- `503 service_unavailable`: Every database connection is busy. A capacity signal, not a broken request. (`Retry-After: 2`)

```json
{
  "valid": true,
  "code": "LAUNCH20",
  "kind": "percent",
  "value": "20",
  "min_amount": "250.00",
  "max_discount": "200.00",
  "expires_at": "2026-12-31T15:59:59+00:00",
  "product_ids": [
    "bbbbbbbb-2222-4222-8222-222222222222"
  ],
  "reason": null
}
```

### GET /v1/shops/{token}/players/me/orders

This player’s paid orders, newest first, each with its `items`. The “my purchases” page of a storefront you built yourself.

**A verified `player_token` only — a player name will not do.** Everywhere else in the Storefront API an unverified name is allowed, because the worst it does is quote someone their own upgrade price. Here it would hand any visitor the purchase history of any player whose username they can guess. Mint one with [`POST /players/link`](https://kantopay.com/documents#ep-plink) after your server has vouched for them.

Orders gifted *to* this player appear with `gifted:true` — matched on the same identity that earns cumulative upgrade credit, which is also the identity they were priced against.

_Auth: Player token_

Required: `token`, `player_token`. Optional: `limit`.

```bash
curl https://api.kantopay.com/v1/shops/{token}/players/me/orders?player_token=YOUR_PLAYER_TOKEN
```

Responses:
- `200`: Valid ?player_token= for this shop. Returns paid orders only, newest first, ?limit= clamped to 1..100 (default 25). player_name echoes the name inside the token, not anything the caller typed. gifted is true when someone else paid and named this player as recipient.
- `200`: Token verifies but that player has no paid orders in this shop
- `400 player_token_required`: ?player_token= missing or blank. A player name is never accepted here.
- `400 invalid_query`: A query value is the wrong type, e.g. ?limit=abc
- `401 invalid_player_token`: player_token is malformed, expired, or was minted for a different shop
- `404 shop_not_found`: Unknown storefront token, or its shop is closed (checked after the player_token presence check)
- `429 rate_limited`: More than 120 requests per minute per IP (v1order bucket, shared with GET /v1/orders/{id}) (`Retry-After: 60`)

```json
{
  "player_name": "Steve",
  "orders": [
    {
      "id": "9f1e6c1a-53ab-4d0e-9d2e-1f0c7a4b8e21",
      "status": "paid",
      "amount": "300.00",
      "currency": "PHP",
      "product_name": "VIP Rank",
      "paid_at": "2026-08-19T04:21:07+00:00",
      "created_at": "2026-08-19T04:18:55+00:00",
      "discount_amount": null,
      "gift_card_applied": null,
      "reversal_type": null,
      "is_test": false,
      "gifted": false,
      "items": [
        {
          "product_id": "bbbbbbbb-2222-4222-8222-222222222222",
          "product_name": "VIP Rank",
          "quantity": 1,
          "amount": "300.00"
        }
      ]
    }
  ]
}
```

### GET /v1/shops/{token}/categories

Your categories with a `product_count` each, so you can render tabs without fetching the whole catalogue to count them, in the order you set in the dashboard, then by name. Each also carries what you gave it there: `id`, `image_url`, `blurb` and `is_ladder` (its products are tiers of one rank ladder). A category you never decorated still lists, with `id`, `image_url` and `blurb` `null` and `is_ladder` `false`. A category hidden from your store’s navigation is left out, as it is on your hosted store.

_Auth: No API key_

Required: `token`.

```bash
curl https://api.kantopay.com/v1/shops/{token}/categories
```

Responses:
- `200`: Published shop; categories of active products, in the order set in the dashboard, then by name. Hidden categories are left out. A category never decorated in the dashboard has id, image_url and blurb null.
- `200`: Shop exists but no active product carries a category
- `404 shop_not_found`: Token matches no shop, or the shop is not published (unpublished is deliberately indistinguishable from missing)
- `500 internal_error`: No database configured, or a query failed. Pool exhaustion is a 503, not this.
- `503 service_unavailable`: Every database connection is busy. A capacity signal, not a broken request. (`Retry-After: 2`)

```json
{
  "categories": [
    {
      "name": "Ranks",
      "product_count": 3,
      "id": "4e0d2c1b-8a7f-4c3e-9b5d-6f1a2e3c4d5b",
      "image_url": "/uploads/0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f.png",
      "blurb": "Climb the ladder: pay only the difference.",
      "is_ladder": true
    },
    {
      "name": "Keys",
      "product_count": 1,
      "id": null,
      "image_url": null,
      "blurb": null,
      "is_ladder": false
    }
  ]
}
```

### GET /v1/shops/{token}/pages

Your published custom pages — rules, FAQ, terms — so a storefront you build yourself has something to put behind those links. Returns `slug`, `title`, `mode`, `has_content`, `show_in_nav` and `nav_order`. **Check `has_content`**: pages you wrote in the drag-and-drop builder can only be rendered by us, so for those you link out rather than fetch. System pages are never listed.

_Auth: No API key_

Required: `token`.

```bash
curl https://api.kantopay.com/v1/shops/{token}/pages
```

Responses:
- `200`: Published, non-system pages (slug not prefixed `__`), ordered by nav_order then title. `has_content` is true only for mode "simple" — for "builder"/"advanced" the detail call returns content: null
- `200`: Shop is published but has written no pages
- `404 shop_not_found`: Token matches no open shop
- `500 internal_error`: No database configured, or a query failed. Pool exhaustion is a 503, not this.
- `503 service_unavailable`: Every database connection is busy. A capacity signal, not a broken request. (`Retry-After: 2`)

```json
{
  "pages": [
    {
      "slug": "rules",
      "title": "Server Rules",
      "mode": "simple",
      "has_content": true,
      "meta_description": "How to behave on the server.",
      "show_in_nav": true,
      "nav_order": 0
    },
    {
      "slug": "faq",
      "title": "FAQ",
      "mode": "builder",
      "has_content": false,
      "meta_description": null,
      "show_in_nav": true,
      "nav_order": 1
    }
  ]
}
```

### GET /v1/shops/{token}/pages/{page_slug}

One page. When `mode` is `"simple"`, `content` is your own markup and you can render it directly. For a builder page `content` is `null` and `hosted_url` points at the page on our side — we would rather tell you than hand back a layout document only our renderer can draw.

_Auth: No API key_

Required: `token`, `page_slug`.

```bash
curl https://api.kantopay.com/v1/shops/{token}/pages/{page_slug}
```

Responses:
- `200`: Published simple page — `content` is the seller's own markup, ready to render
- `200`: Published page built in the drag-and-drop builder (mode "builder" or "advanced") — content is null on purpose and `hosted_url` is where to send the visitor instead
- `404 page_not_found`: Shop resolves, but there is no published page with that slug (system pages prefixed `__` are excluded)
- `404 shop_not_found`: Token matches no open shop — checked before the page lookup
- `500 internal_error`: No database configured, or a query failed. Pool exhaustion is a 503, not this.
- `503 service_unavailable`: Every database connection is busy. A capacity signal, not a broken request. (`Retry-After: 2`)

```json
{
  "slug": "rules",
  "title": "Server Rules",
  "mode": "simple",
  "content": "<h2>Rules</h2><p>No griefing. No cheating. Be kind in chat.</p>",
  "meta_description": "How to behave on the server.",
  "hosted_url": "http://localhost:8080/shop/123/page/rules"
}
```

### GET /v1/shops/{token}/recent-sales

The social proof your hosted store renders, so a store you build yourself isn’t missing it. Returns `{sales:[{name, product, paid_at}]}`. Buyer names are **always masked** (`St•••`) — buyers are free-text with no account, so they never agreed to be listed. `paid_at` is RFC 3339, not a pre-rendered “5 minutes ago”, so you format it in your own language and timezone. Test orders never appear. `limit` 1–25, default 10.

_Auth: No API key_

Required: `token`. Optional: `limit`.

```bash
curl https://api.kantopay.com/v1/shops/{token}/recent-sales
```

Responses:
- `200`: Paid, non-test, non-reversed orders, newest first. `limit` defaults to 10 and is clamped to 1..=25. Buyer names are masked (they never consented to being listed); `paid_at` is RFC 3339, not a pre-rendered "5 minutes ago"
- `200`: Shop is published but has no paid orders yet (unlike the older /shop/{slug} feed, this is now distinguishable from a bad shop, which 404s)
- `400 invalid_query`: `limit` is not a non-negative integer (e.g. ?limit=abc or ?limit=-1) — rejected by the app-wide QueryConfig before the handler runs
- `404 shop_not_found`: Token matches no open shop — resolved before any aggregate runs
- `500 internal_error`: No DB pool configured, a database error on the sales query, or the blocking task was cancelled

```json
{
  "sales": [
    {
      "name": "Ste***",
      "product": "VIP Rank",
      "paid_at": "2026-08-19T14:22:07+00:00"
    },
    {
      "name": "Not***",
      "product": "Legendary Key",
      "paid_at": "2026-08-19T11:04:51+00:00"
    }
  ]
}
```

### GET /v1/shops/{token}/top-customers

Leaderboard: `{customers:[{name, orders, spent}], period, metric}`. Names masked, `spent` a decimal string. `metric=spent` (default) or `orders`; `period=day|week|month|year|all`, default `month`; `limit` 1–25, default 5. An unrecognised period falls back to `month` rather than erroring.

_Auth: No API key_

Required: `token`. Optional: `period`, `metric`, `limit`.

```bash
curl https://api.kantopay.com/v1/shops/{token}/top-customers
```

Responses:
- `200`: Grouped by lowercased buyer name over paid, non-test, non-reversed orders. `limit` defaults to 5, clamped 1..=25. `spent` is a decimal STRING, never a float
- `200`: ?period=all&metric=orders — period is echoed back after normalisation (day | week | month | year | all; anything else silently becomes month) and metric is "orders" only when passed exactly, else "spent". This shop has no paid orders yet
- `400 invalid_query`: `limit` is not a non-negative integer (e.g. ?limit=abc)
- `404 shop_not_found`: Token matches no open shop
- `500 internal_error`: No DB pool configured, a database error on the aggregate query, or the blocking task was cancelled

```json
{
  "customers": [
    {
      "name": "Ste***",
      "orders": 3,
      "spent": "900.00"
    },
    {
      "name": "Not***",
      "orders": 1,
      "spent": "50.00"
    }
  ],
  "period": "month",
  "metric": "spent"
}
```

### GET /v1/shops/{token}/revenue

Total paid revenue for a period — the number behind a goal bar. `{revenue, currency, period}`, revenue a decimal string. `period=day|week|month|year|all`, default `month`. Test orders excluded.

_Auth: No API key_

Required: `token`. Optional: `period`.

```bash
curl https://api.kantopay.com/v1/shops/{token}/revenue
```

Responses:
- `200`: Sum of paid, non-test, non-reversed orders for the period. `revenue` is a decimal string; `period` is echoed back after normalisation, so ?period=nonsense answers "month"
- `200`: Published shop with nothing sold in the period (live, default period)
- `400 invalid_query`: `limit` is not a non-negative integer (the shared FeedQuery is parsed even though revenue ignores limit — e.g. ?limit=-1)
- `404 shop_not_found`: Token matches no open shop
- `500 internal_error`: No DB pool configured, a database error on the SUM query, or the blocking task was cancelled

```json
{
  "revenue": "1250.00",
  "currency": "PHP",
  "period": "month"
}
```

### GET /v1/shops/{token}/giftcards

The denominations you sell (each `amount` in pesos, as a string), plus your gift-card `settings` (the custom amount range). Gift cards never expire. `POST` the same path with `amount`, `buyer_name` and `recipient_email` to sell one; `GET /giftcards/check?code=` returns a balance. The smallest card is ₱20.

_Auth: No API key_

Required: `token`.

```bash
curl https://api.kantopay.com/v1/shops/{token}/giftcards
```

Responses:
- `200`: Published shop. `settings` is the seller's stored giftcard_settings JSON verbatim (null if never configured); this shop sells no fixed denominations
- `200`: Shop with active gift-card denominations, ordered by amount ascending; `label` is null when the seller left it blank
- `404 shop_not_found`: Token matches no open shop. This used to be a 200 carrying {"denominations":[],"settings":null} — byte-identical to a real shop selling no gift cards
- `500 internal_error`: No DB pool configured, a database error on the denominations/settings query, or the blocking task was cancelled
- `503 service_unavailable`: Connection pool exhausted under load (r2d2 → AuthError::PoolExhausted, surfaced through this handler's e.to_response() arm) (`Retry-After: 2`)

```json
{
  "denominations": [],
  "settings": {
    "allowCustom": true,
    "customMax": null,
    "customMin": null,
    "emailNote": null
  }
}
```

---

## Which API to use

Use the Storefront API in anything players can see, such as a website. Use the Server API on machines you control: your game server or your own backend.

### Choosing an API

There is one API with a public half and a private half. The **Storefront API** is every path under `/v1/shops/` and `/v1/orders/`; it needs no credential, and a key holder can call it too. The **Server API** is everything else (`/server`, `/rewards`, `/payments`, `/accounts`, `/items`, `/players`) and needs your key. What decides which you use is where your code runs.

> **Can the machine running this code keep a secret?**

> **Yes** (your game server, your backend, a bot you host): use your `kp_` key, kept in an environment variable such as a `.env` file.

> **No** (a static site, a browser, a game client, anything you ship to players): use the Storefront API only. It needs no backend. A `kp_` key in a web page hands every visitor your orders, your buyers’ emails and your wallet.

Most stores use both: a website that sells through the Storefront API and the plugin on each server that delivers with a key. Both have [test orders](https://kantopay.com/documents#storefront-test).

### Capabilities

**The Server API does everything the Storefront API does, and more:** what each player owns and what has expired, every order with real buyer names, your wallet, reward delivery, and coupon and gift-card admin. Products, prices and reward commands are set in the dashboard; neither API can change them.

| Action | Storefront API | Server API | Dashboard |
| --- | --- | --- | --- |
| [Run from a static site, no backend](https://kantopay.com/documents#storefront-quickstart) | Yes | No: needs a server that keeps the key in `.env` | — |
| [Browse products](https://kantopay.com/documents#ep-v1products) | Yes | Yes | Yes |
| [Price carts and create orders](https://kantopay.com/documents#storefront-quickstart) | Yes | Yes | Yes |
| [View player purchases](https://kantopay.com/documents#ep-splayer) | Player’s own link | By player name | Yes |
| [Deliver rewards](https://kantopay.com/documents#ep-rpending) | No | Yes | View / retry |
| [View wallet and transactions](https://kantopay.com/documents#ep-wallet) | No | Yes | Yes |
| [Manage coupons and gift cards](https://kantopay.com/documents#store-admin) | No | Yes | Yes |
| Edit products, prices, and reward commands | No | No | Yes |
| Configure payouts and cash out | No | No | Yes |

**View all capabilities**

| Action | Storefront API | Server API | Dashboard |
| --- | --- | --- | --- |
| Buying |
| [Browse products, prices, sales and categories](https://kantopay.com/documents#ep-v1products) | Yes | Yes | Yes |
| [Read your pages and category artwork](https://kantopay.com/documents#ep-v1pages) | Yes | Use the Storefront API | Yes |
| [Price a cart (coupons, gift cards, upgrade tiers)](https://kantopay.com/documents#ep-v1quote) | Yes | Yes | Yes |
| [Create an order](https://kantopay.com/documents#ep-scheckout) | Yes | Yes | Yes |
| [Buy a gift card, check its balance](https://kantopay.com/documents#ep-v1gcbuy) | Yes | Yes | Yes |
| [Check a coupon code](https://kantopay.com/documents#ep-v1coupon) | Yes | Yes | Yes |
| [Cancel an unpaid order](https://kantopay.com/documents#ep-v1cancel) | With its cancel token | Any unpaid order | Yes |
| [Make test orders](https://kantopay.com/documents#storefront-test) | Test token | Test server key | Yes |
| Orders and players |
| [Look up an order](https://kantopay.com/documents#ep-plist) | By order id | All orders, searchable | Yes |
| [See what a player has paid for](https://kantopay.com/documents#ep-splayer) | Player’s own link | By player name | Yes |
| [See what a player owns now, and what expired](https://kantopay.com/documents#ep-splayer) | No | Yes | Order list only |
| [Read a player’s receipts, refunds included](https://kantopay.com/documents#ep-ppurchases) | No | Yes | Yes |
| [Recent payments](https://kantopay.com/documents#ep-srecent) | Names masked | Yes | Yes |
| [Top customers](https://kantopay.com/documents#ep-stop) | Names masked | Yes | Yes |
| [Revenue and goals](https://kantopay.com/documents#ep-sgoal) | Total only | Yes, with CSV | Yes |
| [Get told when an order is paid](https://kantopay.com/documents#webhooks) | No | Yes, by webhook | Set up here |
| Money |
| [View wallet and transactions](https://kantopay.com/documents#ep-wallet) | No | Yes | Yes |
| Configure payouts and cash out | No | No | Yes |
| In game |
| [Deliver rewards](https://kantopay.com/documents#ep-rpending) | No | Yes | View / retry |
| [Take back refunded or expired rewards](https://kantopay.com/documents#ep-rrevoke) | No | Yes | View |
| [Send a player a sign-in link](https://kantopay.com/documents#ep-plink) | No | Yes | No |
| [Read captured items](https://kantopay.com/documents#ep-items) | No | Yes | Yes |
| [Save or delete captured items](https://kantopay.com/documents#item-catalog) | No | Yes | No |
| Report Bedrock players and who joined | No | Yes | No |
| [Keep an in-game audit log](https://kantopay.com/documents#ep-audit) | No | Yes | View |
| Store administration |
| [Manage coupons](https://kantopay.com/documents#ep-coupons-list) | No | Yes | Yes |
| [Manage gift-card amounts, void a card](https://kantopay.com/documents#ep-gcdenoms) | No | Yes | Yes |
| In-game menus | No | Read only | Yes |
| Edit products, prices, and reward commands | No | No | Yes |
| Design your storefront | No | No | Yes |

> **Why the catalogue is read-only everywhere but the dashboard.** A caller that could name its own price could charge ₱1 for a ₱1,000 rank, and a caller that could attach its own commands could grant itself anything your server can run. Both are worth more to an attacker than any product in your store. Every order goes through a `product_id` you created, so the name, price, sale, description and reward commands come off *your* row — not off the request.

> The practical consequence: **set your products up in the dashboard once**, then read them with [`GET /v1/shops/{token}/products`](https://kantopay.com/documents#ep-v1products). If you need to bulk-import hundreds of products, tell us — that is a dashboard import, not an API capability.

### Why a storefront token

> **Why a token and not your slug?** Two things a slug cannot do. It can be **rotated** — if someone abuses your token you regenerate it and their copy dies instantly, whereas your slug is your public address and can never change without breaking every link ever shared. And it cannot be **guessed** — keying this API on short public slugs would let anyone walk a dictionary and bulk-harvest every shop on the platform: catalogues, revenue figures, top buyers, all as cross-origin JSON.

> The token is *not* a secret. It ships inside your own page’s JavaScript, the way a public storefront token does on other commerce platforms. It is an identifier you can revoke, not a password. Your slug still addresses the hosted store at `/shop/your-slug`, as it always has.

---

## Server API

Everything the Storefront API sells, plus what only your server should see: what each player owns, every order, your wallet and reward delivery. Requests need a secret API key, so never put one in a browser or a game client.

### Your first request

The Server API needs a server of its own (your game server’s plugin, a backend, a bot you host) because the key must stay secret. Create a key in [Dashboard › Servers](https://kantopay.com/dashboard/servers), one per game server, and keep it in an environment variable, for example a `.env` file your server loads. Never commit that file or put the key in a web page.

```
# .env  (add it to .gitignore)
KANTOPAY_API_KEY=kp_live_…
```

```
curl https://api.kantopay.com/rewards/info \
  -H "Authorization: Bearer $KANTOPAY_API_KEY"
```

From there, sell with [`POST /server/checkout`](https://kantopay.com/documents#ep-scheckout) and deliver with [`/rewards/pending`](https://kantopay.com/documents#ep-rpending). The KantoPay plugin does both for you.

### Authentication

Create an API key in your [dashboard](https://kantopay.com/dashboard) (each key is bound to one server) and send it on every request as *either* header:

`Authorization: Bearer kp_live_…` or `X-API-Key: kp_live_…`

Each endpoint is tagged with who may call it:

**API key only**: server-to-server operations (reward delivery, in-game payments, player lookup). Requires an API key; nothing else can call it.
 **Dual-auth**: “read your own data” endpoints (product catalog, payments, wallet) that the dashboard also uses internally. **Your API key works exactly the same way**, in either header, and counts against the same per-key limit. The tag only means the endpoint is shared with the dashboard, so you call it just like the others.

So from your code the rule is simple: **always send your API key**. Public `/pay/{link_id}` status endpoints need no auth at all.

**Test server keys** start `kp_test_`. They make [test orders](https://kantopay.com/documents#storefront-test) and receive test deliveries only, and they can call the reward routes (`/rewards/…`), `POST /payments/from-product`, `POST /server/quote`, `POST /server/checkout`, and the product catalog, menu and item reads. Any other endpoint answers `403 test_key_not_allowed`.

### How requests work

Each endpoint shows its method (`GET`, `POST`, `PUT` or `DELETE`); all are HTTPS. Reads take their arguments in the **path** (an identifier that is part of the address, like the player in `/server/players/{name}`) or the **query string** (everything optional). Writes take a JSON body and need `Content-Type: application/json`. A body sent on a `GET` is ignored. An unknown query parameter is ignored rather than rejected, so adding one to a URL is never how a request breaks.

**Out-of-range numbers are clamped, not rejected.** `limit=9999` gives you the maximum; `limit=-5` gives you one. That is deliberate — a plugin polling in a loop should degrade to a sensible answer rather than start failing. But a value that is not a number at all, like `limit=abc`, *is* rejected with `400 invalid_query`, because there is nothing sensible to clamp it to.

| Parameter | Where | Default | Range |
| --- | --- | --- | --- |
| `limit` on `/server/recent-payments` | query | 20 | 1–100, clamped |
| `limit` on `/server/top-customers` | query | 10 | 1–100, clamped |
| `offset` | query | 0 | 0–100000, clamped |
| `period` | query | varies — see [periods](https://kantopay.com/documents#server-periods) | `day week month year all`; anything else falls back to the default |
| `metric` | query | `spent` | `spent` or `orders` |
| `target` | query | none | any positive number; omit it and `progress` comes back `null` |
| `include_test` | query | `false` | `true` to include [test orders](https://kantopay.com/documents#storefront-test) |
| `name` | path | — | 1–64 chars; URL-encode it |

**Paging.** Ask for `limit`, and if `has_more` is `true` send `next_offset` back as `offset`. `has_more` is measured by fetching one row more than you asked for, so it is never a guess. Rows are ordered newest-paid first; a sale landing mid-pagination can shift a row between pages, which is fine for a feed and not something to build an audit on.

**Types.** Money is a JSON *number* (`400.0`) on the `/server/*` reads (players, recent payments, top customers, goal) and on analytics. It is a *string* (`"400.00"`) on the wallet, the order lists, the catalogue, `/payments/from-product`, and everything shared with the Storefront API: `/server/quote`, `/server/checkout` and the gift-card routes. Each example response shows which. Timestamps are RFC 3339 in **UTC** (`2026-08-19T05:39:40Z`). Booleans are the literal words `true` and `false`. Player names are matched case-insensitively and trimmed, so whatever casing your server holds will match.

**Missing versus empty.** Leaving an optional parameter out and sending it empty (`?period=`) mean the same thing: the default applies. A missing *required* path segment is not a bad request, it is a different route, and comes back `404 no_such_route`.

### Status codes

Read the status first to know *what kind* of problem you have, then the `code` to know which one. These are the common statuses; each endpoint lists its own responses.

| Status | What it means here | What to do |
| --- | --- | --- |
| `200` | It worked. An empty list is still a 200 — a player with no purchases is not an error. | Nothing. Check `found` or the array length, not the status. |
| `400` | The request itself is wrong: a malformed query string, an id that is not a UUID, a missing player token. | Fix the call. Retrying unchanged will fail identically. |
| `401` | No key, a key that is not `kp_`-shaped, or one that is unknown or revoked. Only a `401` means the key itself is wrong. | Check the header and the key. Do not retry — nothing about waiting will help. |
| `403` | A test server key (`kp_test_`) called something only a live key may (`test_key_not_allowed`). | Use a live key for it, or leave the call out on a test server. |
| `404` | Either the route does not exist (`no_such_route`) or the thing does not (`product_not_found`, `variant_not_found`, `shop_not_found`). Very different problems, same status. | Read the `code`. `no_such_route` is a typo in your URL; the others mean the record is gone or was never yours. |
| `409` | The request is fine but the state says no: a purchase limit reached, a product outside its opening hours, or the same `idempotency_key` still in flight. | Show `message` to the player. For `idempotency_in_progress`, wait for `Retry-After` and retry with the same key. |
| `422` | The request parsed but a value is unacceptable. Carries a `field` naming which one. | Show `message` against `field`. This is the only status that tells you where to look. |
| `429` | You are over the rate limit. | Wait for `Retry-After`, then retry. Do not tighten your poll loop. |
| `500` | Our bug, not yours. | Retry once with backoff. If it persists, quote the `X-Request-ID` in a ticket. |
| `502` | The payment provider upstream failed or timed out (`provider_unavailable` on `/payments/from-product`, with `Retry-After: 5`). | Retry with backoff. If it was a payment call, reuse the same `idempotency_key` so a retry cannot double-charge. |
| `503` | Temporary: the database is busy, or it could not answer while checking your key. Your key is fine. | Honour `Retry-After`. Treat as "later", never as "failed", and never as a reason to replace the key. |

### Errors

Every failure, on every status, is the same shape. One parser handles all of them.

```
{ "code": "auth_invalid_api_key", "message": "Invalid or expired API key" }
```

`field` is added on `422`, naming the parameter at fault. Branch on `code` — never on `message`, which is written for humans and will be reworded.

| code | HTTP | What it means | What to do |
| --- | --- | --- | --- |
| `auth_missing_api_key` | 401 | No credential arrived at all, on an API-key-only route (`/server/*`, `/rewards/*`). The [dual-auth](https://kantopay.com/documents#ep-catalog) routes run the shared session middleware instead and answer `auth_missing_token` for the same mistake — branch on both if you call across the two families. | Send `Authorization: Bearer kp_…` or `X-API-Key`. If you believe you sent one, check the header name. |
| `auth_invalid_api_key` | 401 | Wrong shape, unknown, or revoked. The message distinguishes format from validity. | Re-copy the key from the dashboard. A revoked key never comes back — make a new one. |
| `test_key_not_allowed` | 403 | A test server key called a route only a live key may: wallet, orders, coupons, gift cards, analytics, item edits, `/players/*`, `/audit`, or `/server/*` other than `/server/quote` and `/server/checkout`. | Skip that call on a test server, or use a live key. |
| `rate_limited` | 429 | Over 120 requests in 60 seconds on this key, counted across every route the key calls. | Back off for `Retry-After`. If you poll several servers, give each its own key. |
| `product_not_found` / `variant_not_found` | 404 | `POST /payments/from-product`: no active product with that id in your store, or that product has no option with that `variant_id`. | Re-read [the catalog](https://kantopay.com/documents#ep-catalog); the product may have been deleted or switched off. |
| `already_owned` | 400 | The player already holds this rank tier, so the upgrade would cost ₱0. | Show `message` to the player. Nothing was created. |
| `no_such_route` | 404 | That path and method combination is not a route. | Check spelling and verb. The message echoes what you asked for. |
| `validation_error` | 422 | A value is unacceptable; `field` names it. | Fix that field. Do not retry unchanged. |
| `invalid_query` | 400 | The query string could not be read — usually a number parameter given a non-number. | Check the types of your query values. |
| `idempotency_in_progress` | 409 | The same idempotency key is being processed right now. | Wait for `Retry-After` (2 seconds), then send the same request with the same key. Never make a new key for it: that can create a second order. |
| `idempotency_key_reuse` | 422 | That key was already used for a *different* cart. | Mint a fresh key. A key is bound to the exact order it first created. |
| `provider_unavailable` | 502 | The payment provider did not answer while `POST /payments/from-product` set up the payment. Nothing was created. | Retry after `Retry-After` (5 seconds) with the same `idempotency_key`. |
| `service_unavailable` | 503 | The database is busy, or could not answer while checking your key. | Honour `Retry-After` and retry. Your key still works. |
| `internal_error` | 500 | Our fault. | Retry once, then report with the `X-Request-ID`. |

Codes you will see in the source but never on this surface — `slug_taken`, `domain_taken`, `upload_quota_exceeded`, `payout_in_flight`, the `ai_*` family — belong to the dashboard’s own signed-in routes. They are left out here on purpose, not by oversight.

### Rate limits

**120 requests per 60 seconds, per key**, on every route a key can call, the dual-auth ones included. The limit is counted before we look your key up, so hammering with a bad key is throttled the same as a good one. Each key is separate: give every game server its own and they will never spend each other’s budget. To refresh a whole lobby’s stats, ask for every player in one [`GET /server/players?names=`](https://kantopay.com/documents#ep-splayers) call rather than one call each, so your delivery polls keep their share. The storefront half is limited differently — per IP, per endpoint — see [its own errors section](https://kantopay.com/documents#storefront-errors).

Two headers are worth reading on every response:

| Header | On | Why you want it |
| --- | --- | --- |
| `X-Request-ID` | every response, refusals included | A unique id for that one request, and the id on our own log line for it. Log it. It is the fastest way for us to find what happened when you report something. Send your own (up to 128 visible characters, no `"`) and it is kept; anything else gets a fresh one. |
| `Retry-After` | `429`, `503`, `409 idempotency_in_progress` and `502 provider_unavailable` | Seconds to wait. Honour it instead of guessing — a fixed retry delay either gives up too early or hammers a service that is already struggling. |

Both are listed in `Access-Control-Expose-Headers`, so `res.headers.get('retry-after')` works from a browser too — though a browser has no business holding a `kp_` key.

### Reporting periods

`period` is a **calendar** window, not a rolling one. `month` is “since the 1st”, not “the last 30 days” — so it *resets* on a boundary rather than trailing behind you. These are the same windows the goal bar and the top-customer list on your own storefront already use. The same window does not always mean the same total: some endpoints leave out refunds or count customers by who received the goods, and each one says so.

| `period` | Covers | Resets |
| --- | --- | --- |
| `day` | Since midnight | Every midnight |
| `week` | Since Monday | Every Monday 00:00 |
| `month` | Since the 1st | The 1st of each month |
| `year` | Since 1 January | 1 January |
| `all` | Everything, ever | Never |

**Those boundaries are UTC**, because that is the database’s clock. If you are in the Philippines that is **8am your time**: a `day` runs 8am to 8am, and a `month` turns over at 8am on the 1st. Worth knowing before you wire a daily goal to a scoreboard and wonder why it clears mid-morning.

**Defaults differ, on purpose.** `/server/goal` defaults to `month`, matching the goal bar on your storefront, so a plugin that passes no period agrees with your page without being told. `/server/recent-payments` and `/server/top-customers` default to `all`, matching their storefront twins. An unrecognised value (a typo like `moth`) falls back to **that endpoint’s own default** rather than returning an error — a plugin polls in a loop, and a typo should not stop delivery. Every response echoes the `period` it actually used, so you never have to guess which one you got.

One thing `period` never does: bring back refunded money. Charged-back, refunded, disputed and voided orders are excluded from every window.

### GET /server/players/{name}

**What a player is to your shop, right now** — the call to make on player-join. The storefront half cannot answer this: a browser can type any name into a query string, so the Storefront API demands that player’s own token first. Your key already proves you are the server they play on. `found` is explicit rather than inferred from `orders > 0`, so “never bought” stays distinguishable from “bought nothing yet”. `purchases` is rolled up *per product* with quantities summed across orders, not one row per order. `owned` is keyed by `cumulative_group` and holds only the **top tier** in each (the lowest `rank_order`: tier 1 is the dearest) — a player who bought Diamond and then upgraded to Emerald is Emerald, not both, which is what a permissions plugin is really asking. A **timed** product (one that removes itself after N days) counts in `owned` only while its time runs: each purchase carries `active` (`false` once every purchase of it has expired; a renewal keeps it `true`) and `expires_at` (when the latest purchase runs out, `null` for a permanent product). Matching is case-insensitive and follows the *delivered-to* identity, so a gift counts for the recipient. Refunded, charged-back and test orders are excluded. For the raw receipt log instead, see `/players/{name}/purchases`.

_Auth: API key only_

Required: `name`. Optional: `include_test`.

```bash
curl https://api.kantopay.com/server/players/Notch \
  -H "Authorization: Bearer kp_live_•••"
```

Responses:
- `200`: Valid kp_ key, player has bought something. active is false once a timed product's time has run out on every purchase of it, and such a product is left out of owned; expires_at is null for a permanent product.
- `200`: Valid key, no orders match that name (still 200 — `found` is the signal, not a 404)
- `400 invalid_query`: A query value will not parse — `?limit=abc`, `?offset=-1`, `?include_test=maybe`
- `401 auth_missing_api_key`: No Authorization / X-API-Key header
- `401 auth_invalid_api_key`: Key does not start with kp_ (e.g. `Authorization: Bearer nope`)
- `401 auth_invalid_api_key`: Well-formed kp_ key that is unknown or revoked
- `422 validation_error`: `{name}` trims to empty (e.g. `/server/players/%20`) or is longer than 64 chars
- `429 rate_limited`: More than 120 requests in 60s on this API key (`Retry-After: 60`)
- `503 service_unavailable`: No DB connection free, or the database did not answer while checking the key. Retry after Retry-After: the key is fine (before 2026-10-04 a failed key check answered 401). (`Retry-After: 2`)

```json
{
  "player": "Notch",
  "found": true,
  "orders": 3,
  "spent": 650.0,
  "first_paid_at": "2026-07-14T09:12:44.318471+00:00",
  "last_paid_at": "2026-08-18T16:03:07.902114+00:00",
  "purchases": [
    {
      "product_id": "bbbbbbbb-2222-4222-8222-222222222222",
      "product": "VIP Rank",
      "quantity": 1,
      "spent": 300.0,
      "last_paid_at": "2026-08-18T16:03:07.902114+00:00",
      "cumulative_group": "ranks",
      "active": true,
      "expires_at": "2026-09-17T16:03:07.902114+00:00"
    },
    {
      "product_id": "aaaaaaaa-1111-4111-8111-111111111111",
      "product": "Legendary Key",
      "quantity": 7,
      "spent": 350.0,
      "last_paid_at": "2026-07-14T09:12:44.318471+00:00",
      "cumulative_group": null,
      "active": true,
      "expires_at": null
    }
  ],
  "owned": {
    "ranks": {
      "product_id": "bbbbbbbb-2222-4222-8222-222222222222",
      "product": "VIP Rank",
      "rank_order": 2
    }
  }
}
```

### GET /server/players

**The same answer for many players in one request**, for a server refreshing everyone online. `names` is a comma-separated list: each name is trimmed, a repeat in any casing is asked once, and at most **50** are allowed. Returns `{ "players": [ … ] }`, one [`/server/players/{name}`](https://kantopay.com/documents#ep-splayer) answer per name, in the order you asked; `include_test` works as it does there. The whole call counts once against your key’s 120 a minute. No names, more than 50, or a name over 64 characters answers `422 validation_error` with `field: "names"`.

_Auth: API key only_

Required: `names`. Optional: `include_test`.

```bash
curl https://api.kantopay.com/server/players?names=Notch%2CSteve \
  -H "Authorization: Bearer kp_live_•••"
```

Responses:
- `200`: ?names=Notch,Herobrine — one /server/players/{name} answer per name, in the order asked. A name with no orders is still listed, with found false.
- `400 invalid_query`: include_test will not parse, e.g. ?include_test=maybe
- `401 auth_invalid_api_key`: A kp_ key that is unknown or revoked. No key at all is auth_missing_api_key, as on /server/players/{name}.
- `403 test_key_not_allowed`: A test server key (kp_test_): /server/* acts on the real store
- `422 validation_error`: No names, more than 50 different names, or a name over 64 characters
- `429 rate_limited`: More than 120 requests in 60s on this API key. One call counts once, however many names it asks for. (`Retry-After: 60`)
- `503 service_unavailable`: No DB connection free, or the database did not answer while checking the key. Retry after Retry-After: the key is fine. (`Retry-After: 2`)

```json
{
  "players": [
    {
      "player": "Notch",
      "found": true,
      "orders": 1,
      "spent": 300.0,
      "first_paid_at": "2026-08-18T16:03:07.902114+00:00",
      "last_paid_at": "2026-08-18T16:03:07.902114+00:00",
      "purchases": [
        {
          "product_id": "bbbbbbbb-2222-4222-8222-222222222222",
          "product": "VIP Rank",
          "quantity": 1,
          "spent": 300.0,
          "last_paid_at": "2026-08-18T16:03:07.902114+00:00",
          "cumulative_group": "ranks",
          "active": true,
          "expires_at": null
        }
      ],
      "owned": {
        "ranks": {
          "product_id": "bbbbbbbb-2222-4222-8222-222222222222",
          "product": "VIP Rank",
          "rank_order": 2
        }
      }
    },
    {
      "player": "Herobrine",
      "found": false,
      "orders": 0,
      "spent": 0.0,
      "first_paid_at": null,
      "last_paid_at": null,
      "purchases": [],
      "owned": {}
    }
  ]
}
```

### GET /server/recent-payments

Your own order feed, **unmasked**. The storefront twin runs every name through a mask (`No•••`) because buyers are free text with no account and never agreed to a public listing — here the caller is you, reading your own records. `player` is the delivered-to identity (gift recipient, else buyer): that is who to give it to. `has_more` is measured by fetching one extra row, not guessed. Refunded, charged-back and test orders are excluded unless you ask for test.

_Auth: API key only_

No required parameters. Optional: `limit`, `offset`, `period`, `include_test`.

```bash
curl https://api.kantopay.com/server/recent-payments?limit=20 \
  -H "Authorization: Bearer kp_live_•••"
```

Responses:
- `200`: Valid kp_ key (default limit 20, period `all`)
- `200`: Valid key, more rows exist beyond `limit` (has_more measured with a +1 row)
- `400 invalid_query`: A query value will not parse — `?limit=abc`, `?offset=-1`. Note an unknown `?period=` is NOT an error: it falls back to `all` and is echoed back
- `401 auth_missing_api_key`: No Authorization / X-API-Key header
- `401 auth_invalid_api_key`: Key does not start with kp_
- `401 auth_invalid_api_key`: Well-formed kp_ key that is unknown or revoked
- `429 rate_limited`: More than 120 requests in 60s on this API key (`Retry-After: 60`)
- `503 service_unavailable`: No DB connection free, or the database did not answer while checking the key. Retry after Retry-After: the key is fine (before 2026-10-04 a failed key check answered 401). (`Retry-After: 2`)

```json
{
  "payments": [
    {
      "id": "7c1f0a44-9d2b-4e51-9f0c-2b6c9a1d3e77",
      "player": "Notch",
      "buyer_name": "Notch",
      "recipient_name": null,
      "product": "VIP Rank",
      "amount": 300.0,
      "method": "gcash",
      "paid_at": "2026-08-18T16:03:07.902114+00:00",
      "is_test": false
    },
    {
      "id": "1a8e5b20-3c47-4a19-b8d2-55f0c7e94a10",
      "player": "Steve",
      "buyer_name": "Notch",
      "recipient_name": "Steve",
      "product": "Legendary Key",
      "amount": 50.0,
      "method": "maya",
      "paid_at": "2026-08-17T11:41:52.007336+00:00",
      "is_test": false
    }
  ],
  "period": "all",
  "has_more": false,
  "next_offset": null
}
```

### GET /server/top-customers

Your biggest supporters. Grouped on the **delivered-to** identity, so a player who was gifted five ranks is credited with them — the storefront twin groups on the buyer and masks the name, which is right for a public leaderboard and wrong for a plugin handing out perks. Refunded, charged-back and test orders are excluded. `limit` is **10 by default** (1–100, clamped rather than rejected — `limit=500` returns 100, not an error), so a plain call already gives you the top 10. `period` narrows the window and is a [calendar period](https://kantopay.com/documents#server-periods): `?period=month&limit=10` is your top 10 *this month*, resetting on the 1st.

_Auth: API key only_

No required parameters. Optional: `limit`, `metric`, `period`, `include_test`.

```bash
curl https://api.kantopay.com/server/top-customers?limit=10 \
  -H "Authorization: Bearer kp_live_•••"
```

Responses:
- `200`: Valid kp_ key (default limit 10, metric `spent`, period `all`)
- `200`: Valid key, seller has no kept (paid, non-reversed) orders in the window
- `400 invalid_query`: A query value will not parse — `?limit=abc`. An unknown `?metric=` silently means `spent`; an unknown `?period=` silently means `all`
- `401 auth_missing_api_key`: No Authorization / X-API-Key header
- `401 auth_invalid_api_key`: Key does not start with kp_
- `401 auth_invalid_api_key`: Well-formed kp_ key that is unknown or revoked
- `429 rate_limited`: More than 120 requests in 60s on this API key (`Retry-After: 60`)
- `503 service_unavailable`: No DB connection free, or the database did not answer while checking the key. Retry after Retry-After: the key is fine (before 2026-10-04 a failed key check answered 401). (`Retry-After: 2`)

```json
{
  "customers": [
    {
      "player": "Notch",
      "orders": 5,
      "spent": 950.0,
      "first_paid_at": "2026-06-02T04:18:11.442907+00:00",
      "last_paid_at": "2026-08-18T16:03:07.902114+00:00"
    },
    {
      "player": "Steve",
      "orders": 2,
      "spent": 350.0,
      "first_paid_at": "2026-07-14T09:12:44.318471+00:00",
      "last_paid_at": "2026-08-17T11:41:52.007336+00:00"
    }
  ],
  "period": "all"
}
```

### GET /server/goal

Revenue for a window, and progress toward a target — for an in-game goal bar, a scoreboard or a Discord status. The storefront’s goal block does this arithmetic in the browser against `/shop/{slug}/revenue`; a plugin has no page section to read the target from, so pass `target` and get `progress` back. `progress` is capped at 100 so a bar can render it directly, while `revenue` stays uncapped if you would rather say “142% of goal” yourself. Defaults to `month` — the same window your storefront goal bar uses — and an unrecognised value falls back to that default rather than erroring, because this sits in a poll loop. See [when periods reset](https://kantopay.com/documents#server-periods). **Unlike the storefront source, this excludes reversals** — money you refunded is not money you made.

_Auth: API key only_

No required parameters. Optional: `period`, `target`, `include_test`.

```bash
curl https://api.kantopay.com/server/goal?period=month&target=5000 \
  -H "Authorization: Bearer kp_live_•••"
```

Responses:
- `200`: Valid kp_ key with `?target=5000&period=month`
- `200`: Valid kp_ key, no `target` passed (or target <= 0 / non-finite — it is dropped, not rejected)
- `400 invalid_query`: A query value will not parse — `?target=abc`, `?limit=abc`. An unknown `?period=` is not an error: it falls back to `month`
- `401 auth_missing_api_key`: No Authorization / X-API-Key header
- `401 auth_invalid_api_key`: Key does not start with kp_
- `401 auth_invalid_api_key`: Well-formed kp_ key that is unknown or revoked
- `429 rate_limited`: More than 120 requests in 60s on this API key (`Retry-After: 60`)
- `503 service_unavailable`: No DB connection free, or the database did not answer while checking the key. Retry after Retry-After: the key is fine (before 2026-10-04 a failed key check answered 401). (`Retry-After: 2`)

```json
{
  "period": "month",
  "revenue": 3150.0,
  "orders": 11,
  "target": 5000.0,
  "progress": 63.0
}
```

### POST /server/quote

The storefront’s cart total, with your key instead of the public token: same body and same answer as [`/v1/shops/{token}/quote`](https://kantopay.com/documents#ep-v1quote), through the one pricing path every checkout uses — quantities, variants, cumulative tier credit, a coupon and a gift card. Read-only, like its twin.

_Auth: API key only_

Required: `items`. Optional: `player_name`, `promo_code`, `gift_card_code`.

```bash
curl -X POST https://api.kantopay.com/server/quote \
  -H "Authorization: Bearer kp_live_•••" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "product_id": "11111111-1111-1111-1111-111111111111",
      "quantity": 1
    }
  ],
  "player_name": "Steve_PH"
}'
```

Responses:
- `200`: Cart priced. Read-only: no coupon is redeemed and no gift card is drawn. An unusable promo/gift-card code is reported per field, not as an error. lines add up to subtotal; payment_methods is what checkout will offer for total; blocked is null or the 409 checkout would give.
- `200`: Priced, but checkout would refuse it: blocked carries the exact 409 code and message (a purchase limit reached, or a product outside its opening hours). Show the message and keep Pay disabled.
- `400 cart_empty`: items is present but an empty array. Omitting it is a different failure — see invalid_json — because items carries no serde default and is rejected before this handler runs.
- `400 invalid_product`: A cart line's product_id is not a UUID, or is not an active product of this shop. Variants are not validated. A variant_id that is malformed, unknown, or belongs to a different product is silently ignored: the line falls back to the parent product's price and its name (shop.rs:5390 and 5435), so you get 200 with the base product rather than this 400. The order stays self-consistent - you are not charged for one thing and given another - but a client sending a stale variant id is never told, and the buyer receives the base item they did not pick. quantity is clamped to 1-100, never rejected.
- `400 cart_too_large`: More than MAX_CART_ITEMS (50) distinct lines in items
- `400 already_owned`: A cumulative-group product the player already owns outright (upgrade price would be ₱0)
- `400 invalid_json`: Body is not valid JSON, or a required field is absent. items (types.rs:593) and a cart line's product_id/quantity (types.rs:575-579) have no serde default, so omitting any of them lands here, not on cart_empty.
- `401 invalid_player_token`: player_token in the body does not verify for this shop
- `404 no_such_route`: Wrong verb or a misspelt path under /v1/shops/{token} — caught by that scope's own fallback. (The bare /v1 catch-all only sees mistyped scopes like /v1/shpos/.)
- `413 payload_too_large`: The JSON body is over the 2 MiB limit. (`X-Max-Body-Bytes: 2097152`)
- `415 unsupported_media_type`: Missing or non-JSON Content-Type
- `429 rate_limited`: More than 60 quotes per minute per IP (shared quote bucket) (`Retry-After: 60`)
- `500 internal_error`: Pricing failed — DB error or the blocking task was cancelled (catch-all arm of cart_quote_inner)
- `401 auth_missing_api_key`: No key on the request.

```json
{
  "subtotal": "350.00",
  "discount": "70.00",
  "coupon_ok": true,
  "coupon_message": null,
  "gift_card_applied": "0",
  "gift_card_ok": false,
  "gift_card_message": null,
  "total": "280.00",
  "min_charge": "1",
  "below_minimum": false,
  "free_order": false,
  "lines": [
    {
      "product_id": "bbbbbbbb-2222-4222-8222-222222222222",
      "name": "VIP Rank",
      "quantity": 1,
      "amount": "300.00"
    },
    {
      "product_id": "aaaaaaaa-1111-4111-8111-111111111111",
      "name": "Legendary Key",
      "quantity": 1,
      "amount": "50.00"
    }
  ],
  "payment_methods": ["qrph", "gcash", "card"],
  "is_test": false,
  "blocked": null
}
```

### POST /server/checkout

Create a whole-cart order, with the same body and the same answer as [`/v1/shops/{token}/checkout`](https://kantopay.com/documents#ep-v1checkout): many products, quantities, variants, a coupon, a gift card, a gift recipient. [`/payments/from-product`](https://kantopay.com/documents#ep-pfromproduct) sells one product per call; this one takes the whole cart. Show the player `redirect_url`, the pay page’s full address (as a QR map or a clickable chat link), and poll [`GET /v1/orders/{id}`](https://kantopay.com/documents#ep-v1order). A test server’s key (`kp_test_`) makes test orders here, as it does on `/payments/from-product`; a live key **creates a real order.**

_Auth: API key only_

Required: `items`, `player_name`. Optional: `buyer_email`, `gift_recipient`, `promo_code`, `gift_card_code`.

```bash
curl -X POST https://api.kantopay.com/server/checkout \
  -H "Authorization: Bearer kp_live_•••" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "product_id": "11111111-1111-1111-1111-111111111111",
      "quantity": 1
    }
  ],
  "player_name": "Steve_PH"
}'
```

Responses:
- `200`: Order created. Send the buyer to redirect_url (our /pay/{id} page as a full address, on the host you called) and poll GET /v1/orders/{order_id}. redirect is the same page as a path. Keep cancel_token if the buyer may cancel: POST /v1/orders/{id}/cancel needs it, and only this answer has it.
- `200`: Idempotent replay: the same idempotency_key with the same cart already created an order. Same body as the first call plus the replay header — no second order, no second charge. (`Idempotent-Replay: true`)
- `200`: Paid in full by a gift card, a 100% coupon, or the two together. The order is created, settled and delivered inline, with no payment provider involved, and answers the same JSON; its /pay/ page is already the receipt. Until 2026-10-04 a gift card's answer was a 303 a cross-origin fetch could not follow, and a coupon's was 400 cart_total_zero.
- `400 player_name_required`: player_name is blank after cleaning, or longer than 64 chars (required for checkout, unlike /quote)
- `400 cart_empty`: items is present but an empty array. Omitting it is a different failure — see invalid_json — because items carries no serde default and is rejected before this handler runs.
- `400 invalid_product`: A cart line's product_id is not a UUID, or is not an active product of this shop. Variants are not validated. A variant_id that is malformed, unknown, or belongs to a different product is silently ignored: the line falls back to the parent product's price and its name (shop.rs:5390 and 5435), so you get 200 with the base product rather than this 400. The order stays self-consistent - you are not charged for one thing and given another - but a client sending a stale variant id is never told, and the buyer receives the base item they did not pick. quantity is clamped to 1-100, never rejected.
- `400 cart_too_large`: More than MAX_CART_ITEMS (50) distinct lines in items
- `400 already_owned`: A cumulative-group product the player already owns outright
- `400 coupon_rejected`: promo_code exists but is unusable for this cart. Unlike /quote, checkout rejects hard; message is the coupon engine's own sentence.
- `400 gift_card_rejected`: gift_card_code exists but is unusable (unknown, void, or no balance)
- `400 below_minimum`: Post-coupon, post-gift-card total is above ₱0 but under the ₱1 order floor (min_charge on GET /v1/shops/{token})
- `429 small_order_rate_limited`: More than 10 orders under ₱20 from the same buyer at this shop within an hour (small_order on GET /v1/shops/{token}). Anonymous orders share one bucket per shop. Retry-After is the seconds until the oldest of those orders leaves the hour (it was a fixed 60 before 2026-10-04). (`Retry-After: 1260`)
- `400 cart_total_zero`: The cart itself is worth ₱0 and no coupon or gift card paid for it, so there is nothing to charge or settle. A cart a coupon or gift card zeroed is settled instead (the 200 above).
- `400 return_url_not_allowed`: return_url is not https, is longer than 500 characters, or is not on one of the store's websites (Your website in the dashboard) or its verified custom domain. Checked before any order is made.
- `400 invalid_json`: Body is not valid JSON, or a required field is absent. items (types.rs:593) and a cart line's product_id/quantity (types.rs:575-579) have no serde default, so omitting any of them lands here, not on cart_empty.
- `401 invalid_player_token`: player_token in the body does not verify for this shop
- `404 no_such_route`: Wrong method — a GET on /checkout hits the /v1 scope fallback, not a 405
- `409 idempotency_in_progress`: Same idempotency_key is still being processed by an in-flight request (`Retry-After: 2`)
- `413 payload_too_large`: The JSON body is over the 2 MiB limit. (`X-Max-Body-Bytes: 2097152`)
- `415 unsupported_media_type`: Missing or non-JSON Content-Type
- `422 idempotency_key_reuse`: Same idempotency_key replayed with a different cart (fingerprint covers buyer name, lines, promo code, gift-card code, gift recipient)
- `429 rate_limited`: More than 30 checkouts per minute per IP (`Retry-After: 60`)
- `500 internal_error`: The provider intent was created but the order row could not be written; the idempotency reservation is released so an immediate retry works. (Sibling messages from the same handler: "Error processing request.", "Couldn't apply that code.", "Couldn't apply that gift card.", "Failed to complete order.")
- `502 payment_provider_error`: PayMongo did not answer when creating the QRPh intent (after retries). No order was created; the idempotency key is released so a retry is safe.
- `401 auth_missing_api_key`: No key on the request.

```json
{
  "redirect": "/pay/9f1e6c1a-53ab-4d0e-9d2e-1f0c7a4b8e21",
  "redirect_url": "https://api.kantopay.com/pay/9f1e6c1a-53ab-4d0e-9d2e-1f0c7a4b8e21",
  "order_id": "9f1e6c1a-53ab-4d0e-9d2e-1f0c7a4b8e21",
  "cancel_token": "3b6f0c2a9d4e81f75a0c6e2d9b1f4a83c7e5d2016f9a8b3c4d5e6f708192a3b4"
}
```

### GET /server/giftcards

The gift-card denominations you sell and your custom-amount range, as [`/v1/shops/{token}/giftcards`](https://kantopay.com/documents#ep-v1giftcards).

_Auth: API key only_

```bash
curl https://api.kantopay.com/server/giftcards \
  -H "Authorization: Bearer kp_live_•••"
```

Responses:
- `200`: Published shop. `settings` is the seller's stored giftcard_settings JSON verbatim (null if never configured); this shop sells no fixed denominations
- `200`: Shop with active gift-card denominations, ordered by amount ascending; `label` is null when the seller left it blank
- `500 internal_error`: No DB pool configured, a database error on the denominations/settings query, or the blocking task was cancelled
- `503 service_unavailable`: Connection pool exhausted under load (r2d2 → AuthError::PoolExhausted, surfaced through this handler's e.to_response() arm) (`Retry-After: 2`)
- `401 auth_missing_api_key`: No key on the request.
- `403 test_key_not_allowed`: A test server key (kp_test_) called it.

```json
{
  "denominations": [],
  "settings": {
    "allowCustom": true,
    "customMax": null,
    "customMin": null,
    "emailNote": null
  }
}
```

### POST /server/giftcards

Sell a gift card, as [`POST /v1/shops/{token}/giftcards`](https://kantopay.com/documents#ep-v1gcbuy): `amount` must be one of your denominations or inside your custom range. Same answer as its twin; the code is minted when the payment settles. Needs only the shop open, not the hosted storefront on. A test key cannot sell gift cards.

_Auth: API key only_

Required: `amount`. Optional: `buyer_name`, `buyer_email`.

```bash
curl -X POST https://api.kantopay.com/server/giftcards \
  -H "Authorization: Bearer kp_live_•••" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "500.00",
  "buyer_name": "Steve_PH"
}'
```

Responses:
- `200`: Amount accepted and the PayMongo intent + order row were created. Send the buyer to redirect_url. Keep cancel_token if the buyer may cancel.
- `200`: The same idempotency_key and purchase again (a double-tapped Buy): the first order comes back, and no second one is made. (`Idempotent-Replay: true`)
- `400 invalid_name`: buyer_name survives the name allowlist as a multi-byte name whose 40-character cap still exceeds 64 bytes — roughly 33+ Cyrillic or 22+ CJK characters. An all-ASCII name can never reach this branch.
- `400 invalid_amount`: amount is not a decimal, or is <= 0
- `400 denomination_unavailable`: The amount is not an active denomination and custom amounts are off, or it is outside customMin/customMax. A custom amount under ₱20 is refused even when the minimum is blank. The amount is in pesos: 500, not 50000
- `400 return_url_not_allowed`: return_url is not https, is longer than 500 characters, or is not on one of the store's websites or its verified custom domain. Checked before the payment is set up.
- `400 invalid_json`: Body is malformed JSON or missing the required `amount` field — rejected by the app-wide JsonConfig (src/api/extractor_error_json.rs:30, installed in main.rs:357) before the handler runs; `message` carries serde's byte offset
- `413 payload_too_large`: Body exceeds the 2 MiB JSON limit (`X-Max-Body-Bytes: 2097152`)
- `415 unsupported_media_type`: Request sent without Content-Type: application/json
- `429 rate_limited`: More than 20 gift-card buys from this IP in 60s (storefront_limiter, key gc:{ip}); checked first, before anything else (`Retry-After: 60`)
- `500 internal_error`: The shop/denomination lookup itself failed (DB error or blocking pool cancelled)
- `500 internal_error`: The PayMongo intent exists but the INSERT into payment_links failed
- `502 payment_provider_error`: create_qrph_intent to PayMongo failed after retries
- `503 service_unavailable`: No database pool configured/available when the handler asks for one (`Retry-After: 2`)
- `401 auth_missing_api_key`: No key on the request.
- `403 test_key_not_allowed`: A test server key (kp_test_) called it.

```json
{
  "redirect": "/pay/7c1f0e9a-3d2b-4a55-9f11-2c6b8ad4e001",
  "redirect_url": "https://api.kantopay.com/pay/7c1f0e9a-3d2b-4a55-9f11-2c6b8ad4e001",
  "order_id": "7c1f0e9a-3d2b-4a55-9f11-2c6b8ad4e001",
  "cancel_token": "8d2e4f6a0b1c3d5e7f9a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3e4f5a6"
}
```

### GET /server/giftcards/check

A gift-card code’s balance, as [`/v1/shops/{token}/giftcards/check`](https://kantopay.com/documents#ep-v1gcbalance). For every card you have issued at once, see [`/accounts/gift-cards/issued`](https://kantopay.com/documents#ep-gcissued).

_Auth: API key only_

Required: `code`.

```bash
curl https://api.kantopay.com/server/giftcards/check?code=YOUR_CODE \
  -H "Authorization: Bearer kp_live_•••"
```

Responses:
- `200`: Code exists, status is active, has balance left and is not expired
- `200`: No gift card with that code for this shop — an answer, not an error
- `200`: Card exists but is fully spent, voided, or past expires_at (status is reported as `expired` when the date has passed, otherwise the stored value: active | redeemed | void)
- `400 code_required`: ?code= missing or blank — deliberately not reported as valid:false, so a client bug is not mistaken for a rejected card
- `500 internal_error`: Database error, pool exhaustion, or blocking-task cancellation — this handler's catch-all arm collapses all of them into AuthError::Internal, so it never answers 503 here
- `401 auth_missing_api_key`: No key on the request.
- `403 test_key_not_allowed`: A test server key (kp_test_) called it.

```json
{
  "valid": true,
  "remaining": "250.00",
  "status": "active"
}
```

### POST /payments/from-product

**Recommended.** Create a payment from a product you set up in your dashboard. The name, price, description, delivery commands and target servers all come from the product, so the caller can’t set the price. Pass `variant_id` to charge a specific variant; any active sale is applied automatically. Returns a link id, QR and pay URL, with `product_id` recorded on the order.

It follows the web store’s rules. A rank tier is priced as an upgrade: what this player (the `recipient_name`, else `buyer_name`) already paid into that rank ladder comes off, and a tier they already hold answers `400 already_owned`. An upgrade that would cost less than the ₱1 minimum answers `400 below_minimum`, as the cart does. Each command keeps its “player online”, free-slot and delay conditions, so a kit waits for the player as it would after a web purchase. Purchase limits and opening hours answer `409`. An unknown product answers `404 product_not_found`, an unknown variant `404 variant_not_found`. If the payment provider does not answer, you get `502 provider_unavailable` with `Retry-After: 5`; retry with the same `idempotency_key`. A test server key makes a [test order](https://kantopay.com/documents#storefront-test).

_Auth: API key only_

Required: `product_id`. Optional: `variant_id`, `buyer_name`, `recipient_name`, `buyer_email`, `metadata`.

```bash
curl -X POST https://api.kantopay.com/payments/from-product \
  -H "Authorization: Bearer kp_live_•••" \
  -H "Content-Type: application/json" \
  -d '{
  "product_id": "YOUR_PRODUCT_ID",
  "buyer_name": "Steve_PH"
}'
```

Responses:
- `200`: Product resolved and the QRPh intent was created
- `200`: Same idempotency_key replayed with the same order contents (`Idempotent-Replay: true`)
- `400 invalid_json`: Body is not valid JSON, or does not fit the request type
- `401 auth_missing_api_key`: No Authorization / X-API-Key header at all
- `401 auth_invalid_api_key`: Key does not start with kp_ (e.g. a JWT sent here by mistake)
- `401 auth_invalid_api_key`: kp_-prefixed key that is unknown or revoked
- `404 product_not_found`: product_id is not one of your active products (before 2026-10-04 this was auth_not_found, "Account not found")
- `404 variant_not_found`: variant_id is not an option of that product
- `400 already_owned`: A rank tier the player (recipient_name, else buyer_name) already holds: the upgrade price would be ₱0. Checked after an idempotent replay, so retrying a paid order still returns it.
- `400 below_minimum`: The upgrade price is above ₱0 but under the ₱1 minimum for online payment (a ₱100.50 tier over a ₱100 one). Nothing is created.
- `409 closed_now`: A purchase limit is reached, or the product is outside its opening hours. message is written for the player and says when it opens or resets. (When the only thing in the way is this player's own unpaid order for the same product, that order is returned instead, with Idempotent-Replay: true.)
- `409 idempotency_in_progress`: Another request with the same idempotency_key is still in flight (`Retry-After: 2`)
- `413 payload_too_large`: Body larger than the 2 MiB JSON limit (`X-Max-Body-Bytes: 2097152`)
- `415 unsupported_media_type`: Missing or non-JSON Content-Type
- `422 validation_error`: product_id (or variant_id) is not a UUID
- `422 validation_error`: Resolved price (after variant + sale) is <= 0 or > 999999.99
- `422 idempotency_key_reuse`: idempotency_key was already used for a DIFFERENT product/buyer/recipient/email
- `429 rate_limited`: More than 120 requests in 60s on this API key (`Retry-After: 60`)
- `502 provider_unavailable`: PayMongo did not answer, or refused, when the QR payment was set up. Nothing was created and the idempotency key is released, so retry the same key after Retry-After. (Before 2026-10-04 this was a 500 carrying the provider's own text.) (`Retry-After: 5`)
- `503 service_unavailable`: No DB connection free, or the database did not answer while checking the key. Retry after Retry-After: the key is fine. (`Retry-After: 2`)

```json
{
  "id": "9f1c2d84-6b3e-4c7a-9d1b-2e5a7c0f4d33",
  "seller_id": "ea69cd4a-019e-4bf0-85c3-21f48e88e521",
  "product_name": "VIP Rank",
  "amount": "300",
  "status": "active",
  "pay_url": "https://kantopay.com/pay/9f1c2d84-6b3e-4c7a-9d1b-2e5a7c0f4d33",
  "qr_code_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAk4AAAJOCAIAAA…",
  "paymongo_test_url": null,
  "metadata": {
    "commands": [
      "lp user {player} parent set vip"
    ]
  },
  "commands": [
    "lp user {player} parent set vip"
  ],
  "buyer_name": "Steve",
  "delivery_status": null,
  "repeat_unpaid": 0,
  "created_at": "2026-08-20T08:52:14.113402+00:00",
  "expires_at": "2026-08-21T08:52:14.113402+00:00"
}
```

### GET /products/catalog

List your active products so a plugin, in-game menu or custom storefront can show what’s for sale. Each entry has the product’s id, name, price (and sale-adjusted `effective_amount`), description, image and variants. Pair with [`POST /payments/from-product`](https://kantopay.com/documents#ep-pfromproduct) to build your own storefront.

_Auth: Dual-auth_

```bash
curl https://api.kantopay.com/products/catalog \
  -H "Authorization: Bearer kp_live_•••"
```

Responses:
- `200`: Authenticated with a JWT or a kp_ API key
- `401 auth_missing_token`: No Authorization header
- `401 auth_invalid_token`: Bearer token that is not a kp_ key and not a valid JWT
- `401 auth_invalid_api_key`: Bearer kp_… key that is unknown or revoked
- `401 auth_token_revoked`: Valid JWT whose session was revoked (PIN reset, logout-all, deactivation)
- `429 rate_limited`: A kp_ key over 120 requests in 60s, counted across every route it calls (this route had no per-key limit before 2026-10-04) (`Retry-After: 60`)
- `503 service_unavailable`: The database did not answer while checking the kp_ key. Retry after Retry-After: the key is fine (this answered 401 before 2026-10-04). (`Retry-After: 2`)

```json
{
  "products": [
    {
      "id": "aaaaaaaa-1111-4111-8111-111111111111",
      "name": "Legendary Key",
      "amount": "50.00",
      "effective_amount": "50.00",
      "on_sale": false,
      "sale_percent": null,
      "description": "",
      "image_url": "/uploads/b4a72530-51e7-42dc-b8c3-140bf4899c64.png",
      "category": "Keys",
      "icon": null,
      "sort_order": 0,
      "variants": []
    },
    {
      "id": "bbbbbbbb-2222-4222-8222-222222222222",
      "name": "VIP Rank",
      "amount": "300.00",
      "effective_amount": "240.00",
      "on_sale": true,
      "sale_percent": 20,
      "description": "Coloured name, /fly in the hub, 3 extra homes.",
      "image_url": "/uploads/9ff499e1-4edd-4acf-9c13-1190edb4fac0.jpg",
      "category": "Ranks",
      "icon": "DIAMOND",
      "sort_order": 2,
      "variants": [
        {
          "id": "cccccccc-3333-4333-8333-333333333333",
          "name": "30 days",
          "amount": "300.00",
          "effective_amount": "240.00"
        }
      ]
    }
  ]
}
```

### GET /payments/list

List all payments with pagination, newest first. Filters, all optional and combinable: `status` (`active`, `paid`, `expired`, `cancelled`), `from` and `to` on when the order was made, `q` (a name, product, order id or payment reference) and `delivery` (`pending`, `delivered`, `failed` or `none`). `from` and `to` take a date (`2026-10-01`, a whole day in Philippine time, so `to=2026-10-01` includes that day) or a full time (`2026-10-01T08:00:00+08:00`, with the `+` sent as `%2B`). Anything else answers `422 validation_error` naming the field.

_Auth: Dual-auth_

No required parameters. Optional: `page`, `limit`, `status`, `from`, `to`.

```bash
curl https://api.kantopay.com/payments/list?page=1&limit=20 \
  -H "Authorization: Bearer kp_live_•••"
```

Responses:
- `200`: Authenticated; optional page/limit/status/q/delivery filters applied
- `400 invalid_query`: page or limit is not a number (e.g. ?page=abc)
- `401 auth_missing_token`: No Authorization header
- `401 auth_invalid_token`: Bearer token that is not a kp_ key and not a valid JWT
- `401 auth_invalid_api_key`: Bearer kp_… key that is unknown or revoked
- `401 auth_token_revoked`: Valid JWT whose session was revoked
- `422 validation_error`: ?from= or ?to= is neither a date (2026-10-01) nor an RFC 3339 time. (Before 2026-10-04 any from or to answered 500.)
- `429 rate_limited`: A kp_ key over 120 requests in 60s, counted across every route it calls (`Retry-After: 60`)
- `503 service_unavailable`: No DB connection free, or the database did not answer while checking the key. Retry after Retry-After: the key is fine. (`Retry-After: 2`)

```json
{
  "payments": [
    {
      "id": "fee77e90-8eeb-4931-a2c2-e8f2dd371335",
      "seller_id": "ea69cd4a-019e-4bf0-85c3-21f48e88e521",
      "product_name": "VIP Rank",
      "amount": "300.00",
      "status": "paid",
      "pay_url": "/pay/fee77e90-8eeb-4931-a2c2-e8f2dd371335",
      "qr_code_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAk4AAAJOCAIAAA…",
      "paymongo_test_url": null,
      "metadata": {
        "commands": [
          "lp user Steve parent set vip"
        ]
      },
      "commands": [
        "lp user {player} parent set vip"
      ],
      "buyer_name": "Steve",
      "delivery_status": "delivered",
      "deliveries": [
        {
          "id": "7c3e5b90-1f44-4a2d-9c86-0b1de2f4a771",
          "command": "lp user Steve parent set vip",
          "status": "delivered"
        }
      ],
      "repeat_unpaid": 0,
      "created_at": "2026-08-07T07:53:03.758361+00:00",
      "expires_at": "2026-08-08T07:53:03.758361+00:00"
    },
    {
      "id": "a3ce20c1-4786-4181-9fae-bebb46273af3",
      "seller_id": "ea69cd4a-019e-4bf0-85c3-21f48e88e521",
      "product_name": "VIP Rank",
      "amount": "300.00",
      "status": "expired",
      "pay_url": "/pay/a3ce20c1-4786-4181-9fae-bebb46273af3",
      "qr_code_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAk4AAAJOCAIAAA…",
      "paymongo_test_url": null,
      "metadata": null,
      "commands": [
        "lp user {player} parent set vip"
      ],
      "buyer_name": null,
      "delivery_status": "unclaimed",
      "repeat_unpaid": 0,
      "created_at": "2026-08-06T07:54:25.320153+00:00",
      "expires_at": "2026-08-07T07:54:25.320153+00:00"
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 4
}
```

### GET /rewards/pending

Game-server plugins poll this endpoint to receive pending command deliveries for completed payments. Returns commands that have not yet been acknowledged. **Each API key belongs to one server**: a key only receives the rewards routed to that server (plus any product set to deliver to *all* servers), so every server in your network can safely poll with its own key.

_Auth: API key only_

```bash
curl https://api.kantopay.com/rewards/pending \
  -H "Authorization: Bearer kp_live_•••"
```

Responses:
- `200`: Valid kp_ key, commands waiting to run
- `200`: Valid kp_ key, nothing pending (or every pending delivery is still inside its `delay` window) — `next_check` relaxes to 30
- `401 auth_missing_api_key`: No Authorization / X-API-Key header
- `401 auth_invalid_api_key`: Key does not start with kp_
- `401 auth_invalid_api_key`: Well-formed kp_ key that is unknown or revoked
- `429 rate_limited`: More than 120 requests in 60s on this API key — a poll loop tighter than the returned `next_check` will hit this (`Retry-After: 60`)
- `503 service_unavailable`: No DB connection free, or the database did not answer while checking the key. Retry after Retry-After: the key is fine (before 2026-10-04 a failed key check answered 401). (`Retry-After: 2`)

```json
{
  "deliveries": [
    {
      "id": "4f2c9b81-6d3a-4b17-8e55-a0c71d92f4b3",
      "link_id": "7c1f0a44-9d2b-4e51-9f0c-2b6c9a1d3e77",
      "command": "lp user Notch parent set vip",
      "sort_order": 0,
      "buyer_name": "Notch",
      "created_at": "2026-08-18T16:03:08.114522+00:00",
      "requires_online": true,
      "player": "Notch",
      "slots": 0,
      "delay": 0,
      "product_name": "VIP Rank",
      "price": "300.00",
      "transaction": "7c1f0a44-9d2b-4e51-9f0c-2b6c9a1d3e77",
      "test_mode": false
    },
    {
      "id": "a9d40e63-51bb-4c02-9a8f-1e7d6c440b28",
      "link_id": "1a8e5b20-3c47-4a19-b8d2-55f0c7e94a10",
      "command": "crate give Steve legendary 1",
      "sort_order": 1,
      "buyer_name": "Notch",
      "created_at": "2026-08-17T11:41:52.560019+00:00",
      "requires_online": true,
      "player": "Steve",
      "slots": 1,
      "delay": 0,
      "product_name": "Legendary Key",
      "price": "50.00",
      "transaction": "1a8e5b20-3c47-4a19-b8d2-55f0c7e94a10",
      "test_mode": false
    }
  ],
  "next_check": 10
}
```

### GET /rewards/revocations

Commands that **undo** a delivery — either the order was reversed (refunded, or lost to a chargeback), or it was a **timed package** whose window ran out. The `reason` field tells you which: the reversal type, or `"expired"`. Poll it exactly like [`/rewards/pending`](https://kantopay.com/documents#ep-rpending), run what it returns, then confirm with the **same** [`/rewards/acknowledge`](https://kantopay.com/documents#ep-rack) call: a revocation is an ordinary delivery, so per-server routing and retries behave identically. Without it a buyer who charges back keeps the rank *and* gets their money, and the shortfall lands on you. Commands come from the product’s removal list — one list covers both cases, because taking a rank back is the same command either way. Leave it empty and nothing is ever revoked, timed or not. A timed package sets *“Remove automatically after N days”* on the product. **Safe to adopt at your own pace:** `/rewards/pending` never returns a revocation, so a plugin that ignores this endpoint keeps working exactly as before. **The KantoPay plugin does all of this from version 3.7.1.** Earlier versions never call it, so a server still on one keeps every refunded or expired rank until it updates.

_Auth: API key only_

No required parameters. Optional: `player`.

```bash
curl https://api.kantopay.com/rewards/revocations \
  -H "Authorization: Bearer kp_live_•••"
```

Responses:
- `200`: Commands to undo rewards: the order was refunded, charged back, or a timed product ran out (reason "expired"). Run each, then acknowledge it.
- `200`: Nothing to take back.
- `401 auth_missing_api_key`: No key on the request.
- `429 rate_limited`: Over 120 requests a minute on this key. (`Retry-After: 60`)

```json
{
  "revocations": [
    {
      "id": "0d3b6a2e-7c41-4f8a-b5e9-1a2c3d4e5f60",
      "link_id": "8b1f0e2c-1d3a-4c5e-9f77-2a0b6d4e1c33",
      "command": "lp user Steve parent remove vip",
      "sort_order": 0,
      "player": "Steve",
      "product_name": "VIP",
      "transaction": "8b1f0e2c-1d3a-4c5e-9f77-2a0b6d4e1c33",
      "reason": "refunded",
      "test_mode": false
    }
  ],
  "next_check": 30
}
```

### POST /rewards/acknowledge

Game-server plugins call this endpoint after executing commands to report how each one went. Send `results`, one `{ "id", "status", "error" }` per delivery, where `status` is `"delivered"` or `"failed"` (blank counts as delivered; `error` is your own words, shown to the seller); the older `delivery_ids` list still works and means all delivered. A delivered command leaves the pending pool. A failed one is handed out again, until its fifth failure, when it stops and the seller can retry it from the dashboard. **Any other status is refused for that id**: its outcome is `invalid_status`, it is not written and stays pending, so a typo can never mark a reward delivered that did not run. The other ids in the batch are recorded as usual. The answer has a `results` list with one `outcome` per id, in the order sent: `delivered`, `retrying`, `failed` (for good), `not_found` (unknown, another server’s, or no longer pending), `invalid_id` or `invalid_status`. A key can only acknowledge the deliveries routed to its own server.

_Auth: API key only_

No required parameters. Optional: `results`, `delivery_ids`.

```bash
curl -X POST https://api.kantopay.com/rewards/acknowledge \
  -H "Authorization: Bearer kp_live_•••" \
  -H "Content-Type: application/json" \
  -d '{
  "results": [
    {
      "id": "uuid1",
      "status": "delivered"
    }
  ]
}'
```

Responses:
- `200`: Valid kp_ key and a body carrying `results` and/or the legacy `delivery_ids`. Counts are rows actually updated. `results` has one outcome per id, in the order sent: delivered, retrying (failed, will be handed out again), failed (for good), not_found (unknown, already acknowledged, or another server's), invalid_id or invalid_status
- `200`: A result's status is neither "delivered" nor "failed" (blank counts as delivered). That id is not written and stays pending, so it comes back on the next poll; the rest of the batch is recorded. Before 2026-10-04 any other word counted as delivered.
- `400`: Both `delivery_ids` and `results` are empty or absent. Note this body has NO `code` field — it is the plain MessageResponse shape
- `400 invalid_json`: Body is not well-formed JSON, or does not fit the request type
- `401 auth_missing_api_key`: No Authorization / X-API-Key header
- `401 auth_invalid_api_key`: Key does not start with kp_
- `401 auth_invalid_api_key`: Well-formed kp_ key that is unknown or revoked
- `413 payload_too_large`: Body over the 2 MiB JSON limit (`X-Max-Body-Bytes: 2097152`)
- `415 unsupported_media_type`: Missing or wrong Content-Type
- `429 rate_limited`: More than 120 requests in 60s on this API key (`Retry-After: 60`)
- `503 service_unavailable`: No DB connection free, or the database did not answer while checking the key. Retry after Retry-After: the key is fine (before 2026-10-04 a failed key check answered 401). (`Retry-After: 2`)

```json
{
  "acknowledged": 2,
  "failed": 1,
  "message": "2 delivered, 1 failed",
  "results": [
    { "id": "0c8f5e2a-1b3d-4c6e-8f7a-9b0c1d2e3f40", "outcome": "delivered" },
    { "id": "1d9a6f3b-2c4e-4d7f-9a8b-0c1d2e3f4a51", "outcome": "delivered" },
    { "id": "2eab7a4c-3d5f-4e8a-ab9c-1d2e3f4a5b62", "outcome": "retrying" },
    { "id": "3fbc8b5d-4e6a-4f9b-bcad-2e3f4a5b6c73", "outcome": "not_found" }
  ]
}
```

### POST /payments/list/{id}/cancel

Cancel an **active** (unpaid) payment link so the buyer can no longer pay it. Returns `{ "message": "Payment link cancelled" }`; a link that is already paid, expired, or cancelled returns a `400`.

_Auth: Dual-auth_

Required: `id`.

```bash
curl -X POST https://api.kantopay.com/payments/list/{id}/cancel \
  -H "Authorization: Bearer kp_live_•••"
```

Responses:
- `200`: The link was yours and still active
- `400`: {id} is not a UUID
- `400`: No active link with that id for this seller — already paid, expired, cancelled, or someone else's
- `401 auth_missing_token`: No Authorization header
- `401 auth_invalid_token`: Bearer token that is not a kp_ key and not a valid JWT
- `401 auth_invalid_api_key`: Bearer kp_… key that is unknown or revoked
- `401 auth_token_revoked`: Valid JWT whose session was revoked

```json
{
  "message": "Payment link cancelled"
}
```

### GET /pay/{link_id}/status

Public status check for a payment link. Used by the buyer payment page to poll for payment completion. No authentication required.

_Auth: Public — no auth required_

Required: `link_id`.

```bash
curl https://api.kantopay.com/pay/{link_id}/status
```

Responses:
- `200`: Link exists — status is one of active, paid, expired, cancelled (an active link past expires_at is reported as expired)
- `200`: Link is still open for payment
- `400`: {link_id} is not a UUID
- `404`: Well-formed UUID with no matching payment link

```json
{
  "status": "expired",
  "expires_at": "2026-08-06T09:44:56.637475+00:00"
}
```

### POST /pay/{link_id}/claim

Buyer sets their player name on a payment link before paying. Required for products that have commands (ranks, kits, etc.). No authentication required.

_Auth: Public — no auth required_

Required: `link_id`, `buyer_name`.

```bash
curl -X POST https://api.kantopay.com/pay/{link_id}/claim \
  -H "Content-Type: application/json" \
  -d '{
  "buyer_name": "YOUR_BUYER_NAME"
}'
```

Responses:
- `200`: Name accepted; buyer_name saved and {player} substituted into the link's metadata commands
- `400 invalid_json`: Body is not valid JSON or buyer_name is missing
- `404 auth_not_found`: No active, unexpired link with that id (already paid, cancelled, expired, or unknown)
- `415 unsupported_media_type`: Missing or non-JSON Content-Type
- `422 validation_error`: buyer_name is empty after sanitising, or longer than 64 characters
- `500 internal_error`: {link_id} is not a UUID — the id is parsed inside the DB closure, so a malformed one surfaces as internal_error rather than a 400

```json
{
  "ok": true
}
```

### GET /accounts/wallet

Get current wallet balance.

_Auth: Dual-auth_

```bash
curl https://api.kantopay.com/accounts/wallet \
  -H "Authorization: Bearer kp_live_•••"
```

Responses:
- `200`: Authenticated. Test orders never reach the wallet, so every figure is real money; withdrawable_balance always equals available_balance and is kept for older clients.
- `401 auth_missing_token`: No Authorization header
- `401 auth_invalid_token`: Bearer token that is not a kp_ key and not a valid JWT
- `401 auth_invalid_api_key`: Bearer kp_… key that is unknown or revoked
- `401 auth_token_revoked`: Valid JWT whose session was revoked

```json
{
  "available_balance": "1140.00",
  "withdrawable_balance": "1140.00",
  "pending_balance": "285.00",
  "total_earned": "1425.00",
  "kyc_verified": false,
  "withdrawn": "0.00",
  "pending_items": [
    {
      "amount": "285.00",
      "product": "VIP Rank",
      "method": "gcash",
      "release_at": "2026-09-03"
    }
  ]
}
```

### GET /accounts/wallet/history

Get wallet transaction history.

_Auth: Dual-auth_

```bash
curl https://api.kantopay.com/accounts/wallet/history \
  -H "Authorization: Bearer kp_live_•••"
```

Responses:
- `200`: Authenticated — a bare JSON array, newest first, capped at 100 entries. order_id is "" for entries not tied to a sale (withdrawals, refunds). entry_type is credit, debit, gift_card (what a gift card covered on that order; description "Paid with gift card") or coupon (what a code took off; description "Coupon CODE"). The last two move no money — the wallet was credited when the card was sold, and a discount was never charged — so ignore them in balance arithmetic. execution says what the order's game-server commands did: total, delivered, failed, pending (waiting_player of them held until the buyer is online) and last_run_at, when the latest one was delivered (by the plugin, or by the seller pressing Mark delivered). It is null for an entry with no order and for an order with nothing to run, including one refunded before its commands ran.
- `200`: Authenticated but no ledger entries yet
- `401 auth_missing_token`: No Authorization header
- `401 auth_invalid_token`: Bearer token that is not a kp_ key and not a valid JWT
- `401 auth_invalid_api_key`: Bearer kp_… key that is unknown or revoked
- `401 auth_token_revoked`: Valid JWT whose session was revoked

```json
[
  {
    "id": "3d9b1a52-0c47-4f6e-8a11-95c2d7e4b608",
    "order_id": "fee77e90-8eeb-4931-a2c2-e8f2dd371335",
    "amount": "300.00",
    "entry_type": "credit",
    "description": "Sale revenue",
    "created_at": "2026-08-07T07:55:12.443901+00:00",
    "execution": { "total": 2, "delivered": 2, "failed": 0, "pending": 0, "waiting_player": 0, "last_run_at": "2026-08-07T07:55:40.118204+00:00" }
  },
  {
    "id": "b17c8e04-52aa-4d33-9f70-1c6ea9d0f2b5",
    "order_id": "fee77e90-8eeb-4931-a2c2-e8f2dd371335",
    "amount": "15.00",
    "entry_type": "debit",
    "description": "Platform fee (5% + provider rate)",
    "created_at": "2026-08-07T07:55:12.443901+00:00",
    "execution": { "total": 2, "delivered": 2, "failed": 0, "pending": 0, "waiting_player": 0, "last_run_at": "2026-08-07T07:55:40.118204+00:00" }
  },
  {
    "id": "6e2f4471-9d80-4b1a-b3c5-88f0a1e77d29",
    "order_id": "",
    "amount": "500.00",
    "entry_type": "debit",
    "description": "Withdrawal to gcash ••••1234",
    "created_at": "2026-08-08T03:11:47.902114+00:00",
    "execution": null
  }
]
```

### GET /accounts/analytics

The numbers behind the dashboard’s Analytics page, for one period. `days` is `7`, `30` (default), `90` or `0` for all time; anything else is 30. Everything in the answer reads the same period: `revenue` (gross), `net` after `fees` and `tax`, `orders`, the previous period for comparison, `refunds`, `conversion`, `repeat`, `methods` (how buyers paid), `servers` (what each server delivered; an order routed to several counts under each), `hours` and `dow` (Manila time), `coupons`, `gift`, the daily `series` (monthly for all time), and the `top` products and `customers`. Test orders and dashboard probes never count.

_Auth: API key or dashboard session_

No required parameters. Optional: `days`.

```bash
curl https://api.kantopay.com/accounts/analytics?days=30 \
  -H "Authorization: Bearer kp_live_•••"
```

Responses:
- `200`: Authenticated — the last 30 days (days omitted). Money fields are numbers; series has one bucket per day, or per month for days=0.
- `401 auth_missing_token`: No credential sent (no Authorization or X-API-Key header)
- `401 auth_invalid_api_key`: A kp_ key that does not exist, is revoked, or belongs to a closed store
- `503 service_unavailable`: The key could not be checked right now; wait for Retry-After and try again

```json
{
  "days": 30,
  "lifetime": { "orders": 140, "revenue": 41200.0 },
  "orders": 38,
  "revenue": 9450.0,
  "ordersPrev": 31,
  "revenuePrev": 7200.0,
  "fees": 615.0,
  "tax": 283.5,
  "net": 8551.5,
  "refunds": { "count": 2, "amount": 350.0, "chargebacks": 1 },
  "coupons": { "uses": 7, "discount": 420.0 },
  "gift": { "sold": 3, "soldAmount": 1500.0, "redeemed": 900.0, "outstanding": 600.0 },
  "conversion": { "created": 61, "paid": 38, "expired": 20 },
  "repeat": { "buyers": 22, "returning": 9 },
  "series": [ { "date": "2026-08-06", "orders": 2, "revenue": 600.0 }, "…" ],
  "top": [ { "name": "VIP Rank", "count": 14, "revenue": 4200.0 } ],
  "customers": [ { "name": "Lonaldeu", "orders": 5, "spent": 1500.0 } ],
  "methods": [ { "method": "gcash", "orders": 24, "revenue": 6000.0 } ],
  "servers": [ { "name": "Survival", "game": "minecraft", "orders": 30, "revenue": 7800.0 }, { "name": "Rust Main", "game": "rust", "orders": 8, "revenue": 1650.0 } ],
  "dow": [ { "dow": 6, "orders": 9, "revenue": 2500.0 } ],
  "hours": [ { "hour": 20, "orders": 4, "revenue": 1300.0 } ]
}
```

### GET /accounts/analytics/export

The period’s paid orders as CSV, one row per order, newest first, up to 5,000 rows: `paid_at` (Manila), `order_id`, `buyer`, `product`, `method`, `gross`, `fee`, `tax`, `net`, `coupon_discount`, `gift_card_applied`, `reversal`. Same `days` as above. Written for a spreadsheet at tax time: plain numbers, no currency symbols, and a field that looks like a formula is neutralised so a sheet never runs a buyer’s name. Comes back as `text/csv` with a `Content-Disposition` filename.

_Auth: API key or dashboard session_

No required parameters. Optional: `days`.

```bash
curl https://api.kantopay.com/accounts/analytics/export?days=30 \
  -H "Authorization: Bearer kp_live_•••"
```

Responses:
- `200`: Authenticated — text/csv, one header row then one row per paid order in the period
- `401 auth_missing_token`: No credential sent (no Authorization or X-API-Key header)
- `401 auth_invalid_api_key`: A kp_ key that does not exist, is revoked, or belongs to a closed store
- `503 service_unavailable`: The key could not be checked right now; wait for Retry-After and try again

```
paid_at,order_id,buyer,product,method,gross,fee,tax,net,coupon_discount,gift_card_applied,reversal
2026-09-02 18:41,7a21c0de-1b2f-4c3d-9e8f-0a1b2c3d4e5f,Lonaldeu,VIP Rank,gcash,300.00,22.50,9.00,268.50,0.00,0.00,
2026-08-29 09:12,fee77e90-8eeb-4931-a2c2-e8f2dd371335,JuanDelaCruz,Legendary Key,qrph,50.00,3.00,1.50,45.50,10.00,0.00,
```

### POST /players/link

Turn a player your server has just seen into a **proof** your storefront can trust. Call it when they type `/link` in game and send them the returned `url` as a clickable message; it carries `?kp_player=`, which your storefront reads and passes back as `player_token`.

Why it exists: `player_name` is a string anyone can type, and cumulative upgrade pricing prices against purchase history. A token is the only thing that says *your game server vouched for this person*. It expires after 24 hours, is signed for one shop and one player, and a token that does not verify is a `401` — never a quiet fall back to the typed name.

_Auth: API key only_

Required: `player_name`.

```bash
curl -X POST https://api.kantopay.com/players/link \
  -H "Authorization: Bearer kp_live_•••" \
  -H "Content-Type: application/json" \
  -d '{
  "player_name": "Steve_PH"
}'
```

Responses:
- `200`: Valid kp_ key and `{"player_name":"Notch"}`. `url` is built from the host that served the request, and `player_name` is the CLEANED name (whitespace becomes `_`, anything outside letters/digits/`_`/`.`/`-` is dropped)
- `400 player_name_required`: `player_name` cleans to empty (only disallowed characters) or is longer than 64 characters
- `400 invalid_json`: Body is malformed JSON, or `player_name` is missing / not a string
- `401 auth_missing_api_key`: No Authorization / X-API-Key header
- `401 auth_invalid_api_key`: Key does not start with kp_
- `401 auth_invalid_api_key`: Well-formed kp_ key that is unknown or revoked
- `409 no_storefront`: The key's account has no row in shop_settings — no storefront to link the player to
- `415 unsupported_media_type`: Missing or wrong Content-Type
- `429 rate_limited`: More than 120 requests in 60s on this API key (`Retry-After: 60`)
- `503 service_unavailable`: No DB connection free, or the database did not answer while checking the key. Retry after Retry-After: the key is fine (before 2026-10-04 a failed key check answered 401). (`Retry-After: 2`)

```json
{
  "player_name": "Notch",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzaWQiOiI5YjE3ZDJmMC1hYzE0LTRkMzQtOGY2Yi01ZTIyYzhkOTAxYWEiLCJwbHIiOiJOb3RjaCIsImV4cCI6MTc5NDU2NzIwMH0.M3bJ0kQ8yZr6nQwqA1sVdT7hLpXeCf2gYuI9oKmB4tE",
  "url": "http://localhost:8080/shop/123?kp_player=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzaWQiOiI5YjE3ZDJmMC1hYzE0LTRkMzQtOGY2Yi01ZTIyYzhkOTAxYWEiLCJwbHIiOiJOb3RjaCIsImV4cCI6MTc5NDU2NzIwMH0.M3bJ0kQ8yZr6nQwqA1sVdT7hLpXeCf2gYuI9oKmB4tE",
  "expires_in_seconds": 86400
}
```

### GET /players/{name}/purchases

Everything a player has paid for, newest first, up to 100 — what an in-game `/purchases` command reads, and what you check before re-delivering something lost to a world reset. Each order carries its `items`, because `product` on a cart order is the string “Cart (3 items)” and names nothing you can act on.

Matched on the delivery target (the recipient for a gift, otherwise the buyer), case- and space-insensitively, and scoped to your key’s account. This is the seller-side twin of [`/v1/…/players/me/orders`](https://kantopay.com/documents#ep-v1myorders): your key already means “I am the seller”, so no player token is needed here.

**Refunded, charged-back and test orders are left out**, so a plugin re-delivering from this list never gives back what was refunded. Ask for them with `include_reversed=true` and `include_test=true`; every order carries `reversal_type` (`null`, or why it was taken back) and `is_test`. A disputed order is still listed by default, with `reversal_type: "disputed"`, until the dispute is settled.

_Auth: API key only_

Required: `name`. Optional: `include_reversed`, `include_test`.

```bash
curl https://api.kantopay.com/players/{name}/purchases \
  -H "Authorization: Bearer kp_live_•••"
```

Responses:
- `200`: Valid kp_ key. Up to 100 paid orders delivered to that name (recipient for gifts, else buyer), newest first. Refunded, charged-back and test orders are left out unless ?include_reversed=true / ?include_test=true. `amount` values are STRINGS here, unlike /server/*
- `200`: Valid kp_ key, that name has bought nothing from this seller
- `401 auth_missing_api_key`: No Authorization / X-API-Key header
- `401 auth_invalid_api_key`: Key does not start with kp_
- `401 auth_invalid_api_key`: Well-formed kp_ key that is unknown or revoked
- `422 validation_error`: `{name}` trims to empty — e.g. `/players/%20/purchases`. Unlike /server/players/{name} there is no 64-character ceiling here
- `429 rate_limited`: More than 120 requests in 60s on this API key (`Retry-After: 60`)
- `503 service_unavailable`: No DB connection free, or the database did not answer while checking the key. Retry after Retry-After: the key is fine (before 2026-10-04 a failed key check answered 401). (`Retry-After: 2`)

```json
{
  "player": "Notch",
  "count": 2,
  "purchases": [
    {
      "order_id": "7c1f0a44-9d2b-4e51-9f0c-2b6c9a1d3e77",
      "product": "VIP Rank",
      "amount": "300.00",
      "paid_at": "2026-08-18T16:03:07.902114+00:00",
      "player": "Notch",
      "items": [
        {
          "product_id": "bbbbbbbb-2222-4222-8222-222222222222",
          "product_name": "VIP Rank",
          "quantity": 1,
          "amount": "300.00"
        }
      ],
      "reversal_type": null,
      "is_test": false
    },
    {
      "order_id": "e0b3c518-77af-4d6e-9c21-8a4b0f5d6612",
      "product": "Cart (3 items)",
      "amount": "150.00",
      "paid_at": "2026-07-14T09:12:44.318471+00:00",
      "player": "Notch",
      "items": [
        {
          "product_id": "aaaaaaaa-1111-4111-8111-111111111111",
          "product_name": "Legendary Key",
          "quantity": 3,
          "amount": "150.00"
        }
      ],
      "reversal_type": null,
      "is_test": false
    }
  ]
}
```

### GET /rewards/info

The plugin handshake. Validates the key and answers with the store name, the *server* that key belongs to, what is waiting for it, and `mode` — `"live"`, or `"test"` for a [test server key](https://kantopay.com/documents#storefront-test). `pending_deliveries` counts the rewards waiting to be given, as [`/rewards/pending`](https://kantopay.com/documents#ep-rpending) serves them; `pending_revocations` counts the removals waiting on [`/rewards/revocations`](https://kantopay.com/documents#ep-rrevoke) (refunded, charged-back or expired rewards). A plugin that never polls revocations leaves that number growing. Call it once at startup so an operator sees which store and which server they are wired to, and so a plugin running against test money says so in the console instead of looking like a live install with no sales.

_Auth: API key only_

```bash
curl https://api.kantopay.com/rewards/info \
  -H "Authorization: Bearer kp_live_•••"
```

Responses:
- `200`: Valid kp_ key. `store_name` falls back to the shop slug when no shop name is set (this shop has none, so it reads "123"). `pending_deliveries` counts rewards to give, `pending_revocations` removals waiting on /rewards/revocations. `mode` is "test" and `test_mode` true for a test server key (kp_test_)
- `401 auth_missing_api_key`: No Authorization / X-API-Key header
- `401 auth_invalid_api_key`: Key does not start with kp_ (e.g. `Authorization: Bearer nope`)
- `401 auth_invalid_api_key`: Well-formed kp_ key that is unknown or revoked
- `429 rate_limited`: More than 120 requests in 60s on this API key (`Retry-After: 60`)
- `503 service_unavailable`: No DB connection free, or the database did not answer while checking the key. Retry after Retry-After: the key is fine (before 2026-10-04 a failed key check answered 401). (`Retry-After: 2`)

```json
{
  "ok": true,
  "store_name": "123",
  "server_name": "Survival Main",
  "currency": "PHP",
  "pending_deliveries": 2,
  "pending_revocations": 1,
  "mode": "live",
  "test_mode": false
}
```

### Item catalog

A staff member holds an item, types `/kantopay item import vip-sword`, and the plugin captures the real `ItemStack` into its own `items.json`. These endpoints are where that file is mirrored, so your dashboard can offer the item on a product and a second server can be handed the same catalog.

**Item ids are unique per store, not per server.** A product belongs to the store — if `vip-sword` meant a different item on each of your three servers, a product pointing at it would name three different things and the dashboard could not show you what you are selling. A store spanning Minecraft versions is handled the way the format already handles it: a server on a distant version ignores the exact copy in `data` and rebuilds from `material`/`name`/`lore`, which is what `data_version` is for. Ids match case-insensitively, and `source_key_id` records which server last pushed each entry.

**The server pushes; we store.** An item can only be *captured* in-game, so the game server is the only thing that can author one and this is a mirror. That is enforced, not just described: `PUT` and `DELETE` need an API key even though `GET` also works from a dashboard session. There is no `updated_at` conflict handling because there is only ever one writer — and deleting from the dashboard would not remove anything from a server’s `items.json`, so the two would quietly diverge with no way back.

**`data` is opaque.** Stored and returned byte for byte, never parsed, never re-encoded. The cap is **65,536 bytes** of base64 — roughly ten times a shulker box packed with named, enchanted items — so a plugin can refuse an oversized capture in-game, where the operator can still do something about it, instead of failing at upload. A store holds up to **500 items**. Both numbers come back in a `limits` object on every [/items](https://kantopay.com/documents#ep-items) response, so read them at startup rather than hard-coding them.

**A product can deliver an item directly.** Set a product’s `item_id` and **checkout** stores `kantopay item give <id> <player>` beside the seller’s own command templates, so it arrives as an ordinary delivery: **no plugin change is needed** and older builds keep working. Snapshotted there rather than read off the product at settlement, so a seller editing the product while a buyer is mid-payment cannot change what that order delivers. A product whose entire reward is an item still asks the buyer for their in-game name before showing the QR. [/rewards/pending](https://kantopay.com/documents#ep-rpending) also reports `item_id` on the delivery, so a future build can skip parsing it back out. The generated row always carries `requires_online: true` and `slots: 1` — an item cannot be put in an offline player’s hands, and giving it into a full inventory drops it on the floor of wherever they last stood — and it sorts *after* the product’s own commands, so a rank that unlocks a kit exists before the kit arrives. Buying three of something queues three gives.

### GET /items

Every item this store has captured. `data` is **withheld by default** — 500 items at 64 KB each is a 32 MB response, and the usual caller wants the names. It comes back *present and null*, never silently missing, so “this item has no exact copy” (`has_data: false`) stays distinguishable from “you did not ask”. Pass `include_data=true` to seed a new server.

_Auth: Dual-auth_

No required parameters. Optional: `include_data`.

```bash
curl https://api.kantopay.com/items \
  -H "Authorization: Bearer kp_live_•••"
```

Responses:
- `200`: Your captured items. data is null unless you pass include_data=true.
- `401 auth_missing_api_key`: No key on the request.

```json
{
  "items": [
    {
      "id": "vip-sword",
      "name": "&6VIP Sword",
      "material": "DIAMOND_SWORD",
      "amount": 1,
      "lore": [
        "&7Thank you for supporting us"
      ],
      "enchants": {
        "DAMAGE_ALL": 5
      },
      "unbreakable": false,
      "glint": false,
      "tracked": false,
      "custom_model_data": null,
      "data": null,
      "data_version": "3953",
      "has_data": true,
      "data_bytes": 2048,
      "kit": [],
      "created_by": "Steve",
      "created_at": "2026-09-07T13:30:51+00:00",
      "updated_by": "Steve",
      "updated_at": null,
      "source_key_id": "5d0c9a7e-2f41-4b8e-a1c3-7e6f5d4c3b2a"
    }
  ],
  "count": 1,
  "include_data": false,
  "limits": {
    "max_items": 500,
    "max_data_bytes": 65536
  }
}
```

### GET /items/{id}

One item, **always with `data`** — fetching by id is how you ask for the exact copy. The id is matched case-insensitively. A miss returns `404 item_not_found`, and the message names the `/kantopay item import` that would create it.

_Auth: Dual-auth_

Required: `id`.

```bash
curl https://api.kantopay.com/items/{id} \
  -H "Authorization: Bearer kp_live_•••"
```

Responses:
- `200`: One item, with data filled in.
- `404 item_not_found`: No item with that id in your catalog.
- `422 validation_error`: The id is not a valid item id.

```json
{
  "item": {
    "id": "vip-sword",
    "name": "&6VIP Sword",
    "material": "DIAMOND_SWORD",
    "amount": 1,
    "lore": [
      "&7Thank you for supporting us"
    ],
    "enchants": {
      "DAMAGE_ALL": 5
    },
    "unbreakable": false,
    "glint": false,
    "tracked": false,
    "custom_model_data": null,
    "data": "<base64 item data>",
    "data_version": "3953",
    "has_data": true,
    "data_bytes": 2048,
    "kit": [],
    "created_by": "Steve",
    "created_at": "2026-09-07T13:30:51+00:00",
    "updated_by": "Steve",
    "updated_at": null,
    "source_key_id": "5d0c9a7e-2f41-4b8e-a1c3-7e6f5d4c3b2a"
  }
}
```

### PUT /items/{id}

Create or replace one item — send the `items.json` object verbatim. `PUT` rather than `POST` because the plugin already knows the id, and re-importing the same id must update one row instead of making a second. **201** on create, **200** on replace, both with `{item, created}`. `created_by` and `created_at` survive a replace: they record who first captured the item, which is a different question from who last changed it. A body `id` that disagrees with the URL is refused rather than silently resolved, and an id is **rejected, never sanitised** — you hold that id in your own file and will ask for it back by that exact string. Refusals: `403 item_needs_server_key` (a dashboard session tried to write), `409 item_limit_reached`, `422 validation_error` with the `field` named and the real number in the message.

_Auth: API key only_

Required: `id`, `body`.

```bash
curl -X PUT https://api.kantopay.com/items/{id} \
  -H "Authorization: Bearer kp_live_•••" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "&6VIP Sword",
  "material": "DIAMOND_SWORD",
  "amount": 1,
  "lore": [
    "&7Thank you for supporting us"
  ],
  "enchants": {
    "DAMAGE_ALL": 5
  },
  "tracked": true,
  "kit": [],
  "created_by": "Lonaldeu"
}'
```

Responses:
- `201`: Created: no item had this id yet.
- `200`: Replaced the item with this id.
- `403 item_needs_server_key`: Called from a dashboard session. Items are written only by a game server, with its key.
- `409 item_limit_reached`: You already have 500 items.
- `422 validation_error`: A field is not acceptable; field names it (id, name, material, kit, lore, enchants, data, data_version).

```json
{
  "item": {
    "id": "vip-sword",
    "name": "&6VIP Sword",
    "material": "DIAMOND_SWORD",
    "amount": 1,
    "lore": [
      "&7Thank you for supporting us"
    ],
    "enchants": {
      "DAMAGE_ALL": 5
    },
    "unbreakable": false,
    "glint": false,
    "tracked": false,
    "custom_model_data": null,
    "data": null,
    "data_version": "3953",
    "has_data": true,
    "data_bytes": 2048,
    "kit": [],
    "created_by": "Steve",
    "created_at": "2026-09-07T13:30:51+00:00",
    "updated_by": "Steve",
    "updated_at": null,
    "source_key_id": "5d0c9a7e-2f41-4b8e-a1c3-7e6f5d4c3b2a"
  },
  "created": true
}
```

### DELETE /items/{id}

Remove one item. Refuses with `409 item_in_use`, and the names in the body, if anything still uses it — a product that delivers it, **or another item whose kit names it** (a kit missing one member hands out one item short, with only a plugin-side warning to say so). `blocked_by` is the total; `products` lists the first 25. Never a cascade and never a silent orphan. Clearing those products’ item would stop a live product delivering anything, discovered by a buyer; leaving it would point a live product at nothing, discovered by the same buyer. Naming them is the only outcome that leaves you able to act.

_Auth: API key only_

Required: `id`.

```bash
curl -X DELETE https://api.kantopay.com/items/{id} \
  -H "Authorization: Bearer kp_live_•••"
```

Responses:
- `200`: Deleted.
- `403 item_needs_server_key`: Called from a dashboard session. Items are written only by a game server, with its key.
- `404 item_not_found`: No item with that id in your catalog.
- `409 item_in_use`: A product still delivers this item. Remove it from those products first.

```json
{
  "deleted": true,
  "id": "vip-sword"
}
```

### POST /audit

Record what happened **in-game**, in batches of up to 200. Deliveries already reach us through [/rewards/acknowledge](https://kantopay.com/documents#ep-rack); this is the half that does not — `ITEM-IMPORT`, `ITEM-EDIT`, `ITEM-DELETE`, `KIT-CREATE`, `KIT-EDIT`, `ITEM-GIVE`, `STAFF-TEST`, or anything else you name. **Retry freely:** dedupe is your own `id` when you send one, else a hash of `(server, at, actor, action, subject)`. Send an `id` whenever two real events could share that tuple — two gives of the same item in the same second are two gives. A bad event is rejected *by index* and the rest of the batch still lands, because you cannot repair a row we refuse and failing the whole batch would lose the good events with it. `at` is stored as sent; retention keys on *our* clock instead, so a wrong server clock cannot make a row immortal. A store keeps its newest 50,000 events and its last 180 days, and `evicted` reports anything dropped to stay under that.

_Auth: API key only_

Required: `body`.

```bash
curl -X POST https://api.kantopay.com/audit \
  -H "Authorization: Bearer kp_live_•••" \
  -H "Content-Type: application/json" \
  -d '{
  "events": [
    {
      "at": "2026-09-07T13:30:51Z",
      "actor": "Lonaldeu",
      "action": "ITEM-IMPORT",
      "subject": "vip-sword",
      "detail": "DIAMOND_SWORD x1 (exact)"
    }
  ]
}'
```

Responses:
- `200`: Stored. A bad event is listed in rejected and does not fail the batch; an event id already stored counts as a duplicate.
- `422 validation_error`: events is empty or has more than 200 entries.
- `401 auth_missing_api_key`: No key on the request.

```json
{
  "accepted": 3,
  "duplicates": 1,
  "rejected": [
    {
      "index": 2,
      "field": "at",
      "reason": "at must be an RFC 3339 time."
    }
  ],
  "evicted": 0,
  "message": "3 stored, 1 already had, 1 rejected"
}
```

### Store admin

Coupons and gift-card denominations are the two things in your store an API key *can* create. Everything else about the catalogue stays in the dashboard, and the line between them is not arbitrary: these write a row you can see, edit and delete afterwards, at a price that is yours — they never name a price mid-checkout the way a caller inventing its own product would. A coupon made by your bot is the same object as one made by your thumb.

They exist because an integration could already sell *through* a coupon and never make one. If your Discord bot runs a flash sale, or your launcher hands a returning player a code, that used to mean a human in the dashboard at the exact moment it mattered.

**These are live the instant they return.** There is no draft state and no confirmation step — a coupon you create is redeemable by anyone who learns the code, on your store and over the Storefront API alike. Delete is equally immediate.

### GET /accounts/coupons

Every coupon on your account, active or not. `used_count` against `max_uses` is the number worth watching — a coupon at its limit still exists and still lists, it just stops applying. `product_ids` is empty when the coupon applies to the whole cart.

_Auth: API key or dashboard session_

```bash
curl https://api.kantopay.com/accounts/coupons \
  -H "Authorization: Bearer kp_live_•••"
```

Responses:
- `200`: Authenticated with a session JWT or the seller's own kp_ API key
- `401 auth_missing_token`: No Authorization header (`Content-Type: text/plain; charset=utf-8 (actix ErrorUnauthorized wraps the JSON string)`)
- `401 auth_invalid_api_key`: Authorization: Bearer kp_... that is unknown or revoked (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_invalid_token`: Bearer value that is not kp_-prefixed and does not verify as a JWT (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_token_revoked`: Valid JWT whose jti was revoked (PIN reset, logout-all, deactivation) (`Content-Type: text/plain; charset=utf-8`)

```json
{
  "coupons": [
    {
      "id": "7c1f0a52-9d3e-4c8b-9a10-2f6e5b4d3c21",
      "code": "WELCOME10",
      "kind": "percent",
      "value": "10.00",
      "min_amount": "150.00",
      "max_uses": 100,
      "used_count": 12,
      "expires_at": "2026-12-31T15:59:59+00:00",
      "is_active": true,
      "max_discount": "50.00",
      "product_ids": []
    },
    {
      "id": "3ab9d4e7-6c22-4f5a-8b71-0d9e8c7a6b54",
      "code": "VIP50",
      "kind": "fixed",
      "value": "50.00",
      "min_amount": null,
      "max_uses": null,
      "used_count": 3,
      "expires_at": null,
      "is_active": true,
      "max_discount": null,
      "product_ids": ["bbbbbbbb-2222-4222-8222-222222222222"]
    }
  ]
}
```

### POST /accounts/coupons

Create a coupon. `kind` is `"percent"` or `"fixed"`; `value` is the number for either (`"20"` means 20% or ₱20 depending on the kind). `max_discount` caps a runaway percent coupon on a large cart and is ignored for `fixed`. `min_amount` is the subtotal it starts working at. `product_ids` limits it to specific products — leave it empty for the whole cart. Codes are yours to choose and must be unique on your account.

_Auth: API key or dashboard session_

Required: `code`, `kind`, `value`. Optional: `min_amount`, `max_uses`, `max_discount`, `expires_at`, `product_ids`.

```bash
curl -X POST https://api.kantopay.com/accounts/coupons \
  -H "Authorization: Bearer kp_live_•••" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "LAUNCH20",
  "kind": "percent",
  "value": "20"
}'
```

Responses:
- `200`: Coupon created (note: 200, not 201) — returns the coupon object unwrapped
- `400 invalid_json`: Body is malformed JSON or does not fit CreateCouponRequest (app-wide JsonConfig, src/api/extractor_error_json.rs)
- `401 auth_missing_token`: No Authorization header (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_invalid_api_key`: Authorization: Bearer kp_... that is unknown or revoked (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_invalid_token`: Bearer value that is not kp_-prefixed and does not verify as a JWT (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_token_revoked`: Valid JWT whose jti was revoked (`Content-Type: text/plain; charset=utf-8`)
- `415 unsupported_media_type`: Content-Type is missing or is not application/json
- `422 validation_error`: code is empty, longer than 40 chars, or contains whitespace
- `422 validation_error`: kind is anything other than 'percent' or 'fixed' (compared lowercased/trimmed)
- `422 validation_error`: value is unparseable as a decimal, or is <= 0
- `422 validation_error`: kind is 'percent' and value is greater than 100
- `422 validation_error`: product_ids contains more than 100 entries
- `422 validation_error`: The INSERT hits the per-seller UNIQUE index on code

```json
{
  "id": "7c1f0a52-9d3e-4c8b-9a10-2f6e5b4d3c21",
  "code": "WELCOME10",
  "kind": "percent",
  "value": "10.00",
  "min_amount": "150.00",
  "max_uses": 100,
  "used_count": 0,
  "expires_at": "2026-12-31T15:59:59+00:00",
  "is_active": true,
  "max_discount": "50.00",
  "product_ids": ["bbbbbbbb-2222-4222-8222-222222222222"]
}
```

### DELETE /accounts/coupons/{id}

Delete a coupon. Orders that already redeemed it keep their discount — this only stops future use. Deleting is the honest way to kill a leaked code; there is no disable flag to hunt for.

_Auth: API key or dashboard session_

Required: `id`.

```bash
curl -X DELETE https://api.kantopay.com/accounts/coupons/{id} \
  -H "Authorization: Bearer kp_live_•••"
```

Responses:
- `200`: Always, once the id parses — the handler ignores the affected-row count, so an unknown id or another seller's coupon also returns deleted:true
- `401 auth_missing_token`: No Authorization header (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_invalid_api_key`: Authorization: Bearer kp_... that is unknown or revoked (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_invalid_token`: Bearer value that is not kp_-prefixed and does not verify as a JWT (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_token_revoked`: Valid JWT whose jti was revoked (`Content-Type: text/plain; charset=utf-8`)
- `422 validation_error`: {id} is not a UUID

```json
{
  "deleted": true
}
```

### GET /accounts/gift-cards/products

The fixed denominations you sell, cheapest first. This is the private twin of [`GET /v1/shops/{token}/giftcards`](https://kantopay.com/documents#ep-v1giftcards): same rows, plus the ones you have switched off.

_Auth: API key or dashboard session_

```bash
curl https://api.kantopay.com/accounts/gift-cards/products \
  -H "Authorization: Bearer kp_live_•••"
```

Responses:
- `200`: Authenticated — every denomination for this seller, active or not, ordered by amount
- `401 auth_missing_token`: No Authorization header (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_invalid_api_key`: Authorization: Bearer kp_... that is unknown or revoked (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_invalid_token`: Bearer value that is not kp_-prefixed and does not verify as a JWT (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_token_revoked`: Valid JWT whose jti was revoked (`Content-Type: text/plain; charset=utf-8`)

```json
{
  "denominations": [
    {
      "id": "c4d81b39-5e07-4a6d-9f22-71b3e0a4c8d5",
      "amount": "100.00",
      "label": "Starter",
      "is_active": true
    },
    {
      "id": "e91a7f60-2b48-4c13-8ad6-5f2c9e01b7a3",
      "amount": "500.00",
      "label": null,
      "is_active": true
    }
  ]
}
```

### POST /accounts/gift-cards/products

Add a denomination. `amount` is what the buyer pays and what the card is worth — there is no markup or discount between the two. `label` is cosmetic (“Starter”, “Best value”) and optional.

_Auth: API key or dashboard session_

Required: `amount`. Optional: `label`.

```bash
curl -X POST https://api.kantopay.com/accounts/gift-cards/products \
  -H "Authorization: Bearer kp_live_•••" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "500.00"
}'
```

Responses:
- `200`: Denomination created (200, not 201) — returns the denomination object unwrapped
- `400 invalid_json`: Body is malformed JSON or does not fit CreateDenomRequest (app-wide JsonConfig)
- `401 auth_missing_token`: No Authorization header (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_invalid_api_key`: Authorization: Bearer kp_... that is unknown or revoked (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_invalid_token`: Bearer value that is not kp_-prefixed and does not verify as a JWT (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_token_revoked`: Valid JWT whose jti was revoked (`Content-Type: text/plain; charset=utf-8`)
- `415 unsupported_media_type`: Content-Type is missing or is not application/json
- `422 validation_error`: amount is unparseable as a decimal, or is <= 0
- `422 validation_error`: amount is below the ₱20 floor
- `422 validation_error`: amount is greater than 1,000,000

```json
{
  "id": "c4d81b39-5e07-4a6d-9f22-71b3e0a4c8d5",
  "amount": "500.00",
  "label": "Builder Bundle",
  "is_active": true
}
```

### DELETE /accounts/gift-cards/products/{id}

Remove a denomination from sale. Cards already issued at that amount keep working — a gift card is a balance, not a pointer to this row.

_Auth: API key or dashboard session_

Required: `id`.

```bash
curl -X DELETE https://api.kantopay.com/accounts/gift-cards/products/{id} \
  -H "Authorization: Bearer kp_live_•••"
```

Responses:
- `200`: Always, once the id parses — the affected-row count is ignored, so an unknown or foreign id also returns deleted:true
- `401 auth_missing_token`: No Authorization header (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_invalid_api_key`: Authorization: Bearer kp_... that is unknown or revoked (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_invalid_token`: Bearer value that is not kp_-prefixed and does not verify as a JWT (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_token_revoked`: Valid JWT whose jti was revoked (`Content-Type: text/plain; charset=utf-8`)
- `422 validation_error`: {id} is not a UUID

```json
{
  "deleted": true
}
```

### GET /accounts/gift-cards/settings

Your gift-card configuration: `customMin` / `customMax` (the range for buyer-chosen amounts, in pesos), `emailNote` and `design` (how the card looks). Gift cards never expire, so there is no expiry setting. Returns `{"settings": null}` if you have never set any — that is the default state, not an error.

_Auth: API key or dashboard session_

```bash
curl https://api.kantopay.com/accounts/gift-cards/settings \
  -H "Authorization: Bearer kp_live_•••"
```

Responses:
- `200`: Authenticated — the raw giftcard_settings JSONB from shop_settings, wrapped in "settings". The inner object below is this shop's actual stored value (read via the public /v1/shops/{token}/giftcards route)
- `200`: Seller has no shop_settings row yet, or the column is NULL — the key is still present and set to null
- `401 auth_missing_token`: No Authorization header (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_invalid_api_key`: Authorization: Bearer kp_... that is unknown or revoked (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_invalid_token`: Bearer value that is not kp_-prefixed and does not verify as a JWT (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_token_revoked`: Valid JWT whose jti was revoked (`Content-Type: text/plain; charset=utf-8`)

```json
{
  "settings": {
    "allowCustom": true,
    "customMin": null,
    "customMax": null,
    "emailNote": null
  }
}
```

### PUT /accounts/gift-cards/settings

Replace the whole settings object — send every key you want kept, not just the one you are changing. `customMin` cannot go below the ₱20 gift-card floor, `customMax` cannot be below `customMin`, `emailNote` is plain text under 300 characters, and any `expiryDays` is refused: gift cards never expire. `design` sets how the card looks in the code email, on your gift-card block and on the receipt: `{"style": "color" | "image", "color": "#RRGGBB", "image": "/uploads/<file>", "title": "…", "showLogo": true}`. Every field is optional; `image` must be a path `/accounts/upload-image` returned (never an outside link) and is required for the picture style; `title` is plain text of at most 28 characters. Unknown keys inside `design` are dropped, and a bad field is refused with `field` set to e.g. `design.color`.

_Auth: API key or dashboard session_

No required parameters. Optional: `settings`.

```bash
curl -X PUT https://api.kantopay.com/accounts/gift-cards/settings \
  -H "Authorization: Bearer kp_live_•••" \
  -H "Content-Type: application/json" \
  -d '{
  "settings": {
    "allowCustom": true,
    "customMin": 100,
    "customMax": 5000
  }
}'
```

Responses:
- `200`: Settings written (the UPDATE touched the seller's shop_settings row)
- `400 invalid_json`: Body is malformed JSON or does not fit PutSettingsRequest (app-wide JsonConfig)
- `401 auth_missing_token`: No Authorization header (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_invalid_api_key`: Authorization: Bearer kp_... that is unknown or revoked (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_invalid_token`: Bearer value that is not kp_-prefixed and does not verify as a JWT (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_token_revoked`: Valid JWT whose jti was revoked (`Content-Type: text/plain; charset=utf-8`)
- `415 unsupported_media_type`: Content-Type is missing or is not application/json
- `422 validation_error`: settings.customMin is below the ₱20 floor
- `422 validation_error`: settings.customMax is greater than 1,000,000
- `422 validation_error`: settings.customMax is less than settings.customMin
- `422 validation_error`: settings.expiryDays is present and non-null — expiry is refused outright under RA 10962 (Gift Check Act of 2017), not range-checked
- `422 validation_error`: settings.emailNote is longer than 300 characters
- `422 validation_error`: The UPDATE matched zero rows — the seller has no shop_settings row yet

```json
{
  "success": true
}
```

### GET /accounts/gift-cards/issued

The last 500 cards issued on your account, newest first, with `remaining_amount` and `status`. This is the ledger you check when a player says their card did not work.

_Auth: API key or dashboard session_

```bash
curl https://api.kantopay.com/accounts/gift-cards/issued \
  -H "Authorization: Bearer kp_live_•••"
```

Responses:
- `200`: Authenticated — up to 500 issued cards, newest first. expires_at is always null: mint_gift_card writes no expiry (RA 10962)
- `401 auth_missing_token`: No Authorization header (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_invalid_api_key`: Authorization: Bearer kp_... that is unknown or revoked (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_invalid_token`: Bearer value that is not kp_-prefixed and does not verify as a JWT (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_token_revoked`: Valid JWT whose jti was revoked (`Content-Type: text/plain; charset=utf-8`)

```json
{
  "cards": [
    {
      "id": "9f4c2e18-7a5b-4d63-b2e9-8c01a3f7d6b4",
      "code": "K7RQ-9MTZ-4XBH-2FDW",
      "initial_amount": "500.00",
      "remaining_amount": "200.00",
      "status": "active",
      "expires_at": null,
      "created_at": "2026-08-14T09:12:44.512331+00:00"
    },
    {
      "id": "1d6b8a07-3c94-4f21-a5e8-6b7d2c0f9e43",
      "code": "P3JN-8YVK-QW52-LR6T",
      "initial_amount": "100.00",
      "remaining_amount": "0.00",
      "status": "redeemed",
      "expires_at": null,
      "created_at": "2026-08-02T17:38:05.884012+00:00"
    }
  ]
}
```

### POST /accounts/gift-cards/issued/{id}/void

Void a card that has been spent. A card with a balance answers `409 gift_card_has_balance`: every card was bought by a player, and the Gift Check Act (RA 10962) forbids taking a paid balance away. A card bought by fraud is cancelled by refunding its purchase, which KantoPay support does. Voiding an already-void card is a no-op, not an error.

_Auth: API key or dashboard session_

Required: `id`.

```bash
curl -X POST https://api.kantopay.com/accounts/gift-cards/issued/{id}/void \
  -H "Authorization: Bearer kp_live_•••"
```

Responses:
- `200`: A spent card (balance 0); an unknown id, another seller's card, or an already-voided card also returns voided:true
- `409 gift_card_has_balance`: The card still has a balance a player paid for (RA 10962)
- `401 auth_missing_token`: No Authorization header (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_invalid_api_key`: Authorization: Bearer kp_... that is unknown or revoked (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_invalid_token`: Bearer value that is not kp_-prefixed and does not verify as a JWT (`Content-Type: text/plain; charset=utf-8`)
- `401 auth_token_revoked`: Valid JWT whose jti was revoked (`Content-Type: text/plain; charset=utf-8`)
- `422 validation_error`: {id} is not a UUID

```json
{
  "voided": true
}
```

---

## Webhooks

The other direction: **we call your server** the moment something happens to an order, so your own backend can grant a reward, post to a bot or update a database without polling. Set it up in [Dashboard › Integrations › Developer webhook](https://kantopay.com/dashboard/integrations): paste an `https://` address on your server and save. A signing secret (`whsec_…`) appears below it. Keep it on your server and check every request with it. **Send a test event** posts a signed sample to your address straight away and shows what your server answered.

Each event is a `POST` with a JSON body and these headers:

| Header | Value |
| --- | --- |
| `X-KantoPay-Event` | The event name, also in the body as `event`. |
| `X-KantoPay-Delivery` | The id of this event. Every retry of it carries the same id, so **dedupe on it**. Also in the body as `delivery_id`. |
| `X-KantoPay-Timestamp` | Unix seconds when this request was sent. A retry has a new one. |
| `X-KantoPay-Signature` | `hex(HMAC-SHA256(secret, X-KantoPay-Timestamp + "." + raw_body))`, lowercase. See [Signature verification](https://kantopay.com/documents#webhooks-verify). |

### Events

| Event | Sent when | What to do |
| --- | --- | --- |
| `sale.paid` | An order is paid, including one a gift card or coupon covered in full. Test orders and **Send a test event** send it too, with `"test": true`. | Grant the order once per `order_id`. Grant nothing when `test` is `true`. |
| `order.refunded` | A paid order was refunded. | Run `revoke_commands` to take the reward back. If `reward_kept` is `true`, KantoPay refunded the money without taking the reward back: leave it. |
| `order.charged_back` | The buyer won a chargeback. | Run `revoke_commands` to take the reward back. |
| `order.disputed` | The buyer opened a dispute. No money has moved yet. If it is lost, `order.charged_back` follows; if you win it, nothing more is sent. | Optional: hold the reward until it is settled. |
| `delivery.failed` | An in-game command failed for the fifth time and will not be tried again. | Tell your staff. The command can be retried from the dashboard. |

```
{
  "event": "sale.paid",
  "order_id": "8b1f0e2c-1d3a-4c5e-9f77-2a0b6d4e1c33",
  "product": "VIP Rank",
  "amount": "300.00",
  "net": "292.75",
  "buyer": "Notch",
  "recipient": "Jeb_",
  "shop": "Kanto SMP",
  "product_image": "https://kantopay.com/uploads/vip.png",
  "paid_at": "2026-10-04T04:11:57.412345678+00:00",
  "commands": ["lp user Jeb_ parent add vip"],
  "items": [{ "product_id": "5d0c9a7e-2f41-4b8e-a1c3-7e6f5d4c3b2a", "name": "VIP Rank", "quantity": 1, "amount": "300.00" }],
  "metadata": null,
  "test": false,
  "delivery_id": "c1a7f0e2-9b3d-4e6f-8a21-0d5c7b9e4f13"
}
```

`amount` is what the buyer paid and `net` what reaches you after fees, both pesos as strings. `buyer` paid; `recipient` is who the rewards are for (the gift’s recipient, otherwise the buyer). `commands` are your product’s commands with `{player}` already filled in with `recipient` and any leading `/` removed, ready to run; or ignore them and grant from `items`, the order’s lines (`product_id` is `null` for a product deleted since). `metadata` is what you sent with [`POST /payments/from-product`](https://kantopay.com/documents#ep-pfromproduct), otherwise `null`. `paid_at` is RFC 3339 with a `+00:00` offset and fractions of a second; parse it, do not slice it.

The order events carry the same `order_id`, `product`, `amount`, `buyer`, `recipient`, `shop`, `items`, `test` and `delivery_id`, plus `reversal_type` and `occurred_at`. Instead of `commands` they carry `revoke_commands`: your product’s removal commands, filled in the same way. The different name is on purpose, so a handler that runs `commands` on every event cannot grant the reward again on a refund. A full refund KantoPay made without taking the reward back sends `revoke_commands: []` and `reward_kept: true`, so leave the reward in place. `delivery.failed` adds `reward_delivery_id`, `kind` (`grant` or `revoke`), `command`, `error` (what your plugin reported), `attempts` and `server` (that server key’s name), without `revoke_commands`.

```
{
  "event": "order.refunded",
  "order_id": "8b1f0e2c-1d3a-4c5e-9f77-2a0b6d4e1c33",
  "product": "VIP Rank",
  "amount": "300.00",
  "buyer": "Notch",
  "recipient": "Jeb_",
  "shop": "Kanto SMP",
  "reversal_type": "refunded",
  "items": [{ "product_id": "5d0c9a7e-2f41-4b8e-a1c3-7e6f5d4c3b2a", "name": "VIP Rank", "quantity": 1, "amount": "300.00" }],
  "revoke_commands": ["lp user Jeb_ parent remove vip"],
  "test": false,
  "occurred_at": "2026-10-05T02:30:00.000000000+00:00",
  "delivery_id": "0d3b6a2e-7c41-4f8a-b5e9-1a2c3d4e5f60"
}
```

### Signature verification

Anyone can send a request to your address, so check every one before acting on it:

1. Take `X-KantoPay-Timestamp`, a literal `.`, and the request body **exactly as it arrived**, before any JSON parsing. A body you parsed and turned back into text will not match.
 2. Compute HMAC-SHA256 over that with your whole secret, `whsec_` included, as the key, and write it as lowercase hex.
 3. Compare it with `X-KantoPay-Signature` in constant time, and refuse a timestamp more than 5 minutes from your clock. That stops someone replaying an old request they caught.
 4. Save the event (or put it on a queue), skipping any `X-KantoPay-Delivery` id you already have, and only then answer `2xx`.
 5. Do the work after answering. If you answer first and crash before saving, the event is lost: we only send it again when you do not answer `2xx`.

If the KantoPay plugin already delivers your rewards in game, do not grant them again from the webhook. Use the webhook for everything else, such as a database, a bot or an email.

Signing the body alone, `HMAC(secret, body)`, never matches: the timestamp is part of what we sign.

```
// Node.js with Express
const crypto = require('crypto');
const express = require('express');
const app = express();
const SECRET = process.env.KANTOPAY_WEBHOOK_SECRET; // the whole whsec_… value

// express.raw keeps the exact bytes we sent. Parse JSON only after the check.
app.post('/kantopay-webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  const ts = req.get('X-KantoPay-Timestamp') || '';
  const sig = req.get('X-KantoPay-Signature') || '';
  const expected = crypto.createHmac('sha256', SECRET).update(ts + '.').update(req.body).digest('hex');
  const ok = sig.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
    && Math.abs(Date.now() / 1000 - Number(ts)) <= 300;
  if (!ok) return res.sendStatus(401);

  const event = JSON.parse(req.body);
  // Keep it before saying yes. saveOnce() is yours: a table with a unique key on the delivery id.
  await saveOnce(req.get('X-KantoPay-Delivery'), event);
  res.sendStatus(200);
  // Now do the work, from what you saved (a queue worker, a job, a cron).
});
```

```
<?php
// PHP
$secret = getenv('KANTOPAY_WEBHOOK_SECRET');      // the whole whsec_… value
$body   = file_get_contents('php://input');       // the raw bytes, before json_decode
$ts     = $_SERVER['HTTP_X_KANTOPAY_TIMESTAMP'] ?? '';
$sig    = $_SERVER['HTTP_X_KANTOPAY_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $ts . '.' . $body, $secret);
if (!hash_equals($expected, $sig) || abs(time() - (int) $ts) > 300) {
    http_response_code(401);
    exit;
}
$event = json_decode($body, true);
save_once($_SERVER['HTTP_X_KANTOPAY_DELIVERY'] ?? '', $event);   // yours: unique on the delivery id
http_response_code(200);                                         // only after it is kept
```

### Retries and resend

**Answer with a `2xx` within 8 seconds.** Anything else counts as a failure: another status, no answer in time, or a redirect, which is never followed. A failed event is sent again after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, 6 tries in all. After the sixth it is marked failed and the store owner gets an email, at most one a day.

**Delivery is at least once.** A retry, or a resend, can bring you an event you already handled, so dedupe on `X-KantoPay-Delivery`. Events can also arrive out of order when one of them was retried; when order matters, read the order itself with [`GET /v1/orders/{id}`](https://kantopay.com/documents#ep-v1order). A sale that settles while our server restarts still gets its `sale.paid`, a few minutes late.

Your address must be `https://` and on the public internet. Private and internal addresses are refused when you save and again each time we send.

**Recent deliveries**, under the Developer webhook in the dashboard, lists the last 50 events: whether each was sent, is waiting for its next try, or failed, with its tries, your server’s last HTTP status and the error. The store owner can **Resend** any of them: the same event, with the same `X-KantoPay-Delivery` id and body and a fresh timestamp and signature, to the address saved now. Events are kept 30 days. One whose body was not kept (sent before this log existed, or over 64 KB) cannot be resent.

---

## Changelog

**2026-10-22** — **New: the Server API sells everything the Storefront API sells.** With your key, [`POST /server/quote`](https://kantopay.com/documents#ep-squote) and [`POST /server/checkout`](https://kantopay.com/documents#ep-scheckout) take a whole cart (quantities, variants, upgrade pricing, a coupon, a gift card, a gift recipient), and [`/server/giftcards`](https://kantopay.com/documents#ep-sgiftcards) and [`/server/giftcards/check`](https://kantopay.com/documents#ep-sgccheck) list, sell and check gift cards. Same body and same answer as their Storefront API twins. A test server’s key (`kp_test_`) can quote and check out, and its orders are test orders. A gift-card sale also accepts `buyer_email` as the address the card is sent to.

**2026-10-05** — **Changed: gift cards, sales and "was" prices follow consumer law.** [`POST /accounts/gift-cards/issued/{id}/void`](https://kantopay.com/documents#ep-gcvoid) answers `409 gift_card_has_balance` for a card that still has a balance (RA 10962); only a spent card can be voided. Creating or updating a product with a sale now needs `sale_starts_at` and `sale_ends_at`, no more than 3 months apart, else `422 validation_error` on `sale_ends_at`. Stores show a sale or a `compare_at_amount` as a struck-through price only once the item has been offered at that price for 28 of the last 90 days; the sale price is charged either way, and `/products/catalog` reports `on_sale` and `sale_percent` by the same rule.

**2026-10-05** — **New: the KantoPay plugin takes rewards back in game.** Version 3.7.1, on every platform, polls [`/rewards/revocations`](https://kantopay.com/documents#ep-rrevoke), runs the removal commands for refunds, chargebacks (a dispute you lose is one) and expired timed packages, and acknowledges them. Earlier versions never did, so update from Dashboard › Plugin. Your own integration needs nothing new.

**2026-10-04** — **New: [webhooks](https://kantopay.com/documents#webhooks) are documented here, with more events, a delivery log and resend.**

- The developer webhook sends `order.refunded`, `order.charged_back`, `order.disputed` and `delivery.failed` as well as `sale.paid`. `sale.paid` gains `recipient`, `items`, `metadata`, `test` and `delivery_id`, and its `commands` now name the gift’s recipient, not the buyer.
- **Send a test event** now sends a signed `sale.paid` with `"test": true`. It used to send `"event": "test"`, so a handler that skipped that must now skip `test: true`. Test orders send `sale.paid` with `"test": true` too.
- The signature is `HMAC-SHA256(secret, X-KantoPay-Timestamp + "." + raw_body)`. An HMAC of the body alone never matches. See [Signature verification](https://kantopay.com/documents#webhooks-verify).
- The dashboard lists the last 50 events with your server’s answers, and the owner can resend any of them. An event that fails for good is emailed to the owner.

**2026-10-04** — **New: [test orders](https://kantopay.com/documents#storefront-test), [cancel](https://kantopay.com/documents#ep-v1cancel) and [many players in one call](https://kantopay.com/documents#ep-splayers).**

- A test storefront token (`kps_test_`) and test server keys (`kp_test_`) rehearse checkout, payment, settlement and delivery without real money. A test key gets `403 test_key_not_allowed` outside the routes a test server needs.
- [`POST /v1/orders/{id}/cancel`](https://kantopay.com/documents#ep-v1cancel) cancels an unpaid order, with the `cancel_token` its checkout answered with. Its gift-card, coupon and purchase-limit holds last until its QR code’s deadline, because that code can still be paid.
- [`GET /server/players?names=`](https://kantopay.com/documents#ep-splayers) answers for up to 50 players in one request.

**2026-10-04** — **Changed: the Storefront API.**

- [/checkout](https://kantopay.com/documents#ep-v1checkout) and [POST /giftcards](https://kantopay.com/documents#ep-v1gcbuy) return `redirect_url`, the pay page’s full address. `redirect` is unchanged.
- [/quote](https://kantopay.com/documents#ep-v1quote) returns `lines`, `payment_methods`, `free_order`, `is_test` and `blocked`, the `409` checkout would give for a purchase limit or opening hours.
- An order a 100% coupon covers is settled and delivered at checkout. It used to be refused with `400 cart_total_zero`.
- [POST /giftcards](https://kantopay.com/documents#ep-v1gcbuy) takes `idempotency_key`, and a custom amount is never under ₱20, even with a blank minimum.
- [GET /v1/orders/{id}](https://kantopay.com/documents#ep-v1order) adds `gift_card_code`, `gift_card_code_masked` and `delivery`.
- [Categories](https://kantopay.com/documents#ep-v1categories) add `id`, `image_url`, `blurb` and `is_ladder`. Categories hidden from your store’s navigation are left out, there and on [/v1/shops/{token}](https://kantopay.com/documents#ep-v1shop).
- An unknown product id on [/products/{id}](https://kantopay.com/documents#ep-v1product) answers `404 product_not_found`, not `shop_not_found`.

**2026-10-04** — **Changed: the Server API.** The items marked *check* can change what an existing integration sees.

- A key works in `X-API-Key` on the dual-auth routes too, and gets the same 120 requests a minute there (*check*: those routes had no limit). A database that cannot answer while checking a key gives `503 service_unavailable` with `Retry-After`; it used to say `401`, as if the key were wrong. Refusals now carry CORS headers, `X-Request-ID` and a JSON content type.
- [/rewards/acknowledge](https://kantopay.com/documents#ep-rack) refuses a status other than `delivered` or `failed` for that id: its outcome is `invalid_status` and it stays pending (*check*: such a status used to count as delivered). The rest of the batch is recorded. It now returns an `outcome` per id.
- [/rewards/info](https://kantopay.com/documents#ep-rinfo): `pending_deliveries` counts rewards to give only, and the new `pending_revocations` counts removals waiting on [/rewards/revocations](https://kantopay.com/documents#ep-rrevoke).
- [/players/{name}/purchases](https://kantopay.com/documents#ep-ppurchases) leaves out refunded, charged-back and test orders unless you pass `include_reversed` or `include_test` (*check*), and adds `reversal_type` and `is_test`.
- [/server/players/{name}](https://kantopay.com/documents#ep-splayer): a timed product whose time has run out leaves `owned`, and each purchase adds `active` and `expires_at`. A renewed timed rank is no longer removed by the earlier purchase’s expiry.
- [/payments/from-product](https://kantopay.com/documents#ep-pfromproduct) prices rank tiers as upgrades like the web store, answers `400 already_owned` for a tier the player holds, and keeps each command’s online, slot and delay conditions. An unknown product or variant is `404 product_not_found` / `variant_not_found` (was `auth_not_found`), and a provider failure is `502 provider_unavailable` with `Retry-After: 5` (was a `500` with the provider’s own text).
- [/payments/list](https://kantopay.com/documents#ep-plist) filters by `from` and `to`. Both answered `500` before; a bad value is now `422`.
- The small-order limit’s `429` says in `Retry-After` how long until the buyer can order again, not a fixed 60 seconds.
- A reward meant only for servers you have since deleted, or bought before you had any server, goes to the first server that asks for it, and only to that one. It used to wait forever or run on every server.

**2026-10-04** — **New: [send buyers back to your website](https://kantopay.com/documents#storefront-return).** [/checkout](https://kantopay.com/documents#ep-v1checkout) and [POST /giftcards](https://kantopay.com/documents#ep-v1gcbuy) take `return_url` and `auto_return`. The receipt’s Back button goes to `return_url` with `order_id` and `status`; with `auto_return` a paid buyer goes there straight away. List your sites under Your website in the dashboard first; any other address is `400 return_url_not_allowed`. [GET /v1/orders/{id}](https://kantopay.com/documents#ep-v1order) now returns `shop_slug`, so your site can check an order is its own. **Changed:** a `/checkout` that a gift card pays in full answers `200` with `redirect` and `order_id` like every other order. It used to answer a `303` to the pay page, which a page on your own domain cannot follow.

**2026-10-04** — **Fixed: [POST /v1/shops/{token}/giftcards](https://kantopay.com/documents#ep-v1gcbuy) sells gift cards.** It used to look the token up as a shop address and answer every call `400 denomination_unavailable`, whatever the amount. It now finds the shop by its token like every other Storefront API route, and a token that is not a published shop answers `404 shop_not_found`. The card is emailed to `recipient_email` (this page used to say `buyer_email`, which is ignored), `buyer_name` is optional, and `amount` is in pesos. Also since 2026-10-02: refunding or charging back a gift-card purchase voids the card (a partial refund takes the refunded amount off it), and gift cards never expire, so `expiryDays` is no longer accepted.

**2026-09-15** — **Changed: [/accounts/wallet/history](https://kantopay.com/documents#ep-whist) says what each order’s commands did.** Every entry tied to an order now carries `execution`: how many of its commands were queued (`total`), how many are `delivered`, `failed` and `pending`, how many of the pending wait for the player to join (`waiting_player`), and `last_run_at`, when the latest one was delivered (by the plugin, or by the seller pressing Mark delivered). It is `null` for withdrawals and for orders with nothing to run, including an order refunded before its commands ran. Every existing field is unchanged.

**2026-09-08** — **New: the [item catalog](https://kantopay.com/documents#item-catalog).** Capture a real Minecraft item in-game with `/kantopay item import <id>` and the plugin pushes it to [PUT /items/{id}](https://kantopay.com/documents#ep-item-put), where the dashboard can offer it on a product. Set a product’s `item_id` and settlement generates `kantopay item give <id> <player>` as an ordinary delivery, so **nothing changes on your side** — older plugin builds keep working, and [/rewards/pending](https://kantopay.com/documents#ep-rpending) now also reports `item_id` on the delivery for a build that would rather not parse it back out. [POST /audit](https://kantopay.com/documents#ep-audit) takes the in-game half of the trail that [/rewards/acknowledge](https://kantopay.com/documents#ep-rack) never saw: who imported, edited, deleted or handed out an item, and when.

**2026-09-05** — **New: a reference store at [example.kantopay.com](https://example.kantopay.com).** One HTML file on the [Storefront API](https://kantopay.com/documents#storefront), no backend, no key, with a console that shows each request as the page makes it. Every call it uses is documented here; the page links back to each one.

**2026-09-05** — **New: [/accounts/analytics](https://kantopay.com/documents#ep-analytics) and [/accounts/analytics/export](https://kantopay.com/documents#ep-anexport) on the Server API.** The dashboard’s Analytics numbers, and the period’s paid orders as CSV, for a `kp_` key as well as a dashboard session. One `days` parameter (7, 30, 90, or 0 for all time) scopes everything in the answer.

**2026-09-05** — **Changed: the order floor is ₱1.** `min_charge` on [/v1/shops/{token}](https://kantopay.com/documents#ep-v1shop) now reads `"1"`; `below_minimum` fires only under that. Two things replace what the old floor was quietly doing: cards are offered only from `card_min_charge` (₱100, their flat fee), and orders under `small_order.under` (₱20) share a budget of `small_order.max_per_hour` per buyer per shop, past which `/v1/checkout` answers `429 small_order_rate_limited`. Both numbers are on the shop identity, so read them rather than typing them. Gift cards start at ₱20.

**2026-09-05** — **Changed: [/accounts/wallet/history](https://kantopay.com/documents#ep-whist) names what a gift card or coupon did.** Two new `entry_type` values, `gift_card` and `coupon`, carry what a card covered or a code took off on an order; neither moves money. An order a card paid for in full no longer writes a zero-peso `credit`.

**2026-09-05** — **New: timed packages.** Set *“Remove automatically after N days”* on a product and its removal commands run when the window closes, arriving on [/rewards/revocations](https://kantopay.com/documents#ep-rrevoke) with `reason: "expired"`. Same feed, same acknowledge, no new plumbing on your side if you already poll it. 0 days = permanent, which is every existing product.

**2026-09-05** — **New: [/rewards/revocations](https://kantopay.com/documents#ep-rrevoke) takes a reward back when an order is reversed.** Until now a refund or chargeback returned the buyer’s money and stopped there — they kept the rank, and the shortfall landed on the seller. Poll the new endpoint alongside [/rewards/pending](https://kantopay.com/documents#ep-rpending) and confirm with the same [/rewards/acknowledge](https://kantopay.com/documents#ep-rack). Set the commands per product under *“If refunded, run these”*; leave it empty and nothing is revoked. **Nothing breaks if you ignore this:** `/rewards/pending` never returns a revocation, so existing plugins are unaffected until you choose to add it.

**2026-08-04** — **Fixed: cart purchases now count toward cumulative upgrade pricing.** An order placed through a cart — which is every `/v1/checkout` and every hosted-storefront checkout — recorded only the product *names* it contained, so the “what has this player already paid?” lookup could not see it. Two buyers who paid the same ₱500 for the same rank saw different prices for the next tier depending on which button they had pressed, and `owned` never went true for anything bought in a cart. Orders now record their line items; if you have historical cart orders, `db/backfill_cart_items.sql` recovers the single-item ones.
 Also: `/v1/products` takes `limit` and `offset` and returns `next_offset`, so a catalogue over 250 products is reachable at all; `/v1/checkout` returns `order_id`; order lookups return `items`; new `/v1/…/coupons/check` and `/v1/…/players/me/orders`.

**2026-06-12** — Per-server reward routing on API keys.

**2026-06-09** — Public REST API and this reference.