> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/common/monetization/toss-pay/development.md).

# 开发

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

请按以下顺序进行对接流程。

1. [创建支付](#_1-결제-생성하기) — 在服务器上创建支付并 `payToken`获取。
2. [验证支付](#_2-결제-인증하기) — 用 SDK 打开支付窗口并执行用户认证。
3. [执行支付](#_3-결제-실행하기) — 用已完成认证的 `payToken`来实际确认支付。
4. [退款支付](#_4-결제-환불하기) — 对支付单进行退款。
5. [查询支付状态](#_5-결제-상태-조회하기) — 查询支付状态和交易。

***

### 预先准备事项

#### 需要进行控制台设置

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

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

签约/设置方法请参考 [Toss Pay 介绍](https://developers-apps-in-toss.toss.im/documentation/common/monetization/toss-pay) 文档。

#### 识别支付对象用户

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

| 区分                | 获取方式                                                                                                                  |
| ----------------- | --------------------------------------------------------------------------------------------------------------------- |
| `x-toss-user-key` | [通过 Toss 登录](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login)中获得的 `userKey` 值。 |
| `x-anon-key`      | [用户识别键发放](https://developers-apps-in-toss.toss.im/documentation/common/authentication/hash-key)获得的 hash 值。            |

请根据目的选择。

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

`x-anon-key`如果想提前确认 (hash) 是否为有效值， [验证识别键](https://developers-apps-in-toss.toss.im/documentation/common/authentication/hash-key#식별키-검증하기) API。

***

### 基本信息

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

{% hint style="info" %}
**服务器间通信需要 mTLS 证书**

Toss Pay 支付 API 是从合作伙伴服务器调用到 Apps in Toss 服务器的服务器间通信。为安全起见，请先在服务器上配置 mTLS 证书后再调用。证书获取方法请参考 [mTLS 证书发放方法](https://developers-apps-in-toss.toss.im/documentation/integration/getting-started)。
{% endhint %}

***

### 测试

在请求创建支付时 `isTestPayment: true`设置为 true 时，可以在沙箱环境中测试支付。无需在控制台单独设置，也可以在签约前进行测试。只是，在沙箱中只能创建支付，不支持实际确认处理。

***

### 1. 创建支付

创建支付单。

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

{% hint style="info" %}
**使用现金收据时请务必确认**

需要开具现金收据的合作方，在请求创建支付时 `cashReceipt: true`必须传递。 `cashReceipt`只能在创建支付时设置，支付完成后无法更改现金收据开具对象。 `cashReceipt`若省略 `false`发送为 false 时
{% endhint %}

**请求头**

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

| 名称                | 类型     | 必填   | 说明                                                                                                                                                                                                                                   |
| ----------------- | ------ | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `x-toss-user-key` | string | 任选 1 | [通过 Toss 登录](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login)中获得的 `userKey`。 [可通过](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login#_4-사용자-정보-받기)获取用户信息 |
| `x-anon-key`      | string | 任选 1 | [用户识别键发放](https://developers-apps-in-toss.toss.im/documentation/common/authentication/hash-key)中获得的 `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`，如果是 Live App 支付请求 `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 令牌**。每次都会生成唯一的令牌值。必须保存并管理。 |

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

***

### 2. 验证支付

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

**`TossPay`**

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

**签名**

```typescript
TossPay: {
  checkoutPayment: typeof checkoutPayment;
}
```

**属性**

* checkoutPaymenttypeof checkoutPayment

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

**`checkoutPayment`**

**签名**

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

**参数**

* **options** · 必需 · `CheckoutPaymentOptions`

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

**返回值**

* `Promise<CheckoutPaymentResult>`

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

**示例**

{% tabs %}
{% tab title="js" %}

```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);
  }
}
```

{% endtab %}

{% tab title="React" %}

```tsx
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>;
}
```

{% endtab %}

{% tab title="React Native" %}

```tsx
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>;
}
```

{% endtab %}
{% endtabs %}

**`CheckoutPaymentOptions`**

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

**签名**

```typescript
interface CheckoutPaymentOptions {
  payToken: string;
}
```

**属性**

* **payToken** · 必需 · `string`

  是支付令牌。

**`CheckoutPaymentResult`**

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

**签名**

```typescript
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 使用以下两种之一。不要同时传递两个 header。

| 名称                | 类型     | 必填   | 说明                                                                                                                                                                                                                                   |
| ----------------- | ------ | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `x-toss-user-key` | string | 任选 1 | [通过 Toss 登录](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login)中获得的 `userKey`。 [可通过](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login#_4-사용자-정보-받기)获取用户信息 |
| `x-anon-key`      | string | 任选 1 | [用户识别键发放](https://developers-apps-in-toss.toss.im/documentation/common/authentication/hash-key)中获得的 `hash` 值。                                                                                                                        |

**请求参数**

| 名称            | 类型      | 必填 | 说明                                                    |
| ------------- | ------- | -- | ----------------------------------------------------- |
| payToken      | String  | Y  | Toss Pay 令牌。                                          |
| orderNo       | String  | N  | 商家订单号。                                                |
| isTestPayment | boolean | Y  | `payToken`如果是从沙箱签发的 `true`，如果是从 Live App 签发的 `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:flag\_mm: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  | 错误代码。                                                                                                                                       |

```json
{
  "resultType": "SUCCESS",
  "success": {
    "code": 0,
    "mode": "TEST",
    "orderNo": "20250417-2",
    "amount": 10,
    "approvalTime": "2025-04-17 12:32:10",
    "stateMsg": "支付完成",
    "discountedAmount": 0,
    "paidAmount": 10,
    "payMethod": "TOSS_MONEY",
    "payToken": "O1NZck9XME8ureeVJVJP67",
    "transactionId": "45a77cf4-5577-4d5c-8827-4d4dd328bf12",
    "cardCompanyCode": null,
    "cardCompanyName": null,
    "cardAuthorizationNo": null,
    "spreadOut": null,
    "noInterest": null,
    "salesCheckLinkUrl": null,
    "cardMethodType": null,
    "cardNumber": null,
    "cardUserType": null,
    "cardNum4Print": null,
    "cardBinNumber": null,
    "cashReceiptMgtKey": null,
    "accountBankCode": "092",
    "accountBankName": "토스뱅크",
    "accountNumber": "100******094",
    "msg": null,
    "errorCode": null
  }
}
```

***

### 4. 退款支付

向买家退还支付单。

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

**请求头**

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

| 名称                | 类型     | 必填   | 说明                                                                                                                                                                                                                                   |
| ----------------- | ------ | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `x-toss-user-key` | string | 任选 1 | [通过 Toss 登录](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login)中获得的 `userKey`。 [可通过](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login#_4-사용자-정보-받기)获取用户信息 |
| `x-anon-key`      | string | 任选 1 | [用户识别键发放](https://developers-apps-in-toss.toss.im/documentation/common/authentication/hash-key)中获得的 `hash` 值。                                                                                                                        |

**请求参数**

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

**响应**

| 名称                     | 类型      | 说明                                                                                                                                          |
| ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| refundNo               | String  | 退款编号。                                                                                                                                       |
| approvalTime           | String  | 退款处理时间。 (yyyy-MM-dd HH:flag\_mm: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  | 已脱敏的账号。                                                                                                                                     |

```json
{
  "resultType": "SUCCESS",
  "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",
    "cardNum4Print": "string",
    "cardBinNumber": "string"
    "accountBankCode": "string",
    "accountBankName": "string",
    "accountNumber": "string"
  }
}
```

***

### 5. 查询支付状态

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

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

**请求头**

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

| 名称                | 类型     | 必填   | 说明                                                                                                                                                                                                                                   |
| ----------------- | ------ | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `x-toss-user-key` | string | 任选 1 | [通过 Toss 登录](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login)中获得的 `userKey`。 [可通过](https://developers-apps-in-toss.toss.im/documentation/common/authentication/toss-login#_4-사용자-정보-받기)获取用户信息 |
| `x-anon-key`      | string | 任选 1 | [用户识别键发放](https://developers-apps-in-toss.toss.im/documentation/common/authentication/hash-key)中获得的 `hash` 值。                                                                                                                        |

**请求参数**

| 名称            | 类型      | 必填 | 说明                                                    |
| ------------- | ------- | -- | ----------------------------------------------------- |
| payToken      | String  | Y  | Toss Pay 令牌。                                          |
| orderNo       | String  | Y  | 商家订单号。                                                |
| isTestPayment | boolean | Y  | `payToken`如果是从沙箱签发的 `true`，如果是从 Live App 签发的 `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                 | Object  | 这是卡信息。                                              |
| noInterest           | 布尔值     | 是否适用信用卡免息。 `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  | 这是支付完成处理时间。                                         |

```json
{
  "resultType": "SUCCESS",
  "success": {
    "mode": "string",
    "payToken": "string",
    "orderNo": "string",
    "payStatus": "string",
    "payMethod": "string",
    "amount": 0,
    "discountedAmount": 0,
    "discountAmountV2": 0,
    "paidPointV2": 0,
    "paidAmount": 0,
    "refundableAmount": 0,
    "amountTaxable": 0,
    "amountTaxFree": 0,
    "amountVat": 0,
    "amountServiceFee": 0,
    "disposableCupDeposit": 0,
    "accountBankCode": "string",
    "accountBankName": "string",
    "accountNumber": "string",
    "card": {
      "noInterest": true,
      "spreadOut": 0,
      "cardAuthorizationNo": "string",
      "cardMethodType": "string",
      "cardUserType": "string",
      "cardNumber": "string",
      "cardBinNumber": "string"
      "cardNum4Print": "string",
      "salesCheckLinkUrl": "string",
      "cardCompanyName": "string",
      "cardCompanyCode": 0
    },
    "transactions": [
      {
        "stepType": "string",
        "transactionId": "string",
        "paidAmount": 0,
        "transactionAmount": 0,
        "discountedAmount": 0,
        "pointAmount": 0,
        "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银行                 |
| 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                       | 现在是银行维护时间。请在维护结束后使用。 |
| [其他错误代码](https://docs-pay.toss.im/guide/error-code) |                      |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-zh/common/monetization/toss-pay/development.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.