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

#Environments

#Hostnames

The test environment hostname and its Basic auth user name and password 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).

#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

#Details (introduction page)

The "詳細情報" (details) tab edits what is shown on the game's introduction page on TapFun.

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

#Other tabs

#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}) are replaced with values at launch.
• 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

1. Send the value passed in {token} from the browser to your game server.
2. Your game server calls POST /api/v1/create_session, which returns the TapFun user ID.
3. {token} is valid for 24 hours in the test environment and 180 seconds in production. 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.

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

#Transport

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.

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&note&ret

• tapfunUserId is 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 req (purchaseItem), code (the requested code) and tran (the requested tran).

• If the tran matches 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 same tran is detected after the purchase button is pressed.
• To reproduce the duplicate tran error, open TapFun's game page with ?purchasableCheck=0 added to the URL and call purchaseItem from the game with the same tran. 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.

Response:

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

Response:

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.

Response:

#openAccount

Opens the account page. For a guest, shows the sign-up / login modal.

Response: none

#reboot

Restarts the game, the same as when the player taps the restart icon in the TapFun UI.

Response: none

#consoleLog

Adds a log line to TapFun's log area. It is also written to the browser's developer tools console.

Response: none

#Callback API (item purchase notification)

When a purchaseItem payment succeeds, the TapFun server notifies your game server of the purchase.

#Specification

Request headers:

// 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 10 minutes
  • Up to 24 hours: every hour
  • Up to 14 days: every day
  • 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

{
  "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 tran again, return the result of the existing purchase (idempotency). For example, if the existing purchase with that tran succeeded, return success.

#Web API

HTTP APIs called from your servers. Keep the Bearer token on the server and never send it to the browser.

#Common specification

#Authentication

Authenticate with the HTTP header Authorization: Bearer <AppID>_<APIKey> (the Bearer token in the Publisher Console).

Authorization: Bearer 123_NWU0MjlkY2ViYTVkOTdiYjIwNThmZTkxMDMzYWM4Y2JmNGUyMTQ0Ng

On authentication failure the API returns HTTP 403 with:

{"error":"no authorization"}

#POST /api/v1/create_session

Gets the TapFun user ID from the launch URL's {token} (User authentication). Authentication: required.

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

// 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"
    }
  ]
}

• callbackSuccess tells whether the callback succeeded.
• When "purchases API compatibility mode" is enabled in the Publisher Console, the suffix of userId is 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.

Limits:

• Max images stored: 1,000 (the oldest are deleted automatically beyond that)
• 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.

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

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

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

↑ Back to top