开发

服务介绍和控制台设置方法请参考 Toss Pay 介绍文档。

联动流程请按以下顺序进行。

1. 创建支付 — 在服务器上创建支付并 payToken获取。
2. 验证支付 — 通过 SDK 打开支付窗口并执行用户认证。
3. 执行支付 — 已完成认证的 payToken用于完成实际支付审批。
4. 支付退款 — 对支付订单进行退款。
5. 查询支付状态 — 查询支付状态和交易。

---

前置准备事项

需要进行控制台设置

调用 API 之前，需要先完成以下步骤。

1. 请先进行签约。
2. 请在控制台注册 Toss Pay 密钥值。

签约/设置方法请见 Toss Pay 介绍 文档。

识别支付对象用户

Toss Pay 通过以下 2 种方法之一识别支付对象。请不要同时传递两个值，只选择一个。

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

请根据用途选择。

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

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

---

基本信息

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

服务器间通信需要 mTLS 证书

Toss Pay 支付 API 是从合作方服务器调用 Apps in Toss 服务器的服务器间通信。为安全起见，请先在服务器上配置 mTLS 证书后再调用。证书签发方法请见 mTLS 证书发放方法。

---

测试

在创建支付请求时 isTestPayment: true设置为 isTestPayment: true 后，可以在沙盒环境中测试支付。无需在控制台单独设置，签约前也可以测试。不过，在沙盒中只能创建支付，不支持实际审批处理。

---

1. 创建支付

创建支付订单。

• Content-type: application/json
• Method: POST
• URL: /api-partner/v1/apps-in-toss/pay/make-payment

使用现金收据时请务必确认

需要开具现金收据的合作方在创建支付请求时 cashReceipt: true必须传递。 cashReceipt只能在创建支付时设置，支付完成后无法更改现金收据的开具对象。 cashReceipt若遗漏或 false发送为该值时，不是现金收据开具对象。

请求头

用于识别支付对象的 header 只使用以下 2 种之一。不要同时传递两个 header。

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

请求参数

名称	类型	必填	说明
orderNo	String	Y	商户的订单号。每个商户每次都必须唯一，重复时创建支付请求会失败。仅可使用数字、英文字母、特殊字符 _-:.^@，且不超过 50 个字符。相同订单号在买家认证完成后不可再次使用。首次创建后超过 2 年的订单号也不能重用。
productDesc	String	Y	商品描述。不能仅设置为空白，且反斜杠 \\和引号 "不能包含，且总共不超过 255 个字符。包含韩文时请使用 UTF-8 编码。
amount	Integer	Y	总支付金额。与金额相关的所有参数都必须以数字形式传递。
amountTaxFree	Integer	Y	支付金额中的免税金额。如果是应税商品， 0请传为该值。
amountTaxable	Integer	N	支付金额中的应税金额。若未单独设置，并将免税金额 0以韩元发送，服务器会自动计算。
amountVat	Integer	N	支付金额中的增值税。如果没有值，则将应税金额除以 11 后在小数点第一位进行进位计算。
amountServiceFee	Integer	N	支付金额中的服务费。
enablePayMethods	String	N	支付方式区分变量。- TOSS_MONEY: 仅显示 Toss Money - CARD: 仅显示卡片 - null 或其他：显示为商店设置的默认支付方式
cashReceipt	boolean	N	是否可开具现金收据。使用现金收据功能时 true，未使用时 false请传递。 null 传递相同的异常值时，会明确地 false处理为。
cashReceiptTradeOption	String	N	现金收据开具类型。- GENERAL: 普通（默认值） - CULTURE: 文化费用 - PUBLIC_TP: 交通费
installment	String	N	分期限制类型。- USE: 使用分期（默认值） - NOT_USE: 不使用分期
isTestPayment	boolean	Y	如果是沙盒支付请求， true，如果是正式应用支付请求， false。

curl --location 'https://{{domain}}/api-partner/v1/apps-in-toss/pay/make-payment' \\
--header 'Content-Type: application/json' \
--header 'x-toss-user-key: 1234' \\
--data '{
    "orderNo": "test-20250417-3",
    "productDesc": "test02",
    "amount": 10,
    "amountTaxFree": 0,
    "cashReceipt": false,
    "isTestPayment": true
}'

响应参数

名称	类型	说明
payToken	String	Toss Pay 令牌。每次都会生成唯一的令牌值。必须保存并管理。

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

---

2. 验证支付

TossPay.checkoutPayment会打开 Toss Pay 支付窗口并执行用户认证。认证完成后会返回是否成功。实际支付处理需要在认证成功后由服务器另外进行。

TossPay

TossPay是一个汇总 Toss Pay 支付相关函数的对象。

签名

TossPay: {
  checkoutPayment: typeof checkoutPayment;
}

属性

• checkoutPaymenttypeof checkoutPayment

  用于验证 Toss Pay 支付的函数。

checkoutPayment

签名

function checkoutPayment(options: CheckoutPaymentOptions): Promise<CheckoutPaymentResult>;

参数

• options · 必填 · CheckoutPaymentOptions

  打开支付窗口时所需的选项。

返回值

• Promise<CheckoutPaymentResult>

  返回包含认证是否成功的结果。

示例

js

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

async function handleCheckoutPayment() {
  try {
    // 实际实现时，请替换为负责创建支付的 API 端点。
    const { payToken } = await fetch('/my-api/payment/create').then((res) => res.json());
    const { success, reason } = await checkoutPayment({ payToken });

    if (success) {
      // 实际实现时，请替换为负责执行支付的 API 端点。
      await fetch('/my-api/payment/execute', {
        method: 'POST',
        body: JSON.stringify({ payToken }),
        headers: { 'Content-Type': 'application/json' },
      });
      console.log('支付成功');
    } else {
      console.log('认证失败：', reason);
    }
  } catch (error) {
    console.error('支付认证过程中发生错误：', error);
  }
}

React

import { checkoutPayment } from '@apps-in-toss/web-framework';
import { Button } from '@toss/tds-mobile';

function TossPayButton() {
  async function handlePayment() {
    try {
      const { payToken } = await fetch('/my-api/payment/create').then((res) => res.json());
      const { success, reason } = await checkoutPayment({ payToken });

      if (success) {
        await fetch('/my-api/payment/execute', {
          method: 'POST',
          body: JSON.stringify({ payToken }),
          headers: { 'Content-Type': 'application/json' },
        });
        console.log('支付成功');
      } else {
        console.log('认证失败：', reason);
      }
    } catch (error) {
      console.error('支付认证过程中发生错误：', error);
    }
  }

  return <Button onClick={handlePayment}>支付</Button>;
}

React Native

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

function TossPayButton() {
  async function handlePayment() {
    try {
      const { payToken } = await fetch('/my-api/payment/create').then((res) => res.json());
      const { success, reason } = await TossPay.checkoutPayment({ payToken });

      if (success) {
        await fetch('/my-api/payment/execute', {
          method: 'POST',
          body: JSON.stringify({ payToken }),
          headers: { 'Content-Type': 'application/json' },
        });
        console.log('支付成功');
      } else {
        console.log('认证失败：', reason);
      }
    } catch (error) {
      console.error('支付认证过程中发生错误：', error);
    }
  }

  return <Button onPress={handlePayment}>支付</Button>;
}

CheckoutPaymentOptions

CheckoutPaymentOptions是打开 Toss Pay 支付窗口时所需的选项。

签名

interface CheckoutPaymentOptions {
  payToken: string;
}

属性

• payToken · 必填 · string

  是支付令牌。

CheckoutPaymentResult

CheckoutPaymentResult表示用户在 Toss Pay 支付窗口中是否认证成功。

签名

interface CheckoutPaymentResult {
  success: boolean;
  reason?: string;
}

属性

• success · 必填 · boolean

  表示认证是否成功。
• reasonstring

  是认证失败时的原因。

---

3. 执行支付

买家完成支付认证后，支付状态为“待处理”状态。 payToken与订单号一起调用此 API 时，实际审批会完成，并从买家的支付方式中扣款。

• Content-type: application/json
• Method: POST
• URL: /api-partner/v1/apps-in-toss/pay/execute-payment

请求头

用于识别支付对象的 header 只使用以下 2 种之一。不要同时传递两个 header。

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

请求参数

名称	类型	必填	说明
payToken	String	Y	是 Toss Pay 令牌。
orderNo	String	N	是商户订单号。
isTestPayment	boolean	Y	payToken如果是在沙盒中签发的， true，如果是在正式应用中签发的， false。

curl --location 'https://{{domain}}/api-partner/v1/apps-in-toss/pay/execute-payment' \\
--header 'Content-Type: application/json' \
--header 'x-toss-user-key: 1234' \\
--data '{
    "payToken": "test-20250417-3",
    "orderNo": "test02",
    "isTestPayment": true
}'

响应

名称	类型	说明
mode	String	是支付环境。 LIVE: 真实交易用， TEST: 测试用
orderNo	String	是已审批商品的订单号。
amount	Integer	是商品金额。
approvalTime	String	是支付审批处理时间。 (yyyy-MM-dd HH🇲🇲ss)
stateMsg	String	是状态响应文本。若为正常响应， "支付完成"会返回。
discountedAmount	Integer	是优惠金额。若未应用优惠， 0会返回为该值。包括立减优惠和 Toss 积分使用金额。
paidAmount	Integer	是支付方式审批金额。即总金额中扣除优惠金额后的纯支付方式审批金额。
payMethod	String	是支付方式。 TOSS_MONEY: Toss Money， CARD: 卡片
payToken	String	是 Toss Pay 令牌。必须保存并管理。
transactionId	String	是交易事务 ID。可在调用销售凭证或进行退款时作为区分值使用。
cardCompanyCode	String	是审批银行卡公司代码。
cardCompanyName	String	是审批银行卡公司名称。
cardAuthorizationNo	String	是买家可以查看的银行卡公司批准号。可在 Live Key 支付中查看。
spreadOut	String	是用户选择的卡片分期月数。金额低于 5 万韩元及一次性付款时， 0会返回为该值。
noInterest	String	是否适用卡片免息。 true: 免息， false: 普通
salesCheckLinkUrl	String	是信用卡销售凭证调用 URL。
cardMethodType	String	是卡片类型。 CREDIT: 信用卡， CHECK: 借记卡， PREPAYMENT: 预付卡
cardNumber	String	是已脱敏的卡号。16 位卡号中间部分会被脱敏。
cardUserType	String	是卡片用户区分。 PERSONAL: 本人卡， PERSONAL_FAMILY: 家属卡， CORP_PERSONAL: 法人指定支付账户员工， CORP_PRIVATE: 法人公用， CORP_COMPANY: 法人指定支付账户公司（仅 Hana Card）
cardNum4Print	String	是用户选择的卡片后 4 位。
cardBinNumber	String	是卡 BIN 号。
cashReceiptMgtKey	String	是现金收据管理号标识值。若有此字段，可区分是否开具现金收据。
accountBankCode	String	是银行代码。Toss Money 支付时传递 Toss 定义的银行代码。
accountBankName	String	是银行名称。
accountNumber	String	是账号。包含部分脱敏。
msg	String	是响应非成功时的说明消息。
errorCode	String	是错误代码。

---

4. 退款支付

将支付订单退款给买家。

• Content-type: application/json
• Method: POST
• URL: /api-partner/v1/apps-in-toss/pay/refund-payment

请求头

用于识别支付对象的 header 只使用以下 2 种之一。不要同时传递两个 header。

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

请求参数

名称	类型	必填	说明
payToken	String	Y	是 Toss Pay 令牌。
reason	String	Y	是退款原因。仅允许韩文、数字、英文字母、特殊字符 _ - : . ^ @ ( ) [ ] # / ! % ? &。
isTestPayment	boolean	Y	payToken如果是在沙盒中签发的， true，如果是在正式应用中签发的， false。

响应

名称	类型	说明
refundNo	String	是退款编号。
approvalTime	String	是退款处理时间。 (yyyy-MM-dd HH🇲🇲ss)
cashReceiptMgtKey	String	是现金收据管理号标识值。
refundableAmount	Integer	是可退款金额。
discountedAmount	Integer	是优惠金额。
paidAmount	Integer	是支付方式审批金额。
refundedAmount	Integer	是退款请求金额。
refundedDiscountAmount	Integer	是退款请求金额中实际扣除的优惠金额。
refundedPaidAmount	Integer	是退款请求金额中实际扣除的支付方式金额。
payToken	String	是已退款的支付令牌。
transactionId	String	是交易事务 ID。
cardMethodType	String	是卡片类型。 CREDIT: 信用卡， CHECK: 借记卡， PREPAYMENT: 预付卡
cardNumber	String	是已脱敏的卡号。
cardUserType	String	是卡片用户区分。 PERSONAL: 本人卡， PERSONAL_FAMILY: 家属卡， CORP_PERSONAL: 法人指定支付账户员工， CORP_PRIVATE: 法人公用， CORP_COMPANY: 法人指定支付账户公司（仅 Hana Card）
cardNum4Print	String	是用户选择的卡片后 4 位。
cardBinNumber	String	是卡 BIN 号。
accountBankCode	String	是银行代码。Toss Money 支付时传递 Toss 定义的银行代码。
accountBankName	String	是银行名称。
accountNumber	String	是已脱敏的账号。

---

5. 查询支付状态

可以查询已创建支付的交易状态和交易流水。即使未收到批准或退款响应时也可使用。

• Content-type: application/json
• Method: POST
• URL: /api-partner/v1/apps-in-toss/pay/get-payment-status

请求头

用于识别支付对象的 header 只使用以下 2 种之一。不要同时传递两个 header。

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

请求参数

名称	类型	必填	说明
payToken	String	Y	是 Toss Pay 令牌。
orderNo	String	Y	是商户订单号。
isTestPayment	boolean	Y	payToken如果是在沙盒中签发的， true，如果是在正式应用中签发的， false。

响应

名称	类型	说明
mode	String	是支付环境。 LIVE: 真实交易用， TEST: 测试用
payToken	String	是 Toss Pay 令牌。
orderNo	String	这是与 Toss Pay 关联的商户订单号。
payStatus	String	这是支付状态。
payMethod	String	是支付方式。 TOSS_MONEY: Toss Money， CARD: 卡片
amount	Integer	这是商户传递的支付总金额。
discountedAmount	Integer	是优惠金额。
discountAmountV2	Integer	这是即时折扣应用金额。
paidPointV2	Integer	这是使用的 Toss 积分金额。
paidAmount	Integer	是支付方式审批金额。
refundableAmount	Integer	这是可退款余额。
amountTaxable	Integer	这是总支付金额中的应税金额。
amountTaxFree	Integer	这是总支付金额中的免税金额。
amountVat	Integer	这是总支付金额中的增值税金额。
amountServiceFee	Integer	这是总支付金额中的服务费。
disposableCupDeposit	Integer	这是一次性杯子押金。
accountBankCode	String	这是银行代码。
accountBankName	String	是银行名称。
accountNumber	String	是已脱敏的账号。
card	对象	这是银行卡信息。
noInterest	Boolean	是否适用卡片免息。 true: 免息， false: 普通
spreadOut	Integer	这是用户选择的信用卡分期期数。
cardAuthorizationNo	String	这是购买者可以查看的发卡行授权编号。
cardMethodType	String	是卡片类型。 CREDIT: 信用卡， CHECK: 借记卡， PREPAYMENT: 预付卡
cardUserType	String	是卡片用户区分。
cardNumber	String	是已脱敏的卡号。
cardBinNumber	String	是卡 BIN 号。
cardNum4Print	String	是用户选择的卡片后 4 位。
salesCheckLinkUrl	String	是信用卡销售凭证调用 URL。
cardCompanyName	String	是审批银行卡公司名称。
cardCompanyCode	Integer	这是发卡行代码。
transactions	list	这是交易流水列表。
stepType	String	这是请求的交易类型。 PAY: 支付, REFUND: 退款
transactionId	String	这是交易流水 ID。建议在交易对账时使用。
paidAmount	Integer	这是所请求交易类型中的支付方式金额。
transactionAmount	Integer	这是所请求交易类型的商户传递金额。退款请求时会返回负金额。
discountedAmount	Integer	这是所请求交易类型中适用的折扣金额。包含即时折扣和 Toss 积分使用金额。
pointAmount	Integer	这是所请求交易类型中的积分金额。
regTs	String	这是请求处理时间。
createdTs	String	这是支付创建时间。也是用户首次支付请求时间。
paidTs	String	这是支付完成处理时间。

---

6. 代码整理

支付状态列表

值	说明
PAY_STANDBY	等待支付
PAY_APPROVED	购买者认证完成
PAY_CANCEL	支付取消
PAY_PROGRESS	支付进行中
PAY_COMPLETE	支付完成
REFUND_PROGRESS	退款进行中
REFUND_SUCCESS	退款成功
SETTLEMENT_COMPLETE	结算完成
SETTLEMENT_REFUND_COMPLETE	退款结算完成

银行代码列表

在 Toss Money 支付的情况下，也会一并传递用户选择的账户信息。

银行代码 (accountBankCode)	银行名称 (accountBankName)
002	KDB产业银行
003	IBK企业银行
004	KB国民银行
005	KEB韩亚银行
007	水协银行
011	NH农协银行
020	友利银行
023	SC银行
027	花旗银行
031	大邱银行
032	釜山银行
034	光州银行
035	济州银行
037	全北银行
039	庆南银行
045	MG新村金库
048	信用合作社
050	储蓄银行
064	山林组合
071	邮局
081	韩亚银行
088	新韩银行
089	K银行
090	Kakao银行
092	Toss Bank
103	SBI储蓄银行
218	KB证券
230	未来资产证券
238	未来资产证券
240	三星证券
243	韩国投资证券
247	NH投资证券
261	教保证券
262	HI投资证券
263	现代汽车投资证券
264	Kiwoom证券
265	eBEST证券
266	SK证券
267	大信证券
269	韩华投资证券
270	韩亚证券
271	Toss 证券
278	新韩投资证券
279	DB金融投资
280	Eugene投资
287	Meritz证券
888	Toss Money
889	Toss 积分

卡公司代码列表

卡公司名称	卡（收单机构）代码
新韩	1
现代	2
三星	3
国民	4
乐天	5
韩亚	6
友利	7
农协	8
花旗（不支持）	9
BC（BC）	10

错误代码

值	说明
PAYMENT_EXISTING_PAYMENT	这是已存在的支付。
COMMON_INVALID_API_KEY	这是无效的 apiKey。
COMMON_BREAK_TIME_OF_BANK	现在是银行维护时间。请在维护结束后再使用。
其他错误代码