KantoPay API

The KantoPay API is a fast, idempotent payments-and-fulfilment service built for Southeast-Asian game stores. It creates local-rail payment links, tracks them to settlement, and routes the right command to the right server, while protecting you from double-delivery and double-spend. To know where to begin, refer to Get started.

Every request is authenticated with your API key (as a Bearer token or X-API-Key header). Endpoints marked Dual-auth also work from the dashboard; API key only endpoints require a key. Game-server plugins poll /rewards/pending and confirm with /rewards/acknowledge. Poll /rewards/revocations as well to take a reward back when an order is refunded or charged back.

All endpoints are served from the same origin as your store, under /payments, /rewards and /accounts. To make your first call:

1. Create an API key in your dashboard. Each key is bound to one game server.
2. Send the key as a Bearer token (or X-API-Key header).
3. Set up a product in your dashboard, then create a payment with POST /payments/from-product and show the returned QR/link to your buyer, or list your products via GET /products/catalog to build your own store UI.

Everything under /v1 is a JSON API for building your own storefront — your website, a Discord bot, an in-game GUI — against the same catalogue, pricing and checkout the hosted store uses. Same rails, same payouts, your front end.

No key. No signup. No CORS setup. These routes take no credential at all, because everything they return is already public as HTML on your store page — and a key shipped to a browser is readable by anyone who opens devtools, so it would protect nothing. Your kp_ API key stays secret and server-side, for reward delivery.

All you need is your storefront token — one per shop, in Dashboard › Servers:

Read this first — it is the shape of the whole thing. Your catalogue is authored in the dashboard, always. The API sells what you built; it cannot build it.

Read the catalogue, price the cart on the server, send the buyer to checkout. The cart itself lives in your client — there is no basket to create, no basket id to keep alive, and nothing to expire.

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 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 identical pricing code, so a quoted total can never disagree with what the buyer is charged. 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.

Poll GET /v1/orders/{id} 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 — an order created while your account is in test mode charges no real money, and a client that can’t tell will ship real goods for play money.

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

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

Which codes you can actually get depends on the endpoint, so each one lists its own. Open any endpoint below and use the response picker in its Response panel: every status it can return, with a real body for each, and what you did to earn it. That is more useful than a table you have to translate to your own call — and it cannot drift from the code the way a hand-kept list does.

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 120/min. 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.)

You don’t have to take one. Set hosted_storefront to false and /shop/your-slug stops existing — the page, the product pages, the checkout page, the custom pages and the sitemap all 404. Your products still live in the dashboard, the Storefront API still works, payments and reward delivery are untouched.

What you still get from us in that mode: the catalogue and pricing engine, the cart maths, coupons, gift cards, the buyer’s payment page at /pay/{link_id}, payouts, and in-game delivery. What you own: every pixel a player sees before checkout.

The Storefront API is for people who want control. If you just want your store on your existing site — WordPress, Wix, Squarespace, Carrd — the obvious move is an iframe.

Meanwhile the two shipping options are: link out to your hosted store (a button on your site pointing at kantopay.com/shop/your-slug, or your own domain once you connect one), or use the Storefront API — an afternoon of work for a store indistinguishable from the rest of your site, with no framing involved at all.

Slightly the wrong question, and it trips people up. /v1 is not a lower permission level than an API key — it is the absence of a credential. There is one API: half of it needs proof of who you are, half of it does not. That is the whole distinction — not two permission tiers, one API with a public half and a private half.

So a key holder can call /v1 too. Nothing stops them; those routes never look at the Authorization header. The real question is not what may this credential do — it is:

The private rows are the ones that matter. They are private not because a key unlocks extra features, but because they expose other people’s data and your money — and a credential is the only way to tell your server apart from a stranger asking the same question.

One asymmetry worth knowing: while your account is in test mode the whole /v1 surface returns 503 shop_unavailable, because the storefront is closed to the public. POST /payments/from-product keeps working and stamps the order is_test, so your server-side integration can carry on rehearsing.

They compose. The common setup is your own website for buying and the plugin on each server for delivering — the same order flows through both.

Every panel below is live — real requests against the real API. Each one needs your storefront token, the kps_… value that identifies your shop to /v1. It is not your slug: /v1/shops/123 returns 404 shop_not_found even when 123 is a real, published shop. Find yours in Dashboard › Servers, under the server keys — copy it and paste it into the token field. (Or fetch it with GET /accounts/shop/storefront-token while signed in.) There is exactly one per shop, and you can rotate it from that same page if it ever ends up somewhere it should not. The token is safe in a browser — it only reads what your storefront already shows the public. Your kp_ key is the opposite and must never go near one.

The half that needs a key: taking payments from your own backend, delivering rewards in-game, reading your wallet and order history, and — new — managing your coupons and gift cards. Those last two used to be dashboard-only, which meant an integration could sell through a coupon but never create one. Runs on a machine you control — never in a browser. Every endpoint below shows its method, path, required credential, parameters and a copyable multi-language sample.

Authentication. Create an API key in your 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. 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.

Every Server API endpoint is a plain GET or POST over 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.

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 here (400.0), not a string — the older /v1 catalogue returns amounts as strings, so do not assume one shape across both halves. 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.

Read the status first to know what kind of problem you have, then the code to know which one. Only these can reach a Server API caller.

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

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.

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

120 requests per 60 seconds, per key. 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. The storefront half is limited differently — per IP, per endpoint — see its own errors section.

Two headers are worth reading on every response:

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.

What period means, and when it resets

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, so a plugin and your shop page can never report two different numbers for the same word.

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 money you refunded. Charged-back, refunded, disputed and voided orders are excluded from every window.

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 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 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.

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 the storefront and over /v1 alike. Delete is equally immediate.

Do you support subscriptions or refunds?
No. KantoPay is a one-time-purchase model and all sales are final, which keeps fulfilment simple and fees predictable.

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.

2026-09-08 — New: the item catalog. Capture a real Minecraft item in-game with /kantopay item import <id> and the plugin pushes it to PUT /items/{id}, 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 now also reports item_id on the delivery for a build that would rather not parse it back out. POST /audit takes the in-game half of the trail that /rewards/acknowledge never saw: who imported, edited, deleted or handed out an item, and when.

2026-09-05 — New: a reference store at example.kantopay.com. One HTML file on the Storefront API, 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 and /accounts/analytics/export 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} 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 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 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 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 and confirm with the same /rewards/acknowledge. 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.

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.