使用服务器 API

介绍使用 Apps in Toss API 前所需的服务器通信设置。

获取服务器 mTLS 证书

要使用 Apps in Toss API，必须先 mTLS(mutable Transport Layer Security，双向传输层安全) 设置证书。

mTLS 是客户端和服务器相互验证身份的一种方式。普通 HTTPS 只验证服务器，但 mTLS 会 合作方服务器和 Apps in Toss 服务器相互认证。

设置此证书后才能保障以下内容。

• 通信链路加密
• 仅允许的服务器可调用 API
• 防止篡改

请按如下方式管理已签发的证书。

• 请安全保管证书和密钥文件，避免泄露。
• 请在证书到期前重新签发。
• 如果需要无停机切换，可以先注册两个以上的证书。

如果你还没有准备证书，请先查看《获取服务器 mTLS 证书》文档中的 mTLS 证书签发方法。

检查通信防火墙

如果服务器上管理着 Inbound、Outbound 防火墙，请务必允许以下 IP 和端口。若不允许，API 调用可能失败或收不到回调。

商户需要允许的 Inbound IP

Apps in Toss → 商户

IP	Port
117.52.3.11	443
211.115.96.11	443
106.249.5.11	443
117.52.3.80~87	443
211.115.96.80~87	443
106.249.5.80~87	443

这是 Apps in Toss 向商户服务器发送请求时使用的 IP。例如，当通过控制台注册的回调 URL 接收订阅状态变更回调或数据提供同意撤回回调时，需要使用它。

商户需要允许的 Outbound IP

商户 → Apps in Toss

功能	域名	IP	Port
简便登录、消息发送、Toss 积分发放	apps-in-toss-api.toss.im	117.52.3.192, 211.115.96.192, 106.249.5.192	443
快捷支付	pay-apps-in-toss-api.toss.im	117.52.3.195, 211.115.96.195, 106.249.5.195	443

这是商户服务器调用 Apps in Toss API 时所需的设置。需要开放 HTTPS 443 端口，才能正常通信。

允许 CORS

要在 Mini App 中与服务器通信，需要在服务器的 CORS 允许 Origin 中添加 Mini App Origin。 需要允许的 Origin 会因 SDK 版本和适用日期而异。

SDK 3.x

SDK 3.x Origin 变更说明

从 2026 年 8 月 25 日（周二）之后上传的 SDK 3.x bundle 起，将使用 SDK 2.x 中使用的 Origin 提供服务。 如果与外部服务器通信，请将以下 Origin 添加到服务器的 CORS 允许 Origin 中。

• https://<appName>.apps.tossmini.com ：正式服务环境
• https://<appName>.private-apps.tossmini.com ：控制台 QR 测试环境

• https://<appName>.web.tossmini.com ：正式服务环境
• https://<appName>.private-web.tossmini.com ：控制台 QR 测试环境

SDK 1.x ~ 2.x

• https://<appName>.apps.tossmini.com ：正式服务环境
• https://<appName>.private-apps.tossmini.com ：控制台 QR 测试环境

API 通用规范

域名信息

• https://apps-in-toss-api.toss.im
• https://pay-apps-in-toss-api.toss.im

API 通用响应格式

所有 API 都使用统一的响应结构。 resultType 请先通过该值确认是否成功。

成功响应

{
  "resultType": "SUCCESS",
  "success": {
    "sample": "data"
  }
}

• resultType如果是 "SUCCESS"则表示请求已正常处理。
• 实际响应数据 success 在对象中。
• 每个 API 的 success 内部结构不同。

失败响应

{
  "resultType": "FAIL",
  "error": {
    "errorCode": "INVALID_PARAMETER",
    "reason": "请求失败。"
  }
}

• resultType如果是 "FAIL"则表示请求处理失败。
• errorCode是表示错误类型的代码。
• reason包含可供人类阅读的错误说明。
• 如果发送了错误的参数 INVALID_PARAMETER等代码来触发错误。

处理响应时，务必先 resultType检查 resultType，再分别实现成功和失败逻辑。

请求限制政策

Apps in Toss API 为了稳定运营服务，会限制请求数量。

默认限制

• 每分钟 3,000 QPM
• QPM 是 Queries Per Minute 的缩写，表示 1 分钟内可调用的 API 请求数量。
• 以 Mini App 为准，每分钟最多可请求 3,000 次。

超过该限额后，可能会在一段时间内阻止额外请求。

需要提高 QPM 时

如需超过默认 3,000 QPM 的请求量 Channel Talk申请上调。

申请时请一并提供以下信息。

• 使用目的
• 预估流量规模
• 峰值时段请求量

会在审核业务目的和流量规模后调整限额。如果预计会有大流量，建议在服务上线前提前协商。