推广

服务介绍和控制台设置方法是 促销介绍文档请参考。

在开始开发促销前请务必确认

为了避免用户误解，不能使用与 Toss 中已在使用的名称相同的名称，或用作其他含义。

[示例]

• 积分

  • 如果在迷你应用内通用的自有奖励 “积分” 这个名称就不能使用。

    • 可能会被误认为已发放“Toss 积分”。
  • 请使用能与“Toss 积分”明确区分的术语。
• 提款、提现等 — 不能使用会被误认为是变现的术语。

  • 如果在迷你应用内虚拟资产转换为“Toss 积分”， “Toss 积分发放” 来标示。

调用限制

按 userKey 每分钟最多可调用 10 次。超出时会返回错误。

---

游戏迷你应用

即使没有单独的服务器联动 也可以在游戏迷你应用内向用户发放 Toss 积分并展示在福利标签页中。

SDK 函数： grantPromotionRewardForGame

这个函数只能在游戏分类的迷你应用中调用。在非游戏分类中执行会发生错误。

请注意

• Toss App 5.232.0 版本及以上支持。 undefined 值会在低于该版本时返回，此时进入迷你应用时会显示引导更新的页面。
• 为了稳定获取所有用户的标识符， 将 Toss App 最低支持版本上调至 5.232.0。
• 游戏用户标识符是 游戏公司内部识别用的密钥仅用于此目的，不能用这个密钥直接向 Toss 服务器发起请求。
• 如果重复调用函数，同一用户可能会被重复发放奖励， 请务必应用防护逻辑。
• 在正式开始促销前，需要至少使用测试用促销代码调用 1 次以上。（通过测试调用，促销会正常注册并转换为已批准状态。）

签名

function grantPromotionRewardForGame({
  params,
}: {
  params: {
    promotionCode: string;
    amount: number;
  };
}): Promise<GrantPromotionRewardForGameResult>;

参数

• params · 必填 · { params: { promotionCode: string; amount: number } }

  这是发放积分所需的信息。

  • params.promotionCode · 必填 · string

    促销代码。
  • params.amount · 必填 · number

    要发放的积分金额。

返回值

• Promise<{ key: string } | { errorCode: string; message: string } | 'ERROR' | undefined>

返回积分发放结果。

• { key: string }: 发放积分成功。key 表示奖励密钥。
• { errorCode: string, message: string }: 发放积分失败。请确认错误代码。

错误代码

这是在使用促销函数时可能发生的错误代码列表。请参考响应代码或消息， 应用适当的异常处理逻辑。

4109 如果发生错误？

• 促销预算的 80% 消耗时会通过邮件通知。
• 如果要继续进行促销， 请在控制台中增加预算。
• 如果预算不足， 可在 Biz Wallet 中充值金额以增加预算。
• 当预算全部消耗完时，促销会 自动结束， 4109 并发生错误。
• 如果因预算不足导致积分发放失败， 可能会引发用户 CS 问题，请注意。

代码	消息	发生原因 / 应对方法
40000		在非游戏迷你应用中调用时
4100	找不到促销信息	使用未在控制台注册的促销密钥调用时
4109	促销未在执行中	未在控制台启动促销，或因预算全部耗尽而自动结束时
4110	无法发放/回收奖励	这是内部系统发生错误的情况， 重新发放逻辑。
4111	找不到奖励发放记录	查询了不存在的发放记录时
4112	促销资金不足	由于预算不足导致发放失败时，需要在控制台增加预算或为 Biz Wallet 充值
4114	超过单次发放金额
4116	最大发放金额超过了预算
ERROR	发生了未知错误。
undefined	应用版本低于最低支持版本。

示例

js

import { grantPromotionRewardForGame } from '@apps-in-toss/web-framework';

async function handleGrantPromotionRewardForGame() {
  const result = await grantPromotionRewardForGame({
    params: {
      promotionCode: 'GAME_EVENT_2024',
      amount: 1000,
    },
  });

  if (!result) {
    console.warn('不支持的应用版本。');
  } else if (result === 'ERROR') {
    console.error('发放积分时发生未知错误。');
  } else if ('key' in result) {
    console.log('发放积分成功！', result.key);
  } else if ('errorCode' in result) {
    console.error('发放积分失败：', result.errorCode, result.message);
  }
}

React

import { grantPromotionRewardForGame } from '@apps-in-toss/web-framework';

function GrantRewardButton() {
  async function handleClick() {
    const result = await grantPromotionRewardForGame({
      params: {
        promotionCode: 'GAME_EVENT_2024',
        amount: 1000,
      },
    });

    if (!result) {
      console.warn('不支持的应用版本。');
      return;
    }

    if (result === 'ERROR') {
      console.error('发放积分时发生未知错误。');
      return;
    }

    if ('key' in result) {
      console.log('发放积分成功！', result.key);
    } else if ('errorCode' in result) {
      console.error('发放积分失败：', result.errorCode, result.message);
    }
  }

  return <button onClick={handleClick}>发放积分</button>;
}

React Native

import { Button } from 'react-native';
import { grantPromotionRewardForGame } from '@apps-in-toss/framework';

function GrantRewardButton() {
  async function handlePress() {
    const result = await grantPromotionRewardForGame({
      params: {
        promotionCode: 'GAME_EVENT_2024',
        amount: 1000,
      },
    });

    if (!result) {
      console.warn('不支持的应用版本。');
      return;
    }

    if (result === 'ERROR') {
      console.error('发放积分时发生未知错误。');
      return;
    }

    if ('key' in result) {
      console.log('发放积分成功！', result.key);
    } else if ('errorCode' in result) {
      console.error('发放积分失败：', result.errorCode, result.message);
    }
  }

  return <Button onPress={handlePress} title="发放积分" />;
}

---

非游戏迷你应用

在非游戏分类的迷你应用中，通过促销向用户发放 Toss 积分的方法有两种。

• 无需服务器发放: 无需单独的服务器联动，仅通过调用 SDK 函数即可发放积分。
• 通过服务器发放: 在合作方服务器上直接调用 API 发放积分。适用于需要防止请求篡改等完整性很重要的情况。

无需服务器发放促销积分

SDK 函数： grantPromotionReward

即使没有单独的服务器联动 在非游戏迷你应用内向用户发放 Toss 积分并展示在福利标签页中。

请注意

• Toss App 5.232.0 版本及以上支持。低于该版本时， undefined会返回，并在进入迷你应用时显示更新提示页面。
• 如果重复调用函数，同一用户可能会被重复发放奖励， 请务必应用防护逻辑。
• 在正式开始促销前，需要至少使用测试用促销代码调用 1 次以上需要这样做。测试促销代码应在非沙盒应用中 Toss App（QR 码测试） 中调用。

签名

function grantPromotionReward({
  params,
}: {
  params: {
    promotionCode: string;
    amount: number;
  };
}): Promise<GrantPromotionRewardResult>;

参数

• params · 必填 · { params: { promotionCode: string; amount: number } }

  这是发放积分所需的信息。

  • params.promotionCode · 必填 · string

    促销代码。
  • params.amount · 必填 · number

    要发放的积分金额。

返回值

• Promise<{ key: string } | { errorCode: string; message: string } | 'ERROR' | undefined>

返回积分发放结果。

• { key: string }: 发放积分成功。key 表示奖励密钥。
• { errorCode: string, message: string }: 发放积分失败。请确认错误代码。

错误代码

这是在使用促销函数时可能发生的错误代码列表。请参考响应代码或消息， 应用适当的异常处理逻辑。

4109 如果发生错误？

• 促销预算的 80% 消耗时会通过邮件通知。
• 如果要继续进行促销， 请在控制台中增加预算。
• 如果预算不足， 可在 Biz Wallet 中充值金额以增加预算。
• 当预算全部消耗完时，促销会 自动结束， 4109 并发生错误。
• 如果因预算不足导致积分发放失败， 可能会引发用户 CS 问题，请注意。

代码	消息	发生原因 / 应对方法
4100	找不到促销信息	使用未在控制台注册的促销密钥调用时
4109	促销未在执行中	未在控制台启动促销，或因预算全部耗尽而自动结束时
4110	无法发放/回收奖励	这是内部系统发生错误的情况， 重新发放逻辑。
4111	找不到奖励发放记录	查询了不存在的发放记录时
4112	促销资金不足	由于预算不足导致发放失败时，需要在控制台增加预算或为 Biz Wallet 充值
4114	超过单次发放金额
4116	最大发放金额超过了预算
ERROR	发生了未知错误。
undefined	应用版本低于最低支持版本。

示例

js

import { grantPromotionReward } from '@apps-in-toss/web-framework';

async function handleGrantPromotionReward() {
  const result = await grantPromotionReward({
    params: {
      promotionCode: 'EVENT_2024',
      amount: 1000,
    },
  });

  if (!result) {
    console.warn('不支持的应用版本。');
  } else if (result === 'ERROR') {
    console.error('发放积分时发生未知错误。');
  } else if ('key' in result) {
    console.log('发放积分成功！', result.key);
  } else if ('errorCode' in result) {
    console.error('发放积分失败：', result.errorCode, result.message);
  }
}

React

import { grantPromotionReward } from '@apps-in-toss/web-framework';

function GrantRewardButton() {
  async function handleClick() {
    const result = await grantPromotionReward({
      params: {
        promotionCode: 'EVENT_2024',
        amount: 1000,
      },
    });

    if (!result) {
      console.warn('不支持的应用版本。');
      return;
    }

    if (result === 'ERROR') {
      console.error('发放积分时发生未知错误。');
      return;
    }

    if ('key' in result) {
      console.log('发放积分成功！', result.key);
    } else if ('errorCode' in result) {
      console.error('发放积分失败：', result.errorCode, result.message);
    }
  }

  return <button onClick={handleClick}>发放积分</button>;
}

React Native

import { Button } from 'react-native';
import { grantPromotionReward } from '@apps-in-toss/framework';

function GrantRewardButton() {
  async function handlePress() {
    const result = await grantPromotionReward({
      params: {
        promotionCode: 'EVENT_2024',
        amount: 1000,
      },
    });

    if (!result) {
      console.warn('不支持的应用版本。');
      return;
    }

    if (result === 'ERROR') {
      console.error('发放积分时发生未知错误。');
      return;
    }

    if ('key' in result) {
      console.log('发放积分成功！', result.key);
    } else if ('errorCode' in result) {
      console.error('发放积分失败：', result.errorCode, result.message);
    }
  }

  return <Button onPress={handlePress} title="发放积分" />;
}

---

通过服务器发放促销积分

这是在合作方服务器上直接调用 API，向用户发放 Toss 积分的方式。

识别促销目标用户

促销 API 会通过下列 2 种方法之一识别促销对象。请不要同时传递两个值，只选择一个。

区分	发放方式
x-toss-user-key	Toss 登录获得的 userKey 值。
x-anon-key	用户识别密钥发放获得的 hash 值。

请根据用途选择。

• 如果已经接入 Toss 登录，或者想与姓名、邮箱等会员信息绑定进行统一管理，就使用 Toss 登录。
• 如果不接入登录，想轻量识别用户，就使用用户识别密钥发放功能。

x-anon-key如果想提前确认 (hash) 是否是有效值， 请使用识别密钥验证 API。

---

基本信息

项目	值
Base URL	https://apps-in-toss-api.toss.im
服务器认证	mTLS（客户端证书）
Content-Type	application/json

服务器间通信需要 mTLS 证书

促销 API 是从合作方服务器调用 Apps in Toss 服务器的服务器间通信。为保证安全，请先在服务器上配置 mTLS 证书后再调用。证书发放方法请参考 mTLS 证书发放方法。

① 创建促销奖励发放 Key

发放用于促销的 Key。使用这个 Key 可以向用户发放奖励。

请注意

• 向用户发放奖励的主体是合作方。使用已获得的 Key 向用户发放奖励时， 在促销预算限额内 会持续发放。
• 仅允许单次发放则需要由合作方自行控制。
• 如果尝试使用已使用过的发放 Key 再次发放， 4113 会发生错误。若需要追加发放， 请发放新的 Key。
• 已发放的 Key 有效期为 1 小时。

• Content-type: application/json
• Method: POST
• Endpoint: /api-partner/v1/apps-in-toss/promotion/execute-promotion/get-key

请求头

识别促销对象的请求头使用以下 2 个中的一个。请不要同时传递两个请求头。

名称	类型	必填	说明
x-toss-user-key	string	二选一	Toss 登录获得的 userKey。 获取用户信息即可获得。
x-anon-key	string	二选一	用户识别密钥发放获得的 hash 值。

响应参数

名称	类型	说明
key	String	用于促销发放的 key 值（base64 编码后的值）

{
  "resultType": "SUCCESS",
  "success": {
    "key": "3oBpxjUgl5r66edcVi7ynHGIjhzr9KOka6FfEKikev0="
  }
}

② 发放促销奖励

使用已发放的 key 执行促销奖励发放。发放时会从促销预算中扣除，实际发放可能会有些许延迟。

• Content-type: application/json
• Method: POST
• Endpoint: /api-partner/v1/apps-in-toss/promotion/execute-promotion

请求头

识别促销对象的请求头使用以下 2 个中的一个。请不要同时传递两个请求头。

名称	类型	必填	说明
x-toss-user-key	string	二选一	Toss 登录获得的 userKey。 获取用户信息即可获得。
x-anon-key	string	二选一	用户识别密钥发放获得的 hash 值。

请求参数

名称	类型	必填	说明
promotionCode	String	Y	在控制台中创建的促销代码 ID
key	String	Y	为促销发放而获得的 KEY
amount	Integer	Y	促销发放金额

{
  "promotionCode": "01JPPJ6SB66BQXXDAKRQZ6SZD7",
  "key": "3oBpxjUgl5r66edcVi7ynHGIjhzr9KOka6FfEKikev0=",
  "amount": 10
}

响应参数

名称	类型	说明
key	String	为促销发放而获得的 KEY

{
  "resultType": "SUCCESS",
  "success": {
    "key": "3oBpxjUgl5r66edcVi7ynHGIjhzr9KOka6FfEKikev0="
  }
}

③ 查询促销发放结果

发放请求之后的 查询促销发放状态。

• Content-type: application/json
• Method: POST
• Endpoint: /api-partner/v1/apps-in-toss/promotion/execution-result

请求头

识别促销对象的请求头使用以下 2 个中的一个。请不要同时传递两个请求头。

名称	类型	必填	说明
x-toss-user-key	string	二选一	Toss 登录获得的 userKey。 获取用户信息即可获得。
x-anon-key	string	二选一	用户识别密钥发放获得的 hash 值。

请求参数

名称	类型	必填	说明
promotionCode	String	Y	在控制台中创建的促销代码 ID
key	String	Y	为促销发放而获得的 KEY

{
  "promotionCode": "01JPPJ6SB66BQXXDAKRQZ6SZD7",
  "key": "3oBpxjUgl5r66edcVi7ynHGIjhzr9KOka6FfEKikev0="
}

响应参数

名称	类型	说明
success	String	促销发放结果（SUCCESS / PENDING / FAILED)

{
  "resultType": "SUCCESS",
  "success": "PENDING"
}

错误代码

这是在使用促销 API 时可能发生的错误代码列表。请参考响应代码或消息， 应用适当的异常处理逻辑。

4109 如果发生错误？

• 促销预算的 80% 消耗时会通过邮件通知。
• 如果要继续进行促销， 请在控制台中增加预算。
• 如果预算不足， 可在 Biz Wallet 中充值金额以增加预算。
• 当预算全部消耗完时，促销会 自动结束， 4109 并发生错误。
• 如果因预算不足导致积分发放失败， 可能会引发用户 CS 问题，请注意。

代码	消息	发生原因 / 应对方法
4100	找不到促销信息	使用未在控制台注册的促销密钥调用时
4109	促销未在执行中	未在控制台启动促销，或因预算全部耗尽而自动结束时
4110	无法发放/回收奖励	这是内部系统发生错误的情况， 重新发放逻辑。
4111	找不到奖励发放记录	查询了不存在的发放记录时
4112	促销资金不足	由于预算不足导致发放失败时，需要在控制台增加预算或为 Biz Wallet 充值
4113	已发放/已回收的记录	在使用同一个 Key 重复发放时，请重新发放新的 Key 后重试。
4114	超过单次发放金额
4116	最大发放金额超过了预算