促销（Toss 积分）

创建促销奖励发放密钥

post

此 API 会发放用于让合作伙伴应用向 Toss 用户发放 Toss 积分的密钥。

业务错误代码

以下错误会以 HTTP 200 和 resultType: FAIL 响应。

errorCode

说明

4095

请求已超出限额。请稍后再试。

请求限额: 每个应用每分钟 3,000 次

授权

mutualTLS

这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考使用服务器 API 文档。

响应

200

促销奖励发放密钥创建成功

application/json

或

400

请求正文不符合格式。请在error.data.errorDetails中查看各字段详情。

application/json

500

未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。

application/json

post/api-partner/v1/apps-in-toss/promotion/execute-promotion/get-key

POST /api-partner/v1/apps-in-toss/promotion/execute-promotion/get-key HTTP/1.1
Host: apps-in-toss-api.toss.im

{
  "resultType": "SUCCESS",
  "success": {
    "key": "AwQqk3XyZpLm9vT2sYbN7cQmR1F5oGxU8dK0hVn6ePs="
  }
}

发放促销奖励

post

此 API 让合作伙伴应用可以向 Toss 用户发放 Toss 积分

业务错误代码

以下错误会以 HTTP 200 和 resultType: FAIL 响应。

errorCode

说明

4000

请求无效。

4100

找不到促销信息

4108

促销未获批准

4109

促销未在执行中

4114

超过促销中设置的单次发放金额，无法发放。

4112

促销资金不足

4105

促销已结束

4113

已是发放/回收记录

4110

无法发放/回收奖励

4034

没有工作区，或者没有访问工作区的权限

4010

找不到认证信息。

4095

请求已超出限额。请稍后再试。

请求限额: 每个应用每分钟 3,000 次，每位用户每分钟 20 次

授权

mutualTLS

这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考使用服务器 API 文档。

头参数

x-toss-user-keystring可选

用于验证用户的密钥。可通过获取用户信息 API 获取

Example: 12345678

x-anon-keystring可选

用于验证用户的密钥。可通过迷你应用 SDK 的 User.getAnonymousKey 函数获取

Example: kQ7pL2mZxN9wRt5vB8yD3jF6cA1

请求体

这是发放促销奖励的请求。

amountinteger · int64必填

这是要发放给 Toss 用户的促销金额

Example: 1000

keystring必填

这是通过“创建促销奖励发放密钥”API 发放的奖励发放密钥

Example: AwQqk3XyZpLm9vT2sYbN7cQmR1F5oGxU8dK0hVn6ePs=

promotionCodestring必填

这是通过控制台创建的促销活动的促销代码

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

响应

200

已成功向 Toss 用户发放 Toss 积分

application/json

或

400

请求正文不符合格式。请在error.data.errorDetails中查看各字段详情。

application/json

500

未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。

application/json

post/api-partner/v1/apps-in-toss/promotion/execute-promotion

POST /api-partner/v1/apps-in-toss/promotion/execute-promotion HTTP/1.1
Host: apps-in-toss-api.toss.im
x-toss-user-key: {userKey}
Content-Type: application/json

{
  "promotionCode": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "key": "AwQqk3XyZpLm9vT2sYbN7cQmR1F5oGxU8dK0hVn6ePs=",
  "amount": 1000
}

{
  "resultType": "SUCCESS",
  "success": {
    "key": "AwQqk3XyZpLm9vT2sYbN7cQmR1F5oGxU8dK0hVn6ePs="
  }
}

查询促销 Toss 积分发放结果

post

此 API 让合作伙伴应用可以查询已向 Toss 用户发放的 Toss 积分

业务错误代码

以下错误会以 HTTP 200 和 resultType: FAIL 响应。

errorCode

说明

4000

请求无效。

4100

找不到促销信息

4111

找不到奖励发放记录

4010

找不到认证信息。

4095

请求已超出限额。请稍后再试。

请求限额: 每个应用每分钟 3,000 次

授权

mutualTLS

这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考使用服务器 API 文档。

头参数

x-toss-user-keystring可选

用于验证用户的密钥。可通过获取用户信息 API 获取

Example: 12345678

x-anon-keystring可选

用于验证用户的密钥。可通过迷你应用 SDK 的 User.getAnonymousKey 函数获取

Example: kQ7pL2mZxN9wRt5vB8yD3jF6cA1

请求体

这是查询促销执行结果的请求。

keystring必填

这是通过“创建促销奖励发放密钥”API 发放的奖励发放密钥

Example: AwQqk3XyZpLm9vT2sYbN7cQmR1F5oGxU8dK0hVn6ePs=

promotionCodestring必填

这是通过控制台创建的促销活动的促销代码

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

响应

200

已成功查询促销发放结果

application/json

或

400

请求正文不符合格式。请在error.data.errorDetails中查看各字段详情。

application/json

500

未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。

application/json

post/api-partner/v1/apps-in-toss/promotion/execution-result

POST /api-partner/v1/apps-in-toss/promotion/execution-result HTTP/1.1
Host: apps-in-toss-api.toss.im
x-toss-user-key: {userKey}
Content-Type: application/json

{
  "promotionCode": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "key": "AwQqk3XyZpLm9vT2sYbN7cQmR1F5oGxU8dK0hVn6ePs="
}

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

上一页推送、通知

这有帮助吗？