Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions src/routes/(root)/opi/ko/integration/start/v2/checkout.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,11 @@ async function requestPayment() {
지정한 `redirectUrl`로 다시 리다이렉트됩니다. 이 경우에는 함수 호출 결과를 이용할 수 없고,
결제 성공 여부 등은 [쿼리 문자열](http://en.wikipedia.org/wiki/Query_string)로 전달받게 됩니다.

<Hint style="info">
PC 환경에서도 리다이렉트 방식을 사용하려면 `forceRedirect: true` 옵션을 사용하세요.
자세한 내용은 아래 [3-2. forceRedirect 옵션](#3-2-forceredirect-옵션으로-리다이렉트-강제하기)을 참고하세요.
</Hint>

```ts
PortOne.requestPayment({
/* 파라미터 생략 */
Expand All @@ -136,6 +141,38 @@ PortOne.requestPayment({
예를 들어 paymentId가 `payment-39ecfa97`, redirectUrl이 `https://example.com/payment-redirect`인 경우,
결제 성공 시에 `https://example.com/payment-redirect?paymentId=payment-39ecfa97`로 리다이렉트됩니다.

### 3-2. forceRedirect 옵션으로 리다이렉트 강제하기

PC 환경에서도 결과를 리다이렉트 방식으로 받고 싶은 경우 `forceRedirect` 옵션을 사용할 수 있습니다.
`forceRedirect` 옵션을 사용할 경우 `redirectUrl`을 필수적으로 전달해 주셔야 합니다.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

forceRedirect 옵션을 사용할 때 redirectUrl이 필수라고 설명되어 있습니다. 하지만 browser-sdk.yml 스키마를 보면 redirectUrl이 없으면 forceRedirect 옵션이 무시되고 Promise로 결과가 반환된다고 정의되어 있습니다. 사용자 혼동을 줄이기 위해 문서의 내용을 SDK의 실제 동작과 일치시키는 것이 좋습니다.

`forceRedirect` 옵션을 사용할 경우 `redirectUrl`을 함께 전달해야 리디렉션이 동작합니다.


```ts title="TypeScript"
PortOne.requestPayment({
storeId: "store-xxxxxxxx",
channelKey: "channel-key-xxxxxxxx",
paymentId: `payment-${crypto.randomUUID()}`,
orderName: "나이키 와플 트레이너 2 SD",
totalAmount: 1000,
currency: "CURRENCY_KRW",
payMethod: "CARD",
redirectUrl: "https://example.com/payment/complete",
forceRedirect: true, // PC에서도 리다이렉트 방식 사용
});
```

<Hint style="warning">
`forceRedirect: true`를 사용할 때 `redirectUrl`은 반드시 `http://` 또는 `https://`로 시작해야 합니다.
</Hint>

### 3-3. 모바일 환경에서의 결제창 동작

모바일 환경에서 `redirectUrl`을 설정하지 않으면 SDK가 자동으로 PC 모드로 전환하여
결제창을 표시합니다. 이 경우 결과는 Promise로 반환됩니다.

<Hint style="info">
모바일에서 `redirectUrl` 없이 결제할 경우, 결제창이 팝업 또는 iframe 형태로 표시됩니다.
</Hint>

## 4. 결제 완료 처리 (서버)

paymentId를 서버에 전달하면, 서버는 포트원의 [결제 조회 API](/api/rest-v2/payment#get%20%2Fpayments%2F%7BpaymentId%7D)를
Expand Down
44 changes: 44 additions & 0 deletions src/schema/browser-sdk.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5308,6 +5308,17 @@ resources:
type: resourceRef
optional: true
$ref: "#/resources/entity/RedirectUrl"
forceRedirect:
type: boolean
optional: true
description: |
**결과 리턴 방식을 리디렉션으로 강제**

`true`로 설정하면 원래 프로미스로 resolve 되었을 상황에서도
`redirectUrl`로 쿼리 파라미터와 함께 리디렉션합니다.

- `redirectUrl`이 없으면 기존처럼 프로미스로 반환합니다.
- 본인인증 시작 전 발생하는 에러는 리디렉션하지 않습니다.
customData:
type: string
optional: true
Expand Down Expand Up @@ -5392,6 +5403,17 @@ resources:
type: resourceRef
optional: true
$ref: "#/resources/entity/RedirectUrl"
forceRedirect:
type: boolean
optional: true
description: |
**결과 리턴 방식을 리디렉션으로 강제**

`true`로 설정하면 원래 프로미스로 resolve 되었을 상황에서도
`redirectUrl`로 쿼리 파라미터와 함께 리디렉션합니다.

- `redirectUrl`이 없으면 기존처럼 프로미스로 반환합니다.
- 빌링키 발급 시작 전 발생하는 에러는 리디렉션하지 않습니다.
locale:
optional: true
type: resourceRef
Expand Down Expand Up @@ -5514,6 +5536,17 @@ resources:
type: resourceRef
optional: true
$ref: "#/resources/entity/RedirectUrl"
forceRedirect:
type: boolean
optional: true
description: |
**결과 리턴 방식을 리디렉션으로 강제**

`true`로 설정하면 원래 프로미스로 resolve 되었을 상황에서도
`redirectUrl`로 쿼리 파라미터와 함께 리디렉션합니다.

- `redirectUrl`이 없으면 기존처럼 프로미스로 반환합니다.
- 빌링키 발급 및 결제 시작 전 발생하는 에러는 리디렉션하지 않습니다.
noticeUrls:
optional: true
type: array
Expand Down Expand Up @@ -5637,6 +5670,17 @@ resources:
type: resourceRef
optional: true
$ref: "#/resources/entity/RedirectUrl"
forceRedirect:
type: boolean
optional: true
description: |
**결과 리턴 방식을 리디렉션으로 강제**

`true`로 설정하면 원래 프로미스로 resolve 되었을 상황에서도
`redirectUrl`로 쿼리 파라미터와 함께 리디렉션합니다.

- `redirectUrl`이 없으면 기존처럼 프로미스로 반환합니다.
- 결제 시작 전 발생하는 에러는 리디렉션하지 않습니다.
noticeUrls:
optional: true
type: array
Expand Down