```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",
},
});
}
```
## API 수기(키인)결제 및 빌링키 발급 및 예약/반복 결제 요청하기
수기(키인)로 결제하기 위해서는 `POST /payments/${PAYMENT_ID_HERE}/instant/pay`를 이용하여 결제
요청을 해야합니다. 그리고 빌링키를 발급하기 위해서는 `POST /billing-keys`를 이용하여 빌링키 발급
요청을 해야합니다. 이후 발급된 빌링키로 예약/반복 결제를 하기위해 `POST /schedules` 를 이용하여
결제를 예약합니다.
```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,
},
},
},
},
});
```
```ts
// ... 빌링키 발급
const issueResponse = await axios({
url: "https://api.portone.io/billing-keys",
method: "post",
headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` },
data: {
channelKey,
customer: {
id: customerId,
},
method: {
card: {
credential: {
number: cardNumber,
expiryYear,
expiryMonth,
birthOrBusinessRegistrationNumber,
passwordTwoDigits,
},
},
},
},
});
```
```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", // 결제를 시도할 시각
},
});
// 결제 예약 이후 로직을 구성해주세요.
}
```
## 주요 파라미터
- storeId: string
고객사의 상점을 식별하는 고유한 값입니다.
- paymentId: string
고객사가 채번하는 주문 고유 번호로 매번 고유하게 채번되어야 합니다.
- orderName: string
주문명으로 고객사에서 자유롭게 입력합니다.
- channelKey: string
콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키로 호출하고자 하는 채널을 지정합니다.
- totalAmount: number
결제 금액으로 결제를 원하는 통화(currency)별 scale factor(소수점 몇번째 자리까지 유효한지)를
고려한 number 형식만 허용됩니다.
- currency: string
결제통화로 원화 결제를 원할 시 `KRW`로 입력해야 합니다. KSNET의 경우 `KRW`와 `USD`를 지원합니다.
- payMethod: string
결제수단을 구분하는 코드로 원하는 결제수단 값을 입력해야 합니다.
- customer.fullName: string
구매자 이름으로 KSNET의 경우 필수로 입력해야 합니다.
- taxFreeAmount?: number
면세 금액으로 KSNET과 상점아이디 계약시 복합과세로 계약한 경우 면세 처리를 위해 면세금액을
반드시 입력해야 합니다. 면세금액 미 입력 시 면세금액은 0원으로 자동 처리되며, 결제 요청 금액은
모두 과세 처리 되오니 이 점 유의하시기 바랍니다.
- card.cardCompany: string
카드사 다이렉트 호출 시 결제대행사의 통합결제창을 거치지 않고, 지정한 카드사의 결제화면이 호출됩니다.
카드사별로 지원하는 기능이 상이함으로, 카드 다이렉트 호출 유의사항을 확인해 주세요.
## 유의할 파라미터 - SDK
### SDK 결제/빌링키 발급 공통
- windowType?: string
- KSNET의 경우 PC는 `IFRAME`, mobile은 `REDIRECTION`만 지원되며 이외의 다른 방식으로 결제창을 호출할 경우 에러를 리턴합니다.
- `windowType` 파라미터를 채우지 않을 경우 자동으로 아래와 같이 세팅됩니다.
```json
{
"pc": "IFRAME",
"mobile": "REDIRECTION"
}
```
- locale?: string
- KSNET의 경우 `KO_KR`만 지원합니다. 이외의 값을 넣어도 무시됩니다.
- redirectUrl?: string
- 모바일 환경에서 결제 요청 시 `REDIRECTION` 타입이므로, 필수로 입력해야 합니다.
### API 결제
- productType: string
판매 상품에 대한 상품 유형 파라미터로 API 결제 시 필수로 입력해야 합니다.
- `PHYSICAL`: 실물 상품
- `DIGITAL` : 디지털 상품
### SDK 결제 (`requestPayment`)
- productType?: string
휴대폰 결제인 경우 필수로 입력해야 하며, KSNET의 상점아이디에 설정된 상품 유형과 일치해야합니다.
디지털 상품유형으로 설정된 경우 항상 `PRODUCT_TYPE_DIGITAL`로 입력해야 합니다.
- `PRODUCT_TYPE_REAL`: 실물 상품
- `PRODUCT_TYPE_DIGITAL` : 디지털 상품
- bypass?: object
- ksnet?: object
- sndQpayType?: string
카드 결제 시 결제창에 간편 결제 수단 표시 여부를 설정할 수 있습니다.
- `0` : 간편결제 수단 표시 하지 않음
- `1` : 간편결제 수단 표시함
- sndKakaopayType?: string
카카오페이 결제시 허용할 결제수단
- `CARD`: 카드 결제만 허용
- `MONEY`: 카카오머니 결제만 허용
- 미입력시 모든 결제수단 허용
### 카드 다이렉트 호출
- customer?: object
- fullName?: string
- KSNET을 통한 카드사 다이렉트 호출 시, 구매자명 파라미터는 필수 입력입니다.
- phoneNumber?: string
- 모바일 환경에서 **BC카드, 수협카드, 전북카드, 광주카드, 카카오뱅크카드** 를 다이렉트 호출하는 경우, 필수 입력입니다.
- bypass?: object
- ksnet?: object
- tcode?: string
- 모바일 환경에서 **BC카드, 수협카드, 전북카드, 광주카드, 카카오뱅크카드** 를 다이렉트 호출하는 경우, 필수 입력입니다.
- 통신사에 따라 LG는 lgt, KT는 ktf, SKT는 skt로 입력해야 하며, 통신사 구분이 어려우신 경우 임의의 값을 입력하여 요청해도 무방합니다.
- url?: string
- **우리카드, 하나카드, 농협카드, 삼성카드, 현대카드, 롯데카드, 신한카드, 씨티카드** 를 다이렉트 호출하는 경우 필수 입력입니다.
- storeDetails?: object
- businessName?: string
- **국민카드, 우리카드, 하나카드, 농협카드, 삼성카드, 현대카드, 롯데카드, 신한카드, 씨티카드** 를 다이렉트 호출하는 경우, 필수 입력입니다.
- businessRegistrationNumber?: string
- **국민카드, 우리카드, 하나카드, 농협카드, 삼성카드, 현대카드, 롯데카드, 신한카드, 씨티카드** 를 다이렉트 호출하는 경우, 필수 입력입니다.
- installments?: object
- monthOption?: object
- availableMonthList?: number\[]
- **국민카드, 우리카드, 하나카드, 농협카드, 삼성카드, 현대카드, 롯데카드, 신한카드, 씨티카드** 를 다이렉트 호출하는 경우, 렌더링할 할부개월 리스트를 지정할 수 있습니다.
## 연동 유의사항
### KSNET과 사전 계약이 필요한 경우
포트원을 통해 KSNET을 이용하고자 하는 고객사의 경우 상점아이디의 과세설정이 반드시 `복합과세`로 설정되어 있어야 합니다.
아래의 기능을 사용하려면 사전 신청을 통해 KSNET과 계약을 완료해야 합니다.
계약을 하지 않은 경우 해당 기능을 이용하여 결제 시 결제 승인에 실패하거나, 승인에 성공하더라도 의도한 바와 다른 응답을 받을 수 있습니다.
(ex. 에스크로 결제를 요청하여 결제를 진행하였으나 비-에스크로 결제 응답을 받는 경우)
- 키인결제
- 고객사 부담 무이자 할부 설정
- 가상계좌 입금마감기한 지정
- 가상계좌 환불
- 간편결제
- 신용카드 할부
- 에스크로 (배송 에스크로만 지원)
- KSNET에서는 일반 에스크로, 배송 에스크로 두 가지 유형의 에스크로를 제공하고있으나, 포트원에서는
KSNET 배송 에스크로만 제공하고 있으므로 에스크로 사용을 원할 시 KSNET에 **배송 에스크로**로
설정을 요청 해야합니다.
- 휴대폰 결제
- KSNET을 통해 상품 유형 설정(ex. 실물 혹은 디지털) 요청을 해야합니다.
### 카드 결제
- `card.installment.freeInstallmentPlans.cardCompany` 파라미터는 일부 카드사에 대해서만 적용 가능합니다.
- 지원 가능한 카드 : 비씨,국민,하나,삼성,신한,현대,롯데,농협
- 지원 불가능한 카드 : 씨티