TOSS小程序SDK服务端API
由于TOSS原文档一直在改版调整中，目前已无法获取原md文档，目前先将当时（2025年11月）的翻译内容贴在此处，后续再调整翻译文档的格式 且由于时间紧张，运营并没有翻译代码相关的部分，请使用贴出的原文档链接在原文档查看request body和response示例以及其sample 然后由于其一直在增加新的sdk方法和api，请注意查看原文链接中有没有新增相关页面，并咨询我方运营获取翻译
1. 快捷登录（Toss 登录）
AccessToken 重新获取
这是使用 Refresh Token 重新获取 Access Token 的 API。 /api-partner/v1/apps-in-toss/user/oauth2/refresh-token
Request Body object 使用已颁发的 Refresh Token 来刷新 Access Token 的请求。 refreshToken string Required 已颁发的 Refresh Token。通过该 Token 可以请求新的 Access Token。 JSON {"refreshToken": "1//0gdfg23rF9sds..."} Samples
Responses
200 请求成功时，会返回重新颁发的 Access Token 相关信息。 400 Refresh Token 无效或已过期。
获取AccessToken
这是通过 Authorization Code 颁发 Access Token 和 Refresh Token 的 API。 Request Body
Schema 用于 OAuth2 令牌颁发的请求正文. authorizationCode string 通过 OAuth2 认证流程获取的 Authorization Code。 在用户完成认证后，该 Code 会作为查询参数附加在重定向 URL 中传递。
Referrer string 这是用户进入应用的导流来源。例如，深度链接、推送通知、应用内横幅等路径，表示用户是通过什么方式使用该功能的。 Samples
Responses 200 请求成功后会返回已签发的令牌信息。 400 缺少 Authorization Code 或 Authorization Code 无效。
OAuth2 令牌颁发请求的响应信息
accessToken string 当 API 调用成功时颁发的访问令牌。在需要用户认证的 API 请求中，可放在 Authorization 头中使用。 refreshToken string 用于在访问令牌过期后重新获取新访问令牌的 Refresh Token。可使用该 Token 请求新的 Access Token。 expiresIn integer 访问令牌的有效时间（秒）。过期后，需要使用 Refresh Token 获取新的令牌。 tokenType string 表示令牌类型，通常固定为 'Bearer'。 Scope string 表示令牌可执行的操作范围。例如，可以包含访问用户资料或发送消息的权限。
通过userKey解除登录链接
这是使用 Access Token 解除连接的用户的响应。响应中仅包含已解除连接用户的 userKey /api-partner/v1/apps-in-toss/user/oauth2/access/remove-by-user-key
Request Body
Schema userKey integer 这是要解除连接的用户的唯一标识符，用于在内部系统中识别该用户。 JSON {"userKey": 123456789}
Samples
Responses 200 请求成功后，会返回基于 userKey 已解除连接的用户的 userKey。 400 缺少UserKey或 UserKey 无效
使用AccessToken解除登录链接
这是通过 Authorization 头中的 Access Token 来解除该用户连接的 API。/api-partner/v1/apps-in-toss/user/oauth2/access/remove-by-access-token
Parameters Header Parameters Authorization* 这是包含用户 Access Token 的 Authorization 头的值。 Type string Required Example Bearer ya29.A0ARrdaM9bZxZJ...
Samples
Responses 200 请求成功后，会成功解除与该 Access Token 对应用户的连接。 401 缺少 Access Token 或 Access Token 无效。
获取用户信息
这是使用 Access Token 查询已登录用户信息的 API。 /api-partner/v1/apps-in-toss/user/oauth2/login-me
Parameters Header Parameters Authorization* 这是包含 Bearer 格式 Access Token 的 Authorization 头的值。 Type string Required Example Bearer ya29.A0ARrdaM9bZxZJ...
Samples
Responses 200 请求成功后，会返回查询到的用户个人资料信息。部分字段可能根据用户是否同意而为 null。401 缺少Access Token或Access Token无效
2. 消息发送
发送消息
该 API 允许合作伙伴应用向 Toss 用户发送通知或消息。需要用户认证令牌，并且包含可向用户发送消息的 scope 权限. /api-partner/v1/apps-in-toss/messenger/send-message
Parameters Header Parameters x-toss-user-key * 这是用于认证用户的键。 Type string Required Example toss-user-key-abc123
Samples
Request Body object 定义要发送给用户的消息，包括使用的消息模板以及模板中所需的数据
templateSetCode string 要使用的消息模板代码。填写事先注册好的模板代码之一。
Context object 模板中使用的变量值。例如，可以包含用户姓名或验证码等。
JSON {"templateSetCode": "ALERT_OTP_TEMPLATE","context": {"additionalProperties": {}}}
Responses 200 消息发送成功 400 请求错误或缺少必要信息 401 用户未认证 403 无权限发送消息
包含按渠道发送的消息数量，以及成功/失败消息的详细信息。
msgCount integer 总发送的消息数量。.
sentPushCount integer 通过 Push 发送的消息数量。 sentInboxCount integer 通过 Inbox 发送的消息数量。 sentSmsCount integer 通过 SMS 发送的消息数量。
sentAlimtalkCount integer 通过 Alimtalk(通知消息) 发送的消息数量。.
sentFriendtalkCount integer 通过 Friendtalk(好友消息) 发送的消息数量
Detail object 这是按各渠道发送的消息详细列表，可以查看每条消息在各渠道的发送是否成功或失败。 Fail object 按渠道列出的消息详细列表，可查看每条消息在各渠道的发送状态（成功或失败）。
sentPush object[] Push(推送消息） 渠道发送的消息列表. contentId string 已发送消息的唯一 ID reachedFailReason string 如果消息发送失败，则包含失败原因。 sentInbox object[] Inbox 渠道发送的消息列表。 contentId string 已发送消息的唯一 ID。 reachedFailReason string 如果消息发送失败，则包含失败原因。 sentSms object[] SMS 渠道发送的消息列表。 contentId string reachedFailReason string 如果消息发送失败，则包含失败原因。 sentAlimtalk object[] Alimtalk(通知消息) 渠道发送的消息列表。 contentId string 已发送消息的唯一 ID。 reachedFailReason string 如果消息发送失败，则包含失败原因。 sentFriendtalk object[] Friendtalk(好友消息) 渠道发送的消息列表。contentId string 已发送消息的唯一 ID。 reachedFailReason string 如果消息发送失败，则包含失败原因。.
3. 简易支付（Toss Pay）
退款
可以对已支付的订单发起退款请求。请事先确认是否可退款以及余额等条件。 /api-partner/v1/apps-in-toss/pay/refund-payment
Parameters Header Parameters
x-toss-user-key* 用于认证用户的 Key。 Type string Required Example toss-user-key-abc123
Samples
Request Body Schema object 这是用于 Toss Pay 退款的请求正文。 payToken string Toss Pay 令牌（要退款的支付订单的令牌值）
Max Length 30 Reason string 退款原因 Max Length 55 isTestPayment boolean Sandbox环境为 false，实际应用为 true（true 表示真实支付） JSON {"payToken": "string","reason": "string","isTestPayment": true}
Responses 200 退款请求已成功处理。
Schema refundNo string 退款编号 approvalTime string 支付订单的退款处理时间 (yyyy-MM-dd HH:mm:ss)
cashReceiptMgtKey string 现金订单（单子）收据管理编号 Max Length 36
refundableAmount integer 可退款金额 Format int32 Max Length 7
discountedAmount integer 折扣金额 Format int 32 Max Length 7
paidAmount integer 支付方式批准金额 Formatint 32 Max Length 7
refundedAmount integer 退款请求金额 Formatint 32 Max Length 7
refundedDiscountAmount integer 退款请求金额中实际扣除的折扣金额 Formatint 32 Max Length 7
refundedPaidAmount integer 退款请求金额中实际扣除的支付方式金额 Formatint 32 Max Length 7
payToken string 已退款的支付令牌 Max Length 30
transactionId string 交易事务 ID Max Length 36 cardMethodType string 卡类型（CREDIT：信用卡 / CHECK：借记卡 / PREPAYMENT：预付卡） Max Length 10
cardNumber string 掩码处理后的卡号 Max Length 20
cardUserType string 卡用户类别（区分） PERSONAL(个人卡) PERSONAL_FAMILY(家庭卡) CORP_PERSONAL（公司指定支付账户员工) CORP_PRIVATE(公司共有卡) CORP_COMPANY公司指定支付账户公司（仅 Hana Card） Max Length 20
cardBinNumber string 卡 BIN 号（由发卡银行提供的卡 BIN 号码，可能已掩码） Max Length 8
cardNum4Print string 用户选择的卡号尾号 4 位 Max Length 4
accountBankCode string 银行代码 Max Length 3
accountBankName string 银行名称 Max Length 20
accountNumber string 银行账户号码（包含部分掩码） Max Length 30
JSON {"resultType": "string","error": {"errorType": 0,"errorCode": "string","reason": "string","data": {"additionalProperties": {}},"title": "string"},"success": {"refundNo": "string","approvalTime": "string","cashReceiptMgtKey": "string","refundableAmount": 0,"discountedAmount": 0,"paidAmount": 0,"refundedAmount": 0,"refundedDiscountAmount": 0,"refundedPaidAmount": 0,"payToken": "string","transactionId": "string","cardMethodType": "string","cardNumber": "string","cardUserType": "string","cardBinNumber": "string","cardNum4Print": "string","accountBankCode": "string","accountBankName": "string","accountNumber": "string"}}
创建支付
用于创建支付订单。 /api-partner/v1/apps-in-toss/pay/make-payment
Parameters Header Parameters x-toss-user-key* 用于认证用户的 Key。
Type string Required Example toss-user-key-abc123 Samples
Request Body Schema 这是用于 Toss Pay 创建支付订单的请求正文。
orderNo string 商户商品订单号（可使用数字、英文字母、特殊字符 _ - : . ^ @） Max Length 50
productDesc string 商品描述（包含韩文时请注意编码） Max Length 255
amount integer 总支付金额 Format int64 Max Length 7
amountTaxFree integer 支付金额中免税金额（如商品为应税，则为 0） Format int64 Max Length 7
amountTaxable integer 支付金额中应税金额（若未单独设置应税额，且免税额为 0，则 Toss Pay 服务器会自动计算应税金额和增值税） Format int64 Max Length 7
amountVat integer 支付金额中增值税（如无值，则按应退款应税金额除以 11，向上取整至小数点第一位） Format int64 Max Length 7
amountServiceFee integer 服务费金额 Format int64 Max Length 7
enablePayMethods string TOSS_MONEY/CARD or null
Max Length 100
cashReceipt boolean 现金收据开具可否（若为 null 则未开具）
cashReceiptTradeOption string 现金收据开具类型（CULTURE：文化费 / GENERAL：一般（默认） / PUBLIC_TP：交通费） Max Length 10
installment string 分期限制类型（USE：可分期（默认）/ NOT_USE：不可分期） Max Length 10
isTestPayment boolean 测试环境为 false，正式环境为 true（true 表示真实支付）
JSON {"orderNo": "20250422-01","productDesc": "테스트결제","amount": 0,"amountTaxFree": 0,"amountTaxable": 0,"amountVat": 0,"amountServiceFee": 0,"enablePayMethods": "string","cashReceipt": true,"cashReceiptTradeOption": "string","installment": "string","isTestPayment": true}
Responses 200 支付创建请求已成功处理。
Toss Pay 支付创建请求的响应。 payToken string Toss Pay 令牌（每次唯一，商户必须保存并管理该值）
400 参数错误或尚未完成 Toss Pay 订阅。
查询支付状态
可以查询用户请求的支付状态。 /api-partner/v1/apps-in-toss/pay/get-payment-status
Parameters Header Parameters
x-toss-user-key* 用于认证用户的 Key。 Type string Required Example toss-user-key-abc123
Samples
Request Body Schema
object 支付状态查询请求参数。 payToken string 用于识别支付的 Key。请求时 payToken 或 orderNo 二者之一为必填。 orderNo string 订单号。请求时 payToken 或 orderNo 二者之一为必填。 isTestPayment boolean 是否为测试支付.
JSON {"payToken": "pay-abc123","orderNo": "ORDER_20250407","isTestPayment": false}
Responses 200 返回支付状态信息。
支付状态查询响应信息
404 未找到对应的支付记录。
执行支付
对已完成支付认证的订单发起支付批准请求。 /api-partner/v1/apps-in-toss/pay/execute-payment
Parameters Header Parameters
x-toss-user-key* 用于认证用户的 Key。 Type string Required Example toss-user-key-abc123
Samples
Request Body 用于已认证支付订单的支付批准请求正文。
SCHEMA
payToken string Toss Pay 令牌（待批准支付订单的令牌值）
Max Length 30
orderNo string 商户商品订单号（可使用数字、字母及特殊字符 _ - : . ^ @）
Max Length 50
isTestPayment boolean 测试（Sandbox)环境为 false，正式环境为 true（true 表示真实支付）
JSON {"payToken": "string","orderNo": "20250422-01","isTestPayment": true}
Responses 200 支付批准请求已成功处理。. 400 参数错误或尚未完成 Toss Pay 订阅。
4. Toss Point 发放
查询促销 Toss Point 发放结果
此 API 可让合作应用查询发放给 Toss 用户的 Toss Point。 /api-partner/v1/apps-in-toss/promotion/execution-result
Parameters Header Parameters x-toss-user-key* 用于认证用户的 Key。 Type string Required Example toss-user-key-abc123
Samples
Request Body
JSON {"promotionCode": "string","key": "string"}
Responses 200 成功查询促销发放结果。 400 请求错误或缺少必要信息 401 用户未认证 403 无权限查询 Toss Point 发放结果
JSON {"resultType": "string","error": {"errorType": 0,"errorCode": "string","reason": "string","data": {"additionalProperties": {}},"title": "string"},"success": "string"}
发放促销奖励
此 API 允许合作应用向 Toss 用户发放 Toss Point。 /api-partner/v1/apps-in-toss/promotion/execute-promotion
Parameters Header Parameters x-toss-user-key* 用于认证用户的 Key。 Type string Required Example toss-user-key-abc123
Samples
Request Body
JSON {"promotionCode": "string","key": "string","amount": 0}
Responses 200 成功向 Toss 用户发放 Toss Point。 400 请求错误或缺少必要信息 401 用户未认证 403 无权限发放 Toss Point。 创建促销奖励发放 Key 此 API 为合作应用生成用于向 Toss 用户发放 Toss Point 的授权 Key。 /api-partner/v1/apps-in-toss/promotion/execute-promotion/get-key
Samples
Responses 200 成功生成促销奖励发放 Key 400 请求错误或缺少必要信息 401 用户未认证 403 无权限生成奖励发放 Key
5. IN-APP 支付（应用内支付）
查询支付状态
可查询已创建支付订单的交易状态和交易事务信息。在某些情况下，即使未收到支付批准响应，也可使用此接口。 /api-partner/v1/apps-in-toss/order/get-order-status
Request Body
JSON {"orderId": "string"}
Samples
Responses
200 成功查询应用内支付状态。