> 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 密钥值。

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

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

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

| 区分                | 发放方式                                                                                                              |
| ----------------- | ----------------------------------------------------------------------------------------------------------------- |
| `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`设置为 isTestPayment: 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`发送为该值时，不是现金收据开具对象。
{% endhint %}

**请求头**

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

| 名称                | 类型     | 必填  | 说明                                                                                                                                                                                                                                 |
| ----------------- | ------ | --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-toss-user-key` | string | 二选一 | [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 | 二选一 | [用户识别密钥发放](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`，如果是正式应用支付请求， `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 只使用以下 2 种之一。不要同时传递两个 header。

| 名称                | 类型     | 必填  | 说明                                                                                                                                                                                                                                 |
| ----------------- | ------ | --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-toss-user-key` | string | 二选一 | [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 | 二选一 | [用户识别密钥发放](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`，如果是在正式应用中签发的， `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": "Toss Bank",
    "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 只使用以下 2 种之一。不要同时传递两个 header。

| 名称                | 类型     | 必填  | 说明                                                                                                                                                                                                                                 |
| ----------------- | ------ | --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-toss-user-key` | string | 二选一 | [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 | 二选一 | [用户识别密钥发放](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`，如果是在正式应用中签发的， `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 只使用以下 2 种之一。不要同时传递两个 header。

| 名称                | 类型     | 必填  | 说明                                                                                                                                                                                                                                 |
| ----------------- | ------ | --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-toss-user-key` | string | 二选一 | [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 | 二选一 | [用户识别密钥发放](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`，如果是在正式应用中签发的， `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  | 这是支付完成处理时间。                                           |

```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 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                       | 现在是银行维护时间。请在维护结束后再使用。 |
| [其他错误代码](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.