Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

메뉴구조 개선을 위한 페이지 병합 #430

Closed
wants to merge 3 commits into from
Closed

메뉴구조 개선을 위한 페이지 병합 #430

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6638a6e
페이지 병합
sso-ashley Apr 18, 2024
00cad65
가이드 4,5 통합
sso-ashley Apr 23, 2024
c6135f0
린트 수정
sso-ashley Apr 23, 2024
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
10 changes: 2 additions & 8 deletions src/content/docs/ko/_nav.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,8 @@
- /ko/auth/guide/1
- /ko/auth/guide/2
- /ko/auth/guide/3
- slug: /ko/auth/guide/4/readme
items:
- /ko/auth/guide/4/iframe
- /ko/auth/guide/4/redirect
- slug: /ko/auth/guide/5/readme
items:
- /ko/auth/guide/5/pre
- /ko/auth/guide/5/post
- /ko/auth/guide/4/readme
- /ko/auth/guide/5/readme
- /ko/auth/guide/6
- slug: /ko/auth/guide-1/readme
items:
Expand Down
169 changes: 165 additions & 4 deletions src/content/docs/ko/auth/guide/4/readme.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,10 @@ title: 4. 결제결과 처리하기
description: 결제결과를 안전하게 저장할 수 있는 가이드 입니다.
---

import ContentRef from "~/components/gitbook/ContentRef.astro";
import Details from "~/components/gitbook/Details.astro";
import Tab from "~/components/gitbook/tabs/Tab.astro";
import Tabs from "~/components/gitbook/tabs/Tabs.astro";
import Hint from "~/components/Hint.astro";

결제창이 활성화되는 방식에 따라 결제결과를 획득하는 방법이 상이합니다.
일반적으로 PC 환경에서는 iframe 방식으로 결제창이 활성화되며,
Expand All @@ -15,8 +18,166 @@ import ContentRef from "~/components/gitbook/ContentRef.astro";
|:---------------:|:----------------:|
|**callback 함수**|**m_redirect_url**|

자세한 가이드는 아래 링크를 참고해주세요.
자세한 가이드는 아래 내용을 참고해주세요.

<ContentRef slug="/ko/auth/guide/4/iframe" />
<Details>
<p slot="summary">iframe 결제창 결과처리</p>

<ContentRef slug="/ko/auth/guide/4/redirect" />
대부분의 PC환경에서 적용되는 iframe 방식 결제창 환경에서의 결과처리 방법을 안내합니다.

<Hint style="info">
**iframe이란?**

**다른 HTML 페이지를 현재 페이지에 포함**시킬 수 있는 요소입니다.\
자세한 내용은 [MDN iframe 문서](https://developer.mozilla.org/ko/docs/Web/HTML/Element/iframe)를 참고해주세요.
</Hint>

**PC 환경**에서 일어나는 대부분의 결제는 **`request_pay()`** 함수의 두번째 인자인 **callback** 함수를 통해 결제 결과 수신이 가능합니다.

아래 예제 코드는 결제창 형태가 **iframe 으로 활성화**되는 **대부분의 PC 환경**에서의 결제요청에 대한 응답을 처리하는 부분입니다.

```ts
IMP.request_pay(
{
/** 요청 객체를 추가해주세요 */
},
(rsp) => {
if (rsp.success) {
// axios로 HTTP 요청
axios({
url: "{서버의 결제 정보를 받는 endpoint}",
method: "post",
headers: { "Content-Type": "application/json" },
data: {
imp_uid: rsp.imp_uid,
merchant_uid: rsp.merchant_uid,
},
}).then((data) => {
// 서버 결제 API 성공시 로직
});
} else {
alert(`결제에 실패하였습니다. 에러 내용: ${rsp.error_msg}`);
}
},
);
```

결제가 완료되면 반환되는 응답 객체([**rsp**](../../../sdk/javascript-sdk-old/readme))의 결제 성공
여부에 따라 처리 로직을 **callback** 함수에 작성합니다. 요청이 성공했을 경우에 **결제번호(imp\_uid)와
주문번호(merchant\_uid)를 서버에 전달**하는 로직을 위와 같이 작성합니다.

<Hint style="info">
[payrt](../../../sdk/javascript-sdk/payrt "mention")에서 callback 함수로 전달되는 응답 파라미터를 확인할 수 있습니다.
</Hint>

<Hint style="danger">
최종 결제결과 로직처리는 반드시 [<mark style="color:red;">**웹훅**</mark>](../../../result/webhook)을 이용하여 안정적으로 처리해 주셔야 합니다.

웹훅 연동을 생략하시는 경우 결제결과를 정상적으로 수신받지 못하는 상황이 발생합니다.
</Hint>

<Hint style="success">
**(구) 페이팔(Paypal)** 결제는 PC 환경 결제 시 \*\*팝업형태(새 창)\*\*로 결제창이 활성화 되며

이에 따라 결제 결과도 **m\_redirect\_url** 로 받아보실 수 있습니다.
</Hint>

</Details>

<Details>
<p slot="summary">redirect 결제창 결과처리</p>

새로운 창으로 리디렉션되어 결제가 진행되는 환경에서의 결과 처리 방법을 안내합니다.

아래 예제 코드는 결제창 형태가 **새로운 페이지로 리디렉션되어** 결제가 진행되는 대부분의
**모바일 환경**에서의 결제 요청에 대한 응답을 처리하는 부분입니다.

[리디렉션이란? 페이지 바로가기](../../../tip/redirect)

<Tabs>
<Tab title="JavaScript">
```ts
IMP.request_pay(
{
/* 결제 요청 객체를 채워주세요. */
m_redirect_url: "{리디렉션 될 URL}",
} /* callback */,
); // 리디렉션 방식의 경우 callback은 실행되지 않습니다.
```
</Tab>
</Tabs>

위와 같이 **request\_pay** 함수 파라미터로 **m\_redirect\_url** 을 설정하면
<mark style="color:blue;">**결제 완료**</mark> 이후 해당 URL 주소로
결제 결과를 **쿼리스트링(Query String)** 형태로 전송해 드립니다.

<Hint style="info">
**Query String 이란?**

URL 뒤에 데이터를 전달하는 가장 단순한 방법으로 주로 GET 요청과 함께 데이터를 전송할 때 사용합니다.
</Hint>

결제 결과를 수신받을 endpoint url 주소를 m\_redirect\_url 에 설정하시면 결제결과 수신이 가능합니다.

아래 파라미터를 설정하신 URL 을 통해 Query String 형태로 수신받을수 있습니다.

아래는 Query String 으로 리디렉션되는 URL 예제입니다.

<Tabs>
<Tab title="결제완료/가상계좌 발급완료">
```http
GET https://myservice.com/payments/complete?imp_uid=결제건을_특정하는_포트원_번호&merchant_uid=고객사_고유_주문번호&imp_success=true
```
</Tab>

<Tab title="결제 실패">
```http
GET https://myservice.com/payments/complete?imp_uid=결제건을_특정하는_포트원_번호&merchant_uid=고객사_고유_주문번호&imp_success=false&error_code=에러_코드(현재_정리된_체계는_없음)&error_msg=에러_메시지
```
</Tab>
</Tabs>

| 파라미터명 | 설명 | 비고 |
|:-----------------------------------------:|:------------------:|:-----:|
| **imp\_uid** |포트원 결제 고유번호| 공통 |
| **merchant\_uid** | 고객사 주문번호 | 공통 |
| **imp\_success** | 결제 성공 여부 | 공통 |
|<mark style="color:red;">error\_code</mark>| 오류 코드 |실패 시|
| <mark style="color:red;">error\_msg</mark>| 오류 메세지 |실패 시|

> <mark style="color:blue;">**결제 완료**</mark>**의 의미**
>
> `결제완료`는 아래의 모든 경우를 포함합니다.
>
> 1. **결제 성공**(결제 상태: `paid`, imp\_success: `true`)
> 2. **결제 실패**(결제 상태: `failed`, imp\_success: `false`)
> 3. PG 모듈 설정이 올바르지 않아, **결제 창이 열리지 않음**
> 4. 사용자가 임의로 X 버튼이나 취소 버튼을 눌러 **결제를 종료**함
> 5. 카드 정보 불일치, 한도 초과, 잔액 부족 등의 사유로 **결제가 중단**됨
> 6. 가상계좌 \*\*발급 완료(\*\*결제 상태: `ready`, imp\_success: `true`)

<Hint style="danger">
**결제창이 리디렉션되어 새로운 페이지에서 활성화되는 경우 결제 결과는 callback 으로 받을 수 없습니다.**
</Hint>

<Hint style="danger">
최종 결제 결과 로직 처리는 반드시 [<mark style="color:red;">**웹훅**</mark>](../../../result/webhook)을 이용하여 안정적으로 처리해 주셔야 합니다.

웹훅 연동을 생략하시는 경우 결제 결과를 정상적으로 수신받지 못하는 상황이 발생합니다.
</Hint>

<Hint style="warning">
**imp\_success 파라미터**

<mark style="color:red;">`imp_success`</mark> 파라미터는 **결제 프로세스 정상 종료
여부**를 의미합니다. 하지만 클라이언트 상에서 자바스크립트 함수를 호출해서 결제창이
열리므로 **결제금액이 위변조 되었을 가능성**이 있기 때문에 **이 값으로 결제의 성공
여부를 판단해서는 안됩니다**. 결제의 성공 여부에 따라 아래와 같이 처리합니다.

- imp\_success = true: 결제 정보(imp\_uid, merchant\_uid)를 서버에 전달해서 결제금액의 위변조 여부를 검증한 후 최종적으로 결제 성공 여부를 판단해야 합니다.
- Imp\_success = false: 결제가 실패했음을 사용자에게 알립니다.

\* 일부 PG사에 한해 `imp_success`가 아닌 `success` 파라미터가 전달되거나 아예 전달되지 않는 경우(예: KG이니시스 - 실시간 계좌이체)도 있으니 주의하셔야 합니다.
</Hint>

</Details>
Loading