Introduction
This page is the integration specification for publishers and developers who ship a browser-based web application (Web App) on TapFun. Your web application runs embedded in an iframe on a TapFun page.
If you ship a Windows exe through cloud gaming, see the Cloud Gaming specification instead.
Setting up communication
- Email is the default channel.
- If needed, TapFun creates a Slack Connect channel shared by both companies.
- If you cannot join a Slack Connect channel, we will join your company's communication tool instead.
Logging in to the Publisher Console
You can update your exe and change settings in the Publisher Console of the test environment (https://<TEST_HOST>/publisher). Your TapFun contact grants login access, so send us the email addresses of the people who will log in.
Release planning
Once the remaining issues have a clear path to resolution, we agree on the release date and pricing.
Reporting issues during development
When you hit a problem such as "input does not respond" or "unexpected behavior", report it in the communication channel with:
- The app name where the problem reproduces (if the test environment has several copies of the same game, include the app ID or other identifying information)
- The TapFun user account in the test environment where it happened (unless it only happens as a guest)
- Screenshots that show the situation
- A screen recording of the full reproduction steps, if screenshots are not enough
- The steps to reproduce
If the problem comes from intended behavior, both parties may discuss adding or changing a feature.
Debugging
Add one of these parameters to the game page URL to see the client API traffic.
| Parameter | Effect |
|---|---|
?debugLog=1 |
Shows a log area over the game screen with the client API requests TapFun received (including consoleLog). The second line shows the TapFun user ID of the player who is playing. |
?verbose=1 |
Writes detailed logs to the browser's developer tools console, including the data of consoleLog. |
FAQ
Q. Can the game get the player's wallet balance, or how much they are short when the balance is not enough for purchaseItem?
A. No. The TapFun wallet balance and the shortfall cannot be obtained through the client API, the Web API, or the Callback API.
Q. Can the game find out the player's language or country?
A. Yes. The {lang} (the player's language) and {country} (the country the player connects from) placeholders in the launch URL pass them to your web application (How it works). While the game is running, you can also get them as language and country from getPlayerEnvironment.
Environments
Hostnames
| TapFun environment | Hostname | Access check on the web UI |
|---|---|---|
| Test | Ask your TapFun contact (written as <TEST_HOST> in this document) |
Introduction pages and play screens: email verification / Publisher Console: Basic auth (ask your TapFun contact for the user name and password) |
| Production | https://tapfun.co.jp |
None |
The test environment hostname and the user name and password of the Publisher Console Basic auth are confidential and are not included in this document. Ask your TapFun contact for them. Replace <TEST_HOST> in code examples with the test environment hostname. Do not share them outside your company or anywhere public (public repositories, public channels, and so on).
Who can access the test environment
When you open an introduction page or a play screen in the test environment, an email verification page appears. Enter the verification code sent to the email address you entered, and the page opens. To play a game, you then also need to log in with a TapFun account.
The following people can pass the email verification:
- People who can log in to your Publisher Console
- People whose email address is registered in "Test players" in the Publisher Console. Register people who do not log in to the Publisher Console (such as QA vendors) here
- Write one address per line. An entry that starts with @, such as
@example.com, covers every email address in that domain - Changes take effect as soon as you save
- This applies only to the test environment. The production Publisher Console does not have "Test players"
- Write one address per line. An entry that starts with @, such as
Only your company's apps are shown in the test environment.
Payments in the test environment
To buy items in the test environment, use one of the following.
- AmazonPay: takes you to the "Multi-Payment Service test environment". Select "決済する" (Pay) to complete the payment.
- Test credit card: number
4111111111111111, any future expiry month/year, any 3-digit security code.
Test play in production
To access an app before release, enable maintenance mode in the Publisher Console's basic settings and enter the tester's email address in "Maintenance exception email addresses".
For tests in production that involve purchases, TapFun registers a test-play account for each app. The account receives TapFun credit usable only in that app. Purchases by test-play accounts are cancelled immediately and offset against sales.
Publisher Console
Basic settings
| Field | Description |
|---|---|
| App ID | Internal ID of the app. |
| name | Internal name. |
| apiKey | API key for calling the Web API. |
| Bearer token | Value of Authorization: Bearer when calling the Web API (format: <AppID>_<apiKey>). |
| Maintenance mode | When enabled, new game launches are blocked (How maintenance mode works). |
| Maintenance exception email addresses | Users with these email addresses can play during maintenance. For an unreleased (private) app, enabling maintenance mode also lets these accounts access it. |
| Launch URL | URL that launches your web application. TapFun loads it in an iframe. Placeholders: {token} (token for create_session), {host} (TapFun hostname, e.g. tapfun.co.jp), {appId} (app ID), {lang} / {country} (the player's language and country; see How it works). |
| sigKey | HMAC-SHA256 signing key. Used for the sig of purchaseItem and for signing the Callback API. |
| Require sig for purchaseItem | When enabled, purchaseItem without sig fails (invalidSignature). |
| Frameless display | When enabled, the TapFun header is not shown on the play screen. |
| callback HTTP POST URL | URL notified when an item is purchased (Callback API). |
| callback Notice Webhook URL | Webhook URL notified when sending a callback fails and when it recovers (e.g. a Slack incoming webhook). |
| callback Notice Email | Email address notified when sending a callback fails and when it recovers. |
| purchases API compatibility mode | Backward-compatibility mode that returns userId in the old format in the purchases API. Normally keep it disabled. |
How maintenance mode works
When you enable "Enable maintenance mode" and save:
- New launches: the play screen shows "現在「〇〇」はメンテナンス中です。少しお時間をおいてから、再度お試しください。" (under maintenance, please try again later) and the game does not launch.
- Games being played: they do not end and continue as they are. When the player reloads the page, the same message is shown.
- Exceptions: accounts in "Maintenance exception email addresses" can launch during maintenance.
- Introduction page: it is shown as usual, with no maintenance notice.
After you disable it and save, players can reopen the play screen and launch the game.
Analytics (Google Analytics)
When you set "Google Analytics measurement ID" under "Analytics" in the Publisher Console, page views and purchases on your TapFun introduction page and play screen are sent to your Google Analytics 4 (GA4) property. If it is blank, nothing is sent.
Setup
- In GA4 admin, find the "Measurement ID" (starting with
G-) shown on your web data stream. This is not the numeric "Property ID". - Enter it in "Google Analytics measurement ID" under "Analytics" in the Publisher Console and click "Save".
- Leading and trailing spaces are removed and letters are saved in upper case.
- Values that do not start with
G-cannot be saved.
- In the enhanced measurement settings of the GA4 data stream, turn off "Page changes based on browser history events". Otherwise the play screen is counted twice.
Pages that send data
- Introduction page (
https://tapfun.co.jp/p/<app>) - Play screen (
https://tapfun.co.jp/p/<app>/play), including a play screen opened in a new tab.
Other TapFun pages (top, account, charge, etc.) send nothing. After the player moves from these 2 screens to another page, enhanced measurement events (scrolls, etc.) are no longer sent either.
Events
| Event | When it is sent |
|---|---|
page_view |
When the introduction page or the play screen opens. Sent once for each. |
purchase |
When a purchase completes (purchases covered). |
All events carry these values.
| Parameter | Content |
|---|---|
user_id |
The TapFun user ID. |
page_location |
The page URL. Only query parameters starting with utm_ are kept; the rest are removed. |
page_view also carries the page title as page_title.
purchase carries these values.
| Parameter | Content |
|---|---|
transaction_id |
A unique key for each purchase. |
value |
Purchase amount (JPY). |
currency |
JPY (fixed). |
items |
The one purchased product, with item_id, item_name, item_category, price (same amount as value), and quantity (always 1). |
Login status (login_status)
Whether the player is logged in is sent as the user property login_status.
| Value | Meaning |
|---|---|
logged_in |
A player logged in to TapFun |
guest |
A guest (a player who is not logged in) |
- The login status at the time the page opens is attached from the first
page_view. - When a guest logs in on the screen, the value becomes
logged_infrom then on. Logging out changes it back toguest.
To use login_status in GA4 reports, register it as a user-scoped custom dimension. Data sent before you register it cannot be used in reports, so we recommend registering it right after you set the measurement ID.
Not sent
- Page views and purchases by test play accounts
- Energy purchases
- Cancellations and refunds. Check accurate sales in "Monthly sales" in the Publisher Console.
When the player returns in the same tab from TapFun's payment screens or Google login, that external site is not treated as the referrer.
Purchases covered
Item purchases made with purchaseItem are sent.
| Parameter | Value |
|---|---|
transaction_id |
Same as key in the Callback API and the purchases API |
item_id in items |
purchaseItem's code |
item_name in items |
purchaseItem's name |
item_category in items |
item |
Details (introduction page)
The "詳細情報" (details) tab edits what is shown on the game's introduction page on TapFun.
| Field | Description |
|---|---|
| Icon image | The game's icon. Recommended size: 512x512 (square). |
| 2:1 image | A wide image used in listings and on the introduction page. Recommended size: 1920x960. |
| Controls guide images | Optional images explaining the controls, which players can open from the TapFun screen while playing. |
| Screenshot images | Screenshots shown on the introduction page. |
| Game title | The game name shown on the introduction page and elsewhere. |
| Developer / Publisher | Developer and publisher names shown on the introduction page. |
| Game description | Body text of the introduction page, in Markdown. |
| Third-party EULA | License terms shown on the introduction page, such as third-party licenses included in the game. |
Drag controls guide images and screenshots to reorder them. To delete one, click it to mark it for deletion, then press "追加アップロード & 順序を保存" (upload and save order) to apply the change.
Launching the game
"アプリページ" (app page) at the top of the app screen launches the game with the options below (Debugging). Unreleased apps show "非公開状態" (private).
| Option | Description |
|---|---|
| ログ表示 (show log) | Shows consoleLog API and other logs on screen (same as ?debugLog=1). |
| verbose | Increases the logs written to the browser console (same as ?verbose=1). |
Other tabs
| Tab | Contents |
|---|---|
| 月別売上 (monthly sales) | Daily purchase counts, sales and cancellations, with a breakdown by sales category (Platform / Publisher). |
| 全ての Purchases / 未完了の Purchases (all / unfinished purchases) | List of purchases. "Unfinished" shows only purchases whose callback has not completed. You can resend the callback from each purchase. In the test environment you can also cancel a purchase and stop callback resends. |
| Callbacks | History of Callback API requests. |
| Leaderboards | Leaderboards and their entries. |
| 紹介ページ (introduction page) | Opens the game's introduction page on TapFun in a new tab. |
Launch and authentication
How it works
- The TapFun page is the parent frame. Your web application is embedded in an iframe and opened with the launch URL set in the Publisher Console.
- The placeholders in the launch URL (
{token}/{host}/{appId}/{lang}/{country}) are replaced with values at launch.{lang}is the player's most preferred browser language (a BCP 47 language tag, e.g.ja,en-US), and{country}is the country the player connects from (e.g.JP; see How country is determined). They are empty if they cannot be obtained.
- Communication with the TapFun parent frame uses the client API (postMessage).
Example launch URL:
https://game.example.com/play?host={host}&token={token}&appId={appId}User authentication / getting the TapFun user ID
- Send the value passed in
{token}from the browser to your game server. - Your game server calls
POST /api/v1/create_session, which returns the TapFun user ID. {token}is valid for 180 seconds. It can be reused while valid.
curl https://<TEST_HOST>/api/v1/create_session -X POST \
-H "Authorization: Bearer BEARER_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{"token":"TOKEN_HERE"}'
# {"result":"success","userId":"PLYRABCDEFGHIJKLMNOP123456789APPGRP"}Keep the Bearer token on the server. Never send it to the browser.
TapFun user IDs for guests and members
A Web App can be played by guests who are not logged in to TapFun.
| Situation | TapFun user ID |
|---|---|
| Playing as a guest | Issued per browser. It is tied to the cookie that keeps the TapFun login state (valid for one year), so it stays the same in the same browser. |
| A guest signs up | Does not change. The guest's ID becomes the member's ID. This also holds if the page is reloaded during sign-up or the confirmation email is opened in another browser. |
| An existing member plays as a guest, then logs in | Switches to the member's ID. TapFun keeps no record linking the guest ID and the member ID. |
| The cookie is lost, or another browser is used | A new ID is issued as a different guest. |
- Guests cannot play in the X (formerly Twitter) in-app browser (TapFun asks them to open an external browser).
- Logging in or signing up navigates the TapFun page, so the game is launched again and receives a new
{token}. The ID can change, so get it with create_session on every launch.
Client API
APIs for communication between your web application and TapFun, its parent frame. Messages are exchanged in the player's browser, so never include secrets.
| API | Summary |
|---|---|
| purchaseItem | Item purchase |
| getPlayerEnvironment | Get the player's environment |
| getOneTimeData | Read the URL's onetime value once |
| proposeAuthentication | Prompt the player to log in |
| openAccount | Open the account page |
| reboot | Restart |
| consoleLog | Show a log message |
Transport
| Item | Value |
|---|---|
| Sending | window.parent.postMessage(JSON string, "https://" + {host}) |
| Receiving | The message event on window. event.data is a JSON string. |
| Encoding | UTF-8 |
| Request / response format | JSON |
TapFun accepts a message only if it comes from the embedded iframe and its origin matches the launch URL's origin. On your side, check that event.origin is https://{host}.
const params = new URLSearchParams(location.search);
const tapfunOrigin = 'https://' + params.get('host'); // include {host} in your launch URL
function send(data) {
window.parent.postMessage(JSON.stringify(data), tapfunOrigin);
}
window.addEventListener('message', (event) => {
if (event.origin !== tapfunOrigin) return;
const data = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
console.log('from TapFun', data);
});
send({ req: 'getPlayerEnvironment' });purchaseItem
Shows the item purchase confirmation dialog and processes the payment. When the payment succeeds, TapFun notifies your game server through the Callback API. Grant the item on your game server when it receives the callback.
| Parameter | Required | Description |
|---|---|---|
req |
✓ | purchaseItem (fixed) |
tran |
✓ | Transaction ID generated by your app, unique per app. Purchase is refused if a past purchase (successful or not) used the same tran |
code |
✓ | Product code (any value; used for aggregation on TapFun) |
item |
Composite product code (any value) | |
amount |
✓ | Price (300-10000) |
name |
✓ | Product name (any value) |
img |
Product thumbnail image URL | |
note |
Free-form field | |
ret |
Return target. When charging the TapFun wallet involves a page transition, this sets the path (and after) of the launch URL used to restart the app. It is treated as a launch URL, so placeholders such as {host} are needed again. Must start with /. Example: /purchaseReturn?host={host}&token={token}&appId={appId}#anchor |
|
sig |
* | Signature (How to sign). Required if "Require sig for purchaseItem" is enabled in the Publisher Console. Always verified when sent |
Request example:
{
"req": "purchaseItem",
"tran": "UNIQUE_TRANSACTION_ID_HERE",
"code": "code_type01",
"item": "item_type01",
"img": "https://example.com/img/item.png",
"amount": 500,
"name": "300 Gems",
"ret": "/purchaseReturn?host={host}&token={token}&appId={appId}#anchor",
"sig": "SIGNATURE_HASH_HERE"
}How to sign
Join the following values with & in this order, compute HMAC-SHA256 with the Publisher Console's sigKey as the key, and use the lowercase hex string.
tapfunUserId&tran&code&item&amount&name&img¬e&rettapfunUserIdis not a request parameter, but it is required in the string to sign.- Do not omit empty values such as
item/img/note/ret; keep consecutive&. Example:PLYR123456DBG&ABCD&gem300&&500&300 Gems&&& - Compute the signature on your game server. Never send sigKey to the browser.
// Node.js (game server)
import { createHmac } from 'node:crypto';
function purchaseSig(sigKey, p) {
const s = [p.tapfunUserId, p.tran, p.code, p.item ?? '', p.amount, p.name, p.img ?? '', p.note ?? '', p.ret ?? ''].join('&');
return createHmac('sha256', sigKey).update(s).digest('hex');
}Response notifications
Every notification includes from (purchaseItem). All notifications except parameterError also include code (the requested code) and tran (the requested tran).
result |
When | Extra keys |
|---|---|---|
received |
The purchase event was received and the confirmation dialog opened | — |
purchaseCancel |
The confirmation dialog was closed (purchase cancelled) | — |
purchase |
The purchase button in the dialog was pressed | — |
purchaseSuccess |
The payment succeeded | — |
incompleteCallback |
The purchase failed (sent when the failure modal is shown) | reason (below) |
parameterError |
A required parameter (tran / code / amount / name) is missing (an amount of 0 or a non-numeric amount counts as missing), or amount is negative |
reason: error details (e.g. required param not found "code"; invalid param "amount" for a negative amount) |
reason |
Description |
|---|---|
duplicateTran |
The tran duplicates a past purchase |
unfinishedClallbackPrucahseRemaining |
There is an unfinished callback (e.g. due to a network error). The spelling is exactly as shown |
rejected |
The callback response's result was reject |
unknown |
The callback result could not be obtained for an unknown reason |
invalidSignature |
The signature did not match |
- If the
tranmatches a past purchase, a pre-purchase check shows an error dialog. If the check is passed due to timing, the error dialog is still shown when the sametranis detected after the purchase button is pressed. - To reproduce the duplicate
tranerror, open TapFun's game page with?purchasableCheck=0added to the URL and call purchaseItem from the game with the sametran. The pre-purchase check is skipped so the purchase button can be pressed. - You can see the requests the browser received in the browser's developer tools console.
getPlayerEnvironment
Gets the player's environment.
| Parameter | Required | Description |
|---|---|---|
req |
✓ | getPlayerEnvironment (fixed) |
Response:
| Key | Description |
|---|---|
from |
getPlayerEnvironment |
userAgent |
The browser's navigator.userAgent |
isSP |
1 / 0. See How isSP is determined for the logic and how tablets are handled. |
authenticated |
1: logged in / 0: guest |
language |
The player's most preferred browser language (a BCP 47 language tag, e.g. ja, en-US). Empty if it cannot be obtained. |
country |
The country the player connects from (e.g. JP). See How country is determined for how it is determined and which countries are supported. |
How isSP is determined
isSP is determined only from the browser's User-Agent string (navigator.userAgent). Screen size, touch support, and device orientation are not checked.
It is 1 if the User-Agent contains any of the following, and 0 if it contains none of them.
iPhoneiPodiPad- Both
AndroidandMobile
| Device / browser | User-Agent | isSP |
|---|---|---|
| iPhone | Contains iPhone |
1 |
| iPad (Safari "Request Desktop Website" on) | Same as a Mac (contains Macintosh, does not contain iPad) |
0 |
| iPad (Safari "Request Desktop Website" off) | Contains iPad |
1 |
| Android smartphone | Contains Android and Mobile |
1 |
| Android tablet | Contains Android but not Mobile, or does not contain Android when viewing the desktop site |
0 |
| Windows / Mac (including touch-enabled PCs) | Contains none of the above | 0 |
- The default of "Request Desktop Website" on iPad (Settings → Apps → Safari) differs by model. So an iPad's
isSPcan be either0or1even with the settings unchanged. - Browsers other than Safari are also determined by whether their User-Agent contains
iPad. - There is no value that indicates a tablet. To tell tablets apart, check the
userAgentfrom getPlayerEnvironment in your game. Note that an iPad with "Request Desktop Website" on sends the same User-Agent as a Mac, so the User-Agent alone cannot tell an iPad from a Mac.
How country is determined
country is the country that AWS WAF determines from the IP address the player connects from. The value is an ISO 3166-1 alpha-2 country code (e.g. JP). The countries AWS WAF can determine are those listed under CountryCodes in GeoMatchStatement. If the country cannot be determined, the value is empty.
getOneTimeData
Reads the onetime query string value of the TapFun page URL, once. Useful for deep links. After the request, onetime is removed from the URL.
- Keep the part of the URL after
?(includingonetime=and any other parameters) within 2,048 bytes after URL encoding. Longer URLs fail to open (403 error). onetimeis not carried over when the player returns from the login or sign-up screens. Read the value before prompting the player to log in.
| Parameter | Required | Description |
|---|---|---|
req |
✓ | getOneTimeData (fixed) |
Response:
| Key | Description |
|---|---|
from |
getOneTimeData |
onetime |
Decoded value of onetime. Empty string if already read or absent |
Example: when the URL is https://tapfun.co.jp/p/dummy/play?onetime=abcdefg
// 1st request
{ "from": "getOneTimeData", "onetime": "abcdefg" }
// 2nd request (onetime has been removed from the URL)
{ "from": "getOneTimeData", "onetime": "" }With an encoded value:
// ?onetime=page%3Dqrcode%26code%3Daaaa
{ "from": "getOneTimeData", "onetime": "page=qrcode&code=aaaa" }
// ?onetime=abc%0D%0Adef%0D%0Aghi
{ "from": "getOneTimeData", "onetime": "abc\r\ndef\r\nghi" }proposeAuthentication
Prompts the player to log in. For a guest, shows the sign-up / login modal.
| Parameter | Required | Description |
|---|---|---|
req |
✓ | proposeAuthentication (fixed) |
Response:
| Key | Description |
|---|---|
from |
proposeAuthentication |
authenticated |
1: already logged in, nothing was done / 0: guest, the modal was shown |
openAccount
Opens the account page. For a guest, shows the sign-up / login modal.
| Parameter | Required | Description |
|---|---|---|
req |
✓ | openAccount (fixed) |
Response: none
reboot
Restarts the game, the same as when the player taps the restart icon in the TapFun UI.
| Parameter | Required | Description |
|---|---|---|
req |
✓ | reboot (fixed) |
Response: none
consoleLog
Adds a log line to TapFun's log area. It is also written to the browser's developer tools console.
| Parameter | Required | Description |
|---|---|---|
req |
✓ | consoleLog (fixed) |
data |
✓ | A string or JSON string. If JSON.parse() succeeds, it is shown in the console as a JSON object. |
Response: none
Callback API (item purchase notification)
When a purchaseItem payment succeeds, the TapFun server notifies your game server of the purchase.
Specification
| Item | Value |
|---|---|
| Endpoint | "callback HTTP POST URL" in the Publisher Console |
| Source IP address | Test: ask your TapFun contact / Production: 54.178.93.41 |
| Method | HTTP POST |
| Content-Type | application/json |
| Encoding | UTF-8 |
| Response | JSON (Response) |
| Timeout | 5 seconds |
Request headers:
| Header | Description |
|---|---|
X-TapFun-Callback-Key |
Unique key per callback |
X-TapFun-Retry |
Retry count (only on retries) |
X-TapFun-Signature |
HMAC-SHA256 of the request body signed with sigKey (hex). Compute it from the raw body string as received |
// Signature verification example with Node.js (Express)
import { createHmac, timingSafeEqual } from 'node:crypto';
app.post('/tapfun/callback', express.raw({ type: 'application/json' }), (req, res) => {
const expected = createHmac('sha256', SIG_KEY).update(req.body).digest('hex');
const actual = req.get('X-TapFun-Signature') || '';
if (expected.length !== actual.length || !timingSafeEqual(Buffer.from(expected), Buffer.from(actual))) {
return res.status(400).json({ result: 'error' }); // anything other than success / reject is retried
}
const purchase = JSON.parse(req.body);
// process idempotently by purchase.tran and grant the item
res.json({ result: 'success' });
});Notifications and retries
- The first failure and the recovery are notified to "callback Notice Email" and "callback Notice Webhook URL" in the Publisher Console.
- At purchase time, after a failure or timeout TapFun waits 0.5 seconds and retries 3 times. If all 3 fail, a failure modal is shown to the player.
- After that, retries continue at these intervals:
- Up to 10 minutes: every minute
- Up to 60 minutes: every 5 minutes
- Up to 12 hours: every hour
- Up to 7 days: every 12 hours
- After that, you need to re-run it manually from the Publisher Console.
- While a purchase has an unfinished callback, the player cannot buy another product with the same
code.
Request
| Key | Description |
|---|---|
req |
purchaseItem |
event |
purchaseItem |
result |
success |
key |
Unique key per purchase |
appId |
App ID |
userId |
TapFun user ID |
publisherUserId |
Your user ID for the player, or null if not set |
fromRegisterDevice |
Device the player signed up to TapFun on (SP / PC) |
purchaseDevice |
Device used for the purchase (SP / PC) |
salesDistinction |
Sales category (Publisher / Platform) |
tran |
Transaction ID |
code |
Product code |
item |
Composite product code, or null |
amount |
Price |
name |
Product name |
img |
Image URL, or null |
note |
Note, or null |
createdAt |
Purchase time (UTC) |
{
"req": "purchaseItem",
"event": "purchaseItem",
"result": "success",
"key": "01HRC7QZV1GVT0WX9G6EKSYCAS",
"appId": 1,
"userId": "PLYR01HE2R3JV6Y2NEGRMS4KZQB861DBG",
"publisherUserId": null,
"fromRegisterDevice": "PC",
"purchaseDevice": "PC",
"salesDistinction": "Publisher",
"tran": "abcdef123456",
"code": "gem300",
"item": "itemGem300",
"amount": 500,
"name": "300 Gems",
"img": "https://example.com/img/item.png",
"note": null,
"createdAt": "2024-03-06T06:37:22.000Z"
}Response
Your game server must return success or reject in the JSON result. Otherwise TapFun retries. The HTTP status is not evaluated, but 200 is recommended. Redirects are not supported.
// Purchase succeeded
{ "result": "success" }
// Purchase rejected
{ "result": "reject" }- With
success, the sale is officially recorded. - With
reject, the purchase is cancelled and the player's wallet balance is not reduced (the player's history shows the purchase and a refund). - If your game server detects the same
tranagain, return the result of the existing purchase (idempotency). For example, if the existing purchase with thattransucceeded, returnsuccess.
Web API
HTTP APIs called from your servers. Keep the Bearer token on the server and never send it to the browser.
Common specification
| Item | Value |
|---|---|
| Base URL | https://<environment hostname>/api/v1 (Hostnames) |
| Method | HTTP GET / POST |
| Encoding | UTF-8 |
| Request headers | User-Agent is required (any value, e.g. ExampleGames-Server/1.0). Requests without it are rejected |
| Request format | URL path, query string, POST data (application/x-www-form-urlencoded unless stated otherwise) |
| Response format | JSON. An empty array when an array result has no items. HTTP status is 200 unless stated otherwise |
| Date/time | UTC, yyyy-mm-ddThh:mm:ss.sssZ |
Authentication
Authenticate with the HTTP header Authorization: Bearer <AppID>_<APIKey> (the Bearer token in the Publisher Console).
Authorization: Bearer 123_NWU0MjlkY2ViYTVkOTdiYjIwNThmZTkxMDMzYWM4Y2JmNGUyMTQ0NgOn authentication failure the API returns HTTP 403 with:
{"error":"no authorization"}If the User-Agent header is missing, the API returns an HTML 403 Forbidden page instead of the JSON above.
POST /api/v1/create_session
Gets the TapFun user ID from the launch URL's {token} (User authentication). Authentication: required.
| POST data | Required | Description |
|---|---|---|
token |
✓ | Value passed in the launch URL's {token} |
// Success
{ "result": "success", "userId": "<TapFun user ID>" }
// Failure (400): token missing
{ "result": "failure", "message": "token is missing" }
// Failure (400): token invalid
{ "result": "failure", "message": "token is invalid" }GET /api/v1/purchases
Gets the purchase history, newest first. Useful for checking purchases whose callback you missed. Authentication: required.
| Query string | Required | Description |
|---|---|---|
userId |
TapFun user ID. If omitted, returns purchases for the whole app | |
key |
Purchase key | |
tran |
Transaction ID | |
limit |
Number of results (1-100, default 10). Out of range becomes 10 | |
nextKey |
Key for fetching the next results (the nextKey of the previous response) |
// Success
{
"nextKey": "Purchase01HE2R3JV6Y2NEGRMS4KZQB858", // null when there are no more results
"result": [
{
"key": "Purchase01HE2R3JV6Y2NEGRMS4KZQB861",
"appId": 1,
"userId": "PLYR01HE2R3JV6Y2NEGRMS4KZQB861DBG",
"tran": "abcdef123456",
"code": "abcdef123456",
"item": "abcdef123456",
"amount": 500,
"name": "300 Gems",
"img": null,
"callbackSuccess": false,
"createdAt": "2024-03-06T06:37:22.000Z"
}
]
}callbackSuccesstells whether the callback succeeded.- When "purchases API compatibility mode" is enabled in the Publisher Console, the suffix of
userIdis a few characters shorter. Normally keep it disabled. - There is no failure response (an empty array when nothing matches).
POST /api/v1/photos
Saves an image to TapFun photo storage. Players can view and download images saved from games on TapFun. Authentication: required.
| Item | Value |
|---|---|
| Content-Type | multipart/form-data |
Query string userId |
TapFun user ID (required) |
POST data file |
PNG / JPEG / WebP image binary (required). The part's Content-Disposition must have a filename (any value), e.g. form-data; name="file"; filename="sample.jpg" |
Limits:
- Max images stored: 1,000. The TapFun list shows up to 1,000 images, newest first. Images beyond 1,000 are deleted over time.
- Retention: kept until the player closes their TapFun account, except images the player deletes on TapFun and images beyond the 1,000 limit.
- Max size: 10 MB per image (no overall limit)
- Max width/height: 12,000 pixels
- Max image size: 100 megapixels (e.g. 10,000 × 10,000)
- No wait between calls and no call limit
curl -F "file=@sample.jpg;type=image/jpeg" \
-H "Authorization: Bearer 1_8an4dAfsIyEEvBbaKxd55P2Wgf" \
"https://<TEST_HOST>/api/v1/photos?userId=PLYR01JY39A09EE40YQZRHWTT9EM1VDBG"// Success
{ "result": "success" }
// Failure (404): user ID not found
{ "result": "failure", "message": "userId is not found" }
// Failure (400): other (file missing, too large, invalid type, etc.)
{ "result": "failure", "message": "other problems." }GET /api/v1/leaderboard/entries
Gets leaderboard entries. Authentication: required.
| Query string | Required | Description |
|---|---|---|
name |
✓ | Leaderboard name |
sort |
asc: ascending / desc: descending (default) |
|
userId |
User ID | |
arround |
Gets entries around the given user (1-100). Works when userId is set |
|
offset |
Start position (0-9999). Out of range becomes 0 | |
limit |
Number of entries (1-1000, default 100). Out of range becomes 100 |
// Success
{
"result": "success",
"entries": [
{
"position": 1,
"userId": "PLYR01HE2R3JV6Y2NEGRMS4KZQB861DBG",
"userName": "Player", // UTF-8, no emoji, 1-12 characters
"score": 12345,
"note": "extra info", // up to 8192 characters
"createdAt": "2025-09-24T00:00:00.000Z",
"updatedAt": "2025-09-24T00:00:00.000Z"
}
]
}
// Failure (404): user ID not found
{ "result": "failure", "message": "userId is not found" }
// Failure (400): other
{ "result": "failure", "message": "other problems." }POST /api/v1/leaderboard/entries
Creates or updates a leaderboard entry. If the score is less than or equal to the existing score, it is not updated. A leaderboard is created automatically for each name. Authentication: required.
| POST data | Required | Description |
|---|---|---|
name |
✓ | Leaderboard name. 1-64 characters of letters, digits, _ and - (/^[0-9a-zA-Z_-]{1,64}$/) |
userId |
✓ | User ID |
score |
✓ | Score (0 to 9,223,372,036,854,775,807) |
note |
Extra info (UTF-8, 0-8192 characters) | |
force |
Pass 1 to save even if the score is lower than the existing one |
// Success
{ "result": "success" }
// Failure (404): user ID not found
{ "result": "failure", "message": "userId is not found" }
// Failure (400): other
{ "result": "failure", "message": "other problems." }POST /api/v1/leaderboard/entries/delete
Deletes a leaderboard entry. Returns success even if there is no entry. Authentication: required.
| POST data | Required | Description |
|---|---|---|
name |
✓ | Leaderboard name (/^[0-9a-zA-Z_-]{1,64}$/) |
userId |
✓ | User ID |
// Success
{ "result": "success" }
// Failure (404): user ID not found
{ "result": "failure", "message": "userId is not found" }
// Failure (400): other
{ "result": "failure", "message": "other problems." }Glossary
TapFun user ID
- A unique ID of up to 64 characters that identifies a user. Issued per app.
- Characters:
0-9,a-z,A-Z. - Format:
PLYR+ ULID + a per-app suffix of 3-7 characters (e.g.DBG,XENO,MOCODVLP).
App ID
An unsigned int ID that identifies an app.
API key
A 26-character string issued per app. Characters: 0-9, A-Z.
Publisher Console
The management console for publishers, used for app settings, the introduction page, sales and more. The test and production environments each have their own, and TapFun registers who can log in.
Introduction page
The game's page on TapFun (https://tapfun.co.jp/p/<app>). The play screen is https://tapfun.co.jp/p/<app>/play. Edit its contents under Details in the Publisher Console.
Guest
A player who is not logged in to TapFun.
TapFun wallet
The balance a player charges on TapFun, used for purchases on TapFun.
TapFun credit
Wallet balance given to test-play accounts in production, usable only in the target app (Test play in production).
Product code / composite product code
- Product code (
code): identifies the kind of product and is used for aggregation on TapFun. While a purchase has an unfinished callback, the player cannot buy another product with the same product code. - Composite product code (
item): an auxiliary code your app can use freely. TapFun does not interpret it and returns it as-is in the Callback API and the purchases API.
Changelog
| Date | Change |
|---|---|
| 2026-11-19 | score in POST /api/v1/leaderboard/entries must now be 0 or greater. A negative value returns 400. |
| 2026-11-19 | When amount in purchaseItem is negative, TapFun no longer opens the confirmation dialog and sends parameterError (reason: invalid param "amount"). |
| 2026-11-11 | Corrected the purchaseItem response notifications to match the actual behavior. The notifications carry from, not req. parameterError is sent only when a required parameter is missing, and does not include code or tran. |
| 2026-11-11 | Introduction pages and play screens in the test environment now use email verification instead of Basic auth. You can add people who test play in "Test players" in the Publisher Console (Who can access the test environment). |
| 2026-11-09 | Added the {lang} (the player's language) and {country} (the country the player connects from) placeholders to the launch URL. getPlayerEnvironment now also returns language and country (How country is determined). |
| 2026-11-04 | Added How isSP is determined, including the values on tablets. |
| 2026-11-02 | Added the image retention period to the Photos API and updated the description of the maximum number of images. |
| 2026-11-02 | Added how maintenance mode works in the Publisher Console. |
| 2026-10-27 | The log shown with ?debugLog=1 ("ログ表示", show log) now shows the TapFun user ID on its second line. |
| 2026-10-21 | Added to the Web API common specification that the User-Agent header is required. |
| 2026-10-14 | Added "Analytics (Google Analytics)" to the Publisher Console. |
| 2026-10-07 | Added "TapFun user IDs for guests and members". Added notes on value length and behavior after login to getOneTimeData. |
| 2026-10-02 | Published this document. |