### Install PortOne Python Server SDK

Source: https://developers.portone.io/opi/ko/integration/webhook/readme-v2

Instructions for adding the `portone-server-sdk` package to your Python project. The SDK is distributed via PyPI and requires Python 3.9 or higher. Examples cover various dependency management tools.

```shell
uv add portone-server-sdk
```

```shell
poetry add portone-server-sdk
```

```shell
rye add portone-server-sdk
```

```shell
pipenv install portone-server-sdk
```

```shell
conda install portone-server-sdk
```

```toml
[project]
dependencies = [
  "portone-server-sdk~=x.x.x"
]
```

```shell
pdm add portone-server-sdk
```

```shell
portone-server-sdk ~= x.x.x
```

--------------------------------

### Parameter Example: Direct Card Call with Fixed Installment

Source: https://developers.portone.io/opi/ko/integration/pg/v1/welcome/caution

Example JSON configuration for direct card calls (e.g., BC Card) requiring both the card code and a fixed installment period (e.g., 5 months) for Welcome Payments.

```json
{
  "channelKey": "{콘솔 내 연동 정보의 채널키}",
  "pay_method": "card",
  "card": {
    "direct": {
      "code": "361", // BC카드
      "quota": 5 // 5개월 할부
    }
  }
}
```

--------------------------------

### Parameter Example: Card Payment Installment Options (PC)

Source: https://developers.portone.io/opi/ko/integration/pg/v1/welcome/caution

Example JSON configuration for card payment on PC, showing how to include installment options (2 to 6 months). The '0' (lump sum) is automatically included by Welcome Payments.

```json
{
  "channelKey": "{콘솔 내 연동 정보의 채널키}",
  "pay_method": "card",
  "display": {
    "card_quota": [2, 3, 4, 5, 6] // 일시불 + 2개월 ~ 6개월까지 결제창에 표기
  }
}
```

--------------------------------

### Setup Toss Brand Pay Password Example (Javascript SDK)

Source: https://developers.portone.io/opi/ko/integration/pg/v1/toss-brandpay/module

Demonstrates how to use the `setupPassword()` method of the Brand Pay module instance, including basic error handling for user cancellation.

```Javascript
brandpayModule.setupPassword().catch(function (error) {
  if (error.code === "USER_CANCEL") {
    // 사용자가 창을 닫아 취소한 경우에 대한 처리
  }
});
```

--------------------------------

### Add PortOne JVM Server SDK Dependency

Source: https://developers.portone.io/opi/ko/integration/webhook/readme-v2

Instructions for adding the `io.portone:server-sdk` package as a dependency to JVM-based projects, compatible with Java, Kotlin, and Scala. The SDK is distributed via Maven Central. Examples cover common build tools.

```xml
<dependency>
  <groupId>io.portone</groupId>
  <artifactId>server-sdk</artifactId>
  <version>x.x.x</version>
</dependency>
```

```kotlin
implementation("io.portone:server-sdk:x.x.x")
```

```groovy
implementation 'io.portone:server-sdk:x.x.x'
```

```scala
libraryDependencies += "io.portone" % "server-sdk" % "x.x.x"
```

--------------------------------

### Parameter Example: Toss Pay Installment Quota Display

Source: https://developers.portone.io/opi/ko/integration/pg/v1/welcome/caution

Example JSON configuration for setting installment display options for Toss Pay. The actual displayed installment period may extend beyond the configured value if the card company offers longer interest-free installments.

```json
{
  "channelKey": "{콘솔 내 연동 정보의 채널키}",
  "pay_method": "card",
  "display": {
    "card_quota": [2, 3]
  }
}
```

--------------------------------

### Parameter Example: Card Payment without Direct Call Fixed Installment

Source: https://developers.portone.io/opi/ko/integration/pg/v1/welcome/caution

Example JSON configuration for card payment where the user selects the card and installment period from the payment window, without specifying direct card call or fixed installment.

```json
{
  "channelKey": "{콘솔 내 연동 정보의 채널키}",
  "pay_method": "card"
}
```

--------------------------------

### Kookmin Card Installment Payment Example

Source: https://developers.portone.io/opi/ko/integration/pg/v1/welcome/caution

This snippet illustrates how to initiate a direct payment call for a Kookmin Card installment plan and the corresponding payment approval response. It demonstrates setting the `channelKey`, `pay_method`, `amount`, and specific `card.direct` parameters for installment payments, along with the `card_quota` field in the successful response.

```json
{
  "channelKey": "{콘솔 내 연동 정보의 채널키}",
  "pay_method": "card",
  "amount": "50000",
  "card": {
    "direct": {
      // 국민카드 5개월 할부 다이렉트 호출
      "code": "381",
      "quota": 5
    }
  }
}
```

```json
// GET /payments/{imp_uid}
{
  "card_quota": 5
}
```

--------------------------------

### Parameter Example: Card Payment Lump Sum Only (PC)

Source: https://developers.portone.io/opi/ko/integration/pg/v1/welcome/caution

Example JSON configuration for card payment on PC where no installment options are specified, resulting in only lump sum payment being displayed.

```json
{
  "channelKey": "{콘솔 내 연동 정보의 채널키}",
  "pay_method": "card"
}
```

--------------------------------

### Parameter Example: Allowed Carrier List (phone.detail)

Source: https://developers.portone.io/opi/ko/integration/pg/v1/welcome/caution

Example JSON configuration to allow rendering for specific carriers (SKT, KTF) using the `phone.detail` parameter. This configuration ensures normal operation when used alone.

```json
{
  "phone": {
    "detail": [
      { "carrier": "SKT", "enabled": true },
      { "carrier": "KTF", "enabled": true }
    ]
  }
}
```

--------------------------------

### Example Welcome Payments Bypass Configuration JSON

Source: https://developers.portone.io/opi/ko/integration/pg/v1/welcome/readme

A JSON example demonstrating how to configure `acceptmethod` for Welcome Payments, including payment window styling, allowed payment amounts, and mobile carrier selection, and phone number editability.

```JSON
{
  "channelKey": "{콘솔 내 연동 정보의 채널키}",
  "bypass": {
    "welcome": {
      "acceptmethod": [
        "SKIN(#fc6b2d)",
        "below1000",
        "paypopup",
        "onlyeasypaycode(kakaopay:payco)",
        "hppdefaultcorp(KT)",
        "hppnofix(Y)"
      ]
    }
  }
}
```

--------------------------------

### Example JSON Bypass Configuration for Welcome Payments

Source: https://developers.portone.io/opi/ko/integration/pg/v2/welcome

Demonstrates a JSON configuration for bypassing payment gateway settings, including UI customization (background color), payment amount limits (below 1,000 KRW), secure click rendering as a popup, limiting easy payment options to KakaoPay and Payco, setting KT as the default carrier for mobile micro-payments, and preventing buyer phone number modification.

```json
{
  "channelKey": "{콘솔 내 연동 정보의 채널키}",
  "bypass": {
    "welcome": {
      "acceptmethod": [
        "SKIN(#fc6b2d)",
        "below1000",
        "paypopup",
        "onlyeasypaycode(kakaopay:payco)",
        "hppdefaultcorp(KT)",
        "hppnofix(Y)"
      ]
    }
  }
}
```

--------------------------------

### Example JSON for products parameter

Source: https://developers.portone.io/opi/ko/integration/pg/v1/spb/warning

Illustrates the structure for the 'products' array, including 'id', 'name', 'code', 'unitPrice', 'quantity', and 'tag'. This parameter is strongly recommended by PayPal. It's crucial that the sum of (quantity * unitPrice) for all products matches the total order amount to avoid errors.

```json
{
  "products": [
    {
      "id": "1666779119262",
      "name": "시그니처 핫 초콜릿",
      "code": "DRINK_SIGNITURE_HOT_CHOCOLATE",
      "unitPrice": 5700,
      "quantity": 2,
      "tag": "TAG-1"
    },
    {
      "id": "1666779134572",
      "name": "아이스 아메리카노",
      "code": "DRINK_AMERICANO",
      "unitPrice": 4800,
      "quantity": 3,
      "tag": "TAG-2"
    }
  ]
}
```

--------------------------------

### PortOne SDK Direct Card Payment Request (TypeScript)

Source: https://developers.portone.io/opi/ko/integration/pg/v2/kpn

Demonstrates how to initiate a direct card payment using the PortOne browser SDK. This example specifically targets Kookmin Card direct payment and includes essential parameters for store identification, channel key, payment details, and card company specification.

```typescript
import * as PortOne from "@portone/browser-sdk/v2";
function requestPayment() {
  PortOne.requestPayment({
    storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", // 고객사 storeId로 변경해주세요.
    channelKey: "channel-key-9987cb87-6458-4888-b94e-68d9a2da896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요.
    paymentId: `payment${Math.random().toString(36).slice(2)}`,
    orderName: "나이키 와플 트레이너 2 SD",
    totalAmount: 1000,
    currency: "CURRENCY_KRW",
    payMethod: "CARD",
    card: {
      cardCompany: "KOOKMIN_CARD" // 국민카드 다이렉트
    }
  });
}
```

--------------------------------

### Parameter Example: Virtual Account Deposit Deadline (vbank_due)

Source: https://developers.portone.io/opi/ko/integration/pg/v1/welcome/caution

Example JSON configuration for setting the virtual account deposit deadline using `vbank_due`. Note that the seconds value will be ignored and set to 59.

```json
{
  "vbank_due": "2023-01-01 12:34:56"
}
```

--------------------------------

### Open Toss Brand Pay Settings Example (Javascript SDK)

Source: https://developers.portone.io/opi/ko/integration/pg/v1/toss-brandpay/module

Shows how to use the `openSettings()` method to launch the payment management screen for Brand Pay, with error handling for user cancellation.

```Javascript
brandpayModule.openSettings().catch(function (error) {
  if (error.code === "USER_CANCEL") {
    // 사용자가 창을 닫아 취소한 경우에 대한 처리
  }
});
```

--------------------------------

### Parameter Example: Default Selected Carrier (hppdefaultcorp)

Source: https://developers.portone.io/opi/ko/integration/pg/v1/welcome/caution

Example JSON configuration to set SKT as the default selected carrier using `bypass.welcome.acceptmethod.hppdefaultcorp` and `P_RESERVED.hpp_default_corp` parameters. This configuration ensures normal operation when used alone.

```json
{
  "bypass": {
    "welcome": {
      "acceptmethod": ["hppdefaultcorp(SKT)"],
      "P_RESERVED": ["hpp_default_corp=SKT"]
    }
  }
}
```

--------------------------------

### Request to Set Custom Settlement Start Date

Source: https://developers.portone.io/platform/ko/usages/order

Code examples demonstrating how to make a POST request to the PortOne Transfer API to initiate a transfer with a specified `settlementStartDate`. This allows defining the exact point from which settlement calculations should begin.

```python
orderTransfer_payload = {
"partnerId": "partnerA", # 파트너 A 파트너 아이디 등록 가정
"paymentId": "payment_6", # 포트원 결제시 가맹점 주문번호 (merchant_uid)
"orderDetail": {
  "orderAmount": 10000, # 주문금액
},
"settlementStartDate": '2023-09-01', # 배송완료 시점 (예시)
"isForTest": false, # 테스트 정산 여부
}

headers = {
'Authorization': f'PortOne ${PORTONE_API_SECRET}',
'Content-Type': 'application/json'
}

orderTransferResponse =requests.post('https://api.portone.io/platform/transfer/order', headers=headers, json=orderTransfer_payload)
```

```javascript
const axios = require("axios");
const orderTransfer_payload = {
  partnerId: "partnerA", // 파트너 A 파트너 아이디 등록 가정
  paymentId: "payment_6", // 기존 결제의 고객사 주문번호 (V1 결제 모듈 이용 시 merchant_uid 입력)
  orderDetail: {
    orderAmount: 10000, // 주문금액
  },
  settlementStartDate: "2023-09-01", // 배송완료 시점 (예시)
  isForTest: false, // 테스트 정산 여부
};

const headers = {
  "Content-Type": "application/json",
  Authorization: `PortOne ${PORTONE_API_SECRET}`,
};

async function sendOrderTransfer(data) {
  try {
    const response = await axios.post(
      "https://api.portone.io/platform/transfer/order",
      data,
      {
        headers: headers,
      },
    );
    return response.data;
  } catch (error) {
    console.error("Error sending order transfer:", error);
  }
}
```

--------------------------------

### Parameter Example: Conflicting Carrier Options

Source: https://developers.portone.io/opi/ko/integration/pg/v1/welcome/caution

Example JSON configuration demonstrating the conflict when `phone.detail` and `bypass.welcome.acceptmethod.hppdefaultcorp` parameters are used together. This combination does not operate normally.

```json
{
  "phone": {
    "detail": [
      { "carrier": "SKT", "enabled": true },
      { "carrier": "KTF", "enabled": true }
    ]
  },
  "bypass": {
    "welcome": {
      "acceptmethod": ["hppdefaultcorp(SKT)"],
      "P_RESERVED": ["hpp_default_corp=SKT"]
    }
  }
}
```

--------------------------------

### Retrieve Toss Brand Pay Payment Methods Example (Javascript SDK)

Source: https://developers.portone.io/opi/ko/integration/pg/v1/toss-brandpay/module

Illustrates the usage of the `getPaymentMethods()` method to query registered payment methods, including success and error handling.

```Javascript
brandpayModule
  .getPaymentMethods()
  .then(function (methods) {
    // 성공 처리
  })
  .catch(function (error) {
    if (error.code === "USER_CANCEL") {
      // 사용자가 결제창을 닫은 경우 에러 처리
    }
  });
```

--------------------------------

### Supported Payment Environments

Source: https://developers.portone.io/opi/ko/integration/pg/v1/smartro-v2/readme

This section lists the payment environments supported by the Smartro integration.

```APIDOC
Available Payment Environments:
- PC (iframe)
- Mobile (redirection)
```

--------------------------------

### Payment URL Generation API Request Example (General Call)

Source: https://developers.portone.io/opi/ko/extra/link-pay/readme-v1

An example JSON payload demonstrating a general request to the Payment URL Generation API, including various payment methods like credit card, Naver Pay, Kakao Pay, and virtual bank accounts.

```json
{
  "payment_info": "{\"title\":\"테스트고객사\",\"user_code\":\"imp68124833\",\"amount\":10000,\"merchant_uid\":\"merchant_1630665784552\",\"name\":\"결제링크 테스트\",\"tax_free\":\"면세공급가액\",\"currency\":\"KRW\",\"language\":\"ko\",\"buyer_name\":\"\",\"buyer_tel\":\"\",\"buyer_addr\":\"\",\"buyer_email\":\"\",\"buyer_postcode\":\"\",\"custom_data\":\"json_object\",\"notice_url\":\"결제 결과를 받을 url\",\"pay_methods\":[{\"pg\":\"INIpayTest\",\"pay_method\":\"card\",\"label\":\"신용/체크카드\"},{\"pg\":\"INIpayTest\",\"pay_method\":\"naverpay\",\"label\":\"네이버페이\"},{\"pg\":\"INIpayTest\",\"pay_method\":\"kakaopay\",\"label\":\"카카오페이\"},{\"pg\":\"INIpayTest\",\"pay_method\":\"phone\",\"label\":\"핸드폰 소액결제\"},{\"pg\":\"INIpayTest\",\"pay_method\":\"trans\",\"label\":\"계좌이체\"},{\"pg\":\"INIpayTest\",\"pay_method\":\"vbank\",\"label\":\"가상계좌\"}]}",
  "expired_at": 1634324016
}
```

--------------------------------

### Update to Latest JavaScript SDK

Source: https://developers.portone.io/opi/ko/integration/pg/v1/smartro-v2/readme

Smartro (new module) payment is a feature only supported by the latest SDK. Ensure your JavaScript SDK is updated to the latest version.

```html
<script src="https://cdn.iamport.kr/v1/iamport.js"></script>
```

--------------------------------

### Service Provision Period Parameters

Source: https://developers.portone.io/opi/ko/integration/pg/v1/welcome/readme

Specifies the duration of service provision, either as a start and end date/time range or a recurring interval, with specific considerations for PC and mobile environments in Welcome Payments.

```APIDOC
period?: object
  Description: Service provision period. Only (from and to) or interval can be entered.
  Notes: For Welcome Payments:
    - PC: Only date can be entered, time is ignored.
    - Mobile: Both date and time can be entered, seconds are ignored.

  from: string
    Description: Service provision start time.
    Formats: YYYY-MM-DD, YYYY-MM-DD HH:mm:ss, YYYYMMDD, YYYYMMDDHHmmss

  to: string
    Description: Service provision end time.
    Formats: YYYY-MM-DD, YYYY-MM-DD HH:mm:ss, YYYYMMDD, YYYYMMDDHHmmss

  interval?: string
    Description: Service provision interval.
    Values:
      - '1m': Monthly recurring payment
      - '1y': Yearly recurring payment
```

--------------------------------

### WelcomeBypassOnMobile API Parameters

Source: https://developers.portone.io/opi/ko/integration/pg/v2/welcome

Defines parameters specific to mobile payment bypass configurations, including options for pre-selecting credit cards and various additional settings to control payment behavior.

```APIDOC
WelcomeBypassOnMobile:
  P_CARD_OPTION?: string
    Description: Option to pre-select a credit card. The card corresponding to the set card code will be displayed as selected.
    Format: selcode=card_code (e.g., selcode=14)
  P_RESERVED?: string[]
    Description: Additional options. Select desired options from the strings below and enter them as an array.
    Options:
      - below1000=Y?: string (For card and easy payments) Option to allow payments under 1,000 KRW.
      - noeasypay=Y?: string (For card payments) Option to hide easy payment methods.
      - global_visa3d=Y?: string Option to display international cards.
      - apprun_check=Y?: string (For Android) Calls intent schema (intent://) instead of custom URL scheme.
```

--------------------------------

### PayPal v2 Bypass: Full Shipping and Payer Address Example (KR)

Source: https://developers.portone.io/opi/ko/integration/pg/v1/spb/warning

Demonstrates how to provide both shipping and payer address information within the `bypass.paypal_v2` object for PayPal payments. This setup enables automatic address completion in the payment UI when the 'same as billing address' checkbox is unchecked, populating the shipping address field.

```json
{
  "bypass": {
    "paypal_v2": {
      "purchase_units": [
        {
          "shipping": {
            "address": {
              "address_line_1": "세종대로 110",
              "address_line_2": "서울특별시청",
              "admin_area_1": "서울특별시",
              "admin_area_2": "중구",
              "postal_code": "04524",
              "country_code": "KR"
            },
            "name": {
              "full_name": "홍길동"
            }
          }
        }
      ],
      "payer": {
        "address": {
          "address_line_1": "고산자로 270",
          "address_line_2": "성동구청",
          "admin_area_1": "서울특별시",
          "admin_area_2": "성동구",
          "postal_code": "04750",
          "country_code": "KR"
        }
      }
    }
  }
}
```

--------------------------------

### Example JSON Configuration for PortOne Payment Parameters

Source: https://developers.portone.io/opi/ko/integration/pg/v1/welcome/readme

This JSON snippet demonstrates how to configure various payment parameters within the PortOne system, including payment window styling, amount restrictions, payment method filtering, and mobile small amount payment defaults. It shows how to pass these settings via the `bypass.welcome.acceptmethod` array.

```json
{
  "channelKey": "{콘솔 내 연동 정보의 채널키}",
  "bypass": {
    "welcome": {
      "acceptmethod": [
        "SKIN(#fc6b2d)",
        "below1000",
        "paypopup",
        "onlyeasypaycode(kakaopay:payco)",
        "hppdefaultcorp(KT)",
        "hppnofix(Y)"
      ]
    }
  }
}
```

--------------------------------

### Access and Utilize Toss Brand Pay Module Instance (Javascript SDK)

Source: https://developers.portone.io/opi/ko/integration/pg/v1/toss-brandpay/module

This snippet illustrates how to load the Toss Brand Pay module and then access the returned `brandpayModule` instance. It shows examples of calling methods like `setupPassword()`, `getPaymentMethods()`, and `openSettings()` on the module instance.

```Javascript
const brandpayModule = await IMP.loadModule(
  "toss-brandpay",
  {
    userCode: "imp00000000", //// 관리자 콘솔 - 결제 연동 페이지에서 확인 가능합니다.
  },
  {
    customerKey: "d005f081-830a-4b9c-b5e2-73e56fbe6ac3",
    loadBrandpayOptions: {
      ui: {
        buttonStyle: "default",
        highlightColor: "#3182f6",
        navigationBar: {
          visible: true,
          paddingTop: 10
        },
        labels: {
          oneTouchPay: "원터치결제"
        }
      }
    }
  }
);

brandpayModule.setupPassword();
brandpayModule.getPaymentMethods();
brandpayModule.openSettings();
```

--------------------------------

### Schedule Recurring Payments via PortOne API

Source: https://developers.portone.io/opi/ko/integration/pg/v2/ksnet

This example demonstrates how to schedule a recurring payment using the PortOne API. It makes an `axios` POST request to `/payments/{UNIQUE_PAYMENT_ID}/schedule`, including the `billing_key`, order details, customer information, amount, currency, and the `timeToPay` for the scheduled transaction.

```ts
async function schedulePayment() {
  // 포트원 결제 예약 API 호출
  const response = await axios({
    url: `https://api.portone.io/payments/${encodeURIComponent(UNIQUE_PAYMENT_ID)}/schedule`,
    method: "post",
    headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` },
    data: {
      payment: {
        billing_key: BILLING_KEY_HERE,
        orderName: "월간 이용권 정기결제",
        customer: {
          id: CUSTOMER_ID_HERE,
          // 고객 정보가 필요한 경우 API 명세에 따라 추가해주세요.
        },
        amount: {
          total: 8900,
        },
        currency: "KRW",
      },
      timeToPay: "2023-08-24T14:15:22Z", // 결제를 시도할 시각
    },
  });
  // 결제 예약 이후 로직을 구성해주세요.
}
```

--------------------------------

### Configure windowType Parameter for PortOne SDK Payments

Source: https://developers.portone.io/opi/ko/integration/pg/v2/ksnet

This parameter controls the payment window display type. For KSNET, PC supports `IFRAME` and mobile supports `REDIRECTION` only; other types will result in an error. If left unspecified, the system defaults to `IFRAME` for PC and `REDIRECTION` for mobile, as shown in the example JSON.

```APIDOC
windowType?: string
  - KSNET의 경우 PC는 `IFRAME`, mobile은 `REDIRECTION`만 지원되며 이외의 다른 방식으로 결제창을 호출할 경우 에러를 리턴합니다.
  - `windowType` 파라미터를 채우지 않을 경우 자동으로 아래와 같이 세팅됩니다.
```

```json
{
  "pc": "IFRAME",
  "mobile": "REDIRECTION"
}
```

--------------------------------

### API Reference: brandpayModule.setupPassword() Method

Source: https://developers.portone.io/opi/ko/integration/pg/v1/toss-brandpay/module

Documentation for the `setupPassword` method, which allows users to set or change their payment password. The Promise resolves upon completion.

```APIDOC
brandpayModule.setupPassword()
  Description: Sets or changes the payment password. The Promise resolves when the operation is complete.
  Returns: Promise<void>
  Errors:
    USER_CANCEL: User closed the window.
```

--------------------------------

### Configure Card Installment Months

Source: https://developers.portone.io/opi/ko/integration/pg/v1/inicis

This configuration allows you to specify which installment months are available for card payments. The `card_quota` array defines the allowed months. An empty array means only one-time payment is possible, while specific numbers allow those installment periods. Note that installment payments are only available for transactions over 50,000 KRW.

```json
{
  "display": {
    "card_quota": [6]
  }
}
```

```APIDOC
display?: object - Settings for card installment months to be rendered on the payment window.
  card_quota: number[] - Installment months.
    Examples:
      []: Only one-time payment possible.
      [2,3,4,5,6]: Installment selection possible up to 2, 3, 4, 5, 6 months, including one-time payment.
      [3]: Installment selection possible up to 2, 3 months, including one-time payment.
```

--------------------------------

### Configure Merchant-Funded Interest-Free Installments

Source: https://developers.portone.io/opi/ko/integration/pg/v1/inicis

This setting allows you to configure merchant-funded interest-free installments. Before using this feature, you must coordinate with KG Inicis, and their configuration must be completed first. Once set up, you can specify the maximum number of months for which all cards will offer merchant-funded interest-free installments.

```json
{
  "card": {
    "interest_free": 7
  }
}
```

```APIDOC
card?: object
  interest_free: number - The maximum number of months for which all cards will offer merchant-funded interest-free installments.
```

--------------------------------

### Period Parameter Usage and Supported Intervals

Source: https://developers.portone.io/opi/ko/integration/pg/v1/welcome/caution

This section illustrates the correct usage of the `period` parameter, including date formatting for different environments (PC vs. mobile) and the specific `interval` values supported by Welcome Payments. It shows examples for supported intervals ('1m', '1y') and an unsupported interval ('1d') that results in an error.

```json
{
  "period": { "from": "2023-01-01 00:00:00", "to": "2023-03-01 23:59:59" }
}
```

```json
// 옵션1. interval을 1m로 설정
{
  "period": { "interval": "1m" }
}
```

```json
// 옵션2. interval을 1y로 설정
{
  "period": { "interval": "1y" }
}
```

```json
// 옵션 3. interval을 1d로 설정
{
  "period": { "interval": "1d" }
}
```

--------------------------------

### Example Shortened URL for Deactivation

Source: https://developers.portone.io/opi/ko/extra/link-pay/readme-v1

An example of the `shortenedUrl` format returned by the generation API, illustrating the unique string that should be used for deactivation.

```json
{
  "shortenedUrl": "https://impay.link/4bdf239e"
}
```

--------------------------------

### PortOne SDK Payment Request with Promotion and Card Direct Call

Source: https://developers.portone.io/opi/ko/extra/promotion/integration

Demonstrates how to initiate a payment using the PortOne SDK's `requestPayment` method. This example includes parameters for store identification, applying a specific promotion, directly specifying card company for payment, and setting general payment details like order name, amount, currency, and customer information. It highlights the use of `promotionId` and `card.cardCompany` for promotional discounts.

```tsx
//포트원 인증결제 SDK 호출
PortOne.requestPayment({
  storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec",
  promotionId: "promotion-id-86e1ff2a-2c3a-451c-bdd3-e5cd1664bc3e", //적용할 프로모션 아이디 입력 (Ex. 현대카드 프로모션)
  //카드 다이렉트 호출
  card: {
    cardCompany: "HYUNDAI_CARD"
  },
  //기타 인증결제 파라미터 설정
  channelKey: "channel-key-f042e8e2-92f1-4f68-ad61-cec6ede41529",
  paymentId: `payment-${crypto.randomUUID()}`,
  orderName: "나이키 와플 트레이너 2 SD",
  totalAmount: 1000,
  currency: "CURRENCY_KRW",
  payMethod: "CARD",
  customer: {
    fullName: "홍길동",
    phoneNumber: "010-1234-5678",
    email: "test@test.com"
  }
});
```

--------------------------------

### PayPal Payment Parameters Reference

Source: https://developers.portone.io/opi/ko/integration/pg/v1/spb/warning

Detailed documentation for various parameters used when calling the IMP.loadUI function for PayPal payments. This includes their types, descriptions, and specific usage notes such as formatting requirements, display behavior, and validation rules.

```APIDOC
name?: string
  Description: Order name. Displayed only for non-member payments in the payment window. Not shown for member payments.
pay_method: 'paypal'
  Description: Must be 'paypal'. Inputting any other value will result in an error message and prevent the payment window from being called. Regardless of the actual payment instrument used (e.g., card, bank account), the payment method will always be saved as 'paypal' because PayPal uniformly responds with 'paypal'.
buyer_tel?: string
  Description: Buyer's mobile phone number. Must be entered in E164 format (e.g., for a Korean user with 01012345678, enter 821012345678). The entered phone number will be automatically filled in the contact information for non-member PayPal payments. If the phone number format does not match the accessing country's format, it will be ignored (not auto-completed).
products?: object[]
  Description: Detailed purchase item information. Only 'name' (product name), 'quantity' (product quantity), and 'unitPrice' (product unit price) from the provided values will be displayed in the payment window. PayPal strongly recommends inputting this parameter.
  Constraint: The total sum of (quantity * unitPrice) for each product must exactly match the total order amount. If they do not match, an error message will be returned, and the payment window will not be called.
currency?: string
  Description: Payment currency. Only currencies supported by PayPal can be used. Attempting to pay with an unsupported currency will result in an error message and prevent the payment window from being called. Occasionally, available currencies may be determined by the accessing country or payment method; inputting an unavailable currency in such cases will also result in an error.
digital?: boolean
  Description: For content product sales, the presence of the shipping address input field depends on the value of the 'digital' parameter. If 'digital' is 'false', the shipping address input field is shown. If 'digital' is 'true', the shipping address input field is hidden.
buyer_first_name?: string
buyer_last_name?: string
```

--------------------------------

### Payment URL Generation API Request Example (Direct PG Call)

Source: https://developers.portone.io/opi/ko/extra/link-pay/readme-v1

An example JSON payload for generating a payment URL with a direct call to a specific Payment Gateway (PG), such as Toss Payments, for a card payment.

```json
{
  "payment_info": "{\"title\":\"테스트고객사\",\"user_code\":\"imp68124833\",\"amount\":1000,\"merchant_uid\":\"merchant_16306657845522\",\"name\":\"결제링크 테스트\",\"tax_free\":\"면세공급가액\",\"currency\":\"KRW\",\"language\":\"ko\",\"buyer_name\":\"\",\"buyer_tel\":\"\",\"buyer_addr\":\"\",\"buyer_email\":\"\",\"direct\":{\"pg\":\"tosspayments\",\"pay_method\":\"card\"}}",
  "expired_at": 1634324016
}
```

--------------------------------

### Request SDK Payment with PortOne for KSNET

Source: https://developers.portone.io/opi/ko/integration/pg/v2/ksnet

This snippet demonstrates how to initiate an SDK payment request using the PortOne browser SDK. It shows how to call `PortOne.requestPayment` with essential parameters like `storeId`, `paymentId`, `orderName`, `totalAmount`, `currency`, and crucially, `channelKey` to specify KSNET integration. It also includes `payMethod` and `card` details.

```ts
import * as PortOne from "@portone/browser-sdk/v2";
function requestPayment() {
  PortOne.requestPayment({
    storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", // 고객사 storeId로 변경해주세요.
    paymentId: `payment-${crypto.randomUUID()}`,
    orderName: "나이키 와플 트레이너 2 SD",
    totalAmount: 1000,
    currency: "CURRENCY_KRW",
    channelKey: "channel-key-9987cb87-6458-4888-b94e-68d9a2da896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요.
    payMethod: "CARD",
    card: {
      cardCompany: "BC_CARD",
    },
  });
}
```

--------------------------------

### PortOne Order Transfer API Response Example

Source: https://developers.portone.io/platform/ko/usages/order

An example JSON response structure for a successful PortOne order transfer. It details the `transfer` object, including `amount` breakdowns, `payment` details, and `orderLines` with per-product settlement information.

```json
{
  "transfer": {
    "type": "ORDER",
    "id": "01H7MCX58SGYCNVN1CWY3HXM6D",
    "graphqlId": "NjowMUg3TUNYNThTR1lDTlZOMUNXWTNIWE02RA==",
    "partner": {
      // 파트너 정보 생략
    },
    "status": "IN_PROCESS",
    "settlementDate": "2023-08-31",
    "settlementCurrency": "KRW",
    "isForTest": false,
    "amount": {
      // 전체 주문건에 대한 정산정보
      "settlement": 12460, // 전체 주문건에 대한 정산 금액
      "payment": 14000,
      "order": 14000,
      "platformFee": 1400,
      "platformFeeVat": 140,
      "additionalFee": 0,
      "additionalFeeVat": 0,
      "discount": 0,
      "discountShare": 0
    },
    "contract": {
      //계약 정보 생략
    },
    "payment": {
      "id": "payment_1",
      "orderName": "string",
      "currency": "KRW",
      "method": { "card": {} },
      "paidAt": "2023-08-11T08:21:01.241Z"
    },
    "settlementStartDate": "2023-08-11",
    "orderLines": [
      // 상품별 주문 및 정산정보
      {
        "product": {
          "id": "product_A",
          "name": "상품 A",
          "amount": 2000,
          "tag": "과일"
        },
        "quantity": 5,
        "discounts": [],
        "additionalFees": [],
        "amount": {
          //상품 별 정산정보. 참고로 전체 주문에대한 할인 및 추가수수료 정보는 전체 주문건에 대한 정산정보에 포함됩니다。
          "settlement": 8900,
          "payment": 10000,
          "order": 10000,
          "platformFee": 1000,
          "platformFeeVat": 100,
          "additionalFee": 0,
          "additionalFeeVat": 0,
          "discount": 0,
          "discountShare": 0
        }
      },
      {
        "product": {
          "id": "product_B",
          "name": "상품 B",
          "amount": 4000,
          "tag": "과일"
        },
        "quantity": 1,
        "discounts": [],
        "additionalFees": [],
        "amount": {
          "settlement": 3560,
          "payment": 4000,
          "order": 4000,
          "platformFee": 400,
          "platformFeeVat": 40,
          "additionalFee": 0,
          "additionalFeeVat": 0,
          "discount": 0,
          "discountShare": 0
        }
      }
    ],
    "additionalFees": [], //전체 주문건에 대한 추가수수료 정보
    "discounts": [] //전체 주문건에 대한 할인 정보
  }
}
```

--------------------------------

### PortOne Order Cancellation Settlement API Response Example

Source: https://developers.portone.io/platform/ko/usages/order

An example of the JSON response received after successfully requesting an order cancellation settlement. It outlines the structure of the 'transfer' object, including settlement amounts, payment details, and cancellation information.

```json
{
  "transfer": {
    "type": "ORDER_CANCEL",
    "id": "01H7J87XQ4JAS28RWZBC29YCJ1",
    "graphqlId": "NjowMUg3Sjg3WFE0SkFTMjhSV1pCQzI5WUNKMQ==",
    "partner": {},
    "status": "SCHEDULED",
    "settlementDate": "2023-08-3",
    "settlementCurrency": "KRW",
    "isForTest": false,
    "amount": {
      "settlement": 3560,
      "payment": 4000,
      "order": 4000,
      "platformFee": 400,
      "platformFeeVat": 40,
      "additionalFee": 0,
      "additionalFeeVat": 0,
      "discount": 0,
      "discountShare": 0
    },
    "contract": {},
    "payment": {
      "id": "payment_1",
      "orderName": "string",
      "currency": "KRW",
      "method": {
        "card": {}
      },
      "paidAt": "2023-08-11T08:21:01.241Z"
    }
  },
  "settlementStartDate": "2023-08-12",
  "orderLines": [],
  "additionalFees": [],
  "discounts": [],
  "cancellation": {
    "id": "cancellation_1",
    "cancelledAt": "2023-08-12T11:57:15.292Z"
  }
}
```

--------------------------------

### Perform API Manual (Key-in) Payment via PortOne

Source: https://developers.portone.io/opi/ko/integration/pg/v2/ksnet

This code illustrates how to make a manual (key-in) payment using the PortOne API. It uses an `axios` POST request to `/payments/{PAYMENT_ID_HERE}/instant` with authorization and various payment details, including customer information, amount, currency, and card credentials.

```ts
// ... 수기(키인) 결제
const issueResponse = await axios({
  url: `https://api.portone.io/payments/${encodeURIComponent(PAYMENT_ID_HERE)}/instant`,
  method: "post",
  headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` },
  data: {
    channelKey,
    orderName,
    productType,
    customer: {
      id: customerId,
      name: {
        first: firstName,
        last: lastName,
      },
    },
    amount: {
      total: totalAmount,
    },
    currency,
    method: {
      card: {
        credential: {
          number: cardNumber,
          expiryYear,
          expiryMonth,
          birthOrBusinessRegistrationNumber,
          passwordTwoDigits,
        },
      },
    },
  },
});
```

--------------------------------

### Initiate Authenticated Payment with PortOne SDK (TypeScript)

Source: https://developers.portone.io/opi/ko/integration/pg/v1/newtoss/readme

This TypeScript code snippet demonstrates how to initiate an authenticated payment using the PortOne SDK's `IMP.request_pay` function. It includes various parameters for payment details, buyer information, and callback handling. The `channelKey` is used for PG configuration, replacing the deprecated `pg` parameter.

```ts
const userCode = "고객사 식별코드";
IMP.init(userCode); // 고객사 식별 코드를 넣어 모듈을 초기화해주세요.

IMP.request_pay(
  {
    channelKey: "{콘솔 내 연동 정보의 채널키}",
    merchant_uid: "order_id_1667634130160",
    name: "나이키 와플 트레이너 2 SD",
    pay_method: "card",
    escrow: false,
    amount: "109000",
    tax_free: 3000,
    buyer_name: "홍길동",
    buyer_email: "buyer@example.com",
    buyer_tel: "02-1670-5176",
    buyer_addr: "성수이로 20길 16",
    buyer_postcode: "04783",
    m_redirect_url: "https://helloworld.com/payments/result", // 모바일 환경에서 필수 입력
    notice_url: "https://helloworld.com/api/v1/payments/notice",
    confirm_url: "https://helloworld.com/api/v1/payments/confirm",
    currency: "KRW",
    locale: "ko",
    custom_data: { userId: 30930 },
    display: { card_quota: [0, 6] },
    appCard: false,
    useCardPoint: true,
    bypass: {
      tosspayments: {
        useInternationalCardOnly: true // 영어 결제창 활성화
      }
    }
  },
  (response) => {
    // PC 환경에서 결제 프로세스 완료 후 실행 될 로직
  }
);
```