From 4be6a8021865279cb16268b817e8634ac0308f43 Mon Sep 17 00:00:00 2001 From: LimJiGyu Date: Mon, 25 Mar 2024 12:46:50 +0900 Subject: [PATCH] apply renewal v2 api secret for v2 description --- src/content/docs/ko/v2-payment/authpay.mdx | 82 +++++++++++----------- src/content/docs/ko/v2-payment/v2.mdx | 79 ++++++++++++--------- 2 files changed, 85 insertions(+), 76 deletions(-) diff --git a/src/content/docs/ko/v2-payment/authpay.mdx b/src/content/docs/ko/v2-payment/authpay.mdx index 4afc4a817..edc8c1ffa 100644 --- a/src/content/docs/ko/v2-payment/authpay.mdx +++ b/src/content/docs/ko/v2-payment/authpay.mdx @@ -4,11 +4,8 @@ description: PG 결제창을 이용하는 인증 결제를 연동합니다. --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; -import Tabs from "~/components/gitbook/tabs/Tabs.astro"; -import Tab from "~/components/gitbook/tabs/Tab.astro"; - import Youtube from "~/components/gitbook/Youtube.astro"; +import Hint from "~/components/Hint.astro"; import SdkInstallation from "./_components/sdk-installation.mdx" @@ -16,10 +13,8 @@ import SdkInstallation from "./_components/sdk-installation.mdx"

영상으로 보기

- + + ## 1. 포트원 SDK 설치 @@ -50,7 +45,8 @@ const response = await PortOne.requestPayment({ }); ``` -**paymentId**는 결제 건을 구분하는 문자열로, 결제 요청 및 조회에 필요합니다. 같은 paymentId에 대해 여러 번의 결제 시도가 가능하나, 최종적으로 결제에 성공하는 것은 단 한 번만 가능합니다. (중복 결제 방지) +**paymentId**는 결제 건을 구분하는 문자열로, 결제 요청 및 조회에 필요합니다. 같은 paymentId에 대해 여러 번의 결제 시도가 가능하나, +최종적으로 결제에 성공하는 것은 단 한 번만 가능합니다. (중복 결제 방지) **orderName**은 주문 내용을 나타내는 문자열입니다. 특정한 형식이 있지는 않지만, 결제 처리에 필요하므로 필수적으로 전달해 주셔야 합니다. @@ -73,35 +69,34 @@ const response = await PortOne.requestPayment({ if (response.code != null) { // 오류 발생 - return alert(response.message); + alert(response.message); } // /payment/complete 엔드포인트를 구현해야 합니다. 다음 목차에서 설명합니다. -const notified = await fetch( - `${SERVER_BASE_URL}/payment/complete`, - { - method: "POST", - headers: { "Content-Type": "application/json" }, - // paymentId와 주문 정보를 서버에 전달합니다 - body: JSON.stringify({ - paymentId: paymentId, - // 주문 정보... - }), - } -); +const notified = await fetch(`${SERVER_BASE_URL}/payment/complete`, { + method: "POST", + headers: { "Content-Type": "application/json" }, + // paymentId와 주문 정보를 서버에 전달합니다 + body: JSON.stringify({ + paymentId: paymentId, + // 주문 정보... + }), +}); ``` 결과값에 들어 있는 필드는 다음과 같습니다. -| 필드명 | 설명 | 비고 | -| --------- | ---------- | ------- | -| paymentId | 결제 건 ID | 공통 | -| code | 오류 코드 | 실패 시 | -| message | 오류 문구 | 실패 시 | +|필드명 |설명 |비고 | +|---------|-------|----| +|paymentId|결제 건 ID|공통 | +|code |오류 코드 |실패 시| +|message |오류 문구 |실패 시| ### 3-1. redirect 방식의 경우 -모바일 환경에서의 결제는 대부분 redirect 방식으로 이루어집니다. redirect 방식에서는 브라우저가 결제창으로 리다이렉트되었다가, 결제창에서의 작업이 끝나면 지정한 `redirectUrl`로 다시 리다이렉트됩니다. 이 경우에는 함수 호출 결과를 이용할 수 없고, 결제 성공 여부 등은 [쿼리 문자열](https://en.wikipedia.org/wiki/Query_string)로 전달받게 됩니다. +모바일 환경에서의 결제는 대부분 redirect 방식으로 이루어집니다. redirect 방식에서는 브라우저가 결제창으로 리다이렉트되었다가, 결제창에서의 작업이 끝나면 +지정한 `redirectUrl`로 다시 리다이렉트됩니다. 이 경우에는 함수 호출 결과를 이용할 수 없고, +결제 성공 여부 등은 [쿼리 문자열](https://en.wikipedia.org/wiki/Query_string)로 전달받게 됩니다. ```javascript PortOne.requestPayment({ @@ -112,27 +107,31 @@ PortOne.requestPayment({ 쿼리 문자열로 전달되는 내용은 다음과 같습니다. -| 키 | 설명 | 비고 | -| ---------- | ---------- | ------- | -| payment_id | 결제 건 ID | 공통 | -| code | 오류 코드 | 실패 시 | -| message | 오류 문구 | 실패 시 | +|키 |설명 |비고 | +|-----------|-------|----| +|payment\_id|결제 건 ID|공통 | +|code |오류 코드 |실패 시| +|message |오류 문구 |실패 시| -예를 들어 paymentId가 `payment-39ecfa97`, redirectUrl이 `https://example.com/payment-redirect`인 경우, 결제 성공 시에 `https://example.com/payment-redirect?payment_id=payment-39ecfa97`로 리다이렉트됩니다. +예를 들어 paymentId가 `payment-39ecfa97`, redirectUrl이 `https://example.com/payment-redirect`인 경우, +결제 성공 시에 `https://example.com/payment-redirect?payment_id=payment-39ecfa97`로 리다이렉트됩니다. ## 4. 결제 완료 처리 (서버) -paymentId를 서버에 전달하면, 서버는 포트원의 [결제 조회 API](/api/rest-v2/payment#get%20%2Fpayments%2F%7BpaymentId%7D)를 호출하여 해당 결제 건의 상태를 확인하고 결제 완료 처리를 하여야 합니다. +paymentId를 서버에 전달하면, 서버는 포트원의 [결제 조회 API](/api/rest-v2/payment#get%20%2Fpayments%2F%7BpaymentId%7D)를 +호출하여 해당 결제 건의 상태를 확인하고 결제 완료 처리를 하여야 합니다. -**결제 검증 필수** - -인증 결제의 흐름상 결제 금액 등 정보가 고객의 브라우저 측에서 처리되므로, 의도한 결제 내용이 맞는지 꼭 확인하여야 위변조를 막을 수 있습니다. + **결제 검증 필수** + 인증 결제의 흐름상 결제 금액 등 정보가 고객의 브라우저 측에서 처리되므로, 의도한 결제 내용이 맞는지 꼭 확인하여야 위변조를 막을 수 있습니다. 예시로, 위에서 사용했던 `/payment/complete` 엔드포인트를 다음과 같이 구현할 수 있습니다. +[PORTONE\_API\_SECRET](/docs/ko/ready/readme?v=v2#4-2-v2-api-secret-%EB%B0%9C%EA%B8%89%ED%95%98%EA%B8%B0) +은 V2 전용 시크릿으로, 포트원 콘솔 내 결제연동 탭에서 발급받을 수 있습니다. + ```javascript title="Express" app.use(bodyParser.json()); @@ -146,10 +145,11 @@ app.post("/payment/complete", async (req, res) => { const paymentResponse = await fetch( `https://api.portone.io/payments/${encodeURIComponent(paymentId)}`, { - headers: { "Authorization": `PortOne ${PORTONE_API_SECRET}` }, + headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` }, }, ); - if (!paymentResponse.ok) throw new Error(`paymentResponse: ${paymentResponse.statusText}`); + if (!paymentResponse.ok) + throw new Error(`paymentResponse: ${paymentResponse.statusText}`); const payment = await paymentResponse.json(); // 2. 고객사 내부 주문 데이터의 가격과 실제 지불된 금액을 비교합니다. @@ -170,11 +170,9 @@ app.post("/payment/complete", async (req, res) => { } else { // 결제 금액이 불일치하여 위/변조 시도가 의심됩니다. } - } catch (e) { // 결제 검증에 실패했습니다. res.status(400).send(e); } }); - ``` diff --git a/src/content/docs/ko/v2-payment/v2.mdx b/src/content/docs/ko/v2-payment/v2.mdx index ed4783cc5..46ce04fe1 100644 --- a/src/content/docs/ko/v2-payment/v2.mdx +++ b/src/content/docs/ko/v2-payment/v2.mdx @@ -3,74 +3,86 @@ title: "V2 신모듈 소개" description: 새롭게 출시된 V2 서비스를 소개드립니다. --- -import Hint from "~/components/Hint.astro"; import Figure from "~/components/Figure.astro"; +import Hint from "~/components/Hint.astro"; + import getOpenApiImage from "./_assets/v2/developers_openapi_example.png"; -import getPostmanImportImage from "./_assets/v2/postman_import_example.png"; +import getNpmTypescriptExampleImage from "./_assets/v2/npm_typescript_example.png"; import getPostmanApiStructureImage from "./_assets/v2/postman_api_structure.png"; +import getPostmanImportImage from "./_assets/v2/postman_import_example.png"; import getV2CoproductExampleImage from "./_assets/v2/v2_coproduct_example.png"; -import getNpmTypescriptExampleImage from "./_assets/v2/npm_typescript_example.png"; -## 포트원 신모듈 소개 [V2] +## 포트원 신모듈 소개 \[V2] -포트원 V2는 10년 간의 포트원 운영 경험을 바탕으로 새롭게 설계되었습니다. 개발자 경험의 혁신적인 개선을 통해 포트원을 연동하는 개발자들은 더욱 쉽게 시스템을 이해하고 빠르게 결제 기능을 연동할 수 있습니다. 또한 포트원 V2는 사용자가 직접 느낄 수 있는 개발자 경험의 개선 이외에도, 눈에 보이지 않는 내부적인 부분 또한 많은 개선을 이루었습니다. +포트원 V2는 10년 간의 포트원 운영 경험을 바탕으로 새롭게 설계되었습니다. 개발자 경험의 혁신적인 개선을 통해 포트원을 연동하는 개발자들은 +더욱 쉽게 시스템을 이해하고 빠르게 결제 기능을 연동할 수 있습니다. +또한 포트원 V2는 사용자가 직접 느낄 수 있는 개발자 경험의 개선 이외에도, 눈에 보이지 않는 내부적인 부분 또한 많은 개선을 이루었습니다. ### 혁신적인 개발자 경험: 쉽고 편리한 결제 연동
-포트원 V2는 개발자 경험(Developer Experience)을 혁신적으로 개선하여 쉽고 편리한 결제 연동을 돕습니다. 포트원이 제공하는 차별화된 개발자 경험의 예시는 아래와 같습니다. +포트원 V2는 개발자 경험(Developer Experience)을 혁신적으로 개선하여 쉽고 편리한 결제 연동을 돕습니다. +포트원이 제공하는 차별화된 개발자 경험의 예시는 아래와 같습니다. - **Open API Spec Download** - - 연동용 코드 자동 생성, Custom API Document 활용, Postman Import 등에 사용 가능한 Open API Spec을 다운로드하실 수 있는 기능을 제공합니다. + - 연동용 코드 자동 생성, Custom API Document 활용, Postman Import 등에 + 사용 가능한 Open API Spec을 다운로드하실 수 있는 기능을 제공합니다. -
+

-
+ +
- **직관성 있는 스키마 설계** - - open API spec 파일은 [REST API 문서 페이지](../../../api/rest-v2)에서 **OpenAPI JSON 내려받기** 버튼을 눌러 다운 받으실 수 있습니다. + + - open API spec 파일은 [REST API 문서 페이지](../../../api/rest-v2)에서 **OpenAPI JSON 내려받기** 버튼을 눌러 + 다운 받으실 수 있습니다. + - 타입에 따라 달라지는 스키마 구조를 정확히 표현하여 더욱 예측 가능한 인터페이스로 디자인했습니다. - - 예를 들어 가상계좌로 결제한 결제 건을 조회한다고 가정했을 때, 해당 결제 건은 계좌번호를 항상 포함하고 있을 것입니다. 하지만 기존 시스템을 이용하는 경우, 결제수단별로 응답 스키마가 달라지지 않고 모든 필드를 열거하고 있기 때문에 가상계좌 결제 건임에도 계좌번호는 optional로 제공됩니다. 반면 포트원 V2는 결제수단별로 달라지는 스키마 구조를 정확히 표현하고 있기 때문에, 가상계좌 결제 건일 때는 계좌번호가 required로 제공된다는 것이 타입으로 보장됩니다. + + - 예를 들어 가상계좌로 결제한 결제 건을 조회한다고 가정했을 때, 해당 결제 건은 계좌번호를 항상 포함하고 있을 것입니다. + 하지만 기존 시스템을 이용하는 경우, 결제수단별로 응답 스키마가 달라지지 않고 모든 필드를 열거하고 있기 때문에 + 가상계좌 결제 건임에도 계좌번호는 optional로 제공됩니다. + 반면 포트원 V2는 결제수단별로 달라지는 스키마 구조를 정확히 표현하고 있기 때문에, 가상계좌 결제 건일 때는 + 계좌번호가 required로 제공된다는 것이 타입으로 보장됩니다. + - 이러한 예시를 통해 확인할 수 있듯이, 개발자는 포트원 V2의 직관적인 인터페이스를 통해 결제 시스템을 쉽게 이해하고 불필요한 코드 작성을 최소화할 수 있습니다. -
+
+ - **npm, Typescript 지원** + - V2 SDK는 Typescript로 작성되어 함수의 파라미터 및 응답의 타입을 확인하실 수 있고, npm을 통해 install이 가능합니다. -
+
## 내부 시스템 개선: 풍부한 데이터와 견고한 서버 -포트원 V2는 개발자 경험의 개선을 통해 연동의 편리함을 보장하면서, 장기적으로 고객사의 서비스 운영에 도움이 될 만한 내부 시스템 개선을 진행했습니다. 고객사의 제품 품질 향상과 개선된 비즈니스 의사결정을 도울 수 있는 풍부한 데이터를 제공합니다. 또한 안정적인 운영을 위해 훨씬 더 견고한 시스템을 구축했습니다. +포트원 V2는 개발자 경험의 개선을 통해 연동의 편리함을 보장하면서, 장기적으로 고객사의 서비스 운영에 도움이 될 만한 내부 시스템 개선을 진행했습니다. +고객사의 제품 품질 향상과 개선된 비즈니스 의사결정을 도울 수 있는 풍부한 데이터를 제공합니다. 또한 안정적인 운영을 위해 훨씬 더 견고한 시스템을 구축했습니다. ### 확장성: 무한한 가능성을 열어주는 결제 시스템 -V2는 '항상 준비된 시스템'입니다. 향상된 [오토스케일링](https://ko.wikipedia.org/wiki/%EC%98%A4%ED%86%A0%EC%8A%A4%EC%BC%80%EC%9D%BC%EB%A7%81) 능력을 제공하는 포트원 V2는 블랙프라이데이부터 크리스마스 선착순 이벤트까지, 아무리 많은 결제 트래픽이 몰려도 문제없이 처리할 수 있습니다. V1의 오토스케일링도 훌륭하지만, V2는 더 빠른 반응 속도로 더 많은 트래픽을 감당할 수 있는 '진화된 스케일링 능력'을 갖췄습니다. +V2는 '항상 준비된 시스템'입니다. 향상된 [오토스케일링](https://ko.wikipedia.org/wiki/%EC%98%A4%ED%86%A0%EC%8A%A4%EC%BC%80%EC%9D%BC%EB%A7%81) +능력을 제공하는 포트원 V2는 블랙프라이데이부터 크리스마스 선착순 이벤트까지, 아무리 많은 결제 트래픽이 몰려도 문제없이 처리할 수 있습니다. +V1의 오토스케일링도 훌륭하지만, V2는 더 빠른 반응 속도로 더 많은 트래픽을 감당할 수 있는 '진화된 스케일링 능력'을 갖췄습니다. ### 안정성: 신뢰할 수 있는 서버 -V2의 서버 시스템은 더욱 강해졌습니다. 휴먼 에러의 위험성을 극단적으로 줄이기 위해 모든 서버 시스템은 자동화된 코드로 관리됩니다. 추가로 [Scala]()와 같은 강타입 언어를 사용하여 시스템의 안정성을 더욱 강화했습니다. +V2의 서버 시스템은 더욱 강해졌습니다. 휴먼 에러의 위험성을 극단적으로 줄이기 위해 모든 서버 시스템은 자동화된 코드로 관리됩니다. +추가로 [Scala](https://ko.wikipedia.org/wiki/%EC%8A%A4%EC%B9%BC%EB%9D%BC_\(%ED%94%84%EB%A1%9C%EA%B7%B8%EB%9E%98%EB%B0%8D_%EC%96%B8%EC%96%B4\))와 +같은 강타입 언어를 사용하여 시스템의 안정성을 더욱 강화했습니다. ### 완벽한 데이터 보존: 우수한 데이터 정합성과 풍부한 정보 제공 -V2는 모든 데이터를 수집하고 기록합니다. [Event Sourcing](https://learn.microsoft.com/ko-kr/azure/architecture/patterns/event-sourcing) 기술을 접목하여 서비스의 모든 결제 처리 내역을 빠짐없이 보존합니다. 이를 통해 비즈니스 의사결정에 필요한 주요 정보를 풍부하게 제공합니다. +V2는 모든 데이터를 수집하고 기록합니다. [Event Sourcing](https://learn.microsoft.com/ko-kr/azure/architecture/patterns/event-sourcing) +기술을 접목하여 서비스의 모든 결제 처리 내역을 빠짐없이 보존합니다. 이를 통해 비즈니스 의사결정에 필요한 주요 정보를 풍부하게 제공합니다. ### 기능 확장: 신속한 업데이트와 혁신 -V2는 최신 결제 기능을 가장 빠르게 제공합니다. 곧 출시될 스마트라우팅은 V2 인프라를 이용 중인 고객사에게 우선하여 제공됩니다. 최신 기능을 통해 결제 프로세스를 혁신하고, 고객의 결제 경험을 향상시킬 수 있습니다. +V2는 최신 결제 기능을 가장 빠르게 제공합니다. 곧 출시될 스마트라우팅은 V2 인프라를 이용 중인 고객사에게 우선하여 제공됩니다. +최신 기능을 통해 결제 프로세스를 혁신하고, 고객의 결제 경험을 향상시킬 수 있습니다. ## 사용 가능한 PG사 @@ -84,7 +96,7 @@ V2는 최신 결제 기능을 가장 빠르게 제공합니다. 곧 출시될 - **네이버페이** - **스마트로** - **나이스페이먼츠** -- **페이팔** +- **페이팔** ### 본인인증 @@ -99,8 +111,7 @@ V2는 최신 결제 기능을 가장 빠르게 제공합니다. 곧 출시될
-V2 API Secret 요청 또는 추가적으로 궁금하신 사항은 아래 이메일로 문의주시기 바랍니다. - -- V2 기술지원 이메일: tech.support@portone.io + 추가적으로 궁금하신 사항은 아래 이메일로 문의주시기 바랍니다. + - V2 기술지원 이메일: [tech.support@portone.io](mailto:tech.support@portone.io)