diff --git a/src/content/docs/ko/ready/_components/integration-guide/kcp-v2.mdx b/src/content/docs/ko/ready/_components/integration-guide/kcp-v2.mdx index 27944db40..e603050ca 100644 --- a/src/content/docs/ko/ready/_components/integration-guide/kcp-v2.mdx +++ b/src/content/docs/ko/ready/_components/integration-guide/kcp-v2.mdx @@ -1,4 +1,5 @@ import Figure from '~/components/Figure.astro'; +import Hint from "~/components/Hint.astro"; import * as prose from '~/components/prose'; import image1 from "./assets/kcp-v2.png"; @@ -10,6 +11,18 @@ import image6 from "./assets/kcp5.png"; export const components = prose; + + + 포트원 V2에서 제공하는 KCP의 경우 **KCP의 PG-API방식**만 지원합니다. 따라서 아래와 같이 인증서 발급 후 + 사용할 수 있습니다. + + 해당 인증서의 경우 유효기간은 **5년**이며, 유효기간 만료 30일전부터 갱신이 가능합니다. + + **서비스 인증서의 유효기간이 만료되거나 폐기된 경우** 즉시 결제 승인/취소 등 관련 + **서비스 이용이 불가능**하오니 + 서비스 사용을 위해서 인증서를 재발급이 필요한 후 **포트원에 저장된 채널 정보를 업데이트** 해야 합니다. + + 1. [KCP 파트너관리자](https://partner.kcp.co.kr/) 접속 후 로그인을 합니다. 2. \[고객센터]→\[인증센터]→\[KCP PG-API]를 클릭합니다. diff --git a/src/content/docs/ko/v2-payment/pg/kcp-v2.mdx b/src/content/docs/ko/v2-payment/pg/kcp-v2.mdx index 0fcb78123..707ed7725 100644 --- a/src/content/docs/ko/v2-payment/pg/kcp-v2.mdx +++ b/src/content/docs/ko/v2-payment/pg/kcp-v2.mdx @@ -129,7 +129,7 @@ KCP 기준으로 작성한 예시 코드는 아래와 같습니다. **채널 키** - 포트원 콘솔 내 \[결제연동] > \[채널관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다. + 포트원 콘솔 내 \[연동 관리] > \[연동 정보] > \[채널 관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다. - `totalAmount` **\*** **number** @@ -200,33 +200,35 @@ KCP 기준으로 작성한 예시 코드는 아래와 같습니다. - `skin_indx` **integer** - **결제창 색상 변경 파라미터** + **결제창 색상** - - PC 결제창의 색상을 변경합니다. + - PC로 결제창 호출 시 결제창 색상을 변경합니다. - 1\~12까지 설정 가능합니다. - `kcp_pay_title` **string** - **결제창 상단 문구 변경 파라미터** + **결제창 상단 문구** - 결제창의 상단 문구를 변경합니다. - `shop_user_id` **string** - **기관에 따라 리스크 관리 조치를 위한 쇼핑몰 관리 ID 파라미터** + **기관에 따라 리스크 관리 조치를 위한 쇼핑몰 관리 ID** - 상품권, 휴대폰 결제 시 필수로 입력해야 합니다. - `site_name` **string** - **카드사 다이렉트 호출 시 결제창에 표기될 고객사 상호명** + **카드사 다이렉트 호출 시 결제창에 표기될 상호명** - - PC의 경우 안심클릭(V3D)카드사인 신한, 현대, 삼성, 농협, 하나, 외환, 롯데, 씨티, 우리카드사에 대해 다이렉트 호출 시 필수인 파라미터 입니다. - - 모바일의 경우 필수로 입력되어야 하는 파라미터 입니다. + - PC의 경우 신한, 현대, 삼성, 농협, 하나, 외환, 롯데, 씨티, 우리카드사에 대해 다이렉트 호출 시 필수로 입력해야 합니다. + - 모바일의 경우 필수로 입력해야 합니다. - `disp_tax_yn` **string** + **결제창 현금영수증 노출 여부** - - 결제창에서 현금영수증 노출 여부를 정하는 파라미터 입니다. 결제수단이 계좌이체, 가상계좌인 경우에만 유효합니다. + + - 결제창에서 현금영수증 노출 여부를 설정할 수 있습니다. 실시간 계좌이체 또는 가상계좌 결제 시 사용할 수 있습니다. - `Y`: 노출 - `N`: 노출하지 않음 - `R`: 소득공제로 노출 @@ -236,59 +238,61 @@ KCP 기준으로 작성한 예시 코드는 아래와 같습니다. **에스크로 결제 예상 배송 소요일** - - 에스크로 결제 시, 결제 상품의 예상 배송 소요일입니다. KCP에서 에스크로 결제 시 입력 권장하는 필드이며, 미입력 시 '00'으로 입력됩니다. - 입력 형식은 두 자리 수로 입력 되어야 합니다. ex. 예상 배송 소요기간이 3일인 경우,'03'으로 입력 + - 에스크로 결제 시, 결제 상품의 예상 배송 소요일입니다. KCP측에서 에스크로 결제 사용 시 입력을 권장하고 있습니다. + - 미입력 시 '00'으로 입력됩니다. + - 입력 형식은 두 자리 수로 입력되어야 합니다. ex. 예상 배송 소요기간이 3일인 경우,`03`으로 입력 - - - **bypass 예시 코드** - - ```json - { - "bypass": { - "kcp_v2": { - "site_logo": "https://portone.io/assets/portone.jpg", - "skin_indx": 6, - "shop_user_id": "user_id1", - "site_name": "포트원 고객사" - } - } - } - ``` +#### 예제 + +```json title="bypass 파라미터 예시" +{ + "bypass": { + "kcp_v2": { + "site_logo": "https://portone.io/assets/portone.jpg", + "skin_indx": 6, + "shop_user_id": "user_id1", + "site_name": "포트원 고객사" + } + } +} +``` + ### SDK 결제 - 유의사항 #### 공통
-

`paymentId` 에는 영문/숫자만 허용됩니다.

+

`paymentId` 파라미터 내 한글, 특수문자 미지원

- `paymentId` 에는 영문/숫자만 허용됩니다. - - 한글이나 특수 문자는 허용되지 않습니다. + `paymentId` 에는 영문/숫자만 사용할 수 있습니다. 한글이나 특수 문자가 포함된 채 결제를 요청하는 경우 + 결제 실패가 발생하오니 유의하시기 바랍니다.
-

지원되는 결제창 언어

+

결제창 표시 언어 지원 안내

- SDK를 통한 결제 요청 파라미터에는 결제창 언어를 지정할 수 있는 `locale` 파라미터가 존재합니다. - PC, 모바일 결제에서 `KO_KR`, `EN_US`를 지원합니다. + SDK를 통한 결제 요청 시 `locale` 파라미터를 이용하여 결제창 언어를 변경할 수 있으며, PC 및 모바일 환경 모두 + 한국어(`KO_KR`) 및 영어(`EN_US`)를 지원합니다. + 미입력 시 자동으로 한국어로 표시됩니다.
-

지원되는 결제 통화

+

결제 통화 지원 안내

- SDK를 통한 결제 요청 파라미터에는 결제 통화를 지정할 수 있는 `currency` 파라미터가 존재합니다. - KCP의 경우 `KRW`와 `USD`를 지원하며, 이 중 `USD`는 카드 결제일 경우에만 지정 가능합니다. + SDK를 통한 결제 요청 시 `currency` 파라미터를 이용하여 결제 통화를 지정할 수 있으며, KCP에서는 + `KRW`와 `USD`만 지원됩니다. 단, `USD`는 카드 결제일 경우에만 지정 가능합니다.

부가세, 면세금액 직접 지정을 위해서는 별도 계약이 필요합니다.

- SDK를 통한 결제 요청 파라미터에는 부가세를 지정할 수 있는 `vat` 파라미터와 면세 금액을 지정할 수 있는 `taxFreeAmount` 파라미터가 존재합니다. - KCP의 경우 부가세 및 면세금액을 직접 지정하기 위해서는 별도 계약이 필요합니다. 별도 계약이 되지 않은 상태에서 `vat`와 `taxFreeAmount`에 값을 지정해 결제를 요청하면 - 요청한 내용과 다른 금액으로 실결제가 발생할 수 있습니다. + SDK를 통한 결제 요청 시 면세 금액(`taxFreeAmount`) 와 부가세(`vatAmount`) 파라미터를 이용하여 면세금액과 부가세를 + 직접 지정할 수 있습니다. 다만 직접 지정하여 사용하기 위해서는 사전에 KCP와 별도로 계약을 진행해야 합니다. + 별도로 계약을 진행하지 않은 상태에서 해당 파라미터에 값을 지정하여 결제를 요청하는 경우 요청한 내용과 다른 금액으로 + 실결제가 발생할 수 있습니다.
@@ -302,37 +306,76 @@ KCP 기준으로 작성한 예시 코드는 아래와 같습니다. #### 카드 결제
-

카드사 다이렉트 호출 시 할부 개월 수 옵션은 고정 할부 개월 수만 지원합니다.

+

카드사 다이렉트 호출 시 고정 할부 개월 수만 설정할 수 있습니다.

- KCP의 경우 **카드사 다이렉트 호출 시 할부 개월 수 옵션은** 고정 할부 개월 수만 지원합니다. 카드사 다이렉트 호출을 설정했으나 할부 개월 수 옵션을 `card.installment.monthOption.fixedMonth` 가 아닌 + KCP의 경우 카드사 다이렉트 호출 시 **고정 할부 개월 수**만 설정 가능합니다. + 카드사 다이렉트 호출 시 할부 개월 수 옵션을 `card.installment.monthOption.fixedMonth` 가 아닌 `card.installment.monthOption.availableMonthList`로 설정할 경우 에러가 발생합니다.

카드사 다이렉트 호출 시 지원하는 카드사 종류

- KCP의 경우 다음 카드사들을 다이렉트 카드사로 지원합니다. - - - V3D(안심클릭) 카드사: 신한, 현대, 삼성, 농협, 하나, 외환, 롯데, 씨티, 우리 - - ISP(안전결제) 카드사: 우체국, 광주, 새마을금고, 수협, 제주은행, 신협, 저축은행, KDB산업은행, 비씨, 국민 + 아래 카드사는 다이렉트 호출이 가능합니다. + + - 신한카드 + - 현대카드 + - 삼성카드 + - 농협카드 + - 하나카드 + - 롯데카드 + - 씨티카드 + - 우리카드 + - 비씨카드 + - 국민카드 + - 우체국은행 카드 + - 광주은행 카드 + - 새마을금고 카드 + - 수협은행 카드 + - 제주은행 카드 + - 신협 카드 + - 저축은행 카드 + - KDB산업은행 카드
-

KCP에서 지원하지 않는 카드 관련 파라미터

+

미지원 카드 관련 파라미터 안내

KCP의 경우 아래 파라미터들을 지원하지 않으며, 해당 파라미터들을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. - - `useCardPoint`: 카드 포인트 사용 여부.(KCP의 경우 지정하지 않아도 카드 포인트를 사용 가능합니다.) - - `useInstallment`: 할부 사용 여부. (KCP의 경우 `installment` 파라미터로 직접 설정 가능합니다.) - - `useFreeInterestFromMall`: 상점부담무이자 사용 여부. (KCP의 경우 `installment.freeInstallmentPlans` 파라미터로 직접 설정 가능합니다.) + - `useCardPoint`: 카드 포인트 사용 여부. + - KCP의 경우 지정하지 않아도 카드 포인트를 사용 가능합니다. + + - `useInstallment`: 할부 사용 여부. + - KCP의 경우 `installment` 파라미터로 직접 설정 가능합니다. + + - `useFreeInterestFromMall`: 상점부담무이자 사용 여부. + - KCP의 경우 `installment.freeInstallmentPlans` 파라미터로 직접 설정 가능합니다. +
+ +
+

일부 카드사에 한하여 다이렉트 호출 시 필수 파라미터 안내

+ + PC 환경에서 카드사 다이렉트 결제 요청 시, 다음 카드사들의 경우 `bypass.kcp_v2.site_name`을 필수로 입력해야 합니다. + + - 신한카드 + - 우리카드 + - 현대카드 + - 삼성카드 + - 농협카드 + - 하나카드 + - 롯데카드 + - 씨티카드 + + 모바일 환경에서 카드사 다이렉트 결제 요청 시, 고객사 상호명 파라미터인 `bypass.kcp_v2.site_name`을 필수로 입력해야 합니다.
#### 간편 결제
-

KCP에서 지원하는 간편결제사 종류

+

간편결제 허브형 지원 안내

- KCP의 경우 아래 간편결제사를 지원합니다. `easyPay.easyPayProvider` 파라미터에 아래 리스트 중 원하는 값을 입력하세요. + KCP의 경우 아래 간편결제 허브형을 지원합니다. `easyPay.easyPayProvider` 파라미터에 아래 리스트 중 원하는 값을 입력하세요. - 카카오페이: `KAKAOPAY` - 네이버페이: `NAVERPAY` @@ -345,22 +388,29 @@ KCP 기준으로 작성한 예시 코드는 아래와 같습니다.
-

KCP에서 지원하지 않는 간편결제 관련 파라미터

+

미지원 간편결제 관련 파라미터 안내

KCP의 경우 아래 파라미터들을 지원하지 않으며, 해당 파라미터들을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. - `useCardPoint`: 카드사 포인트 사용 여부 + - `customerIdentifier`: 현금영수증 발행 대상 식별 정보 + - `availablePayMethod`: 간편결제 세부 결제수단 지정 렌더링 옵션 + - `availableCards`: 결제 수단으로써 사용 허가할 카드사 리스트 - - `useInstallment`: 할부 사용 여부. (KCP의 경우 `installment` 파라미터로 직접 설정 가능합니다.) - - `useFreeInterestFromMall`: 상점부담무이자 사용 여부. (KCP의 경우 `installment.freeInstallmentPlans` 파라미터로 직접 설정 가능합니다.) + + - `useInstallment`: 할부 사용 여부. + - KCP의 경우 `installment` 파라미터로 직접 설정 가능합니다. + + - `useFreeInterestFromMall`: 상점부담무이자 사용 여부. + - KCP의 경우 `installment.freeInstallmentPlans` 파라미터로 직접 설정 가능합니다.
#### 계좌이체
-

KCP에서 지원하지 않는 계좌이체 관련 파라미터

+

미지원 계좌이체 관련 파라미터 안내

KCP의 경우 아래 파라미터들을 지원하지 않으며, 해당 파라미터들을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. @@ -371,7 +421,7 @@ KCP 기준으로 작성한 예시 코드는 아래와 같습니다. #### 가상계좌 결제
-

KCP에서 지원하지 않는 가상계좌 관련 파라미터

+

미지원 가상계좌 관련 파라미터 안내

KCP의 경우 아래 파라미터들을 지원하지 않으며, 해당 파라미터들을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. @@ -383,7 +433,7 @@ KCP 기준으로 작성한 예시 코드는 아래와 같습니다. #### 상품권 결제
-

KCP에서 지원하는 상품권 종류 및 필수 여부

+

상품권 지원 안내

KCP PC, 모바일 결제에서 `giftCertificateType`는 선택 사항입니다. 결제에서 해당 파라미터를 입력하지 않을 경우 결제창 내에서 상품권 종류를 선택할 수 있습니다. KCP에서 지원하는 상품권 종류는 아래와 같습니다. @@ -394,9 +444,9 @@ KCP 기준으로 작성한 예시 코드는 아래와 같습니다.
-

bypass.kcp\_v2.shop\_user\_id 필수 입력

+

상품권 또는 휴대폰 결제 시 필수 파라미터 안내

- KCP 에서 상품권, 휴대폰 결제 시 리스크 관리를 위해 고객사 회원의 ID를 필수로 받고 있어, + KCP에서 상품권, 휴대폰 결제 시 리스크 관리를 위해 고객사 회원의 ID를 필수로 받고 있어, `bypass.kcp_v2.shop_user_id`를 필수로 입력하셔야 합니다.
@@ -405,46 +455,26 @@ KCP 기준으로 작성한 예시 코드는 아래와 같습니다.

결제창에 노출될 통신사 지정 옵션 지원 여부

- KCP 모바일 결제의 경우 하나의 통신사 지정만 가능해 `availableCarriers` 를 지원하지 않습니다.\ + KCP 모바일 결제의 경우 하나의 통신사만 지정할 수 있으며 `availableCarriers`를 사용할 수 없습니다. 통신사 구분 값을 위한 `carrier`만 사용이 가능합니다.
-
-

`bypass.kcp_v2.shop_user_id` 필수 입력

- - KCP 에서 상품권, 휴대폰 결제 시 리스크 관리를 위해 고객사 회원의 ID를 필수로 받고 있어, - `bypass.kcp_v2.shop_user_id`를 필수로 입력하셔야 합니다. -
- #### 에스크로 결제
-

에스크로 결제 시 필수 입력 파라미터

+

에스크로 결제 시 필수 파라미터 안내

- KCP 에스크로 결제 시 `products` 파라미터를 필수로 요구합니다. - 구매 상품의 정보를 담아 products 리스트에 하나 이상의 상품 정보가 포함되어야 합니다. + KCP 에스크로 결제 시 `products` 파라미터를 필수로 요구합니다. + 구매 상품의 정보를 담아 `products` 리스트에 하나 이상의 상품 정보가 포함되어야 합니다.
-
-

예상 배송 소요일 파라미터 `bypass.kcp_v2.deli_term` 입력 권장

- KCP에서 에스크로 결제 시 예상 배송 소요일인 `bypass.kcp_v2.deli_term`을 입력 권장하고 있습니다. - 입력 형식은 두 자리 수로 입력 되어야 합니다. ex. 예상 배송 소요기간이 3일인 경우,'03'으로 입력 - 정확한 소요일을 알 수 없어 미입력 시 '00'으로 입력됩니다. - -
- -#### 카드사 다이렉트 결제
-

PC 카드사 다이렉트 안심클릭(V3D) 카드사로 결제 시 `bypass.kcp_v2.site_name`필수 입력

- - KCP에서 PC 카드사 다이렉트 결제 시, 안심클릭(V3D) 카드사인 다음 카드사들로 결제하시는 경우에, `bypass.kcp_v2.site_name`을 필수로 입력하셔야 합니다. +

에스크로 결제 시 입력 권장 파라미터 안내

- - V3D(안심클릭) 카드사: 신한, 현대, 삼성, 농협, 하나, 외환, 롯데, 씨티, 우리 -
-
-

모바일 카드사 다이렉트 결제 시 `bypass.kcp_v2.site_name`필수 입력

+ KCP에서 에스크로 결제 시 예상 배송 소요일인 `bypass.kcp_v2.deli_term`을 입력을 권장하고 있습니다. + 입력 형식은 두 자리 수로 입력 되어야 합니다. ex. 예상 배송 소요기간이 3일인 경우,'03'으로 입력 + 정확한 소요일을 알 수 없어 미입력 시 '00'으로 입력됩니다. - KCP에서 모바일 카드사 다이렉트 결제 시, 고객사 상호명 파라미터인 `bypass.kcp_v2.site_name`을 필수로 입력하셔야 합니다.
## SDK 빌링키 발급 요청하기 @@ -491,7 +521,7 @@ KCP 기준으로 작성한 예시 코드는 아래와 같습니다. **채널 키** - 포트원 콘솔 내 \[결제연동] > \[채널관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다. + 포트원 콘솔 내 \[연동 관리] > \[연동 정보] > \[채널 관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다. - `billingKeyMethod` **\*** **string** @@ -565,14 +595,14 @@ KCP 기준으로 작성한 예시 코드는 아래와 같습니다. ### SDK 빌링키 발급 - 유의사항
-

`offerPeriod` 파라미터 제약 사항

+

파라미터 제약 사항

- SDK를 통한 빌링키 발급 요청 파라미터에는 제공 기간을 나타내는 `offerPeriod` 파라미터가 존재합니다. - 빌링키 발급의 경우 간격을 입력하는 방식(`interval`)만 지원 합니다. + SDK를 통한 빌링키 발급 요청 `offerPeriod` 파라미터를 이용하여 제공 기간을 나타낼 수 있으며, 빌링키 발급 시 + `interval`파라미터만 지원됩니다.
-

카드사 다이렉트 호출을 지원하지 않습니다.

+

카드사 다이렉트 호출 미지원 안내

KCP 경우 카드사 다이렉트 호출을 통한 빌링키 발급을 지원하지 않습니다. `card.cardCompany` 필드에 값을 채워도 빌링키 발급 동작에 아무런 영향을 미치지 않습니다. @@ -580,38 +610,49 @@ KCP 기준으로 작성한 예시 코드는 아래와 같습니다. ## API 수기(키인)결제 요청하기 -수기(키인)로 결제하기 위해서는 `POST /payments/${PAYMENT_ID_HERE}/instant` API를 호출합니다. - -카드 수기 결제 관련 유의 사항은 다음과 같습니다. - -- 카드 번호, 유효 기간 년/월, 생년월일 또는 사업자등록번호, 카드 비밀번호 앞 두 자리 파라미터를 모두 입력해야 합니다. -- 카드 할부 개월 수를 지정할 수 있습니다. 무이자 및 카드 포인트 파라미터는 무시됩니다. +수기(키인) 결제 요청 시 `POST /payments/${PAYMENT_ID_HERE}/instant` API를 호출해야 합니다. -가상계좌 수기 결제 관련 유의 사항은 다음과 같습니다. - -- 회전식 가상계좌만 지원되고, 고정식 가상계좌는 지원되지 않습니다. - -- 가상계좌 입금자명을 `customer.name`에 입력해야 합니다. - -- 예금주명 지정은 무시됩니다. - -- 사용 가능한 은행은 다음과 같습니다. - - 기업은행 - - 국민은행 - - 수협은행 - - NH농협은행 - - 우리은행 - - SC제일은행 - - iM뱅크 - - 부산은행 - - 광주은행 - - 경남은행 - - 우체국 - - 하나은행 - - 신한은행 +KCP 기준으로 작성한 예시 코드는 아래와 같습니다. - + + ```javascript + // ... 수기(키인) 결제 + const issueResponse = await axios({ + url: `https://api.portone.io/payments/${PAYMENT_ID_HERE}/instant`, + method: "post", + headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` }, + data: { + channelKey: "channel-key-9987cb87-****-****-****-********896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요. + orderName: "나이키 와플 트레이너 2 SD", + amount: { + total: 10000, + }, + currency: "KRW", + customer: { + name: { + full: "홍길동", + }, + email: "test@test.com", + phoneNumber: "010-1234-0000", + }, + method: { + card: { + credential: { + nuber: "1234123400001234", // 카드 번호 입력 시 숫자만 입력해주세요. + expiryYear: "26", // 유효기간 만료 연도 2자리 + expiryMonth: "12", // 유효기간 만료 월 2자리 + birthOrBusinessRegistrationNumber: "900101", // 카드 소유주 생년월일 또는 사업자 등록번호 + passwordTwoDigits: "00", // 카드 비밀번호 앞 2자리 + }, + }, + }, + }, + }); + ``` + + + ```javascript // ... 수기(키인) 결제 const issueResponse = await axios({ @@ -645,7 +686,6 @@ KCP 기준으로 작성한 예시 코드는 아래와 같습니다. remitteeName: `테스트`, }, }, - productCount: 1, }, }); ``` @@ -673,7 +713,7 @@ KCP 기준으로 작성한 예시 코드는 아래와 같습니다. **채널 키** - 포트원 콘솔 내 \[결제연동] > \[채널관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다. + 포트원 콘솔 내 \[연동 관리] > \[연동 정보] > \[채널 관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다. - `amount` **\*** **object** @@ -768,83 +808,125 @@ KCP 기준으로 작성한 예시 코드는 아래와 같습니다. - `card` **object** - - `credential` **\*** **string** + **카드 결제 시 파라미터** - **인증 관련 정보** + + - `credential` **\*** **string** - - - `number` **\*** **object** + **인증 관련 정보** - **카드 번호** + + - `number` **\*** **object** - - `expiryYear` **\*** **object** + **카드 번호** - **유효 기간 만료 연도 (YY 형식 ex. 24)** + - `expiryYear` **\*** **object** - - `expiryMonth` **\*** **string** + **유효 기간 만료 연도 (YY 형식 ex. 24)** - **유효기간 만료 월 (MM 형식 ex. 05)** + - `expiryMonth` **\*** **string** - - `birthOrBusinessRegistrationNumber` **\*** **string** + **유효기간 만료 월 (MM 형식 ex. 05)** - **생년월일 또는 사업자 등록 번호** + - `birthOrBusinessRegistrationNumber` **\*** **string** - - `passwordTwoDigits`**\*** **string** + **생년월일 또는 사업자 등록 번호** - **비밀번호 앞 두자리** - - + - `passwordTwoDigits`**\*** **string** - - `customer` **object** - - **고객 정보** + **비밀번호 앞 두자리** + + + - - - `name` **object** + - `customer` **object** - **고객 이름** + **고객 정보** - - full 또는 separated 중 하나를 입력할 수 있습니다. 입력시 KCP에 전달됩니다. + + - `name` **object** - - - `full` **string** + **고객 이름** - **한 줄 이름 형식 (ex. 김포트)** + - full 또는 separated 중 하나를 입력할 수 있습니다. - - `separated` **object** + + - `full` **string** - **분리된 이름** + **한 줄 이름 형식 (ex. 김포트)** - - - `first` **\*** **string** + - `separated` **object** - **이름** + **분리된 이름** - - `last` **\*** **string** + + - `first` **\*** **string** - **성** - - + **이름** - - `phoneNumber` **string** + - `last` **\*** **string** - **구매자 연락처** + **성** + + - 입력시 KCP에 전달됩니다. + - `phoneNumber` **string** - - `email` **string** + **구매자 연락처** - **구매자 이메일** + - `email` **string** - 입력시 KCP에 전달됩니다. - + **구매자 이메일** +### 유의사항 + +#### 카드 결제 + +
+

미지원 파라미터 안내

+ + 무이자 및 카드 포인트 파라미터는 지원하지 않습니다. 해당 파라미터를 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. +
+ +#### 가상계좌 결제 + +
+

고정식 가상계좌 미지원 안내

+ + 회전식(일반) 가상계좌만 지원되며, 고정식 가상계좌는 지원하지 않습니다. +
+ +
+

가상계좌 발급 시 입금자명 관련 안내

+ + 발급된 가상계좌의 입금자명은 결제 요청 시 `customer.name` 파라미터에 입력된 이름으로 표시됩니다. + `remitteeName`을 설정하더라도 결제 동작에 아무런 영향을 주지 않습니다. +
+ +
+

가상계좌 발급 가능 은행 안내

+ + - 아래 은행에 한하여 가상계좌 발급이 가능합니다. + - 기업은행 + - 국민은행 + - 수협은행 + - NH농협은행 + - 우리은행 + - SC제일은행 + - iM뱅크 + - 부산은행 + - 광주은행 + - 경남은행 + - 우체국 + - 하나은행 + - 신한은행 +
+ ## API 빌링키 발급 요청하기 -빌링키를 발급하기 위해서는 `POST /billing-keys`를 이용하여 빌링키 발급 요청을 해야합니다. +빌링키를 발급 요청 시 `POST /billing-keys`를 호출해야 합니다. KCP 기준으로 작성한 예시 코드는 아래와 같습니다. @@ -884,7 +966,7 @@ KCP 기준으로 작성한 예시 코드는 아래와 같습니다. **채널 키** - 포트원 콘솔 내 \[결제연동] > \[채널관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다. + 포트원 콘솔 내 \[연동 관리] > \[연동 정보] > \[채널 관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다. - `method` **\*** **object** @@ -965,7 +1047,7 @@ KCP 기준으로 작성한 예시 코드는 아래와 같습니다. ## API 빌링키 단건 결제 요청하기 -발급된 빌링키로 단건 결제를 하기 위해 `POST /payments/${PAYMENT_ID_HERE}/billing-key`를 이용하여 결제를 요청합니다. +발급된 빌링키로 단건 결제 요청 시 `POST /payments/${PAYMENT_ID_HERE}/billing-key` API를 호출해야 합니다. KCP 기준으로 작성한 예시 코드는 아래와 같습니다. @@ -982,15 +1064,14 @@ KCP 기준으로 작성한 예시 코드는 아래와 같습니다. orderName: "월간 이용권 정기결제", customer: { id: "customer-1234", // 고객사에서 관리하는 고객 고유번호 - phoneNumber: `010-1234-5678`, - email: `test@test.com`, + phoneNumber: "010-1234-5678", + email: "test@test.com", }, amount: { total: 10000, }, currency: "KRW", }, - productCount: 1, }, }); ``` @@ -1107,7 +1188,7 @@ KCP 기준으로 작성한 예시 코드는 아래와 같습니다. }, currency: "KRW", }, - timeToPay: "2023-01-01 00:00:00", // 결제를 시도할 시각 + timeToPay: "2023-01-01T00:00:00+09:00", // 결제 예정 시점. RFC 3339 형식으로 입력해야 합니다. }, }); ``` @@ -1160,47 +1241,47 @@ KCP 기준으로 작성한 예시 코드는 아래와 같습니다. **결제 통화** 결제통화로 원화 결제 시 `KRW`로 입력해야 합니다. - - - `timeToPay` **\*** **string** + - `customer` **\*** **object** - **결제 예정 시점** + **고객 정보** - - `customer` **\*** **object** + + - `name` **\*** **object** - **고객 정보** + **고객 이름** - - - `name` **\*** **object** + + - `full` **string** - **고객 이름** + **한 줄 이름 형식 (ex. 김포트)** - - - `full` **string** + - `separated` **object** - **한 줄 이름 형식 (ex. 김포트)** + **분리된 이름** - - `separated` **object** + + - `first` **\*** **string** - **분리된 이름** - - - - `first` **\*** **string** - - **이름** + **이름** - - `last` **\*** **string** + - `last` **\*** **string** - **성** + **성** + - - - `phoneNumber` **\*** **string** + - `phoneNumber` **\*** **string** - **구매자 연락처** + **구매자 연락처** - - `email`**\*** **string** + - `email`**\*** **string** - **구매자 이메일** + **구매자 이메일** + + + - `timeToPay` **\*** **string** + + **결제 예정 시점** diff --git a/src/content/docs/ko/v2-payment/v2-sdk/payment-request.mdx b/src/content/docs/ko/v2-payment/v2-sdk/payment-request.mdx index 8eb0062c6..1722590bb 100644 --- a/src/content/docs/ko/v2-payment/v2-sdk/payment-request.mdx +++ b/src/content/docs/ko/v2-payment/v2-sdk/payment-request.mdx @@ -257,9 +257,9 @@ PG사별 지원되는 결제수단이 모두 상이합니다. `pgProvider` 파라미터가 없는 경우에 필수로 존재해야 합니다. 두 파라미터가 모두 존재하는 경우 `channelKey`을 적용하니 둘 중 하나만 제공해주세요. -### **`pgProvider`** **string** +### **`pgProvider`** **string** (Deprecated 예정) -**PG사 구분코드** +**PG사 구분코드** (2024년 09월 30일부터 사용이 불가능한 파라미터 입니다.) `channelKey` 파라미터가 없는 경우에 필수로 존재해야 합니다. @@ -279,9 +279,9 @@ PG사별 지원되는 결제수단이 모두 상이합니다. - `KPN`
-### **`isTestChannel`** **boolean** +### **`isTestChannel`** **boolean** (Deprecated 예정) -**테스트 채널 정보로 결제할지 여부** +**테스트 채널 정보로 결제할지 여부** (2024년 09월 30일부터 사용이 불가능한 파라미터 입니다.) 미입력 시 기본값은 `false`입니다.