客户端 API

本页所有接口都使用 X-Kasskeep-Key: pk_...。app_user_id 长度为 1 到 200 个字符。

POST /v1/receipts

提交一笔商店交易。返回 {"customer": ...}。

字段	类型	说明
app_user_id	string	必填
platform	ios, android, test	必填。决定使用哪个渠道
ios.signed_transaction	string	StoreKit 2 的 Transaction.jwsRepresentation
android.product_id	string	Play 商品 id 或订阅 id
android.purchase_token	string	Purchase.purchaseToken
android.type	inapp, subs	提示先查询哪个 Play API
test.purchase_id	string	重新提交一笔测试商店购买

{ "app_user_id": "6f1c2a3b-4d5e-4f60-8a71-92b3c4d5e6f7", "platform": "ios", "ios": { "signed_transaction": "eyJhbGciOiJFUzI1NiIs..." } }

{ "app_user_id": "6f1c2a3b-4d5e-4f60-8a71-92b3c4d5e6f7", "platform": "android", "android": { "product_id": "coins_100", "purchase_token": "...", "type": "inapp" } }

状态码	错误码	含义
400	invalid_signed_transaction	签名或证书链有误、bundle id 或环境不对（详见 message）
400	environment_not_allowed	该 App 不接受这个环境
400	invalid_purchase_token	Google 不认识这个 token
403	app_account_token_mismatch	交易绑定的是另一个用户 id
403	transaction_belongs_to_another_user	已记录在另一个用户名下
422	android_not_configured	该 App 没有配置包名或服务账号
502	verification_unavailable	Apple 证书吊销检查或 Google API 暂时失败；请重试

Android 的待处理购买在完成之前不会被记录。

GET /v1/customers/:app_user_id

用户的订阅和购买。可选 ?environment=production|sandbox|test。

{
  "customer": {
    "app_user_id": "6f1c...",
    "subscriptions": [
      { "product_id": "pro_monthly", "platform": "ios", "environment": "production", "original_transaction_id": "2000000123", "status": "active", "will_renew": true, "current_period_start": "2026-10-01T12:00:00.000Z", "current_period_end": "2026-11-01T12:00:00.000Z", "ownership": "purchased" }
    ],
    "purchases": [
      { "product_id": "coins_100", "platform": "ios", "environment": "production", "transaction_id": "2000000456", "purchased_at": "2026-10-02T08:00:00.000Z", "quantity": 1, "status": "owned" }
    ]
  }
}

订阅 status 的取值见数据模型。使用私钥时响应会更详细，见服务端 API。

POST /v1/customers/:app_user_id/restore

提交商店里该用户当前拥有的全部购买。返回 {"customer": ...}。

字段	类型	说明
platform	ios, android, test	必填
ios.signed_transactions	string[]	最多 500 项
android.purchases	{product_id, purchase_token, type}[]	最多 500 项
test.purchase_ids	string[]	可选；不传则重新同步所有测试购买

属于其他用户的交易，或 Google 不认识的交易，会被跳过，不报错。配置了 App Store API 密钥时，Kasskeep 还会从 Apple 补全历史记录。

POST /v1/checkout

为网页支付渠道创建托管结账页。见 Stripe。

字段	类型	说明
app_user_id	string	必填
channel	string	stripe
product_id	string	必须已在该渠道映射
success_url, cancel_url	string	checkout_return_hosts 中某个域名下的 https 地址
quantity	integer	1 到 100，默认 1

响应：{"url": "...", "session_id": "cs_..."}。

状态码	错误码
400	unknown_channel、checkout_not_supported、return_url_not_allowed、product_not_configured
422	return_hosts_not_configured、stripe_not_configured
502	stripe_unavailable、stripe_auth_failed、stripe_rejected

POST /v1/test-store/purchases

在测试商店购买。需要已开启测试商店。

字段	类型	说明
app_user_id	string	必填
product_id	string	必填
type	inapp, subs	必填
quantity	integer	1 到 100；订阅只能是 1
outcome	success, cancelled, pending, failed	默认 success
price_micros, currency	integer, [A-Z]{3}	可选，覆盖价格

响应：{outcome, purchase, customer}。

GET /v1/test-store/products

?ids=a,b&type=inapp|subs。为允许的 id（最多 200 个）返回 {products: [{product_id, type, title, description, price_micros, currency, environment}], subscription_period_seconds}。

GET /v1/customers/:app_user_id/ad-rewards

最近的奖励，最新的在前。?limit=1..200（默认 50），?environment=production|test。返回 {app_user_id, ad_rewards: [...]}。仅供展示和客服使用；请根据回调发放奖励。

POST /v1/ads/test/rewards

一次测试奖励。见测试模式。

字段	类型	说明
app_user_id	string	必填
ad_unit	string	你的统一广告位名
reward_type	string	可选
reward_amount	number	可选，0 到 1e9
custom_data	string	可选，最多 8192 个字符
outcome	completed, skipped, failed	默认 completed
network	test, admob, applovin, levelplay	默认 test

响应：{status, reward_event_id, ad_reward}。