From 2ac04976f08a51e6ce74b2a5a0a044cb541a71d0 Mon Sep 17 00:00:00 2001 From: Ashley Date: Sun, 24 Mar 2024 01:11:16 +0900 Subject: [PATCH] =?UTF-8?q?lint=20=EC=88=98=EC=A0=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/content/docs/ko/etc/phone/1.mdx | 8 +- src/content/docs/ko/etc/phone/4.mdx | 150 +- .../docs/ko/pg/payment-gateway/danal.mdx | 48 +- .../ko/pg/payment-gateway/daou/readme.mdx | 337 +- .../docs/ko/pg/payment-gateway/eximbay.mdx | 248 +- src/content/docs/ko/pg/payment-gateway/kg.mdx | 14 +- .../ko/pg/payment-gateway/ksnet/warning.mdx | 175 +- .../ko/pg/payment-gateway/newtoss/readme.mdx | 518 +- .../ko/pg/payment-gateway/newtoss/warning.mdx | 291 +- .../docs/ko/pg/payment-gateway/nhn-kcp.mdx | 947 +- .../ko/pg/payment-gateway/nice-v2/readme.mdx | 224 +- .../ko/pg/payment-gateway/paymentwall.mdx | 290 +- .../docs/ko/pg/payment-gateway/paypal.mdx | 46 +- .../ko/pg/payment-gateway/settle/mybank.mdx | 249 +- .../ko/pg/payment-gateway/settle/readme.mdx | 184 +- .../pg/payment-gateway/smartro-v2/readme.mdx | 288 +- .../docs/ko/pg/payment-gateway/smartro.mdx | 42 +- .../docs/ko/pg/payment-gateway/spb/stc.mdx | 2 +- .../docs/ko/pg/payment-gateway/toss.mdx | 6 +- .../ko/pg/payment-gateway/welcome/api.mdx | 2 +- .../ko/pg/payment-gateway/welcome/caution.mdx | 475 +- .../ko/pg/payment-gateway/welcome/readme.mdx | 827 +- src/content/docs/ko/pg/simple/kakopay.mdx | 195 +- src/content/docs/ko/pg/simple/naver.mdx | 618 +- src/content/docs/ko/pg/simple/payco.mdx | 42 +- .../ko/pg/simple/toss-brandpay/module.mdx | 289 +- .../ko/pg/simple/toss-brandpay/readme.mdx | 401 +- .../ko/pg/simple/toss-brandpay/widget.mdx | 6 +- .../docs/ko/pg/simple/tosspay-v2/readme.mdx | 134 +- src/content/docs/ko/platform/api.mdx | 8251 ++++++++--------- 30 files changed, 7439 insertions(+), 7868 deletions(-) diff --git a/src/content/docs/ko/etc/phone/1.mdx b/src/content/docs/ko/etc/phone/1.mdx index e7182a7fc..e1230c4bc 100644 --- a/src/content/docs/ko/etc/phone/1.mdx +++ b/src/content/docs/ko/etc/phone/1.mdx @@ -3,15 +3,15 @@ title: 1. 본인인증 준비하기 description: 휴대폰 본인인증 연동을 위한 준비 --- -import Tabs from "~/components/gitbook/tabs/Tabs.astro"; import Tab from "~/components/gitbook/tabs/Tab.astro"; +import Tabs from "~/components/gitbook/tabs/Tabs.astro"; [**`고객사 식별코드`**](../../ready/readme#4-포트원-연동정보-확인하기)를 이용하여 `IMP` 객체를 초기화합니다. ```javascript title="client-side" -var IMP = window.IMP; // 생략 가능 +var IMP = window.IMP; // 생략 가능 IMP.init("{고객사 식별코드}"); // 예: imp00000000 ``` @@ -19,8 +19,8 @@ IMP.init("{고객사 식별코드}"); // 예: imp00000000 ```javascript title="client-side" -const IMP = window.IMP; // 생략 가능 -IMP.init("{고객사 식별코드}"); // 예: imp00000000 +const IMP = window.IMP; // 생략 가능 +IMP.init("{고객사_식별코드}"); // 예: imp00000000 ``` diff --git a/src/content/docs/ko/etc/phone/4.mdx b/src/content/docs/ko/etc/phone/4.mdx index 0fd5115bc..4d5c1b934 100644 --- a/src/content/docs/ko/etc/phone/4.mdx +++ b/src/content/docs/ko/etc/phone/4.mdx @@ -3,13 +3,13 @@ title: 4. 인증정보 조회 및 활용하기 description: 인증정보를 획득하고 활용하는 방법을 안내합니다. --- -import Hint from "~/components/Hint.astro"; -import Tabs from "~/components/gitbook/tabs/Tabs.astro"; import Tab from "~/components/gitbook/tabs/Tab.astro"; +import Tabs from "~/components/gitbook/tabs/Tabs.astro"; +import Hint from "~/components/Hint.astro"; 휴대폰 본인인증 완료이후 획득한 `imp_uid`를 이용하여 고객 인증정보를 조회할 수 있습니다. -### **STEP 01.** 인증정보(imp_uid) 서버단에서 획득하기 +## **STEP 01.** 인증정보(imp_uid) 서버단에서 획득하기 아래는 휴대폰 본인인증 앞단에서 넘어온 값을 서버단에서 수신받은 예제 입니다. @@ -17,12 +17,11 @@ import Tab from "~/components/gitbook/tabs/Tab.astro"; ```javascript title="server-side" app.use(bodyParser.json()); - ... - // "/certifications"에 대한 POST 요청을 처리하는 controller - app.post("/certifications", async (request, response) => { - // request의 body에서 imp_uid 추출 - const { imp_uid } = request.body; -}) +// "/certifications"에 대한 POST 요청을 처리하는 controller +app.post("/certifications", async (request, response) => { + // request의 body에서 imp_uid 추출 + const { imp_uid } = request.body; +}); ``` @@ -30,11 +29,10 @@ app.use(bodyParser.json()); ```javascript title="server-side" app.use(bodyParser.json()); - ... - // "/certifications/redirect"에 대한 GET 요청을 처리하는 controller - app.get("/certifications/redirect", async (request, response) => { - const { imp_uid } = request.query; // request의 query에서 imp_uid 추출 -}) +// "/certifications/redirect"에 대한 GET 요청을 처리하는 controller +app.get("/certifications/redirect", async (request, response) => { + const { imp_uid } = request.query; // request의 query에서 imp_uid 추출 +}); ``` @@ -46,40 +44,38 @@ app.use(bodyParser.json()); ```javascript title="server-side" app.use(bodyParser.json()); - ... - // "/certifications"에 대한 POST 요청을 처리하는 controller - app.post("/certifications", async (request, response) => { - const { imp_uid } = request.body; // request의 body에서 imp_uid 추출 - try { - // 인증 토큰 발급 받기 - const getToken = await axios({ - url: "https://api.iamport.kr/users/getToken", - // POST method - method: "post", - // "Content-Type": "application/json" - headers: { "Content-Type": "application/json" }, - data: { - imp_key: "imp_apikey", // REST API키 - imp_secret: "ekKoeW8RyKuT0zgaZsUtXXTLQ4AhPFW3ZGseDA6bkA5lamv9OqDMnxyeB9wqOsuO9W3Mx9YSJ4dTqJ3f" // REST API Secret - } - }); - const { access_token } = getToken.data; // 인증 토큰 - ... - // imp_uid로 인증 정보 조회 - const getCertifications = await axios({ - // imp_uid 전달 - url: \`https://api.iamport.kr/certifications/\${imp_uid}\`, - // GET method - method: "get", - // 인증 토큰 Authorization header에 추가 - headers: { "Authorization": access_token } - }); - const certificationsInfo = getCertifications.data; // 조회한 인증 정보 - ... - } catch(e) { - console.error(e); - } - }); +// "/certifications"에 대한 POST 요청을 처리하는 controller +app.post("/certifications", async (request, response) => { + const { imp_uid } = request.body; // request의 body에서 imp_uid 추출 + try { + // 인증 토큰 발급 받기 + const getToken = await axios({ + url: "https://api.iamport.kr/users/getToken", + // POST method + method: "post", + // "Content-Type": "application/json" + headers: { "Content-Type": "application/json" }, + data: { + imp_key: "imp_apikey", // REST API키 + imp_secret: + "ekKoeW8RyKuT0zgaZsUtXXTLQ4AhPFW3ZGseDA6bkA5lamv9OqDMnxyeB9wqOsuO9W3Mx9YSJ4dTqJ3f", // REST API Secret + }, + }); + const { access_token } = getToken.data; // 인증 토큰 + // imp_uid로 인증 정보 조회 + const getCertifications = await axios({ + // imp_uid 전달 + url: `https://api.iamport.kr/certifications/\${imp_uid}`, + // GET method + method: "get", + // 인증 토큰 Authorization header에 추가 + headers: { Authorization: access_token }, + }); + const certificationsInfo = getCertifications.data; // 조회한 인증 정보 + } catch (e) { + console.error(e); + } +}); ``` ### **STEP 03.** 인증 정보 활용하기 @@ -114,36 +110,34 @@ app.use(bodyParser.json()); ```javascript title="Node.js" // "/certifications"에 대한 POST 요청을 처리하는 controller - app.post("/certifications", async (request, response) => { - const { imp_uid } = request.body; // request의 body에서 imp_uid 추출 - try { - // 인증 토큰 발급 받기 - /* ...중략... */ - // imp_uid로 인증 정보 조회 - /* ...중략... */ - const certificationsInfo = getCertifications.data; // 조회한 인증 정보 - // unique_key: 개인식별 고유 키, unique_in_site: 사이트 별 개인식별 고유 키 - const { unique_key, unique_in_site, name, gender, birth } = certificationsInfo; - ... - // 연령 제한 로직 - if (new Date(birth).getFullYear() <= 1999) { - // 연령 만족 +app.post("/certifications", async (request, response) => { + const { imp_uid } = request.body; // request의 body에서 imp_uid 추출 + try { + // 인증 토큰 발급 받기 + /* ...중략... */ + // imp_uid로 인증 정보 조회 + /* ...중략... */ + const certificationsInfo = getCertifications.data; // 조회한 인증 정보 + // unique_key: 개인식별 고유 키, unique_in_site: 사이트 별 개인식별 고유 키 + const { unique_key, unique_in_site, name, gender, birth } = + certificationsInfo; + // 연령 제한 로직 + if (new Date(birth).getFullYear() <= 1999) { + // 연령 만족 + } else { + // 연령 미달 + } + // 1인 1계정 허용 로직 + // DB에서 unique_key 조회 후 가입여부 검사 + Users.find({ certificationKey: unique_key }).then((user) => { + if (!user) { + // 신규 고객 } else { - // 연령 미달 + // 이미 가입된 고객 } - ... - // 1인 1계정 허용 로직 - // DB에서 unique_key 조회 후 가입여부 검사 - Users.find({ certificationKey: unique_key }) - .then((user) => { - if (!user) { - // 신규 고객 - } else { - // 이미 가입된 고객 - } - }); - } catch(e) { - console.error(e); - } - }); + }); + } catch (e) { + console.error(e); + } +}); ``` diff --git a/src/content/docs/ko/pg/payment-gateway/danal.mdx b/src/content/docs/ko/pg/payment-gateway/danal.mdx index 39d3d7d43..6de50f6cc 100644 --- a/src/content/docs/ko/pg/payment-gateway/danal.mdx +++ b/src/content/docs/ko/pg/payment-gateway/danal.mdx @@ -3,19 +3,19 @@ title: 다날 description: 다날 결제연동 방법을 안내합니다. --- -import Codepen from "~/components/gitbook/Codepen.astro"; import Figure from "~/components/Figure.astro"; -import Hint from "~/components/Hint.astro"; -import Tabs from "~/components/gitbook/tabs/Tabs.astro"; +import Codepen from "~/components/gitbook/Codepen.astro"; import Tab from "~/components/gitbook/tabs/Tab.astro"; +import Tabs from "~/components/gitbook/tabs/Tabs.astro"; +import Hint from "~/components/Hint.astro"; -### 1. 다날 채널 설정하기 +## 1. 다날 채널 설정하기 [결제대행사 채널 설정하기](../../ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다.
-### 2.결제 요청하기 +## 2.결제 요청하기 @@ -39,11 +39,11 @@ IMP.request_pay( function (rsp) { // callback 로직 //* ...중략... *// - } + }, ); ``` -#### 주요 파라미터 설명 +### 주요 파라미터 설명 **`pg` \*****string** @@ -129,11 +129,11 @@ IMP.request_pay( } else { alert("빌링키 발급 실패"); } - } + }, ); ``` -#### 주요 파라미터 설명 +### 주요 파라미터 설명 **`pg` \*****string** @@ -161,7 +161,7 @@ IMP.request_pay( **`to`** **`: YYYYMMDD`** -#### 빌링키(customer_uid)로 결제 요청하기 +### 빌링키(customer_uid)로 결제 요청하기 빌링키 발급이 성공하면 실 빌링키는 customer_uid 와 1:1 매칭되어 **포트원 서버에 저장**됩니다. customer_uid를 고객사 내부서버에 저장하시고 [**비 인증 결제요청 REST API**](../../api/api-4/api)를 호출하시면 결제를 발생시킬 수 있습니다. @@ -174,7 +174,7 @@ curl -H "Content-Type: application/json" \ -### 3. 부가기능 +## 3. 부가기능 @@ -184,13 +184,13 @@ curl -H "Content-Type: application/json" \ detail: [ { carrier: "*", // 모두 활성화 - enabled: false + enabled: false, }, { carrier: "SKT", // SKT만 활성화 - enabled: true + enabled: true, }, - ] + ]; } } ``` @@ -201,24 +201,24 @@ curl -H "Content-Type: application/json" \ detail: [ { carrier: "SKT", - enabled: false + enabled: false, }, { carrier: "KTF", - enabled: false + enabled: false, }, { carrier: "LGT", - enabled: false + enabled: false, }, { carrier: "CJH", - enabled: false - } - ] + enabled: false, + }, + ]; } } -KCT, SKL 을 제외한 나머지 통신사는 비활성화 됩니다. +// KCT, SKL을 제외한 나머지 통신사는 비활성화 됩니다. ``` ```js title="특정 통신사만 비노출" @@ -242,7 +242,7 @@ phone: { ```javascript title="javascript" prefill: { - phoneNumber: "휴대폰번호" // 휴대폰번호 입력(하이픈 제거) + phoneNumber: "휴대폰번호"; // 휴대폰번호 입력(하이픈 제거) } ``` @@ -254,7 +254,7 @@ prefill: { ```javascript title="javascript" display: { - card_quota: [6] // 할부개월 6개월까지만 활성화 + card_quota: [6]; // 할부개월 6개월까지만 활성화 } ``` @@ -276,7 +276,7 @@ display: { -```javascript title="javascript" +```json title="javascript" card: { direct: { code: "367", diff --git a/src/content/docs/ko/pg/payment-gateway/daou/readme.mdx b/src/content/docs/ko/pg/payment-gateway/daou/readme.mdx index fdc49ca59..9c2f5757e 100644 --- a/src/content/docs/ko/pg/payment-gateway/daou/readme.mdx +++ b/src/content/docs/ko/pg/payment-gateway/daou/readme.mdx @@ -5,242 +5,231 @@ description: 키움페이 연동 방법을 안내합니다. import Figure from "~/components/Figure.astro"; import ContentRef from "~/components/gitbook/ContentRef.astro"; -import Hint from "~/components/Hint.astro"; -import Tabs from "~/components/gitbook/tabs/Tabs.astro"; import Tab from "~/components/gitbook/tabs/Tab.astro"; +import Tabs from "~/components/gitbook/tabs/Tabs.astro"; +import Hint from "~/components/Hint.astro"; -### 1. 키움페이 채널 설정하기 +## 1. 키움페이 채널 설정하기 [결제대행사 채널 설정하기](../../ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다.
-### 2.결제 요청하기 +## 2.결제 요청하기 -[JavaScript SDK](../../../sdk/javascript-sdk-old/readme) `IMP.request_pay(param, callback)`을 호출하여 다우 페이조아 결제창을 호출할 수 있습니다. **결제 결과**는 PC의 경우 `IMP.request_pay(param, callback)` 호출 후 **callback**으로 수신되고 모바일의 경우 **m_redirect_url**로 리디렉션됩니다. +[JavaScript SDK](../../../sdk/javascript-sdk-old/readme) `IMP.request_pay(param, callback)`을 호출하여 다우 페이조아 결제창을 호출할 수 있습니다. **결제 결과**는 PC의 경우 `IMP.request_pay(param, callback)` 호출 후 **callback**으로 수신되고 모바일의 경우 **m\_redirect\_url**로 리디렉션됩니다. -**페이조아 결제창 연동을 위해서는 ****JS SDK Version 1.2.0**** 이상을 사용하셔야 합니다.** - + **페이조아 결제창 연동을 위해서는 ****JS SDK Version 1.2.0**** 이상을 사용하셔야 합니다.** - - -```javascript title="Javascript SDK" -IMP.request_pay( - { - pg: "daou.{상점 ID}", - pay_method: "card", - merchant_uid: "mid_1234567890", - escrow: false, - amount: 1004, - name: "노스페이스 롱패딩 M", - buyer_name: "홍길동", - buyer_email: "hello@world.com", - buyer_tel: "01012345678", - digital: false, // 디지털로 계약되었다면 true로 설정 - m_redirect_url: "https://allerts.com/payments/complete", - bypass: { - // 키움페이 전용 파라미터 - daou: { - PRODUCTCODE: "portone", - CASHRECEIPTFLAG: 0, + + ```javascript title="Javascript SDK" + IMP.request_pay( + { + pg: "daou.{상점 ID}", + pay_method: "card", + merchant_uid: "mid_1234567890", + escrow: false, + amount: 1004, + name: "노스페이스 롱패딩 M", + buyer_name: "홍길동", + buyer_email: "hello@world.com", + buyer_tel: "01012345678", + digital: false, // 디지털로 계약되었다면 true로 설정 + m_redirect_url: "https://allerts.com/payments/complete", + bypass: { + // 키움페이 전용 파라미터 + daou: { + PRODUCTCODE: "portone", + CASHRECEIPTFLAG: 0, + }, + }, + app_scheme: "portoneappscheme", }, - }, - app_scheme: "portoneappscheme", - }, - function (rsp) { - // callback 로직 - // * ...중략... * - } -); -``` - -**주요 파라미터 설명** - -**`pg` \*****string** + function (rsp) { + // callback 로직 + // * ...중략... * + }, + ); + ``` -**PG사 구분코드** + **주요 파라미터 설명** -**`daou`** 로 지정하면 됩니다. + **`pg` \*****string** -**`pay_method`** **\*** **string** + **PG사 구분코드** -**결제수단 구분코드** + **`daou`** 로 지정하면 됩니다. -- card(신용카드) -- trans(실시간 계좌이체) -- vbank(가상계좌) + **`pay_method`** **\*** **string** -**`merchant_uid`** **\*** **string** + **결제수단 구분코드** -**주문번호** + - card(신용카드) + - trans(실시간 계좌이체) + - vbank(가상계좌) -매번 고유하게 채번되어야 합니다. + **`merchant_uid`** **\*** **string** -**`digital`** **\*** **`string`** + **주문번호** -**디지털 컨텐츠 여부** + 매번 고유하게 채번되어야 합니다. -고객사 \<-\> 페이조아간 계약 상태에 따라 정해진 올바른 값을 넣어야 함. 그렇지 않은 경우 결제 진행 불가 + **`digital`** **\*** **`string`** -**`bypass.daou.PRODUCTCODE`** **`string`** + **디지털 컨텐츠 여부** -**결제 상품 고유 번호** + 고객사 \<-> 페이조아간 계약 상태에 따라 정해진 올바른 값을 넣어야 함. 그렇지 않은 경우 결제 진행 불가 -값에 대해 정해진 규격이 없고 보내지 않을 경우 포트원에서 기본값(iamport)을 설정해 페이조아 측으로 전달 + **`bypass.daou.PRODUCTCODE`** **`string`** -**`bypass.daou.CASHRECEIPTFLAG`** **``****`number`** + **결제 상품 고유 번호** -**현금영수증 발급 구분코드** + 값에 대해 정해진 규격이 없고 보내지 않을 경우 포트원에서 기본값(iamport)을 설정해 페이조아 측으로 전달 -비 신용결제(계좌,가상)시 페이조아에서 자동발급 여부 구분코드 + **`bypass.daou.CASHRECEIPTFLAG`** **\`\`****`number`** -**`1`: 허용** + **현금영수증 발급 구분코드** -**`0`: 차단** + 비 신용결제(계좌,가상)시 페이조아에서 자동발급 여부 구분코드 -**`app_scheme`** **`string`** + **`1`: 허용** -**모바일 앱 URL Scheme** + **`0`: 차단** -모바일 앱 환경에서 결제시 필수 파라미터 + **`app_scheme`** **`string`** -**`amount` \*****number** + **모바일 앱 URL Scheme** -**결제금액** + 모바일 앱 환경에서 결제시 필수 파라미터 -**string** 이 아닌 점에 유의하세요. + **`amount` \*****number** -**`escrow`** **`boolean`** + **결제금액** -**에스크로 설정여부** + **string** 이 아닌 점에 유의하세요. -계좌이체,가상계좌만 지원됩니다. + **`escrow`** **`boolean`** - + **에스크로 설정여부** - -**API 방식으로 빌링키 발급,결제요청,예약결제를 구현할수 있습니다.** + 계좌이체,가상계좌만 지원됩니다. + -**일회성 결제 요청하기** + + **API 방식으로 빌링키 발급,결제요청,예약결제를 구현할수 있습니다.** -REST[ **API POST /subscribe/payments/onetime**](../../../api/api-4/api-1)을 호출하여 일회성 결제를 요청합니다. 요청 시 전달된 카드는 포트원에 등록되지 않습니다. + **일회성 결제 요청하기** -```sh -curl -H "Content-Type: application/json" \ - -X POST -d '{"merchant_uid":"order_id_8237352", "card_number":"1234-1234-1234-1234", "expiry":"2019-01", "birth":"123456", "amount":3000}' \ - https://api.iamport.kr/subscribe/payments/onetime -``` + REST[**API POST /subscribe/payments/onetime**](../../../api/api-4/api-1)을 호출하여 일회성 결제를 요청합니다. 요청 시 전달된 카드는 포트원에 등록되지 않습니다. -**빌링키 발급 요청하기** + ```sh + curl -H "Content-Type: application/json" \ + -X POST -d '{"merchant_uid":"order_id_8237352", "card_number":"1234-1234-1234-1234", "expiry":"2019-01", "birth":"123456", "amount":3000}' \ + https://api.iamport.kr/subscribe/payments/onetime + ``` -REST [**API POST /subscribe/customers/\{customer_uid}**](../../../api/api-2/api-1)를 호출하여 빌링키 발급을 요청합니다. + **빌링키 발급 요청하기** -```sh -curl -H "Content-Type: application/json" \ - -X POST -d '{"card_number":"1234-1234-1234-1234", "expiry":"2025-12", "birth":"820213", "pwd_2digit":"00"}' \ - https://api.iamport.kr/subscribe/customers/your-customer-unique-id -``` + REST [**API POST /subscribe/customers/\{customer\_uid}**](../../../api/api-2/api-1)를 호출하여 빌링키 발급을 요청합니다. -**빌링키 발급 및 최초 결제 요청하기** + ```sh + curl -H "Content-Type: application/json" \ + -X POST -d '{"card_number":"1234-1234-1234-1234", "expiry":"2025-12", "birth":"820213", "pwd_2digit":"00"}' \ + https://api.iamport.kr/subscribe/customers/your-customer-unique-id + ``` -REST [**API POST /subscribe/payments/onetime**](../../../api/api-4/api-1)을 호출하여 빌링키 발급과 최초 결제를 요청합니다. + **빌링키 발급 및 최초 결제 요청하기** -- **`customer_uid`** : 빌링키 등록을 위해서 지정해야 합니다. + REST [**API POST /subscribe/payments/onetime**](../../../api/api-4/api-1)을 호출하여 빌링키 발급과 최초 결제를 요청합니다. -```sh -curl -H "Content-Type: application/json" \ - -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "card_number":"1234-1234-1234-1234", "expiry":"2019-01", "birth":"123456", "amount":3000}' \ - https://api.iamport.kr/subscribe/payments/onetime -``` + - **`customer_uid`** : 빌링키 등록을 위해서 지정해야 합니다. -**빌링키로 결제 요청하기** + ```sh + curl -H "Content-Type: application/json" \ + -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "card_number":"1234-1234-1234-1234", "expiry":"2019-01", "birth":"123456", "amount":3000}' \ + https://api.iamport.kr/subscribe/payments/onetime + ``` -빌링키 발급과 최초 결제가 성공하면 빌링키는 전달된 `customer_uid` 와 1:1 매칭되어 포트원에 저장됩니다. 보안상의 이유로 서버는 빌링키에 직접 접근할 수 없기 때문에 `customer_uid`를 이용해서 재결제([**POST /subscribe/payments/again**](../../../api/api-4/api)) REST API를 다음과 같이 호출합니다. + **빌링키로 결제 요청하기** -```sh -curl -H "Content-Type: application/json" \ - -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "amount":3000}' \ - https://api.iamport.kr/subscribe/payments/again -``` + 빌링키 발급과 최초 결제가 성공하면 빌링키는 전달된 `customer_uid` 와 1:1 매칭되어 포트원에 저장됩니다. 보안상의 이유로 서버는 빌링키에 직접 접근할 수 없기 때문에 `customer_uid`를 이용해서 재결제([**POST /subscribe/payments/again**](../../../api/api-4/api)) REST API를 다음과 같이 호출합니다. -**자세한 가이드는 아래 링크를 참조하세요** + ```sh + curl -H "Content-Type: application/json" \ + -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "amount":3000}' \ + https://api.iamport.kr/subscribe/payments/again + ``` - + **자세한 가이드는 아래 링크를 참조하세요** - + + -### 3. 부가기능 +## 3. 부가기능 - -```javascript title="javascript" -display: { - card_quota: [6] // 할부개월 6개월까지만 활성화 -} -``` - -**파라미터 설명** - -- **`card_quota` :** - - `[]`: 일시불만 결제 가능 - - `2,3,4,5,6`: 일시불을 포함한 2, 3, 4, 5, 6개월까지 할부개월 선택 가능 - - - -할부결제는 **5만원 이상 결제 요청시**에만 이용 가능합니다. - - - - - - -```javascript title="javascript" -card: { - direct: { - code: "367", - quota: 3 - } -} -``` - -**파라미터 설명** - -- **`code`** : 카드사 금융결제원 표준 코드. [**링크**](https://faq.portone.io/6503bcb4-4a61-4cf3-afd8-5d913b1385a6) 참조 (**string**) -- **`quota`** : 할부 개월 수. 일시불일 시 0으로 지정 (**number**) - - - - -에스크로 결제를 위해서는 **`escrow`** 파라미터를 추가하고 **true** 값으로 설정해야 합니다. 에스크로 결제가 완료되면 고객사는 배송정보 등록을 진행해야 하며 해당 작업이 누락되는 경우 **정산이 진행되지 않습니다**. [**배송정보 등록**](../../../api/api-7/api-1) 및 [**배송수정 API**](../../../api/api-7/api-2) 를 이용하여 배송정보를 관리할 수 있습니다. - -```json title="API Body 예시" -{ - "logis": { - "invoice": "1728384716123", - "company": "CJGLS", - "receiving_at": "20220215", - "address": "성수이로20길16" - }, - "receiver": { - "name": "홍길동" - }, - "sender": { - "relationship": "본인" - } -} -``` - - - -**주의사항** - -- 에스크로 배송정보 등록/수정 시 고객사가 전달한 배송정보(운송장 번호, 택배사 이름 등)에 대해 페이조아 측에서 유효성 체크를 하지 않습니다. - - - - + + ```javascript title="javascript" + display: { + card_quota: [6]; // 할부개월 6개월까지만 활성화 + } + ``` + + **파라미터 설명** + + - **`card_quota` :** + - `[]`: 일시불만 결제 가능 + - `2,3,4,5,6`: 일시불을 포함한 2, 3, 4, 5, 6개월까지 할부개월 선택 가능 + + + 할부결제는 **5만원 이상 결제 요청시**에만 이용 가능합니다. + + + + + ```json title="javascript" + card: { + direct: { + code: "367", + quota: 3 + } + } + ``` + + **파라미터 설명** + + - **`code`** : 카드사 금융결제원 표준 코드. [**링크**](https://faq.portone.io/6503bcb4-4a61-4cf3-afd8-5d913b1385a6) 참조 (**string**) + - **`quota`** : 할부 개월 수. 일시불일 시 0으로 지정 (**number**) + + + + 에스크로 결제를 위해서는 **`escrow`** 파라미터를 추가하고 **true** 값으로 설정해야 합니다. 에스크로 결제가 완료되면 고객사는 배송정보 등록을 진행해야 하며 해당 작업이 누락되는 경우 **정산이 진행되지 않습니다**. [**배송정보 등록**](../../../api/api-7/api-1) 및 [**배송수정 API**](../../../api/api-7/api-2) 를 이용하여 배송정보를 관리할 수 있습니다. + + ```json title="API Body 예시" + { + "logis": { + "invoice": "1728384716123", + "company": "CJGLS", + "receiving_at": "20220215", + "address": "성수이로20길16" + }, + "receiver": { + "name": "홍길동" + }, + "sender": { + "relationship": "본인" + } + } + ``` + + + **주의사항** + + - 에스크로 배송정보 등록/수정 시 고객사가 전달한 배송정보(운송장 번호, 택배사 이름 등)에 대해 페이조아 측에서 유효성 체크를 하지 않습니다. + + diff --git a/src/content/docs/ko/pg/payment-gateway/eximbay.mdx b/src/content/docs/ko/pg/payment-gateway/eximbay.mdx index 1a29f71f8..38fbf49e1 100644 --- a/src/content/docs/ko/pg/payment-gateway/eximbay.mdx +++ b/src/content/docs/ko/pg/payment-gateway/eximbay.mdx @@ -3,151 +3,157 @@ title: 엑심베이 description: 엑심베이 결제 연동 방법을 안내합니다. --- -import Details from "~/components/gitbook/Details.astro"; import Figure from "~/components/Figure.astro"; -import Hint from "~/components/Hint.astro"; -import Tabs from "~/components/gitbook/tabs/Tabs.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"; -### 1. 엑심베이 채널 설정하기 +## 1. 엑심베이 채널 설정하기 [결제대행사 채널 설정하기](../../ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다.
-### 2.결제 요청하기 +## 2.결제 요청하기 [JavaScript SDK](../../sdk/javascript-sdk-old/readme) `IMP.request_pay(param, callback)`을 호출하여 -엑심베이 결제창을 호출할 수 있습니다. **결제결과**는 **PC / 모바일** 모두 **callback** 으로 전달됩니다. +엑심베이 결제창을 호출할 수 있습니다. **결제결과**는 **PC / 모바일** 모두 **callback** 으로 전달됩니다. - -```javascript title="Javascript SDK" -IMP.request_pay({ - pg: "eximbay.{상점 ID}", - pay_method: "card", - merchant_uid: "order_no_0001", // 상점에서 관리하는 주문 번호 - name: "주문명:결제테스트", - amount: 14.20, - currency: "USD", // 기본값: USD(원화 KRW는 페이팔 정책으로 인해 지원하지 않음) - buyer_email: "test@portone.io", - buyer_name: "구매자이름", - buyer_tel: "010-1234-5678", - buyer_addr: "서울특별시 강남구 삼성동", - buyer_postcode: "123-456", - popup:false // 팝업창 활성 비활성화 컨트롤 -}, function(rsp) { // callback 로직 - /* ...중략... */ -}); -``` - -**주요 파라미터 설명** - -**`pg` \*****string** - -**PG사 구분코드** - -**`eximbay`** 로 지정하면 됩니다. - -**`pay_method`** **\*** **string** - -**결제수단 구분코드** - -- 신용카드: `card` -- 알리페이 / 알리페이 플러스: `alipay` (상점아이디 설정에 따라 알리페이 혹은 알리페이 플러스로 호출됩니다. ) -- 해외카드: `card` -- 유니온페이: `unionpay` -- 텐페이: `tenpay` -- 일본 편의점결제(eContext): `econtext` -- 위챗페이: `wechat` -- 몰페이: `molpay` - -**`merchant_uid`** **\*** **string** - -**`고객사 주문번호`** - -매번 고유하게 채번되어야 합니다. - -**`buyer_tel`** **\*** **`string`** - -**`주문자 연락처`** - -**`amount`** **\*** **`integer`** - -**결제금액** - -**string** 이 아닌점에 유의하세요 - -**`currency`** **`string`** - -**결제통화코드** - -- KRW -- USD -- EUR -- GBP -- JPY -- THB -- SGD -- RUB -- HKD -- CAD -- AUD -- CNY -- TWD -- MYR -- VND -- PHP -- MNT -- NZD -- AED -- MOP -- BRL -- KZT -- NOK -- SAR -- TRY - -**`language`** **`string`** - -- 한국어 : ko -- 영어 : en -- 중국어 : zh -- 일본어 : jp - - + + ```javascript title="Javascript SDK" + IMP.request_pay( + { + pg: "eximbay.{상점 ID}", + pay_method: "card", + merchant_uid: "order_no_0001", // 상점에서 관리하는 주문 번호 + name: "주문명:결제테스트", + amount: 14.2, + currency: "USD", // 기본값: USD(원화 KRW는 페이팔 정책으로 인해 지원하지 않음) + buyer_email: "test@portone.io", + buyer_name: "구매자이름", + buyer_tel: "010-1234-5678", + buyer_addr: "서울특별시 강남구 삼성동", + buyer_postcode: "123-456", + popup: false, // 팝업창 활성 비활성화 컨트롤 + }, + function (rsp) { + // callback 로직 + /* ...중략... */ + }, + ); + ``` + + **주요 파라미터 설명** + + **`pg` \*****string** + + **PG사 구분코드** + + **`eximbay`** 로 지정하면 됩니다. + + **`pay_method`** **\*** **string** + + **결제수단 구분코드** + + - 신용카드: `card` + - 알리페이 / 알리페이 플러스: `alipay` (상점아이디 설정에 따라 알리페이 혹은 알리페이 플러스로 호출됩니다. ) + - 해외카드: `card` + - 유니온페이: `unionpay` + - 텐페이: `tenpay` + - 일본 편의점결제(eContext): `econtext` + - 위챗페이: `wechat` + - 몰페이: `molpay` + + **`merchant_uid`** **\*** **string** + + **`고객사 주문번호`** + + 매번 고유하게 채번되어야 합니다. + + **`buyer_tel`** **\*** **`string`** + + **`주문자 연락처`** + + **`amount`** **\*** **`integer`** + + **결제금액** + + **string** 이 아닌점에 유의하세요 + + **`currency`** **`string`** + + **결제통화코드** + + - KRW + - USD + - EUR + - GBP + - JPY + - THB + - SGD + - RUB + - HKD + - CAD + - AUD + - CNY + - TWD + - MYR + - VND + - PHP + - MNT + - NZD + - AED + - MOP + - BRL + - KZT + - NOK + - SAR + - TRY + + **`language`** **`string`** + + - 한국어 : ko + - 영어 : en + - 중국어 : zh + - 일본어 : jp + -**참고사항** - -포트원은 엑심베이 정기결제를 지원하지 않습니다. + **참고사항** + 포트원은 엑심베이 정기결제를 지원하지 않습니다.
-

편의점 결제 테스트 방법

+

편의점 결제 테스트 방법

+ + **편의점결제 동작 방식** + + 한국의 가상계좌와 같이 결제창 내에서는 등록을 한 다음에 고객에게 이메일 / 문자로 전달되는 화면을 편의점 카운터에서 지불하며 처리합니다. + + - 포트원 내부에서는 `pay_method: "vbank"` 로 기록됨 + - Econtext 등록이 완료되었다는 콜백함수 및 웹훅 전송 (`status: "ready"` 상태 / `vbank_num`은 `unknown`으로 고정) + - Econtext 로부터 입금확인이 되면 포트원에서 엑심베이로부터 응답을 받아 `status: "paid"`로 변경 후 결제완료처리에 대한 웹훅 전송 + + **편의점결제 테스트 진행순서** + + 가상계좌와 같이 실제 고객이 입금한 결과를 테스트해야 하므로 아래와 같이 입금완료됨을 임의적으로 통지받아보실 수 있습니다. -**편의점결제 동작 방식** + 1. 엑심베이 테스트모드 ON상태에서 1번과 같이 결제창 진행 -한국의 가상계좌와 같이 결제창 내에서는 등록을 한 다음에 고객에게 이메일 / 문자로 전달되는 화면을 편의점 카운터에서 지불하며 처리합니다. + 2. 콜백 응답 중 `pg_tid` 값을 별도로 메모 (포트원 관리자콘솔 PG사승인번호 컬럼에서 확인 가능) -- 포트원 내부에서는 `pay_method: "vbank"` 로 기록됨 -- Econtext 등록이 완료되었다는 콜백함수 및 웹훅 전송 (`status: "ready"` 상태 / `vbank_num`은 `unknown`으로 고정) -- Econtext 로부터 입금확인이 되면 포트원에서 엑심베이로부터 응답을 받아 `status: "paid"`로 변경 후 결제완료처리에 대한 웹훅 전송 + 3. [http://test.econ.ne.jp/site/tuchi\_2/tuchi\_menu\_2.html](http://test.econ.ne.jp/site/tuchi_2/tuchi_menu_2.html)로 이동 후 계정 로그인 + (아이디 : `ectest` / 비번 : `#eg0810#`) -**편의점결제 테스트 진행순서** + 4. ShopID : `361301`, orderID : 2번에서 확보한 PG사승인번호 입력 -가상계좌와 같이 실제 고객이 입금한 결과를 테스트해야 하므로 아래와 같이 입금완료됨을 임의적으로 통지받아보실 수 있습니다. + 5. 하단에 있는 **`登録`** 버튼 클릭 -1. 엑심베이 테스트모드 ON상태에서 1번과 같이 결제창 진행 -2. 콜백 응답 중 `pg_tid` 값을 별도로 메모 (포트원 관리자콘솔 PG사승인번호 컬럼에서 확인 가능) -3. [http://test.econ.ne.jp/site/tuchi_2/tuchi_menu_2.html](http://test.econ.ne.jp/site/tuchi_2/tuchi_menu_2.html)로 이동 후 계정 로그인 - (아이디 : `ectest` / 비번 : `#eg0810#`) -4. ShopID : `361301`, orderID : 2번에서 확보한 PG사승인번호 입력 -5. 하단에 있는 **`登録`** 버튼 클릭 -6. 다음 페이지에서 한 번 더 **`登録`** 클릭 -7. 10분 후 결제상태가 `status: "paid"`로 바뀌는지 확인 (이 때 입금에 대한 웹훅 발송됨) + 6. 다음 페이지에서 한 번 더 **`登録`** 클릭 + 7. 10분 후 결제상태가 `status: "paid"`로 바뀌는지 확인 (이 때 입금에 대한 웹훅 발송됨)
diff --git a/src/content/docs/ko/pg/payment-gateway/kg.mdx b/src/content/docs/ko/pg/payment-gateway/kg.mdx index 5f57668fb..591647dad 100644 --- a/src/content/docs/ko/pg/payment-gateway/kg.mdx +++ b/src/content/docs/ko/pg/payment-gateway/kg.mdx @@ -3,11 +3,11 @@ title: KG모빌리언스 description: KG모빌리언스 결제 연동 방법을 안내합니다. --- -import Codepen from "~/components/gitbook/Codepen.astro"; import Figure from "~/components/Figure.astro"; +import Codepen from "~/components/gitbook/Codepen.astro"; import Hint from "~/components/Hint.astro"; -### 1. KG모빌리언스 채널 설정하기 +## 1. KG모빌리언스 채널 설정하기 [결제대행사 채널 설정하기](../../ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다. @@ -35,11 +35,11 @@ IMP.request_pay( function (rsp) { // callback 로직 //* ...중략... *// - } + }, ); ``` -#### 주요 파라미터 설명 +### 주요 파라미터 설명 **`pg` \*****string** @@ -91,7 +91,7 @@ IMP.request_pay( } else { alert("빌링키 발급 실패"); } - } + }, ); ``` @@ -103,7 +103,7 @@ IMP.request_pay( -#### 주요 파라미터 설명 +### 주요 파라미터 설명 **`pg` \*****string** @@ -125,7 +125,7 @@ IMP.request_pay( (실 결제를 발생시키기 위해서는 **`customer_uid`** 로 **REST API 를 이용하여 결제를 요청**해주셔야 합니다.) -#### 빌링키(`customer_uid`)로 결제 요청하기 +### 빌링키(`customer_uid`)로 결제 요청하기 빌링키 발급이 성공하면 실 빌링키는 `customer_uid` 와 1:1 매칭되어 **포트원 서버에 저장**됩니다. `customer_uid`를 고객사 내부서버에 저장하시고 [**비 인증 결제요청 REST API**](../../api/api-4/api) 를 호출하시면 결제를 발생시킬 수 있습니다. diff --git a/src/content/docs/ko/pg/payment-gateway/ksnet/warning.mdx b/src/content/docs/ko/pg/payment-gateway/ksnet/warning.mdx index b1508baa7..5f82f77c7 100644 --- a/src/content/docs/ko/pg/payment-gateway/ksnet/warning.mdx +++ b/src/content/docs/ko/pg/payment-gateway/ksnet/warning.mdx @@ -7,142 +7,151 @@ import Details from "~/components/gitbook/Details.astro"; import Hint from "~/components/Hint.astro";
-

계약 확인사항

+

계약 확인사항

-**포트원을 통한 KSNET 이용 고객사의 상점아이디 과세 설정은 반드시 `복합과세`로 설정되어 있어야 합니다. 일반과세, 면세 설정은 지원하지 않습니다.** + **포트원을 통한 KSNET 이용 고객사의 상점아이디 과세 설정은 반드시 `복합과세`로 설정되어 있어야 합니다. 일반과세, 면세 설정은 지원하지 않습니다.** -- 키인결제 -- 고객사 분담 무이자 할부 설정 -- 가상계좌 마감일시 지정 -- 가상계좌 환불 -- 간편결제 사용 -- 할부 사용 -- 에스크로 사용, 배송 에스크로만 지원 - - KSNET에서 일반 에스크로, 배송 에스크로 두 가지 유형의 에스크로를 제공합니다. 포트원을 통해 KSNET 에스크로를 사용하려는 경우 반드시 **배송 에스크로** 설정이 되어 있어야 합니다. -- 휴대폰 결제 시 상품 유형 설정(실물 혹은 디지털) + - 키인결제 -
+ - 고객사 분담 무이자 할부 설정 -
-

특정카드사 고객사 분담 무이자 할부 설정 불가

+ - 가상계좌 마감일시 지정 + + - 가상계좌 환불 + + - 간편결제 사용 -KSNET에서 고객사 분담 무이자 할부 설정에 필요한 카드 코드 정보를 일부 카드사에 대해서만 제공하고 있습니다. 카드코드가 제공되지 않는 일부 카드사의 경우 고객사 부담 무이자 할부를 설정할 수 없습니다. + - 할부 사용 + - 에스크로 사용, 배송 에스크로만 지원 + - KSNET에서 일반 에스크로, 배송 에스크로 두 가지 유형의 에스크로를 제공합니다. 포트원을 통해 KSNET 에스크로를 사용하려는 경우 반드시 **배송 에스크로** 설정이 되어 있어야 합니다. + + - 휴대폰 결제 시 상품 유형 설정(실물 혹은 디지털)
-

계좌이체

+

특정카드사 고객사 분담 무이자 할부 설정 불가

-#### 결제창에서 현금영수증 발급 시 사업자번호, 휴대폰 번호에 숫자만 입력해야합니다. + KSNET에서 고객사 분담 무이자 할부 설정에 필요한 카드 코드 정보를 일부 카드사에 대해서만 제공하고 있습니다. 카드코드가 제공되지 않는 일부 카드사의 경우 고객사 부담 무이자 할부를 설정할 수 없습니다. +
-계좌이체 결제창을 통한 현금영수증 발급 시 휴대폰번호, 사업자 번호는 **숫자만** 입력해야 합니다. 하이픈(-)을 포함한 다른 문자가 포함되는 경우 별다른 에러 표시 없이 결제는 진행되지만 현금영수증이 발급되지 않습니다. +
+

계좌이체

+ ## 결제창에서 현금영수증 발급 시 사업자번호, 휴대폰 번호에 숫자만 입력해야합니다. + + 계좌이체 결제창을 통한 현금영수증 발급 시 휴대폰번호, 사업자 번호는 **숫자만** 입력해야 합니다. 하이픈(-)을 포함한 다른 문자가 포함되는 경우 별다른 에러 표시 없이 결제는 진행되지만 현금영수증이 발급되지 않습니다.
-

가상계좌

- -#### 예금주명 지정 불가 +

가상계좌

-가상계좌의 예금주명은 고객사명으로 고정되며 별도 지정이 불가합니다. + ## 예금주명 지정 불가 -#### 부가세, 면세 금액 설정 지원 안 함 + 가상계좌의 예금주명은 고객사명으로 고정되며 별도 지정이 불가합니다. -KSNET는 일회성 가상계좌의 경우 부가세, 면세 금액 설정을 지원하지 않습니다. + ## 부가세, 면세 금액 설정 지원 안 함 -#### 가상계좌 입금기한은 필수 입력 항목 + KSNET는 일회성 가상계좌의 경우 부가세, 면세 금액 설정을 지원하지 않습니다. -KSNET에서 가상계좌 입금기한은 선택 입력 항목으로 안내하고 있지만 입력하지 않을 경우 가상계좌 입금기한을 특정할 수 없고 오동작할 가능성이 있어 필수로 입력해야합니다. (포트원에서는 필수 값으로 제한하고 있습니다.) + ## 가상계좌 입금기한은 필수 입력 항목 -#### 가상계좌 입금기한은 **초 단위 UNIX TIMESTAMP 사용** + KSNET에서 가상계좌 입금기한은 선택 입력 항목으로 안내하고 있지만 입력하지 않을 경우 가상계좌 입금기한을 특정할 수 없고 오동작할 가능성이 있어 필수로 입력해야합니다. (포트원에서는 필수 값으로 제한하고 있습니다.) -`vbank_due` 파라미터로 전달하는 가상계좌 입금기한은 초 단위의 UNIX TIMESTAMP(통상 10자리 자연수)로 입력하여야 합니다. (`api로 가상계좌를 발급하는 경우에만 해당합니다.`) + ## 가상계좌 입금기한은 **초 단위 UNIX TIMESTAMP 사용** + `vbank_due` 파라미터로 전달하는 가상계좌 입금기한은 초 단위의 UNIX TIMESTAMP(통상 10자리 자연수)로 입력하여야 합니다. (`api로 가상계좌를 발급하는 경우에만 해당합니다.`)
-

에스크로 서비스

- -### 주문자 이메일 필수 입력 +

에스크로 서비스

-구매 확인을 받기 위한 주문자 이메일을 필수로 입력하여야 합니다. + ## 주문자 이메일 필수 입력 -### 등록 소요 시간 존재 + 구매 확인을 받기 위한 주문자 이메일을 필수로 입력하여야 합니다. -에스크로 거래는 30분 \~ 1시간 뒤 [ksta.ksnet.co.kr](http://ksta.ksnet.co.kr/) > PG 거래내역 > 배송 에스크로 거래조회에서 확인이 가능합니다. 에스크로 정보 수정의 경우도 등록이 완료된 이후부터 가능합니다. + ## 등록 소요 시간 존재 -### 배송정보 발송일시는 **초 단위 UNIX TIMESTAMP 사용** + 에스크로 거래는 30분 \~ 1시간 뒤 [ksta.ksnet.co.kr](http://ksta.ksnet.co.kr/) > PG 거래내역 > 배송 에스크로 거래조회에서 확인이 가능합니다. 에스크로 정보 수정의 경우도 등록이 완료된 이후부터 가능합니다. -`logis.sent_at` 파라미터로 전달하는 배송정보 발송일시는 초 단위의 UNIX TIMESTAMP(통상 10자리 자연수)로 입력하여야 합니다. + ## 배송정보 발송일시는 **초 단위 UNIX TIMESTAMP 사용** + `logis.sent_at` 파라미터로 전달하는 배송정보 발송일시는 초 단위의 UNIX TIMESTAMP(통상 10자리 자연수)로 입력하여야 합니다.
-

키인결제

+

키인결제

-판매 상품에 대한 구분값으로 **`product_type`** 파라미터를 사용해야 결제가 가능합니다. + 판매 상품에 대한 구분값으로 **`product_type`** 파라미터를 사용해야 결제가 가능합니다. -고객사 분담 무이자를 원하시는 경우 PG사와의 별도의 계약 후 **`interest_free_by_merchant`** 파라미터를 사용해야 합니다. + 고객사 분담 무이자를 원하시는 경우 PG사와의 별도의 계약 후 **`interest_free_by_merchant`** 파라미터를 사용해야 합니다. -카드번호와 유효기간만으로 결제를 요청하는 비인증 승인 API만 연동되어 있어 - -**`birth`**(생년월일 6자리 혹은 사업자 등록번호 10자리)와 **`pwd_2digit`**(비밀번호 앞 2자리)는 검증하지 않습니다. + 카드번호와 유효기간만으로 결제를 요청하는 비인증 승인 API만 연동되어 있어 + **`birth`**(생년월일 6자리 혹은 사업자 등록번호 10자리)와 **`pwd_2digit`**(비밀번호 앞 2자리)는 검증하지 않습니다.
-

빌링키 결제

- -판매 상품에 대한 구분값으로 **`product_type`** 을 파라미터로 사용해야 결제가 가능합니다. +

빌링키 결제

-고객사 분담 무이자를 원하시는 경우 pg 사와의 별도의 계약 후 **`interest_free_by_merchant`** 파라미터를 사용해야 합니다. + 판매 상품에 대한 구분값으로 **`product_type`** 을 파라미터로 사용해야 결제가 가능합니다. + 고객사 분담 무이자를 원하시는 경우 pg 사와의 별도의 계약 후 **`interest_free_by_merchant`** 파라미터를 사용해야 합니다.
-

빌링키 등록

- -`card_number`, `expiry`, `pwd_2digit`, `birth` 파라미터 입력은 필수 입니다. +

빌링키 등록

+ `card_number`, `expiry`, `pwd_2digit`, `birth` 파라미터 입력은 필수 입니다.
-

기타

- -- 휴대폰 결제는 부분취소 불가능. -- 카드, 간편결제 외 결제의 경우 매출 전표 확인 불가능. -- 간편결제(카카오페이, 페이코) 카드 결제의 경우 KSNET 측에서 카드정보(카드번호, bin) 정보를 제공해주지 않아 결제 정보에 카드사 정보가 제공되지 않습니다. -- USD 결제는 순수 해외카드로만 결제 가능합니다. -- 카카오페이 사용 시 상점정보(대표자명, 주소, 전화번호)를 필수로 입력해야합니다 -- 부분취소는 총 9회까지 가능합니다. (카드결제, 가상계좌, 계좌이체, 간편결제) -- 취소는 결제일 기준 6개월 이내에만 가능합니다. -- 가상계좌 환불은 23:00\~06:00 시간 외에만 가능합니다. -- 계좌입금 거래 시 결제창에서 발급한 현금영수증은 경우 거래 취소 시 자동으로 취소 되지 않습니다. -- 복합과세의 계좌입금 거래를 부분취소하는 경우 기존에 발급한 현금영수증을 취소하고 부분취소 금액이 반영된 금액 정보로 다시 현금영수증을 발급해야합니다. -- 매출 전표 확인 시 자동으로 인쇄 기능이 호출됩니다. 오동작이 아닌 KSNET의 의도된 기능입니다. -- 간편 결제 수단에서 고객사 분담 무이자 설정은 사용 불가능합니다. -- 간편 결제 수단에서 할부 개월 수 표시 설정은 일부 간편결제사에서만 가능합니다. - - 네이버페이, 카카오페이, LPay: 할부 개월 수 표시 설정 가능 - - Payco, SSGPay: 할부 개월 수 표시 설정 불가, 5만원 이상 시 1\~12 개월 표시 고정 +

기타

+ - 휴대폰 결제는 부분취소 불가능. + + - 카드, 간편결제 외 결제의 경우 매출 전표 확인 불가능. + + - 간편결제(카카오페이, 페이코) 카드 결제의 경우 KSNET 측에서 카드정보(카드번호, bin) 정보를 제공해주지 않아 결제 정보에 카드사 정보가 제공되지 않습니다. + + - USD 결제는 순수 해외카드로만 결제 가능합니다. + + - 카카오페이 사용 시 상점정보(대표자명, 주소, 전화번호)를 필수로 입력해야합니다 + + - 부분취소는 총 9회까지 가능합니다. (카드결제, 가상계좌, 계좌이체, 간편결제) + + - 취소는 결제일 기준 6개월 이내에만 가능합니다. + + - 가상계좌 환불은 23:00\~06:00 시간 외에만 가능합니다. + + - 계좌입금 거래 시 결제창에서 발급한 현금영수증은 경우 거래 취소 시 자동으로 취소 되지 않습니다. + + - 복합과세의 계좌입금 거래를 부분취소하는 경우 기존에 발급한 현금영수증을 취소하고 부분취소 금액이 반영된 금액 정보로 다시 현금영수증을 발급해야합니다. + + - 매출 전표 확인 시 자동으로 인쇄 기능이 호출됩니다. 오동작이 아닌 KSNET의 의도된 기능입니다. + + - 간편 결제 수단에서 고객사 분담 무이자 설정은 사용 불가능합니다. + + - 간편 결제 수단에서 할부 개월 수 표시 설정은 일부 간편결제사에서만 가능합니다. + - 네이버페이, 카카오페이, LPay: 할부 개월 수 표시 설정 가능 + - Payco, SSGPay: 할부 개월 수 표시 설정 불가, 5만원 이상 시 1\~12 개월 표시 고정
-특이사항 - -- 카드, 간편결제를 외 결제 수단 에서는 매출전표를 제공하지 않습니다. -- KSNET은 KRW, USD 만 지원합니다. -- USD 결제의 경우 순수 해외 카드만 결제 가능합니다. -- 페이코, 카카오페이의 경우 카드번호 혹은 카드bin 정보를 제공하지 않습니다. -- 주문자 이메일(`buyer_email`)은 선택 입력 항목이지만 에스크로 결제에서 구매확인 이메일 수신을 위해 필수로 입력해야 합니다. -- 카드, 간편결제 다이렉트 호출은 현재 지원하지 않습니다. -- 발급사가 비씨,국민,하나,삼성,신한,현대,롯데,농협인 경우에 `고객사 무이자 할부`를 설정할 수 있습니다. -- 결제 취소 시 부분취소는 9회까지 가능합니다. (카드결제, 가상계좌, 계좌이체) -- 취소는 결제일 기준으로 6개월까지만 가능합니다. -- 가상계좌 환불은 23:00\~06:00 시간 외에만 가능합니다. -- 가상계좌 환불은 특약이 있는 고객사만 사용 가능합니다. -- 휴대폰 결제는 부분취소를 지원하지 않습니다. -- 계좌입금 거래 시 발급한 현금영수증은 경우 거래 취소 시 자동으로 취소 되지 않습니다. 수동으로 취소해야 합니다. -- **포트원을 통한 KSNET 이용 고객사의 상점아이디 `복합과세` 및 `면세`만 지원합니다.** - + 특이사항 + + - 카드, 간편결제를 외 결제 수단 에서는 매출전표를 제공하지 않습니다. + - KSNET은 KRW, USD 만 지원합니다. + - USD 결제의 경우 순수 해외 카드만 결제 가능합니다. + - 페이코, 카카오페이의 경우 카드번호 혹은 카드bin 정보를 제공하지 않습니다. + - 주문자 이메일(`buyer_email`)은 선택 입력 항목이지만 에스크로 결제에서 구매확인 이메일 수신을 위해 필수로 입력해야 합니다. + - 카드, 간편결제 다이렉트 호출은 현재 지원하지 않습니다. + - 발급사가 비씨,국민,하나,삼성,신한,현대,롯데,농협인 경우에 `고객사 무이자 할부`를 설정할 수 있습니다. + - 결제 취소 시 부분취소는 9회까지 가능합니다. (카드결제, 가상계좌, 계좌이체) + - 취소는 결제일 기준으로 6개월까지만 가능합니다. + - 가상계좌 환불은 23:00\~06:00 시간 외에만 가능합니다. + - 가상계좌 환불은 특약이 있는 고객사만 사용 가능합니다. + - 휴대폰 결제는 부분취소를 지원하지 않습니다. + - 계좌입금 거래 시 발급한 현금영수증은 경우 거래 취소 시 자동으로 취소 되지 않습니다. 수동으로 취소해야 합니다. + - **포트원을 통한 KSNET 이용 고객사의 상점아이디 `복합과세` 및 `면세`만 지원합니다.** diff --git a/src/content/docs/ko/pg/payment-gateway/newtoss/readme.mdx b/src/content/docs/ko/pg/payment-gateway/newtoss/readme.mdx index 70f1dad66..718b62d11 100644 --- a/src/content/docs/ko/pg/payment-gateway/newtoss/readme.mdx +++ b/src/content/docs/ko/pg/payment-gateway/newtoss/readme.mdx @@ -5,9 +5,10 @@ description: 토스페이먼츠 (신모듈 / 2022-07-27 버전) 연동 방법을 import Figure from "~/components/Figure.astro"; 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 Tabs from "~/components/gitbook/tabs/Tabs.astro"; +import Hint from "~/components/Hint.astro"; + import image1 from "../_assets/tosspayments/tosspayments1.webp"; import image2 from "../_assets/tosspayments/tosspayments2.png"; import image3 from "../_assets/tosspayments/tosspayments3.png"; @@ -23,13 +24,12 @@ import image4 from "../_assets/tosspayments/tosspayments4.png"; 토스페이먼츠 신모듈 결제는 최신 SDK에서만 지원되는 기능입니다. -```javascript title="JS SDK" - +```html title="JS SDK" + ``` -**토스페이먼츠 신모듈을 연동하기 위해서는 위에 안내된 JS SDK를 이용하셔야 합니다** - + **토스페이먼츠 신모듈을 연동하기 위해서는 위에 안내된 JS SDK를 이용하셔야 합니다** [JavaScript SDK](../../../sdk/javascript-sdk/readme)문서를 통해 최신 SDK를 설치해주세요. @@ -43,336 +43,322 @@ import image4 from "../_assets/tosspayments/tosspayments4.png"; 토스페이먼츠 신 모듈을 기준으로 작성한 예시 코드는 아래와 같습니다. - - -```javascript showLineNumbers -const userCode = "고객사 식별코드"; -IMP.init(userCode); // 고객사 식별 코드를 넣어 모듈을 초기화해주세요. - -IMP.request_pay( - { - pg: "tosspayments", // 반드시 "tosspayments"임을 명시해주세요. - merchant_uid: "order_id_1667634130160", - name: "나이키 와플 트레이너 2 SD", - pay_method: "card", - escrow: false, - amount: "109000", - tax_free: 3000, - buyer_name: "홍길동", - buyer_email: "buyer@example.com", - buyer_tel: "02-1670-5176", - buyer_addr: "성수이로 20길 16", - buyer_postcode: "04783", - m_redirect_url: "https://helloworld.com/payments/result", // 모바일 환경에서 필수 입력 - notice_url: "https://helloworld.com/api/v1/payments/notice", - confirm_url: "https://helloworld.com/api/v1/payments/confirm", - currency: "KRW", - locale: "ko", - custom_data: { userId: 30930 }, - display: { card_quota: [0, 6] }, - appCard: false, - useCardPoint: true, - bypass: { - tosspayments: { - useInternationalCardOnly: true, // 영어 결제창 활성화 + + ```javascript showLineNumbers + const userCode = "고객사 식별코드"; + IMP.init(userCode); // 고객사 식별 코드를 넣어 모듈을 초기화해주세요. + + IMP.request_pay( + { + pg: "tosspayments", // 반드시 "tosspayments"임을 명시해주세요. + merchant_uid: "order_id_1667634130160", + name: "나이키 와플 트레이너 2 SD", + pay_method: "card", + escrow: false, + amount: "109000", + tax_free: 3000, + buyer_name: "홍길동", + buyer_email: "buyer@example.com", + buyer_tel: "02-1670-5176", + buyer_addr: "성수이로 20길 16", + buyer_postcode: "04783", + m_redirect_url: "https://helloworld.com/payments/result", // 모바일 환경에서 필수 입력 + notice_url: "https://helloworld.com/api/v1/payments/notice", + confirm_url: "https://helloworld.com/api/v1/payments/confirm", + currency: "KRW", + locale: "ko", + custom_data: { userId: 30930 }, + display: { card_quota: [0, 6] }, + appCard: false, + useCardPoint: true, + bypass: { + tosspayments: { + useInternationalCardOnly: true, // 영어 결제창 활성화 + }, + }, }, - }, - }, - (response) => { - // PC 환경에서 결제 프로세스 완료 후 실행 될 로직 - } -); -``` - -
-

주요 파라미터 설명

- -**`pg` \*****string** - -**PG사 구분코드** + (response) => { + // PC 환경에서 결제 프로세스 완료 후 실행 될 로직 + }, + ); + ``` -_tosspayments_ 로 지정하면 됩니다. +
+

주요 파라미터 설명

-**`pay_method`** **string** + **`pg` \*****string** -- 카드 (card) -- 계좌이체(trans) -- 가상계좌(vbank) -- 휴대폰 소액결제(phone) -- 도서문화상품권(booknlife) -- 스마트문상(smartculture) -- 컬쳐랜드(cultureland) -- 카카오페이 (kakaopay) -- 네이버페이 (naverpay) -- 엘페이 (lpay) -- 삼성페이(samsung) -- SSGpay (ssgpay) -- 애플페이 (applepay) -- 페이코 (payco) -- 토스간편결제 (tosspay) + **PG사 구분코드** -**`merchant_uid`** **\*** **string** + _tosspayments_ 로 지정하면 됩니다. -**주문번호** + **`pay_method`** **string** -매번 고유하게 채번되어야 합니다. + - 카드 (card) + - 계좌이체(trans) + - 가상계좌(vbank) + - 휴대폰 소액결제(phone) + - 도서문화상품권(booknlife) + - 스마트문상(smartculture) + - 컬쳐랜드(cultureland) + - 카카오페이 (kakaopay) + - 네이버페이 (naverpay) + - 엘페이 (lpay) + - 삼성페이(samsung) + - SSGpay (ssgpay) + - 애플페이 (applepay) + - 페이코 (payco) + - 토스간편결제 (tosspay) -**`amount` \*****number** + **`merchant_uid`** **\*** **string** -**결제금액** + **주문번호** -**string** 이 아닌점에 유의하세요 + 매번 고유하게 채번되어야 합니다. -**`buyer_name`** **\*** **`string`** + **`amount` \*****number** -**`구매자 이름`** + **결제금액** -**`buyer_email`** **`string`** + **string** 이 아닌점에 유의하세요 -**`구매자 email 주소`** + **`buyer_name`** **\*** **`string`** -**`currency`** **`string`** + **`구매자 이름`** -**`통화구분코드`** + **`buyer_email`** **`string`** -**`appCard`** **`boolean`** + **`구매자 email 주소`** -카드 결제시, 카드 결제창에 앱카드만 선택 가능하도록 할지 여부 (기본값: **false**) + **`currency`** **`string`** -**`useCardPoint`** **`boolean`** + **`통화구분코드`** -카드 결제시, 카드 포인트 사용 허용할지 여부 + **`appCard`** **`boolean`** -
+ 카드 결제시, 카드 결제창에 앱카드만 선택 가능하도록 할지 여부 (기본값: **false**) -
-

기타 파라미터 설명

+ **`useCardPoint`** **`boolean`** -**`bypass`** **object** + 카드 결제시, 카드 포인트 사용 허용할지 여부 +
-**`isCulturalExpense`** **boolean** +
+

기타 파라미터 설명

-문화비 지출여부 + **`bypass`** **object** -**`useInternationalCardOnly`** **boolean** + **`isCulturalExpense`** **boolean** -해외카드(Visa, MasterCard, UnionPay) 결제 여부입니다. 값이 `true`면 해외카드 결제가 가능한 영문 결제창이 열립니다. + 문화비 지출여부 -**`cashReceiptType`** **string** + **`useInternationalCardOnly`** **boolean** -현금성 결제(계좌이체, 가상계좌)창에서 선택할 수 있는 현금영수증 발급 유형 (기본값: 결제창에서 선택 가능) + 해외카드(Visa, MasterCard, UnionPay) 결제 여부입니다. 값이 `true`면 해외카드 결제가 가능한 영문 결제창이 열립니다. -- anonymous (미발행, 자진발급) -- personal (소득공제) -- corporate (지출증빙) + **`cashReceiptType`** **string** -```javascript -{ - pay_method: 'trans', - bypass: { - isCulturalExpense: true, - cashReceiptType: 'personal' - } -} -``` + 현금성 결제(계좌이체, 가상계좌)창에서 선택할 수 있는 현금영수증 발급 유형 (기본값: 결제창에서 선택 가능) -
- - - - -인증결제창 호출 파라미터에서 **customer\_uid** 값을 추가하면 비 인증 결제창을 호출할 수 있습니다. 비 인증 결제창에서 빌링키를 발급받은 후 해당 빌링키로 결제를 요청합니다. - -```javascript title="Javascript SDK" -IMP.request_pay( - { - pg: "tosspayments.{MID}", - pay_method: "card", // 'card'만 지원됩니다. - merchant_uid: "order_monthly_0001", // 상점에서 관리하는 주문 번호 - name: "최초인증결제", - amount: 0, // 실제 승인은 발생되지 않고 오직 빌링키만 발급됩니다. - customer_uid: "your-customer-unique-id", // 필수 입력. - buyer_email: "test@portone.io", - buyer_name: "포트원", - buyer_tel: "02-1234-1234", - m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", - customer_id: "matthew", //고객사가 회원에게 부여한 고유 ID - }, - function (rsp) { - // callback 로직 - } -); -``` - - -- 비인증 결제를 위해서는 **토스페이먼츠로 부터 발급받은 MID정보**를 포트원 관리자콘솔에 설정하셔야 비 인증 결제창을 활성화 시킬수 있습니다. -- 빌링키 발급시 **실 결제는 발생되지 않습니다**.(금액을 지정해도 결제가 발생되지 않음) + - anonymous (미발행, 자진발급) + - personal (소득공제) + - corporate (지출증빙) - + ```json + { + pay_method: "trans", + bypass: { + isCulturalExpense: true, + cashReceiptType: "personal" + } + } + ``` +
+ -**주요 파라미터 설명** + + 인증결제창 호출 파라미터에서 **customer\_uid** 값을 추가하면 비 인증 결제창을 호출할 수 있습니다. 비 인증 결제창에서 빌링키를 발급받은 후 해당 빌링키로 결제를 요청합니다. -**`pg` \*****string** + ```javascript title="Javascript SDK" + IMP.request_pay( + { + pg: "tosspayments.{MID}", + pay_method: "card", // 'card'만 지원됩니다. + merchant_uid: "order_monthly_0001", // 상점에서 관리하는 주문 번호 + name: "최초인증결제", + amount: 0, // 실제 승인은 발생되지 않고 오직 빌링키만 발급됩니다. + customer_uid: "your-customer-unique-id", // 필수 입력. + buyer_email: "test@portone.io", + buyer_name: "포트원", + buyer_tel: "02-1234-1234", + m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", + customer_id: "matthew", //고객사가 회원에게 부여한 고유 ID + }, + function (rsp) { + // callback 로직 + }, + ); + ``` -**PG사 구분코드** + + - 비인증 결제를 위해서는 **토스페이먼츠로 부터 발급받은 MID정보**를 포트원 관리자콘솔에 설정하셔야 비 인증 결제창을 활성화 시킬수 있습니다. + - 빌링키 발급시 **실 결제는 발생되지 않습니다**.(금액을 지정해도 결제가 발생되지 않음) + -**`tosspayments`** 로 지정하면 됩니다. + **주요 파라미터 설명** -**`customer_uid` \*****string** + **`pg` \*****string** -**카드 빌링키** + **PG사 구분코드** -비 인증 결제창에서 고객이 입력한 카드정보와 1:1로 매칭될 빌링키를 지정합니다. + **`tosspayments`** 로 지정하면 됩니다. -**`amount` \*****number** + **`customer_uid` \*****string** -**결제금액** + **카드 빌링키** -결제창에 표시될 금액으로 실제 승인은 이루어지지 않습니다.(실 결제를 발생시키기 위해서는 **customer_uid** 로 **REST API 를 이용하여 결제요청**을 해주셔야 합니다.) + 비 인증 결제창에서 고객이 입력한 카드정보와 1:1로 매칭될 빌링키를 지정합니다. -**`customer_id`** **`string`** + **`amount` \*****number** -**`구매자 식별자`** + **결제금액** -빌링키를 발급한 고객의 고유 ID 를 지정합니다.(회원ID) 해당 값 설정시 빌링키와 고객을 맵핑할 수 있습니다. 누락시 포트원에서 임의의 값을 설정합니다. + 결제창에 표시될 금액으로 실제 승인은 이루어지지 않습니다.(실 결제를 발생시키기 위해서는 **customer\_uid** 로 **REST API 를 이용하여 결제요청**을 해주셔야 합니다.) -**빌링키(customer_uid)로 결제 요청하기** + **`customer_id`** **`string`** -빌링키 발급이 성공하면 실 빌링키는 customer_uid 와 1:1 매칭되어 **포트원 서버에 저장**됩니다. customer_uid를 고객사 내부서버에 저장하시고 [**비 인증 결제요청 REST API**](../../../api/api-4/api)를 호출하시면 결제를 발생시킬 수 있습니다. + **`구매자 식별자`** -```sh title="server-side" -curl -H "Content-Type: application/json" \ - -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "amount":3000}' \ - https://api.iamport.kr/subscribe/payments/again -``` + 빌링키를 발급한 고객의 고유 ID 를 지정합니다.(회원ID) 해당 값 설정시 빌링키와 고객을 맵핑할 수 있습니다. 누락시 포트원에서 임의의 값을 설정합니다. - + **빌링키(customer\_uid)로 결제 요청하기** - -**API 방식으로 빌링키 발급,결제요청,예약결제를 구현할수 있습니다.** + 빌링키 발급이 성공하면 실 빌링키는 customer\_uid 와 1:1 매칭되어 **포트원 서버에 저장**됩니다. customer\_uid를 고객사 내부서버에 저장하시고 [**비 인증 결제요청 REST API**](../../../api/api-4/api)를 호출하시면 결제를 발생시킬 수 있습니다. - -**MID 발급시 주의사항** + ```sh title="server-side" + curl -H "Content-Type: application/json" \ + -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "amount":3000}' \ + https://api.iamport.kr/subscribe/payments/again + ``` + -토스페이먼츠로 부터 MID 발급시 **API version** 은 반드시 **1.4** 이어야 합니다. + + **API 방식으로 빌링키 발급,결제요청,예약결제를 구현할수 있습니다.** - + + **MID 발급시 주의사항** -**일회성 결제 요청하기** + 토스페이먼츠로 부터 MID 발급시 **API version** 은 반드시 **1.4** 이어야 합니다. + -REST[ **API POST /subscribe/payments/onetime**](../../../api/api-4/api-1)을 호출하여 일회성 결제를 요청합니다. 요청 시 전달된 카드는 포트원에 등록되지 않습니다. + **일회성 결제 요청하기** -```sh -curl -H "Content-Type: application/json" \ - -X POST -d '{"merchant_uid":"order_id_8237352", "card_number":"1234-1234-1234-1234", "expiry":"2019-01", "birth":"123456", "amount":3000}' \ - https://api.iamport.kr/subscribe/payments/onetime -``` + REST[**API POST /subscribe/payments/onetime**](../../../api/api-4/api-1)을 호출하여 일회성 결제를 요청합니다. 요청 시 전달된 카드는 포트원에 등록되지 않습니다. -**빌링키 발급 요청하기** + ```sh + curl -H "Content-Type: application/json" \ + -X POST -d '{"merchant_uid":"order_id_8237352", "card_number":"1234-1234-1234-1234", "expiry":"2019-01", "birth":"123456", "amount":3000}' \ + https://api.iamport.kr/subscribe/payments/onetime + ``` -REST [**API POST /subscribe/customers/\{customer_uid}**](../../../api/api-2/api-1)를 호출하여 빌링키 발급을 요청합니다. + **빌링키 발급 요청하기** -```sh -curl -H "Content-Type: application/json" \ - -X POST -d '{"card_number":"1234-1234-1234-1234", "expiry":"2025-12", "birth":"820213", "pwd_2digit":"00"}' \ - https://api.iamport.kr/subscribe/customers/your-customer-unique-id -``` + REST [**API POST /subscribe/customers/\{customer\_uid}**](../../../api/api-2/api-1)를 호출하여 빌링키 발급을 요청합니다. -**빌링키 발급 및 최초 결제 요청하기** + ```sh + curl -H "Content-Type: application/json" \ + -X POST -d '{"card_number":"1234-1234-1234-1234", "expiry":"2025-12", "birth":"820213", "pwd_2digit":"00"}' \ + https://api.iamport.kr/subscribe/customers/your-customer-unique-id + ``` -REST [**API POST /subscribe/payments/onetime**](../../../api/api-4/api-1)을 호출하여 빌링키 발급과 최초 결제를 요청합니다. + **빌링키 발급 및 최초 결제 요청하기** -- **`customer_uid`** : 빌링키 등록을 위해서 지정해야 합니다. + REST [**API POST /subscribe/payments/onetime**](../../../api/api-4/api-1)을 호출하여 빌링키 발급과 최초 결제를 요청합니다. -```sh -curl -H "Content-Type: application/json" \ - -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "card_number":"1234-1234-1234-1234", "expiry":"2019-01", "birth":"123456", "amount":3000}' \ - https://api.iamport.kr/subscribe/payments/onetime -``` + - **`customer_uid`** : 빌링키 등록을 위해서 지정해야 합니다. -**빌링키로 결제 요청하기** + ```sh + curl -H "Content-Type: application/json" \ + -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "card_number":"1234-1234-1234-1234", "expiry":"2019-01", "birth":"123456", "amount":3000}' \ + https://api.iamport.kr/subscribe/payments/onetime + ``` -빌링키 발급과 최초 결제가 성공하면 빌링키는 전달된 `customer_uid` 와 1:1 매칭되어 포트원에 저장됩니다. 보안상의 이유로 서버는 빌링키에 직접 접근할 수 없기 때문에 `customer_uid`를 이용해서 재결제([**POST /subscribe/payments/again**](../../../api/api-4/api)) REST API를 다음과 같이 호출합니다. + **빌링키로 결제 요청하기** -```sh -curl -H "Content-Type: application/json" \ - -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "amount":3000}' \ - https://api.iamport.kr/subscribe/payments/again -``` + 빌링키 발급과 최초 결제가 성공하면 빌링키는 전달된 `customer_uid` 와 1:1 매칭되어 포트원에 저장됩니다. 보안상의 이유로 서버는 빌링키에 직접 접근할 수 없기 때문에 `customer_uid`를 이용해서 재결제([**POST /subscribe/payments/again**](../../../api/api-4/api)) REST API를 다음과 같이 호출합니다. - + ```sh + curl -H "Content-Type: application/json" \ + -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "amount":3000}' \ + https://api.iamport.kr/subscribe/payments/again + ``` + ### 3. 부가기능 - - -```javascript title="javascript" -display: { - card_quota: [6], // 할부개월 6개월만 활성화 - only_installment: true // 일시불 항목은 제외 -} -``` - -**파라미터 설명** - -- **card_quota :** - -\- 지정한 숫자에 해당하는 할부개월수만 표기 + + ```json title="javascript" + display: { + card_quota: [6], // 할부개월 6개월만 활성화 + only_installment: true // 일시불 항목은 제외 + } + ``` -\- `[]`: 일시불만 결제 가능 + **파라미터 설명** -\- `2,3,4,5,6`: 일시불을 포함한 2, 3, 4, 5, 6개월까지 할부개월 선택 가능\\ + - **card\_quota :** -- **`only_installment` : `true`** 인 경우 `card_quota` 에 설정한 할부개월수만 표시 + \- 지정한 숫자에 해당하는 할부개월수만 표기 - -할부결제는 **5만원 이상 결제 요청시**에만 이용 가능합니다. - - + \- `[]`: 일시불만 결제 가능 - - - -```javascript title="javascript" -card: { - direct: { - code: "367", - quota: 3 - } -} -``` + \- `2,3,4,5,6`: 일시불을 포함한 2, 3, 4, 5, 6개월까지 할부개월 선택 가능\\ -**파라미터 설명** + - **`only_installment` : `true`** 인 경우 `card_quota` 에 설정한 할부개월수만 표시 -- **`code`** : 카드사 금융결제원 표준 코드. [**링크**](https://faq.portone.io/6503bcb4-4a61-4cf3-afd8-5d913b1385a6) 참조 (**string**) -- **`quota`** : 할부 개월 수. 일시불일 시 0 으로 지정. (**number**) + + 할부결제는 **5만원 이상 결제 요청시**에만 이용 가능합니다. + + - + + ```json title="javascript" + card: { + direct: { + code: "367", + quota: 3 + } + } + ``` - + **파라미터 설명** -토스페이먼츠 고정식 가상계좌 발급 서비스를 이용하기 위해서는 **토스페이먼츠 측과 협의**를 통해 결제에 이용하는 MID에 고정식 가상계좌 설정이 반드시 선행되어야 합니다. + - **`code`** : 카드사 금융결제원 표준 코드. [**링크**](https://faq.portone.io/6503bcb4-4a61-4cf3-afd8-5d913b1385a6) 참조 (**string**) + - **`quota`** : 할부 개월 수. 일시불일 시 0 으로 지정. (**number**) + -해당 설정이 완료되면 두가지 방식으로 고정식 가상계좌를 발급할 수 있습니다. + + 토스페이먼츠 고정식 가상계좌 발급 서비스를 이용하기 위해서는 **토스페이먼츠 측과 협의**를 통해 결제에 이용하는 MID에 고정식 가상계좌 설정이 반드시 선행되어야 합니다. -- [API 방식](../../../api/api-9/api) -- 결제창 방식 + 해당 설정이 완료되면 두가지 방식으로 고정식 가상계좌를 발급할 수 있습니다. -두 방식 모두 **고유식별번호**가 유입되어야 하며 해당 값은 각 고객을 특정할수 있는 고유값이어야 합니다. + - [API 방식](../../../api/api-9/api) + - 결제창 방식 -결제창 방식을 이용하기 위해서 고객에게 사전에 해당 고유식별번호가 안내되어야 하며 가상계좌 발급단계에서 아래 첨부이미지처럼 고유식별번호 란에 해당 값이 유입되어야 합니다. + 두 방식 모두 **고유식별번호**가 유입되어야 하며 해당 값은 각 고객을 특정할수 있는 고유값이어야 합니다. -
+ 결제창 방식을 이용하기 위해서 고객에게 사전에 해당 고유식별번호가 안내되어야 하며 가상계좌 발급단계에서 아래 첨부이미지처럼 고유식별번호 란에 해당 값이 유입되어야 합니다. -API 방식 또한 `vbank_key` 파라미터가 고유식별번호에 대응되는 값으로 API방식은 고객사에서 직접 해당 값을 기재해서 호출할수 있기 때문에 고객 편의차원에서 훨씬 간편한 고정식 가상계좌 서비스를 제공할수 있습니다. +
-고정식 가상계좌 발급이 정상적으로 이루어지면 아래와 같이 고객휴대폰 번호로 SMS가 발송되며 고객은 해당 정보를 보고 입금을 할수 있습니다.(비용: 무료) + API 방식 또한 `vbank_key` 파라미터가 고유식별번호에 대응되는 값으로 API방식은 고객사에서 직접 해당 값을 기재해서 호출할수 있기 때문에 고객 편의차원에서 훨씬 간편한 고정식 가상계좌 서비스를 제공할수 있습니다. -
+ 고정식 가상계좌 발급이 정상적으로 이루어지면 아래와 같이 고객휴대폰 번호로 SMS가 발송되며 고객은 해당 정보를 보고 입금을 할수 있습니다.(비용: 무료) - +
+ ## 4. 사용가능 기능 @@ -385,45 +371,41 @@ API 방식 또한 `vbank_key` 파라미터가 고유식별번호에 대응되는 - [현금영수증 발급(외부) API](../../../api/api-8/api-5) + **기존에 deprecated된 응답들은 모두 제거됐습니다. ⚠️** -**기존에 deprecated된 응답들은 모두 제거됐습니다. ⚠️** + 신 토스페이먼츠 모듈 연동시에 사용되는 신규 JS SDK는 기존 모듈에서 제공했던 CallBack 파라미터가 대부분 삭제되었습니다.(특히 deprecated 로 명시된 파라미터는 모두 삭제되었습니다.) -신 토스페이먼츠 모듈 연동시에 사용되는 신규 JS SDK는 기존 모듈에서 제공했던 CallBack 파라미터가 대부분 삭제되었습니다.(특히 deprecated 로 명시된 파라미터는 모두 삭제되었습니다.) + 해당 JS SDK 사용시 Callback 으로 내려받을수 있는 데이터는 오직 아래 두가지 입니다. -해당 JS SDK 사용시 Callback 으로 내려받을수 있는 데이터는 오직 아래 두가지 입니다. - -**`imp_uid`, `merchant_uid`** - -따라서 해당 SDK를 사용하실때는 `IMP.request_pay()`로부터 응답된 객체(또는 쿼리 파라미터)에서 `imp_uid`를 가지고 **아임포트 REST API(GET `/payments/imp_uid`)로 결제 상세 내역(승인 상태, 승인 결과 등등)을 조회**하여 응답 파라미터 중 status 파라미터로 결제 상태를 파악하셔야 합니다. + **`imp_uid`, `merchant_uid`** + 따라서 해당 SDK를 사용하실때는 `IMP.request_pay()`로부터 응답된 객체(또는 쿼리 파라미터)에서 `imp_uid`를 가지고 **아임포트 REST API(GET `/payments/imp_uid`)로 결제 상세 내역(승인 상태, 승인 결과 등등)을 조회**하여 응답 파라미터 중 status 파라미터로 결제 상태를 파악하셔야 합니다. + ```html + + ``` -```html - -``` - -위 JS SDK 를 이용하여 토스페이먼츠,케이에스넷 연동시 callback Data는 -아래와 같이 두가지 형태로만 내려갑니다. - -- `imp_uid` -- `merchant_uid` + 위 JS SDK 를 이용하여 토스페이먼츠,케이에스넷 연동시 callback Data는 + 아래와 같이 두가지 형태로만 내려갑니다. -위 PG사를 제외한 다른 PG사는 `imp_success` 파라미터가 기존처럼 내려가지만 -해당 파리미터는 deprecated 된 값이기 때문에 해당 값에 의존성을 가진 프로그램 로직은 모두 삭제하시는 -방향성을 잡아가셔야 하는점 유념하시기 바랍니다. + - `imp_uid` + - `merchant_uid` + 위 PG사를 제외한 다른 PG사는 `imp_success` 파라미터가 기존처럼 내려가지만 + 해당 파리미터는 deprecated 된 값이기 때문에 해당 값에 의존성을 가진 프로그램 로직은 모두 삭제하시는 + 방향성을 잡아가셔야 하는점 유념하시기 바랍니다. -**토스페이먼츠 API 버전 설정** + **토스페이먼츠 API 버전 설정** -- [토스페이먼츠 개발자센터](https://app.tosspayments.com/signin?redirectUrl=https%3A%2F%2Fdevelopers.tosspayments.com%2Fmy%2Fapi-keys) 로그인 -- 왼쪽 네비게이션 메뉴 API 키 선택 → API 버전을 **2022-07-27**로 선택 + - [토스페이먼츠 개발자센터](https://app.tosspayments.com/signin?redirectUrl=https%3A%2F%2Fdevelopers.tosspayments.com%2Fmy%2Fapi-keys) 로그인 - API 버전을 다르게 설정하면 결제 승인 / 실패 시 실제 응답과 다른 응답을 받아볼 수 있으니 **반드시 API 버전을 2022-07-27로** 맞춰주시기 바랍니다 + - 왼쪽 네비게이션 메뉴 API 키 선택 → API 버전을 **2022-07-27**로 선택 -
+ API 버전을 다르게 설정하면 결제 승인 / 실패 시 실제 응답과 다른 응답을 받아볼 수 있으니 **반드시 API 버전을 2022-07-27로** 맞춰주시기 바랍니다 +
diff --git a/src/content/docs/ko/pg/payment-gateway/newtoss/warning.mdx b/src/content/docs/ko/pg/payment-gateway/newtoss/warning.mdx index 2d90947e6..db225d519 100644 --- a/src/content/docs/ko/pg/payment-gateway/newtoss/warning.mdx +++ b/src/content/docs/ko/pg/payment-gateway/newtoss/warning.mdx @@ -3,8 +3,8 @@ title: 연동 유의사항 description: 토스페이먼츠 (신 모듈) 연동 유의사항을 소개합니다. --- -import Details from "~/components/gitbook/Details.astro"; import Figure from "~/components/Figure.astro"; +import Details from "~/components/gitbook/Details.astro"; ## 토스페이먼츠와 사전 계약이 필요한 경우 @@ -24,233 +24,223 @@ import Figure from "~/components/Figure.astro"; ## 카드 결제
-

appCard 파라미터는 일부 카드사에 대해서만 적용 됨

+

appCard 파라미터는 일부 카드사에 대해서만 적용 됨

-토스페이먼츠의 경우 카드 결제시, 앱 카드로만 결제할 수 있도록 제한하는 appCard 파라미터를 지원하지만 지원 범위가 아래와 같이 제한적입니다. - -- 지원 가능 카드: 국민, 농협, 롯데, 삼성, 신한, 현대, 우리, 하나 -- 지원 불가 카드: 씨티 + 토스페이먼츠의 경우 카드 결제시, 앱 카드로만 결제할 수 있도록 제한하는 appCard 파라미터를 지원하지만 지원 범위가 아래와 같이 제한적입니다. + - 지원 가능 카드: 국민, 농협, 롯데, 삼성, 신한, 현대, 우리, 하나 + - 지원 불가 카드: 씨티
-

display.card_quota 파라미터는 다른 PG사와 다르게 동작 함

+

display.card\_quota 파라미터는 다른 PG사와 다르게 동작 함

-display.card_quota 파라미터로 결제창에 렌더링 될 할부 개월수 리스트를 제어할 수 있습니다. 다른 PG사는 전달한 값만 렌더링 되지만, 토스페이먼츠의 경우에는 토스페이먼츠 자체 정책에 따라 **일시불 \~ 전달한 값 중 최대값까지 모두 렌더링**됩니다. + display.card\_quota 파라미터로 결제창에 렌더링 될 할부 개월수 리스트를 제어할 수 있습니다. 다른 PG사는 전달한 값만 렌더링 되지만, 토스페이먼츠의 경우에는 토스페이먼츠 자체 정책에 따라 **일시불 \~ 전달한 값 중 최대값까지 모두 렌더링**됩니다. -- 예1. 일시불만 허용 + - 예1. 일시불만 허용 - ```jsx - display: { - card_quota: [0]; - } - ``` + ```jsx + display: { + card_quota: [0]; + } + ``` -- 예2. 5개월만 허용 + - 예2. 5개월만 허용 - ```jsx - display: { - card_quota: [5]; - } - ``` + ```jsx + display: { + card_quota: [5]; + } + ``` -- 예3. \[토스페이먼츠] 일시불 \~ 5개월까지 허용 + - 예3. \[토스페이먼츠] 일시불 \~ 5개월까지 허용 - ```jsx - display: { - card_quota: [3, 5]; // 3과 5 중에 최대값이 5이기 때문에 일시불 ~ 5개월까지 모두 렌더링 된다 - } - ``` + ```jsx + display: { + card_quota: [3, 5]; // 3과 5 중에 최대값이 5이기 때문에 일시불 ~ 5개월까지 모두 렌더링 된다 + } + ``` -- 예3. \[타 PG사] 일시불 \~ 5개월까지 허용 + - 예3. \[타 PG사] 일시불 \~ 5개월까지 허용 - ```jsx - display: { - card_quota: [0, 1, 2, 3, 4, 5]; - } - ``` + ```jsx + display: { + card_quota: [0, 1, 2, 3, 4, 5]; + } + ``` -- 예4. \[토스페이먼츠] 3개월과 5개월만 허용 → **불가능** -- 예5. \[타 PG사] 3개월과 5개월만 허용 + - 예4. \[토스페이먼츠] 3개월과 5개월만 허용 → **불가능** + - 예5. \[타 PG사] 3개월과 5개월만 허용
-

무이자 할부가 적용 되어도 ISP 계열 카드로 결제시에는 “무이자” 표기가 되지 않음

+

무이자 할부가 적용 되어도 ISP 계열 카드로 결제시에는 “무이자” 표기가 되지 않음

-고객사는 토스페이먼츠와 사전 계약 또는 카드사 정책에 따라 무이자 할부 기능을 사용할 수 있습니다. 이에 따라 결제창 내에서 각 카드 사별 최대 무이자 할부 개월수에 따라 할부 개월수 옆에 “무이자” 또는 “무”라고 표기 됩니다. + 고객사는 토스페이먼츠와 사전 계약 또는 카드사 정책에 따라 무이자 할부 기능을 사용할 수 있습니다. 이에 따라 결제창 내에서 각 카드 사별 최대 무이자 할부 개월수에 따라 할부 개월수 옆에 “무이자” 또는 “무”라고 표기 됩니다. -- 예1. 삼성카드 - 최대 3개월 무이자 할부 적용 → 3개월까지 “무” 표기 + - 예1. 삼성카드 - 최대 3개월 무이자 할부 적용 → 3개월까지 “무” 표기 -
+
-하지만 ISP 계열 카드의 경우에는 실제로 무이자가 적용된다고 하더라도 “무이자” 여부가 표기되지 않습니다. + 하지만 ISP 계열 카드의 경우에는 실제로 무이자가 적용된다고 하더라도 “무이자” 여부가 표기되지 않습니다. -- 예2. BC카드 - 최대 12개월 무이자 할부 적용 → 표기 없음 → 실제 결제 승인시 무이자 할부 적용은 됨 + - 예2. BC카드 - 최대 12개월 무이자 할부 적용 → 표기 없음 → 실제 결제 승인시 무이자 할부 적용은 됨 -
- -이는 ISP 계열 카드사 결제시 사용되는 페이북 앱 특성에 따른 것으로 실제 결제 승인시에는 정상적으로 무이자 할부가 적용됩니다. +
+ 이는 ISP 계열 카드사 결제시 사용되는 페이북 앱 특성에 따른 것으로 실제 결제 승인시에는 정상적으로 무이자 할부가 적용됩니다.
-

할부 기간 선택 관련 이슈

+

할부 기간 선택 관련 이슈

+ + 모바일 웹 - 카드 결제시 토스페이먼츠 결제창 내에서 간편결제의 경우 할부 기간 선택이 불가능하고, 간편결제 외의 모든 카드사의 경우엔 할부 기간 선택이 가능합니다. -모바일 웹 - 카드 결제시 토스페이먼츠 결제창 내에서 간편결제의 경우 할부 기간 선택이 불가능하고, 간편결제 외의 모든 카드사의 경우엔 할부 기간 선택이 가능합니다. + - 모바일 웹 - 간편결제 외 카드사: 할부 기간 선택 가능\ + ![]() -- 모바일 웹 - 간편결제 외 카드사: 할부 기간 선택 가능\ - ![]() -- 모바일 웹 - 간편결제: 할부 기간 선택 불가능\ - ![]() + - 모바일 웹 - 간편결제: 할부 기간 선택 불가능\ + ![]() -반면, PC - 카드 결제 - ISP계열의 경우에는 토스페이먼츠 결제창 내에서도 할부 기간 선택이 불가능 하며, 대신 ISP 페이북 팝업에서는 선택이 가능합니다. + 반면, PC - 카드 결제 - ISP계열의 경우에는 토스페이먼츠 결제창 내에서도 할부 기간 선택이 불가능 하며, 대신 ISP 페이북 팝업에서는 선택이 가능합니다. -- PC - 카드결제 - ISP 선택: 할부 기간 선택 불가능\ - -- PC - 카드결제 - ISP 선택 - 페이북 팝업: 할부 기간 선택 가능 + - PC - 카드결제 - ISP 선택: 할부 기간 선택 불가능\\ + -다소 헷갈릴 수 있으나 간편결제는 간편결제 앱에서 할부 개월수를 선택할 수 있어 토스페이먼츠 결제창에서 선택할 수 없다는 토스 답변이 있었습니다. + - PC - 카드결제 - ISP 선택 - 페이북 팝업: 할부 기간 선택 가능 + 다소 헷갈릴 수 있으나 간편결제는 간편결제 앱에서 할부 개월수를 선택할 수 있어 토스페이먼츠 결제창에서 선택할 수 없다는 토스 답변이 있었습니다.
-

카카오페이 13개월 이상 할부 개월수 불가능한 이슈

- -카카오페이 자체에서 13개월 이상 할부 결제를 지원하지 않기 때문에, 카카오페이로는 최대 12개월까지 할부 결제가 가능합니다. +

카카오페이 13개월 이상 할부 개월수 불가능한 이슈

+ 카카오페이 자체에서 13개월 이상 할부 결제를 지원하지 않기 때문에, 카카오페이로는 최대 12개월까지 할부 결제가 가능합니다.
-

카카오페이 일부 카드의 경우 카드 정보를 확인할 수 없는 이슈

- -카카오페이로 결제시 일부 카드(2022년 6월 이후 카드사 측에서 신규 생성 된 카드)의 경우, 카카오페이 → 토스페이먼츠로 카드 정보를 정상적으로 내려주지 않기 때문에 포트원 REST API로 결제내역 조회(GET /payments/\{imp_uid})시 카드사 정보(card_code: 카드 코드, card_name: 카드 이름)를 확인할 수 없습니다. +

카카오페이 일부 카드의 경우 카드 정보를 확인할 수 없는 이슈

+ 카카오페이로 결제시 일부 카드(2022년 6월 이후 카드사 측에서 신규 생성 된 카드)의 경우, 카카오페이 → 토스페이먼츠로 카드 정보를 정상적으로 내려주지 않기 때문에 포트원 REST API로 결제내역 조회(GET /payments/\{imp\_uid})시 카드사 정보(card\_code: 카드 코드, card\_name: 카드 이름)를 확인할 수 없습니다.
## 카드사 다이렉트 호출
-

고정 할부 개월수(card.direct.quota)를 보내지 않으면 무조건 일시불로 결제 됨

- -토스페이먼츠는 카드사 다이렉트 호출시 **quota 값을 전달하지 않는 경우에는 무조건 일시불로 결제**가 됩니다. +

고정 할부 개월수(card.direct.quota)를 보내지 않으면 무조건 일시불로 결제 됨

-따라서 카드사 다이렉트 호출시에는 반드시 구매자가 할부 개월수를 선택할 수 있는 UI/UX를 만들어주신 후 결제창 호출(IMP.request_pay)시 card.direct.quota값을 넘겨야 합니다. + 토스페이먼츠는 카드사 다이렉트 호출시 **quota 값을 전달하지 않는 경우에는 무조건 일시불로 결제**가 됩니다. -- 예1. 현대카드 다이렉트 호출 → 무조건 일시불로 결제 됨 - - ```jsx - card: { - direct: { - code: "367"; - } - } - ``` + 따라서 카드사 다이렉트 호출시에는 반드시 구매자가 할부 개월수를 선택할 수 있는 UI/UX를 만들어주신 후 결제창 호출(IMP.request\_pay)시 card.direct.quota값을 넘겨야 합니다. -- 예2. 삼성카드 다이렉트 호출 + 5개월 고정 할부 개월수 지정 → 5개월 할부 적용 + - 예1. 현대카드 다이렉트 호출 → 무조건 일시불로 결제 됨 - ```jsx - { + ```jsx card: { direct: { - code: '365', - quota: 5 + code: "367"; } } - } - ``` + ``` + + - 예2. 삼성카드 다이렉트 호출 + 5개월 고정 할부 개월수 지정 → 5개월 할부 적용 + ```jsx + { + card: { + direct: { + code: '365', + quota: 5 + } + } + } + ```
-

고정 할부 개월수(card.direct.quota)를 보내도 카드 결제창에서 결제 될 할부 개월수를 확인할 수 없음

+

고정 할부 개월수(card.direct.quota)를 보내도 카드 결제창에서 결제 될 할부 개월수를 확인할 수 없음

-카드사 다이렉트 호출시 quota 값을 보내도 **실제로 카드사 결제창에서는 결제시 적용 될 할부 개월수를 확인할 수 없습니다.** (물론 실제 승인시에는 전달한 quota값 만큼 할부 적용이 됨) + 카드사 다이렉트 호출시 quota 값을 보내도 **실제로 카드사 결제창에서는 결제시 적용 될 할부 개월수를 확인할 수 없습니다.** (물론 실제 승인시에는 전달한 quota값 만큼 할부 적용이 됨) -단, ISP 계열의 카드사인 경우에는 페이북 팝업에서 확인이 가능하며 이 값을 사용자가 변경 할 수는 없습니다. + 단, ISP 계열의 카드사인 경우에는 페이북 팝업에서 확인이 가능하며 이 값을 사용자가 변경 할 수는 없습니다. -- 예. BC카드 다이렉트 호출 + 5개월 고정 할부 개월수 지정\\ + - 예. BC카드 다이렉트 호출 + 5개월 고정 할부 개월수 지정\\ -
- -
-
+
+ -```javascript -card: { - direct: { - code: '361', - quota: 5 - } -} -``` +
+
+ ```json + card: { + direct: { + code: "361", + quota: 5 + } + } + ```
-

페이북을 통한 ISP 계열 카드 결제시, 카드 번호가 정상적으로 내려오지 않음

- -페이북 통한 ISP 계열 카드 결제시 토스페이먼츠로부터 실제 카드 번호와 다른 9200으로 시작하는 카드 번호가 내려오고 있어 결제 승인 내역 조회(POST `/payments/{imp_uid}`)시 응답되는 카드 번호(`card_numer`)가 정확하지 않습니다. +

페이북을 통한 ISP 계열 카드 결제시, 카드 번호가 정상적으로 내려오지 않음

+ 페이북 통한 ISP 계열 카드 결제시 토스페이먼츠로부터 실제 카드 번호와 다른 9200으로 시작하는 카드 번호가 내려오고 있어 결제 승인 내역 조회(POST `/payments/{imp_uid}`)시 응답되는 카드 번호(`card_numer`)가 정확하지 않습니다.
-

사파리 브라우저에서 ISP 계열 카드 결제 불가능

- -사파리 브라우저에서 ISP 계열 카드 결제를 위한 페이북 팝업 호출에 이슈가 있습니다. 이는 토스페이먼츠 결제창에서 페이북으로 넘어가는 과정에서 발생하는 이슈로 포트원과는 무관합니다. +

사파리 브라우저에서 ISP 계열 카드 결제 불가능

+ 사파리 브라우저에서 ISP 계열 카드 결제를 위한 페이북 팝업 호출에 이슈가 있습니다. 이는 토스페이먼츠 결제창에서 페이북으로 넘어가는 과정에서 발생하는 이슈로 포트원과는 무관합니다.
## 가상계좌
-

가상계좌 발급 완료시 예금주 명 알 수 없음

- -토스페이먼츠는 가상계좌 발급 완료시 발급 된 가상계좌의 **예금주 명을 전달해주지 않습니다**. 따라서 포트원 REST API로 결제내역 조회(GET `/payments/{imp_uid}`)시 `vbank_holder`가 null로 전달됩니다. +

가상계좌 발급 완료시 예금주 명 알 수 없음

-실제 가상계좌 예금주 명은 토스페이먼츠와 계약된 고객사 이름과 동일하다고 하니, 참고 부탁드립니다. + 토스페이먼츠는 가상계좌 발급 완료시 발급 된 가상계좌의 **예금주 명을 전달해주지 않습니다**. 따라서 포트원 REST API로 결제내역 조회(GET `/payments/{imp_uid}`)시 `vbank_holder`가 null로 전달됩니다. + 실제 가상계좌 예금주 명은 토스페이먼츠와 계약된 고객사 이름과 동일하다고 하니, 참고 부탁드립니다.
## 간편결제
-

대부분의 간편결제에 대해 결제 테스트 불가능

- -토스페이먼츠는 SSGPAY, 네이버페이, 카카오페이, 페이코 등 대부분의 간편결제에 대해 결제 테스트 기능을 제공하고 있지 않습니다. 따라서 테스트용 설정으로 간편결제를 시도하면 `[PAY_PROCESS_ABORTED] Toss Payments와 계약된 결제수단(SSG)이 아닙니다.` 와 같은 에러 메시지가 리턴되면서 결제창이 호출되지 않습니다. 이 경우 토스페이먼츠와 실 상점 계약을 하여 실 상점 정보를 포트원 관리자페이지에 다시 등록한 후 시도하셔야 합니다. +

대부분의 간편결제에 대해 결제 테스트 불가능

+ 토스페이먼츠는 SSGPAY, 네이버페이, 카카오페이, 페이코 등 대부분의 간편결제에 대해 결제 테스트 기능을 제공하고 있지 않습니다. 따라서 테스트용 설정으로 간편결제를 시도하면 `[PAY_PROCESS_ABORTED] Toss Payments와 계약된 결제수단(SSG)이 아닙니다.` 와 같은 에러 메시지가 리턴되면서 결제창이 호출되지 않습니다. 이 경우 토스페이먼츠와 실 상점 계약을 하여 실 상점 정보를 포트원 관리자페이지에 다시 등록한 후 시도하셔야 합니다.
-

카드 외 복합 결제 건에 대해서는 정확한 결제 수단 정보 확인 불가능

- -간편결제로는 여러가지 결제수단으로 결제 할 수도 있고 각 결제 수단을 혼합하여 복합 결제를 할 수도 있습니다. 이때 토스페이먼츠는 구매자가 정확히 어떤 방식으로 결제했는지 데이터를 내려주지 않으며 그 내용은 아래와 같습니다. +

카드 외 복합 결제 건에 대해서는 정확한 결제 수단 정보 확인 불가능

-1. 카드로 결제한 경우에는 카드 정보(카드사, 카드 유형 등)를 확인할 수 있습니다. -2. 하지만 카드 외의 결제 수단으로 결제를 한 경우에는, 결제 수단 세부 정보(어떤 은행, 포인트, 머니인지)를 확인할 수 없습니다. -3. 카드가 포함 된 결제 건인지 아닌지는 구분이 됩니다. 따라서 카드가 포함 된 결제 건이면 결제 수단을 `card` 로 기록합니다. -4. 하지만 계좌 / 포인트 / 머니 중 어떤 것으로 결제 됐는지 구분되지 않습니다. 따라서 카드가 포함 되지 않은 결제 건이면 결제 수단을 `point`로 기록합니다. 실제로 등록된 계좌로 결제 됐다고 하더라도 포인트나 머니로 결제 된 것과 구분되지 않기 때문에 결제 수단을 `trans`로 저장하지 않습니다. + 간편결제로는 여러가지 결제수단으로 결제 할 수도 있고 각 결제 수단을 혼합하여 복합 결제를 할 수도 있습니다. 이때 토스페이먼츠는 구매자가 정확히 어떤 방식으로 결제했는지 데이터를 내려주지 않으며 그 내용은 아래와 같습니다. + 1. 카드로 결제한 경우에는 카드 정보(카드사, 카드 유형 등)를 확인할 수 있습니다. + 2. 하지만 카드 외의 결제 수단으로 결제를 한 경우에는, 결제 수단 세부 정보(어떤 은행, 포인트, 머니인지)를 확인할 수 없습니다. + 3. 카드가 포함 된 결제 건인지 아닌지는 구분이 됩니다. 따라서 카드가 포함 된 결제 건이면 결제 수단을 `card` 로 기록합니다. + 4. 하지만 계좌 / 포인트 / 머니 중 어떤 것으로 결제 됐는지 구분되지 않습니다. 따라서 카드가 포함 되지 않은 결제 건이면 결제 수단을 `point`로 기록합니다. 실제로 등록된 계좌로 결제 됐다고 하더라도 포인트나 머니로 결제 된 것과 구분되지 않기 때문에 결제 수단을 `trans`로 저장하지 않습니다.
-

고정 할부 개월수 적용해도 일시불과 함께 표기

+

고정 할부 개월수 적용해도 일시불과 함께 표기

-네이버페이, L페이, 토스페이, 삼성페이 등 일부 간편결제사의 경우 해당 간편결제사의 정책에 따라 **고정 할부 개월수를 설정하더라도 일시불과 함께 렌더링**됩니다. + 네이버페이, L페이, 토스페이, 삼성페이 등 일부 간편결제사의 경우 해당 간편결제사의 정책에 따라 **고정 할부 개월수를 설정하더라도 일시불과 함께 렌더링**됩니다. -- 예. 네이버페이 - 5개월 고정 할부 설정시, 일시불과 5개월 할부 모두 선택 가능 + - 예. 네이버페이 - 5개월 고정 할부 설정시, 일시불과 5개월 할부 모두 선택 가능 - ```jsx - { - pay_method: 'naverpay', - display: { - card_quota: [5] + ```json + { + pay_method: "naverpay", + display: { + card_quota: [5] + } } - } - ``` - -
+ ``` +
## 기타 @@ -262,60 +252,53 @@ card: { - `cashReceiptType` 파라미터로 인한 오동작 관련 이슈
-

지출증빙 발급번호 이슈

+

지출증빙 발급번호 이슈

-`bypass.cashReceiptType`(현금성 결제시, 결제창 내에 현금영수증 발급 유형 설정 값)을 corporate(지출 증빙)으로 설정하고 결제창을 호출하면 토스페이먼츠 결제창에서 현금영수증 발급 유형이 “지출증빙”으로 표기되어있으나 발급 번호가 사업자등록번호가 아닌 주민등록번호로 설정되어있으며 이를 변경할 수 없는 토스 버그가 있습니다. 따라서 구매자는 현금영수증 발급 유형을 지출증빙용이 아닌 소득공제용이나 미발행으로 바꿔서 선택한 후 다시 지출증빙용을 선택해야합니다. - - + `bypass.cashReceiptType`(현금성 결제시, 결제창 내에 현금영수증 발급 유형 설정 값)을 corporate(지출 증빙)으로 설정하고 결제창을 호출하면 토스페이먼츠 결제창에서 현금영수증 발급 유형이 “지출증빙”으로 표기되어있으나 발급 번호가 사업자등록번호가 아닌 주민등록번호로 설정되어있으며 이를 변경할 수 없는 토스 버그가 있습니다. 따라서 구매자는 현금영수증 발급 유형을 지출증빙용이 아닌 소득공제용이나 미발행으로 바꿔서 선택한 후 다시 지출증빙용을 선택해야합니다. +
-

간편결제 - SSG페이 결제시 토스페이먼츠 결제창에서 휴대폰 번호를 입력하지 않아도 다음으로 넘어가는 이슈

- -간편결제 - SSG페이 결제시 토스페이먼츠 결제창에서 휴대폰 번호를 입력해야 구매자의 휴대폰에 깔린 SSG 페이 앱에서 푸쉬 알림이 오면서 결제를 할 수 있는데, 현재 토스페이먼츠 결제창에서 휴대폰 번호를 입력하지 않아도 다음 단계로 이동되기 때문에 구매자는 이 경우 무한 대기를 하게 됩니다. 휴대폰 번호를 입력을 하지 않은 경우엔 다음 단계로 이동할 수 없도록 토스 측의 조치가 필요합니다.![]() +

간편결제 - SSG페이 결제시 토스페이먼츠 결제창에서 휴대폰 번호를 입력하지 않아도 다음으로 넘어가는 이슈

+ 간편결제 - SSG페이 결제시 토스페이먼츠 결제창에서 휴대폰 번호를 입력해야 구매자의 휴대폰에 깔린 SSG 페이 앱에서 푸쉬 알림이 오면서 결제를 할 수 있는데, 현재 토스페이먼츠 결제창에서 휴대폰 번호를 입력하지 않아도 다음 단계로 이동되기 때문에 구매자는 이 경우 무한 대기를 하게 됩니다. 휴대폰 번호를 입력을 하지 않은 경우엔 다음 단계로 이동할 수 없도록 토스 측의 조치가 필요합니다.![]()
-

삼성페이 결제 중단시 결제창 잘림 현상

+

삼성페이 결제 중단시 결제창 잘림 현상

-삼성페이 결제창 렌더링 후 장시간 대기했다가 우측 상단 X 버튼을 눌러 결제 프로세스를 중단하면 아래와 같이 잘린 화면이 렌더링됩니다. 가로 스크롤도 동작하지 않아(스크롤은 움직이지만 화면은 고정) 사용자 경험이 다소 저해됩니다. - - + 삼성페이 결제창 렌더링 후 장시간 대기했다가 우측 상단 X 버튼을 눌러 결제 프로세스를 중단하면 아래와 같이 잘린 화면이 렌더링됩니다. 가로 스크롤도 동작하지 않아(스크롤은 움직이지만 화면은 고정) 사용자 경험이 다소 저해됩니다. +
-

현금영수증 발급 API 호출시 유효성 검사를 하지 않음

- -예를 들어 현금영수증 발급 유형(type)을 소득공제(person)으로 보내고 현금영수증 발급 번호(identifier)를 사업자 등록번호로 보내면 실제로는 현금영수증 발급에 실패해야하지만 토스페이먼츠에서 유효성 검사를 하지 않아 그대로 성공 응답을 보내고 있습니다. +

현금영수증 발급 API 호출시 유효성 검사를 하지 않음

-따라서 원활한 현금영수증 발급을 위해서는 현금영수증 발급 API 호출시 현금영수증 정보를 정확하게 입력하셔야 합니다. + 예를 들어 현금영수증 발급 유형(type)을 소득공제(person)으로 보내고 현금영수증 발급 번호(identifier)를 사업자 등록번호로 보내면 실제로는 현금영수증 발급에 실패해야하지만 토스페이먼츠에서 유효성 검사를 하지 않아 그대로 성공 응답을 보내고 있습니다. + 따라서 원활한 현금영수증 발급을 위해서는 현금영수증 발급 API 호출시 현금영수증 정보를 정확하게 입력하셔야 합니다.
-

사파리 / 파이어폭스 브라우저 내 팝업 블로커 이슈

- -사파리 / 파이어폭스 브라우저에서 설정에서 팝업이 차단되어있는 경우 페이북 결제시 팝업이 뜨지 않아 결제 진행이 되지 않거나 가상계좌 발급이나 휴대폰 소액결제시 승인에 실패하는 등 결제가 원활하게 진행되지 않을 수 있으니, 반드시 팝업을 해제하시고 시도해주시기 바랍니다. +

사파리 / 파이어폭스 브라우저 내 팝업 블로커 이슈

+ 사파리 / 파이어폭스 브라우저에서 설정에서 팝업이 차단되어있는 경우 페이북 결제시 팝업이 뜨지 않아 결제 진행이 되지 않거나 가상계좌 발급이나 휴대폰 소액결제시 승인에 실패하는 등 결제가 원활하게 진행되지 않을 수 있으니, 반드시 팝업을 해제하시고 시도해주시기 바랍니다.
-

IE 브라우저 - 카드결제 - 페이코 선택시 아래와 같이 결제창이 잘리는 이슈

- -이에 대해 토스로부터 “IE 에서 fade out 이 되고 있으므로 수정에 우선순위를 두기 어려울것 같습니다.”라는 답변을 받았습니다. +

IE 브라우저 - 카드결제 - 페이코 선택시 아래와 같이 결제창이 잘리는 이슈

+ 이에 대해 토스로부터 “IE 에서 fade out 이 되고 있으므로 수정에 우선순위를 두기 어려울것 같습니다.”라는 답변을 받았습니다.
-

IE 브라우저 결제 중단시 에러 메시지 인코딩 이슈

- -IE 브라우저에서 결제 중단(결제 승인/실패 이전에 결제창을 명시적으로 닫을때)시 토스페이먼츠로부터 아래와 같이 인코딩 된 에러 메시지가 전달되는 이슈가 있습니다. (이를 디코딩해보면 “사용자가결제를취소하였습니다”라는 메시지) +

IE 브라우저 결제 중단시 에러 메시지 인코딩 이슈

-`%EC%82%AC%EC%9A%A9%EC%9E%90%EA%B0%80 %EA%B2%B0%EC%A0%9C%EB%A5%BC %EC%B7%A8%EC%86%8C%ED%95%98%EC%98%80%EC%8A%B5%EB%8B%88%EB%8B%A4` + IE 브라우저에서 결제 중단(결제 승인/실패 이전에 결제창을 명시적으로 닫을때)시 토스페이먼츠로부터 아래와 같이 인코딩 된 에러 메시지가 전달되는 이슈가 있습니다. (이를 디코딩해보면 “사용자가결제를취소하였습니다”라는 메시지) -이에 대해 토스로부터 “IE 의 인코딩 이슈라서 저희가 수정해 드리기가 애매하고, 내부적으로 IE 는 fadeout 되어 더 이상 공식적으로 지원을 하지 않고 있습니다.”라는 답변을 받았습니다. + `%EC%82%AC%EC%9A%A9%EC%9E%90%EA%B0%80 %EA%B2%B0%EC%A0%9C%EB%A5%BC %EC%B7%A8%EC%86%8C%ED%95%98%EC%98%80%EC%8A%B5%EB%8B%88%EB%8B%A4` + 이에 대해 토스로부터 “IE 의 인코딩 이슈라서 저희가 수정해 드리기가 애매하고, 내부적으로 IE 는 fadeout 되어 더 이상 공식적으로 지원을 하지 않고 있습니다.”라는 답변을 받았습니다.
diff --git a/src/content/docs/ko/pg/payment-gateway/nhn-kcp.mdx b/src/content/docs/ko/pg/payment-gateway/nhn-kcp.mdx index 485495b3a..03d02d1ba 100644 --- a/src/content/docs/ko/pg/payment-gateway/nhn-kcp.mdx +++ b/src/content/docs/ko/pg/payment-gateway/nhn-kcp.mdx @@ -3,544 +3,541 @@ title: NHN KCP description: NHN KCP 결제창 연동 가이드입니다. --- +import Figure from "~/components/Figure.astro"; import Codepen from "~/components/gitbook/Codepen.astro"; import ContentRef from "~/components/gitbook/ContentRef.astro"; -import Figure from "~/components/Figure.astro"; -import Hint from "~/components/Hint.astro"; -import Tabs from "~/components/gitbook/tabs/Tabs.astro"; import Tab from "~/components/gitbook/tabs/Tab.astro"; +import Tabs from "~/components/gitbook/tabs/Tabs.astro"; +import Hint from "~/components/Hint.astro"; -### 1. NHN KCP 채널 설정하기 +## 1. NHN KCP 채널 설정하기 [결제대행사 채널 설정하기](../../ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다.
-### 2.결제 요청하기 +## 2.결제 요청하기 [JavaScript SDK](../../sdk/javascript-sdk/readme) `IMP.request_pay(param, callback)`을 호출하여 NHN KCP 결제창을 호출할 수 있습니다. **결제결과**는 PC의 경우 `IMP.request_pay(param, callback)` 호출 후 **callback** 으로 수신되고 -모바일의 경우 **m_redirect_url** 로 리디렉션됩니다. +모바일의 경우 **m\_redirect\_url** 로 리디렉션됩니다. - -```javascript -IMP.request_pay({ - pg : 'kcp.{사이트코드}', //테스트인경우 kcp.T0000 - pay_method : 'card', - merchant_uid: "order_no_0001", //상점에서 생성한 고유 주문번호 - name : '주문명:결제테스트', - amount : 1004, - company : '상호명',//해당 파라미터 설정시 통합결제창에 해당 상호명이 노출됩니다. - buyer_email : 'test@portone.io', - buyer_name : '구매자이름', - buyer_tel : '010-1234-5678', - buyer_addr : '서울특별시 강남구 삼성동', - buyer_postcode : '123-456', - language : 'ko', // en 설정시 영문으로 출력되면 해당 파라미터 생략시 한국어 default - m_redirect_url : '{모바일에서 결제 완료 후 리디렉션 될 URL}', - auth_mode:'key-in' // 키인결제(일회성 결제)이용시 설정 -}, function(rsp) { // callback 로직 - //* ...중략... *// -}); -``` - -### 주요 파라미터 설명 - -**`pg`** **\*** **string** - -**PG사 구분코드** - -`kcp.{사이트코드}` - -사이트코드 값은 KCP 계약 후 KCP로 부터 발급받을수 있습니다. - -**`pay_method`** **\*** **string** - -**결제수단 구분코드** - -- card (신용카드) -- samsung (삼성페이) -- trans (실시간 계좌이체) -- vbank(가상계좌) -- phone (휴대폰소액결제) -- payco (페이코 허브형) -- lpay(L페이 허브형) -- cultureland (문화상품권) -- smartculture (스마트문상) -- happymoney (해피머니) -- booknlife (도서문화상품권) -- point (베네피아 포인트) -- kakaopay(카카오페이) -- naverpay(네이버페이) -- applepay(애플페이) - -**`merchant_uid`** **\*** **string** - -**주문번호** - -매번 고유하게 채번되어야 합니다. - -**`amount`** **\*** **integer** - -**결제금액** - -**string** 이 아닌점에 유의하세요 - - -**payco 허브형**인 경우 KCP 관리자페이지 신청 및 설정이 필요합니다. - -신청안내 링크 : [https://sir.kr/main/service/p_payco_hub.php](https://sir.kr/main/service/p_payco_hub.php) - - - - - - - - -인증결제창 호출 파라미터에서 **customer\_uid** 값을 추가하면 비 인증 결제창을 호출할 수 있습니다. 비인증 결제창에서 빌링키를 발급받은 후 해당 빌링키로 결제를 요청합니다. - -```javascript title="Javascript SDK" showLineNumbers -IMP.request_pay( - { - pg: "kcp_billing.{사이트코드}", - pay_method: "card", // 'card'만 지원됩니다. - merchant_uid: "order_monthly_0001", // 상점에서 관리하는 주문 번호 - name: "최초인증결제", - amount: 0, // 결제창에 표시될 금액. 실제 승인이 이뤄지지는 않습니다. - customer_uid: "your-customer-unique-id", // 필수 입력. - buyer_email: "test@portone.io", - buyer_name: "포트원", - buyer_tel: "02-1234-1234", - m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", - }, - function (rsp) { - if (rsp.success) { - alert("빌링키 발급 성공"); - } else { - alert("빌링키 발급 실패"); - } - } -); -``` + + ```javascript + IMP.request_pay( + { + pg: "kcp.{사이트코드}", //테스트인경우 kcp.T0000 + pay_method: "card", + merchant_uid: "order_no_0001", //상점에서 생성한 고유 주문번호 + name: "주문명:결제테스트", + amount: 1004, + company: "상호명", //해당 파라미터 설정시 통합결제창에 해당 상호명이 노출됩니다. + buyer_email: "test@portone.io", + buyer_name: "구매자이름", + buyer_tel: "010-1234-5678", + buyer_addr: "서울특별시 강남구 삼성동", + buyer_postcode: "123-456", + language: "ko", // en 설정시 영문으로 출력되면 해당 파라미터 생략시 한국어 default + m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", + auth_mode: "key-in", // 키인결제(일회성 결제)이용시 설정 + }, + function (rsp) { + // callback 로직 + //* ...중략... *// + }, + ); + ``` + + ## 주요 파라미터 설명 + + **`pg`** **\*** **string** + + **PG사 구분코드** + + `kcp.{사이트코드}` + + 사이트코드 값은 KCP 계약 후 KCP로 부터 발급받을수 있습니다. + + **`pay_method`** **\*** **string** - -- 비인증 결제를 위해서는 **KCP와 협의가 완료된 사이트코드**를 관리자콘솔에 설정하셔야 비인증 결제창을 활성화 시킬수 있습니다. -- KCP는 빌링키 발급시 **실 결제는 발생되지 않습니다**.(금액을 지정해도 결제가 발생되지 않음) + **결제수단 구분코드** + + - card (신용카드) + - samsung (삼성페이) + - trans (실시간 계좌이체) + - vbank(가상계좌) + - phone (휴대폰소액결제) + - payco (페이코 허브형) + - lpay(L페이 허브형) + - cultureland (문화상품권) + - smartculture (스마트문상) + - happymoney (해피머니) + - booknlife (도서문화상품권) + - point (베네피아 포인트) + - kakaopay(카카오페이) + - naverpay(네이버페이) + - applepay(애플페이) - + **`merchant_uid`** **\*** **string** -### + **주문번호** -### 주요 파라미터 설명 + 매번 고유하게 채번되어야 합니다. -**`pg`** **\*** **string** + **`amount`** **\*** **integer** -**PG사 구분코드** + **결제금액** -`kcp_billing.{사이트코드}` + **string** 이 아닌점에 유의하세요 -사이트코드 값은 KCP 계약 후 KCP로 부터 발급받을수 있습니다. + + **payco 허브형**인 경우 KCP 관리자페이지 신청 및 설정이 필요합니다. -**`customer_uid`** **\*** **string** + 신청안내 링크 : [https://sir.kr/main/service/p\_payco\_hub.php](https://sir.kr/main/service/p_payco_hub.php) + -**카드 빌링키** + + -비 인증 결제창에서 고객이 입력한 카드정보와 1:1로 매칭될 빌링키를 지정합니다. + + 인증결제창 호출 파라미터에서 **customer\_uid** 값을 추가하면 비 인증 결제창을 호출할 수 있습니다. 비인증 결제창에서 빌링키를 발급받은 후 해당 빌링키로 결제를 요청합니다. -**`amount`** **\*** **Integer** + ```javascript title="Javascript SDK" showLineNumbers + IMP.request_pay( + { + pg: "kcp_billing.{사이트코드}", + pay_method: "card", // 'card'만 지원됩니다. + merchant_uid: "order_monthly_0001", // 상점에서 관리하는 주문 번호 + name: "최초인증결제", + amount: 0, // 결제창에 표시될 금액. 실제 승인이 이뤄지지는 않습니다. + customer_uid: "your-customer-unique-id", // 필수 입력. + buyer_email: "test@portone.io", + buyer_name: "포트원", + buyer_tel: "02-1234-1234", + m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", + }, + function (rsp) { + if (rsp.success) { + alert("빌링키 발급 성공"); + } else { + alert("빌링키 발급 실패"); + } + }, + ); + ``` -**결제금액** + + - 비인증 결제를 위해서는 **KCP와 협의가 완료된 사이트코드**를 관리자콘솔에 설정하셔야 비인증 결제창을 활성화 시킬수 있습니다. + - KCP는 빌링키 발급시 **실 결제는 발생되지 않습니다**.(금액을 지정해도 결제가 발생되지 않음) + -결제창에 표시될 금액으로 실제 승인은 이루어지지 않습니다.(실 결제를 발생시키기 위해서는 **customer_uid** 로 **REST API 를 이용하여 결제요청**을 해주셔야 합니다.) + ## 주요 파라미터 설명 -### 빌링키(customer_uid)로 결제 요청하기 + **`pg`** **\*** **string** -빌링키 발급이 성공하면 실 빌링키는 customer_uid 와 1:1 매칭되어 **포트원 서버에 저장**됩니다. customer_uid를 고객사 내부서버에 저장하시고 [**비 인증 결제요청 REST API**](../../api/api-4/api)를 호출하시면 결제를 발생시킬 수 있습니다. + **PG사 구분코드** -```sh title="server-side" -curl -H "Content-Type: application/json" \ - -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "amount":3000}' \ - https://api.iamport.kr/subscribe/payments/again -``` + `kcp_billing.{사이트코드}` -**API 방식으로 빌링키 발급,결제요청,예약결제를 구현할수 있습니다.** + 사이트코드 값은 KCP 계약 후 KCP로 부터 발급받을수 있습니다. - + **`customer_uid`** **\*** **string** - -### 일회성 결제 요청하기 + **카드 빌링키** -REST [**API POST /subscribe/payments/onetime**](../../api/api-4/api-1)을 호출하여 일회성 결제를 요청합니다. 요청 시 전달된 카드는 포트원에 등록되지 않습니다. + 비 인증 결제창에서 고객이 입력한 카드정보와 1:1로 매칭될 빌링키를 지정합니다. -```sh -curl -H "Content-Type: application/json" \ - -X POST -d '{"merchant_uid":"order_id_8237352", "card_number":"1234-1234-1234-1234", "expiry":"2019-01", "birth":"123456", "amount":3000}' \ - https://api.iamport.kr/subscribe/payments/onetime -``` + **`amount`** **\*** **Integer** -#### + **결제금액** -### 빌링키 발급 요청하기 + 결제창에 표시될 금액으로 실제 승인은 이루어지지 않습니다.(실 결제를 발생시키기 위해서는 **customer\_uid** 로 **REST API 를 이용하여 결제요청**을 해주셔야 합니다.) -REST [**API POST /subscribe/customers/\{customer_uid}**](../../api/api-2/api-1)를 호출하여 빌링키 발급을 요청합니다. + ## 빌링키(customer\_uid)로 결제 요청하기 -```sh -curl -H "Content-Type: application/json" \ - -X POST -d '{"card_number":"1234-1234-1234-1234", "expiry":"2025-12", "birth":"820213", "pwd_2digit":"00"}' \ - https://api.iamport.kr/subscribe/customers/your-customer-unique-id -``` + 빌링키 발급이 성공하면 실 빌링키는 customer\_uid 와 1:1 매칭되어 **포트원 서버에 저장**됩니다. customer\_uid를 고객사 내부서버에 저장하시고 [**비 인증 결제요청 REST API**](../../api/api-4/api)를 호출하시면 결제를 발생시킬 수 있습니다. -#### + ```sh title="server-side" + curl -H "Content-Type: application/json" \ + -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "amount":3000}' \ + https://api.iamport.kr/subscribe/payments/again + ``` -### 빌링키 발급 및 최초 결제 요청하기 + **API 방식으로 빌링키 발급,결제요청,예약결제를 구현할수 있습니다.** + -REST [**API POST /subscribe/payments/onetime**](../../api/api-4/api-1)을 호출하여 빌링키 발급과 최초 결제를 요청합니다. + + ## 일회성 결제 요청하기 -- **`customer_uid`** : 빌링키 등록을 위해서 지정해야 합니다. + REST [**API POST /subscribe/payments/onetime**](../../api/api-4/api-1)을 호출하여 일회성 결제를 요청합니다. 요청 시 전달된 카드는 포트원에 등록되지 않습니다. -```sh -curl -H "Content-Type: application/json" \ - -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "card_number":"1234-1234-1234-1234", "expiry":"2019-01", "birth":"123456", "amount":3000}' \ - https://api.iamport.kr/subscribe/payments/onetime -``` + ```sh + curl -H "Content-Type: application/json" \ + -X POST -d '{"merchant_uid":"order_id_8237352", "card_number":"1234-1234-1234-1234", "expiry":"2019-01", "birth":"123456", "amount":3000}' \ + https://api.iamport.kr/subscribe/payments/onetime + ``` -#### + ## 빌링키 발급 요청하기 -### 빌링키로 결제 요청하기 + REST [**API POST /subscribe/customers/\{customer\_uid}**](../../api/api-2/api-1)를 호출하여 빌링키 발급을 요청합니다. -빌링키 발급과 최초 결제가 성공하면 빌링키는 전달된 `customer_uid` 와 1:1 매칭되어 포트원에 저장됩니다. 보안상의 이유로 서버는 빌링키에 직접 접근할 수 없기 때문에 `customer_uid`를 이용해서 재결제([**POST /subscribe/payments/again**](../../api/api-4/api)) REST API를 다음과 같이 호출합니다. + ```sh + curl -H "Content-Type: application/json" \ + -X POST -d '{"card_number":"1234-1234-1234-1234", "expiry":"2025-12", "birth":"820213", "pwd_2digit":"00"}' \ + https://api.iamport.kr/subscribe/customers/your-customer-unique-id + ``` -```sh -curl -H "Content-Type: application/json" \ - -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "amount":3000}' \ - https://api.iamport.kr/subscribe/payments/again -``` + ## 빌링키 발급 및 최초 결제 요청하기 -**자세한 가이드는 아래 링크를 참조하세요** + REST [**API POST /subscribe/payments/onetime**](../../api/api-4/api-1)을 호출하여 빌링키 발급과 최초 결제를 요청합니다. - + - **`customer_uid`** : 빌링키 등록을 위해서 지정해야 합니다. - + ```sh + curl -H "Content-Type: application/json" \ + -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "card_number":"1234-1234-1234-1234", "expiry":"2019-01", "birth":"123456", "amount":3000}' \ + https://api.iamport.kr/subscribe/payments/onetime + ``` + + ## 빌링키로 결제 요청하기 + + 빌링키 발급과 최초 결제가 성공하면 빌링키는 전달된 `customer_uid` 와 1:1 매칭되어 포트원에 저장됩니다. 보안상의 이유로 서버는 빌링키에 직접 접근할 수 없기 때문에 `customer_uid`를 이용해서 재결제([**POST /subscribe/payments/again**](../../api/api-4/api)) REST API를 다음과 같이 호출합니다. + + ```sh + curl -H "Content-Type: application/json" \ + -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "amount":3000}' \ + https://api.iamport.kr/subscribe/payments/again + ``` + + **자세한 가이드는 아래 링크를 참조하세요** + + + -### 3. 부가기능 +## 3. 부가기능 - -```javascript title="javascript" -display: { - card_quota: [6] // 할부개월 6개월까지만 활성화 -} -``` - -**파라미터 설명** - -- **card_quota :** - - `[]`: 일시불만 결제 가능 - - `2,3,4,5,6`: 일시불을 포함한 2, 3, 4, 5, 6개월까지 할부개월 선택 가능\\ - - -할부결제는 **5만원 이상 결제 요청시**에만 이용 가능합니다. - - - -할부개월수 **3개월****까지 활성화 예제** - - - - - - -```javascript title="javascript" -{ - card: { - direct: { - code: "367", - quota: 3 - // 카드사 포인트 사용 경우 - // quota: 80 = 80(현대카드 포인트 할부개월) + 0(일시불) - // quota: 93 = 80(현대카드 포인트 할부개월) + 13개월 할부 - // quota: 60 = 60(기타카드 포인트 할부개월) + 0(일시불) - // quota: 63 = 60(기타카드 포인트 할부개월) + 3개월 할부 + + ```javascript title="javascript" + display: { + card_quota: [6]; // 할부개월 6개월까지만 활성화 + } + ``` + + **파라미터 설명** + + - **card\_quota :** + - `[]`: 일시불만 결제 가능 + - `2,3,4,5,6`: 일시불을 포함한 2, 3, 4, 5, 6개월까지 할부개월 선택 가능\\ + + + 할부결제는 **5만원 이상 결제 요청시**에만 이용 가능합니다. + + + 할부개월수 **3개월****까지 활성화 예제** + + + + + + ```json + { + card: { + direct: { + code: "367", + quota: 3 + // 카드사 포인트 사용 경우 + // quota: 80 = 80(현대카드 포인트 할부개월) + 0(일시불) + // quota: 93 = 80(현대카드 포인트 할부개월) + 13개월 할부 + // quota: 60 = 60(기타카드 포인트 할부개월) + 0(일시불) + // quota: 63 = 60(기타카드 포인트 할부개월) + 3개월 할부 + } + }, + company: "고객사", // 해당 파라미터를 설정하지 않으면 카드사 모듈 창에 import 로 표기 + } + ``` + + **파라미터 설명** + + - **code**: 카드사 금융결제원 표준 코드. [**링크**](https://faq.portone.io/6503bcb4-4a61-4cf3-afd8-5d913b1385a6) 참조 (**string**) + + - **quota**: 할부 개월 수. 일시불일 시 0 으로 지정. 만약, 신용 카드사 포인트를 사용할 경우 카드사별 포인트 할부개월\[1]을 할부 개월 수에 더해줘야 합니다. (**integer**) + +
+ \[1] 카드사별 포인트 할부개월 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

카드사 포인트

+ 		+

포인트 할부개월

+
+

현대M

+ 		+

+80

+
+

국민

+ 		+

+60

+
+

비씨

+ 		+

+60

+
+

삼성

+ 		+

+60

+
+

하나/외환

+ 		+

+60

+
+

롯데

+ 		+

+60

+
+

신한

+ 		+

+60

+
+

농협

+ 		+

+60

+
+

씨티

+ 		+

+60

+
+

우리

+ 		+

+60

+
+
+ + + **주의사항** + + - 현재 **KG이니시스, KCP, 토스페이먼츠, 나이스페이먼츠, KICC, 다날** 6개 PG사에 대해서만 카드사 결제창 direct 호출이 가능합니다. + - 일부 PG사의 경우, 모든 상점아이디에 대하여 카드사 결제창 direct 노출 기능을 지원하지 않습니다. 반드시 포트원을 통해 현재 사용중인 상점아이디가 카드사 결제창 direct 호출이 가능하도록 설정이 되어있는지 PG사에 확인이 필요합니다. + + + **현대카드** 결제모듈 바로 호출 예제 + + + + + + ```javascript + { + card: { + detail: [ + { card_code: "*", enabled: false }, // 모든 카드사 비활성화 + { card_code: "366", enabled: true }, // 특정 카드만 활성화 + ]; + } + } + ``` + + **파라미터 설명** + + - **card\_code :** 금결원 카드사코드 [**링크**](https://faq.portone.io/6503bcb4-4a61-4cf3-afd8-5d913b1385a6) 참조 (**string)** + - **enabled :** 해당카드 활성화 여부 (**boolean)** + + **신한카드****만 결제창 노출 처리 예제** + + + + + + 인증결제시 각 카드사 앱카드 결제 화면만 노출하고 싶은 경우 아래 파라미터를 설정하시면 됩니다. + + ```javascript title="request_pay()" + { + appCard: true; //true 설정시 각 카드사 앱카드 결제만 활성화 } - }, - company: "고객사", // 해당 파라미터를 설정하지 않으면 카드사 모듈 창에 import 로 표기 -} -```` - -**파라미터 설명** - -- **code**: 카드사 금융결제원 표준 코드. [**링크**](https://faq.portone.io/6503bcb4-4a61-4cf3-afd8-5d913b1385a6) 참조 (**string**) -- **quota**: 할부 개월 수. 일시불일 시 0 으로 지정. 만약, 신용 카드사 포인트를 사용할 경우 카드사별 포인트 할부개월[1]을 할부 개월 수에 더해줘야 합니다. (**integer**) -
- [1] 카드사별 포인트 할부개월 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-

카드사 포인트

- 		-

포인트 할부개월

-
-

현대M

- 		-

+80

-
-

국민

- 		-

+60

-
-

비씨

- 		-

+60

-
-

삼성

- 		-

+60

-
-

하나/외환

- 		-

+60

-
-

롯데

- 		-

+60

-
-

신한

- 		-

+60

-
-

농협

- 		-

+60

-
-

씨티

- 		-

+60

-
-

우리

- 		-

+60

-
-
- - -**주의사항** - -- 현재 **KG이니시스, KCP, 토스페이먼츠, 나이스페이먼츠, KICC, 다날** 6개 PG사에 대해서만 카드사 결제창 direct 호출이 가능합니다. -- 일부 PG사의 경우, 모든 상점아이디에 대하여 카드사 결제창 direct 노출 기능을 지원하지 않습니다. 반드시 포트원을 통해 현재 사용중인 상점아이디가 카드사 결제창 direct 호출이 가능하도록 설정이 되어있는지 PG사에 확인이 필요합니다. - - - -**현대카드** 결제모듈 바로 호출 예제 - - - - - - -```javascript -{ - card: { - detail: [ - { card_code: "*", enabled: false }, // 모든 카드사 비활성화 - { card_code: "366", enabled: true } // 특정 카드만 활성화 - ] - } -} -```` - -**파라미터 설명** - -- **card_code :** 금결원 카드사코드 [**링크**](https://faq.portone.io/6503bcb4-4a61-4cf3-afd8-5d913b1385a6) 참조 (**string)** -- **enabled :** 해당카드 활성화 여부 (**boolean)** - -**신한카드****만 결제창 노출 처리 예제** - - - - - - -인증결제시 각 카드사 앱카드 결제 화면만 노출하고 싶은 경우 아래 파라미터를 설정하시면 됩니다. - -```javascript title="request_pay()" -{ - appCard: true; //true 설정시 각 카드사 앱카드 결제만 활성화 -} -``` - - + ``` + ### 4. 기타 파라미터 - -**상품권 결제수단**을 사용하기 위해서는 고객사에서 관리하는 회원ID를 아래와 같은 방법으로 파라미터 설정이 필요합니다. - -```javascript title="javascript SDK" -{ - bypass: { - shop_user_id: "ABCD123"; // 고객사 회원ID (20byte) - } -} -``` - - -**상품권 기관 RM 조치를 위해 필수적으로 실어주셔야 합니다.** - - - -**컬처랜드 문화 상품권을 호출하는 경우** - -```javascript -IMP.request_pay({ - pg: "kcp.{문화상품권 대상 사이트코드}", - pay_method: "cultureland", //문화상품권 - merchant_uid: "A00021-TEST", - name: "당근 10kg", - amount: 1004, - buyer_email: "iamport@chai.finance", - buyer_name: "포트원 기술지원팀", - buyer_tel: "010-1234-5678", - buyer_addr: "서울특별시 강남구 삼성동", - buyer_postcode: "123-456", - bypass: { - shop_user_id: "abaddd", // 고객사 회원 id기재 - }, -}); -``` - - - - -에스크로 결제를 위해서는 **`escrow`** 파라미터를 추가하고 **true** 값으로 설정되어야 합니다. 에스크로 결제요청 시 **장바구니 상품을 묶어서 결제하는 경우** 해당 품목에 대한 정보를 전달하기 위해 해당 상품관련 정보를 추가 파라미터(**`kcpProducts`**)로 전달해야 합니다.\ -\*\*`kcpProducts`\*\*는 다음 4개의 필수 속성으로 구성된 객체배열입니다. - -**`amount`** 값은 결제 금액(`param.amount`) 값과 관계가 없으며 비교검증되지 않습니다. - -- orderNumber : 상품주문번호 -- name : 상품명 -- quantity : 수량 -- amount : 상품 가격 - -```javascript title="JavaScript SDK" -IMP.request_pay({ - pg: "kcp", - escrow: true, // 에스크로 결제인 경우 필요 - kcpProducts: [ + + **상품권 결제수단**을 사용하기 위해서는 고객사에서 관리하는 회원ID를 아래와 같은 방법으로 파라미터 설정이 필요합니다. + + ```javascript title="javascript SDK" { - orderNumber: "xxxx", - name: "상품A", - quantity: 3, - amount: 1000, - }, + bypass: { + shop_user_id: "ABCD123"; // 고객사 회원ID (20byte) + } + } + ``` + + + **상품권 기관 RM 조치를 위해 필수적으로 실어주셔야 합니다.** + + + **컬처랜드 문화 상품권을 호출하는 경우** + + ```javascript + IMP.request_pay({ + pg: "kcp.{문화상품권 대상 사이트코드}", + pay_method: "cultureland", //문화상품권 + merchant_uid: "A00021-TEST", + name: "당근 10kg", + amount: 1004, + buyer_email: "iamport@chai.finance", + buyer_name: "포트원 기술지원팀", + buyer_tel: "010-1234-5678", + buyer_addr: "서울특별시 강남구 삼성동", + buyer_postcode: "123-456", + bypass: { + shop_user_id: "abaddd", // 고객사 회원 id기재 + }, + }); + ``` + + + + 에스크로 결제를 위해서는 **`escrow`** 파라미터를 추가하고 **true** 값으로 설정되어야 합니다. 에스크로 결제요청 시 **장바구니 상품을 묶어서 결제하는 경우** 해당 품목에 대한 정보를 전달하기 위해 해당 상품관련 정보를 추가 파라미터(**`kcpProducts`**)로 전달해야 합니다.\ + \*\*`kcpProducts`\*\*는 다음 4개의 필수 속성으로 구성된 객체배열입니다. + + **`amount`** 값은 결제 금액(`param.amount`) 값과 관계가 없으며 비교검증되지 않습니다. + + - orderNumber : 상품주문번호 + - name : 상품명 + - quantity : 수량 + - amount : 상품 가격 + + ```javascript title="JavaScript SDK" + IMP.request_pay({ + pg: "kcp", + escrow: true, // 에스크로 결제인 경우 필요 + kcpProducts: [ + { + orderNumber: "xxxx", + name: "상품A", + quantity: 3, + amount: 1000, + }, + { + orderNumber: "yyyy", + name: "상품B", + quantity: 2, + amount: 3000, + }, + ], + /* ...중략 (README 파일에서 상세 샘플코드를 확인하세요)... */ + }); + ``` + + + + ```javascript title="request_pay()" { - orderNumber: "yyyy", - name: "상품B", - quantity: 2, - amount: 3000, - }, - ], - /* ...중략 (README 파일에서 상세 샘플코드를 확인하세요)... */ -}); -``` - - - - -```javascript title="request_pay()" -{ - prefill: { - phoneNumber: "고정할 휴대폰번호" - } -} -``` - -숫자만 입력하세요 - - - - -```javascript -IMP.request_pay({ - ... - bypass: { - coupon_apply_yn: "Y", // 미사용시 "N" - }, - ... -}); -``` - -인증 결제창내 할인쿠폰 UX를 활성/비활성화 할 수 있습니다. -해당 기능은 KCP와 협의 후 사용 가능 합니다. - - - - -```javascript -IMP.request_pay({ - ... - bypass : { - batch_birth_day_yn: "Y", // 결제창 렌더링 시 생년월일 입력 박스 고정 활성화 - } - ... -}); -``` - -NHN KCP 결제창을 이용한 빌링키 발급 시 PC 환경에서 공인인증서 절차를 생략하는 경우 -카드 정보 입력 화면에서 생년월일 입력 박스가 표시되도록 고정시킬 수 있습니다. -해당 파라미터를 설정하지 않고 빌링키 발급 진행 시 최초 주민등록번호 입력 박스가 표시되며, 카드 정보 8자리 입력 시 생년월일 입력 박스로 변환됩니다. - - - + prefill: { + phoneNumber: "고정할 휴대폰번호"; + } + } + ``` + + 숫자만 입력하세요 + + + + ```javascript + IMP.request_pay({ + bypass: { + coupon_apply_yn: "Y", // 미사용시 "N" + }, + }); + ``` + + 인증 결제창내 할인쿠폰 UX를 활성/비활성화 할 수 있습니다. + 해당 기능은 KCP와 협의 후 사용 가능 합니다. + + + + ```javascript + IMP.request_pay({ + bypass: { + batch_birth_day_yn: "Y", // 결제창 렌더링 시 생년월일 입력 박스 고정 활성화 + }, + }); + ``` + + NHN KCP 결제창을 이용한 빌링키 발급 시 PC 환경에서 공인인증서 절차를 생략하는 경우 + 카드 정보 입력 화면에서 생년월일 입력 박스가 표시되도록 고정시킬 수 있습니다. + 해당 파라미터를 설정하지 않고 빌링키 발급 진행 시 최초 주민등록번호 입력 박스가 표시되며, 카드 정보 8자리 입력 시 생년월일 입력 박스로 변환됩니다. + diff --git a/src/content/docs/ko/pg/payment-gateway/nice-v2/readme.mdx b/src/content/docs/ko/pg/payment-gateway/nice-v2/readme.mdx index cae60471d..7a1461489 100644 --- a/src/content/docs/ko/pg/payment-gateway/nice-v2/readme.mdx +++ b/src/content/docs/ko/pg/payment-gateway/nice-v2/readme.mdx @@ -3,16 +3,14 @@ title: 나이스페이먼츠 (신모듈) description: 나이스페이먼츠 연동 방법을 안내합니다. --- -import * as prose from "~/components/prose"; import Details from "~/components/gitbook/Details.astro"; import Hint from "~/components/Hint.astro"; +import * as prose from "~/components/prose"; export const components = prose; - -import Figure from "~/components/Figure.astro"; -import Tabs from "~/components/gitbook/tabs/Tabs.astro"; import Tab from "~/components/gitbook/tabs/Tab.astro"; +import Tabs from "~/components/gitbook/tabs/Tabs.astro"; -### 1. 나이스페이먼츠(신모듈) 채널 설정하기 +## 1. 나이스페이먼츠(신모듈) 채널 설정하기 [결제대행사 채널 설정하기](../../ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다. @@ -20,14 +18,23 @@ import Tab from "~/components/gitbook/tabs/Tab.astro"; 그렇지 않은 상태에서 해당 기능 이용시 PG창 호출에 실패하거나, 승인에 실패하거나, 승인에 성공하더라도 의도한 바와는 다른 응답을 얻게 될 수 있으니 주의 해주시기 바랍니다. - 모든 결제 수단(간편결제 포함) + - 면세 / 복합과세 사용 + - 부가세 지정 금액 방식 사용(영세율 포함) + - 부분 취소 + - 할부 사용 + - 상점 부담 무이자 할부 사용 + - 카드사 포인트 사용 + - 에스크로 사용 + - 해외 결제 사용 + - 일부 bypass 파라미터 - UserCI - MallUserID @@ -35,167 +42,160 @@ import Tab from "~/components/gitbook/tabs/Tab.astro"; - PaycoClientId, PaycoAccessToken - SamPayMallType -### 2. 최신 JavaScript SDK로 업데이트하기 +## 2. 최신 JavaScript SDK로 업데이트하기 나이스페이먼츠(신모듈) 결제는 최신 SDK에서만 지원되는 기능입니다. -```javascript title="JS SDK" +```html title="JS SDK" ``` **(신) 나이스페이먼츠를 연동하기 위해서는 위에 안내된 JS SDK를 이용하셔야 합니다** - -#### **기존에 deprecated된 콜백 응답은 모두 제거**됐습니다. + ### **기존에 deprecated된 콜백 응답은 모두 제거**됐습니다. -신규 JS SDK는 기존 모듈에서 제공했던 CallBack 응답 파라미터가 대부분 삭제되었습니다. -(특히 deprecated 로 명시된 파라미터는 모두 삭제되었습니다.) + 신규 JS SDK는 기존 모듈에서 제공했던 CallBack 응답 파라미터가 대부분 삭제되었습니다. + (특히 deprecated 로 명시된 파라미터는 모두 삭제되었습니다.) -해당 JS SDK 사용시 Callback 으로 내려받을수 있는 데이터는 오직 아래 두가지 입니다. + 해당 JS SDK 사용시 Callback 으로 내려받을수 있는 데이터는 오직 아래 두가지 입니다. -**`imp_uid`, `merchant_uid`** - -따라서 해당 SDK를 사용하실때는 `IMP.request_pay`로부터 응답된 객체(또는 쿼리 파라미터)에서 -`imp_uid`를 가지고 **아임포트 REST API(GET `/payments/imp_uid`)로 결제 상세 내역(승인 상태, 승인 결과 등등)을 조회**하여 -응답 파라미터 중 `status` 파라미터로 결제 상태를 파악하셔야 합니다. + **`imp_uid`, `merchant_uid`** + 따라서 해당 SDK를 사용하실때는 `IMP.request_pay`로부터 응답된 객체(또는 쿼리 파라미터)에서 + `imp_uid`를 가지고 **아임포트 REST API(GET `/payments/imp_uid`)로 결제 상세 내역(승인 상태, 승인 결과 등등)을 조회**하여 + 응답 파라미터 중 `status` 파라미터로 결제 상태를 파악하셔야 합니다. [JavaScript SDK](../../../sdk/javascript-sdk/readme) 문서를 통해 최신 SDK를 설치해주세요. -### 3.결제 요청하기 +## 3.결제 요청하기 [JavaScript SDK](../../../sdk/javascript-sdk/readme) `IMP.request_pay(param, callback)`을 호출하여 (신) 나이스페이먼츠 결제창을 호출할 수 있습니다. **결제 결과**는 PC의 경우 `IMP.request_pay(param, callback)` 호출 후 **callback**으로 수신되고 모바일의 경우 -**m_redirect_url** 로 리디렉션됩니다. +**m\_redirect\_url** 로 리디렉션됩니다. - -```javascript title="Javascript SDK" -IMP.request_pay( - { - pg: "nice_v2.{상점 ID}", - pay_method: "card", - merchant_uid: "orderNo0001", - name: "주문명:결제테스트", - amount: 1004, - buyer_email: "test@portone.io", - buyer_name: "구매자이름", - buyer_tel: "010-1234-5678", - buyer_addr: "서울특별시 강남구 삼성동", - buyer_postcode: "123-456", - m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", - }, - function (rsp) { - // callback 로직 - } -); -``` - -
-

주요 파라미터 설명

+ + ```javascript title="Javascript SDK" + IMP.request_pay( + { + pg: "nice_v2.{상점 ID}", + pay_method: "card", + merchant_uid: "orderNo0001", + name: "주문명:결제테스트", + amount: 1004, + buyer_email: "test@portone.io", + buyer_name: "구매자이름", + buyer_tel: "010-1234-5678", + buyer_addr: "서울특별시 강남구 삼성동", + buyer_postcode: "123-456", + m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", + }, + function (rsp) { + // callback 로직 + }, + ); + ``` -**`pg` \*****string** +
+

주요 파라미터 설명

-**PG사 구분코드** + **`pg` \*****string** -`nice_v2` 로 지정하면 됩니다. + **PG사 구분코드** -**`pay_method`** **\*** **string** + `nice_v2` 로 지정하면 됩니다. -**결제수단 구분코드** + **`pay_method`** **\*** **string** -- card (신용카드) -- trans (실시간 계좌이체) -- vbank (가상계좌) -- phone (휴대폰소액결제) -- cultureland (컬쳐랜드) -- naverpay_card (네이버페이 - 카드) -- naverpay_point (네이버페이 - 포인트) -- kakaopay (카카오페이) -- payco (페이코) -- samsungpay (삼성페이) -- skpay (11Pay (구.SKPay)) -- ssgpay (SSGPAY) -- ssgpay_bank (SSGPAY 은행계좌) -- lpay (LPAY) -- applepay (애플페이) + **결제수단 구분코드** -**`merchant_uid`** **\*** **string** + - card (신용카드) + - trans (실시간 계좌이체) + - vbank (가상계좌) + - phone (휴대폰소액결제) + - cultureland (컬쳐랜드) + - naverpay\_card (네이버페이 - 카드) + - naverpay\_point (네이버페이 - 포인트) + - kakaopay (카카오페이) + - payco (페이코) + - samsungpay (삼성페이) + - skpay (11Pay (구.SKPay)) + - ssgpay (SSGPAY) + - ssgpay\_bank (SSGPAY 은행계좌) + - lpay (LPAY) + - applepay (애플페이) -**주문번호** + **`merchant_uid`** **\*** **string** -매번 고유하게 채번되어야 합니다. + **주문번호** -**`amount`** **\*** **`integer`** + 매번 고유하게 채번되어야 합니다. -**결제금액** + **`amount`** **\*** **`integer`** -소수점 두번째 자리까지 허용합니다. + **결제금액** -**`buyer_tel`** **\*** **string** + 소수점 두번째 자리까지 허용합니다. -**구매자 전화번호** + **`buyer_tel`** **\*** **string** -**`vbank_due`** **\*** **string** + **구매자 전화번호** -**가상계좌 입금기한 (YYYY-MM-DD)** + **`vbank_due`** **\*** **string** -(신) 나이스페이먼츠의 경우 필수 입력이며 날짜는 무조건 23:59:59로 설정 됨 + **가상계좌 입금기한 (YYYY-MM-DD)** -**`escrow`** **\*** **boolean** + (신) 나이스페이먼츠의 경우 필수 입력이며 날짜는 무조건 23:59:59로 설정 됨 -**에스크로 결제 여부** + **`escrow`** **\*** **boolean** -**`period`** **\*** **array** + **에스크로 결제 여부** -**서비스 제공 기간** + **`period`** **\*** **array** -날짜만 입력이 가능하며(시간은 무시) 시작 날짜와 종료 날짜를 모두 입력해야 합니다. + **서비스 제공 기간** -**`from`** **`: YYYYMMDD`** + 날짜만 입력이 가능하며(시간은 무시) 시작 날짜와 종료 날짜를 모두 입력해야 합니다. -**`to`** **`: YYYYMMDD`** + **`from`** **`: YYYYMMDD`** -
+ **`to`** **`: YYYYMMDD`** +
-
-

- 결제 가능 결제수단 -

- -- card + 에스크로, 다이렉트 -- vbank + 에스크로 -- trans + 에스크로, 다이렉트(은행 지정 X) -- phone + 다이렉트(통신사 지정 X) -- cultureland -- naverpay_card -- naverpay_point -- kakaopay -- payco -- samsungpay -- skpay -- ssgpay -- ssgpay_bank -- lpay -- applepay - -
- - +
+

+ 결제 가능 결제수단 +

+ - card + 에스크로, 다이렉트 + - vbank + 에스크로 + - trans + 에스크로, 다이렉트(은행 지정 X) + - phone + 다이렉트(통신사 지정 X) + - cultureland + - naverpay\_card + - naverpay\_point + - kakaopay + - payco + - samsungpay + - skpay + - ssgpay + - ssgpay\_bank + - lpay + - applepay +
+
-

- 가능한 결제 환경 -

- -- PC (iframe) -- 모바일 (리디렉션) +

+ 가능한 결제 환경 +

+ - PC (iframe) + - 모바일 (리디렉션)
diff --git a/src/content/docs/ko/pg/payment-gateway/paymentwall.mdx b/src/content/docs/ko/pg/payment-gateway/paymentwall.mdx index 6a628c619..7f70ae613 100644 --- a/src/content/docs/ko/pg/payment-gateway/paymentwall.mdx +++ b/src/content/docs/ko/pg/payment-gateway/paymentwall.mdx @@ -4,229 +4,229 @@ description: 페이먼트월 결제창 연동가이드를 확인 합니다. --- import Figure from "~/components/Figure.astro"; -import Hint from "~/components/Hint.astro"; -import Tabs from "~/components/gitbook/tabs/Tabs.astro"; import Tab from "~/components/gitbook/tabs/Tab.astro"; +import Tabs from "~/components/gitbook/tabs/Tabs.astro"; +import Hint from "~/components/Hint.astro"; -### 1. 페이먼트월 채널 설정하기 +## 1. 페이먼트월 채널 설정하기 [결제대행사 채널 설정하기](../../ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다.
-### 2.결제 요청하기 +## 2.결제 요청하기 [JavaScript SDK](../../sdk/javascript-sdk-old/readme) `IMP.request_pay(param, callback)`을 호출하여 -페이먼트월 결제창을 호출할 수 있습니다. **결제결과**는 PC의 경우 IMP.request_pay(param, callback) +페이먼트월 결제창을 호출할 수 있습니다. **결제결과**는 PC의 경우 IMP.request\_pay(param, callback) 호출 후 **callback** 으로 수신되며 -모바일의 경우**m_redirect_url** 로 리디렉션됩니다. +모바일의 경우**m\_redirect\_url** 로 리디렉션됩니다. - -```javascript title="Javascript SDK" -IMP.request_pay({ - pg: "paymentwall.{project_key}", - pay_method: "card", // 페이먼트월은 국가IP에 따라 결제수단이 활성화 됩니다.(생략가능) - merchant_uid: "order_no_0001", //상점에서 생성한 고유 주문번호 - name: "주문명:결제테스트", - amount: 1004, - currency: "KRW", // 필수 파라미터 - buyer_email: "test@portone.io", //필수 파라미터 - buyer_name: "Jack Son", // 반드시 Firstname Lastname 이 빈칸으로 구분되어야 - buyer_tel: "010-1234-5678", - buyer_addr: "서울특별시 강남구 삼성동", - buyer_postcode: "123-456", - m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", - use_test_method : true, // 테스트 결제 수단을 활성화하는 파라미터, - bypass: { - // 터미날3 인경우 해당 파라미터 설정, 미 설정시 Defualt(일반) 결제창 활성화 - widget_code: "t3_1", - // 특정 결제수단만 활성화 하는 경우 사용 all 인 경우(default) 국가 지원 결제수단 모두 표 - ps: "all", - country_code: "DE" // 코드가 지정되면 지정된 국가에서 지원하는 결제수단이 활성화됩니다. - }, -}, function (rsp) { // callback 로직 - /* ...중략... */ -}); -``` + + ```javascript title="Javascript SDK" + IMP.request_pay( + { + pg: "paymentwall.{project_key}", + pay_method: "card", // 페이먼트월은 국가IP에 따라 결제수단이 활성화 됩니다.(생략가능) + merchant_uid: "order_no_0001", //상점에서 생성한 고유 주문번호 + name: "주문명:결제테스트", + amount: 1004, + currency: "KRW", // 필수 파라미터 + buyer_email: "test@portone.io", //필수 파라미터 + buyer_name: "Jack Son", // 반드시 Firstname Lastname 이 빈칸으로 구분되어야 + buyer_tel: "010-1234-5678", + buyer_addr: "서울특별시 강남구 삼성동", + buyer_postcode: "123-456", + m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", + use_test_method: true, // 테스트 결제 수단을 활성화하는 파라미터, + bypass: { + // 터미날3 인경우 해당 파라미터 설정, 미 설정시 Defualt(일반) 결제창 활성화 + widget_code: "t3_1", + // 특정 결제수단만 활성화 하는 경우 사용 all 인 경우(default) 국가 지원 결제수단 모두 표 + ps: "all", + country_code: "DE", // 코드가 지정되면 지정된 국가에서 지원하는 결제수단이 활성화됩니다. + }, + }, + function (rsp) { + // callback 로직 + /* ...중략... */ + }, + ); + ``` -### **주요 파라미터 설명** + ## **주요 파라미터 설명** -`pg` \* **string** + `pg` \* **string** -**PG사 구분코드** + **PG사 구분코드** -`paymentwall`로 지정하면 됩니다. 페이먼트월 채널을 여러개 사용하는 경우 `{pg}.{mid}` 형식으로 요청해야 합니다. (예시-`paymentwall.{projeckey}`) + `paymentwall`로 지정하면 됩니다. 페이먼트월 채널을 여러개 사용하는 경우 `{pg}.{mid}` 형식으로 요청해야 합니다. (예시-`paymentwall.{projeckey}`) -`pay_method` **string** + `pay_method` **string** -**결제수단 구분코드** + **결제수단 구분코드** -결제수단 제어는 [페이먼트월 홈페이지](https://api.paymentwall.com/) 안에서 Project를 활성화 하여 제어가 가능합니다. 따라서 `pay_method`의 값은 무시될 수 있습니다. + 결제수단 제어는 [페이먼트월 홈페이지](https://api.paymentwall.com/) 안에서 Project를 활성화 하여 제어가 가능합니다. 따라서 `pay_method`의 값은 무시될 수 있습니다. -(별도로 제어하지 않으시면 국가IP에 맞는 결제수단이 기본으로 노출됩니다) + (별도로 제어하지 않으시면 국가IP에 맞는 결제수단이 기본으로 노출됩니다) -`merchant_uid` **\*** **string** + `merchant_uid` **\*** **string** -**주문번호** + **주문번호** -매번 고유하게 채번되어야 합니다. + 매번 고유하게 채번되어야 합니다. -`amount` **\*** **integer** + `amount` **\*** **integer** -**결제금액** + **결제금액** -string 형식이 아닌 integer 형식으로 요청해야 합니다. + string 형식이 아닌 integer 형식으로 요청해야 합니다. -`name` **\*** **string** + `name` **\*** **string** -**주문명** + **주문명** -페이먼트월의 경우 필수로 입력해야 합니다. + 페이먼트월의 경우 필수로 입력해야 합니다. -`buyer_name` **\*** **string** + `buyer_name` **\*** **string** -**구매자 이름** + **구매자 이름** -결제시 사용되는 구매자 이름 입니다. 페이먼트월의 경우 필수로 입력해야 합니다. + 결제시 사용되는 구매자 이름 입니다. 페이먼트월의 경우 필수로 입력해야 합니다. -`buyer_email` **\*** **string** + `buyer_email` **\*** **string** -**구매자 email 주소** + **구매자 email 주소** -결제시 사용되는 구매자 이메일입니다. 페이먼트월의 경우 필수로 입력해야 합니다. + 결제시 사용되는 구매자 이메일입니다. 페이먼트월의 경우 필수로 입력해야 합니다. -`currency` **\*** **string** + `currency` **\*** **string** -**통화구분코드** + **통화구분코드** -입력하지 않는 경우 기본적으로 `KRW`로 요청하며, 해외 통화 결제 시 해당 통화 구분 코드를 입력한 후 요청해야 합니다. + 입력하지 않는 경우 기본적으로 `KRW`로 요청하며, 해외 통화 결제 시 해당 통화 구분 코드를 입력한 후 요청해야 합니다. -`use_test_method` **boolean** + `use_test_method` **boolean** -**테스트 결제수단 활성화 여부** + **테스트 결제수단 활성화 여부** -LIVE 프로젝트에서 테스트 결제수단을 활성화 하는 경우 사용합니다. + LIVE 프로젝트에서 테스트 결제수단을 활성화 하는 경우 사용합니다. -만약 LIVE 프로젝트가 아니라면(페이먼트월 심사 완료 전 단계), `use_test_method` 파라미터 설정과 동시에 bypass의 `ps` 파라미터를 `test`로 설정해야 테스트 결제수단 사용이 가능합니다. + 만약 LIVE 프로젝트가 아니라면(페이먼트월 심사 완료 전 단계), `use_test_method` 파라미터 설정과 동시에 bypass의 `ps` 파라미터를 `test`로 설정해야 테스트 결제수단 사용이 가능합니다. -```javascript title="Javascript SDK" -IMP.request_pay({ - use_test_method: true, - bypass: { - ps: "test", // LIVE 프로젝트가 아닌 경우, ps도 test로 설정해야만 테스트 결제수단이 활성화됩니다. - }, -}); -``` + ```javascript title="Javascript SDK" + IMP.request_pay({ + use_test_method: true, + bypass: { + ps: "test", // LIVE 프로젝트가 아닌 경우, ps도 test로 설정해야만 테스트 결제수단이 활성화됩니다. + }, + }); + ``` -`bypass` **object** + `bypass` **object** -**페이먼트월 전용 파라미터** + **페이먼트월 전용 파라미터** -- `widget_code`: 터미날3 인 경우 `t3_1`로 파라미터를 설정해야 합니다. 미설정시 Default(일반) 결제창이 활성화됩니다. -- `ps`: 특정 결제수단만 활성화 하는 경우 사용됩니다. 페이먼트월 가이드를 참고하여 해당하는 코드를 입력해야 합니다. [ → 페이먼트월 가이드 바로가기](https://docs.paymentwall.com/reference/payment-system-shortcodes) ex) `kakaopaykr` = 카카오페이 -- `country_code` : 지정된 국가에서 지원되는 결제수단이 위젯상에 노출됩니다. 다음 문서를 참고하여 해당하는 국가코드를 입력해야 합니다. [ → 국가코드 바로가기](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) + - `widget_code`: 터미날3 인 경우 `t3_1`로 파라미터를 설정해야 합니다. 미설정시 Default(일반) 결제창이 활성화됩니다. + - `ps`: 특정 결제수단만 활성화 하는 경우 사용됩니다. 페이먼트월 가이드를 참고하여 해당하는 코드를 입력해야 합니다. [→ 페이먼트월 가이드 바로가기](https://docs.paymentwall.com/reference/payment-system-shortcodes) ex) `kakaopaykr` = 카카오페이 + - `country_code` : 지정된 국가에서 지원되는 결제수단이 위젯상에 노출됩니다. 다음 문서를 참고하여 해당하는 국가코드를 입력해야 합니다. [→ 국가코드 바로가기](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) + - + + 인증결제창 호출 파라미터에서 `customer_uid` 값을 추가하면 비 인증 결제창을 호출할 수 있습니다. + 비 인증 결제창에서 빌링키를 발급받은 후 해당 빌링키로 결제를 요청합니다. - -인증결제창 호출 파라미터에서 `customer_uid` 값을 추가하면 비 인증 결제창을 호출할 수 있습니다. -비 인증 결제창에서 빌링키를 발급받은 후 해당 빌링키로 결제를 요청합니다. + ```javascript title="Javascript SDK" + IMP.request_pay( + { + pg: "paymentwall.{project_key}", + pay_method: "card", // 빌링키 결제는 오직 신용카드만 가능합니다. + merchant_uid: "order_monthly_0001", // 상점에서 관리하는 주문 번호 + name: "최초인증결제", + amount: 20, // 빌링키 발급과 함께 최초 승인이 같이 이루어집니다. + currency: "USD", // 필수 파라미터 + customer_uid: "your-customer-unique-id", // 필수 입력 + buyer_email: "test@portone.io", // 빌링키 발급시 기재한 주소와 빌링키 결제할때 기재한 주소가 동일해야 합니다. + buyer_name: "Jack Son", // 반드시 Firstname Lastname 이 빈칸으로 구분되어야 합니다. + buyer_tel: "02-1234-1234", + m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", + }, + function (rsp) { + if (rsp.success) { + alert("빌링키 발급 성공"); + } else { + alert("빌링키 발급 실패"); + } + }, + ); + ``` -```javascript title="Javascript SDK" -IMP.request_pay( - { - pg: "paymentwall.{project_key}", - pay_method: "card", // 빌링키 결제는 오직 신용카드만 가능합니다. - merchant_uid: "order_monthly_0001", // 상점에서 관리하는 주문 번호 - name: "최초인증결제", - amount: 20, // 빌링키 발급과 함께 최초 승인이 같이 이루어집니다. - currency: "USD", // 필수 파라미터 - customer_uid: "your-customer-unique-id", // 필수 입력 - buyer_email: "test@portone.io", // 빌링키 발급시 기재한 주소와 빌링키 결제할때 기재한 주소가 동일해야 합니다. - buyer_name: "Jack Son", // 반드시 Firstname Lastname 이 빈칸으로 구분되어야 합니다. - buyer_tel: "02-1234-1234", - m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", - }, - function (rsp) { - if (rsp.success) { - alert("빌링키 발급 성공"); - } else { - alert("빌링키 발급 실패"); - } - } -); -``` + **주요 파라미터 설명** -**주요 파라미터 설명** + `pg` \* **string** -`pg` \* **string** + **PG사 구분코드** -**PG사 구분코드** + `paymentwall`로 지정하면 됩니다. 페이먼트월 채널을 여러개 사용하는 경우 `{pg}.{mid}` 형식으로 요청해야 합니다. (예시-`paymentwall.{projeckey}`) -`paymentwall`로 지정하면 됩니다. 페이먼트월 채널을 여러개 사용하는 경우 `{pg}.{mid}` 형식으로 요청해야 합니다. (예시-`paymentwall.{projeckey}`) + `customer_uid` \* **string** -`customer_uid` \* **string** + **빌링키** -**빌링키** + 비 인증 결제창에서 고객이 입력한 카드정보와 1:1로 매칭될 빌링키를 지정합니다. + 빌링키 발급이 성공하면 실 빌링키는 `customer_uid`와 1:1 매칭되어 **포트원 서버에 저장**됩니다. + `customer_uid`를 고객사 내부서버에 저장한 후 [**비 인증 결제요청 REST API**](../../api/api-4/api)를 호출하여 결제 요청을 해야합니다. -비 인증 결제창에서 고객이 입력한 카드정보와 1:1로 매칭될 빌링키를 지정합니다. -빌링키 발급이 성공하면 실 빌링키는 `customer_uid`와 1:1 매칭되어 **포트원 서버에 저장**됩니다. -`customer_uid`를 고객사 내부서버에 저장한 후 [**비 인증 결제요청 REST API**](../../api/api-4/api)를 호출하여 결제 요청을 해야합니다. + ```sh title="server-side" + curl -H "Content-Type: application/json" \ + -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "amount":3000}' \ + https://api.iamport.kr/subscribe/payments/again + ``` -```sh title="server-side" -curl -H "Content-Type: application/json" \ - -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "amount":3000}' \ - https://api.iamport.kr/subscribe/payments/again -``` + `amount` **\*** **integer** -`amount` **\*** **integer** + **결제금액** -**결제금액** + string 형식이 아닌 integer 형식으로 요청해야 합니다. + 설정된 금액으로 **최초 승인이 발생**됩니다. -string 형식이 아닌 integer 형식으로 요청해야 합니다. -설정된 금액으로 **최초 승인이 발생**됩니다. + `name` **\*** **string** -`name` **\*** **string** + **주문명** -**주문명** + 페이먼트월의 경우 필수로 입력해야 합니다. -페이먼트월의 경우 필수로 입력해야 합니다. + `buyer_name` **\*** **string** -`buyer_name` **\*** **string** + **구매자 이름** -**구매자 이름** + 결제시 사용되는 구매자 이름 입니다. 페이먼트월의 경우 필수로 입력해야 합니다. -결제시 사용되는 구매자 이름 입니다. 페이먼트월의 경우 필수로 입력해야 합니다. + `buyer_email` **\*** **string** -`buyer_email` **\*** **string** + **구매자 email 주소** -**구매자 email 주소** + 결제시 사용되는 구매자 이메일입니다. 페이먼트월의 경우 필수로 입력해야 합니다. -결제시 사용되는 구매자 이메일입니다. 페이먼트월의 경우 필수로 입력해야 합니다. + `currency` **\*** **string** -`currency` **\*** **string** + **통화구분코드** -**통화구분코드** - -입력하지 않는 경우 기본적으로 `KRW`로 요청하며, 해외 통화 결제 시 해당 통화 구분 코드를 입력한 후 요청해야 합니다. - - + 입력하지 않는 경우 기본적으로 `KRW`로 요청하며, 해외 통화 결제 시 해당 통화 구분 코드를 입력한 후 요청해야 합니다. + -**배송정보 등록 API** + **배송정보 등록 API** -페이먼트월을 통한 이커머스(실물상품) 결제인 경우 아래 배송정보등록 API를 반드시 연동해야 합니다. 해당 API를 연동하지 않을 경우 정산 시 문제가 발생할 수 있습니다. - -[ → 페이먼트월 배송등록 API 바로가기](https://developers.portone.io/api/rest-v1/pg.paymentwall) + 페이먼트월을 통한 이커머스(실물상품) 결제인 경우 아래 배송정보등록 API를 반드시 연동해야 합니다. 해당 API를 연동하지 않을 경우 정산 시 문제가 발생할 수 있습니다. + [→ 페이먼트월 배송등록 API 바로가기](https://developers.portone.io/api/rest-v1/pg.paymentwall) -페이먼트월의 경우 빌링키 발급 시 빌링키 발급과 동시에 결제가 이루어지는 방식으로만 제공하고 있습니다. -페이먼트월 정책에 따라 최초 결제 승인 없이 **빌링키만 발급하는 방식은 지원되지 않습니다.** - -또한, 빌링키만 발급하기 위해 임의의 결제를 발생시켜 승인 후 즉시 취소하는 경우 카드사 정책에 따라 이용이 중지될 수 있습니다. + 페이먼트월의 경우 빌링키 발급 시 빌링키 발급과 동시에 결제가 이루어지는 방식으로만 제공하고 있습니다. + 페이먼트월 정책에 따라 최초 결제 승인 없이 **빌링키만 발급하는 방식은 지원되지 않습니다.** + 또한, 빌링키만 발급하기 위해 임의의 결제를 발생시켜 승인 후 즉시 취소하는 경우 카드사 정책에 따라 이용이 중지될 수 있습니다. diff --git a/src/content/docs/ko/pg/payment-gateway/paypal.mdx b/src/content/docs/ko/pg/payment-gateway/paypal.mdx index a75469c8f..01910a29a 100644 --- a/src/content/docs/ko/pg/payment-gateway/paypal.mdx +++ b/src/content/docs/ko/pg/payment-gateway/paypal.mdx @@ -5,9 +5,9 @@ description: 페이팔(Express Checkout) 결제연동 방법을 안내합니다. import Figure from "~/components/Figure.astro"; import File from "~/components/gitbook/File.astro"; -import Hint from "~/components/Hint.astro"; -import Tabs from "~/components/gitbook/tabs/Tabs.astro"; import Tab from "~/components/gitbook/tabs/Tab.astro"; +import Tabs from "~/components/gitbook/tabs/Tabs.astro"; +import Hint from "~/components/Hint.astro"; 페이팔 Express checkout 방식으로 신규 가입 및 연동이 불가합니다. @@ -15,13 +15,13 @@ import Tab from "~/components/gitbook/tabs/Tab.astro"; -### 1. 페이팔 채널 설정하기 +## 1. 페이팔 채널 설정하기 [결제대행사 채널 설정하기](../../ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다.
-### 2.결제 요청하기 +## 2.결제 요청하기 [JavaScript SDK](../../sdk/javascript-sdk-old/readme) `IMP.request_pay(param, callback)`을 호출하여 페이팔 결제창을 호출할 수 있습니다. **결제결과**는 **PC / 모바일** 모두 @@ -30,22 +30,26 @@ import Tab from "~/components/gitbook/tabs/Tab.astro"; ```javascript title="Javascript SDK" -IMP.request_pay({ - pg: "paypal.{API 사용자 이름}", - pay_method: "card", - merchant_uid: "order_no_0001", // 상점에서 관리하는 주문 번호 - name: "주문명:결제테스트", - amount: 14.20, - currency: "USD", // 기본값: USD(원화 KRW는 페이팔 정책으로 인해 지원하지 않음) - buyer_email: "test@portone.io", - buyer_name: "구매자이름", - buyer_tel: "010-1234-5678", - buyer_addr: "서울특별시 강남구 삼성동", - buyer_postcode: "123-456", - m_redirect_url: "{결제 완료 후 리디렉션 될 URL}" -}, function(rsp) { // callback 로직 - /* ...중략... */ -}); +IMP.request_pay( + { + pg: "paypal.{API 사용자 이름}", + pay_method: "card", + merchant_uid: "order_no_0001", // 상점에서 관리하는 주문 번호 + name: "주문명:결제테스트", + amount: 14.2, + currency: "USD", // 기본값: USD(원화 KRW는 페이팔 정책으로 인해 지원하지 않음) + buyer_email: "test@portone.io", + buyer_name: "구매자이름", + buyer_tel: "010-1234-5678", + buyer_addr: "서울특별시 강남구 삼성동", + buyer_postcode: "123-456", + m_redirect_url: "{결제 완료 후 리디렉션 될 URL}", + }, + function (rsp) { + // callback 로직 + /* ...중략... */ + }, +); ``` **주요 파라미터 설명** @@ -89,7 +93,7 @@ PC환경 모바일 환경 모두 해당 값을 필수로 설정해야 결과를 -### 추가 기능 +## 추가 기능 Paypal에서는 고위험업종(게임, 디지털 콘텐츠) 고객사의 경우 판매자 보호 및 더 높은 수준의 위험관리를 위해 STC API(SetTransactionContext API)를 제공합니다. diff --git a/src/content/docs/ko/pg/payment-gateway/settle/mybank.mdx b/src/content/docs/ko/pg/payment-gateway/settle/mybank.mdx index 44162dca3..131118960 100644 --- a/src/content/docs/ko/pg/payment-gateway/settle/mybank.mdx +++ b/src/content/docs/ko/pg/payment-gateway/settle/mybank.mdx @@ -4,179 +4,180 @@ description: 핵토파이낸셜에서 제공하는 오픈뱅킹 기반 계좌간 --- import Figure from "~/components/Figure.astro"; -import Hint from "~/components/Hint.astro"; -import Tabs from "~/components/gitbook/tabs/Tabs.astro"; import Tab from "~/components/gitbook/tabs/Tab.astro"; +import Tabs from "~/components/gitbook/tabs/Tabs.astro"; +import Hint from "~/components/Hint.astro"; -### 1. 내통장결제 채널 설정하기 +## 1. 내통장결제 채널 설정하기 [결제대행사 채널 설정하기](../../ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다.
-### 2.결제 요청하기 +## 2.결제 요청하기 [JavaScript SDK](../../../sdk/javascript-sdk-old/readme) `IMP.request_pay(param, callback)`을 -호출하여 내통장 결제 결제창을 호출할 수 있습니다. **결제결과**는 PC의 경우 IMP.request_pay(param, +호출하여 내통장 결제 결제창을 호출할 수 있습니다. **결제결과**는 PC의 경우 IMP.request\_pay(param, callback) 호출 후 **callback** 으로 수신되 -모바일의 경우 **m_redirect_url** 로 리디렉션됩니다. +모바일의 경우 **m\_redirect\_url** 로 리디렉션됩니다. - -```javascript title="Javascript SDK" -IMP.request_pay({ // param - pg: "settle_acc.MID", // 발급받은 고객사아이디 - pay_method: "trans", - merchant_uid: "ORD20180131-0000011", - name: "노르웨이 회전 의자", - buyer_email: "gildong@gmail.com", - buyer_name: "홍길동", - buyer_tel: "010-1234-5678", - buyer_addr: "서울특별시 강남구 삼성동", - m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", - amount: 1000, - bypass: { - settle: { - addDeductionYn: "N", // 추가공제구분 (대중교통:Y, 도서,공연비:C, 추가공제없음:N) - criPsblYn: "N", // 현금영수증 발행가능 여부 ( Y or N or ""빈문자열은 Y로인식) - custCi: "<회원 연계정보(Connecting Information)>" // 고객사가 보유한 회원 CI를 설정하면 내통장 결제에 등록한 CI와 비교하여 동일인인지 자동검증되며 일치하지 않은 경우 결제가 중단됩니다. - } - } -}, function (rsp) { // callback - // 생략 -}); -``` - -#### 주요 파라미터 설명 - -**`pg` \*****string** + + ```javascript title="Javascript SDK" + IMP.request_pay( + { + // param + pg: "settle_acc.MID", // 발급받은 고객사아이디 + pay_method: "trans", + merchant_uid: "ORD20180131-0000011", + name: "노르웨이 회전 의자", + buyer_email: "gildong@gmail.com", + buyer_name: "홍길동", + buyer_tel: "010-1234-5678", + buyer_addr: "서울특별시 강남구 삼성동", + m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", + amount: 1000, + bypass: { + settle: { + addDeductionYn: "N", // 추가공제구분 (대중교통:Y, 도서,공연비:C, 추가공제없음:N) + criPsblYn: "N", // 현금영수증 발행가능 여부 ( Y or N or ""빈문자열은 Y로인식) + custCi: "<회원 연계정보(Connecting Information)>", // 고객사가 보유한 회원 CI를 설정하면 내통장 결제에 등록한 CI와 비교하여 동일인인지 자동검증되며 일치하지 않은 경우 결제가 중단됩니다. + }, + }, + }, + function (rsp) { + // callback + // 생략 + }, + ); + ``` -**PG사 구분코드** + ### 주요 파라미터 설명 -**``** **`settle_acc`****`.MID 형태`** 로 지정하셔야 합니다. + **`pg` \*****string** -**`pay_method`** **\*** **string** + **PG사 구분코드** -**결제수단 구분코드** + **\`\`** **`settle_acc`****`.MID 형태`** 로 지정하셔야 합니다. -**`trans`** + **`pay_method`** **\*** **string** -**`merchant_uid`** **\*** **string** + **결제수단 구분코드** -**`고객사 주문번호`** + **`trans`** -매번 고유하게 채번되어야 합니다. + **`merchant_uid`** **\*** **string** -**`buyer_tel`** **\*** **`string`** + **`고객사 주문번호`** -**구매자 연락처** + 매번 고유하게 채번되어야 합니다. -필수 파라미터 입니다. + **`buyer_tel`** **\*** **`string`** -**`amount`** **\*** **`integer`** + **구매자 연락처** -**결제금액** + 필수 파라미터 입니다. -**string** 이 아닌점에 유의하세요 + **`amount`** **\*** **`integer`** -**`bypass`** + **결제금액** -**optional** 로 계약이 된 경우 사용 가능합니다. + **string** 이 아닌점에 유의하세요 -``` -addDeductionYn: 추가공제구분 (대중교통:Y, 도서,공연비:C, 추가공제없음:N) -criPsblYn: "N", // 현금영수증 발행가능 여부 ( Y or N or ""빈문자열은 Y로인식) -``` + **`bypass`** - -1. **내통장결제는 팝업 형태로 제공됩니다.** -2. **매출전표가** 제공되지 않습니다. -3. 선불충전금 ( ex: 카카오페이, 네이버페이 충전금)으로만 결제하는 경우 계좌정보(은행코드)가 제공되지 않습니다 + **optional** 로 계약이 된 경우 사용 가능합니다. - + ```json + addDeductionYn: "Y" //추가공제구분 (대중교통:Y, 도서,공연비:C, 추가공제없음:N) + criPsblYn: "N", // 현금영수증 발행가능 여부 ( Y or N or ""빈문자열은 Y로인식) + ``` - + + 1. **내통장결제는 팝업 형태로 제공됩니다.** + 2. **매출전표가** 제공되지 않습니다. + 3. 선불충전금 ( ex: 카카오페이, 네이버페이 충전금)으로만 결제하는 경우 계좌정보(은행코드)가 제공되지 않습니다 + + - -인증결제창 호출 파라미터에서 **customer\_uid** 값을 추가하면 비 인증 결제창을 호출할 수 있습니다. 비인증 결제창에서 빌링키를 발급받은 후 해당 빌링키로 결제를 요청합니다. + + 인증결제창 호출 파라미터에서 **customer\_uid** 값을 추가하면 비 인증 결제창을 호출할 수 있습니다. 비인증 결제창에서 빌링키를 발급받은 후 해당 빌링키로 결제를 요청합니다. -```javascript title="Javascript SDK" -IMP.request_pay( - { - pg: "settle_acc.MID", //발급받은 고객사아이디 - pay_method: "trans", - merchant_uid: "ORD20180131-0000011", - name: "노르웨이 회전 의자", - buyer_email: "gildong@gmail.com", - buyer_name: "홍길동", - buyer_tel: "010-1234-5678", - buyer_addr: "서울특별시 강남구 삼성동", - m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", - customer_uid: "A00001-001", // 빌링키와 맵핑되는 - amount: 1000, - bypass: { - settle: { - addDeductionYn: "N", // 추가공제구분 (대중교통:Y, 도서,공연비:C, 추가공제없음:N) - criPsblYn: "N", // 현금영수증 발행가능 여부 ( Y or N or ""빈문자열은 Y로인식) + ```javascript title="Javascript SDK" + IMP.request_pay( + { + pg: "settle_acc.MID", //발급받은 고객사아이디 + pay_method: "trans", + merchant_uid: "ORD20180131-0000011", + name: "노르웨이 회전 의자", + buyer_email: "gildong@gmail.com", + buyer_name: "홍길동", + buyer_tel: "010-1234-5678", + buyer_addr: "서울특별시 강남구 삼성동", + m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", + customer_uid: "A00001-001", // 빌링키와 맵핑되는 + amount: 1000, + bypass: { + settle: { + addDeductionYn: "N", // 추가공제구분 (대중교통:Y, 도서,공연비:C, 추가공제없음:N) + criPsblYn: "N", // 현금영수증 발행가능 여부 ( Y or N or ""빈문자열은 Y로인식) + }, + }, }, - }, - }, - function (rsp) { - if (rsp.success) { - alert("빌링키 발급 성공"); - } else { - alert("빌링키 발급 실패"); - } - } -); -``` - - -- 비인증 결제를 위해서는 **정기결제 계약이 필수입니다.** -- amount 값을 0으로 설정시 빌링키만 발급이 가능합니다. - - + function (rsp) { + if (rsp.success) { + alert("빌링키 발급 성공"); + } else { + alert("빌링키 발급 실패"); + } + }, + ); + ``` -#### 주요 파라미터 설명 + + - 비인증 결제를 위해서는 **정기결제 계약이 필수입니다.** + - amount 값을 0으로 설정시 빌링키만 발급이 가능합니다. + -**`pg` \*****string** + ### 주요 파라미터 설명 -**PG사 구분코드** + **`pg` \*****string** -**`settle_acc`****`.MID 형태`** 로 지정\\ + **PG사 구분코드** -**`customer_uid` \*****string** + **`settle_acc`****`.MID 형태`** 로 지정\\ -**빌링키** + **`customer_uid` \*****string** -등록 계좌정보와 1:1로 매칭될 빌링키를 지정합니다. + **빌링키** -**`amount` \*****Integer** + 등록 계좌정보와 1:1로 매칭될 빌링키를 지정합니다. -**결제금액** + **`amount` \*****Integer** -0원으로 입력시 빌링키만 발급되 실금액 설정시 결제와 동시에 빌링키가 발급됩니다.\\ + **결제금액** -#### 빌링키(customer_uid)로 결제 요청하기 + 0원으로 입력시 빌링키만 발급되 실금액 설정시 결제와 동시에 빌링키가 발급됩니다.\\ -빌링키 발급이 성공하면 실 빌링키는 customer_uid 와 1:1 매칭되어 **포트원 서버에 저장**됩니다. customer_uid를 고객사 내부서버에 저장하시고 [**비 인증 결제요청 REST API**](../../../api/api-4/api)를 호출하시면 결제를 발생시킬 수 있습니다. + ### 빌링키(customer\_uid)로 결제 요청하기 -```sh title="server-side" -curl -H "Content-Type: application/json" \ - -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "amount":3000}' \ - https://api.iamport.kr/subscribe/payments/again -``` + 빌링키 발급이 성공하면 실 빌링키는 customer\_uid 와 1:1 매칭되어 **포트원 서버에 저장**됩니다. customer\_uid를 고객사 내부서버에 저장하시고 [**비 인증 결제요청 REST API**](../../../api/api-4/api)를 호출하시면 결제를 발생시킬 수 있습니다. -**추가 파라미터 안내** + ```sh title="server-side" + curl -H "Content-Type: application/json" \ + -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "amount":3000}' \ + https://api.iamport.kr/subscribe/payments/again + ``` -```json -{ - "extra": { - "addDeductionYn": "N", // 추가공제구분 (대중교통:Y, 도서,공연비:C, 추가공제없음:N) - "criPsblYn": "N" // 현금영수증 발행가능 여부 ( Y or N or ""빈문자열은 Y로인식) - } -} -``` + **추가 파라미터 안내** - + ```json + { + "extra": { + "addDeductionYn": "N", // 추가공제구분 (대중교통:Y, 도서,공연비:C, 추가공제없음:N) + "criPsblYn": "N" // 현금영수증 발행가능 여부 ( Y or N or ""빈문자열은 Y로인식) + } + } + ``` + diff --git a/src/content/docs/ko/pg/payment-gateway/settle/readme.mdx b/src/content/docs/ko/pg/payment-gateway/settle/readme.mdx index ec56e0aa3..e96232f40 100644 --- a/src/content/docs/ko/pg/payment-gateway/settle/readme.mdx +++ b/src/content/docs/ko/pg/payment-gateway/settle/readme.mdx @@ -3,20 +3,20 @@ title: 핵토파이낸셜 description: 핵토파이낸셜 결제 연동 방법을 안내합니다. --- +import Figure from "~/components/Figure.astro"; import Codepen from "~/components/gitbook/Codepen.astro"; import ContentRef from "~/components/gitbook/ContentRef.astro"; -import Figure from "~/components/Figure.astro"; -import Hint from "~/components/Hint.astro"; -import Tabs from "~/components/gitbook/tabs/Tabs.astro"; import Tab from "~/components/gitbook/tabs/Tab.astro"; +import Tabs from "~/components/gitbook/tabs/Tabs.astro"; +import Hint from "~/components/Hint.astro"; -### 1. 핵토파이낸셜 채널 설정하기 +## 1. 핵토파이낸셜 채널 설정하기 [결제대행사 채널 설정하기](../../ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다.
-### 2.결제 요청하기 +## 2.결제 요청하기 [JavaScript SDK](../../../sdk/javascript-sdk-old/readme) `IMP.request_pay(param, callback)`을 호출하여 핵토파이낸셜 결제창을 호출할 수 있습니다. **결제결과**는 PC의 경우 `IMP.request_pay(param, @@ -24,129 +24,129 @@ callback)` 호출 후 **`callback`**으로 수 모바일의 경우 **`m_redirect_url`**로 리디렉션됩니다. - -```javascript title="Javascript SDK" -IMP.request_pay({ - pg: "settle.{상점 ID}", - pay_method: "card", - merchant_uid: "order_no_0001", // 상점에서 생성한 고유 주문번호 - name: "주문명:결제테스트", - amount: 1004, - buyer_email: "test@portone.io", - buyer_name: "구매자이름", - buyer_tel: "010-1234-5678", // 누락시 오류 발생 - buyer_addr: "서울특별시 강남구 삼성동", - company: "포트원", // 가상계좌 발급시 권고사항 - buyer_postcode: "123-456" - m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", -}, function (rsp) { // callback 로직 - /* ...중략... */ -}); -``` - -**주요 파라미터 설명** - -**`pg` \*****string** - -**PG사 구분코드** - -**`settle`** 로 지정하면 됩니다. + + ```javascript title="Javascript SDK" + IMP.request_pay( + { + pg: "settle.{상점 ID}", + pay_method: "card", + merchant_uid: "order_no_0001", // 상점에서 생성한 고유 주문번호 + name: "주문명:결제테스트", + amount: 1004, + buyer_email: "test@portone.io", + buyer_name: "구매자이름", + buyer_tel: "010-1234-5678", // 누락시 오류 발생 + buyer_addr: "서울특별시 강남구 삼성동", + company: "포트원", // 가상계좌 발급시 권고사항 + buyer_postcode: "123-456", + m_redirect_url: "http://", // 모바일에서 결제 완료 후 리디렉션 될 URL + }, + function (rsp) { + // callback 로직 + /* ...중략... */ + }, + ); + ``` -**`pay_method`** **\*** **string** + **주요 파라미터 설명** -**결제수단 구분코드** + **`pg` \*****string** -- card (신용카드) -- trans (실시간 계좌이체) -- vbank(가상계좌) -- phone (휴대폰소액결제) + **PG사 구분코드** -**`merchant_uid`** **\*** **string** + **`settle`** 로 지정하면 됩니다. -**`고객사 주문번호`** + **`pay_method`** **\*** **string** -매번 고유하게 채번되어야 합니다. + **결제수단 구분코드** -**`buyer_tel`** **\*** **`string`** + - card (신용카드) + - trans (실시간 계좌이체) + - vbank(가상계좌) + - phone (휴대폰소액결제) -**구매자 연락처** + **`merchant_uid`** **\*** **string** -필수 파라미터 입니다. + **`고객사 주문번호`** -**`amount`** **\*** **`integer`** + 매번 고유하게 채번되어야 합니다. -**결제금액** + **`buyer_tel`** **\*** **`string`** -**string** 이 아닌점에 유의하세요 + **구매자 연락처** -**`company`** **`string`** + 필수 파라미터 입니다. -**`회사명`** + **`amount`** **\*** **`integer`** -**가상계좌** 결제 요청인 경우 필수 파라미터 + **결제금액** - + **string** 이 아닌점에 유의하세요 - + **`company`** **`string`** - -**세틀뱅크는 비 인증 결제창을 지원하지 않습니다.** + **`회사명`** - + **가상계좌** 결제 요청인 경우 필수 파라미터 - -**API 방식으로 결제요청,예약결제를 구현할수 있습니다.** + + -**일회성 결제 요청하기** + + **세틀뱅크는 비 인증 결제창을 지원하지 않습니다.** + -REST[ **API POST /subscribe/payments/onetime**](../../../api/api-4/api-1)을 호출하여 일회성 결제를 요청합니다. 요청 시 전달된 카드는 포트원에 등록되지 않습니다. + + **API 방식으로 결제요청,예약결제를 구현할수 있습니다.** -```sh -curl -H "Content-Type: application/json" \ - -X POST -d '{"merchant_uid":"order_id_8237352", "card_number":"1234-1234-1234-1234", "expiry":"2019-01", "birth":"123456", "amount":3000}' \ - https://api.iamport.kr/subscribe/payments/onetime -``` + **일회성 결제 요청하기** -**빌링키 발급 요청하기** + REST[**API POST /subscribe/payments/onetime**](../../../api/api-4/api-1)을 호출하여 일회성 결제를 요청합니다. 요청 시 전달된 카드는 포트원에 등록되지 않습니다. -REST [**API POST /subscribe/customers/\{customer_uid}**](../../../api/api-2/api-1)를 호출하여 빌링키 발급을 요청합니다. + ```sh + curl -H "Content-Type: application/json" \ + -X POST -d '{"merchant_uid":"order_id_8237352", "card_number":"1234-1234-1234-1234", "expiry":"2019-01", "birth":"123456", "amount":3000}' \ + https://api.iamport.kr/subscribe/payments/onetime + ``` -```sh -curl -H "Content-Type: application/json" \ - -X POST -d '{"card_number":"1234-1234-1234-1234", "expiry":"2025-12", "birth":"820213", "pwd_2digit":"00"}' \ - https://api.iamport.kr/subscribe/customers/your-customer-unique-id -``` + **빌링키 발급 요청하기** - -**세틀뱅크** [**빌링키 단독 발급 API**](../../../api/api-2/api-1)**는 별도 계약 후 사용가능합니다..** + REST [**API POST /subscribe/customers/\{customer\_uid}**](../../../api/api-2/api-1)를 호출하여 빌링키 발급을 요청합니다. - + ```sh + curl -H "Content-Type: application/json" \ + -X POST -d '{"card_number":"1234-1234-1234-1234", "expiry":"2025-12", "birth":"820213", "pwd_2digit":"00"}' \ + https://api.iamport.kr/subscribe/customers/your-customer-unique-id + ``` -**빌링키 발급 및 최초 결제 요청하기** + + **세틀뱅크** [**빌링키 단독 발급 API**](../../../api/api-2/api-1)**는 별도 계약 후 사용가능합니다..** + -REST [**API POST /subscribe/payments/onetime**](../../../api/api-4/api-1)을 호출하여 빌링키 발급과 최초 결제를 요청합니다. + **빌링키 발급 및 최초 결제 요청하기** -- **`customer_uid`** : 빌링키 등록을 위해서 지정해야 합니다. + REST [**API POST /subscribe/payments/onetime**](../../../api/api-4/api-1)을 호출하여 빌링키 발급과 최초 결제를 요청합니다. -```sh -curl -H "Content-Type: application/json" \ - -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "card_number":"1234-1234-1234-1234", "expiry":"2019-01", "birth":"123456", "amount":3000}' \ - https://api.iamport.kr/subscribe/payments/onetime -``` + - **`customer_uid`** : 빌링키 등록을 위해서 지정해야 합니다. -**빌링키로 결제 요청하기** + ```sh + curl -H "Content-Type: application/json" \ + -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "card_number":"1234-1234-1234-1234", "expiry":"2019-01", "birth":"123456", "amount":3000}' \ + https://api.iamport.kr/subscribe/payments/onetime + ``` -빌링키 발급과 최초 결제가 성공하면 빌링키는 전달된 `customer_uid` 와 1:1 매칭되어 포트원에 저장됩니다. 보안상의 이유로 서버는 빌링키에 직접 접근할 수 없기 때문에 `customer_uid`를 이용해서 재결제([**POST /subscribe/payments/again**](../../../api/api-4/api)) REST API를 다음과 같이 호출합니다. + **빌링키로 결제 요청하기** -```sh -curl -H "Content-Type: application/json" \ - -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "amount":3000}' \ - https://api.iamport.kr/subscribe/payments/again -``` + 빌링키 발급과 최초 결제가 성공하면 빌링키는 전달된 `customer_uid` 와 1:1 매칭되어 포트원에 저장됩니다. 보안상의 이유로 서버는 빌링키에 직접 접근할 수 없기 때문에 `customer_uid`를 이용해서 재결제([**POST /subscribe/payments/again**](../../../api/api-4/api)) REST API를 다음과 같이 호출합니다. -**자세한 비 인증 결제 가이드는 아래 링크를 참조하세요** + ```sh + curl -H "Content-Type: application/json" \ + -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "amount":3000}' \ + https://api.iamport.kr/subscribe/payments/again + ``` - + **자세한 비 인증 결제 가이드는 아래 링크를 참조하세요** - + + diff --git a/src/content/docs/ko/pg/payment-gateway/smartro-v2/readme.mdx b/src/content/docs/ko/pg/payment-gateway/smartro-v2/readme.mdx index fb244e9a6..ceda489c8 100644 --- a/src/content/docs/ko/pg/payment-gateway/smartro-v2/readme.mdx +++ b/src/content/docs/ko/pg/payment-gateway/smartro-v2/readme.mdx @@ -3,228 +3,228 @@ title: 스마트로(신모듈) description: 스마트로 연동 방법을 안내합니다. --- -import * as prose from "~/components/prose"; import Details from "~/components/gitbook/Details.astro"; import Hint from "~/components/Hint.astro"; +import * as prose from "~/components/prose"; export const components = prose; import Figure from "~/components/Figure.astro"; -import Tabs from "~/components/gitbook/tabs/Tabs.astro"; import Tab from "~/components/gitbook/tabs/Tab.astro"; +import Tabs from "~/components/gitbook/tabs/Tabs.astro"; -### 1. 스마트로 채널 설정하기 +## 1. 스마트로 채널 설정하기 [결제대행사 채널 설정하기](../../ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다.
-### 2. 최신 JavaScript SDK로 업데이트하기 +## 2. 최신 JavaScript SDK로 업데이트하기 스마트로(신모듈) 결제는 최신 SDK에서만 지원되는 기능입니다. -```javascript title="JS SDK" +```html title="JS SDK" ``` **스마트로 신모듈을 연동하기 위해서는 위에 안내된 JS SDK를 이용하셔야 합니다** - [JavaScript SDK](../../../sdk/javascript-sdk/readme)문서를 통해 최신 SDK를 설치해주세요. -### 3.결제 요청하기 +## 3.결제 요청하기 [JavaScript SDK](../../../sdk/javascript-sdk/readme) `IMP.request_pay(param, callback)`을 호출하여 스마트로 결제창을 호출할 수 있습니다. **결제결과**는 PC의 경우 `IMP.request_pay(param, callback)` 호출 후 **callback**으로 수신되고 -모바일의 경우 **m_redirect_url** 로 리디렉션됩니다. +모바일의 경우 **m\_redirect\_url** 로 리디렉션됩니다. - -```javascript title="Javascript SDK" -IMP.request_pay({ - pg: 'smartro_v2.{상점 ID}', - pay_method: 'card', - merchant_uid: "orderNo0001", // 상점에서 생성한 고유 주문번호 주의: 스마트로 일반결제시 주문 번호에 특수문자 사용 불가 - name: '주문명:결제테스트', - amount: 1004, - buyer_email: 'test@portone.io', - buyer_name: '구매자이름', - buyer_tel: '010-1234-5678', - buyer_addr: '서울특별시 강남구 삼성동', - buyer_postcode: '123-456', - m_redirect_url: '{모바일에서 결제 완료 후 리디렉션 될 URL}', - period: { - from: "20230512", //YYYYMMDD - to: "20230515", //YYYYMMDD - }, -}, function(rsp) { // callback 로직 - /* ...중략... */ -}); -``` - -
-

주요 파라미터 설명

+ + ```javascript title="Javascript SDK" + IMP.request_pay( + { + pg: "smartro_v2.{상점 ID}", + pay_method: "card", + merchant_uid: "orderNo0001", // 상점에서 생성한 고유 주문번호 주의: 스마트로 일반결제시 주문 번호에 특수문자 사용 불가 + name: "주문명:결제테스트", + amount: 1004, + buyer_email: "test@portone.io", + buyer_name: "구매자이름", + buyer_tel: "010-1234-5678", + buyer_addr: "서울특별시 강남구 삼성동", + buyer_postcode: "123-456", + m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", + period: { + from: "20230512", //YYYYMMDD + to: "20230515", //YYYYMMDD + }, + }, + function (rsp) { + // callback 로직 + /* ...중략... */ + }, + ); + ``` -**`pg` \*****string** +
+

주요 파라미터 설명

+ + **`pg` \*****string** + + **PG사 구분코드** + + `smartro_v2` 로 지정하면 됩니다. + + **`pay_method`** **\*** **string** + + **결제수단 구분코드** + + - card (신용카드) + - trans (실시간 계좌이체) + - vbank(가상계좌) + - phone (휴대폰소액결제) + - lpay (LPAY) + - kakaopay (카카오페이) + - naverpay (네이버페이) + - payco (페이코) + - pinpay (핀페이) -**PG사 구분코드** + **`merchant_uid`** **\*** **string** -`smartro_v2` 로 지정하면 됩니다. + **주문번호** -**`pay_method`** **\*** **string** + 매번 고유하게 채번되어야 합니다. + 주의: 스마트로 일반결제시 주문 번호에 특수문자 사용 불가 -**결제수단 구분코드** + **`amount`** **\*** **`integer`** -- card (신용카드) -- trans (실시간 계좌이체) -- vbank(가상계좌) -- phone (휴대폰소액결제) -- lpay (LPAY) -- kakaopay (카카오페이) -- naverpay (네이버페이) -- payco (페이코) -- pinpay (핀페이) + **결제금액** -**`merchant_uid`** **\*** **string** + **string** 이 아닌점에 유의하세요 -**주문번호** + 소수점 두번째 자리까지 허용합니다. -매번 고유하게 채번되어야 합니다. -주의: 스마트로 일반결제시 주문 번호에 특수문자 사용 불가 + **`buyer_tel`** **\*** **string** -**`amount`** **\*** **`integer`** + **구매자 전화번호** -**결제금액** + 주의: 스마트로 일반 결제시 필수 입력 -**string** 이 아닌점에 유의하세요 + **`vbank_due`** **\*** **string** -소수점 두번째 자리까지 허용합니다. + **가상계좌 입금기한 (YYYY-MM-DD)** -**`buyer_tel`** **\*** **string** + 스마트로의 경우 필수 입력이며 날짜는 무조건 23:59:59로 설정 됨 -**구매자 전화번호** + **`escrow`** **\*** **boolean** -주의: 스마트로 일반 결제시 필수 입력 + **에스크로 결제 여부** -**`vbank_due`** **\*** **string** + **`period`** **\*** **array** -**가상계좌 입금기한 (YYYY-MM-DD)** + **서비스 제공 기간** -스마트로의 경우 필수 입력이며 날짜는 무조건 23:59:59로 설정 됨 + 날짜만 입력이 가능하며(시간은 무시) 시작 날짜와 종료 날짜를 모두 입력해야 합니다. -**`escrow`** **\*** **boolean** + **`from`** **`: YYYYMMDD`** -**에스크로 결제 여부** + **`to`** **`: YYYYMMDD`** +
-**`period`** **\*** **array** +
+

+ 결제 가능 결제수단 +

-**서비스 제공 기간** + - card + 에스크로, 다이렉트 + - vbank + 에스크로 + - trans + 에스크로 + - phone + - lpay + - naverpay + - kakaopay + - pinpay + - payco +
+ -날짜만 입력이 가능하며(시간은 무시) 시작 날짜와 종료 날짜를 모두 입력해야 합니다. + + 인증결제창 호출 파라미터에서 **customer\_uid**, **customer\_id**값을 추가하면 비 인증 결제창을 호출할 수 있습니다. + 비 인증 결제창에서 빌링키를 발급받은 후 해당 빌링키로 결제를 요청합니다. -**`from`** **`: YYYYMMDD`** + ```javascript title="Javascript SDK" + IMP.request_pay( + { + pg: "smartro_v2.{MID}", + pay_method: "card", // 'card'만 지원됩니다. + merchant_uid: "orderMonthly0001", // 상점에서 관리하는 주문 번호 주의: 스마트로 일반결제시 주문 번호에 특수문자 사용 불가 + name: "최초인증결제", + amount: 1000, // 실제 승인은 발생되지 않고 오직 빌링키만 발급됩니다. + customer_uid: "your-customer-unique-id", // 필수 입력. + buyer_email: "test@portone.io", + buyer_name: "포트원", + buyer_tel: "02-1234-1234", + m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", + customer_id: "matthew", //고객사가 회원에게 부여한 고유 ID로 필수 입력. + }, + function (rsp) { + // callback 로직 + }, + ); + ``` -**`to`** **`: YYYYMMDD`** +
+

주요 파라미터 설명

-
+ **`pg` \*****string** -
-

- 결제 가능 결제수단 -

+ **PG사 구분코드** -- card + 에스크로, 다이렉트 -- vbank + 에스크로 -- trans + 에스크로 -- phone -- lpay -- naverpay -- kakaopay -- pinpay -- payco + `smartro_v2` 로 지정하면 됩니다. -
+ **`pay_method`** **\*** **string** - - - - 인증결제창 호출 파라미터에서 **customer\_uid**, **customer\_id**값을 추가하면 비 인증 결제창을 호출할 수 있습니다. - 비 인증 결제창에서 빌링키를 발급받은 후 해당 빌링키로 결제를 요청합니다. - ```javascript title="Javascript SDK" - IMP.request_pay({ - pg: "smartro_v2.{MID}", - pay_method: "card", // 'card'만 지원됩니다. - merchant_uid: "orderMonthly0001", // 상점에서 관리하는 주문 번호 주의: 스마트로 일반결제시 주문 번호에 특수문자 사용 불가 - name: "최초인증결제", - amount: 1000, // 실제 승인은 발생되지 않고 오직 빌링키만 발급됩니다. - customer_uid: "your-customer-unique-id", // 필수 입력. - buyer_email: "test@portone.io", - buyer_name: "포트원", - buyer_tel: "02-1234-1234", - m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", - customer_id: "matthew", //고객사가 회원에게 부여한 고유 ID로 필수 입력. - }, function (rsp) { - // callback 로직 - }); - ``` + **결제수단 구분코드** -
-

주요 파라미터 설명

+ - card (신용카드) -**`pg` \*****string** + **`merchant_uid`** **\*** **string** -**PG사 구분코드** + **주문번호** -`smartro_v2` 로 지정하면 됩니다. + 매번 고유하게 채번되어야 합니다. -**`pay_method`** **\*** **string** + 주의: 스마트로 일반결제시 주문 번호에 특수문자 사용 불가 -**결제수단 구분코드** + **`customer_uid`** **\*** **string** -- card (신용카드) + **`빌링키 발급을 위한 결제 수단을 특정하는 고유 번호`** -**`merchant_uid`** **\*** **string** + 빌링키 발급시 필수 입력 -**주문번호** + **`customer_id`** **\*** **string** -매번 고유하게 채번되어야 합니다. + **`구매자 식별자`** -주의: 스마트로 일반결제시 주문 번호에 특수문자 사용 불가 + 주의: 스마트로 빌링키 발급시 필수 입력으로 입력 길이는 **20자**로 제한됩니다. -**`customer_uid`** **\*** **string** + **`m_redirect_url`** **\*** **string** -**`빌링키 발급을 위한 결제 수단을 특정하는 고유 번호`** + **`리다이렉트 URL`** -빌링키 발급시 필수 입력 - -**`customer_id`** **\*** **string** - -**`구매자 식별자`** - -주의: 스마트로 빌링키 발급시 필수 입력으로 입력 길이는 **20자**로 제한됩니다. - -**`m_redirect_url`** **\*** **string** - -**`리다이렉트 URL`** - -리디렉션 방식으로 진행할 경우, 트랜잭션 종료 이후 302 리디렉션 될 고객사 URL - -스마트로의 경우 모바일 환경에서 **리디렉션 방식으로 빌링키 발급창이 렌더링 되기 때문에 필수입력입니다.** - -
- - + 리디렉션 방식으로 진행할 경우, 트랜잭션 종료 이후 302 리디렉션 될 고객사 URL + 스마트로의 경우 모바일 환경에서 **리디렉션 방식으로 빌링키 발급창이 렌더링 되기 때문에 필수입력입니다.** +
+
-

- 가능한 결제 환경 -

- -- PC (iframe) -- 모바일 (리디렉션) +

+ 가능한 결제 환경 +

+ - PC (iframe) + - 모바일 (리디렉션)
diff --git a/src/content/docs/ko/pg/payment-gateway/smartro.mdx b/src/content/docs/ko/pg/payment-gateway/smartro.mdx index 1fa892036..cdd6687a8 100644 --- a/src/content/docs/ko/pg/payment-gateway/smartro.mdx +++ b/src/content/docs/ko/pg/payment-gateway/smartro.mdx @@ -4,9 +4,9 @@ description: 스마트로 연동 방법을 안내합니다. --- import Figure from "~/components/Figure.astro"; -import Hint from "~/components/Hint.astro"; -import Tabs from "~/components/gitbook/tabs/Tabs.astro"; import Tab from "~/components/gitbook/tabs/Tab.astro"; +import Tabs from "~/components/gitbook/tabs/Tabs.astro"; +import Hint from "~/components/Hint.astro"; **스마트로(구모듈) 연동 방법에 관한 매뉴얼**입니다. @@ -16,13 +16,13 @@ import Tab from "~/components/gitbook/tabs/Tab.astro"; -### 1. 스마트로 채널 설정하기 +## 1. 스마트로 채널 설정하기 [결제대행사 채널 설정하기](../../ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다.
-### 2.결제 요청하기 +## 2.결제 요청하기 [JavaScript SDK](../../sdk/javascript-sdk/readme) `IMP.request_pay(param, callback)`을 호출하여 스마트로 결제창을 호출할 수 있습니다. **결제결과**는 PC의 경우 `IMP.request_pay(param, callback)` @@ -32,21 +32,25 @@ import Tab from "~/components/gitbook/tabs/Tab.astro"; ```javascript title="Javascript SDK" -IMP.request_pay({ - pg: "smartro.{상점 ID}", - pay_method: "card", - merchant_uid: "order_no_0001", // 상점에서 생성한 고유 주문번호 - name: "주문명:결제테스트", - amount: 1004, - buyer_email: "test@portone.io", - buyer_name: "구매자이름", - buyer_tel: "010-1234-5678", - buyer_addr: "서울특별시 강남구 삼성동", - buyer_postcode: "123-456", - m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}" -}, function(rsp) { // callback 로직 - /* ...중략... */ -}); +IMP.request_pay( + { + pg: "smartro.{상점 ID}", + pay_method: "card", + merchant_uid: "order_no_0001", // 상점에서 생성한 고유 주문번호 + name: "주문명:결제테스트", + amount: 1004, + buyer_email: "test@portone.io", + buyer_name: "구매자이름", + buyer_tel: "010-1234-5678", + buyer_addr: "서울특별시 강남구 삼성동", + buyer_postcode: "123-456", + m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", + }, + function (rsp) { + // callback 로직 + /* ...중략... */ + }, +); ``` **주요 파라미터 설명** diff --git a/src/content/docs/ko/pg/payment-gateway/spb/stc.mdx b/src/content/docs/ko/pg/payment-gateway/spb/stc.mdx index 51a26d7ba..db4a6037e 100644 --- a/src/content/docs/ko/pg/payment-gateway/spb/stc.mdx +++ b/src/content/docs/ko/pg/payment-gateway/spb/stc.mdx @@ -10,7 +10,7 @@ import Details from "~/components/gitbook/Details.astro"; 모든 파라미터는 String 타입으로 보내셔야 합니다. Format이 작성되어 있지 않은 필드들은 자유 형식으로 보내주시면 됩니다. -### 산업군 별 파라미터 +## 산업군 별 파라미터

이벤트/티켓 판매 산업

diff --git a/src/content/docs/ko/pg/payment-gateway/toss.mdx b/src/content/docs/ko/pg/payment-gateway/toss.mdx index 38ab63882..63158eb76 100644 --- a/src/content/docs/ko/pg/payment-gateway/toss.mdx +++ b/src/content/docs/ko/pg/payment-gateway/toss.mdx @@ -14,13 +14,13 @@ import Hint from "~/components/Hint.astro"; 구모듈에 비해 신모듈에서 다양한 기능 및 결제수단을 지원하고 있습니다. 신규 고객사의 경우 가급적 신모듈로 연동하는 것을 권장드립니다. -### 1. 토스페이먼츠 채널 설정하기 +## 1. 토스페이먼츠 채널 설정하기 [결제대행사 채널 설정하기](../../ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다.
-### 2. 결제창 호출 +## 2. 결제창 호출 [JavaScript SDK](../../sdk/javascript-sdk-old/readme) `IMP.request_pay(param, callback)`을 호출하여 토스페이먼츠 결제창을 호출할 수 있습니다. **결제결과**는 PC의 경우 `IMP.request_pay(param, callback)` 호출 후 **callback** 으로 수신되 모바일의 경우 **m_redirect_url** 로 리디렉션됩니다. @@ -45,7 +45,7 @@ IMP.request_pay( function (rsp) { // callback 로직 //* ...중략... *// - } + }, ); ``` diff --git a/src/content/docs/ko/pg/payment-gateway/welcome/api.mdx b/src/content/docs/ko/pg/payment-gateway/welcome/api.mdx index 5a943a7ef..3d3e7e157 100644 --- a/src/content/docs/ko/pg/payment-gateway/welcome/api.mdx +++ b/src/content/docs/ko/pg/payment-gateway/welcome/api.mdx @@ -3,7 +3,7 @@ title: API 연동 description: 웰컴페이먼츠 API 연동 방법을 안내합니다. --- -### 지원 기능 +## 지원 기능 - 가상 계좌 발급, 회수 - 현금영수증 발급, 취소, 조회 diff --git a/src/content/docs/ko/pg/payment-gateway/welcome/caution.mdx b/src/content/docs/ko/pg/payment-gateway/welcome/caution.mdx index 67e6142f8..688ec3bf8 100644 --- a/src/content/docs/ko/pg/payment-gateway/welcome/caution.mdx +++ b/src/content/docs/ko/pg/payment-gateway/welcome/caution.mdx @@ -4,12 +4,8 @@ description: 웰컴페이먼츠 연동 유의사항을 소개합니다. --- import Details from "~/components/gitbook/Details.astro"; -import Figure from "~/components/Figure.astro"; -import Hint from "~/components/Hint.astro"; -import Tabs from "~/components/gitbook/tabs/Tabs.astro"; -import Tab from "~/components/gitbook/tabs/Tab.astro"; -# 웰컴페이먼츠와 사전 계약이 필요한 경우 +## 웰컴페이먼츠와 사전 계약이 필요한 경우 아래 기능을 사용하시려면 웰컴페이먼츠에 사전 신청 후 계약이 완료되어야 합니다. 그렇지 않은 상태에서 해당 기능 이용시 결제 승인에 실패하거나, 승인에 성공하더라도 의도한 바와는 다른 응답(예: 결제창에서 @@ -24,7 +20,7 @@ import Tab from "~/components/gitbook/tabs/Tab.astro"; - 휴대폰 실물 / 컨텐츠 사용 - 휴대폰 빌링키 발급과 동시에 결제 실물 / 컨텐츠 사용 -# 테스트 모드 유의사항 +## 테스트 모드 유의사항 ### 테스트 모드에서 확인 불가능한 일부 기능/파라미터 존재 @@ -40,35 +36,34 @@ import Tab from "~/components/gitbook/tabs/Tab.astro"; 성공하며, 승인 결과로 할부 개월수는 0(일시불)이 아닌, 결제창 호출시 전달 한 값 그대로 리턴됩니다.
-

파라미터 예제 코드

- -```javascript -// 1. 국민카드 5개월 할부 다이렉트 호출 -{ - ...중략 - pg: 'welcome', - pay_method: 'card', - amount: '50000', - card: { +

파라미터 예제 코드

+ + ```json + // 1. 국민카드 5개월 할부 다이렉트 호출 + { + //...중략 + pg: "welcome", + pay_method: "card", + amount: 50000, + card: { direct: { // 국민카드 5개월 할부 다이렉트 호출 - code: '381', - quota: 5, + code: "381", + quota: 5, + } } } -} - -// 2. 국민카드 앱에서 체크카드로 결제 -// 3. 승인 응답 결과 할부 개월수가 5로 전달 됨 -// GET /payments/{imp_uid} -{ - ...중략 - **card_quota: 5** -} -``` + // 2. 국민카드 앱에서 체크카드로 결제 + // 3. 승인 응답 결과 할부 개월수가 5로 전달 됨 + // GET /payments/{imp_uid} + { + //...중략 + card_quota: 5 + } + ```
-# 공통 유의사항 +## 공통 유의사항 ### 구매자 연락처(PC만), 이름, 주문명, 주문번호는 필수 입력 @@ -91,49 +86,47 @@ IOS 모바일 웹/인앱 브라우저에서 결제창 호출 후 카드사 앱 단, 현금영수증 자진발급(`anonymous`) 옵션만 지원하기 때문에 현금영수증 발행 식별 정보 파라미터(`customerIdentifier`)는 지원하지 않습니다.
-

지원 가능: 현금영수증 자진 발급

- -```javascript -{ - // 현금영수증 자진 발급 - ...중략 - pg: 'welcome', - pay_method: 'vbank', - bypass: { - cashReceiptType: 'anonymous' - } -} -``` - +

지원 가능: 현금영수증 자진 발급

+ + ```json + { + // 현금영수증 자진 발급 + //...중략 + pg: "welcome", + pay_method: "vbank", + bypass: { + cashReceiptType: "anonymous" + } + } + ```
-

지원 불가: 현금영수증 소득공제/지출증빙

- -```javascript -{ - // 현금영수증 소득공제 - ...중략 - pg: 'welcome', - pay_method: 'trans', - bypass: { - cashReceiptType: 'personal', - customerIdentifier: '01012345678' - } - // 웰컴페이먼츠에서 제공하지 않는 현금영수증 발급 유형(CASH_RECEIPT_TYPE_PERSONAL)입니다. - - // 현금영수증 지출증빙 - ...중략 - pg: 'welcome', - pay_method: 'trans', - bypass: { - cashReceiptType: 'corporate', - customerIdentifier: '1178178260' - } - // 웰컴페이먼츠에서 제공하지 않는 현금영수증 발급 유형(CASH_RECEIPT_TYPE_CORPORATE)입니다. -} -``` - +

지원 불가: 현금영수증 소득공제/지출증빙

+ + ```json + { + // 현금영수증 소득공제 + //...중략 + pg: "welcome", + pay_method: "trans", + bypass: { + cashReceiptType: "personal", + customerIdentifier: "01012345678" + } + // 웰컴페이먼츠에서 제공하지 않는 현금영수증 발급 유형(CASH_RECEIPT_TYPE_PERSONAL)입니다. + + // 현금영수증 지출증빙 + //...중략 + pg: "welcome", + pay_method: "trans", + bypass: { + cashReceiptType: "corporate", + customerIdentifier: "1178178260" + } + // 웰컴페이먼츠에서 제공하지 않는 현금영수증 발급 유형(CASH_RECEIPT_TYPE_CORPORATE)입니다. + } + ```
## 제공기간 파라미터(`period`) @@ -143,37 +136,35 @@ IOS 모바일 웹/인앱 브라우저에서 결제창 호출 후 카드사 앱 제공기간 파라미터는 (from과 to) 또는 interval만 입력 가능하며 셋 다 입력은 불가능합니다.
-

파라미터 예제 코드

- -```javascript -// period: { from: "2023-01-01", to: "2023-03-01", interval: "1m" } -{ - ...중략 - error_msg: "제공 기간은 range와 interval 둘 중 하나만 입력해주세요" -} -``` +

파라미터 예제 코드

+ ```javascript + // period: { from: "2023-01-01", to: "2023-03-01", interval: "1m" } + { + //...중략 + error_msg: "제공 기간은 range와 interval 둘 중 하나만 입력해주세요"; + } + ```
또한 from과 to를 입력하는 경우 둘 다 입력해야하며 둘 중 하나만 입력은 불가능합니다.
-

파라미터 예제 코드

- -```javascript -// period: { from: "2023-01-01" } -{ - ...중략 - error_msg: "웰컴페이먼츠의 경우 제공 기간은 시작 날짜와 종료 날짜를 모두 입력하셔야 합니다. (둘 중 하나만 입력 불가)" -} - -// period: { to: "2023-03-01" } -{ - ...중략 - error_msg: "웰컴페이먼츠의 경우 제공 기간은 시작 날짜와 종료 날짜를 모두 입력하셔야 합니다. (둘 중 하나만 입력 불가)" -} -``` +

파라미터 예제 코드

+ + ```javascript + // period: { from: "2023-01-01" } + { + //...중략 + error_msg: "웰컴페이먼츠의 경우 제공 기간은 시작 날짜와 종료 날짜를 모두 입력하셔야 합니다. (둘 중 하나만 입력 불가)"; + } + // period: { to: "2023-03-01" } + { + //...중략 + error_msg: "웰컴페이먼츠의 경우 제공 기간은 시작 날짜와 종료 날짜를 모두 입력하셔야 합니다. (둘 중 하나만 입력 불가)"; + } + ```
### 날짜(`from`과 `to`)의 경우 PC와 모바일 지원 형식이 다름 @@ -181,17 +172,16 @@ IOS 모바일 웹/인앱 브라우저에서 결제창 호출 후 카드사 앱 웰컴페이먼츠의 경우 제공기간 파라미터에 대해 PC의 경우 날짜까지만 표기되지만 모바일의 경우 분까지 표기됩니다.
-

파라미터 예제 코드

- -```javascript -{ - ...중략 - period: { from: '2023-01-01 00:00:00', to: '2023-03-01 23:59:59' } -} -// PC에서는 "2023-01-01 ~ 2023-03-01"로 표기(시간 정보 무시) -// 모바일에서는 "2023-01-01 00:00 ~ 2023-03-01 23:59"로 표기(초 정보 무시) -``` +

파라미터 예제 코드

+ ```json + { + //...중략 + period: { from: "2023-01-01 00:00:00", to: "2023-03-01 23:59:59" } + } + // PC에서는 "2023-01-01 ~ 2023-03-01"로 표기(시간 정보 무시) + // 모바일에서는 "2023-01-01 00:00 ~ 2023-03-01 23:59"로 표기(초 정보 무시) + ```
### 간격(`interval`)은 1m 또는 1y만 허용 됨 @@ -199,29 +189,34 @@ IOS 모바일 웹/인앱 브라우저에서 결제창 호출 후 카드사 앱 웰컴페이먼츠의 경우 제공 기간을 간격으로 입력하는 경우, 1m 또는 1y만 허용됩니다.
-

파라미터 예제 코드

- -```javascript -// 옵션1. interval을 1m로 설정 -{ - ...중략 - period: { interval: '1m' } -} - -// 옵션2. interval을 1y로 설정 -{ - ...중략 - period: { interval: '1y' } -} - -// 옵션 3. interval을 1d로 설정 -{ - ...중략 - period: { interval: '1d' } -} --> 웰컴페이먼츠 제공 기간 주기가 올바르지 않습니다. 1m 또는 1y만 허용됩니다. -``` +

파라미터 예제 코드

+ + ```javascript + // 옵션1. interval을 1m로 설정 + { + //...중략 + period: { + interval: "1m"; + } + } + + // 옵션2. interval을 1y로 설정 + { + //...중략 + period: { + interval: "1y"; + } + } + // 옵션 3. interval을 1d로 설정 + { + //...중략 + period: { + interval: "1d"; + } + } + // 웰컴페이먼츠 제공 기간 주기가 올바르지 않습니다. 1m 또는 1y만 허용됩니다. + ```
### 모바일 환경 - 휴대폰 결제시 제공 기간 파라미터(`period`)를 지원하지 않음 @@ -240,49 +235,48 @@ IOS 모바일 웹/인앱 브라우저에서 결제창 호출 후 카드사 앱 렌더링을 허용 할 통신사 리스트(`phone.detail`) 옵션과 기본 선택 될 통신사 옵션(`bypass.welcome.acceptmethod.hppdefaultcorp(통신사)`/`P_RESERVED.hpp_default_corp=통신사`)은 함께 사용할 경우 정상적으로 동작하지 않아 둘 중 하나만 사용해야 합니다.
-

파라미터 예제 코드

+

파라미터 예제 코드

-```javascript -// 옵션1. SKT와 KT만 렌더링을 허용 -> 정상 동작 -{ - ...중략 - phone: { + ```json + // 옵션1. SKT와 KT만 렌더링을 허용 -> 정상 동작 + { + //...중략 + phone: { detail: [ - { carrier: 'SKT', enabled: true }, - { carrier: 'KTF', enabled: true } - ] + { carrier: "SKT", enabled: true }, + { carrier: "KTF", enabled: true } + ] + } } -} - -// 옵션2. SKT를 기본 선택 -> 정상 동작 -{ - ...중략 - bypass: { - welcome: { - acceptmethod: ['hppdefaultcorp(SKT)'], - P_RESERVED: ['hpp_default_corp=SKT'] + + // 옵션2. SKT를 기본 선택 -> 정상 동작 + { + //...중략 + bypass: { + welcome: { + acceptmethod: ["hppdefaultcorp(SKT)"], + P_RESERVED: ["hpp_default_corp=SKT"] + } } } -} -// 옵션3. 옵션 1 + 옵션 2 -> 정상 동작하지 않음 -{ - ...중략 - phone: { - detail: [ - { carrier: 'SKT', enabled: true }, - { carrier: 'KTF', enabled: true } - ] - }, - bypass: { - welcome: { - acceptmethod: ['hppdefaultcorp(SKT)'], - P_RESERVED: ['hpp_default_corp=SKT'] + // 옵션3. 옵션 1 + 옵션 2 -> 정상 동작하지 않음 + { + //...중략 + phone: { + detail: [ + { carrier: "SKT", enabled: true }, + { carrier: "KTF", enabled: true } + ] + }, + bypass: { + welcome: { + acceptmethod: ["hppdefaultcorp(SKT)"], + P_RESERVED: ["hpp_default_corp=SKT"] + } } } -} -``` - + ```
# 일반결제 유의사항 @@ -294,19 +288,18 @@ IOS 모바일 웹/인앱 브라우저에서 결제창 호출 후 카드사 앱 웰컴페이먼츠의 경우 PC 환경에서는 일시불이 기본으로 포함되기 때문에, 할부 개월수에 0(일시불)을 넣지 않더라도 결제창에 자동으로 표기됩니다.
-

파라미터 예제 코드

- -```javascript -{ - ...중략 - pg: 'welcome', - pay_method: 'card', - display: { - card_quota: [2,3,4,5,6] // 일시불 + 2개월 ~ 6개월까지 결제창에 표기 - } -} -``` - +

파라미터 예제 코드

+ + ```json + { + //...중략 + pg: "welcome", + pay_method: "card", + display: { + card_quota: [2,3,4,5,6] // 일시불 + 2개월 ~ 6개월까지 결제창에 표기 + } + } + ```
### PC 환경에서는 할부 옵션을 설정하지 않는 경우 무조건 일시불로 결제 됨 @@ -314,27 +307,26 @@ IOS 모바일 웹/인앱 브라우저에서 결제창 호출 후 카드사 앱 웰컴페이먼츠의 경우 PC 환경에서 **할부 옵션을 전달하지 않는 경우 `무조건 일시불만 표기`**되니 주의하시기 바랍니다.
-

파라미터 예제 코드

- -```javascript -// 일시불만 표기 -{ - ...중략 - pg: 'welcome', - pay_method: 'card', -} - -// 일시불 + 2개월 ~ 6개월까지 결제창에 표기 -{ - ...중략 - pg: 'welcome', - pay_method: 'card', - display: { - card_quota: [2,3,4,5,6] // 일시불 + 2개월 ~ 6개월까지 결제창에 표기 - } -} -``` +

파라미터 예제 코드

+ + ```json + // 일시불만 표기 + { + //...중략 + pg: "welcome", + pay_method: "card", + } + // 일시불 + 2개월 ~ 6개월까지 결제창에 표기 + { + //...중략 + pg: "welcome", + pay_method: "card", + display: { + card_quota: [2,3,4,5,6] // 일시불 + 2개월 ~ 6개월까지 결제창에 표기 + } + } + ```
### 카드사 다이렉트 호출시 고정 할부 개월수는 필수 입력 @@ -347,29 +339,28 @@ IOS 모바일 웹/인앱 브라우저에서 결제창 호출 후 카드사 앱 할부 개월수를 함께 넘겨야 하니다.
-

파라미터 예제 코드

- -```javascript -// 예. BC카드 5개월 할부 -...중략 -pg: 'welcome', -pay_method: 'card', -card: { - direct: { - // 다이렉트 호출 할 카드사 코드와 고정 할부 개월수를 모두 지정해야 함 - code: '361' // BC카드 - quota: 5, // 5개월 할부 +

파라미터 예제 코드

+ + ```json + // 예. BC카드 5개월 할부 + //...중략 + pg: "welcome", + pay_method: "card", + card: { + direct: { + // 다이렉트 호출 할 카드사 코드와 고정 할부 개월수를 모두 지정해야 함 + code: "361" // BC카드 + quota: 5, // 5개월 할부 + } } -} -// 예. 결제창에서 카드사와 할부 개월수 선택 -...중략 -pg: 'welcome', -pay_method: 'card' - -// 다이렉트 호출 할 카드사와 고정 할부 개월수 모두 지정하지 않아야 함 -``` + // 예. 결제창에서 카드사와 할부 개월수 선택 + //...중략 + pg: "welcome", + pay_method: "card" + // 다이렉트 호출 할 카드사와 고정 할부 개월수 모두 지정하지 않아야 함 + ```
### 카드사 포인트 사용 불가 옵션 사용 불가능 @@ -412,16 +403,15 @@ PC 환경에서는 별도 제한이 없습니다. 단, 웰컴페이먼츠의 경우 전달 한 초 값은 무시되며 무조건 59초로 설정되니 유의하시기 바랍니다.
-

파라미터 예제 코드

- -```javascript -{ - ...중략 - vbank_due: '2023-01-01 12:34:56' -} -// 입금 기한이 "2023-01-01 12:34:59"로 설정 됨 -``` +

파라미터 예제 코드

+ ```javascript + { + // ...중략 + vbank_due: "2023-01-01 12:34:56"; + } + // 입금 기한이 "2023-01-01 12:34:59"로 설정 됨 + ```
## 상품권 결제 @@ -432,32 +422,31 @@ PC 환경에서는 별도 제한이 없습니다. ## 간편 결제 -### 토스페이의 경우, 할부 개월수 리스트는 전달한 값과 카드사가 제공하는 무이자 할부 개월 수의 최대값까지 표기 됨 +### 할부 개월수 리스트는 전달한 값과 카드사가 제공하는 무이자 할부 개월 수의 최대값까지 표기됨 예를 들어 할부 개월수 리스트를 3개월까지 렌더링 되도록 설정했으나, 현재 해당 카드사에서 6개월까지 무이자 할부 이벤트가 진행되고 있다면 할부 개월수는 6개월까지 표기 됩니다.
-

파라미터 예제 코드

- -```javascript -// 예) 할부 개월수를 3개월까지 렌더링 되도록 설정 -...중략 -pg: 'welcome', -pay_method: 'card', -display: { - card_quota: [2,3] -} - -// 결과) 테스트 당시 우리카드가 6개월까지 무이자 할부 이벤트가 진행중이기 때문에 6개월까지 할부 개월수가 렌더링 됨 -``` +

파라미터 예제 코드

+ + ```json + // 예) 할부 개월수를 3개월까지 렌더링 되도록 설정 + //...중략 + pg: "welcome", + pay_method: "card", + display: { + card_quota: [2,3] + } -### 카카오페이의 경우, 카드 정보를 제공하지 않음 + // 결과) 테스트 당시 우리카드가 6개월까지 무이자 할부 이벤트가 진행중이기 때문에 6개월까지 할부 개월수가 렌더링 됨 + ``` -카카오페이에 등록 된 카드로 결제시 카카오페이에서 카드 정보를 내려주지 않기 때문에 카드 정보를 확인할 수 없습니다. + ### 카카오페이의 경우, 카드 정보를 제공하지 않음 + 카카오페이에 등록 된 카드로 결제시 카카오페이에서 카드 정보를 내려주지 않기 때문에 카드 정보를 확인할 수 없습니다.
-# 빌링키 발급 유의사항 +## 빌링키 발급 유의사항 ### 빌링키 발급 수단(`pay_method`)은 필수 입력이며 카드(`card`)만 허용 됨 @@ -467,11 +456,11 @@ display: { 금액(amount) 파라미터는 필수 입력이며, **전달 한 금액(amount)만큼 실제로 승인이 되지 않고** 단순히 빌링키 발급 창에 표기 될 용도로만 사용됩니다. -### 면세 금액(tax_free)과 부가세(vat_amount)는 지원하지 않음 +### 면세 금액(tax\_free)과 부가세(vat\_amount)는 지원하지 않음 빌링키 발급만 되고 실제 승인은 되지 않기 때문에 면세 금액과 부가세는 지원하지 않으며, 전달해도 무시됩니다. -# 빌링키 발급과 동시에 결제 유의사항 +## 빌링키 발급과 동시에 결제 유의사항 ### 빌링키 발급 및 결제 수단(`pay_method`)은 필수 입력이며 휴대폰(`phone`)만 허용 됨 @@ -481,7 +470,7 @@ display: { 금액(amount) 파라미터는 필수 입력이며, **전달 한 금액(amount)만큼 실제로 승인이 됩니다.** -### 면세 금액(tax_free)과 부가세(vat_amount)는 지원하지 않음 +### 면세 금액(tax\_free)과 부가세(vat\_amount)는 지원하지 않음 웰컴페이먼츠의 경우 빌링키 발급과 동시에 결제시, 실제 승인이 되지만 면세 금액과 부가세는 지원하지 않으며, 전달해도 무시됩니다. @@ -491,7 +480,7 @@ display: { 따라서 제공기간 파라미터는 지원되지 않으며, PG 창의 제공기간 영역에 무조건 "월 자동결제"로 표기됩니다. -# 에스크로 유의사항 +## 에스크로 유의사항 ### 에스크로 결제의 경우 고객사가 임의로 취소할 수 없음 diff --git a/src/content/docs/ko/pg/payment-gateway/welcome/readme.mdx b/src/content/docs/ko/pg/payment-gateway/welcome/readme.mdx index 33bd512ee..fb52debc6 100644 --- a/src/content/docs/ko/pg/payment-gateway/welcome/readme.mdx +++ b/src/content/docs/ko/pg/payment-gateway/welcome/readme.mdx @@ -4,261 +4,263 @@ description: 웰컴페이먼츠 연동 방법을 안내합니다. --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; - -import Figure from "~/components/Figure.astro"; -import Tabs from "~/components/gitbook/tabs/Tabs.astro"; import Tab from "~/components/gitbook/tabs/Tab.astro"; +import Tabs from "~/components/gitbook/tabs/Tabs.astro"; +import Hint from "~/components/Hint.astro"; -### 1. 웰컴페이먼츠 채널 설정하기 +## 1. 웰컴페이먼츠 채널 설정하기 [결제대행사 채널 설정하기](../../ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다. -### 2. 최신 JavaScript SDK로 업데이트하기 +## 2. 최신 JavaScript SDK로 업데이트하기 웰컴페이먼츠 결제는 최신 SDK에서만 지원되는 기능입니다. -```javascript title="JS SDK" +```html title="JS SDK" ``` **웰컴페이먼츠를 연동하기 위해서는 위에 안내된 JS SDK를 이용하셔야 합니다** - [JavaScript SDK](../../../sdk/javascript-sdk/readme) 문서를 통해 최신 SDK를 설치해주세요. -### 3.결제 요청하기 +## 3.결제 요청하기 [JavaScript SDK](../../../sdk/javascript-sdk/readme) `IMP.request_pay(param, callback)`을 호출하여 웰컴페이먼츠 결제/빌링키 발급/빌링키 발급과 동시에 결제창을 호출할 수 있습니다. **트랜잭션 결과**는 PC의 경우 **callback** 함수로 전달되고 -모바일의 경우 **m_redirect_url**로 302 리디렉션됩니다. +모바일의 경우 **m\_redirect\_url**로 302 리디렉션됩니다. - -```javascript title="Javascript SDK" -IMP.request_pay({ - pg: 'welcome.{상점 ID}', - pay_method: 'card', - merchant_uid: "orderNo0001", // 고객사에서 채번한 주문 고유 번호입니다. - name: '주문명:결제테스트', - amount: 1004, - buyer_email: 'test@portone.io', - buyer_name: '구매자이름', - buyer_tel: '010-1234-5678', - m_redirect_url: '{모바일에서 결제 완료 후 리디렉션 될 URL}', -}, function(rsp) { // callback 로직 - const { imp_uid, merchant_uid } = rsp; - - // 콜백 함수로 전달 받은 imp_uid로 포트원 결제 내역 조회 API를 통해 결제 상태를 판단합니다. -}); -``` + + ```javascript title="Javascript SDK" + IMP.request_pay( + { + pg: "welcome.{상점 ID}", + pay_method: "card", + merchant_uid: "orderNo0001", // 고객사에서 채번한 주문 고유 번호입니다. + name: "주문명:결제테스트", + amount: 1004, + buyer_email: "test@portone.io", + buyer_name: "구매자이름", + buyer_tel: "010-1234-5678", + m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", + }, + function (rsp) { + // callback 로직 + const { imp_uid, merchant_uid } = rsp; -
-

주요 파라미터 설명

+ // 콜백 함수로 전달 받은 imp_uid로 포트원 결제 내역 조회 API를 통해 결제 상태를 판단합니다. + }, + ); + ``` + +
+

주요 파라미터 설명

-**`pg`** **\*** **`welcome`** + **`pg`** **\*** **`welcome`** -**PG사 구분코드** + **PG사 구분코드** -**`pay_method`** **\*** **string** + **`pay_method`** **\*** **string** -**결제수단 구분코드** + **결제수단 구분코드** -- card (신용카드) -- trans (실시간 계좌이체) -- vbank (가상계좌) -- phone (휴대폰소액결제) -- culturegift (문화상품권) -- lpay (LPAY) -- kakaopay (카카오페이) -- payco (페이코) -- tosspay (토스페이) + - card (신용카드) + - trans (실시간 계좌이체) + - vbank (가상계좌) + - phone (휴대폰소액결제) + - culturegift (문화상품권) + - lpay (LPAY) + - kakaopay (카카오페이) + - payco (페이코) + - tosspay (토스페이) -**`merchant_uid`** **\*** **string** + **`merchant_uid`** **\*** **string** -**주문 번호** + **주문 번호** -매번 고유하게 채번되어야 합니다. + 매번 고유하게 채번되어야 합니다. -**`amount`** **\*** **`integer`** + **`amount`** **\*** **`integer`** -**결제 금액** + **결제 금액** -**string** 이 아닌 점에 유의하세요. + **string** 이 아닌 점에 유의하세요. -**`tax_free`** **number** + **`tax_free`** **number** -**면세 금액** + **면세 금액** -**`vat_amount`** **number** + **`vat_amount`** **number** -**부가세 금액** + **부가세 금액** -상점 아이디가 “부가세 업체 정함”으로 설정 된 경우일때만 전달 가능합니다. + 상점 아이디가 “부가세 업체 정함”으로 설정 된 경우일때만 전달 가능합니다. -주의: 전체 금액의 10% 이하만 허용 됩니다. + 주의: 전체 금액의 10% 이하만 허용 됩니다. -**`buyer_name`** **\*** **string** + **`buyer_name`** **\*** **string** -**구매자 이름** + **구매자 이름** -주의: 웰컴페이먼츠의 경우 구매자 이름은 필수 입력입니다. + 주의: 웰컴페이먼츠의 경우 구매자 이름은 필수 입력입니다. -**`buyer_tel`** **\*** **string** + **`buyer_tel`** **\*** **string** -**구매자 연락처** + **구매자 연락처** -주의: 웰컴페이먼츠의 경우 구매자 연락처는 필수 입력입니다. + 주의: 웰컴페이먼츠의 경우 구매자 연락처는 필수 입력입니다. -**`buyer_email`** **string** + **`buyer_email`** **string** -**구매자 이메일 주소** + **구매자 이메일 주소** -**`m_redirect_url`** **string** + **`m_redirect_url`** **string** -**모바일 환경에서 트랜잭션 종료 후 302 리디렉션 될 URL** + **모바일 환경에서 트랜잭션 종료 후 302 리디렉션 될 URL** -주의: 웰컴페이먼츠의 경우 **모바일 환경에서 필수 입력**입니다. + 주의: 웰컴페이먼츠의 경우 **모바일 환경에서 필수 입력**입니다. -**`notice_url`** **string** 또는 **string[]** + **`notice_url`** **string** 또는 **string\[]** -**트랜잭션 종료 후 웹훅이 발송 될 고객사 서버 URL** + **트랜잭션 종료 후 웹훅이 발송 될 고객사 서버 URL** -주의: notice_url 파라미터 설정시, 콘솔에 설정 된 웹훅 URL은 override 되며 notice_url에 전달 한 주소로만 웹훅이 발송됩니다. + 주의: notice\_url 파라미터 설정시, 콘솔에 설정 된 웹훅 URL은 override 되며 notice\_url에 전달 한 주소로만 웹훅이 발송됩니다. -**`confirm_url`** **string** + **`confirm_url`** **string** -**트랜잭션 승인 직전 최종 승인 여부를 질의 할 고객사 서버 URL** + **트랜잭션 승인 직전 최종 승인 여부를 질의 할 고객사 서버 URL** -트랜잭션 승인 직전, 포트원 서버에서 confirm_url로 트랜잭션 최종 승인 여부를 질의하게 되며 200 외의 응답을 받은 경우 트랜잭션은 중단됩니다. + 트랜잭션 승인 직전, 포트원 서버에서 confirm\_url로 트랜잭션 최종 승인 여부를 질의하게 되며 200 외의 응답을 받은 경우 트랜잭션은 중단됩니다. -**`app_scheme`** **string** + **`app_scheme`** **string** -**IOS 앱에서 결제시 카드/은행 앱에서 인증 후 복귀 될 고객사 커스텀 앱 URL Scheme** + **IOS 앱에서 결제시 카드/은행 앱에서 인증 후 복귀 될 고객사 커스텀 앱 URL Scheme** -- 예: portone:// -- 주의: **IOS 앱 결제시 필수** 입력이며 **앱이 아닌 모바일 웹 결제시에는 입력하지 마세요.** + - 예: portone:// + - 주의: **IOS 앱 결제시 필수** 입력이며 **앱이 아닌 모바일 웹 결제시에는 입력하지 마세요.** -**`currency`** **`KRW`** + **`currency`** **`KRW`** -**결제 통화** + **결제 통화** -웰컴페이먼츠의 경우 KRW만 허용되며, 미 입력시 KRW로 자동 적용됩니다. + 웰컴페이먼츠의 경우 KRW만 허용되며, 미 입력시 KRW로 자동 적용됩니다. -**`language`** **string** + **`language`** **string** -**결제창 언어 설정** + **결제창 언어 설정** -- ko(한국어, 기본값) -- en(영어) -- zh(중국어) + - ko(한국어, 기본값) + - en(영어) + - zh(중국어) -**`digital`** **string** + **`digital`** **string** -**휴대폰 소액결제시 실물/컨텐츠 여부** + **휴대폰 소액결제시 실물/컨텐츠 여부** -주의: **휴대폰 소액결제시 필수 입력**입니다. + 주의: **휴대폰 소액결제시 필수 입력**입니다. -**`vbank_due`** **\*** **string** + **`vbank_due`** **\*** **string** -**가상계좌 입금기한** + **가상계좌 입금기한** -- YYYY-MM-DD -- YYYY-MM-DD HH:mm:ss -- YYYYMMDD -- YYYYMMDDHHmmss + - YYYY-MM-DD + - YYYY-MM-DD HH:mm:ss + - YYYYMMDD + - YYYYMMDDHHmmss -주의: 웰컴페이먼츠의 경우 무시되며 무조건 59초로 설정 됩니다. + 주의: 웰컴페이먼츠의 경우 무시되며 무조건 59초로 설정 됩니다. -**`escrow`** **boolean** + **`escrow`** **boolean** -**에스크로 결제 여부** + **에스크로 결제 여부** -웰컴페이먼츠의 경우, 카드/계좌이체/가상계좌 결제시 에스크로 결제가 허용됩니다. + 웰컴페이먼츠의 경우, 카드/계좌이체/가상계좌 결제시 에스크로 결제가 허용됩니다. -**`useCardPoint`** **boolean** + **`useCardPoint`** **boolean** -**카드사 포인트 사용 여부** + **카드사 포인트 사용 여부** -웰컴페이먼츠의 경우, 카드사 포인트 사용 불가 옵션(useCardPoint: false)은 지원하지 않습니다. + 웰컴페이먼츠의 경우, 카드사 포인트 사용 불가 옵션(useCardPoint: false)은 지원하지 않습니다. -카드사 포인트 사용(useCardPoint: true) 또는 기본값(=파라미터 전달하지 않음, 결제창에서 고객이 카드사 포인트 사용 여부 결정)만 사용 가능합니다. + 카드사 포인트 사용(useCardPoint: true) 또는 기본값(=파라미터 전달하지 않음, 결제창에서 고객이 카드사 포인트 사용 여부 결정)만 사용 가능합니다. -**`useFreeInterestFromMall`** **boolean** + **`useFreeInterestFromMall`** **boolean** -**상점 부담 무이자 할부 사용 여부** + **상점 부담 무이자 할부 사용 여부** -**`period`** **object** + **`period`** **object** -**서비스 제공 기간** + **서비스 제공 기간** -(from과 to) 또는 interval 중 하나만 입력 가능합니다. + (from과 to) 또는 interval 중 하나만 입력 가능합니다. -주의: 모바일 환경 - 휴대폰 소액결제시엔 지원하지 않습니다. + 주의: 모바일 환경 - 휴대폰 소액결제시엔 지원하지 않습니다. -- **`from`**: 서비스 제공 시작 시각 -- **`to`**: 서비스 제공 종료 시각 + - **`from`**: 서비스 제공 시작 시각 - - YYYY-MM-DD - - YYYY-MM-DD HH:mm:ss - - YYYYMMDD - - YYYYMMDDHHmmss + - **`to`**: 서비스 제공 종료 시각 - 웰컴페이먼츠의 경우 + - YYYY-MM-DD + - YYYY-MM-DD HH:mm:ss + - YYYYMMDD + - YYYYMMDDHHmmss - - PC: 날짜까지만 입력 가능하며 시간은 무시됩니다. - - 모바일: 날짜와 시간 모두 입력 가능하며 초는 무시됩니다. + 웰컴페이먼츠의 경우 -- **`interval`**: 서비스 제공 간격 - - 1m: 매월 정기결제 - - 1y: 매년 정기결제 + - PC: 날짜까지만 입력 가능하며 시간은 무시됩니다. + - 모바일: 날짜와 시간 모두 입력 가능하며 초는 무시됩니다. -**`bypass.logo_url`** **string** + - **`interval`**: 서비스 제공 간격 + - 1m: 매월 정기결제 + - 1y: 매년 정기결제 -결제창에 노출 될 메인 로고 URL(크기: 89x19)로 **PC 전용** 파라미터입니다. + **`bypass.logo_url`** **string** -**`bypass.logo_2nd`** **string** + 결제창에 노출 될 메인 로고 URL(크기: 89x19)로 **PC 전용** 파라미터입니다. -결제창에 노출 될 서브 로고 URL(크기: 64x13)로 **PC 전용** 파라미터입니다. + **`bypass.logo_2nd`** **string** -**`bypass.P_CARD_OPTION`** **object** + 결제창에 노출 될 서브 로고 URL(크기: 64x13)로 **PC 전용** 파라미터입니다. -**모바일 카드/간편결제 전용** 파라미터입니다. + **`bypass.P_CARD_OPTION`** **object** -1. 신용카드 우선 선택 옵션 + **모바일 카드/간편결제 전용** 파라미터입니다. - 예) selcode=14 + 1. 신용카드 우선 선택 옵션 -- 해당 카드 코드에 해당하는 카드가 선택된 채로 Display -- 간편결제는 불가능 (타 카드 선택 가능) + 예) selcode=14 -2. 선택적 표시 옵션 + - 해당 카드 코드에 해당하는 카드가 선택된 채로 Display + - 간편결제는 불가능 (타 카드 선택 가능) - 예1) onlycard=visa3d - 예2) selcode=14:onlycard=visa3d + 2. 선택적 표시 옵션 -- 안심결제: visa3d -- ISP: isp -- 간편결제: easypay 중 선택 적 표시 + 예1) onlycard=visa3d + 예2) selcode=14:onlycard=visa3d -**`bypass.P_ONLY_EASYPAYCODE`** **string** + - 안심결제: visa3d + - ISP: isp + - 간편결제: easypay 중 선택 적 표시 -카드 결제창 내 렌더링 될 간편 결제 리스트를 의미하며 **모바일 전용** 파라미터입니다. + **`bypass.P_ONLY_EASYPAYCODE`** **string** -예) 카카오페이, 엘페이, 페이코만 렌더링 → -”KAKAOPAY:LPAY:PAYCO” 전달 + 카드 결제창 내 렌더링 될 간편 결제 리스트를 의미하며 **모바일 전용** 파라미터입니다. -- 카카오페이: KAKAOPAY -- 엘페이: LPAY -- 페이코: PAYCO -- 토스페이: TOSSPAY + 예) 카카오페이, 엘페이, 페이코만 렌더링 → + ”KAKAOPAY:LPAY:PAYCO” 전달 -**`bypass.acceptmethod`** **array** + - 카카오페이: KAKAOPAY + - 엘페이: LPAY + - 페이코: PAYCO + - 토스페이: TOSSPAY -**PC - 카드 결제 전용 파라미터** + **`bypass.acceptmethod`** **array** + + **PC - 카드 결제 전용 파라미터** |형식 |설명 | |---------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -275,408 +277,403 @@ IMP.request_pay({ |hppdefaultcorp(통신사 코드)|휴대폰 소액결제시 기본 선택되어있는 통신사
- 기본: 기본 선택되어있는 통신사 없음
예) KT 기본 선택 → ”hppdefaultcorp(KT)” 전달
- SKT: `SKT`
- KT: `KTF`
- LG 유플러스: `LGT`
- 알뜰폰 전체: `MVNO`
- 알뜰폰 CJ 헬로 모바일: `CJH`
- 알뜰폰 티플러스: `KCT`
- 알뜰폰 SK 세븐모바일: `SKL`
| |hppnofix(N 또는 Y) |휴대폰 소액결제창에 자동 입력되는 `buyer_tel`값을 수정할 수 있는지 여부
- 기본값: 수정 가능
- Y : 수정 불가능
- N : 수정 가능(기본)
| -```javascript -// -...중략 -pg: 'welcome', -bypass: { - welcome: { - acceptmethod: [ - "SKIN(#fc6b2d)", // 결제창 배경 색상 #fc6b2d - "below1000", // 1,000원 이하 결제 허용 - "paypopup", // 안심 클릭을 팝업으로 렌더링 - "onlyeasypaycode(kakaopay:payco)", // 카드 결제창 내 간편결제는 카카오페이와 페이코만 렌더링 - "hppdefaultcorp(KT)", // 휴대폰 소액결제시 KT 기본 선택 - "hppnofix(Y)", // 휴대폰 소액결제시 결제 창 내에서 구매자 전화번호 수정 불가능 - ] - } -} -``` - -**`bypass.P_RESERVED`** **array** - -**모바일 - 카드 결제 전용 파라미터** + ```json + //...중략 + pg: "welcome", + bypass: { + welcome: { + acceptmethod: [ + "SKIN(#fc6b2d)", // 결제창 배경 색상 #fc6b2d + "below1000", // 1,000원 이하 결제 허용 + "paypopup", // 안심 클릭을 팝업으로 렌더링 + "onlyeasypaycode(kakaopay:payco)", // 카드 결제창 내 간편결제는 카카오페이와 페이코만 렌더링 + "hppdefaultcorp(KT)", // 휴대폰 소액결제시 KT 기본 선택 + "hppnofix(Y)", // 휴대폰 소액결제시 결제 창 내에서 구매자 전화번호 수정 불가능 + ] + } + } + ``` + + **`bypass.P_RESERVED`** **array** + + **모바일 - 카드 결제 전용 파라미터** |형식 |설명 | |-----------|----------------------------------------------------------| |below1000=Y|1,000원 미만 결제 허용 여부
- 기본값: 허용하지 않음| -**모바일 - 휴대폰 소액 결제 전용 파라미터** + **모바일 - 휴대폰 소액 결제 전용 파라미터** |형식 |설명 | |----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |hpp_default_corp=통신사 코드|휴대폰 소액결제시 기본 선택되어있는 통신사
- 기본: 기본 선택되어있는 통신사 없음
예) KT 기본 선택 → ”hpp_default_corp=KT” 전달
- SKT: `SKT`
- KT: `KTF`
- LG 유플러스: `LGT`
- 알뜰폰 전체: `MVNO`
- 알뜰폰 CJ 헬로 모바일: `CJH`
- 알뜰폰 티플러스: `KCT`
- 알뜰폰 SK 세븐모바일: `SKL`| |hpp_nofix=Y 또는 N |휴대폰 소액결제창에 자동 입력되는 buyer_tel값을 수정할 수 있는지 여부
- 기본: 수정 가능
- Y : 수정 불가능
- N : 수정 가능(기본)
| -```javascript -// -...중략 -pg: 'welcome', -bypass: { - welcome: { - P_RESERVED: [ - "below1000=Y", // 1,000원 이하 결제 허용 - "hpp_default_corp=KT", // 휴대폰 소액결제시 KT 기본 선택 - "hppnofix=Y", // 휴대폰 소액결제시 결제 창 내에서 구매자 전화번호 수정 불가능 - ] - } -} -``` + ```json + //...중략 + pg: "welcome", + bypass: { + welcome: { + P_RESERVED: [ + "below1000=Y", // 1,000원 이하 결제 허용 + "hpp_default_corp=KT", // 휴대폰 소액결제시 KT 기본 선택 + "hppnofix=Y", // 휴대폰 소액결제시 결제 창 내에서 구매자 전화번호 수정 불가능 + ] + } + } + ``` +
-
+
+

+ 웰컴페이먼츠 지원 결제 수단 +

-
-

- 웰컴페이먼츠 지원 결제 수단 -

+ - card + 에스크로, 다이렉트 + - vbank + 에스크로 + - trans + 에스크로 + - phone + - culturegift + - lpay + - kakaopay + - payco + - tosspay +
+ -- card + 에스크로, 다이렉트 -- vbank + 에스크로 -- trans + 에스크로 -- phone -- culturegift -- lpay -- kakaopay -- payco -- tosspay + + 일반 결제 창 호출 파라미터에서 **customer\_uid**, **customer\_id**값을 추가하면 빌링키 발급 창을 호출할 수 있습니다. + 빌링키 발급 창에서 빌링키를 발급 받은 후, 빌링 결제 API를 호출해 해당 빌링키로 결제를 할 수 있습니다. -
+ ```javascript title="Javascript SDK" + IMP.request_pay( + { + pg: "welcome.{MID}", + pay_method: "card", // 빌링키 발급 수단입니다. 웰컴페이먼츠의 경우 'card'만 지원됩니다. + merchant_uid: "orderMonthly0001", // 고객사에서 채번한 주문 고유 번호입니다. + name: "빌링키 발급", + amount: 1000, // 전달한 결제 금액 만큼 실제로 승인되지는 않으며, 단순히 빌링키 발급 창에 표기 용도입니다. + customer_uid: "your-customer-unique-id", // 고객사가 구매자의 결제 수단을 특정하기 위해 채번한 고유 ID로 빌링키 발급시 필수 입력입니다. + customer_id: "matthew", // 고객사가 회원에게 부여한 고유 ID입니다. + buyer_email: "test@portone.io", + buyer_name: "포트원", + buyer_tel: "02-1234-1234", + m_redirect_url: "{모바일에서 빌링키 발급 완료 후 리디렉션 될 URL}", + }, + function (rsp) { + const { imp_uid, merchant_uid } = rsp; - - - - 일반 결제 창 호출 파라미터에서 **customer\_uid**, **customer\_id**값을 추가하면 빌링키 발급 창을 호출할 수 있습니다. - 빌링키 발급 창에서 빌링키를 발급 받은 후, 빌링 결제 API를 호출해 해당 빌링키로 결제를 할 수 있습니다. - ```javascript title="Javascript SDK" - IMP.request_pay({ - pg: "welcome.{MID}", - pay_method: "card", // 빌링키 발급 수단입니다. 웰컴페이먼츠의 경우 'card'만 지원됩니다. - merchant_uid: "orderMonthly0001", // 고객사에서 채번한 주문 고유 번호입니다. - name: "빌링키 발급", - amount: 1000, // 전달한 결제 금액 만큼 실제로 승인되지는 않으며, 단순히 빌링키 발급 창에 표기 용도입니다. - customer_uid: "your-customer-unique-id", // 고객사가 구매자의 결제 수단을 특정하기 위해 채번한 고유 ID로 빌링키 발급시 필수 입력입니다. - customer_id: "matthew", // 고객사가 회원에게 부여한 고유 ID입니다. - buyer_email: "test@portone.io", - buyer_name: "포트원", - buyer_tel: "02-1234-1234", - m_redirect_url: "{모바일에서 빌링키 발급 완료 후 리디렉션 될 URL}", - }, function (rsp) { - const { imp_uid, merchant_uid } = rsp; - - // 콜백 함수로 전달 받은 imp_uid로 포트원 결제 내역 조회 API를 통해 빌링키 발급 상태를 판단합니다. - }); - ``` + // 콜백 함수로 전달 받은 imp_uid로 포트원 결제 내역 조회 API를 통해 빌링키 발급 상태를 판단합니다. + }, + ); + ``` -
-

주요 파라미터 설명

+
+

주요 파라미터 설명

-**`pg`** **\*** **`welcome`** + **`pg`** **\*** **`welcome`** -**PG사 구분코드** + **PG사 구분코드** -**`merchant_uid`** **\*** **string** + **`merchant_uid`** **\*** **string** -**주문 번호** + **주문 번호** -매번 고유하게 채번되어야 합니다. + 매번 고유하게 채번되어야 합니다. -**`amount`** **\*** **`integer`** + **`amount`** **\*** **`integer`** -**결제 금액** + **결제 금액** -**string** 이 아닌 점에 유의하세요. + **string** 이 아닌 점에 유의하세요. -전달한 결제 금액 만큼 실제로 승인되지는 않으며, 단순히 빌링키 발급 창에 표기 용도입니다. + 전달한 결제 금액 만큼 실제로 승인되지는 않으며, 단순히 빌링키 발급 창에 표기 용도입니다. -**`pay_method`** **\*** **`card`** + **`pay_method`** **\*** **`card`** -**빌링키 발급 수단** + **빌링키 발급 수단** -웰컴페이먼츠의 경우, 빌링키 발급 수단은 `card`만 허용되며 **반드시 `card`를 필수로 입력해주셔야** 합니다. + 웰컴페이먼츠의 경우, 빌링키 발급 수단은 `card`만 허용되며 **반드시 `card`를 필수로 입력해주셔야** 합니다. -**`customer_uid`** **\*** **string** + **`customer_uid`** **\*** **string** -**빌링키 발급 수단 고유 ID** + **빌링키 발급 수단 고유 ID** -고객사가 구매자의 빌링키 발급 수단을 특정하기 위해 채번한 고유 번호로 빌링키 발급시 필수 입력입니다. + 고객사가 구매자의 빌링키 발급 수단을 특정하기 위해 채번한 고유 번호로 빌링키 발급시 필수 입력입니다. -**`customer_id`** **string** + **`customer_id`** **string** -**구매자 고유 ID** + **구매자 고유 ID** -고객사가 구매자를 특정하기 위해 채번한 고유 번호입니다. + 고객사가 구매자를 특정하기 위해 채번한 고유 번호입니다. -**`buyer_name`** **\*** **string** + **`buyer_name`** **\*** **string** -**구매자 이름** + **구매자 이름** -주의: 웰컴페이먼츠의 경우 구매자 이름은 필수 입력입니다. + 주의: 웰컴페이먼츠의 경우 구매자 이름은 필수 입력입니다. -**`buyer_tel`** **\*** **string** + **`buyer_tel`** **\*** **string** -**구매자 연락처** + **구매자 연락처** -주의: 웰컴페이먼츠의 경우 구매자 연락처는 필수 입력입니다. + 주의: 웰컴페이먼츠의 경우 구매자 연락처는 필수 입력입니다. -**`buyer_email`** **string** + **`buyer_email`** **string** -**구매자 이메일 주소** + **구매자 이메일 주소** -**`m_redirect_url`** **string** + **`m_redirect_url`** **string** -**모바일 환경에서 트랜잭션 종료 후 302 리디렉션 될 URL** + **모바일 환경에서 트랜잭션 종료 후 302 리디렉션 될 URL** -주의: 웰컴페이먼츠의 경우 **모바일 환경에서 필수 입력**입니다. + 주의: 웰컴페이먼츠의 경우 **모바일 환경에서 필수 입력**입니다. -**`notice_url`** **string** 또는 **string[]** + **`notice_url`** **string** 또는 **string\[]** -**트랜잭션 종료 후 웹훅이 발송 될 고객사 서버 URL** + **트랜잭션 종료 후 웹훅이 발송 될 고객사 서버 URL** -주의: notice_url 파라미터 설정시, 콘솔에 설정 된 웹훅 URL은 override 되며 notice_url에 전달 한 주소로만 웹훅이 발송됩니다. + 주의: notice\_url 파라미터 설정시, 콘솔에 설정 된 웹훅 URL은 override 되며 notice\_url에 전달 한 주소로만 웹훅이 발송됩니다. -**`period`** **object** + **`period`** **object** -**서비스 제공 기간** + **서비스 제공 기간** -(from과 to) 또는 interval 중 하나만 입력 가능합니다. + (from과 to) 또는 interval 중 하나만 입력 가능합니다. -- **`from`**: 서비스 제공 시작 시각 -- **`to`**: 서비스 제공 종료 시각 + - **`from`**: 서비스 제공 시작 시각 - - YYYY-MM-DD - - YYYY-MM-DD HH:mm:ss - - YYYYMMDD - - YYYYMMDDHHmmss + - **`to`**: 서비스 제공 종료 시각 - 웰컴페이먼츠의 경우 + - YYYY-MM-DD + - YYYY-MM-DD HH:mm:ss + - YYYYMMDD + - YYYYMMDDHHmmss - - PC: 날짜까지만 입력 가능하며 시간은 무시됩니다. - - 모바일: 날짜와 시간 모두 입력 가능하며 초는 무시됩니다. + 웰컴페이먼츠의 경우 -- **`interval`**: 서비스 제공 간격 - - 1m: 매월 정기결제 - - 1y: 매년 정기결제 + - PC: 날짜까지만 입력 가능하며 시간은 무시됩니다. + - 모바일: 날짜와 시간 모두 입력 가능하며 초는 무시됩니다. -**`bypass.logo_url`** **string** + - **`interval`**: 서비스 제공 간격 + - 1m: 매월 정기결제 + - 1y: 매년 정기결제 -결제창에 노출 될 메인 로고 URL(크기: 89x19)로 **PC 전용** 파라미터입니다. + **`bypass.logo_url`** **string** -**`bypass.logo_2nd`** **string** + 결제창에 노출 될 메인 로고 URL(크기: 89x19)로 **PC 전용** 파라미터입니다. -결제창에 노출 될 서브 로고 URL(크기: 64x13)로 **PC 전용** 파라미터입니다. + **`bypass.logo_2nd`** **string** -
+ 결제창에 노출 될 서브 로고 URL(크기: 64x13)로 **PC 전용** 파라미터입니다. +
-
-

- 웰컴페이먼츠 지원 빌링키 발급 수단 -

+
+

+ 웰컴페이먼츠 지원 빌링키 발급 수단 +

-- card + - card +
+ -
+ + ```javascript title="Javascript SDK" + IMP.request_pay( + { + pg: "welcome.{상점 ID}", + pay_method: "phone", // 빌링키 발급 및 결제 수단입니다. 웰컴페이먼츠의 경우 'phone'만 지원합니다. + merchant_uid: "orderNo0001", // 고객사에서 채번한 주문 고유 번호입니다. + name: "주문명:결제테스트", + amount: 1000, // 전달한 금액 만큼 실제로 승인이 됩니다. + customer_uid: "your-customer-unique-id", // 고객사가 구매자의 결제 수단을 특정하기 위해 채번한 고유 ID로 빌링키 발급시 필수 입력입니다. + customer_id: "matthew", // 고객사가 회원에게 부여한 고유 ID입니다. + buyer_email: "test@portone.io", + buyer_name: "구매자이름", + buyer_tel: "010-1234-5678", + m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", + }, + function (rsp) { + // callback 로직 + const { imp_uid, merchant_uid } = rsp; - - - -```javascript title="Javascript SDK" -IMP.request_pay({ - pg: 'welcome.{상점 ID}', - pay_method: 'phone', // 빌링키 발급 및 결제 수단입니다. 웰컴페이먼츠의 경우 'phone'만 지원합니다. - merchant_uid: "orderNo0001", // 고객사에서 채번한 주문 고유 번호입니다. - name: '주문명:결제테스트', - amount: 1000, // 전달한 금액 만큼 실제로 승인이 됩니다. - customer_uid: "your-customer-unique-id", // 고객사가 구매자의 결제 수단을 특정하기 위해 채번한 고유 ID로 빌링키 발급시 필수 입력입니다. - customer_id: "matthew", // 고객사가 회원에게 부여한 고유 ID입니다. - buyer_email: 'test@portone.io', - buyer_name: '구매자이름', - buyer_tel: '010-1234-5678', - m_redirect_url: '{모바일에서 결제 완료 후 리디렉션 될 URL}', -}, function(rsp) { // callback 로직 - const { imp_uid, merchant_uid } = rsp; - - // 콜백 함수로 전달 받은 imp_uid로 포트원 결제 내역 조회 API를 통해 결제 상태를 판단합니다. -}); -``` + // 콜백 함수로 전달 받은 imp_uid로 포트원 결제 내역 조회 API를 통해 결제 상태를 판단합니다. + }, + ); + ``` -
-

주요 파라미터 설명

+
+

주요 파라미터 설명

-**`pg`** **\*** **`welcome`** + **`pg`** **\*** **`welcome`** -**PG사 구분코드** + **PG사 구분코드** -**`merchant_uid`** **\*** **string** + **`merchant_uid`** **\*** **string** -**주문 번호** + **주문 번호** -매번 고유하게 채번되어야 합니다. + 매번 고유하게 채번되어야 합니다. -**`amount`** **\*** **`integer`** + **`amount`** **\*** **`integer`** -**결제 금액** + **결제 금액** -**string** 이 아닌 점에 유의하세요. + **string** 이 아닌 점에 유의하세요. -**`pay_method`** **\*** **`phone`** + **`pay_method`** **\*** **`phone`** -**빌링키 발급 및 결제 수단을** + **빌링키 발급 및 결제 수단을** -- phone (휴대폰소액결제) + - phone (휴대폰소액결제) -웰컴페이먼츠의 경우, 빌링키 발급 동시에 결제 수단은 `phone`만 허용되며 **반드시 `phone`을 필수로 입력해주셔야** 합니다. + 웰컴페이먼츠의 경우, 빌링키 발급 동시에 결제 수단은 `phone`만 허용되며 **반드시 `phone`을 필수로 입력해주셔야** 합니다. -**빌링키 발급 수단 고유 ID** + **빌링키 발급 수단 고유 ID** -고객사가 구매자의 빌링키 발급 수단을 특정하기 위해 채번한 고유 번호로 빌링키 발급시 필수 입력입니다. + 고객사가 구매자의 빌링키 발급 수단을 특정하기 위해 채번한 고유 번호로 빌링키 발급시 필수 입력입니다. -**`customer_id`** **string** + **`customer_id`** **string** -**구매자 고유 ID** + **구매자 고유 ID** -고객사가 구매자를 특정하기 위해 채번한 고유 번호입니다. + 고객사가 구매자를 특정하기 위해 채번한 고유 번호입니다. -**`buyer_name`** **\*** **string** + **`buyer_name`** **\*** **string** -**구매자 이름** + **구매자 이름** -주의: 웰컴페이먼츠의 경우 구매자 이름은 필수 입력입니다. + 주의: 웰컴페이먼츠의 경우 구매자 이름은 필수 입력입니다. -**`buyer_tel`** **\*** **string** + **`buyer_tel`** **\*** **string** -**구매자 연락처** + **구매자 연락처** -주의: 웰컴페이먼츠의 경우 구매자 연락처는 필수 입력입니다. + 주의: 웰컴페이먼츠의 경우 구매자 연락처는 필수 입력입니다. -**`buyer_email`** **string** + **`buyer_email`** **string** -**구매자 이메일 주소** + **구매자 이메일 주소** -**`m_redirect_url`** **string** + **`m_redirect_url`** **string** -**모바일 환경에서 트랜잭션 종료 후 302 리디렉션 될 URL** + **모바일 환경에서 트랜잭션 종료 후 302 리디렉션 될 URL** -주의: 웰컴페이먼츠의 경우 **모바일 환경에서 필수 입력**입니다. + 주의: 웰컴페이먼츠의 경우 **모바일 환경에서 필수 입력**입니다. -**`notice_url`** **string** 또는 **string[]** + **`notice_url`** **string** 또는 **string\[]** -**트랜잭션 종료 후 웹훅이 발송 될 고객사 서버 URL** + **트랜잭션 종료 후 웹훅이 발송 될 고객사 서버 URL** -주의: notice_url 파라미터 설정시, 콘솔에 설정 된 웹훅 URL은 override 되며 notice_url에 전달 한 주소로만 웹훅이 발송됩니다. + 주의: notice\_url 파라미터 설정시, 콘솔에 설정 된 웹훅 URL은 override 되며 notice\_url에 전달 한 주소로만 웹훅이 발송됩니다. -**`confirm_url`** **string** + **`confirm_url`** **string** -**트랜잭션 승인 직전 최종 승인 여부를 질의 할 고객사 서버 URL** + **트랜잭션 승인 직전 최종 승인 여부를 질의 할 고객사 서버 URL** -트랜잭션 승인 직전, 포트원 서버에서 confirm_url로 트랜잭션 최종 승인 여부를 질의하게 되며 200 외의 응답을 받은 경우 트랜잭션은 중단됩니다. + 트랜잭션 승인 직전, 포트원 서버에서 confirm\_url로 트랜잭션 최종 승인 여부를 질의하게 되며 200 외의 응답을 받은 경우 트랜잭션은 중단됩니다. -**`currency`** **`KRW`** + **`currency`** **`KRW`** -**결제 통화** + **결제 통화** -웰컴페이먼츠의 경우 KRW만 허용되며, 미 입력시 KRW로 자동 적용됩니다. + 웰컴페이먼츠의 경우 KRW만 허용되며, 미 입력시 KRW로 자동 적용됩니다. -**`digital`** **\*** **string** + **`digital`** **\*** **string** -**실물/컨텐츠 여부** + **실물/컨텐츠 여부** -**`period`** **object** + **`period`** **object** -**서비스 제공 기간** + **서비스 제공 기간** -(from과 to) 또는 interval 중 하나만 입력 가능합니다. + (from과 to) 또는 interval 중 하나만 입력 가능합니다. -주의: **모바일 환경에서는 지원하지 않습니다.** + 주의: **모바일 환경에서는 지원하지 않습니다.** -- **`from`**: 서비스 제공 시작 시각 -- **`to`**: 서비스 제공 종료 시각 + - **`from`**: 서비스 제공 시작 시각 - - YYYY-MM-DD - - YYYY-MM-DD HH:mm:ss - - YYYYMMDD - - YYYYMMDDHHmmss + - **`to`**: 서비스 제공 종료 시각 - 웰컴페이먼츠의 경우 + - YYYY-MM-DD + - YYYY-MM-DD HH:mm:ss + - YYYYMMDD + - YYYYMMDDHHmmss - - PC: 날짜까지만 입력 가능하며 시간은 무시됩니다. - - 모바일: 날짜와 시간 모두 입력 가능하며 초는 무시됩니다. + 웰컴페이먼츠의 경우 -- **`interval`**: 서비스 제공 간격 - - 1m: 매월 정기결제 - - 1y: 매년 정기결제 + - PC: 날짜까지만 입력 가능하며 시간은 무시됩니다. + - 모바일: 날짜와 시간 모두 입력 가능하며 초는 무시됩니다. -**`bypass.acceptmethod`** **array** + - **`interval`**: 서비스 제공 간격 + - 1m: 매월 정기결제 + - 1y: 매년 정기결제 -**PC - 휴대폰 소액 결제 전용 파라미터** + **`bypass.acceptmethod`** **array** + + **PC - 휴대폰 소액 결제 전용 파라미터** |형식 |설명 | |---------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |hppdefaultcorp(통신사 코드)|휴대폰 소액결제시 기본 선택되어있는 통신사
- 기본: 기본 선택되어있는 통신사 없음
예) KT 기본 선택 → ”hppdefaultcorp(KT)” 전달
- SKT: `SKT`
- KT: `KTF`
- LG 유플러스: `LGT`
- 알뜰폰 전체: `MVNO`
- 알뜰폰 CJ 헬로 모바일: `CJH`
- 알뜰폰 티플러스: `KCT`
- 알뜰폰 SK 세븐모바일: `SKL`
| |hppnofix(N 또는 Y) |휴대폰 소액결제창에 자동 입력되는 `buyer_tel`값을 수정할 수 있는지 여부
- 기본값: 수정 가능
- Y : 수정 불가능
- N : 수정 가능(기본)
| -```javascript -// -...중략 -pg: 'welcome', -bypass: { - welcome: { - acceptmethod: [ - "SKIN(#fc6b2d)", // 결제창 배경 색상 #fc6b2d - "below1000", // 1,000원 이하 결제 허용 - "paypopup", // 안심 클릭을 팝업으로 렌더링 - "onlyeasypaycode(kakaopay:payco)", // 카드 결제창 내 간편결제는 카카오페이와 페이코만 렌더링 - "hppdefaultcorp(KT)", // 휴대폰 소액결제시 KT 기본 선택 - "hppnofix(Y)", // 휴대폰 소액결제시 결제 창 내에서 구매자 전화번호 수정 불가능 - ] - } -} -``` - -**`bypass.P_RESERVED`** **array** - -**모바일 - 휴대폰 소액 결제 전용 파라미터** + ```json + //...중략 + pg: "welcome", + bypass: { + welcome: { + acceptmethod: [ + "SKIN(#fc6b2d)", // 결제창 배경 색상 #fc6b2d + "below1000", // 1,000원 이하 결제 허용 + "paypopup", // 안심 클릭을 팝업으로 렌더링 + "onlyeasypaycode(kakaopay:payco)", // 카드 결제창 내 간편결제는 카카오페이와 페이코만 렌더링 + "hppdefaultcorp(KT)", // 휴대폰 소액결제시 KT 기본 선택 + "hppnofix(Y)", // 휴대폰 소액결제시 결제 창 내에서 구매자 전화번호 수정 불가능 + ] + } + } + ``` + + **`bypass.P_RESERVED`** **array** + + **모바일 - 휴대폰 소액 결제 전용 파라미터** |형식 |설명 | |----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |hpp_default_corp=통신사 코드|휴대폰 소액결제시 기본 선택되어있는 통신사
- 기본: 기본 선택되어있는 통신사 없음
예) KT 기본 선택 → ”hpp_default_corp=KT” 전달
- SKT: `SKT`
- KT: `KTF`
- LG 유플러스: `LGT`
- 알뜰폰 전체: `MVNO`
- 알뜰폰 CJ 헬로 모바일: `CJH`
- 알뜰폰 티플러스: `KCT`
- 알뜰폰 SK 세븐모바일: `SKL`| |hpp_nofix=Y 또는 N |휴대폰 소액결제창에 자동 입력되는 buyer_tel값을 수정할 수 있는지 여부
- 기본: 수정 가능
- Y : 수정 불가능
- N : 수정 가능(기본)
| -```javascript -// -...중략 -pg: 'welcome', -bypass: { - welcome: { - P_RESERVED: [ - "below1000=Y", // 1,000원 이하 결제 허용 - "hpp_default_corp=KT", // 휴대폰 소액결제시 KT 기본 선택 - "hppnofix=Y", // 휴대폰 소액결제시 결제 창 내에서 구매자 전화번호 수정 불가능 - ] - } -} -``` - -
+ ```json + //...중략 + pg: "welcome", + bypass: { + welcome: { + P_RESERVED: [ + "below1000=Y", // 1,000원 이하 결제 허용 + "hpp_default_corp=KT", // 휴대폰 소액결제시 KT 기본 선택 + "hppnofix=Y", // 휴대폰 소액결제시 결제 창 내에서 구매자 전화번호 수정 불가능 + ] + } + } + ``` +
+ +
+

+ 웰컴페이먼츠 지원 빌링키 발급과 동시에 결제 수단 +

+ + - phone +
+ +

- 웰컴페이먼츠 지원 빌링키 발급과 동시에 결제 수단 + 가능한 트랜잭션 환경

-- phone - -
- - - - - -
-

- 가능한 트랜잭션 환경 -

- -- PC (iframe) -- 모바일 (리디렉션) - + - PC (iframe) + - 모바일 (리디렉션)
diff --git a/src/content/docs/ko/pg/simple/kakopay.mdx b/src/content/docs/ko/pg/simple/kakopay.mdx index 9f384a0bf..29866ca18 100644 --- a/src/content/docs/ko/pg/simple/kakopay.mdx +++ b/src/content/docs/ko/pg/simple/kakopay.mdx @@ -3,19 +3,19 @@ title: 카카오페이 description: 카카오페이 연동 방법을 안내합니다. --- -import Codepen from "~/components/gitbook/Codepen.astro"; import Figure from "~/components/Figure.astro"; -import Hint from "~/components/Hint.astro"; -import Tabs from "~/components/gitbook/tabs/Tabs.astro"; +import Codepen from "~/components/gitbook/Codepen.astro"; import Tab from "~/components/gitbook/tabs/Tab.astro"; +import Tabs from "~/components/gitbook/tabs/Tabs.astro"; +import Hint from "~/components/Hint.astro"; -### 1. 카카오페이 채널 설정하기 +## 1. 카카오페이 채널 설정하기 [결제대행사 채널 설정하기](../../ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다.
-### 2.결제 요청하기 +## 2.결제 요청하기 [JavaScript SDK](../../sdk/javascript-sdk-old/readme) `IMP.request_pay(param, callback)`을 호출하여 카카오페이 결제창을 호출할 수 있습니다. **결제결과**는 PC의 경우 `IMP.request_pay(param, callback)` @@ -23,140 +23,139 @@ import Tab from "~/components/gitbook/tabs/Tab.astro"; 모바일의 경우 **`m_redirect_url`** 로 리디렉션됩니다. - -```javascript title="Javascript SDK" -IMP.request_pay({ - pg: "kakaopay.{CID}", - pay_method: "card", // 생략가 - merchant_uid: "order_no_0001", // 상점에서 생성한 고유 주문번호 - name: "주문명:결제테스트", - amount: 1004, - buyer_email: "test@portone.io", - buyer_name: "구매자이름", - buyer_tel: "010-1234-5678", - buyer_addr: "서울특별시 강남구 삼성동", - buyer_postcode: "123-456", - m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}" -}, function (rsp) { // callback 로직 - /* ...중략... */ -}); -``` + + ```javascript title="Javascript SDK" + IMP.request_pay( + { + pg: "kakaopay.{CID}", + pay_method: "card", // 생략가 + merchant_uid: "order_no_0001", // 상점에서 생성한 고유 주문번호 + name: "주문명:결제테스트", + amount: 1004, + buyer_email: "test@portone.io", + buyer_name: "구매자이름", + buyer_tel: "010-1234-5678", + buyer_addr: "서울특별시 강남구 삼성동", + buyer_postcode: "123-456", + m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", + }, + function (rsp) { + // callback 로직 + /* ...중략... */ + }, + ); + ``` -**주요 파라미터 설명** + **주요 파라미터 설명** -**`pg`** **string** + **`pg`** **string** -**PG사 구분코드** + **PG사 구분코드** -**`kakaopay`** 로 지정하면 됩니다. + **`kakaopay`** 로 지정하면 됩니다. -**`pay_method`** **string** + **`pay_method`** **string** -**결제수단 구분코드** + **결제수단 구분코드** -생략가능 + 생략가능 -(호출 시 선택된 값은 무시되며 카카오페이 앱에서 신용카드와 카카오머니 중 선택한 옵션으로 설정됩니다.) + (호출 시 선택된 값은 무시되며 카카오페이 앱에서 신용카드와 카카오머니 중 선택한 옵션으로 설정됩니다.) -**`merchant_uid`** **\*** **string** + **`merchant_uid`** **\*** **string** -**주문번호** + **주문번호** -매번 고유하게 채번되어야 합니다. + 매번 고유하게 채번되어야 합니다. -**`amount`** **integer** + **`amount`** **integer** -**결제금액** + **결제금액** -**string** 이 아닌점에 유의하세요 + **string** 이 아닌점에 유의하세요 - + + - + + 인증결제창 호출 파라미터에서 **customer\_uid** 값을 추가하면 정기결제창을 호출할 수 있습니다. - -인증결제창 호출 파라미터에서 **customer\_uid** 값을 추가하면 정기결제창을 호출할 수 있습니다. + + **amount 금액** - -**amount 금액** + 카카오페이 간편결제는 빌링키 발급시 amount 파라미터에 금액이 설정되는 경우 **실 결제와 동시에 빌링키가 발급**됩니다. -카카오페이 간편결제는 빌링키 발급시 amount 파라미터에 금액이 설정되는 경우 **실 결제와 동시에 빌링키가 발급**됩니다. + 실결제를 원하지 않은 경우 amount 금액을 **0원**으로 설정합니다. + -실결제를 원하지 않은 경우 amount 금액을 **0원**으로 설정합니다. + ```javascript title="Javascript SDK" + IMP.request_pay( + { + pg: "kakaopay.{CID}", + merchant_uid: "order_monthly_0001", // 상점에서 관리하는 주문 번호 + name: "최초인증결제", + amount: 0, // 결제창에 표시될 금액. 실제 승인이 이뤄지지는 않습니다. + customer_uid: "your-customer-unique-id", // 필수 입력. + buyer_email: "test@portone.io", + buyer_name: "포트원", + buyer_tel: "02-1234-1234", + m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", + }, + function (rsp) { + if (rsp.success) { + alert("빌링키 발급 성공"); + } else { + alert("빌링키 발급 실패"); + } + }, + ); + ``` - - -```javascript title="Javascript SDK" -IMP.request_pay( - { - pg: "kakaopay.{CID}", - merchant_uid: "order_monthly_0001", // 상점에서 관리하는 주문 번호 - name: "최초인증결제", - amount: 0, // 결제창에 표시될 금액. 실제 승인이 이뤄지지는 않습니다. - customer_uid: "your-customer-unique-id", // 필수 입력. - buyer_email: "test@portone.io", - buyer_name: "포트원", - buyer_tel: "02-1234-1234", - m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", - }, - function (rsp) { - if (rsp.success) { - alert("빌링키 발급 성공"); - } else { - alert("빌링키 발급 실패"); - } - } -); -``` - -**주요 파라미터 설명** + **주요 파라미터 설명** -**`pg`** **string** + **`pg`** **string** -**PG사 구분코드** + **PG사 구분코드** -**`kakaopay`** 로 지정하면 됩니다. + **`kakaopay`** 로 지정하면 됩니다. -**`customer_uid`** **string** + **`customer_uid`** **string** -**카드 빌링키** + **카드 빌링키** -비 인증 결제창에서 고객이 입력한 카드정보와 1:1로 매칭될 빌링키를 지정합니다. + 비 인증 결제창에서 고객이 입력한 카드정보와 1:1로 매칭될 빌링키를 지정합니다. -**`amount`** **Integer** + **`amount`** **Integer** -**결제금액** + **결제금액** -결제창에 표시될 금액으로 0원 이상 설정시 실 결제가 발생됩니다. + 결제창에 표시될 금액으로 0원 이상 설정시 실 결제가 발생됩니다. -(실 결제를 원하지 않은 경우 amount 금액을 0원으로 설정합니다.) + (실 결제를 원하지 않은 경우 amount 금액을 0원으로 설정합니다.) -**빌링키(customer_uid)로 결제 요청하기** + **빌링키(customer\_uid)로 결제 요청하기** -빌링키 발급이 성공하면 실 빌링키는 customer_uid 와 1:1 매칭되어 **포트원 서버에 저장**됩니다. customer_uid를 고객사 내부서버에 저장하시고 [**비 인증 결제요청 REST API**](../../api/api-4/api)를 호출하시면 결제를 발생시킬 수 있습니다. + 빌링키 발급이 성공하면 실 빌링키는 customer\_uid 와 1:1 매칭되어 **포트원 서버에 저장**됩니다. customer\_uid를 고객사 내부서버에 저장하시고 [**비 인증 결제요청 REST API**](../../api/api-4/api)를 호출하시면 결제를 발생시킬 수 있습니다. -```sh title="server-side" -curl -H "Content-Type: application/json" \ - -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "amount":3000}' \ - https://api.iamport.kr/subscribe/payments/again -``` - - + ```sh title="server-side" + curl -H "Content-Type: application/json" \ + -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "amount":3000}' \ + https://api.iamport.kr/subscribe/payments/again + ``` + -#### 참고사항 - -- 카카오페이 결제버튼이 노출되는 것을 권장 합니다. -- 카카오페이 고객사 사이니지 이미지를 [다운받아](https://biz.kakaopay.com/online/guide) 활용할 수 있습니다. + ## 참고사항 -
+ - 카카오페이 결제버튼이 노출되는 것을 권장 합니다. + - 카카오페이 고객사 사이니지 이미지를 [다운받아](https://biz.kakaopay.com/online/guide) 활용할 수 있습니다. -
+
+
-**카카오페이 간편결제는 스마트폰 카카오 앱상에서 진행됩니다.** - + **카카오페이 간편결제는 스마트폰 카카오 앱상에서 진행됩니다.** diff --git a/src/content/docs/ko/pg/simple/naver.mdx b/src/content/docs/ko/pg/simple/naver.mdx index 6a44c5188..e68de907e 100644 --- a/src/content/docs/ko/pg/simple/naver.mdx +++ b/src/content/docs/ko/pg/simple/naver.mdx @@ -3,436 +3,444 @@ title: 네이버페이(결제형) description: 네이버페이 결제형 연동 방법을 안내합니다. --- -import Details from "~/components/gitbook/Details.astro"; import Figure from "~/components/Figure.astro"; -import Hint from "~/components/Hint.astro"; -import Tabs from "~/components/gitbook/tabs/Tabs.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"; -### 1. 네이버페이 채널 설정하기 +## 1. 네이버페이 채널 설정하기 [결제대행사 채널 설정하기](../../ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 PG 설정을 진행합니다.
-### 2.결제 요청하기 +## 2.결제 요청하기 [JavaScript SDK](../../sdk/javascript-sdk-old/readme) `IMP.request_pay(param, callback)`을 호출하여 -네이버페이 결제형 결제창을 호출할 수 있습니다. **결제결과**는 PC의 경우 IMP.request_pay(param, +네이버페이 결제형 결제창을 호출할 수 있습니다. **결제결과**는 PC의 경우 IMP.request\_pay(param, callback) 호출 후 **callback** 으로 수신 되며 -모바일의 경우 **m_redirect_url** 로 리디렉션됩니다. +모바일의 경우 **m\_redirect\_url** 로 리디렉션됩니다. - -```javascript title="Javascript SDK" -IMP.request_pay({ - pg: "naverpay.{파트너 ID}", - merchant_uid: "order_no_0001", // 상점에서 관리하는 주문 번호 - name: "주문명:결제테스트", - amount: 1004, - buyer_email: "test@portone.io", - buyer_name: "구매자이름", - buyer_tel: "010-1234-5678", - buyer_addr: "서울특별시 강남구 삼성동", - buyer_postcode: "123-456", - naverUseCfm: "20221231", // 이용완료일자(필요시 설정합니다) - naverPopupMode: true, // 팝업모드 활성화 - m_redirect_url: "{결제 완료 후 리디렉션 될 URL}", - naverPurchaserName: "구매자이름", - naverPurchaserBirthday: "20151201", - naverChainId: "sAMplEChAINid", - naverMerchantUserKey: "고객사의 사용자 키", - naverCultureBenefit:true // 문화비 소득공제 적용여부 - naverProducts: [ - { - "categoryType": "BOOK", - "categoryId": "GENERAL", - "uid": "107922211", - "name": "한국사", - "payReferrer": "NAVER_BOOK", - "sellerId": "sellerA", - "count": 10 - }, - { - "categoryType": "MUSIC", - "categoryId": "CD", - "uid": "299911002", - "name": "러블리즈", - "payReferrer": "NAVER_BOOK", - "sellerId": "sellerB", - "count": 1 - } - ] -}, function (rsp) { // callback 로직 - /* ...중략... */ -}); -``` - -**주요 파라미터 설명** - -**`pg`** **string** + + ```javascript title="Javascript SDK" + IMP.request_pay( + { + pg: "naverpay.{파트너 ID}", + merchant_uid: "order_no_0001", // 상점에서 관리하는 주문 번호 + name: "주문명:결제테스트", + amount: 1004, + buyer_email: "test@portone.io", + buyer_name: "구매자이름", + buyer_tel: "010-1234-5678", + buyer_addr: "서울특별시 강남구 삼성동", + buyer_postcode: "123-456", + naverUseCfm: "20221231", // 이용완료일자(필요시 설정합니다) + naverPopupMode: true, // 팝업모드 활성화 + m_redirect_url: "{결제 완료 후 리디렉션 될 URL}", + naverPurchaserName: "구매자이름", + naverPurchaserBirthday: "20151201", + naverChainId: "sAMplEChAINid", + naverMerchantUserKey: "고객사의 사용자 키", + naverCultureBenefit: true, // 문화비 소득공제 적용여부 + naverProducts: [ + { + categoryType: "BOOK", + categoryId: "GENERAL", + uid: "107922211", + name: "한국사", + payReferrer: "NAVER_BOOK", + sellerId: "sellerA", + count: 10, + }, + { + categoryType: "MUSIC", + categoryId: "CD", + uid: "299911002", + name: "러블리즈", + payReferrer: "NAVER_BOOK", + sellerId: "sellerB", + count: 1, + }, + ], + }, + function (rsp) { + // callback 로직 + /* ...중략... */ + }, + ); + ``` -**PG사 구분코드** + **주요 파라미터 설명** -`naverpay` 로 지정하면 됩니다. + **`pg`** **string** -\ -**`merchant_uid`** **\*** **string** + **PG사 구분코드** -**주문번호** + `naverpay` 로 지정하면 됩니다. -매번 고유하게 채번되어야 합니다. + \ + **`merchant_uid`** **\*** **string** -\ -**`amount`** **integer** + **주문번호** -**결제금액** + 매번 고유하게 채번되어야 합니다. -**string** 이 아닌점에 유의하세요 + \ + **`amount`** **integer** -\ -**`naverUseCfm`** **string** + **결제금액** -**이용 완료일** (`yyyyMMdd` 형식의 문자열로 **결제 당일 또는 미래의 일자**여야 함) + **string** 이 아닌점에 유의하세요 -- 상품 유형에 따라 네이버페이-고객사 간 필수값으로 계약되는 경우 입력합니다 + \ + **`naverUseCfm`** **string** -\ -**`name`** **\*** **string** + **이용 완료일** (`yyyyMMdd` 형식의 문자열로 **결제 당일 또는 미래의 일자**여야 함) -**제품명** + - 상품 유형에 따라 네이버페이-고객사 간 필수값으로 계약되는 경우 입력합니다 -네이버페이 내부적으로 `외 2개` 의 표현이 자동생성되므로 `xxxx 외 2개` 대신`naverProducts[0].name`(첫번째 상품명)으로 설정하길 권장합니다. + \ + **`name`** **\*** **string** + + **제품명** + + 네이버페이 내부적으로 `외 2개` 의 표현이 자동생성되므로 `xxxx 외 2개` 대신`naverProducts[0].name`(첫번째 상품명)으로 설정하길 권장합니다. + + \ + **`naverPopupMode`** **boolean** + + **결제창 팝업여부** + + `false`인 경우 페이지 리디렉션 방식으로 진행되며 `m_redirect_url`을 설정해야 합니다 + + \ + **`m_redirect_url`** **string** + + **리다이렉트 URL** + + 리디렉션 방식으로 진행(`naverPopupMode: false`)할 경우 결제 완료 후 리디렉션 될 URL + + \ + **`naverPurchaserName`** **string** + + **구매자 이름** -\ -**`naverPopupMode`** **boolean** + 결제 상품이 고위험 업종에 해당하여 네이버페이 계약 당시 별도의 안내를 받은 **대상 고객사만 필수 입력**합니다. -**결제창 팝업여부** + \ + **`naverPurchaserBirthday`** **string** -`false`인 경우 페이지 리디렉션 방식으로 진행되며 `m_redirect_url`을 설정해야 합니다 + **구매자 생년월일(yyyyMMdd)** -\ -**`m_redirect_url`** **string** + 결제 상품이 고위험 업종에 해당하여 네이버페이 계약 당시 별도의 안내를 받은 **대상 고객사만 필수 입력**합니다. -**리다이렉트 URL** + \ + **`naverProducts`** **\*** **array** -리디렉션 방식으로 진행(`naverPopupMode: false`)할 경우 결제 완료 후 리디렉션 될 URL + **상품정보** -\ -**`naverPurchaserName`** **string** + 네이버페이 매뉴얼의 **`productItems`** 파라미터와 동일합니다. -**구매자 이름** + (해당 파라미터 누락시 네이버페이 검수를 통과할 수 없습니다.) -결제 상품이 고위험 업종에 해당하여 네이버페이 계약 당시 별도의 안내를 받은 **대상 고객사만 필수 입력**합니다. + > `naverProducts`는 다음 6개의 속성으로 하나의 상품 정보를 표현하는 객체의 배열입니다. + > + > - **`categoryType`** (필수) : [공식 매뉴얼](https://developer.pay.naver.com/docs/v2/api#etc-etc_product) 참고 + > + > - **`categoryId`** (필수) : [공식 매뉴얼](https://developer.pay.naver.com/docs/v2/api#etc-etc_product) 참고 + > + > - **`uid`** (필수) : 고객사 내부의 상품 고유 ID를 활용하는 것이 일반적이지만, 네이버페이 가이드 참고가 필요합니다. [공식 매뉴얼](https://developer.pay.naver.com/docs/v2/api#etc-etc_product) + > + > - **`name`** (필수) : 주문상품의 명칭 + > + > - **`count`** (필수) : 상품 주문 개수 + > + > - **`sellerId`** (선택) : 고객사가 하위 판매자를 식별하기 위한 고유 ID(영문 대소문자 및 숫자 허용) + > 고객사의 업종이 통신판매중개업에 해당하여 네이버페이 계약 당시 별도의 안내를 받은 대상 고객사만 필수 입력합니다. 비대상 고객사는 입력하지 않습니다. + > + > - **`payReferrer`** (선택) : 네이버 플랫폼의 타 서비스와 제휴계약 후 유입분석을 진행하는 경우에만 입력 [공식 매뉴얼](https://developer.pay.naver.com/docs/v2/api#etc-etc_product_ref) + > -\ -**`naverPurchaserBirthday`** **string** + \ + **`naverChainId`** **string** -**구매자 생년월일(yyyyMMdd)** + **네이버페이 그룹형 가맹점용 chain id** -결제 상품이 고위험 업종에 해당하여 네이버페이 계약 당시 별도의 안내를 받은 **대상 고객사만 필수 입력**합니다. + - 같은 파트너 ID로 두개 이상의 서비스를 운영하는 그룹형 가맹점의 경우에만 네이버페이로부터 전달받은 값을 필수 입력합니다. + - 비 대상 고객사는 입력하지 않습니다. -\ -**`naverProducts`** **\*** **array** + \ + **`naverCultureBenefit`** **boolean** -**상품정보** + **네이버페이 도서/공연 소득공제** -네이버페이 매뉴얼의 **`productItems`** 파라미터와 동일합니다. + 도서/공연 소득공제가 필요한 경우 해당 파라미터를 설정합니다. -(해당 파라미터 누락시 네이버페이 검수를 통과할 수 없습니다.) + \ + **`naverMerchantUserKey`** **string** -> `naverProducts`는 다음 6개의 속성으로 하나의 상품 정보를 표현하는 객체의 배열입니다. -> -> - **`categoryType`** (필수) : [공식 매뉴얼](https://developer.pay.naver.com/docs/v2/api#etc-etc_product) 참고 -> - **`categoryId`** (필수) : [공식 매뉴얼](https://developer.pay.naver.com/docs/v2/api#etc-etc_product) 참고 -> - **`uid`** (필수) : 고객사 내부의 상품 고유 ID를 활용하는 것이 일반적이지만, 네이버페이 가이드 참고가 필요합니다. [공식 매뉴얼](https://developer.pay.naver.com/docs/v2/api#etc-etc_product) -> - **`name`** (필수) : 주문상품의 명칭 -> - **`count`** (필수) : 상품 주문 개수 -> - **`sellerId`** (선택) : 고객사가 하위 판매자를 식별하기 위한 고유 ID(영문 대소문자 및 숫자 허용) -> - 고객사의 업종이 통신판매중개업에 해당하여 네이버페이 계약 당시 별도의 안내를 받은 대상 고객사만 필수 입력합니다. -> - 비대상 고객사는 입력하지 않습니다. -> - **`payReferrer`** (선택) : 네이버 플랫폼의 타 서비스와 제휴계약 후 유입분석을 진행하는 경우에만 입력 [공식 매뉴얼](https://developer.pay.naver.com/docs/v2/api#etc-etc_product_ref) + **고객사의 사용자 키** -\ -**`naverChainId`** **string** + - 개인 아이디와 같은 개인정보 데이터는 제외하여 전달해야 합니다. + - 네이버페이 기준 **고위험군 제품을 판매하는 고객사의 경우 필수** 입력합니다. + - 비 대상 고객사는 입력하지 않습니다. + -**네이버페이 그룹형 가맹점용 chain id** + + **빌링키 발급받기** -- 같은 파트너 ID로 두개 이상의 서비스를 운영하는 그룹형 가맹점의 경우에만 네이버페이로부터 전달받은 값을 필수 입력합니다. -- 비 대상 고객사는 입력하지 않습니다. + ```javascript title="JavaScript SDK" + IMP.request_pay( + { + pg: "naverpay.{파트너 ID}", + customer_uid: "gildong_0001_1234", // 빌링, 필수 입력. + merchant_uid: "order_monthly_0001", // 상점에서 생성한 고유 주문번호 + name: "Slim 요금제(1개월 단위)", + amount: 1004, // 실 결제는 발생되지 않습니다. + buyer_email: "test@portone.io", + buyer_name: "구매자이름", + buyer_tel: "010-1234-5678", // 필수 입력. + buyer_addr: "서울특별시 강남구 삼성동", + buyer_postcode: "123-456", + naverProductCode: "반복결제 상품코드", + naverProductCount: 5, + naverPopupMode: true, // 팝업모드 활성화 + m_redirect_url: "{등록 완료 후 리디렉션 될 URL}", + }, + function (rsp) { + // callback 로직 + /* ...중략... */ + }, + ); + ``` -\ -**`naverCultureBenefit`** **boolean** - -**네이버페이 도서/공연 소득공제** - -도서/공연 소득공제가 필요한 경우 해당 파라미터를 설정합니다. - -\ -**`naverMerchantUserKey`** **string** - -**고객사의 사용자 키** - -- 개인 아이디와 같은 개인정보 데이터는 제외하여 전달해야 합니다. -- 네이버페이 기준 **고위험군 제품을 판매하는 고객사의 경우 필수** 입력합니다. -- 비 대상 고객사는 입력하지 않습니다. - - - - -**빌링키 발급받기** - -```javascript title="JavaScript SDK" -IMP.request_pay( - { - pg: "naverpay.{파트너 ID}", - customer_uid: "gildong_0001_1234", // 빌링, 필수 입력. - merchant_uid: "order_monthly_0001", // 상점에서 생성한 고유 주문번호 - name: "Slim 요금제(1개월 단위)", - amount: 1004, // 실 결제는 발생되지 않습니다. - buyer_email: "test@portone.io", - buyer_name: "구매자이름", - buyer_tel: "010-1234-5678", // 필수 입력. - buyer_addr: "서울특별시 강남구 삼성동", - buyer_postcode: "123-456", - naverProductCode: "반복결제 상품코드", - naverProductCount: 5, - naverPopupMode: true, // 팝업모드 활성화 - m_redirect_url: "{등록 완료 후 리디렉션 될 URL}", - }, - function (rsp) { - // callback 로직 - /* ...중략... */ - } -); -``` + **주요 파라미터 설명** -**주요 파라미터 설명** + **`pg`** **string** -**`pg`** **string** + **PG사 구분코드** -**PG사 구분코드** + `naverpay` 로 지정하면 됩니다. -`naverpay` 로 지정하면 됩니다. + \ + **`customer_uid`** **\*** **string** -\ -**`customer_uid`** **\*** **string** + **빌링키** -**빌링키** + - 정기/반복 결제 등록을 위해서 지정해야 합니다. 미 지정 시, 일반결제로 진행됩니다. + - 등록 후 해당 키를 사용해 반복결제 승인을 요청할 수 있습니다. -- 정기/반복 결제 등록을 위해서 지정해야 합니다. 미 지정 시, 일반결제로 진행됩니다. -- 등록 후 해당 키를 사용해 반복결제 승인을 요청할 수 있습니다. + \ + **`merchant_uid`** **\*** **string** -\ -**`merchant_uid`** **\*** **string** + **주문번호** -**주문번호** + 매번 고유하게 채번되어야 합니다. -매번 고유하게 채번되어야 합니다. + \ + **`amount`** **integer** -\ -**`amount`** **integer** + **결제금액** -**결제금액** + **string** 이 아닌점에 유의하세요 -**string** 이 아닌점에 유의하세요 + **정기/반복 결제 등록과정에서는 ****결제승인이 이뤄지지 않습니다****.** -**정기/반복 결제 등록과정에서는 ****결제승인이 이뤄지지 않습니다****.** + \ + **`naverProductCode`** **\*** **string** -\ -**`naverProductCode`** **\*** **string** + **고객사의 상품코드** -**고객사의 상품코드** + - 동일한 고객이 동일상품에 대해 중복으로 반복결제 등록하는 것을 방지하기 위한 파라미터입니다. + - 기본값은 random으로 자동 생성되어 중복결제가 가능하므로 값을 지정해 주세요. -- 동일한 고객이 동일상품에 대해 중복으로 반복결제 등록하는 것을 방지하기 위한 파라미터입니다. -- 기본값은 random으로 자동 생성되어 중복결제가 가능하므로 값을 지정해 주세요. + \ + **`naverProductCount`** **integer** -\ -**`naverProductCount`** **integer** + **결제대상 상품 수** -**결제대상 상품 수** + \ + **`name`** **\*** **string** -\ -**`name`** **\*** **string** + **제품명** -**제품명** + 네이버페이 내부적으로 **`외 2개`** 의 표현이 자동생성되므로 **"`xxxx 외 2개"`** 대신`naverProducts[0].name`(첫번째 상품명)으로 설정하길 권장합니다. -네이버페이 내부적으로 **`외 2개`** 의 표현이 자동생성되므로 **"`xxxx 외 2개"`** 대신`naverProducts[0].name`(첫번째 상품명)으로 설정하길 권장합니다. + \ + **`naverPopupMode`** **boolean** -\ -**`naverPopupMode`** **boolean** + **결제창 팝업여부** -**결제창 팝업여부** + `false`인 경우 페이지 리디렉션 방식으로 진행되며 `m_redirect_url`을 설정해야 합니다 -`false`인 경우 페이지 리디렉션 방식으로 진행되며 `m_redirect_url`을 설정해야 합니다 + \ + **`m_redirect_url`** **string** -\ -**`m_redirect_url`** **string** + **리다이렉트 URL** -**리다이렉트 URL** + 리디렉션 방식으로 진행(`naverPopupMode`: **false**)할 경우 결제 완료 후 리디렉션 될 URL -리디렉션 방식으로 진행(`naverPopupMode`: **false**)할 경우 결제 완료 후 리디렉션 될 URL + \ + **`naverActionType`** **string** -\ -**`naverActionType`** **string** + **신규 등록/수단 변경 여부** -**신규 등록/수단 변경 여부** + 네이버페이를 통해 발급한 빌링키의 결제 수단을 변경하고자 하는 경우 포트원 빌링키인 `customer_uid`를 동일하게 입력하고, `naverActionType` 파라미터를 `CHANGE`로 입력하여 빌링키를 재발급해야 합니다. -네이버페이를 통해 발급한 빌링키의 결제 수단을 변경하고자 하는 경우 포트원 빌링키인 `customer_uid`를 동일하게 입력하고, `naverActionType` 파라미터를 `CHANGE`로 입력하여 빌링키를 재발급해야 합니다. + `naverActionType` 파라미터를 이용하지 않고 동일한 고객의 정보로 추가 빌링키를 발급 시도하면 이전의 결제 수단 정보가 구매자의 네이버페이 계정에 그대로 남아있어 문제가 발생할 수 있습니다. -`naverActionType` 파라미터를 이용하지 않고 동일한 고객의 정보로 추가 빌링키를 발급 시도하면 이전의 결제 수단 정보가 구매자의 네이버페이 계정에 그대로 남아있어 문제가 발생할 수 있습니다. + - `NEW`(default) : 신규 등록 + - `CHANGE` 결제 수단 변경 -- `NEW`(default) : 신규 등록 -- `CHANGE` 결제 수단 변경 + **결제요청하기** -**결제요청하기** + 빌링키 발급이 완료되면 설정한 **`customer_uid`** 를 이용하여 결제승인 API를 호출하여 결제를 요청하거나 결제를 예약할 수 있습니다 -빌링키 발급이 완료되면 설정한 **`customer_uid`** 를 이용하여 결제승인 API를 호출하여 결제를 요청하거나 결제를 예약할 수 있습니다 + **결제 요청방법** -**결제 요청방법** + REST API [**/subscribe/payments/again**](../../api/api-4/api) 를 호출하여 결제를 요청할 수 있습니다. -REST API [**/subscribe/payments/again**](../../api/api-4/api) 를 호출하여 결제를 요청할 수 있습니다. + - `customer_uid`: 정기/반복결제 등록 시 사용된 해당 고객의 `customer_uid` + - `merchant_uid`: 고객사 주문번호 + - `amount`: 결제승인 요청금액 (결제고객 등록 시 지정된 금액과 달라도 무방함) + - `tax_free`: `amount` 중 면세공급가액 (기본값: 0) + - `name`: 주문의 명칭 + - `extra.naverUseCfm`: 이용 완료일(yyyyMMdd 형식의 문자열로 결제 당일 또는 미래의 일자여야 함) 상품 유형에 따라, 네이버페이-고객사 간 필수값으로 계약되는 경우 입력합니다. -- `customer_uid`: 정기/반복결제 등록 시 사용된 해당 고객의 `customer_uid` -- `merchant_uid`: 고객사 주문번호 -- `amount`: 결제승인 요청금액 (결제고객 등록 시 지정된 금액과 달라도 무방함) -- `tax_free`: `amount` 중 면세공급가액 (기본값: 0) -- `name`: 주문의 명칭 -- `extra.naverUseCfm`: 이용 완료일(yyyyMMdd 형식의 문자열로 결제 당일 또는 미래의 일자여야 함) 상품 유형에 따라, 네이버페이-고객사 간 필수값으로 계약되는 경우 입력합니다. + ```json title="sample json" + { + "customer_uid": "gildong_0001_1234", + "merchant_uid": "order_monthly_0002", //재사용 불가 + "amount": 10000, + "name": "Slim 요금제(최초과금)", + "extra": { + "naverUseCfm": "20201001" + } + } + ``` -```json title="sample json" -{ - "customer_uid": "gildong_0001_1234", - "merchant_uid": "order_monthly_0002", //재사용 불가 - "amount": 10000, - "name": "Slim 요금제(최초과금)", - "extra": { - "naverUseCfm": "20201001" - } -} -``` + ```title="form-urlencoded" + customer_uid={고객사의 결제 고객을 특정하는 Unique Key}&merchant_uid={고객사 주문번호}&amount=10000&name=Slim 요금제(최초과금)&extra[naverUseCfm]=20201001 + ``` -```title="form-urlencoded" -customer_uid={고객사의 결제 고객을 특정하는 Unique Key}&merchant_uid={고객사 주문번호}&amount=10000&name=Slim 요금제(최초과금)&extra[naverUseCfm]=20201001 -``` + **결제 예약방법** -**결제 예약방법** + REST API[**/subscribe/payments/schedule**](../../api/api-3/api)를 호출하여 결제예약을 할 수 있습니다. -REST API[ **/subscribe/payments/schedule**](../../api/api-3/api)를 호출하여 결제예약을 할 수 있습니다. + - `customer_uid` : 정기/반복결제 등록 시 사용된 해당 고객의 `customer_uid` -- `customer_uid` : 정기/반복결제 등록 시 사용된 해당 고객의 `customer_uid` -- `schedules` : 결제 예약 정보 객체 배열(1개 이상 설정 가능) - - `merchant_uid` : 고객사 주문번호 - - `schedule_at` : 결제요청 예약시각 (UNIX timestamp) - - `amount` : 결제승인 요청금액 (결제고객 등록 시 지정된 금액과 달라도 무방함) - - `extra.naverUseCfm` : 이용 완료일(yyyyMMdd 형식의 문자열로 결제 당일 또는 미래의 일자여야 함) 상품 유형에 따라, 네이버페이-고객사 간 필수값으로 계약되는 경우 입력합니다. + - `schedules` : 결제 예약 정보 객체 배열(1개 이상 설정 가능) + - `merchant_uid` : 고객사 주문번호 + - `schedule_at` : 결제요청 예약시각 (UNIX timestamp) + - `amount` : 결제승인 요청금액 (결제고객 등록 시 지정된 금액과 달라도 무방함) + - `extra.naverUseCfm` : 이용 완료일(yyyyMMdd 형식의 문자열로 결제 당일 또는 미래의 일자여야 함) 상품 유형에 따라, 네이버페이-고객사 간 필수값으로 계약되는 경우 입력합니다. -```json title="sample json" -{ - "customer_uid": "gildong_0001_1234", - "schedules": [ + ```json title="sample json" { - "merchant_uid": "order_monthly_0003", //재사용 불가 - "schedule_at": 1519862400, - "amount": 10000, - "extra": { - "naverUseCfm": "20201001" - } + "customer_uid": "gildong_0001_1234", + "schedules": [ + { + "merchant_uid": "order_monthly_0003", //재사용 불가 + "schedule_at": 1519862400, + "amount": 10000, + "extra": { + "naverUseCfm": "20201001" + } + } + ] } - ] -} -``` + ``` -```title="form-urlencoded" -customer_uid={고객사의 결제 고객을 특정하는 Unique Key}&schedules[0][merchant_uid]={고객사 주문번호}&schedules[0][schedule_at]={결제요청 예약시각 UNIX timestamp}&schedules[0][amount]=10000&schedules[0][extra][naverUseCfm]=20201001\ -``` - - + ```title="form-urlencoded" + customer_uid={고객사의 결제 고객을 특정하는 Unique Key}&schedules[0][merchant_uid]={고객사 주문번호}&schedules[0][schedule_at]={결제요청 예약시각 UNIX timestamp}&schedules[0][amount]=10000&schedules[0][extra][naverUseCfm]=20201001\ + ``` + -**연동 주의사항** + ## 연동 주의사항 -#### 에레 메세지를 가공하지 않은 상태로 노출해야합니다. + ### 에레 메세지를 가공하지 않은 상태로 노출해야합니다. -결제창 호출(IMP.request_pay 함수)후 결제창 하단의 "취소" 버튼 클릭 등으로 결제 프로세스가 중단되거나 잔액 부족, 한도 초과, 10원 미만 결제 등의 사유로 결제에 실패하면 콜백 함수(popup 방식)/m_redirect_url(리디렉션 방식)로 전달되는 결제 결과(response 객체/쿼리 파라미터)에 실패 사유(error_msg)가 전달됩니다. -이 에러 메시지는 사용자에게 가공 없이 그대로 노출되어야 합니다. 해당 내용을 준수하지 않는 경우 네이버페이 검수 진행시 수정 요청이 있을 수 있습니다. + 결제창 호출(IMP.request\_pay 함수)후 결제창 하단의 "취소" 버튼 클릭 등으로 결제 프로세스가 중단되거나 잔액 부족, 한도 초과, 10원 미만 결제 등의 사유로 결제에 실패하면 콜백 함수(popup 방식)/m\_redirect\_url(리디렉션 방식)로 전달되는 결제 결과(response 객체/쿼리 파라미터)에 실패 사유(error\_msg)가 전달됩니다. + 이 에러 메시지는 사용자에게 가공 없이 그대로 노출되어야 합니다. 해당 내용을 준수하지 않는 경우 네이버페이 검수 진행시 수정 요청이 있을 수 있습니다. -예) error_msg가 "잔액 부족"이라고 가정할때, "결제에 실패하였습니다. 실패 사유:" + "잔액 부족"과 같은 형태로 가공되면 안됨 + 예) error\_msg가 "잔액 부족"이라고 가정할때, "결제에 실패하였습니다. 실패 사유:" + "잔액 부족"과 같은 형태로 가공되면 안됨 -#### 최소 결제 금액에 대해 예외 처리해야 합니다. + ### 최소 결제 금액에 대해 예외 처리해야 합니다. -네이버페이 결제형의 경우 10원 이상부터 결제가 가능합니다. 10원 미만의 경우 결제 요청에 대해 예외 처리가 필요합니다. + 네이버페이 결제형의 경우 10원 이상부터 결제가 가능합니다. 10원 미만의 경우 결제 요청에 대해 예외 처리가 필요합니다. -예) 사용자에게 최소 결제 금액이 10원이라 결제를 할 수 없다는 의미를 담는 에러 메시지가 노출되어야 함 + 예) 사용자에게 최소 결제 금액이 10원이라 결제를 할 수 없다는 의미를 담는 에러 메시지가 노출되어야 함 -#### 환불 API 요청 시 추가 속성 + ### 환불 API 요청 시 추가 속성 -아임포트 환불 API인 `POST /payments/cancel` 호출 시 다음 추가 속성를 설정해야 합니다. + 아임포트 환불 API인 `POST /payments/cancel` 호출 시 다음 추가 속성를 설정해야 합니다. -- `extra.requester` : API를 호출하는 출처. 다음 중 선택 : - - customer : 구매자에 의한 요청 - - admin(기본값) : 어드민에 의한 요청 -- `reason`: 결제 취소 사유. + - `extra.requester` : API를 호출하는 출처. 다음 중 선택 : + - customer : 구매자에 의한 요청 + - admin(기본값) : 어드민에 의한 요청 -**예시(json)** + - `reason`: 결제 취소 사유. -``` -{ - "imp_uid" : "imp_123412341234", //환불처리할 아임포트 거래번호 - "amount" : 3000, //환불할 금액 - "reason": "결제 취소 사유", //실제 사유와 같아야 함 - "extra" : { - "requester" : "customer" - } -} -``` + **예시 코드** -**예시(form-urlencoded)** + ```json + { + "imp_uid" : "imp_123412341234", //환불처리할 아임포트 거래번호 + "amount" : 3000, //환불할 금액 + "reason": "결제 취소 사유", //실제 사유와 같아야 함 + "extra" : { + "requester" : "customer" + } + } + ``` -``` -imp_uid=imp_123412341234&amount=3000&extra[requester]=customer -``` + **예시 코드** + ```form-urlencoded + imp_uid=imp_123412341234&amount=3000&extra[requester]=customer + ``` -**"API 호출 권한이 없습니다"** + **"API 호출 권한이 없습니다"** -네이버페이 결제형 연동은 **네이버페이 검수진행이 시작되기 전까지는 운영환경에서 결제창 호출시** - -**위와 같은 오류가 도출**됩니다. 해당 부분은 -검수가 진행되면 해결되는 부분이기 때문에 무시해주시면 됩니다. + 네이버페이 결제형 연동은 **네이버페이 검수진행이 시작되기 전까지는 운영환경에서 결제창 호출시** + **위와 같은 오류가 도출**됩니다. 해당 부분은 + 검수가 진행되면 해결되는 부분이기 때문에 무시해주시면 됩니다.
-

거래 취소 시 유의사항

+

거래 취소 시 유의사항

-포트원 환불 API인 `POST` [**`/payments/cancel`**](../../api/api-1/api) 호출시 아래 파라미터를 반드시 설정해 주셔야 합니다. (**해당 파라미터 누락시 네이버페이 실 검수를 통과할 수 없습니다.**) + 포트원 환불 API인 `POST` [**`/payments/cancel`**](../../api/api-1/api) 호출시 아래 파라미터를 반드시 설정해 주셔야 합니다. (**해당 파라미터 누락시 네이버페이 실 검수를 통과할 수 없습니다.**) -- **`extra.requester`**: API를 호출하는 출처 - - **`customer`**: 구매자에 의한 요청 - - **`admin`**(기본값): 어드민에 의한 요청 -- **`reason`**: 결제 취소 사유. + - **`extra.requester`**: API를 호출하는 출처 + - **`customer`**: 구매자에 의한 요청 + - **`admin`**(기본값): 어드민에 의한 요청 -**예시(json)** + - **`reason`**: 결제 취소 사유. -```javascript -{ - "imp_uid" : "imp_123412341234", //환불처리할 포트원 거래고유번호 - "amount" : 3000, //환불할 금액 - "reason": "결제 취소 사유", //실제 사유와 같아야 함 - "extra" : { - "requester" : "customer" - } -} -``` + **예시 코드** -**예시(form-urlencoded)** + ```json + { + "imp_uid" : "imp_123412341234", //환불처리할 포트원 거래고유번호 + "amount" : 3000, //환불할 금액 + "reason": "결제 취소 사유", //실제 사유와 같아야 함 + "extra" : { + "requester" : "customer" + } + } + ``` -``` -imp_uid=imp_123412341234&amount=3000&extra[requester]=customer -``` + **예시 코드** + ```form-urlencoded + imp_uid=imp_123412341234&amount=3000&extra[requester]=customer + ```
diff --git a/src/content/docs/ko/pg/simple/payco.mdx b/src/content/docs/ko/pg/simple/payco.mdx index 4af559705..efceec19b 100644 --- a/src/content/docs/ko/pg/simple/payco.mdx +++ b/src/content/docs/ko/pg/simple/payco.mdx @@ -3,19 +3,19 @@ title: 페이코 description: 페이코 결제 연동방법을 안내합니다. --- -import Codepen from "~/components/gitbook/Codepen.astro"; import Figure from "~/components/Figure.astro"; -import Hint from "~/components/Hint.astro"; -import Tabs from "~/components/gitbook/tabs/Tabs.astro"; +import Codepen from "~/components/gitbook/Codepen.astro"; import Tab from "~/components/gitbook/tabs/Tab.astro"; +import Tabs from "~/components/gitbook/tabs/Tabs.astro"; +import Hint from "~/components/Hint.astro"; -### 1. 페이코 채널 설정하기 +## 1. 페이코 채널 설정하기 [결제대행사 채널 설정하기](../../ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다.
-### 2.결제 요청하기 +## 2.결제 요청하기 [JavaScript SDK](../../sdk/javascript-sdk-old/readme) `IMP.request_pay(param, callback)`을 호출하여 페이코 결제창을 호출할 수 있습니다. **결제결과**는 PC의 경우 `IMP.request_pay(param, callback)` 호출 @@ -25,19 +25,23 @@ import Tab from "~/components/gitbook/tabs/Tab.astro"; ```javascript title="Javascript SDK" -IMP.request_pay({ - pg: "payco.{CPID}", - merchant_uid: "order_no_0001", // 상점에서 관리하는 주문 번호 - name: "주문명:결제테스트", - amount: 1004, - buyer_email: "test@portone.io", - buyer_name: "구매자이름", - buyer_tel: "010-1234-5678", - buyer_addr: "서울특별시 강남구 삼성동", - buyer_postcode: "123-456" -}, function(rsp) { // callback 로직 - /* ...중략... */ -}); +IMP.request_pay( + { + pg: "payco.{CPID}", + merchant_uid: "order_no_0001", // 상점에서 관리하는 주문 번호 + name: "주문명:결제테스트", + amount: 1004, + buyer_email: "test@portone.io", + buyer_name: "구매자이름", + buyer_tel: "010-1234-5678", + buyer_addr: "서울특별시 강남구 삼성동", + buyer_postcode: "123-456", + }, + function (rsp) { + // callback 로직 + /* ...중략... */ + }, +); ``` **주요 파라미터 설명** @@ -106,7 +110,7 @@ IMP.request_pay( } else { alert("빌링키 발급(자동결제 등록) 실패"); } - } + }, ); ``` diff --git a/src/content/docs/ko/pg/simple/toss-brandpay/module.mdx b/src/content/docs/ko/pg/simple/toss-brandpay/module.mdx index bf174990b..d2883c9cc 100644 --- a/src/content/docs/ko/pg/simple/toss-brandpay/module.mdx +++ b/src/content/docs/ko/pg/simple/toss-brandpay/module.mdx @@ -3,206 +3,195 @@ title: 모듈 로딩 연동 description: 토스페이먼츠 브랜드페이의 모듈 로딩에 연동 방법을 안내합니다. --- -import Codepen from "~/components/gitbook/Codepen.astro"; import Details from "~/components/gitbook/Details.astro"; -import Figure from "~/components/Figure.astro"; -import Hint from "~/components/Hint.astro"; -import Tabs from "~/components/gitbook/tabs/Tabs.astro"; import Tab from "~/components/gitbook/tabs/Tab.astro"; +import Tabs from "~/components/gitbook/tabs/Tabs.astro"; ## 모듈 로드 파라미터 정의 - -```javascript title="Javascript SDK" -await IMP.loadModule( - 'toss-brandpay', - { - userCode: 'imp00000000', //// 관리자 콘솔 - 결제 연동 페이지에서 확인 가능합니다. - }, - { - customerKey: 'd005f081-830a-4b9c-b5e2-73e56fbe6ac3', - loadBrandpayOptions: { - ui: { - buttonStyle: "default", - highlightColor: "#3182f6", - navigationBar: { - visible: true, - paddingTop: 10, - }, - labels: { - oneTouchPay: "원터치결제", + + ```javascript title="Javascript SDK" + await IMP.loadModule( + "toss-brandpay", + { + userCode: "imp00000000", //// 관리자 콘솔 - 결제 연동 페이지에서 확인 가능합니다. + }, + { + customerKey: "d005f081-830a-4b9c-b5e2-73e56fbe6ac3", + loadBrandpayOptions: { + ui: { + buttonStyle: "default", + highlightColor: "#3182f6", + navigationBar: { + visible: true, + paddingTop: 10, + }, + labels: { + oneTouchPay: "원터치결제", + }, }, }, - } - } -); -``` - -
-

주요 파라미터 설명

+ }, + ); + ``` -**`moduleType`** **\*** **string** +
+

주요 파라미터 설명

-**모듈 타입** + **`moduleType`** **\*** **string** -브랜드페이의 경우 `toss-brandpay` 를 사용합니다. + **모듈 타입** -**`userCode`** **\*** **string** + 브랜드페이의 경우 `toss-brandpay` 를 사용합니다. -**고객사 식별코드** + **`userCode`** **\*** **string** -`IMP` 로 시작하는 포트원 고객사 식별코드입니다. + **고객사 식별코드** -**`tier_code`** **string** + `IMP` 로 시작하는 포트원 고객사 식별코드입니다. -**하위상점(Tier)의 고유코드** + **`tier_code`** **string** -[상점·계정 관리]-[하위 상점 관리]에서 하위 상점을 생성한 경우에만 사용 가능합니다. 하위상점 고유코드는 알파벳 대문자 또는 숫자만 입력가능하며, 3자까지 입력 가능합니다. + **하위상점(Tier)의 고유코드** -**`loadBrandpayOptions`** **Object** + \[상점·계정 관리]-\[하위 상점 관리]에서 하위 상점을 생성한 경우에만 사용 가능합니다. 하위상점 고유코드는 알파벳 대문자 또는 숫자만 입력가능하며, 3자까지 입력 가능합니다. -브랜드페이의 모듈 로딩에 필요한 추가 파라미터입니다. -`moduleType`을 `toss-brandpay`로 설정하는 경우 필요합니다. + **`loadBrandpayOptions`** **Object** -**`loadBrandpayOptions.customer_id`** **\*** **string** + 브랜드페이의 모듈 로딩에 필요한 추가 파라미터입니다. + `moduleType`을 `toss-brandpay`로 설정하는 경우 필요합니다. -**구매자 ID** + **`loadBrandpayOptions.customer_id`** **\*** **string** -고객 ID입니다. 다른사용자에게 노출될 경우, 악의적 사용에 대한 문제가 있음으로 자동 증가하는 숫자는 허용되지 않습니다. -UUID 등 유추가 불가능한 무작위 값을 사용하시길 권장드립니다. + **구매자 ID** -**`loadBrandpayOptions.ui`** **Object** + 고객 ID입니다. 다른사용자에게 노출될 경우, 악의적 사용에 대한 문제가 있음으로 자동 증가하는 숫자는 허용되지 않습니다. + UUID 등 유추가 불가능한 무작위 값을 사용하시길 권장드립니다. -브랜드페이의 경우 결제창의 UI를 커스터마이징이 가능하며, 아래의 옵션들을 제공하고 있습니다. -포트원을 통한 연동 후 `IMP.request_pay` 호출 시 `bypass.toss_brandpay.ui` 객체 정보를 추가하여 UI 커스터마이징 기능을 사용할 수 있습니다. + **`loadBrandpayOptions.ui`** **Object** -**`loadBrandpayOptions.ui.buttonStyle`** **string** + 브랜드페이의 경우 결제창의 UI를 커스터마이징이 가능하며, 아래의 옵션들을 제공하고 있습니다. + 포트원을 통한 연동 후 `IMP.request_pay` 호출 시 `bypass.toss_brandpay.ui` 객체 정보를 추가하여 UI 커스터마이징 기능을 사용할 수 있습니다. -**버튼스타일 구분코드** + **`loadBrandpayOptions.ui.buttonStyle`** **string** -버튼 스타일입니다. 값을 넣지 않으면 기본값인 `default`로 설정됩니다. -`default`로 설정하면 모서리가 둥글고 주변에 여백을 가진 버튼을 사용할 수 있고, `full`로 설정하면 하단 영역이 전부 채워지는 형태의 버튼을 사용할 수 있습니다. + **버튼스타일 구분코드** -**`loadBrandpayOptions.ui.highlightColor`** **string** + 버튼 스타일입니다. 값을 넣지 않으면 기본값인 `default`로 설정됩니다. + `default`로 설정하면 모서리가 둥글고 주변에 여백을 가진 버튼을 사용할 수 있고, `full`로 설정하면 하단 영역이 전부 채워지는 형태의 버튼을 사용할 수 있습니다. -**UI 메인 색상** + **`loadBrandpayOptions.ui.highlightColor`** **string** -UI의 메인 색상입니다. 값을 넣지 않으면 기본 색상인 `#3182f6`로 설정됩니다. [웹에서 사용할 수 있는 색상 코드 형식](https://developer.mozilla.org/ko/docs/Web/CSS/color_value)을 모두 사용할 수 있습니다. + **UI 메인 색상** -**`loadBrandpayOptions.ui.navigationBar.visible`** **boolean** + UI의 메인 색상입니다. 값을 넣지 않으면 기본 색상인 `#3182f6`로 설정됩니다. [웹에서 사용할 수 있는 색상 코드 형식](https://developer.mozilla.org/ko/docs/Web/CSS/color_value)을 모두 사용할 수 있습니다. -**내비게이션 바 사용 여부** + **`loadBrandpayOptions.ui.navigationBar.visible`** **boolean** -화면 뒤로 가기 기능을 제공하는 내비게이션 바 사용 여부입니다. 값을 넣지 않으면 기본값인 `true`로 설정됩니다. 내비게이션 바를 사용하지 않으려면 `false`로 설정해야 합니다. + **내비게이션 바 사용 여부** -**`loadBrandpayOptions.ui.navigationBar.paddingTop`** **number** + 화면 뒤로 가기 기능을 제공하는 내비게이션 바 사용 여부입니다. 값을 넣지 않으면 기본값인 `true`로 설정됩니다. 내비게이션 바를 사용하지 않으려면 `false`로 설정해야 합니다. -**내비게이션 바 상단 여백** + **`loadBrandpayOptions.ui.navigationBar.paddingTop`** **number** -내비게이션 바 위쪽에 설정할 여백 값입니다. 값의 단위는 `px`입니다. + **내비게이션 바 상단 여백** -**`loadBrandpayOptions.ui.labels.oneTouchPay`** **string** + 내비게이션 바 위쪽에 설정할 여백 값입니다. 값의 단위는 `px`입니다. -**원터치결제 대체 텍스트** + **`loadBrandpayOptions.ui.labels.oneTouchPay`** **string** -UI에 표시되는 `원터치결제`를 대신해 사용할 텍스트입니다. 값을 넣지 않으면 `원터치결제`로 표시됩니다. + **원터치결제 대체 텍스트** -
- + UI에 표시되는 `원터치결제`를 대신해 사용할 텍스트입니다. 값을 넣지 않으면 `원터치결제`로 표시됩니다. +
+ ## 모듈로드 결과값 정의 - -```javascript title="Javascript SDK" -const brandpayModule = await IMP.loadModule( - 'toss-brandpay', - { - userCode: 'imp00000000', //// 관리자 콘솔 - 결제 연동 페이지에서 확인 가능합니다. - }, - { - customerKey: 'd005f081-830a-4b9c-b5e2-73e56fbe6ac3', - loadBrandpayOptions: { - ui: { - buttonStyle: "default", - highlightColor: "#3182f6", - navigationBar: { - visible: true, - paddingTop: 10, - }, - labels: { - oneTouchPay: "원터치결제", + + ```javascript title="Javascript SDK" + const brandpayModule = await IMP.loadModule( + "toss-brandpay", + { + userCode: "imp00000000", //// 관리자 콘솔 - 결제 연동 페이지에서 확인 가능합니다. + }, + { + customerKey: "d005f081-830a-4b9c-b5e2-73e56fbe6ac3", + loadBrandpayOptions: { + ui: { + buttonStyle: "default", + highlightColor: "#3182f6", + navigationBar: { + visible: true, + paddingTop: 10, + }, + labels: { + oneTouchPay: "원터치결제", + }, }, }, - } - } -); - -brandpayModule.setupPassword() -brandpayModule.getPaymentMethods() -brandpayModule.openSettings() - -```` - - -
-

setupPassword 설명

- -결제할 때 사용할 비밀번호를 설정할 수 있는 메서드입니다. 비밀번호 등록・변경이 완료되면 Promise가 resolve됩니다. + }, + ); -자세한 내용은 [토스페이먼츠의 개발자센터 문서](https://docs.tosspayments.com/reference/brandpay-sdk#setuppassword) 를 참고하세요. + brandpayModule.setupPassword(); + brandpayModule.getPaymentMethods(); + brandpayModule.openSettings(); + ``` + -```javascript title="Javascript SDK" -brandpayModule.setupPassword() - .catch(function (error) { - if (error.code === 'USER_CANCEL') { - // 사용자가 창을 닫아 취소한 경우에 대한 처리 - } - }) -``` +
+

setupPassword 설명

-
-
-

getPaymentMethods 설명

+ 결제할 때 사용할 비밀번호를 설정할 수 있는 메서드입니다. 비밀번호 등록・변경이 완료되면 Promise가 resolve됩니다. -등록되어 있는 결제 수단을 조회하는 메서드입니다. 조회가 성공했을 때 Promise가 resolve되고 고객의 결제수단 정보(BrandpayMethodResponse)가 반환됩니다. - -자세한 내용은 [토스페이먼츠의 개발자센터 문서](https://docs.tosspayments.com/reference/brandpay-sdk#getpaymentmethods) 를 참고하세요. - -```javascript title="Javascript SDK" -brandpayModule - .getPaymentMethods() - .then(function (methods) { - // 성공 처리 - }) - .catch(function (error) { - if (error.code === 'USER_CANCEL') { - // 사용자가 결제창을 닫은 경우 에러 처리 - } - }) -``` - -
-
-

openSettings 설명

- -브랜드페이에서 사용하는 결제수단, 비밀번호 설정을 관리하는 결제 관리창을 열 수 있습니다. - -자세한 내용은 [토스페이먼츠의 개발자센터 문서](https://docs.tosspayments.com/reference/brandpay-sdk#opensettings) 를 참고하세요. - -```javascript title="Javascript SDK" -brandpayModule.openSettings().catch(function (error) { - if (error.code === 'USER_CANCEL') { - // 사용자가 창을 닫아 취소한 경우에 대한 처리 - } -}) -``` - -
+ 자세한 내용은 [토스페이먼츠의 개발자센터 문서](https://docs.tosspayments.com/reference/brandpay-sdk#setuppassword) 를 참고하세요. + ```javascript title="Javascript SDK" + brandpayModule.setupPassword().catch(function (error) { + if (error.code === "USER_CANCEL") { + // 사용자가 창을 닫아 취소한 경우에 대한 처리 + } + }); + ``` +
+ +
+

getPaymentMethods 설명

+ + 등록되어 있는 결제 수단을 조회하는 메서드입니다. 조회가 성공했을 때 Promise가 resolve되고 고객의 결제수단 정보(BrandpayMethodResponse)가 반환됩니다. + + 자세한 내용은 [토스페이먼츠의 개발자센터 문서](https://docs.tosspayments.com/reference/brandpay-sdk#getpaymentmethods) 를 참고하세요. + + ```javascript title="Javascript SDK" + brandpayModule + .getPaymentMethods() + .then(function (methods) { + // 성공 처리 + }) + .catch(function (error) { + if (error.code === "USER_CANCEL") { + // 사용자가 결제창을 닫은 경우 에러 처리 + } + }); + ``` +
+ +
+

openSettings 설명

+ + 브랜드페이에서 사용하는 결제수단, 비밀번호 설정을 관리하는 결제 관리창을 열 수 있습니다. + + 자세한 내용은 [토스페이먼츠의 개발자센터 문서](https://docs.tosspayments.com/reference/brandpay-sdk#opensettings) 를 참고하세요. + + ```javascript title="Javascript SDK" + brandpayModule.openSettings().catch(function (error) { + if (error.code === "USER_CANCEL") { + // 사용자가 창을 닫아 취소한 경우에 대한 처리 + } + }); + ``` +
- -``` -```` diff --git a/src/content/docs/ko/pg/simple/toss-brandpay/readme.mdx b/src/content/docs/ko/pg/simple/toss-brandpay/readme.mdx index a09f152f8..85105d3f8 100644 --- a/src/content/docs/ko/pg/simple/toss-brandpay/readme.mdx +++ b/src/content/docs/ko/pg/simple/toss-brandpay/readme.mdx @@ -4,12 +4,11 @@ title: 토스페이먼츠 브랜드페이 description: 토스페이먼츠 브랜드페이 연동 방법을 안내합니다. --- -import Codepen from "~/components/gitbook/Codepen.astro"; -import Details from "~/components/gitbook/Details.astro"; import Figure from "~/components/Figure.astro"; -import Hint from "~/components/Hint.astro"; -import Tabs from "~/components/gitbook/tabs/Tabs.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"; ## 1. 토스페이먼츠 브랜드페이 채널 설정하기 @@ -21,29 +20,27 @@ import Tab from "~/components/gitbook/tabs/Tab.astro"; 토스페이먼츠 브랜드페이 결제는 최신 SDK에서만 지원되는 기능입니다. -```javascript title="JS SDK" +```html title="JS SDK" ``` **토스페이먼츠 브랜드페이를 연동하기 위해서는 위에 안내된 JS SDK를 이용하셔야 합니다** - -#### **기존에 deprecated된 콜백 응답은 모두 제거**됐습니다. - -신규 JS SDK는 기존 모듈에서 제공했던 CallBack 응답 파라미터가 대부분 삭제되었습니다. -(특히 deprecated 로 명시된 파라미터는 모두 삭제되었습니다.) + ### **기존에 deprecated된 콜백 응답은 모두 제거**됐습니다. -해당 JS SDK 사용시 Callback 으로 내려받을수 있는 데이터는 오직 아래 두가지 입니다. + 신규 JS SDK는 기존 모듈에서 제공했던 CallBack 응답 파라미터가 대부분 삭제되었습니다. + (특히 deprecated 로 명시된 파라미터는 모두 삭제되었습니다.) -**`imp_uid`, `merchant_uid`** + 해당 JS SDK 사용시 Callback 으로 내려받을수 있는 데이터는 오직 아래 두가지 입니다. -따라서 해당 SDK를 사용하실때는 `IMP.request_pay`로부터 응답된 객체(또는 쿼리 파라미터)에서 -`imp_uid`를 가지고 **아임포트 REST API(GET `/payments/imp_uid`)로 결제 상세 내역(승인 상태, 승인 결과 등등)을 조회**하여 -응답 파라미터 중 `status` 파라미터로 결제 상태를 파악하셔야 합니다. + **`imp_uid`, `merchant_uid`** + 따라서 해당 SDK를 사용하실때는 `IMP.request_pay`로부터 응답된 객체(또는 쿼리 파라미터)에서 + `imp_uid`를 가지고 **아임포트 REST API(GET `/payments/imp_uid`)로 결제 상세 내역(승인 상태, 승인 결과 등등)을 조회**하여 + 응답 파라미터 중 `status` 파라미터로 결제 상태를 파악하셔야 합니다. [JavaScript SDK](../../../sdk/javascript-sdk/readme) 문서를 통해 최신 SDK를 설치해주세요. @@ -57,78 +54,76 @@ import Tab from "~/components/gitbook/tabs/Tab.astro"; 수신됩니다. - -```javascript title="Javascript SDK" -IMP.request_pay( - { - pg: "toss_brandpay.{상점 ID}", - pay_method: "toss_brandpay", - merchant_uid: "orderNo0001", - name: "주문명:결제테스트", - amount: 1004, - buyer_email: "test@portone.io", - customer_id: "d005f081-830a-4b9c-b5e2-73e56fbe6ac3", - bypass: { - isCulturalExpense: true - } - }, - function (rsp) { - // callback 로직 - } -); -``` - -
-

주요 파라미터 설명

- -**`pg`** **\*** **string** + + ```javascript title="Javascript SDK" + IMP.request_pay( + { + pg: "toss_brandpay.{상점 ID}", + pay_method: "toss_brandpay", + merchant_uid: "orderNo0001", + name: "주문명:결제테스트", + amount: 1004, + buyer_email: "test@portone.io", + customer_id: "d005f081-830a-4b9c-b5e2-73e56fbe6ac3", + bypass: { + isCulturalExpense: true, + }, + }, + function (rsp) { + // callback 로직 + }, + ); + ``` -**PG사 구분코드** +
+

주요 파라미터 설명

-`toss_brandpay` 로 지정하면 됩니다. + **`pg`** **\*** **string** -**`pay_method`** **\*** **string** + **PG사 구분코드** -**결제수단 구분코드** + `toss_brandpay` 로 지정하면 됩니다. -`toss_brandpay` 로 지정하면 됩니다. + **`pay_method`** **\*** **string** -**`merchant_uid`** **\*** **string** + **결제수단 구분코드** -**주문번호** + `toss_brandpay` 로 지정하면 됩니다. -매번 고유하게 채번되어야 합니다. + **`merchant_uid`** **\*** **string** -**`name`** **\*** **string** + **주문번호** -**주문명** + 매번 고유하게 채번되어야 합니다. -**`amount`** **\*** **integer** + **`name`** **\*** **string** -**결제금액** + **주문명** -브랜드페이는 원화 결제만 지원합니다. KRW 기준으로 금액을 입력해주세요. + **`amount`** **\*** **integer** -**`buyer_email`** **string** + **결제금액** -**구매자 email 주소** + 브랜드페이는 원화 결제만 지원합니다. KRW 기준으로 금액을 입력해주세요. -**`customer_id`** **\*** **string** + **`buyer_email`** **string** -**구매자 ID** + **구매자 email 주소** -고객 ID입니다. 다른사용자에게 노출될 경우, 악의적 사용에 대한 문제가 있음으로 자동 증가하는 숫자는 허용되지 않습니다. -UUID 등 유추가 불가능한 무작위 값을 사용하시길 권장드립니다. + **`customer_id`** **\*** **string** -**`bypass.isCulturalExpense`** **\*** **string** + **구매자 ID** -**도서 문화비 결제 여부** + 고객 ID입니다. 다른사용자에게 노출될 경우, 악의적 사용에 대한 문제가 있음으로 자동 증가하는 숫자는 허용되지 않습니다.\ + UUID 등 유추가 불가능한 무작위 값을 사용하시길 권장드립니다. -도서 문화비 소득 공제 결제 여부를 나타내는 파라미터입니다. 기본값은 `false`입니다. + **`bypass.isCulturalExpense`** **\*** **string** -
+ **도서 문화비 결제 여부** - + 도서 문화비 소득 공제 결제 여부를 나타내는 파라미터입니다. 기본값은 `false`입니다. +
+ ## 3. UI 커스터마이징 @@ -139,77 +134,75 @@ UUID 등 유추가 불가능한 무작위 값을 사용하시길 권장드립니 커스터마이징 기능을 사용할 수 있습니다. - - -```javascript title="Javascript SDK" -IMP.request_pay( - { - pg: "toss_brandpay.{상점 ID}", - pay_method: "toss_brandpay", - merchant_uid: "orderNo0001", - name: "주문명:결제테스트", - amount: 1004, - buyer_email: "test@portone.io", - bypass: { - toss_brandpay: { - brandpayOptions: { - ui: { - buttonStyle: "default", - highlightColor: "#3182f6", - navigationBar: { - visible: true, - paddingTop: 10, - }, - labels: { - oneTouchPay: "원터치결제", + + ```javascript title="Javascript SDK" + IMP.request_pay( + { + pg: "toss_brandpay.{상점 ID}", + pay_method: "toss_brandpay", + merchant_uid: "orderNo0001", + name: "주문명:결제테스트", + amount: 1004, + buyer_email: "test@portone.io", + bypass: { + toss_brandpay: { + brandpayOptions: { + ui: { + buttonStyle: "default", + highlightColor: "#3182f6", + navigationBar: { + visible: true, + paddingTop: 10, + }, + labels: { + oneTouchPay: "원터치결제", + }, + }, }, }, }, }, - }, - }, - function (rsp) { - // callback 로직 - } -); -``` - -**`buttonStyle`** **string** + function (rsp) { + // callback 로직 + }, + ); + ``` -**버튼스타일 구분코드** + **`buttonStyle`** **string** -- 버튼 스타일입니다. 값을 넣지 않으면 기본값인 `default`로 설정됩니다. -- `default`로 설정하면 모서리가 둥글고 주변에 여백을 가진 버튼을 사용할 수 있고, `full`로 설정하면 하단 영역이 전부 채워지는 형태의 버튼을 사용할 수 있습니다. + **버튼스타일 구분코드** -**`highlightColor`** **string** + - 버튼 스타일입니다. 값을 넣지 않으면 기본값인 `default`로 설정됩니다. + - `default`로 설정하면 모서리가 둥글고 주변에 여백을 가진 버튼을 사용할 수 있고, `full`로 설정하면 하단 영역이 전부 채워지는 형태의 버튼을 사용할 수 있습니다. -**UI 메인 색상** + **`highlightColor`** **string** -- UI의 메인 색상입니다. -- 값을 넣지 않으면 기본 색상인 `#3182f6`로 설정됩니다. -- [웹에서 사용할 수 있는 색상 코드 형식](https://developer.mozilla.org/ko/docs/Web/CSS/color_value)을 모두 사용할 수 있습니다. + **UI 메인 색상** -**`navigationBar.visible`** **boolean** + - UI의 메인 색상입니다. + - 값을 넣지 않으면 기본 색상인 `#3182f6`로 설정됩니다. + - [웹에서 사용할 수 있는 색상 코드 형식](https://developer.mozilla.org/ko/docs/Web/CSS/color_value)을 모두 사용할 수 있습니다. -**내비게이션 바 사용 여부** + **`navigationBar.visible`** **boolean** -- 화면 뒤로 가기 기능을 제공하는 내비게이션 바 사용 여부입니다. -- 값을 넣지 않으면 기본값인 `true`로 설정됩니다. -- 내비게이션 바를 사용하지 않으려면 `false`로 설정해야 합니다. + **내비게이션 바 사용 여부** -**`navigationBar.paddingTop`** **number** + - 화면 뒤로 가기 기능을 제공하는 내비게이션 바 사용 여부입니다. + - 값을 넣지 않으면 기본값인 `true`로 설정됩니다. + - 내비게이션 바를 사용하지 않으려면 `false`로 설정해야 합니다. -**내비게이션 바 상단 여백** + **`navigationBar.paddingTop`** **number** -- 내비게이션 바 위쪽에 설정할 여백 값입니다. 값의 단위는 `px`입니다. + **내비게이션 바 상단 여백** -**`labels.oneTouchPay`** **string** + - 내비게이션 바 위쪽에 설정할 여백 값입니다. 값의 단위는 `px`입니다. -**원터치결제 대체 텍스트** + **`labels.oneTouchPay`** **string** -- UI에 표시되는 `원터치결제`를 대신해 사용할 텍스트입니다. 값을 넣지 않으면 `원터치결제`로 표시됩니다. + **원터치결제 대체 텍스트** - + - UI에 표시되는 `원터치결제`를 대신해 사용할 텍스트입니다. 값을 넣지 않으면 `원터치결제`로 표시됩니다. + ## 4. 결제수단 지정 바로 결제 @@ -223,135 +216,129 @@ IMP.request_pay( 있는, `getPaymentMethods()` 함수를 통해 확인할 수 있습니다. - - -```javascript title="Javascript SDK" -IMP.request_pay( - { - pg: "toss_brandpay.{상점 ID}", - pay_method: "toss_brandpay", - merchant_uid: "orderNo0001", - name: "주문명:결제테스트", - amount: 1004, - buyer_email: "test@portone.io", - customer_id: "d005f081-830a-4b9c-b5e2-73e56fbe6ac3", - useCardPoint: true, - display: { - card_quota: [6], - }, - bypass: { - cashReceiptType: "personal", - customerIdentifier: "01000000000", - toss_brandpay: { - methodId: "3nKLoSBV7l8zUHU14cZxK", - discountCode: "001", + + ```javascript title="Javascript SDK" + IMP.request_pay( + { + pg: "toss_brandpay.{상점 ID}", + pay_method: "toss_brandpay", + merchant_uid: "orderNo0001", + name: "주문명:결제테스트", + amount: 1004, + buyer_email: "test@portone.io", + customer_id: "d005f081-830a-4b9c-b5e2-73e56fbe6ac3", + useCardPoint: true, + display: { + card_quota: [6], + }, + bypass: { + cashReceiptType: "personal", + customerIdentifier: "01000000000", + toss_brandpay: { + methodId: "3nKLoSBV7l8zUHU14cZxK", + discountCode: "001", + }, + }, }, - }, - }, - function (rsp) { - // callback 로직 - } -); -``` - -### 기타 파라미터 - -아래 파라미터를 사용하기 위해서는 결제 수단 ID인 `methodId`를 지정하여 함께 결제 요청해야 합니다. - - - -#### **브랜드페이 위젯에서 사용할 수 없는 파라미터** 가 포함되어 있습니다. - -아래 파라미터는 브랜드페이 위젯에서는 사용할 수 없습니다. + function (rsp) { + // callback 로직 + }, + ); + ``` -- **`display.card_quot`** -- **`useCardPoint`** -- **`bypass.cashReceiptType`** -- **`bypass.customerIdentifier`** + ### 기타 파라미터 - + 아래 파라미터를 사용하기 위해서는 결제 수단 ID인 `methodId`를 지정하여 함께 결제 요청해야 합니다. -**`useCardPoint`** **boolean** + + #### **브랜드페이 위젯에서 사용할 수 없는 파라미터** 가 포함되어 있습니다. -**카드사 포인트 사용 여부** + 아래 파라미터는 브랜드페이 위젯에서는 사용할 수 없습니다. -- 카드사 포인트를 사용 여부를 지정하는 값입니다. -- `true` 입력 시 카드사 포인트 사용이 가능하며, 입력하지 않는 경우 기본값은 `false`입니다. -- (단, 카드사 포인트를 사용하기 위해서는 사전에 토스페이먼츠를 통해 계약이 진행되어야 합니다.) + - **`display.card_quot`** + - **`useCardPoint`** + - **`bypass.cashReceiptType`** + - **`bypass.customerIdentifier`** + -**`display.card_quota`** **number array** + **`useCardPoint`** **boolean** -**카드 할부 개월 수** + **카드사 포인트 사용 여부** -- 카드 결제 시 할부 개월 수를 지정할 수 있습니다. -- `[3]` 형식으로 전달하면 3개월 할부로 결제가 진행됩니다. -- (단, 일반적으로 결제금액이 5만원 이상일 때만 적용됩니다.) + - 카드사 포인트를 사용 여부를 지정하는 값입니다. + - `true` 입력 시 카드사 포인트 사용이 가능하며, 입력하지 않는 경우 기본값은 `false`입니다. + - (단, 카드사 포인트를 사용하기 위해서는 사전에 토스페이먼츠를 통해 계약이 진행되어야 합니다.) -**`bypass.cashReceiptType`** **string** + **`display.card_quota`** **number array** -**현금영수증 발급 타입** + **카드 할부 개월 수** -- `unable`로 설정시 현금영수증을 발행하지 않으며, `personal`로 설정 시에는 소득 공제용, `corporate`으로 설정 시에는 지출 증빙용으로 현금영수증을 발급합니다. -- `anonymous`으로 설정하는 경우 현금영수증 자진발급됩니다. 기본값은 `unable`입니다. + - 카드 결제 시 할부 개월 수를 지정할 수 있습니다. + - `[3]` 형식으로 전달하면 3개월 할부로 결제가 진행됩니다. + - (단, 일반적으로 결제금액이 5만원 이상일 때만 적용됩니다.) -**`bypass.customerIdentifier`** **string** + **`bypass.cashReceiptType`** **string** -**현금영수증 발급 식별번호** + **현금영수증 발급 타입** -- 현금영수증 발급을 위한 식별번호입니다. -- 현금영수증 종류에 따라 휴대폰번호, 사업자등록번호, 현금영수증 카드번호를 입력할 수 있습니다. + - `unable`로 설정시 현금영수증을 발행하지 않으며, `personal`로 설정 시에는 소득 공제용, `corporate`으로 설정 시에는 지출 증빙용으로 현금영수증을 발급합니다. + - `anonymous`으로 설정하는 경우 현금영수증 자진발급됩니다. 기본값은 `unable`입니다. -**`bypass.toss_brandpay.discountCode`** **string** + **`bypass.customerIdentifier`** **string** -**카드사 즉시 할인 코드** + **현금영수증 발급 식별번호** -- 토스페이먼츠의 [카드혜택 조회 API](https://docs.tosspayments.com/reference#%EC%B9%B4%EB%93%9C-%ED%98%9C%ED%83%9D-%EC%A1%B0%ED%9A%8C-1)로 적용할 수 있는 할인 코드 목록을 조회할 수 있습니다. -- 해당 API는 포트원을 통해 지원이 불가능하므로, 직접 토스페이먼츠 API를 연동하여 사용해야 합니다. + - 현금영수증 발급을 위한 식별번호입니다. + - 현금영수증 종류에 따라 휴대폰번호, 사업자등록번호, 현금영수증 카드번호를 입력할 수 있습니다. -### 브랜드페이 위젯 전용 파라미터 + **`bypass.toss_brandpay.discountCode`** **string** -아래 파라미터를 사용하기 위해서는 결제 수단 ID인 `methodId`를 지정하여 함께 결제 요청해야 합니다. + **카드사 즉시 할인 코드** - + - 토스페이먼츠의 [카드혜택 조회 API](https://docs.tosspayments.com/reference#%EC%B9%B4%EB%93%9C-%ED%98%9C%ED%83%9D-%EC%A1%B0%ED%9A%8C-1)로 적용할 수 있는 할인 코드 목록을 조회할 수 있습니다. + - 해당 API는 포트원을 통해 지원이 불가능하므로, 직접 토스페이먼츠 API를 연동하여 사용해야 합니다. -#### 브랜드페이 위젯에서만 사용 가능한 파라미터입니다. + ### 브랜드페이 위젯 전용 파라미터 -`bypass.toss_brandpay.widgetOptions` 에 설정되어야 합니다. + 아래 파라미터를 사용하기 위해서는 결제 수단 ID인 `methodId`를 지정하여 함께 결제 요청해야 합니다. - + + #### 브랜드페이 위젯에서만 사용 가능한 파라미터입니다. -**`methodType`** **string** + `bypass.toss_brandpay.widgetOptions` 에 설정되어야 합니다. + -**위젯에 보여줄 결제 수단** + **`methodType`** **string** -- 위젯에 보여줄 결제수단을 선택합니다. -- `카드`, `계좌` 중 하나입니다. 예를 들어 `카드`를 선택하면 등록한 결제수단 중 `카드`만 노출됩니다. + **위젯에 보여줄 결제 수단** -**`methodId`** **string** + - 위젯에 보여줄 결제수단을 선택합니다. + - `카드`, `계좌` 중 하나입니다. 예를 들어 `카드`를 선택하면 등록한 결제수단 중 `카드`만 노출됩니다. -**위젯에서 기본 결제수단으로 선택할 결제수단의 ID** + **`methodId`** **string** -- 위젯을 열었을때, 해당 methodId에 해당하는 결제수단이 가장 먼저 보여집니다. -- 가장 최근에 결제한 카드를 보여주거나, 유저가 선호하는 카드를 보여줄 때 사용할 수 있습니다. + **위젯에서 기본 결제수단으로 선택할 결제수단의 ID** -**`ui.promotionSection.summary.visible`** **boolean** + - 위젯을 열었을때, 해당 methodId에 해당하는 결제수단이 가장 먼저 보여집니다. + - 가장 최근에 결제한 카드를 보여주거나, 유저가 선호하는 카드를 보여줄 때 사용할 수 있습니다. -**혜택 배지 영역 표시여부** + **`ui.promotionSection.summary.visible`** **boolean** -- 해택 배지 영역에서는 즉시 할인 대상 카드 정보 등을 간략히 보여줍니다. 기본값은 `true`입니다. + **혜택 배지 영역 표시여부** -**`ui.promotionSection.description.visible`** **boolean** + - 해택 배지 영역에서는 즉시 할인 대상 카드 정보 등을 간략히 보여줍니다. 기본값은 `true`입니다. -**혜택 배지 영역 표시여부** + **`ui.promotionSection.description.visible`** **boolean** -- 결제 해택 영역을 보여주거나 숨깁니다. 기본값은 `true`입니다. + **혜택 배지 영역 표시여부** -**`ui.promotionSection.description.defaultOpen`** **boolean** + - 결제 해택 영역을 보여주거나 숨깁니다. 기본값은 `true`입니다. -**결제 혜택 상세 설명 표시 여부** + **`ui.promotionSection.description.defaultOpen`** **boolean** -- 결제 혜택의 상세 설명을 보여주거나 숨깁니다. -- `true`인 경우, 결제 카드사의 결제 혜택을 자세히 설명합니다. 기본값은 `false`입니다. + **결제 혜택 상세 설명 표시 여부** - + - 결제 혜택의 상세 설명을 보여주거나 숨깁니다. + - `true`인 경우, 결제 카드사의 결제 혜택을 자세히 설명합니다. 기본값은 `false`입니다. + diff --git a/src/content/docs/ko/pg/simple/toss-brandpay/widget.mdx b/src/content/docs/ko/pg/simple/toss-brandpay/widget.mdx index 3d3aea2a9..c5e30124e 100644 --- a/src/content/docs/ko/pg/simple/toss-brandpay/widget.mdx +++ b/src/content/docs/ko/pg/simple/toss-brandpay/widget.mdx @@ -4,16 +4,12 @@ title: 브랜드페이 위젯 연동 description: 토스페이먼츠 브랜드페이 위젯 연동 방법을 안내합니다. --- -import Codepen from "~/components/gitbook/Codepen.astro"; -import Details from "~/components/gitbook/Details.astro"; import Figure from "~/components/Figure.astro"; import Hint from "~/components/Hint.astro"; -import Tabs from "~/components/gitbook/tabs/Tabs.astro"; -import Tab from "~/components/gitbook/tabs/Tab.astro"; -import screenshot1 from "./_assets/widget_example.png"; import screenshot2 from "./_assets/loadui.png"; import screenshot3 from "./_assets/updateloadui.png"; +import screenshot1 from "./_assets/widget_example.png"; - 브랜드페이의 경우 고객사의 주문 페이지에 바로 브랜드페이를 통한 결제가 가능하도록 브랜드페이 UI를 렌더링 할 수 있는 위젯 기능을 제공합니다. diff --git a/src/content/docs/ko/pg/simple/tosspay-v2/readme.mdx b/src/content/docs/ko/pg/simple/tosspay-v2/readme.mdx index 53a619c11..f787d6f90 100644 --- a/src/content/docs/ko/pg/simple/tosspay-v2/readme.mdx +++ b/src/content/docs/ko/pg/simple/tosspay-v2/readme.mdx @@ -4,66 +4,67 @@ description: 토스페이 연동 방법을 안내합니다. --- 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 Tabs from "~/components/gitbook/tabs/Tabs.astro"; +import Hint from "~/components/Hint.astro"; - 토스페이(tosspay_v2)에서는 일반결제 및 정기결제 모두 지원하고 있습니다. 신규 연동하시는 고객사께서는 해당 가이드를 참고하여 진행해주세요. + 토스페이(tosspay\_v2)에서는 일반결제 및 정기결제 모두 지원하고 있습니다. 신규 연동하시는 고객사께서는 해당 가이드를 참고하여 진행해주세요. -### 1. 토스페이 채널 설정하기 +## 1. 토스페이 채널 설정하기 [결제대행사 채널 설정하기](../../ready/readme#3-결제대행사-채널-설정하기) 페이지의 내용을 참고하여 채널 설정을 진행합니다.
-### 2. 최신 JavaScript SDK로 업데이트하기 +## 2. 최신 JavaScript SDK로 업데이트하기 토스페이 결제는 최신 SDK에서만 지원되는 기능입니다. -```javascript title="JS SDK" +```html title="JS SDK" ``` **토스페이를 연동하기 위해서는 위에 안내된 JS SDK를 이용하셔야 합니다.** -[JavaScript SDK](../../../sdk/javascript-sdk/readme)문서를 통해 최신 SDK를 설치해주세요. - + [JavaScript SDK](../../../sdk/javascript-sdk/readme)문서를 통해 최신 SDK를 설치해주세요. -### 3.결제 요청하기 +## 3.결제 요청하기 [JavaScript SDK](../../../sdk/javascript-sdk/readme) `IMP.request_pay(param, callback)`을 호출하여 결제창을 호출할 수 있습니다. **결제결과**는 PC의 경우 `IMP.request_pay(param, callback)` 호출 후 **callback**으로 수신되고 -모바일의 경우 **m_redirect_url** 로 리디렉션됩니다. +모바일의 경우 **m\_redirect\_url** 로 리디렉션됩니다. ```javascript title="Javascript SDK" - IMP.request_pay({ - pg: "tosspay_v2.{MID}", - pay_method: "tosspay", // 'tosspay_card', 'tosspay_money' 도 지원됩니다. - merchant_uid: "orderMonthly0001", // 상점에서 관리하는 주문 번호 - name: "최초인증결제", - buyer_email: "test@portone.io", - buyer_name: "포트원", - buyer_tel: "02-1234-1234", - m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", - amount: 1004, - card: { - useInstallment: false, - } - bypass: { - expiredTime: "2023-12-02 11:00:00", //결제 만료시간 - cashReceiptTradeOption: 'CULTURE' //현금영수증 발급타입 - - } - }, function (rsp) { - // callback 로직 - }); + IMP.request_pay( + { + pg: "tosspay_v2.{MID}", + pay_method: "tosspay", // 'tosspay_card', 'tosspay_money' 도 지원됩니다. + merchant_uid: "orderMonthly0001", // 상점에서 관리하는 주문 번호 + name: "최초인증결제", + buyer_email: "test@portone.io", + buyer_name: "포트원", + buyer_tel: "02-1234-1234", + m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", + amount: 1004, + card: { + useInstallment: false, + }, + bypass: { + expiredTime: "2023-12-02 11:00:00", //결제 만료시간 + cashReceiptTradeOption: "CULTURE", //현금영수증 발급타입 + }, + }, + function (rsp) { + // callback 로직 + }, + ); ```
@@ -78,9 +79,10 @@ import Tab from "~/components/gitbook/tabs/Tab.astro"; **`pay_method`** **\*** **string** **결제수단 구분코드** - - `tosspay_money` : 계좌결제만 허용합니다. - - `tosspay_card` : 카드결제만 허용합니다. - - `tosspay` : 모든 결제수단을 허용합니다. + + - `tosspay_money` : 계좌결제만 허용합니다. + - `tosspay_card` : 카드결제만 허용합니다. + - `tosspay` : 모든 결제수단을 허용합니다. **`merchant_uid`** **\*** **string** @@ -115,30 +117,32 @@ import Tab from "~/components/gitbook/tabs/Tab.astro"; - `GENERAL`: 일반 (default) - `CULTURE`: 문화비 - `PUBLIC_TP`: 교통비 -
- 인증결제창 호출 파라미터에서 **customer\_uid**, **customer\_id**값을 추가하면 비인증 결제창을 호출할 수 있습니다. 비인증 결제창에서 빌링키를 발급받은 후 해당 빌링키로 결제를 요청합니다. + ```javascript title="Javascript SDK" - IMP.request_pay({ - pg: "tosspay_v2.{MID}", - pay_method: "tosspay", // 'tosspay'만 지원됩니다. - merchant_uid: "orderMonthly0001", // 상점에서 관리하는 주문 번호 - name: "최초인증결제", - customer_id: "matthew", //고객사가 회원에게 부여한 고유 ID로 필수 입력. - customer_uid: "your-customer-unique-id", // 필수 입력. - buyer_email: "test@portone.io", - buyer_name: "포트원", - buyer_tel: "02-1234-1234", - m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", - notice_url: "{빌링키 발급 결과를 받을 URL}", - }, function (rsp) { - // callback 로직 - }); + IMP.request_pay( + { + pg: "tosspay_v2.{MID}", + pay_method: "tosspay", // 'tosspay'만 지원됩니다. + merchant_uid: "orderMonthly0001", // 상점에서 관리하는 주문 번호 + name: "최초인증결제", + customer_id: "matthew", //고객사가 회원에게 부여한 고유 ID로 필수 입력. + customer_uid: "your-customer-unique-id", // 필수 입력. + buyer_email: "test@portone.io", + buyer_name: "포트원", + buyer_tel: "02-1234-1234", + m_redirect_url: "{모바일에서 결제 완료 후 리디렉션 될 URL}", + notice_url: "{빌링키 발급 결과를 받을 URL}", + }, + function (rsp) { + // callback 로직 + }, + ); ```
@@ -187,23 +191,20 @@ import Tab from "~/components/gitbook/tabs/Tab.astro"; **`빌링키 발급 완료 웹훅 전달 URL`** 빌링키 발급이 완료됐을 때 웹훅이 전달될 URL입니다. 해당 파라미터가 전달되지 않은 경우 콘솔에 등록한 웹훅 주소로 웹훅이 발송됩니다. **(신) 토스페이의 경우 SDK 콜백만으로 빌링키 발급여부를 체크하는 경우 정보 유실 가능성이 있기 때문에, 반드시 웹훅으로 빌링키 발급여부를 체크하길 권장합니다**. -
- **빌링키로 결제 요청하기** 빌링키 발급 시 전달한 `customer_uid`를 이용해서 재결제([**POST /subscribe/payments/again**](../../api/api-4/api)) REST API를 다음과 같이 호출합니다. + ```javascript - await fetch( - 'https://api.iamport.kr/subscribe/payments/again', - { - method: 'POST', - headers: { + await fetch("https://api.iamport.kr/subscribe/payments/again", { + method: "POST", + headers: { Authorization: `Basic ${ACCESS_TOKEN}`, - 'Content-Type': 'application/json', + "Content-Type": "application/json", }, body: JSON.stringify({ customer_uid: "customer_uid", // [필수 입력] 빌링키 발급시 전달 한 빌링키와 1:1 매핑되는 ID @@ -214,22 +215,23 @@ import Tab from "~/components/gitbook/tabs/Tab.astro"; bypass: JSON.stringify({ tosspay_v2: { cashReceiptTradeType: "GENERAL", // 현금영수증 발급 대상 타입 - sendFailPush: false // 결제 실패 시 토스페이앱 푸시알람 발송 여부 - } - }) - }) - ) + sendFailPush: false, // 결제 실패 시 토스페이앱 푸시알람 발송 여부 + }, + }), + }), + }); ``` ### (신) 토스페이 빌링키 결제 전용 파라미터 - `bypass` 에 json string 형태로 설정되어야 합니다. + `bypass` 에 json string 형태로 설정되어야 합니다. **`tosspay_v2.cashReceiptTradeOption`** **string** **현금영수증 발급 대상 타입** + - `GENERAL`: 일반 (default) - `CULTURE`: 문화비 - `PUBLIC_TP`: 교통비 @@ -237,8 +239,8 @@ import Tab from "~/components/gitbook/tabs/Tab.astro"; **`tosspay_v2.cashReceiptTradeOption`** **boolean** **결제실패 푸시알람 사용 여부** + - `false`: 미사용 (default) - `true`: 사용 - diff --git a/src/content/docs/ko/platform/api.mdx b/src/content/docs/ko/platform/api.mdx index 2f4d232ea..0302588b7 100644 --- a/src/content/docs/ko/platform/api.mdx +++ b/src/content/docs/ko/platform/api.mdx @@ -3,8 +3,6 @@ title: 파트너정산 API description: 파트너정산에 관련된 API 를 확인할 수 있습니다 --- -import Details from "~/components/gitbook/Details.astro"; - ## 서문 안녕하세요. 포트원 PO 김준일입니다. @@ -26,39 +24,35 @@ openapi.yaml 파일 혹은 graphql로 개발하시길 희망하실 경우 편하 ## 정산 -
-
- -고객의 주문(order-transfer) 와 주문취소(order-cancel-transfer)로 부터 계약 규칙에 맞게 파생되는 정산금과 수동으로(manual-transfer) 임의의 정산금액을 등록할 수 있습니다. 고객의 주문건에 대해서는 결제/환불 모두 적용할 수 있습니다. - -
-
- -**Endpoints** - -```text -POST /platform/transfers/order -POST /platform/transfers/order-cancel -POST /platform/transfers/manual -GET /platform/transfers/{id} -GET /platform/transfer-sumaries -GET /platform/transfer-dashbaord -GET /platform/transfer-filter-options -``` +
+
+ 고객의 주문(order-transfer) 와 주문취소(order-cancel-transfer)로 부터 계약 규칙에 맞게 파생되는 정산금과 수동으로(manual-transfer) 임의의 정산금액을 등록할 수 있습니다. 고객의 주문건에 대해서는 결제/환불 모두 적용할 수 있습니다. +
-
+
+ **Endpoints** + + ```text + POST /platform/transfers/order + POST /platform/transfers/order-cancel + POST /platform/transfers/manual + GET /platform/transfers/{id} + GET /platform/transfer-sumaries + GET /platform/transfer-dashbaord + GET /platform/transfer-filter-options + ``` +
### 정산 객체 정산 생성 및 조회시 response 로 반환되는 transfer 객체의 파라미터 별 설명입니다. -
-
- -**Attributes** -**type** enum -정산 타입 +
+
+ **Attributes** + **type** enum + 정산 타입 |Enum Value |Description | |------------|--------------| @@ -66,29 +60,29 @@ GET /platform/transfer-filter-options |ORDER_CANCEL|주문 취소 정산| |MANUAL |수동 정산 | ---- + --- -**id** string + **id** string -정산 객체 아이디 + 정산 객체 아이디 ---- + --- -**graphqlId** string + **graphqlId** string -포트원 내부에서 사용되는 정산 객체 graphql 아이디. 혹시 graphql을 더 선호하신다면 연락 부탁드립니다. + 포트원 내부에서 사용되는 정산 객체 graphql 아이디. 혹시 graphql을 더 선호하신다면 연락 부탁드립니다. ---- + --- -**partner** dictionary + **partner** dictionary -정산의 대상이 되는 파트너 객체 + 정산의 대상이 되는 파트너 객체 -[partner attribute](#파트너-객체) + [partner attribute](#파트너-객체) -**status** enum + **status** enum -정산의 상태값 + 정산의 상태값 |Enum Value|Description | |----------|------------------------------------------------------------------------------------------------------| @@ -98,654 +92,636 @@ GET /platform/transfer-filter-options |IN_PAYOUT |이체 중. 관리자 콘솔 내에서 대량이체 엑셀 파일을 받은 후 아직 이체완료 상태값 업데이트를 하지 않았을때| |PAID_OUT |이체 완료 상태 | ---- - -**memo** string - -정산에 대한 메모. 수동 정산(manual)에만 해당됩니다. - ---- - -**settlementDate** string + --- -정산일. 정산주기에 맞게 파트너에게 이체되어야 하는 시점이다. + **memo** string -`yyyy-MM-dd` 형식을 따릅니다. + 정산에 대한 메모. 수동 정산(manual)에만 해당됩니다. ---- + --- -**payoutId** string + **settlementDate** string -정산 객체가 정산주기에 맞춰서 포함될 이체 객체의 고유 아이디 + 정산일. 정산주기에 맞게 파트너에게 이체되어야 하는 시점이다. -status 가 IN_PAYOUT 일때부터 생성됩니다성 + `yyyy-MM-dd` 형식을 따릅니다. ---- + --- -**payoutGraphqlID** string + **payoutId** string -payoutId의 내부 graphql 아이디 + 정산 객체가 정산주기에 맞춰서 포함될 이체 객체의 고유 아이디 ---- + status 가 IN\_PAYOUT 일때부터 생성됩니다성 -**contract** dictionary + --- -정산에 적용되는 계약 객체 + **payoutGraphqlID** string -[contract entity](#계약-객체) + payoutId의 내부 graphql 아이디 ---- + --- -**isForTest** boolean + **contract** dictionary -테스트용 정산인지 여부. false 일때 실제 정산입니다. + 정산에 적용되는 계약 객체 -**amount** dictionary -정산 금액 정보 + [contract entity](#계약-객체) - - - +
+ --- - amount.**settlement** int64 + **isForTest** boolean - 계산된 정산금액. + 테스트용 정산인지 여부. false 일때 실제 정산입니다. - 기본적으로 `주문금액 - 플랫폼_중계_수수료 - 중계_수수료_부가세 - PG사_수수료 - PG사_수수료_부가세- 할인분담금 - 추가수수료 - 추가수수료_부가세` 로 계산됩니다. + **amount** dictionary + 정산 금액 정보 - 수식설정을 통해 계산법을 변경하실 수 있습니다. 수식 설정은 관리자 콘솔에서 가능합니다. -
+ + - - - - - + - amount.**order** int64 + + - - - + - amount.**platformFee** int64 + + + - + + - - + - amount.**platformFeeVat** int64 + + - - - + - amount.**additionalFee** int64 + + - - - + - amount.**additionalFeeVat** int64 + + - - - + - amount.**discountShare** int64 + + - - - + - amount.**discount** int64 + + - -
+ amount.**settlement** int64 -
+ 계산된 정산금액. - amount.**payment** int64 + 기본적으로 `주문금액 - 플랫폼_중계_수수료 - 중계_수수료_부가세 - PG사_수수료 - PG사_수수료_부가세- 할인분담금 - 추가수수료 - 추가수수료_부가세` 로 계산됩니다. - 결제금액. -
+ 수식설정을 통해 계산법을 변경하실 수 있습니다. 수식 설정은 관리자 콘솔에서 가능합니다. +
+ amount.**payment** int64 - 주문금액. 주문금액 = 결제금액 + 할인금액 으로 통상적으로 계산됩니다. -
+ 결제금액. +
+ amount.**order** int64 - 계산된 플랫폼 중개 수수료. 기본적으로 contractId 에 해당되는 수수료가 주문금액에 적용됩니다. 수식설정을 통해 계산법을 변경하실 수 있습니다. + 주문금액. 주문금액 = 결제금액 + 할인금액 으로 통상적으로 계산됩니다. +
+ amount.**platformFee** int64 -
+ 계산된 플랫폼 중개 수수료. 기본적으로 contractId 에 해당되는 수수료가 주문금액에 적용됩니다. 수식설정을 통해 계산법을 변경하실 수 있습니다. +
+ amount.**platformFeeVat** int64 - 계산된 중개수수료 부가세. 기본적으로 중개 수수료의 10% 의 내림처리입니다. 수식설정을 통해 소수점 처리를 변경하실 수 있습니다. -
+ 계산된 중개수수료 부가세. 기본적으로 중개 수수료의 10% 의 내림처리입니다. 수식설정을 통해 소수점 처리를 변경하실 수 있습니다. +
+ amount.**additionalFee** int64 - 계산된 추가 수수료. 기본적으로 additionalFeeIds 에 해당되는 추가 수수료가 주문금액에 적용됩니다. 수식설정을 통해 계산법을 변경하실 수 있습니다. -
+ 계산된 추가 수수료. 기본적으로 additionalFeeIds 에 해당되는 추가 수수료가 주문금액에 적용됩니다. 수식설정을 통해 계산법을 변경하실 수 있습니다. +
+ amount.**additionalFeeVat** int64 - 계산된 추가 수수료 부가세. 기본적으로 추가 수수료의 10% 의 내림처리입니다. 수식설정을 통해 소수점 처리를 변경하실 수 있습니다. -
+ 계산된 추가 수수료 부가세. 기본적으로 추가 수수료의 10% 의 내림처리입니다. 수식설정을 통해 소수점 처리를 변경하실 수 있습니다. +
+ amount.**discountShare** int64 - 계산된 파트너 할인 분담 금액. discountShareId 의 분담율이 적용됩니다. -
+ 계산된 파트너 할인 분담 금액. discountShareId 의 분담율이 적용됩니다. +
+ amount.**discount** int64 - 할인금 -
+ 할인금 + + + ---- + --- -**payment** dictionary + **payment** dictionary -주문 정산건에 해당되는 결제 정보. 포트원(Portone) 결제일때 와 외부 결제(External) 일때 요구되는 값이 다릅니다. -해당 값은 one of 로직으로 간주되어 `"payment": { "type" : "INTERNAL" 혹은 "EXTERNAL"}` 와 같이 전달해야 합니다. + 주문 정산건에 해당되는 결제 정보. 포트원(Portone) 결제일때 와 외부 결제(External) 일때 요구되는 값이 다릅니다. + 해당 값은 one of 로직으로 간주되어 `"payment": { "type" : "INTERNAL" 혹은 "EXTERNAL"}` 와 같이 전달해야 합니다. - - - - + + +
+ + + - - - - - - - - - - - - - - - - - - - + -
payment.**type** string required 결제 타입. 포트원 결제일때는 "INTERNAL" 입니다. -
- - payment.**id** string required - - merchant_uid(V1) 혹은 payment_id(V2) - - 혹여나 주문은 이루어 졌지만 결제가 이루어지지 않은 경우가 있습니다. 대표적인 예로 포인트 및 쿠폰 (할인) 으로 상품을 사는 case 입니다. - 해당 경우에는 포트원 결제는 없어도 고객사 내에서 해당 주문에 대한 주문 아이디를 전달해주셔야 합니다. -
- payment.**storeId** string - - 포트원 고객사의 스토어 아이디. 관리자 콘솔에서 확인하실 수 있습니다. - - 포트원 결제일때만 반환됩니다. - -
- payment.**channelKey** string - - 포트원 결제시 사용된 채널키. 관리자 콘솔에서 확인하실 수 있습니다. - - 포트원 결제일때만 반환됩니다. -
- payment.**orderName** string - - 주문명. 임의로 전달해주실 수 있습니다. -
- payment.**method** dicionary - - 주문건의 결제수단 - 아래 결제 수단중 하나만 택해서 전달해야 합니다. - 간편 결제수단("easyPay") 를 제외하고 특정 결제수단에 해당된다면 빈 json 값 (```{}```) 을 전달해야 합니다. +
- - + + - - - - + + - - - - + + - - - - + + - 상품권 + + - - - + - - -
+
+ payment.**id** string required - method.**card** dictionary optional + merchant\_uid(V1) 혹은 payment\_id(V2) - 신용카드 + 혹여나 주문은 이루어 졌지만 결제가 이루어지지 않은 경우가 있습니다. 대표적인 예로 포인트 및 쿠폰 (할인) 으로 상품을 사는 case 입니다. + 해당 경우에는 포트원 결제는 없어도 고객사 내에서 해당 주문에 대한 주문 아이디를 전달해주셔야 합니다. +
+
+ payment.**storeId** string - method.**transfer** dictionary optional + 포트원 고객사의 스토어 아이디. 관리자 콘솔에서 확인하실 수 있습니다. - 계좌이체 + 포트원 결제일때만 반환됩니다. +
+
+ payment.**channelKey** string - method.**virtualAccount** dictionary optional + 포트원 결제시 사용된 채널키. 관리자 콘솔에서 확인하실 수 있습니다. - 가상계좌 + 포트원 결제일때만 반환됩니다. +
+
+ payment.**orderName** string - method.**giftCertificate** dictionary optional + 주문명. 임의로 전달해주실 수 있습니다. +
+ payment.**method** dicionary -
+ 주문건의 결제수단 + 아래 결제 수단중 하나만 택해서 전달해야 합니다. + 간편 결제수단("easyPay") 를 제외하고 특정 결제수단에 해당된다면 빈 json 값 (`{}`) 을 전달해야 합니다. - method.**mobile** dictionary optional + + + + - - - - + + - 간편결제 -
+ method.**card** dictionary optional - 휴대폰 소액결제 + 신용카드 +
+
+ method.**transfer** dictionary optional - method.**easyPay** dictionary optional + 계좌이체 +
- - + + - 간편결제 브랜드 (i.e. "KAKAOPAY") + + - - - + - easyPay.**method** enum + + - -
+
+ method.**virtualAccount** dictionary optional - easyPay.**provider** enum + 가상계좌 +
+ method.**giftCertificate** dictionary optional -
+ 상품권 +
+ method.**mobile** dictionary optional - 간편결제 내의 결제 수단 (i.e. "CARD", "TRANSFER") -
+ 휴대폰 소액결제 +
-
+
+ method.**easyPay** dictionary optional - payment.**currency** enum + 간편결제 - 외부 결제연동 서비스를 통해 결제된 주문건의 결제통화 + + + + - + + + 간편결제 내의 결제 수단 (i.e. "CARD", "TRANSFER") + + +
+ easyPay.**provider** enum - 현재는 'KRW', 'JPY', 'USD' 만 지원합니다. + 간편결제 브랜드 (i.e. "KAKAOPAY") +
+ easyPay.**method** enum -
+
- + + + payment.**currency** enum - - - + 외부 결제연동 서비스를 통해 결제된 주문건의 결제통화 - payment.**paidAt** Date + 현재는 'KRW', 'JPY', 'USD' 만 지원합니다. + + + + - 결제 완료 시점 - + + + payment.**paidAt** Date - - + 결제 완료 시점 + + + ---- + --- -**settlementStartDate** Date + **settlementStartDate** Date -정산 시작일. 정산주기에 맞춰서 정산이 진행되는 시점이다. 정산 주기가 적용되는 시점이다. + 정산 시작일. 정산주기에 맞춰서 정산이 진행되는 시점이다. 정산 주기가 적용되는 시점이다. ---- + --- -**orderDetails** dictionary required + **orderDetails** dictionary required -주문 정산건에 해당되는 주문 상세 정보. 주문건에 포함된 상품의 정보를 전달해야 합니다. + 주문 정산건에 해당되는 주문 상세 정보. 주문건에 포함된 상품의 정보를 전달해야 합니다. -one of 로직으로써 단순히 주문금액만 전달하고 싶으신 경우에는 `"orderDetails" : {"orderAmount": 금액}` 와 같이 전달하시면 됩니다. -상품 정보 및 상품별 할인 및 추가수수료를 적용하여 전달하고 싶으신 경우에는 `"orderDetails" : {"orderLines": [{...}, {...}]}` 와 같이 전달하시면 됩니다. + one of 로직으로써 단순히 주문금액만 전달하고 싶으신 경우에는 `"orderDetails" : {"orderAmount": 금액}` 와 같이 전달하시면 됩니다. + 상품 정보 및 상품별 할인 및 추가수수료를 적용하여 전달하고 싶으신 경우에는 `"orderDetails" : {"orderLines": [{...}, {...}]}` 와 같이 전달하시면 됩니다. -**payment.type = INTERNAL** 일경우 전달하시지 않으셔도 됩니다. 그럴경우 주문금액은 주어진 **payment.id** 에 해당되는 결제금액 + **discounts.amount** 의 합에 해당되는 할인금액 으로 계산됩니다. + **payment.type = INTERNAL** 일경우 전달하시지 않으셔도 됩니다. 그럴경우 주문금액은 주어진 **payment.id** 에 해당되는 결제금액 + **discounts.amount** 의 합에 해당되는 할인금액 으로 계산됩니다. -- 주문금액만 전달할 경우 (`"orderDetails": {"orderAmount": 금액}`) + - 주문금액만 전달할 경우 (`"orderDetails": {"orderAmount": 금액}`) - - - + - 상품 정보 및 상품별 금액, 수량 할인 및 추가수수료를 적용하여 전달할 경우 (`"orderDetails": {"orderLines": [{...}, {...}]}`) - -
+ + + + +
+ **orderAmount** int optional - **orderAmount** int optional + 정산건에 해당되는 주문금액. 결제금액 + 할인금액 입니다. - 정산건에 해당되는 주문금액. 결제금액 + 할인금액 입니다. + 단일 주문건에 정산해야할 파트너 대상이 여러명일 경우, 혹은 다른 이유로 여러 정산 건을 생성하고 싶을 경우, 해당되는 주문금액을 전달하시면 됩니다. - 단일 주문건에 정산해야할 파트너 대상이 여러명일 경우, 혹은 다른 이유로 여러 정산 건을 생성하고 싶을 경우, 해당되는 주문금액을 전달하시면 됩니다. + 전달하지 기본값은 주어진 **payment.portOne.id** 에 해당되는 결제금액 + **discounts.amount** 의 합에 해당되는 할인금액 입니다. - 전달하지 기본값은 주어진 **payment.portOne.id** 에 해당되는 결제금액 + **discounts.amount** 의 합에 해당되는 할인금액 입니다. + **payment.external** 일때는 **orderAmount** 혹은 **orderLines** 를 통해서 주문금액을 전달해주셔야 합니다. +
- **payment.external** 일때는 **orderAmount** 혹은 **orderLines** 를 통해서 주문금액을 전달해주셔야 합니다. -
+ 해당 정보를 전달하면 주문금액은 전체 상품별 금액들의 합으로 계산됩니다. -- 상품 정보 및 상품별 금액, 수량 할인 및 추가수수료를 적용하여 전달할 경우 (`"orderDetails": {"orderLines": [{...}, {...}]}`) + + + - - + 리스트의 각 객체별 단일 할인에 해당된다. - -
+ orderLines.**product** dictionary required -해당 정보를 전달하면 주문금액은 전체 상품별 금액들의 합으로 계산됩니다. + 주문정산건에 해당되는 낱개 상품 정보. - - - + - 상품 이름. 고객사의 서버에 등록된 상품 이름을 임의로 보내주시면 됩니다. + + + 상품 갯수 + + - - - + + - 상품 가격. 상품의 낱개 가격입니다. + + + 해당 상품에 적용된 추가수수료 정책 리스트. 포트원에 등록된 추가수수료 아이디를 보내주시면 됩니다. 해당 아이디의 추가수수료가 정산에 적용됩니다. + [추가수수료 참고](#추가-수수료-객체)] + + +
- orderLines.**product** dictionary required + + + + -
+ product.**id** string required - 주문정산건에 해당되는 낱개 상품 정보. + 상품 아이디. 고객사의 서버에 등록된 상품 아이디를 임의로 보내주시면 됩니다. +
- - + + - 상품 아이디. 고객사의 서버에 등록된 상품 아이디를 임의로 보내주시면 됩니다. + + + 상품 가격. 상품의 낱개 가격입니다. + + - - - + + +
+
+ product.**name** string required - product.**id** string required + 상품 이름. 고객사의 서버에 등록된 상품 이름을 임의로 보내주시면 됩니다. +
+ product.**amount** int required -
+
+ product.**tag** list of string optional - product.**name** string required + 상품 태그. 내부 구분을 위한 태그입니다. +
+
+ orderLines.**quantity** int required -
+
+ orderLines.**discounts** list of dictionary optional - product.**amount** int required + 해당 상품에 적용될 할인정보 리스트 + [할인 정책 참고](#할인-유형) +
+ orderLines.**additionalFees** list of dictionary optional -
-
+ --- - product.**tag** list of string optional + **discounts** list of dictionary - 상품 태그. 내부 구분을 위한 태그입니다. + 할인 금액과 유형 (discountShares) 객체의 리스트 -
- + 해당 값들은 전체 주문건에 대해서 적용된다. 상품별 적용이 아니다. - - - - orderLines.**quantity** int required + [할인 정책 참고](#할인-유형) - 상품 갯수 + + + - - - + - 해당 상품에 적용될 할인정보 리스트 - [할인 정책 참고](#할인-유형) - - - - + - + 할인 정책 (sharePolicy) 객체 -
+ discounts.**amount** int64 -
- orderLines.**discounts** list of dictionary optional + 할인 금액 +
- orderLines.**additionalFees** list of dictionary optional +
+ discounts.**sharePolicy** dictionary - 해당 상품에 적용된 추가수수료 정책 리스트. 포트원에 등록된 추가수수료 아이디를 보내주시면 됩니다. 해당 아이디의 추가수수료가 정산에 적용됩니다. - [추가수수료 참고](#추가-수수료-객체)] -
+ + + + -**discounts** list of dictionary + + + -리스트의 각 객체별 단일 할인에 해당된다. + + + -[할인 정책 참고](#할인-유형) + + + +
+ sharePolicy.**id** string ---- + 할인 정책 객체 고유 아이디 +
+ sharePolicy.**partnerShareRate** int64 -할인 금액과 유형 (discountShares) 객체의 리스트 + 할인 분담율 +
+ sharePolicy.**memo** string -해당 값들은 전체 주문건에 대해서 적용된다. 상품별 적용이 아니다. + 할인유형 객체 고객사 지정 내부 메모 +
+ sharePolicy.**isHidden** boolean - - - + - discounts.**amount** int64 + + + +
+ 할인유형 객체 숨김 여부 +
+ sharePolicy.**appliedAt** Date - 할인 금액 + 할인유형 객체 적용 시간 +
+
- + --- - - - + **additionalFees** list of dictionary - discounts.**sharePolicy** dictionary + 추가수수료 (additionalFee) 객체의 리스트 - 할인 정책 (sharePolicy) 객체 + 해당 값들은 전체 주문건에 대해서 적용된다. 상품별 적용이 아니다. - - - - - - - -
+ [추가 수수료 참고](#추가-수수료) - sharePolicy.**id** string + - additionalFee attributes - 할인 정책 객체 고유 아이디 + + + - - - + +
+ additionalFee.**policy** dictionary -
+ 추가수수료 정책 (additionalFeePolicy) 객체 - sharePolicy.**partnerShareRate** int64 + + + + - - - - + + +
+ policy.**id** string - 할인 분담율 + 추가수수료 정책 객체 고유 아이디 +
+
+ policy.**fee** dictionary - sharePolicy.**memo** string + 추가수수료 정책 객체 수수료 - 할인유형 객체 고객사 지정 내부 메모 + + + - - - + - sharePolicy.**isHidden** boolean + + + +
+ fee.**amount** int64 -
+ 추가수수료 정책 객체 수수료 정액 금액 +
+ fee.**rate** int64 - 할인유형 객체 숨김 여부 + 추가수수료 정책 객체 수수료 비율 + 1\*10^5 으로써 10% 일경우 100000 으로 입력 +
+
+
-
+ --- + - sharePolicy.**appliedAt** Date +
+ **Response (주문 정산예시)** - 할인유형 객체 적용 시간 - -
- - - - - ---- - -**additionalFees** list of dictionary - -추가수수료 (additionalFee) 객체의 리스트 - -해당 값들은 전체 주문건에 대해서 적용된다. 상품별 적용이 아니다. - -[추가 수수료 참고](#추가-수수료) - -- additionalFee attributes - - - - - - -
- - additionalFee.**policy** dictionary - - 추가수수료 정책 (additionalFeePolicy) 객체 - - - - - - - -
- - policy.**id** string - - 추가수수료 정책 객체 고유 아이디 - -
- - policy.**fee** dictionary - - 추가수수료 정책 객체 수수료 - - - - - - - - -
- - fee.**amount** int64 - - 추가수수료 정책 객체 수수료 정액 금액 -
- - fee.**rate** int64 - - 추가수수료 정책 객체 수수료 비율 - 1*10^5 으로써 10% 일경우 100000 으로 입력 -
- -
- -
- ---- - -
-
- -**Response (주문 정산예시)** - -```json -{ - "transfer": { - "type": "ORDER", - "id": "01H7HVM3YYCYQC3HF6KN4VZYZ2", - "graphqlId": "NjowMUg3SFZNM1lZQ1lRQzNIRjZLTjRWWllaMg==", - "partner": { - "id": "partner_2", - "graphqlId": "NDpwYXJ0bmVyXzI=", - "name": "파이썬 강사", - "email": "kjnkyj12@gmail.com", - "businessRegistrationNumber": "1178178260", - "account": { - "bank": "SHINHAN", - "currency": "KRW", - "number": "10358907249", - "holder": "김준일", - "status": "VERIFIED" - }, - "status": "APPROVED", - "defaultContractId": "contract_2", - "memo": "잭슨 테스트", - "tags": ["파이썬"], - "isHidden": false, - "appliedAt": "2023-08-09T07:39:25.645014Z" - }, - "status": "IN_PROCESS", - "memo": "testing order transfer", - "settlementDate": "2023-08-18", - "settlementCurrency": "KRW", - "isForTest": true, - "amount": { - "settlement": 17250, - "payment": 20000, - "order": 25000, - "platformFee": 2500, - "platformFeeVat": 0, - "additionalFee": 2500, - "additionalFeeVat": 250, - "discount": 5000, - "discountShare": 2500 - }, - "contract": { - "id": "contract_2", - "graphqlId": "NTpjb250cmFjdF8y", - "memo": "contract 2", - "platformFee": { "type": "FIXED_RATE", "rate": 10000 }, - "settlementCycle": { - "lagDays": 2, - "datePolicy": "CALENDAR_DAY", - "method": { "type": "WEEKLY", "daysOfWeek": ["FRI"] } - }, - "platformFeeVatPayer": "MERCHANT", - "isHidden": false, - "appliedAt": "2023-08-09T07:39:17.207733Z" - }, - "payment": { - "type": "EXTERNAL", - "id": "payment_1", - "orderName": "테스트 주문", - "currency": "KRW", - "method": { "type": "CARD" }, - "paidAt": "2023-08-11T08:21:01.241Z" - }, - "settlementStartDate": "2023-08-11", - "orderLines": [ - { - "product": { "id": "1", "name": "product_1", "amount": 5000 }, - "quantity": 5, - "discounts": [ + ```json + { + "transfer": { + "type": "ORDER", + "id": "01H7HVM3YYCYQC3HF6KN4VZYZ2", + "graphqlId": "NjowMUg3SFZNM1lZQ1lRQzNIRjZLTjRWWllaMg==", + "partner": { + "id": "partner_2", + "graphqlId": "NDpwYXJ0bmVyXzI=", + "name": "파이썬 강사", + "email": "kjnkyj12@gmail.com", + "businessRegistrationNumber": "1178178260", + "account": { + "bank": "SHINHAN", + "currency": "KRW", + "number": "10358907249", + "holder": "김준일", + "status": "VERIFIED" + }, + "status": "APPROVED", + "defaultContractId": "contract_2", + "memo": "잭슨 테스트", + "tags": ["파이썬"], + "isHidden": false, + "appliedAt": "2023-08-09T07:39:25.645014Z" + }, + "status": "IN_PROCESS", + "memo": "testing order transfer", + "settlementDate": "2023-08-18", + "settlementCurrency": "KRW", + "isForTest": true, + "amount": { + "settlement": 17250, + "payment": 20000, + "order": 25000, + "platformFee": 2500, + "platformFeeVat": 0, + "additionalFee": 2500, + "additionalFeeVat": 250, + "discount": 5000, + "discountShare": 2500 + }, + "contract": { + "id": "contract_2", + "graphqlId": "NTpjb250cmFjdF8y", + "memo": "contract 2", + "platformFee": { "type": "FIXED_RATE", "rate": 10000 }, + "settlementCycle": { + "lagDays": 2, + "datePolicy": "CALENDAR_DAY", + "method": { "type": "WEEKLY", "daysOfWeek": ["FRI"] } + }, + "platformFeeVatPayer": "MERCHANT", + "isHidden": false, + "appliedAt": "2023-08-09T07:39:17.207733Z" + }, + "payment": { + "type": "EXTERNAL", + "id": "payment_1", + "orderName": "테스트 주문", + "currency": "KRW", + "method": { "type": "CARD" }, + "paidAt": "2023-08-11T08:21:01.241Z" + }, + "settlementStartDate": "2023-08-11", + "orderLines": [ { - "sharePolicy": { - "id": "discount_1", - "graphqlId": "MjpkaXNjb3VudF8x", - "partnerShareRate": 500000000, - "memo": "테스트 할인", - "isHidden": false, - "appliedAt": "2023-08-09T07:45:45.799176Z" - }, - "amount": 2500, - "shareAmount": 1250 + "product": { "id": "1", "name": "product_1", "amount": 5000 }, + "quantity": 5, + "discounts": [ + { + "sharePolicy": { + "id": "discount_1", + "graphqlId": "MjpkaXNjb3VudF8x", + "partnerShareRate": 500000000, + "memo": "테스트 할인", + "isHidden": false, + "appliedAt": "2023-08-09T07:45:45.799176Z" + }, + "amount": 2500, + "shareAmount": 1250 + } + ], + "additionalFees": [ + { + "policy": { + "id": "addtional_fee_1", + "graphqlId": "MzphZGR0aW9uYWxfZmVlXzE=", + "fee": { "type": "FIXED_RATE", "rate": 5000 }, + "memo": "테스트 추가수수료", + "vatPayer": "PARTNER", + "isHidden": false, + "appliedAt": "2023-08-09T07:41:12.393974Z" + }, + "amount": 1250, + "vat": 125 + } + ], + "amount": { + "settlement": 19875, + "payment": 22500, + "order": 25000, + "platformFee": 2500, + "platformFeeVat": 0, + "additionalFee": 1250, + "additionalFeeVat": 125, + "discount": 2500, + "discountShare": 1250 + } } ], "additionalFees": [ @@ -763,53 +739,24 @@ one of 로직으로써 단순히 주문금액만 전달하고 싶으신 경우 "vat": 125 } ], - "amount": { - "settlement": 19875, - "payment": 22500, - "order": 25000, - "platformFee": 2500, - "platformFeeVat": 0, - "additionalFee": 1250, - "additionalFeeVat": 125, - "discount": 2500, - "discountShare": 1250 - } - } - ], - "additionalFees": [ - { - "policy": { - "id": "addtional_fee_1", - "graphqlId": "MzphZGR0aW9uYWxfZmVlXzE=", - "fee": { "type": "FIXED_RATE", "rate": 5000 }, - "memo": "테스트 추가수수료", - "vatPayer": "PARTNER", - "isHidden": false, - "appliedAt": "2023-08-09T07:41:12.393974Z" - }, - "amount": 1250, - "vat": 125 - } - ], - "discounts": [ - { - "sharePolicy": { - "id": "discount_1", - "graphqlId": "MjpkaXNjb3VudF8x", - "partnerShareRate": 500000000, - "memo": "테스트 할인", - "isHidden": false, - "appliedAt": "2023-08-09T07:45:45.799176Z" - }, - "amount": 2500, - "shareAmount": 1250 + "discounts": [ + { + "sharePolicy": { + "id": "discount_1", + "graphqlId": "MjpkaXNjb3VudF8x", + "partnerShareRate": 500000000, + "memo": "테스트 할인", + "isHidden": false, + "appliedAt": "2023-08-09T07:45:45.799176Z" + }, + "amount": 2500, + "shareAmount": 1250 + } + ] } - ] - } -} -``` - -
+ } + ``` +
--- @@ -818,539 +765,542 @@ one of 로직으로써 단순히 주문금액만 전달하고 싶으신 경우 `POST https://api.portone.io/platform/transfers/order` -
-
+
+
+ 주문 정산건이란 결제를 기반으로 한 주문건에 대해서 각 파트너에게 정산해주기 위한 정산객체를 api로 등록하는 겁니다. -주문 정산건이란 결제를 기반으로 한 주문건에 대해서 각 파트너에게 정산해주기 위한 정산객체를 api로 등록하는 겁니다. + **Parameters** -**Parameters** + **partnerId** string required -**partnerId** string required + 주문 정산건에 해당되는 파트너 지정 -주문 정산건에 해당되는 파트너 지정 + --- ---- + **contractId** string optional -**contractId** string optional + 주문 정산건에 적용될 계약의 아이디. 기본으로 정산될 파트너의 기본 계약이 적용되지만 **contractId** 를 통해 다른 계약을 지정할 경우 지정된 계약의 정보가 적용된다. -주문 정산건에 적용될 계약의 아이디. 기본으로 정산될 파트너의 기본 계약이 적용되지만 **contractId** 를 통해 다른 계약을 지정할 경우 지정된 계약의 정보가 적용된다. + --- ---- + **memo** string optional -**memo** string optional + 정산건에 내부 구분을 위한 메모 -정산건에 내부 구분을 위한 메모 + --- ---- + **paymentId** dictionary required -**paymentId** dictionary required + 고객사 주문 아이디. 포트원 결제일 경우 포트원 결제에 전달해주시는 merchant\_uid (v1) 혹은 payment\_id(v2) 를 전달하셔야 합니다. + 외부결제 일 경우 단순히 고객사 주문번호를 전달해주시면 됩니다. -고객사 주문 아이디. 포트원 결제일 경우 포트원 결제에 전달해주시는 merchant_uid (v1) 혹은 payment_id(v2) 를 전달하셔야 합니다. -외부결제 일 경우 단순히 고객사 주문번호를 전달해주시면 됩니다. + --- ---- + **orderDetails** dictionary required -**orderDetails** dictionary required + 주문 정산건에 해당되는 주문 상세 정보. 주문건에 포함된 상품의 정보를 전달해야 합니다. -주문 정산건에 해당되는 주문 상세 정보. 주문건에 포함된 상품의 정보를 전달해야 합니다. + one of 로직으로써 단순히 주문금액만 전달하고 싶으신 경우에는 `"orderDetails" : {"orderAmount": 금액}` 와 같이 전달하시면 됩니다. + 상품 정보 및 상품별 할인 및 추가수수료를 적용하여 전달하고 싶으신 경우에는 `"orderDetails" : {"orderLines": [{...}, {...}]}` 와 같이 전달하시면 됩니다. -one of 로직으로써 단순히 주문금액만 전달하고 싶으신 경우에는 `"orderDetails" : {"orderAmount": 금액}` 와 같이 전달하시면 됩니다. -상품 정보 및 상품별 할인 및 추가수수료를 적용하여 전달하고 싶으신 경우에는 `"orderDetails" : {"orderLines": [{...}, {...}]}` 와 같이 전달하시면 됩니다. + **payment.portOne** 일경우 전달하시지 않으셔도 됩니다. 그럴경우 주문금액은 주어진 **payment.portOne.id** 에 해당되는 결제금액 + **discounts.amount** 의 합에 해당되는 할인금액 으로 계산됩니다. -**payment.portOne** 일경우 전달하시지 않으셔도 됩니다. 그럴경우 주문금액은 주어진 **payment.portOne.id** 에 해당되는 결제금액 + **discounts.amount** 의 합에 해당되는 할인금액 으로 계산됩니다. + - 주문금액만 전달할 경우 (`"orderDetails": {"orderAmount": 금액}`) -- 주문금액만 전달할 경우 (`"orderDetails": {"orderAmount": 금액}`) + + + + 해당 정보를 전달하면 주문금액은 전체 상품별 금액들의 합으로 계산됩니다. - -
+ **orderAmount** int optional - - - + +
+ 정산건에 해당되는 주문금액. 결제금액 + 할인금액 입니다. - **orderAmount** int optional + 단일 주문건에 정산해야할 파트너 대상이 여러명일 경우, 혹은 다른 이유로 여러 정산 건을 생성하고 싶을 경우, 해당되는 주문금액을 전달하시면 됩니다. - 정산건에 해당되는 주문금액. 결제금액 + 할인금액 입니다. + 전달하지 기본값은 주어진 **payment.portOne.id** 에 해당되는 결제금액 + **discounts.amount** 의 합에 해당되는 할인금액 입니다. - 단일 주문건에 정산해야할 파트너 대상이 여러명일 경우, 혹은 다른 이유로 여러 정산 건을 생성하고 싶을 경우, 해당되는 주문금액을 전달하시면 됩니다. + **payment.external** 일때는 **orderAmount** 혹은 **orderLines** 를 통해서 주문금액을 전달해주셔야 합니다. +
- 전달하지 기본값은 주어진 **payment.portOne.id** 에 해당되는 결제금액 + **discounts.amount** 의 합에 해당되는 할인금액 입니다. + - 상품 정보 및 상품별 금액, 수량 할인 및 추가수수료를 적용하여 전달할 경우 (`"orderDetails": {"orderLines": [{...}, {...}]}`) - **payment.external** 일때는 **orderAmount** 혹은 **orderLines** 를 통해서 주문금액을 전달해주셔야 합니다. -
+ + + + +
+ orderLines.**product** dictionary required -- 상품 정보 및 상품별 금액, 수량 할인 및 추가수수료를 적용하여 전달할 경우 (`"orderDetails": {"orderLines": [{...}, {...}]}`) + 주문정산건에 해당되는 낱개 상품 정보. -해당 정보를 전달하면 주문금액은 전체 상품별 금액들의 합으로 계산됩니다. + + + + 적용될 추가 수수료 정책 아이디. i.e. 해당 상품에만 로켓배송 수수료가 적용될 경우 로켓배송 수수료 정책 아이디를 보내주시면 됩니다. + + +
+ product.**id** string required - - - + - 주문정산건에 해당되는 낱개 상품 정보. + + + - product.**name** string required + + + - + + - - + - product.**tag** list of string optional + + +
- orderLines.**product** dictionary required + 상품 아이디. 고객사의 서버에 등록된 상품 아이디를 임의로 보내주시면 됩니다. +
+ product.**name** string required - - - + - product.**id** string required + + + - + + - - + +
+ 상품 이름. 고객사의 서버에 등록된 상품 이름을 임의로 보내주시면 됩니다. +
+ product.**amount** int required - 상품 아이디. 고객사의 서버에 등록된 상품 아이디를 임의로 보내주시면 됩니다. + 상품 가격. 상품의 낱개 가격입니다. +
+ product.**tag** list of string optional -
+ 상품 태그. 내부 구분을 위한 태그입니다. +
+
+ orderLines.**quantity** int required - 상품 이름. 고객사의 서버에 등록된 상품 이름을 임의로 보내주시면 됩니다. + 상품 갯수 +
+ orderLines.**discounts** list of dictionary optional -
+ 해당 상품에 적용될 할인정보 리스트 + [할인 정책 참고](#할인-유형) - product.**amount** int required + + + + - + + - - + +
+ discounts.**sharePolicyId** string required - 상품 가격. 상품의 낱개 가격입니다. + 적용될 할인정책 아이디. +
+ discounts.**amount** int required -
+ 해당 할인정책이 적용되는 할인금액. i.e. 1000원 쿠폰에 대한 할인이면 1000 +
+
+ orderLines.**additionalFees** list of dictionary optional - 상품 태그. 내부 구분을 위한 태그입니다. + 해당 상품에 적용된 추가수수료 정책 리스트. 포트원에 등록된 추가수수료 아이디를 보내주시면 됩니다. 해당 아이디의 추가수수료가 정산에 적용됩니다. + [추가수수료 참고](#추가-수수료-객체)] -
+ + -
+ additionalFees.**policyId** string required -
-
+
- - - - orderLines.**quantity** int required + --- - 상품 갯수 + **settlementStartDate** string 기본값은 결제완료 시점 optional - - - - - orderLines.**discounts** list of dictionary optional + `'yyyy-MM-dd'` 형식을 따릅니다. - 해당 상품에 적용될 할인정보 리스트 - [할인 정책 참고](#할인-유형) - - - - - - - -
- discounts.**sharePolicyId** string required + 정산 시작일로써 정산 주기가 적용될 날짜이다. 주문완료, 배송완료 등 정산이 고려되기 시작해야하는 시간을 뜻한다. 기본값은 주문정산건과 연결된 결제의 완료 시점으로 업데이트 된다. - 적용될 할인정책 아이디. -
- discounts.**amount** int required + 따라서 **payment.type = 'INTERNAL'** 일때는 포트원 결제완료 시점, **payment.type = 'EXTERNAL'** 일때는 **externalPaymentDetail.paidAt** 값이 기본값으로 적용되며 **payment.paidAt** 값을 전달하지 않을경우 현재시점으로 적용된다. - 해당 할인정책이 적용되는 할인금액. i.e. 1000원 쿠폰에 대한 할인이면 1000 -
- - - - - orderLines.**additionalFees** list of dictionary optional - - 해당 상품에 적용된 추가수수료 정책 리스트. 포트원에 등록된 추가수수료 아이디를 보내주시면 됩니다. 해당 아이디의 추가수수료가 정산에 적용됩니다. - [추가수수료 참고](#추가-수수료-객체)] - - - - -
- additionalFees.**policyId** string required + 배송완료 예정일, 수강 오픈일, 등 미래시점으로 지정해 놓으면 해당 시점부터 정산주기가 적용되며 그동안 정산객체의 상태값은 준비 (**SCHEDULED**)로 적용된다. - 적용될 추가 수수료 정책 아이디. i.e. 해당 상품에만 로켓배송 수수료가 적용될 경우 로켓배송 수수료 정책 아이디를 보내주시면 됩니다. -
- - + --- - + **discounts** list of dictionary optional ---- + 주문 정산건에 적용할 할인 정책들의 리스트. 할인 정책 객체들로 이루어져 있다. -**settlementStartDate** string 기본값은 결제완료 시점 optional + 할인 정책이란 특정 주문에 적용된 할인에 대해서 유형별 파트너 분담율을 정산에 계산하기 위한 객체이다. -`'yyyy-MM-dd'` 형식을 따릅니다. + **orderLines**를 통해 각 상품별 적용될 할인 정보와 **orderLines.discounts** 별개로 해당 파라미터는 주문건 전체에 적용될 할인 정보를 전달할 때 사용합니다. -정산 시작일로써 정산 주기가 적용될 날짜이다. 주문완료, 배송완료 등 정산이 고려되기 시작해야하는 시간을 뜻한다. 기본값은 주문정산건과 연결된 결제의 완료 시점으로 업데이트 된다. + + + + -배송완료 예정일, 수강 오픈일, 등 미래시점으로 지정해 놓으면 해당 시점부터 정산주기가 적용되며 그동안 정산객체의 상태값은 준비 (**SCHEDULED**)로 적용된다. + + + +
+ discount._sharePolicyId_\* string required -따라서 **payment.type = 'INTERNAL'** 일때는 포트원 결제완료 시점, **payment.type = 'EXTERNAL'** 일때는 **externalPaymentDetail.paidAt** 값이 기본값으로 적용되며 **payment.paidAt** 값을 전달하지 않을경우 현재시점으로 적용된다. + 할인 정책 아이디. 포트원에 등록된 할인 정책 아이디를 보내주시면 됩니다. 해당 아이디의 할인분담율이 정산에 적용됩니다. +
+ discount.**amount** int64 required ---- + 할인 금액. 주문금액보다 클 수 없습니다. +
-**discounts** list of dictionary optional + --- -주문 정산건에 적용할 할인 정책들의 리스트. 할인 정책 객체들로 이루어져 있다. + **additionalFees** list of dictionary optional -할인 정책이란 특정 주문에 적용된 할인에 대해서 유형별 파트너 분담율을 정산에 계산하기 위한 객체이다. + 주문 정산건에 적용될 추가 수수료 아이디들의 리스트 -**orderLines**를 통해 각 상품별 적용될 할인 정보와 **orderLines.discounts** 별개로 해당 파라미터는 주문건 전체에 적용될 할인 정보를 전달할 때 사용합니다. + 추가수수료란 특정 주문정산건에 고객사가 파트너에게 추가 서비스를 제공함으로써 과금되는 수수료 이다. 정산수식에대한 수정이 있지 않는한 기본으로 추가수수료는 주문금액에 부과된다. + [추가수수료 참고](#추가-수수료-객체)] - - - + **externalPaymentDetail** dictionary optional - - - + + -**additionalFees** list of dictionary optional + + + - 신용카드 + + - - - + +
+ + + + +
+ additionalFees.**policyId** string required - discount.*sharePolicyId** string required + 적용될 추가 수수료 정책 아이디. i.e. 해당 상품에만 로켓배송 수수료가 적용될 경우 로켓배송 수수료 정책 아이디를 보내주시면 됩니다. +
- 할인 정책 아이디. 포트원에 등록된 할인 정책 아이디를 보내주시면 됩니다. 해당 아이디의 할인분담율이 정산에 적용됩니다. + --- -
+ 포트원 결제가 아닌 경우에만 전달하셔야 합니다. - discount.**amount** int64 required + + + + - + + + 외부 결제 주문명. + + -
+ externalPaymentDetail.**currency** enum required - 할인 금액. 주문금액보다 클 수 없습니다. + 외부 결제 통화. 'KRW','USD','JPY'만 지원합니다. +
+ externalPaymentDetail.**orderName** string optional -
+
+ externalPaymentDetail.**paidAt** string optional ---- + 외부 결제 완료 시점. 'yyyy-MM-dd'T'HH:mm:ss.SSSZ' 형식을 따릅니다. 기본값은 현재시점입니다. +
+ externalPaymentDetail.**method** dicionary -주문 정산건에 적용될 추가 수수료 아이디들의 리스트 + 외부 결제연동 서비스를 통해 결제된 주문건의 결제수단 + 아래 결제 수단중 하나만 택해서 전달해야 합니다. + 간편 결제수단("easyPay") 를 제외하고 특정 결제수단에 해당된다면 빈 json 값 (`{}`) 을 전달해야 합니다. -추가수수료란 특정 주문정산건에 고객사가 파트너에게 추가 서비스를 제공함으로써 과금되는 수수료 이다. 정산수식에대한 수정이 있지 않는한 기본으로 추가수수료는 주문금액에 부과된다. -[추가수수료 참고](#추가-수수료-객체)] + + + + + -**externalPaymentDetail** dictionary optional + + + -
+ method.**card** dictionary optional - - - + - 적용될 추가 수수료 정책 아이디. i.e. 해당 상품에만 로켓배송 수수료가 적용될 경우 로켓배송 수수료 정책 아이디를 보내주시면 됩니다. - - -
-additionalFees.**policyId** string required + 신용카드 +
+
+ method.**transfer** dictionary optional ---- + 계좌이체 +
+ method.**virtualAccount** dictionary optional -포트원 결제가 아닌 경우에만 전달하셔야 합니다. + 가상계좌 +
- - + + 상품권 + + - - - + + 휴대폰 소액결제 + + - - - + + 간편결제 - - - + +
- externalPaymentDetail.**currency** enum required +
+ method.**giftCertificate** dictionary optional - 외부 결제 통화. 'KRW','USD','JPY'만 지원합니다. -
- externalPaymentDetail.**orderName** string optional +
+ method.**mobile** dictionary optional - 외부 결제 주문명. -
- externalPaymentDetail.**paidAt** string optional +
+ method.**easyPay** dictionary optional - 외부 결제 완료 시점. 'yyyy-MM-dd'T'HH:mm:ss.SSSZ' 형식을 따릅니다. 기본값은 현재시점입니다. -
- externalPaymentDetail.**method** dicionary + + + + -
+ easyPay.**provider** enum - 외부 결제연동 서비스를 통해 결제된 주문건의 결제수단 - 아래 결제 수단중 하나만 택해서 전달해야 합니다. - 간편 결제수단("easyPay") 를 제외하고 특정 결제수단에 해당된다면 빈 json 값 (```{}```) 을 전달해야 합니다. + 간편결제 브랜드 (i.e. "KAKAOPAY") +
- - + + +
+
+ easyPay.**method** enum - method.**card** dictionary optional + 간편결제 내의 결제 수단 (i.e. "CARD", "TRANSFER") +
+
+
+ payment.**currency** enum -
+ 외부 결제연동 서비스를 통해 결제된 주문건의 결제통화 - method.**transfer** dictionary optional + 현재는 'KRW', 'JPY', 'USD' 만 지원합니다. +
- 계좌이체 + **isForTest** boolean optional 기본값은 false - - - - + 포트원의 테스트 서버로 정산 데이터를 전달할지 여부를 결정한다. 기본값은 false이다. 테스트 서버로 전달할 경우 정산 데이터는 테스트 서버에만 저장되며 실제 정산에는 반영되지 않는다. - method.**virtualAccount** dictionary optional + --- +
- 가상계좌 +
+ **Request body** + one of 까지 다 표현되어 모든 파라미터가 나옵니다. - - - - - - method.**giftCertificate** dictionary optional - - 상품권 - - - - - - - method.**mobile** dictionary optional - - 휴대폰 소액결제 - - - - - - - method.**easyPay** dictionary optional - - 간편결제 - - - - - - - -
- - easyPay.**provider** enum - - 간편결제 브랜드 (i.e. "KAKAOPAY") - -
- - easyPay.**method** enum - - 간편결제 내의 결제 수단 (i.e. "CARD", "TRANSFER") -
- - - - - - - - - - payment.**currency** enum - - 외부 결제연동 서비스를 통해 결제된 주문건의 결제통화 - - 현재는 'KRW', 'JPY', 'USD' 만 지원합니다. - - - - - - -**isForTest** boolean optional 기본값은 false - -포트원의 테스트 서버로 정산 데이터를 전달할지 여부를 결정한다. 기본값은 false이다. 테스트 서버로 전달할 경우 정산 데이터는 테스트 서버에만 저장되며 실제 정산에는 반영되지 않는다. - ---- - -
-
-**Request body** -one of 까지 다 표현되어 모든 파라미터가 나옵니다. - -```json -{ - "partnerId": "string", - "contractId": "string", - "memo": "string", - "paymentId": "string", - "orderDetail": { - "orderAmount": 0, - "orderLines": [ - { - "product": { - "id": "string", - "name": "string", - "amount": 0, - "tag": "string" - }, - "quantity": 0, - "discounts": [ - { - "sharePolicyId": "string", - "amount": 0 - } - ], - "additionalFees": [ + ```json + { + "partnerId": "string", + "contractId": "string", + "memo": "string", + "paymentId": "string", + "orderDetail": { + "orderAmount": 0, + "orderLines": [ { - "policyId": "string" + "product": { + "id": "string", + "name": "string", + "amount": 0, + "tag": "string" + }, + "quantity": 0, + "discounts": [ + { + "sharePolicyId": "string", + "amount": 0 + } + ], + "additionalFees": [ + { + "policyId": "string" + } + ] } ] - } - ] - }, - "settlementStartDate": "string", - "discounts": [ - { - "sharePolicyId": "string", - "amount": 0 - } - ], - "additionalFees": [ - { - "policyId": "string" - } - ], - "externalPaymentDetail": { - "currency": "AED", - "orderName": "string", - "paidAt": "2023-08-15T08:14:26.703Z", - "method": { - "card": {}, - "transfer": {}, - "virtualAccount": {}, - "giftCertificate": {}, - "mobile": {}, - "easyPay": { - "provider": "APPLEPAY", - "method": "CARD" - } + }, + "settlementStartDate": "string", + "discounts": [ + { + "sharePolicyId": "string", + "amount": 0 + } + ], + "additionalFees": [ + { + "policyId": "string" + } + ], + "externalPaymentDetail": { + "currency": "AED", + "orderName": "string", + "paidAt": "2023-08-15T08:14:26.703Z", + "method": { + "card": {}, + "transfer": {}, + "virtualAccount": {}, + "giftCertificate": {}, + "mobile": {}, + "easyPay": { + "provider": "APPLEPAY", + "method": "CARD" + } + } + }, + "isForTest": true } - }, - "isForTest": true -} -``` + ``` -**Response** + **Response** -주문 정산객체가 반환됩니다. + 주문 정산객체가 반환됩니다. -**정산 시작일 참고** + **정산 시작일 참고** -- 정산시작일(settlementStartDate)을 전달하지 않을경우 결제완료 시점으로 기본으로 지정됩니다. 이 경우 정산 api호출시점에 결제완료가 아직 되지 않았다면 에러를 반환합니다. -- 정산시작일(settlementStartDate)을 미래의 시점으로 전달할 경우 status 는 PREPARE이고 이에 적용될 계약정보는 정산api를 호출한 시점에 등록된 계약으로 적용되나 계약정보가 바뀌어 업데이트 될 여지가 있습니다. + - 정산시작일(settlementStartDate)을 전달하지 않을경우 결제완료 시점으로 기본으로 지정됩니다. 이 경우 정산 api호출시점에 결제완료가 아직 되지 않았다면 에러를 반환합니다. + - 정산시작일(settlementStartDate)을 미래의 시점으로 전달할 경우 status 는 PREPARE이고 이에 적용될 계약정보는 정산api를 호출한 시점에 등록된 계약으로 적용되나 계약정보가 바뀌어 업데이트 될 여지가 있습니다. ---- + --- -- 포트원 결제일 경우 -- 상품 정보를 전달할 경우 - -```json -{ - "transfer": { - "type": "ORDER", - "id": "01H7HVM3YYCYQC3HF6KN4VZYZ2", - "graphqlId": "NjowMUg3SFZNM1lZQ1lRQzNIRjZLTjRWWllaMg==", - "partner": { - "id": "partner_2", - "graphqlId": "NDpwYXJ0bmVyXzI=", - "name": "파이썬 강사", - "email": "kjnkyj12@gmail.com", - "businessRegistrationNumber": "1178178260", - "account": { - "bank": "SHINHAN", - "currency": "KRW", - "number": "10358907249", - "holder": "김준일", - "status": "VERIFIED" - }, - "status": "APPROVED", - "defaultContractId": "contract_2", - "memo": "잭슨 테스트", - "tags": ["파이썬"], - "isHidden": false, - "appliedAt": "2023-08-09T07:39:25.645014Z" - }, - "status": "IN_PROCESS", - "memo": "testing order transfer", - "settlementDate": "2023-08-18", - "settlementCurrency": "KRW", - "isForTest": true, - "amount": { - "settlement": 17250, - "payment": 20000, - "order": 25000, - "platformFee": 2500, - "platformFeeVat": 0, - "additionalFee": 2500, - "additionalFeeVat": 250, - "discount": 5000, - "discountShare": 2500 - }, - "contract": { - "id": "contract_2", - "graphqlId": "NTpjb250cmFjdF8y", - "memo": "contract 2", - "platformFee": { "type": "FIXED_RATE", "rate": 10000 }, - "settlementCycle": { - "lagDays": 2, - "datePolicy": "CALENDAR_DAY", - "method": { "type": "WEEKLY", "daysOfWeek": ["FRI"] } - }, - "platformFeeVatPayer": "MERCHANT", - "isHidden": false, - "appliedAt": "2023-08-09T07:39:17.207733Z" - }, - "payment": { - "type": "EXTERNAL", - "id": "payment_1", - "orderName": "테스트 주문", - "currency": "KRW", - "method": { "type": "CARD" }, - "paidAt": "2023-08-11T08:21:01.241Z" - }, - "settlementStartDate": "2023-08-11", - "orderLines": [ - { - "product": { "id": "1", "name": "product_1", "amount": 5000 }, - "quantity": 5, - "discounts": [ + - 포트원 결제일 경우 + - 상품 정보를 전달할 경우 + + ```json + { + "transfer": { + "type": "ORDER", + "id": "01H7HVM3YYCYQC3HF6KN4VZYZ2", + "graphqlId": "NjowMUg3SFZNM1lZQ1lRQzNIRjZLTjRWWllaMg==", + "partner": { + "id": "partner_2", + "graphqlId": "NDpwYXJ0bmVyXzI=", + "name": "파이썬 강사", + "email": "kjnkyj12@gmail.com", + "businessRegistrationNumber": "1178178260", + "account": { + "bank": "SHINHAN", + "currency": "KRW", + "number": "10358907249", + "holder": "김준일", + "status": "VERIFIED" + }, + "status": "APPROVED", + "defaultContractId": "contract_2", + "memo": "잭슨 테스트", + "tags": ["파이썬"], + "isHidden": false, + "appliedAt": "2023-08-09T07:39:25.645014Z" + }, + "status": "IN_PROCESS", + "memo": "testing order transfer", + "settlementDate": "2023-08-18", + "settlementCurrency": "KRW", + "isForTest": true, + "amount": { + "settlement": 17250, + "payment": 20000, + "order": 25000, + "platformFee": 2500, + "platformFeeVat": 0, + "additionalFee": 2500, + "additionalFeeVat": 250, + "discount": 5000, + "discountShare": 2500 + }, + "contract": { + "id": "contract_2", + "graphqlId": "NTpjb250cmFjdF8y", + "memo": "contract 2", + "platformFee": { "type": "FIXED_RATE", "rate": 10000 }, + "settlementCycle": { + "lagDays": 2, + "datePolicy": "CALENDAR_DAY", + "method": { "type": "WEEKLY", "daysOfWeek": ["FRI"] } + }, + "platformFeeVatPayer": "MERCHANT", + "isHidden": false, + "appliedAt": "2023-08-09T07:39:17.207733Z" + }, + "payment": { + "type": "EXTERNAL", + "id": "payment_1", + "orderName": "테스트 주문", + "currency": "KRW", + "method": { "type": "CARD" }, + "paidAt": "2023-08-11T08:21:01.241Z" + }, + "settlementStartDate": "2023-08-11", + "orderLines": [ { - "sharePolicy": { - "id": "discount_1", - "graphqlId": "MjpkaXNjb3VudF8x", - "partnerShareRate": 500000000, - "memo": "테스트 할인", - "isHidden": false, - "appliedAt": "2023-08-09T07:45:45.799176Z" - }, - "amount": 2500, - "shareAmount": 1250 + "product": { "id": "1", "name": "product_1", "amount": 5000 }, + "quantity": 5, + "discounts": [ + { + "sharePolicy": { + "id": "discount_1", + "graphqlId": "MjpkaXNjb3VudF8x", + "partnerShareRate": 500000000, + "memo": "테스트 할인", + "isHidden": false, + "appliedAt": "2023-08-09T07:45:45.799176Z" + }, + "amount": 2500, + "shareAmount": 1250 + } + ], + "additionalFees": [ + { + "policy": { + "id": "addtional_fee_1", + "graphqlId": "MzphZGR0aW9uYWxfZmVlXzE=", + "fee": { "type": "FIXED_RATE", "rate": 5000 }, + "memo": "테스트 추가수수료", + "vatPayer": "PARTNER", + "isHidden": false, + "appliedAt": "2023-08-09T07:41:12.393974Z" + }, + "amount": 1250, + "vat": 125 + } + ], + "amount": { + "settlement": 19875, + "payment": 22500, + "order": 25000, + "platformFee": 2500, + "platformFeeVat": 0, + "additionalFee": 1250, + "additionalFeeVat": 125, + "discount": 2500, + "discountShare": 1250 + } } ], "additionalFees": [ @@ -1368,53 +1318,25 @@ one of 까지 다 표현되어 모든 파라미터가 나옵니다. "vat": 125 } ], - "amount": { - "settlement": 19875, - "payment": 22500, - "order": 25000, - "platformFee": 2500, - "platformFeeVat": 0, - "additionalFee": 1250, - "additionalFeeVat": 125, - "discount": 2500, - "discountShare": 1250 - } - } - ], - "additionalFees": [ - { - "policy": { - "id": "addtional_fee_1", - "graphqlId": "MzphZGR0aW9uYWxfZmVlXzE=", - "fee": { "type": "FIXED_RATE", "rate": 5000 }, - "memo": "테스트 추가수수료", - "vatPayer": "PARTNER", - "isHidden": false, - "appliedAt": "2023-08-09T07:41:12.393974Z" - }, - "amount": 1250, - "vat": 125 - } - ], - "discounts": [ - { - "sharePolicy": { - "id": "discount_1", - "graphqlId": "MjpkaXNjb3VudF8x", - "partnerShareRate": 500000000, - "memo": "테스트 할인", - "isHidden": false, - "appliedAt": "2023-08-09T07:45:45.799176Z" - }, - "amount": 2500, - "shareAmount": 1250 + "discounts": [ + { + "sharePolicy": { + "id": "discount_1", + "graphqlId": "MjpkaXNjb3VudF8x", + "partnerShareRate": 500000000, + "memo": "테스트 할인", + "isHidden": false, + "appliedAt": "2023-08-09T07:45:45.799176Z" + }, + "amount": 2500, + "shareAmount": 1250 + } + ] } - ] - } -} -``` + } + ``` -**Error Code** + **Error Code** |Code|Description | |:---|:----------------------------------------------------------------------------------------------------------------------------| @@ -1441,301 +1363,290 @@ one of 까지 다 표현되어 모든 파라미터가 나옵니다. `POST https://api.portone.io/platform/transfers/order-cancel`
-
- -주문 취소 정산건이란 결제 취소를 기반으로 파트너에게 정산금을 차감할 수 있는 api입니다. - -취소 정산 등록은 사전에 주문 정산이 등록되어 있는 경우에만 사용할 수 있습니다. - -결제 취소에 대한 id를 전달주셔야 하며 취소시 차감되는 주문금액 및 할인금액 에 따라 차감될 정산금액을 계산합니다. - -**Parameters** +
+ 주문 취소 정산건이란 결제 취소를 기반으로 파트너에게 정산금을 차감할 수 있는 api입니다. -**partnerId** required + 취소 정산 등록은 사전에 주문 정산이 등록되어 있는 경우에만 사용할 수 있습니다. -주문 취소 정산건에 해당되는 파트너 지정 + 결제 취소에 대한 id를 전달주셔야 하며 취소시 차감되는 주문금액 및 할인금액 에 따라 차감될 정산금액을 계산합니다. ---- + **Parameters** -**paymentId** required + **partnerId** required -취소하고자 하는 기존 주문건의 paymentId. 기존에 주문정산으로써 등록 되어있어야 합니다. + 주문 취소 정산건에 해당되는 파트너 지정 ---- + --- -**cancellationId** required + **paymentId** required -결제 취소 아이디. 포트원 결제일 경우 결제취소 아이디 (cancellation_id) 는 v2 api를 통해 발급 가능하며 #결제-취소(POST https://api.portone.io/v2/payments/{payment_id}/cancel), -결제내역-단건조회 (GET https://api.portone.io/v2/payments) api를 통해 받으실 수 있습니다. (참고: https://developers.portone.io/docs/ko/api-v2/payment/) + 취소하고자 하는 기존 주문건의 paymentId. 기존에 주문정산으로써 등록 되어있어야 합니다. -외부 결제일 경우 단순히 결제 취소건당 unique한 아이디를 전달해주시면 됩니다. + --- -**memo** optional + **cancellationId** required -주문 취소 정산 건에 내부 구분을 위한 메모 + 결제 취소 아이디. 포트원 결제일 경우 결제취소 아이디 (cancellation\_id) 는 v2 api를 통해 발급 가능하며 #결제-취소(POST [https://api.portone.io/v2/payments/\{payment\_id}/cancel](https://api.portone.io/v2/payments/\{payment_id}/cancel)), + 결제내역-단건조회 (GET [https://api.portone.io/v2/payments](https://api.portone.io/v2/payments)) api를 통해 받으실 수 있습니다. (참고: [https://developers.portone.io/docs/ko/api-v2/payment/](https://developers.portone.io/docs/ko/api-v2/payment/)) ---- + 외부 결제일 경우 단순히 결제 취소건당 unique한 아이디를 전달해주시면 됩니다. -**orderDetails** required + **memo** optional -주문취소 정산건에 해당되는 주문 상세 정보. 기존 주문건에 포함된 상품의 정보중 취소하고자 한는 항목을 전달해야 합니다. + 주문 취소 정산 건에 내부 구분을 위한 메모 -one of 로직으로써 단순히 주문취소 금액만 전달하고 싶으신 경우에는 `"orderDetails" : {"orderAmount": 금액}` 와 같이 전달하시면 됩니다. -취소하고자 하는 상품 정보 및 상품별 할인금 을 전달하고 싶으신 경우에는 `"orderDetails" : {"orderLines": [{...}, {...}]}` 와 같이 전달하시면 됩니다. -단순히 전체 취소를 하시고 싶으시다면 `"orderDetails" : {"all": []}` 와 같이 전달하시면 됩니다. + --- -- 주문취소 금액만 전달할 경우 (`"orderDetails": {"orderAmount": 금액}`) + **orderDetails** required - - - +
+ 주문취소 정산건에 해당되는 주문 상세 정보. 기존 주문건에 포함된 상품의 정보중 취소하고자 한는 항목을 전달해야 합니다. - **orderAmount** optional + one of 로직으로써 단순히 주문취소 금액만 전달하고 싶으신 경우에는 `"orderDetails" : {"orderAmount": 금액}` 와 같이 전달하시면 됩니다. + 취소하고자 하는 상품 정보 및 상품별 할인금 을 전달하고 싶으신 경우에는 `"orderDetails" : {"orderLines": [{...}, {...}]}` 와 같이 전달하시면 됩니다. + 단순히 전체 취소를 하시고 싶으시다면 `"orderDetails" : {"all": []}` 와 같이 전달하시면 됩니다. - 주문 취소시 적용될 주문 취소금액. 주문금액 인점 유의 하셔야 합니다. 주문금액은 결제금액 + 할인금액 입니다. + - 주문취소 금액만 전달할 경우 (`"orderDetails": {"orderAmount": 금액}`) - 해당 값이 주문 정산시 주문금액과 동일한 경우에는 따로 취소하실 할인금액을 전달하지 않으셔도 환불 처리 됩니다. -
+ + -
+ **orderAmount** optional -
+ 주문 취소시 적용될 주문 취소금액. 주문금액 인점 유의 하셔야 합니다. 주문금액은 결제금액 + 할인금액 입니다. -- 상품 정보 및 상품별 금액, 수량 할인 및 추가수수료를 적용하여 전달할 경우 (`"orderDetails": {"orderLines": [{...}, {...}]}`) + 해당 값이 주문 정산시 주문금액과 동일한 경우에는 따로 취소하실 할인금액을 전달하지 않으셔도 환불 처리 됩니다. + + + -해당 정보를 전달하면 주문금액은 전체 상품별 금액들의 합으로 계산됩니다. + - 상품 정보 및 상품별 금액, 수량 할인 및 추가수수료를 적용하여 전달할 경우 (`"orderDetails": {"orderLines": [{...}, {...}]}`) - - - +
- orderLines.**productId** dictionary required + 해당 정보를 전달하면 주문금액은 전체 상품별 금액들의 합으로 계산됩니다. - 취소하고자 하는 상품 아이디 -
+ + - - + - 취소하고자 하는 상품 갯수 + + - - - + - 해당 상품에서 취소하고자 하는 할인정보 리스트 + + + +
+ orderLines.**productId** dictionary required -
- orderLines.**quantity** required + 취소하고자 하는 상품 아이디 +
+ orderLines.**quantity** required -
- orderLines.**discounts** list of dictionary optional + 취소하고자 하는 상품 갯수 +
+ orderLines.**discounts** list of dictionary optional - 상품에 대한 모든 수량 취소시 모든 discount도 자동으로 취소됩니다. - - - - - - - + +
- discounts.**amount** required + 해당 상품에서 취소하고자 하는 할인정보 리스트 - 취소할 할인 금액. 해당 상품에 적용되었던 할인 금액중 환불에 해당하는 금액을 전달 주시면 됩니다. + 상품에 대한 모든 수량 취소시 모든 discount도 자동으로 취소됩니다. -
- discounts.**sharePolicyId** required + + + + - - -
+ discounts.**amount** required - 할인 정책 아이디. 주문 정산시 상품에 등록되었던 할인 정책 아이디 중 취소하고자 하는 아이디를 전달주시면 됩니다. + 취소할 할인 금액. 해당 상품에 적용되었던 할인 금액중 환불에 해당하는 금액을 전달 주시면 됩니다. +
-
+ discounts.**sharePolicyId** required -
+ 할인 정책 아이디. 주문 정산시 상품에 등록되었던 할인 정책 아이디 중 취소하고자 하는 아이디를 전달주시면 됩니다. +
+ + + -- 전체 취소를 하고자 할 경우 (`"orderDetails": {"all": []}`) + - 전체 취소를 하고자 할 경우 (`"orderDetails": {"all": []}`) ---- + --- -**discounts** optional + **discounts** optional -주문 취소시 적용될 할인정보 리스트 + 주문 취소시 적용될 할인정보 리스트 -모든 금액 취소시 모든 discount도 자동으로 취소됩니다. + 모든 금액 취소시 모든 discount도 자동으로 취소됩니다. - - - - - + 취소 정산 또한 주문 정산과 동일하게 정산주기가 적용됩니다. 따라서 주문 정산건이 이미 정산이 되었고 해당 주문건에 대한 취소정산이 이루어졌을때 취소금액은 다음 정산주기에 적용됩니다. - + 따라서 **payment.type = INTERNAL** 일때는 포트원 결제취소 시점 값이 기본값으로 적용됩니다. -
+ + + + - 할인 정책 아이디. 주문 정산시 등록되었던 할인 정책 아이디 중 취소하고자 하는 아이디를 전달주시면 됩니다. + + + 취소할 할인 금액. 해당 주문에 적용되었던 할인 금액중 환불에 해당하는 금액을 전달 주시면 됩니다. + + +
+ discount.**sharePolicyId** string required - discount.**sharePolicyId** string required + 할인 정책 아이디. 주문 정산시 등록되었던 할인 정책 아이디 중 취소하고자 하는 아이디를 전달주시면 됩니다. +
+ discount.**amount** int64 required -
-
+ --- - discount.**amount** int64 required + **settlementStartDate** string 기본값은 결제완료 시점 - 취소할 할인 금액. 해당 주문에 적용되었던 할인 금액중 환불에 해당하는 금액을 전달 주시면 됩니다. + `'yyyy-MM-dd'` 형식의 문자열로 전달해주시면 됩니다. -
+ --- ---- + **isForTest** boolean optional 기본값은 false -**settlementStartDate** string 기본값은 결제완료 시점 + 포트원의 테스트 서버로 정산 데이터를 전달할지 여부를 결정한다. 기본값은 false이다. 테스트 서버로 전달할 경우 정산 데이터는 테스트 서버에만 저장되며 실제 정산에는 반영되지 않는다. +
-`'yyyy-MM-dd'` 형식의 문자열로 전달해주시면 됩니다. +
+ 취소 정산의 취소 주문금액 , 상품별 취소 주문 금액 및 수량, 주문 취소 할인금액 및 상품별 취소 할인 금액에 따라 새로운 음수 정산금액을 계산하신다고 이해하시면 됩니다. -취소 정산 또한 주문 정산과 동일하게 정산주기가 적용됩니다. 따라서 주문 정산건이 이미 정산이 되었고 해당 주문건에 대한 취소정산이 이루어졌을때 취소금액은 다음 정산주기에 적용됩니다. + **Request Body** + one of 로직에 해당되는 parameter가 다 표기되었습니다. -따라서 **payment.type = INTERNAL** 일때는 포트원 결제취소 시점 값이 기본값으로 적용됩니다. + ```json + { + "partnerId": "string", + "paymentId": "string", + "cancellationId": "string", + "memo": "string", + "orderDetail": { + "orderAmount": 0, + "orderLines": [ + { + "productId": "string", + "quantity": 0, + "discounts": [ + { + "sharePolicyId": "string", + "amount": 0 + } + ] + } + ], + "all": {} + }, + "discounts": [ + { + "sharePolicyId": "string", + "amount": 0 + } + ], + "settlementStartDate": "string", + "externalCancellationDetail": { + "cancelledAt": "2023-08-15T09:02:20.868Z" + }, + "isForTest": true + } + ``` ---- + **Response** -**isForTest** boolean optional 기본값은 false + 취소 정산시 반환되는 금액 및 수수 값들은 다 주문정산객체 값의 음수처리 입니다. -포트원의 테스트 서버로 정산 데이터를 전달할지 여부를 결정한다. 기본값은 false이다. 테스트 서버로 전달할 경우 정산 데이터는 테스트 서버에만 저장되며 실제 정산에는 반영되지 않는다. + - 외부 결제일때 + - orderAmount 일때 -
-
- -취소 정산의 취소 주문금액 , 상품별 취소 주문 금액 및 수량, 주문 취소 할인금액 및 상품별 취소 할인 금액에 따라 새로운 음수 정산금액을 계산하신다고 이해하시면 됩니다. - -**Request Body** -one of 로직에 해당되는 parameter가 다 표기되었습니다. - -```json -{ - "partnerId": "string", - "paymentId": "string", - "cancellationId": "string", - "memo": "string", - "orderDetail": { - "orderAmount": 0, - "orderLines": [ - { - "productId": "string", - "quantity": 0, - "discounts": [ - { - "sharePolicyId": "string", - "amount": 0 - } - ] - } - ], - "all": {} - }, - "discounts": [ + ```json { - "sharePolicyId": "string", - "amount": 0 - } - ], - "settlementStartDate": "string", - "externalCancellationDetail": { - "cancelledAt": "2023-08-15T09:02:20.868Z" - }, - "isForTest": true -} -``` - -**Response** - -취소 정산시 반환되는 금액 및 수수 값들은 다 주문정산객체 값의 음수처리 입니다. - -- 외부 결제일때 -- orderAmount 일때 - -```json -{ - "transfer": { - "type": "ORDER_CANCEL", - "id": "01H7J87XQ4JAS28RWZBC29YCJ1", - "graphqlId": "NjowMUg3Sjg3WFE0SkFTMjhSV1pCQzI5WUNKMQ==", - "partner": { - "id": "partnerA", - "graphqlId": "NDpwYXJ0bmVyQQ==", - "name": "파이썬 강사", - "email": "kjnkyj12@gmail.com", - "businessRegistrationNumber": "1178178260", - "account": { - "bank": "SHINHAN", - "currency": "KRW", - "number": "10358907249", - "holder": "김준일", - "status": "VERIFIED" - }, - "status": "APPROVED", - "defaultContractId": "contractA", - "memo": "잭슨 테스트 예시문", - "tags": ["파이썬"], - "isHidden": false, - "appliedAt": "2023-08-11T11:19:58.829787Z" - }, - "status": "SCHEDULED", - "settlementDate": "2023-08-31", - "settlementCurrency": "KRW", - "isForTest": false, - "amount": { - "settlement": 4450, - "payment": 5000, - "order": 5000, - "platformFee": 500, - "platformFeeVat": 50, - "additionalFee": 0, - "additionalFeeVat": 0, - "discount": 0, - "discountShare": 0 - }, - "contract": { - "id": "contractA", - "graphqlId": "NTpjb250cmFjdEE=", - "memo": "contract A", - "platformFee": { - "type": "FIXED_RATE", - "rate": 10000 - }, - "settlementCycle": { - "lagDays": 2, - "datePolicy": "HOLIDAY_BEFORE", - "method": { - "type": "MONTHLY", - "daysOfMonth": [31] + "transfer": { + "type": "ORDER_CANCEL", + "id": "01H7J87XQ4JAS28RWZBC29YCJ1", + "graphqlId": "NjowMUg3Sjg3WFE0SkFTMjhSV1pCQzI5WUNKMQ==", + "partner": { + "id": "partnerA", + "graphqlId": "NDpwYXJ0bmVyQQ==", + "name": "파이썬 강사", + "email": "kjnkyj12@gmail.com", + "businessRegistrationNumber": "1178178260", + "account": { + "bank": "SHINHAN", + "currency": "KRW", + "number": "10358907249", + "holder": "김준일", + "status": "VERIFIED" + }, + "status": "APPROVED", + "defaultContractId": "contractA", + "memo": "잭슨 테스트 예시문", + "tags": ["파이썬"], + "isHidden": false, + "appliedAt": "2023-08-11T11:19:58.829787Z" + }, + "status": "SCHEDULED", + "settlementDate": "2023-08-31", + "settlementCurrency": "KRW", + "isForTest": false, + "amount": { + "settlement": 4450, + "payment": 5000, + "order": 5000, + "platformFee": 500, + "platformFeeVat": 50, + "additionalFee": 0, + "additionalFeeVat": 0, + "discount": 0, + "discountShare": 0 + }, + "contract": { + "id": "contractA", + "graphqlId": "NTpjb250cmFjdEE=", + "memo": "contract A", + "platformFee": { + "type": "FIXED_RATE", + "rate": 10000 + }, + "settlementCycle": { + "lagDays": 2, + "datePolicy": "HOLIDAY_BEFORE", + "method": { + "type": "MONTHLY", + "daysOfMonth": [31] + } + }, + "platformFeeVatPayer": "PARTNER", + "isHidden": false, + "appliedAt": "2023-08-11T11:18:52.944447Z" + }, + "payment": { + "type": "EXTERNAL", + "id": "payment_1", + "orderName": "테스트 주문", + "currency": "KRW", + "method": { + "type": "CARD" + }, + "paidAt": "2023-08-11T08:21:01.241Z" + }, + "settlementStartDate": "2023-08-12", + "orderLines": [], + "additionalFees": [], + "discounts": [], + "cancellation": { + "id": "cancellation_1", + "cancelledAt": "2023-08-12T11:57:15.292Z" } - }, - "platformFeeVatPayer": "PARTNER", - "isHidden": false, - "appliedAt": "2023-08-11T11:18:52.944447Z" - }, - "payment": { - "type": "EXTERNAL", - "id": "payment_1", - "orderName": "테스트 주문", - "currency": "KRW", - "method": { - "type": "CARD" - }, - "paidAt": "2023-08-11T08:21:01.241Z" - }, - "settlementStartDate": "2023-08-12", - "orderLines": [], - "additionalFees": [], - "discounts": [], - "cancellation": { - "id": "cancellation_1", - "cancelledAt": "2023-08-12T11:57:15.292Z" + } } - } -} -``` + ``` -**Error Code** + **Error Code** |Code|Description | |:---|:----------------------------------------------------------------------------------------------------------------------------| @@ -1765,99 +1676,98 @@ one of 로직에 해당되는 parameter가 다 표기되었습니다. `POST https://api.portone.io/platform/transfers/manual`
-
+
+ 수동 정산건이란 결제를 기반으로 하지않고 고객이 원하는 만큼 파트너에게 정산금을 추가 및 차감할 수 있는 api입니다. -수동 정산건이란 결제를 기반으로 하지않고 고객이 원하는 만큼 파트너에게 정산금을 추가 및 차감할 수 있는 api입니다. + **Parameters** -**Parameters** + **partnerId** string required -**partnerId** string required + 해당 수동 정산건이 적용될 파트너의 고유 아이디 -해당 수동 정산건이 적용될 파트너의 고유 아이디 + --- ---- + **settlementAmount** int required -**settlementAmount** int required + 해당 수동 정산건으로 적용하길 원하는 금액. 음수 및 양수 둘다 가능하다. -해당 수동 정산건으로 적용하길 원하는 금액. 음수 및 양수 둘다 가능하다. + --- ---- + **settlementDate** string required -**settlementDate** string required + `'yyyy-mm-dd'` 형식으로 보내주시면 됩니다. + 해당 수동 정산건이 적용되길 원하는 정산일. 꼭 정확한 정산일을 전달하셔야 합니다. -`'yyyy-mm-dd'` 형식으로 보내주시면 됩니다. -해당 수동 정산건이 적용되길 원하는 정산일. 꼭 정확한 정산일을 전달하셔야 합니다. + --- ---- + **memo** string optional -**memo** string optional + 해당 수동 정산건 등록시 내부 관리를 위해 전달하는 메모. + 50자 까지 가능하다다 -해당 수동 정산건 등록시 내부 관리를 위해 전달하는 메모. -50자 까지 가능하다다 + --- ---- + **isForTest** boolean optional 기본값은 false + + 포트원의 테스트 서버로 정산 데이터를 전달할지 여부를 결정한다. 기본값은 false이다. 테스트 서버로 전달할 경우 정산 데이터는 테스트 서버에만 저장되며 실제 정산에는 반영되지 않는다. +
-**isForTest** boolean optional 기본값은 false +
+ **Request Body** -포트원의 테스트 서버로 정산 데이터를 전달할지 여부를 결정한다. 기본값은 false이다. 테스트 서버로 전달할 경우 정산 데이터는 테스트 서버에만 저장되며 실제 정산에는 반영되지 않는다. + ```json + Example Value + Schema + { + "partnerId": "string", + "memo": "string", + "settlementAmount": 0, + "settlementDate": "string", + "isForTest": true + } + ``` -
-
-**Request Body** - -```json -Example Value -Schema -{ - "partnerId": "string", - "memo": "string", - "settlementAmount": 0, - "settlementDate": "string", - "isForTest": true -} -``` - -**Response** - -수동 정산객체가 반환된다. - -```json -{ - "transfer": { - "type": "MANUAL", - "id": "01H7W8JQF61EXTRYWCT667CYK2", - "graphqlId": "NjowMUg3VzhKUUY2MUVYVFJZV0NUNjY3Q1lLMg==", - "partner": { - "id": "partnerA", - "graphqlId": "NDpwYXJ0bmVyQQ==", - "name": "파이썬 강사", - "email": "kjnkyj12@gmail.com", - "businessRegistrationNumber": "1178178260", - "account": { - "bank": "SHINHAN", - "currency": "KRW", - "number": "10358907249", - "holder": "김준일", - "status": "VERIFIED" - }, - "status": "APPROVED", - "defaultContractId": "contractA", - "memo": "잭슨 테스트 예시문", - "tags": ["파이썬"], - "isHidden": false, - "appliedAt": "2023-08-11T11:19:58.829787Z" - }, - "status": "IN_PROCESS", - "memo": "테스트 수동 정산", - "settlementDate": "2023-09-27", - "settlementCurrency": "KRW", - "isForTest": false, - "settlementAmount": 100000 - } -} -``` - -**Error Code** + **Response** + + 수동 정산객체가 반환된다. + + ```json + { + "transfer": { + "type": "MANUAL", + "id": "01H7W8JQF61EXTRYWCT667CYK2", + "graphqlId": "NjowMUg3VzhKUUY2MUVYVFJZV0NUNjY3Q1lLMg==", + "partner": { + "id": "partnerA", + "graphqlId": "NDpwYXJ0bmVyQQ==", + "name": "파이썬 강사", + "email": "kjnkyj12@gmail.com", + "businessRegistrationNumber": "1178178260", + "account": { + "bank": "SHINHAN", + "currency": "KRW", + "number": "10358907249", + "holder": "김준일", + "status": "VERIFIED" + }, + "status": "APPROVED", + "defaultContractId": "contractA", + "memo": "잭슨 테스트 예시문", + "tags": ["파이썬"], + "isHidden": false, + "appliedAt": "2023-08-11T11:19:58.829787Z" + }, + "status": "IN_PROCESS", + "memo": "테스트 수동 정산", + "settlementDate": "2023-09-27", + "settlementCurrency": "KRW", + "isForTest": false, + "settlementAmount": 100000 + } + } + ``` + + **Error Code** |Code|Description | |:---|:--------------------------------------------------------------------------------------------------------------------------------------------| @@ -1877,109 +1787,135 @@ Schema `GET https://api.portone.io/platform/transfers/{id}`
-
+
+ 등록된 정산객체를 조회합니다. -등록된 정산객체를 조회합니다. + **Parameters** -**Parameters** + Request Body 는 없습니다. +
-Request Body 는 없습니다. +
+ **Request** -
-
- -**Request** - -```text -curl -X GET https://api.portone.com/v2/platform/transfers/{id} \ - -h {Authorization: Bearer {access_token}} -``` - -**Response** - -정산정보가 반환됩니다. - -```json -{ - "transfer": { - "type": "ORDER", - "id": "01H7HVM3YYCYQC3HF6KN4VZYZ2", - "graphqlId": "NjowMUg3SFZNM1lZQ1lRQzNIRjZLTjRWWllaMg==", - "partner": { - "id": "partner_2", - "graphqlId": "NDpwYXJ0bmVyXzI=", - "name": "파이썬 강사", - "email": "kjnkyj12@gmail.com", - "businessRegistrationNumber": "1178178260", - "account": { - "bank": "SHINHAN", - "currency": "KRW", - "number": "10358907249", - "holder": "김준일", - "status": "VERIFIED" - }, - "status": "APPROVED", - "defaultContractId": "contract_2", - "memo": "잭슨 테스트", - "tags": ["파이썬"], - "isHidden": false, - "appliedAt": "2023-08-09T07:39:25.645014Z" - }, - "status": "IN_PROCESS", - "memo": "testing order transfer", - "settlementDate": "2023-08-18", - "settlementCurrency": "KRW", - "isForTest": true, - "amount": { - "settlement": 17250, - "payment": 20000, - "order": 25000, - "platformFee": 2500, - "platformFeeVat": 0, - "additionalFee": 2500, - "additionalFeeVat": 250, - "discount": 5000, - "discountShare": 2500 - }, - "contract": { - "id": "contract_2", - "graphqlId": "NTpjb250cmFjdF8y", - "memo": "contract 2", - "platformFee": { "type": "FIXED_RATE", "rate": 10000 }, - "settlementCycle": { - "lagDays": 2, - "datePolicy": "CALENDAR_DAY", - "method": { "type": "WEEKLY", "daysOfWeek": ["FRI"] } - }, - "platformFeeVatPayer": "MERCHANT", - "isHidden": false, - "appliedAt": "2023-08-09T07:39:17.207733Z" - }, - "payment": { - "type": "EXTERNAL", - "id": "payment_1", - "orderName": "테스트 주문", - "currency": "KRW", - "method": { "type": "CARD" }, - "paidAt": "2023-08-11T08:21:01.241Z" - }, - "settlementStartDate": "2023-08-11", - "orderLines": [ - { - "product": { "id": "1", "name": "product_1", "amount": 5000 }, - "quantity": 5, - "discounts": [ + ```text + curl -X GET https://api.portone.com/v2/platform/transfers/{id} \ + -h {Authorization: Bearer {access_token}} + ``` + + **Response** + + 정산정보가 반환됩니다. + + ```json + { + "transfer": { + "type": "ORDER", + "id": "01H7HVM3YYCYQC3HF6KN4VZYZ2", + "graphqlId": "NjowMUg3SFZNM1lZQ1lRQzNIRjZLTjRWWllaMg==", + "partner": { + "id": "partner_2", + "graphqlId": "NDpwYXJ0bmVyXzI=", + "name": "파이썬 강사", + "email": "kjnkyj12@gmail.com", + "businessRegistrationNumber": "1178178260", + "account": { + "bank": "SHINHAN", + "currency": "KRW", + "number": "10358907249", + "holder": "김준일", + "status": "VERIFIED" + }, + "status": "APPROVED", + "defaultContractId": "contract_2", + "memo": "잭슨 테스트", + "tags": ["파이썬"], + "isHidden": false, + "appliedAt": "2023-08-09T07:39:25.645014Z" + }, + "status": "IN_PROCESS", + "memo": "testing order transfer", + "settlementDate": "2023-08-18", + "settlementCurrency": "KRW", + "isForTest": true, + "amount": { + "settlement": 17250, + "payment": 20000, + "order": 25000, + "platformFee": 2500, + "platformFeeVat": 0, + "additionalFee": 2500, + "additionalFeeVat": 250, + "discount": 5000, + "discountShare": 2500 + }, + "contract": { + "id": "contract_2", + "graphqlId": "NTpjb250cmFjdF8y", + "memo": "contract 2", + "platformFee": { "type": "FIXED_RATE", "rate": 10000 }, + "settlementCycle": { + "lagDays": 2, + "datePolicy": "CALENDAR_DAY", + "method": { "type": "WEEKLY", "daysOfWeek": ["FRI"] } + }, + "platformFeeVatPayer": "MERCHANT", + "isHidden": false, + "appliedAt": "2023-08-09T07:39:17.207733Z" + }, + "payment": { + "type": "EXTERNAL", + "id": "payment_1", + "orderName": "테스트 주문", + "currency": "KRW", + "method": { "type": "CARD" }, + "paidAt": "2023-08-11T08:21:01.241Z" + }, + "settlementStartDate": "2023-08-11", + "orderLines": [ { - "sharePolicy": { - "id": "discount_1", - "graphqlId": "MjpkaXNjb3VudF8x", - "partnerShareRate": 500000000, - "memo": "테스트 할인", - "isHidden": false, - "appliedAt": "2023-08-09T07:45:45.799176Z" - }, - "amount": 2500, - "shareAmount": 1250 + "product": { "id": "1", "name": "product_1", "amount": 5000 }, + "quantity": 5, + "discounts": [ + { + "sharePolicy": { + "id": "discount_1", + "graphqlId": "MjpkaXNjb3VudF8x", + "partnerShareRate": 500000000, + "memo": "테스트 할인", + "isHidden": false, + "appliedAt": "2023-08-09T07:45:45.799176Z" + }, + "amount": 2500, + "shareAmount": 1250 + } + ], + "additionalFees": [ + { + "policy": { + "id": "addtional_fee_1", + "graphqlId": "MzphZGR0aW9uYWxfZmVlXzE=", + "fee": { "type": "FIXED_RATE", "rate": 5000 }, + "memo": "테스트 추가수수료", + "vatPayer": "PARTNER", + "isHidden": false, + "appliedAt": "2023-08-09T07:41:12.393974Z" + }, + "amount": 1250, + "vat": 125 + } + ], + "amount": { + "settlement": 19875, + "payment": 22500, + "order": 25000, + "platformFee": 2500, + "platformFeeVat": 0, + "additionalFee": 1250, + "additionalFeeVat": 125, + "discount": 2500, + "discountShare": 1250 + } } ], "additionalFees": [ @@ -1997,1302 +1933,1164 @@ curl -X GET https://api.portone.com/v2/platform/transfers/{id} \ "vat": 125 } ], - "amount": { - "settlement": 19875, - "payment": 22500, - "order": 25000, - "platformFee": 2500, - "platformFeeVat": 0, - "additionalFee": 1250, - "additionalFeeVat": 125, - "discount": 2500, - "discountShare": 1250 - } - } - ], - "additionalFees": [ - { - "policy": { - "id": "addtional_fee_1", - "graphqlId": "MzphZGR0aW9uYWxfZmVlXzE=", - "fee": { "type": "FIXED_RATE", "rate": 5000 }, - "memo": "테스트 추가수수료", - "vatPayer": "PARTNER", - "isHidden": false, - "appliedAt": "2023-08-09T07:41:12.393974Z" - }, - "amount": 1250, - "vat": 125 - } - ], - "discounts": [ - { - "sharePolicy": { - "id": "discount_1", - "graphqlId": "MjpkaXNjb3VudF8x", - "partnerShareRate": 500000000, - "memo": "테스트 할인", - "isHidden": false, - "appliedAt": "2023-08-09T07:45:45.799176Z" - }, - "amount": 2500, - "shareAmount": 1250 + "discounts": [ + { + "sharePolicy": { + "id": "discount_1", + "graphqlId": "MjpkaXNjb3VudF8x", + "partnerShareRate": 500000000, + "memo": "테스트 할인", + "isHidden": false, + "appliedAt": "2023-08-09T07:45:45.799176Z" + }, + "amount": 2500, + "shareAmount": 1250 + } + ] } - ] - } -} -``` - -
+ } + ``` +
--- ## 계약 -
-
-`계약` 객체는 고객사가 파트너에게 정산해줄 대금과 정산일을 계산하는데 적용되는 정보입니다. - -고객사의 플랫폼에서 재화 및 서비스를 판매하는데에 대한 중개수수료정보와 판매금에 대한 정산을 언제 해주는지 알려주는 정산일로 구성되어 있습니다. +
+
+ `계약` 객체는 고객사가 파트너에게 정산해줄 대금과 정산일을 계산하는데 적용되는 정보입니다. -
-
-**Endpoints** - -```text -POST /platform/contracts -GET /platform/contract/{id} -PATCH /platform/contract/{id} -POST /platform/contracts/numered-pages -POST /platform/contracts/{id}/schedule -PUT /platform/contracts/{id}/schedule -GET /platform/contracts/{id}/schedule -DELETE /platform/contracts/{id}/schedule -GET /platform/contract-filter-options -``` + 고객사의 플랫폼에서 재화 및 서비스를 판매하는데에 대한 중개수수료정보와 판매금에 대한 정산을 언제 해주는지 알려주는 정산일로 구성되어 있습니다. +
-
+
+ **Endpoints** + + ```text + POST /platform/contracts + GET /platform/contract/{id} + PATCH /platform/contract/{id} + POST /platform/contracts/numered-pages + POST /platform/contracts/{id}/schedule + PUT /platform/contracts/{id}/schedule + GET /platform/contracts/{id}/schedule + DELETE /platform/contracts/{id}/schedule + GET /platform/contract-filter-options + ``` +
--- ### 계약 객체 -
-
-Attributes - -**id** string - -계약객체의 고유 아이디 - ---- - -**graphqlId** string - -계약객체의 고유 아이디 (포트원 내부 graphql버전) - -**memo** string - -계약객체 내부 표기를 위한 메모 - ---- - -**platformFee** dictionary - -중개수수료. 기본 **Fee** attribute 을 사용한다. - -one of logic 으로 정액, 정률 중 하나만 사용할 수 있다. - - - - - - - - - - -
- - platformFee.**amount** int64 - - 정액일 경우 사용하는 parameter. 현재로서 정액 플랫폼 중개 수수료는 원화만 지원한다. - -
- - platformFee.**fixedRate** int64 - - 정률일 경우 10^-5표기. 즉 10% → 10000 으로 입력. - -
- ---- - -**settlementCycle** dictionary - -정산주기 Attribute. 지체일, 정산일, 기준일로 구성되어있다. 해당 요소들의 조합으로 정산일을 계산한다. - - - - - - - - + 계약객체 내부 표기를 위한 메모 - - - - - -
- - settlementCycle.**lagDays** int64 - - 지체일(d+n의 n).정산시작일(통상주문완료일) 로 부터 더해진다음 날짜로부터 가장 가까운 날에 정산이 된다. 최소 1 최대 10 까지 지정할 수 있다. - -
- - settlementCycle.**datePolicy** enum - - 기준일이며 정산일 계산시 공휴일을 고려하기 위함이다. 값은 달력일, 전 영업일, 후 영업일 이렇게 3가지가 있다. - 값: CALENDAR_DAY, HOLIDAY_BEFORE, HOLIDAY_AFTER - - - - - - - - - - - -
+
+
+ Attributes - **CALENDAR_DAY** 달력일. 정산일 계산시 공휴일을 고려하지 않습니다. + **id** string -
+ 계약객체의 고유 아이디 - **HOLIDAY_BEFORE** 전 영업일. 정산일 계산시 공휴일을 고려하여 공휴일이 정산일이 되는 경우에는 공휴일 전 영업일로 정산일을 계산합니다. + --- -
+ **graphqlId** string - **HOLIDAY_AFTER** 후 영업일. 정산일 계산시 공휴일을 고려하여 공휴일이 정산일이 되는 경우에는 공휴일 후 영업일로 정산일을 계산합니다. + 계약객체의 고유 아이디 (포트원 내부 graphql버전) -
+ **memo** string -
+ --- - settlementCycle.**method** dictionary + **platformFee** dictionary - 정산주기 관련되서 매일, 주에 n회, 달에 n회, 특정 분기 혹은 지정된 날짜에 정산을 할수 있도록 정산주기의 기간별 종류를 정할 수 있다. 값으론 daily, weekly, monthly, manualDates 가 있습니다. + 중개수수료. 기본 **Fee** attribute 을 사용한다. - 계약별 정산 주기의 method는 매일, 주 n회, 달 n회, 지정된 날짜 중 하나만 택할 수 있습니다. + one of logic 으로 정액, 정률 중 하나만 사용할 수 있다. - - - - - - - - - - -
+ platformFee.**amount** int64 - method.**type** enum - - 정산 주기의 종류를 나타냅니다. 값으론 daily, weekly, monthly, manualDates 가 있습니다. - - |값 |설명 | - |---------------|-------------------------| - |**DAILY** |매일 | - |**WEEKLY** |주 n회. 최대 2회까지 가능| - |**MONTHLY** |달 n회. 최대 3회까지 가능| - |**MANUALDATES**|지정된 날짜 | + 정액일 경우 사용하는 parameter. 현재로서 정액 플랫폼 중개 수수료는 원화만 지원한다.
- - method.**daily** json dicionary - 정산 주기가 매일일때 단순히 빈 json '{}' 을 입력하면 됩니다. - - 혹시나 격일 과 같은 특정 패턴에 정산을 지정하고 싶으시면 문의 부탁드립니다. - -
+ platformFee.**fixedRate** int64 - method.**weekly** dicionary - - weekly attribute - - - - - -
- - weekly.**dayOfWeek** enum - - 정산 주기가 주 n회일때 n, 특정 요일들을 지정 할 수 있습니다. 최대 두가지 요일을 지정 할 수 있습니다. - i.e. ['MON', 'WED'] 는 매주 월요일, 수요일에 정산을 한다는 의미입니다. - 두가지 이상의 요일을 지정 하고 싶으시면 문의 부탁드립니다. - - 요일 enum - - - - - - - - - - - - - - - - - - - - - - - -
- - **MON** 월요일 - -
- - **TUE** 화요일 - -
- - **WED** 수요일 - -
- - **THU** 목요일 - -
- - **FRI** 금요일 - -
- - **SAT** 토요일 - -
- - **SUN** 일요일 - -
-
-
- - method.**monthly** dictionary - - monthly attribute - - - - - -
- - monthly.**dayOfMonth** list of int64 - - 정산 주기가 달 n회일때 n, 특정 날짜들을 지정 할 수 있습니다. 최대 두가지 날짜를 지정 할 수 있습니다. - i.e. [1, 15] 는 매월 1일, 15일에 정산을 한다는 의미입니다. - - 31 의 경우에는 월말로 지정됩니다. - - 두가지 이상의 날짜를 지정 하고 싶으시면 문의 부탁드립니다. - -
-
- - method.**manualDates** dicionary - - manualDates attribute - - - - - -
- - manualDates.**dates** - - 정산 주기가 특정 분기 혹은 지정된 날짜('MM-DD')일때 지정된 날짜들을 지정 할 수 있습니다. 최대 여덜가지 날짜를 지정 할 수 있습니다. - - dates attribute - - - - - - - - -
- - dates.**month** int64 - - 달로써 1-12 사이의 값을 가집니다. - -
- - dates.**day** int64 - - 일로써 1-31 사이의 값을 가집니다. - - 만약에 없는 일을 지정할 경우 에러를 반환합니다. - -
- - 여덜가지 이상의 날짜를 지정 하고 싶으시면 문의 부탁드립니다. - -
-
-
- -- 정산주기 값 설정 예시 - -```javascript -settlementCycle = { - lay_days: 3, - method: { - monthly: { - dayOfMonth: [15, 31], - }, - }, - datePolicy: "HOLIDAY_BEFORE", -}; -``` - -case 1: 10일 주문완료 (settlementStartDate) - -- d + 3일 = 13일 -- 13일의 그다음 정산일 = 15일 -- if 15일이 영업일이라면 정산일 = 15일 -- elif 15일이 영업일이 아니라면 i.e. 토요일 이라면 정산일 = 14일 - -case 2: 13일 주문완료 - -- d + 3일 = 16일 -- 16일의 그다음 정산일 = 31일 -- if 31일이 영업일이라면 정산일 = 31일 -- elif 31일이 영업일이 아니라면 i.e. 토요일 이라면 정산일 = 30일 - ---- - -**platformFeeVatPayer** enum - -해당 계약의 중개수수료에 대해서 부가세 포함 여부. -값: PARTNER, MERCHANT - -**PARTNER**: 부가세 파트너 부담 - -**MERCHANT**: 부가세 파트너 미부담 - ---- - -**isHidden** boolean - -계약 객체 숨기처리 여부. 숨김 처리는 soft delete이라고 생각하시면 됩니다. - ---- - -**appliedAt** Datetime - -계약 객체가 업데이트 된 시점. - ---- - -
-
-**Response (월별 정산)** - -```json -{ - "id": "contract_2", - "graphqlId": "NTpjb250cmFjdF8y", - "memo": "contract 2", - "platformFee": { "type": "FIXED_RATE", "rate": 10000 }, - "settlementCycle": { - "lagDays": 2, - "datePolicy": "CALENDAR_DAY", - "method": { "type": "MONTHLY", "daysOfmonth": [31] } - }, - "platformFeeVatPayer": "MERCHANT", - "isHidden": false, - "appliedAt": "2023-08-09T07:39:17.207733Z" -} -``` - -**Response (일별 정산)** - -```json -{ - "id": "contract_2", - "graphqlId": "NTpjb250cmFjdF8y", - "memo": "contract 2", - "platformFee": { "type": "FIXED_RATE", "rate": 10000 }, - "settlementCycle": { - "lagDays": 2, - "datePolicy": "CALENDAR_DAY", - "method": { "type": "DAILY", "daily": {} } - }, - "platformFeeVatPayer": "MERCHANT", - "isHidden": false, - "appliedAt": "2023-08-09T07:39:17.207733Z" -} -``` - -**Response (주별 정산)** - -```json -{ - "id": "contract_2", - "graphqlId": "NTpjb250cmFjdF8y", - "memo": "contract 2", - "platformFee": { "type": "FIXED_RATE", "rate": 10000 }, - "settlementCycle": { - "lagDays": 2, - "datePolicy": "CALENDAR_DAY", - "method": { "type": "WEEKLY", "daysOfWeek": ["FRI"] } - }, - "platformFeeVatPayer": "MERCHANT", - "isHidden": false, - "appliedAt": "2023-08-09T07:39:17.207733Z" -} -``` - -**Response (월-일 정산)** - -```json -{"id": "contract_2", - "graphqlId": "NTpjb250cmFjdF8y", - "memo": "contract 2", - "platformFee": {"type": "FIXED_RATE", "rate": 10000}, - "settlementCycle": {"lagDays": 2, - "datePolicy": "CALENDAR_DAY", - "method": {"type": "MANUALDATES", "dates": ["month": 1, "day": 1]}}, - "platformFeeVatPayer": "MERCHANT", - "isHidden": false, - "appliedAt": "2023-08-09T07:39:17.207733Z"} -``` - -
-
- ---- - -### 계약 생성 - -`POST https://api.portone.io/platform/contracts` - -
-
-새로운 계약을 생성합니다. - -**Parameters** - -**id** optional string - -계약객체에 부여하는 고유 아이디. 전달하지 않을경우 response에서 포트원이 임의로 발급해 드립니다. - ---- - -**memo** optional string - -계약객체 내부 표기를 위한 메모 - ---- - -**platformFee** required dictionary - -중개수수료. 기본 **Fee** attribute 을 사용한다. + 정률일 경우 10^-5표기. 즉 10% → 10000 으로 입력. + + + -**Amount** (정액 수수료) 혹은 **dRate** (정률 수수료) 둘 중 하나만 전달 하셔야 합니다. + --- - - - +
+ **settlementCycle** dictionary - platformFee.**Amount** int64 + 정산주기 Attribute. 지체일, 정산일, 기준일로 구성되어있다. 해당 요소들의 조합으로 정산일을 계산한다. - 정액일 경우 사용하는 parameter. 현재로서 정액 플랫폼 중개 수수료는 원화만 지원한다. -
+ + - - + - platformFee.**Rate** int64 + + + 기준일이며 정산일 계산시 공휴일을 고려하기 위함이다. 값은 달력일, 전 영업일, 후 영업일 이렇게 3가지가 있다. + 값: CALENDAR\_DAY, HOLIDAY\_BEFORE, HOLIDAY\_AFTER - -
+ settlementCycle.**lagDays** int64 -
+ 지체일(d+n의 n).정산시작일(통상주문완료일) 로 부터 더해진다음 날짜로부터 가장 가까운 날에 정산이 된다. 최소 1 최대 10 까지 지정할 수 있다. +
+ settlementCycle.**datePolicy** enum - 정률일 경우 10^-5표기. 즉 10% → 10000 으로 입력. -
+ + + + ---- + + + -**settlementCycle** required dictionary + + + +
+ **CALENDAR\_DAY** 달력일. 정산일 계산시 공휴일을 고려하지 않습니다. +
+ **HOLIDAY\_BEFORE** 전 영업일. 정산일 계산시 공휴일을 고려하여 공휴일이 정산일이 되는 경우에는 공휴일 전 영업일로 정산일을 계산합니다. +
+ **HOLIDAY\_AFTER** 후 영업일. 정산일 계산시 공휴일을 고려하여 공휴일이 정산일이 되는 경우에는 공휴일 후 영업일로 정산일을 계산합니다. +
+ + -정산주기 Attribute. 지체일, 정산일, 기준일로 구성되어있다. 해당 요소들의 조합으로 정산일을 계산한다. + + + settlementCycle.**method** dictionary - - - - - - - - - + 정액일 경우 사용하는 parameter. 현재로서 정액 플랫폼 중개 수수료는 원화만 지원한다. + + - -
+ 정산주기 관련되서 매일, 주에 n회, 달에 n회, 특정 분기 혹은 지정된 날짜에 정산을 할수 있도록 정산주기의 기간별 종류를 정할 수 있다. 값으론 daily, weekly, monthly, manualDates 가 있습니다. - settlementCycle.**lagDays** int64 + 계약별 정산 주기의 method는 매일, 주 n회, 달 n회, 지정된 날짜 중 하나만 택할 수 있습니다. - 지체일(d+n의 n).정산시작일(통상주문완료일) 로 부터 더해진다음 날짜로부터 가장 가까운 날에 정산이 된다. 최소 1 최대 10 까지 지정할 수 있다. + + + + 정산 주기의 종류를 나타냅니다. 값으론 daily, weekly, monthly, manualDates 가 있습니다. - - - + - settlementCycle.**datePolicy** enum + + + - 정산주기 관련되서 매일, 주에 n회, 달에 n회, 특정 분기 혹은 지정된 날짜에 정산을 할수 있도록 정산주기의 기간별 종류를 정할 수 있다. 값으론 daily, weekly, monthly, manualDates 가 있습니다. + + - -
+ method.**type** enum -
+ |값 |설명 | + |---------------|-------------------------| + |**DAILY** |매일 | + |**WEEKLY** |주 n회. 최대 2회까지 가능| + |**MONTHLY** |달 n회. 최대 3회까지 가능| + |**MANUALDATES**|지정된 날짜 | +
+ method.**daily** json dicionary - 기준일이며 정산일 계산시 공휴일을 고려하기 위함이다. 값은 달력일, 전 영업일, 후 영업일 이렇게 3가지가 있다. - 값: CALENDAR_DAY, HOLIDAY_BEFORE, HOLIDAY_AFTER + 정산 주기가 매일일때 단순히 빈 json '{}' 을 입력하면 됩니다. - - - + - **CALENDAR_DAY** 달력일. 정산일 계산시 공휴일을 고려하지 않습니다. + + - - - + - - - - + - -
+ 혹시나 격일 과 같은 특정 패턴에 정산을 지정하고 싶으시면 문의 부탁드립니다. +
+ method.**weekly** dicionary -
+ weekly attribute - **HOLIDAY_BEFORE** 전 영업일. 정산일 계산시 공휴일을 고려하여 공휴일이 정산일이 되는 경우에는 공휴일 전 영업일로 정산일을 계산합니다. + + + + +
+ weekly.**dayOfWeek** enum + + 정산 주기가 주 n회일때 n, 특정 요일들을 지정 할 수 있습니다. 최대 두가지 요일을 지정 할 수 있습니다. + i.e. \['MON', 'WED'] 는 매주 월요일, 수요일에 정산을 한다는 의미입니다. + 두가지 이상의 요일을 지정 하고 싶으시면 문의 부탁드립니다. + + 요일 enum + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ **MON** 월요일 +
+ **TUE** 화요일 +
+ **WED** 수요일 +
+ **THU** 목요일 +
+ **FRI** 금요일 +
+ **SAT** 토요일 +
+ **SUN** 일요일 +
+
+
+
+ method.**monthly** dictionary - **HOLIDAY_AFTER** 후 영업일. 정산일 계산시 공휴일을 고려하여 공휴일이 정산일이 되는 경우에는 공휴일 후 영업일로 정산일을 계산합니다. + monthly attribute -
+ + + + 정산 주기가 달 n회일때 n, 특정 날짜들을 지정 할 수 있습니다. 최대 두가지 날짜를 지정 할 수 있습니다. + i.e. \[1, 15] 는 매월 1일, 15일에 정산을 한다는 의미입니다. - - - + +
+ monthly.**dayOfMonth** list of int64 -
+ 31 의 경우에는 월말로 지정됩니다. - settlementCycle.**method** dictionary + 두가지 이상의 날짜를 지정 하고 싶으시면 문의 부탁드립니다. +
+
+ method.**manualDates** dicionary - 계약별 정산 주기의 method는 매일, 주 n회, 달 n회, 지정된 날짜 중 하나만 택할 수 있습니다. + manualDates attribute - - - + +
+ + + + +
+ manualDates.**dates** - method.**daily** json dicionary + 정산 주기가 특정 분기 혹은 지정된 날짜('MM-DD')일때 지정된 날짜들을 지정 할 수 있습니다. 최대 여덜가지 날짜를 지정 할 수 있습니다. - 정산 주기가 매일일때 단순히 빈 json '{}' 을 입력하면 됩니다. + dates attribute - 혹시나 격일 과 같은 특정 패턴에 정산을 지정하고 싶으시면 문의 부탁드립니다. + + + - - - + - method.**weekly** dicionary + + + +
+ dates.**month** int64 -
+ 달로써 1-12 사이의 값을 가집니다. +
+ dates.**day** int64 - weekly attribute + 일로써 1-31 사이의 값을 가집니다. - - - + +
+ 만약에 없는 일을 지정할 경우 에러를 반환합니다. +
- weekly.**daysOfWeek** enum + 여덜가지 이상의 날짜를 지정 하고 싶으시면 문의 부탁드립니다. +
+
+
- 정산 주기가 주 n회일때 n, 특정 요일들을 지정 할 수 있습니다. 최대 두가지 요일을 지정 할 수 있습니다. - i.e. ['MON', 'WED'] 는 매주 월요일, 수요일에 정산을 한다는 의미입니다. - 두가지 이상의 요일을 지정 하고 싶으시면 문의 부탁드립니다. + - 정산주기 값 설정 예시 - 요일 enum + ```javascript + settlementCycle = { + lay_days: 3, + method: { + monthly: { + dayOfMonth: [15, 31], + }, + }, + datePolicy: "HOLIDAY_BEFORE", + }; + ``` - - - - - - - - - - - - - - - - - - - - - - -
+ case 1: 10일 주문완료 (settlementStartDate) - **MON** 월요일 + - d + 3일 = 13일 + - 13일의 그다음 정산일 = 15일 + - if 15일이 영업일이라면 정산일 = 15일 + - elif 15일이 영업일이 아니라면 i.e. 토요일 이라면 정산일 = 14일 -
+ case 2: 13일 주문완료 - **TUE** 화요일 + - d + 3일 = 16일 + - 16일의 그다음 정산일 = 31일 + - if 31일이 영업일이라면 정산일 = 31일 + - elif 31일이 영업일이 아니라면 i.e. 토요일 이라면 정산일 = 30일 -
+ --- - **WED** 수요일 + **platformFeeVatPayer** enum -
+ 해당 계약의 중개수수료에 대해서 부가세 포함 여부. + 값: PARTNER, MERCHANT - **THU** 목요일 + **PARTNER**: 부가세 파트너 부담 -
+ **MERCHANT**: 부가세 파트너 미부담 - **FRI** 금요일 + --- -
+ **isHidden** boolean - **SAT** 토요일 -
+ 계약 객체 숨기처리 여부. 숨김 처리는 soft delete이라고 생각하시면 됩니다. - **SUN** 일요일 + --- -
+ **appliedAt** Datetime -
+ 계약 객체가 업데이트 된 시점. -
+ --- + - method.**monthly** dictionary +
+ **Response (월별 정산)** - monthly attribute + ```json + { + "id": "contract_2", + "graphqlId": "NTpjb250cmFjdF8y", + "memo": "contract 2", + "platformFee": { "type": "FIXED_RATE", "rate": 10000 }, + "settlementCycle": { + "lagDays": 2, + "datePolicy": "CALENDAR_DAY", + "method": { "type": "MONTHLY", "daysOfmonth": [31] } + }, + "platformFeeVatPayer": "MERCHANT", + "isHidden": false, + "appliedAt": "2023-08-09T07:39:17.207733Z" + } + ``` - - - - -
- monthly.**daysOfMonth** list of int64 + **Response (일별 정산)** - 정산 주기가 달 n회일때 n, 특정 날짜들을 지정 할 수 있습니다. 최대 두가지 날짜를 지정 할 수 있습니다. - i.e. [1, 15] 는 매월 1일, 15일에 정산을 한다는 의미입니다. + ```json + { + "id": "contract_2", + "graphqlId": "NTpjb250cmFjdF8y", + "memo": "contract 2", + "platformFee": { "type": "FIXED_RATE", "rate": 10000 }, + "settlementCycle": { + "lagDays": 2, + "datePolicy": "CALENDAR_DAY", + "method": { "type": "DAILY", "daily": {} } + }, + "platformFeeVatPayer": "MERCHANT", + "isHidden": false, + "appliedAt": "2023-08-09T07:39:17.207733Z" + } + ``` - 31 의 경우에는 월말로 지정됩니다. + **Response (주별 정산)** - 두가지 이상의 날짜를 지정 하고 싶으시면 문의 부탁드립니다. + ```json + { + "id": "contract_2", + "graphqlId": "NTpjb250cmFjdF8y", + "memo": "contract 2", + "platformFee": { "type": "FIXED_RATE", "rate": 10000 }, + "settlementCycle": { + "lagDays": 2, + "datePolicy": "CALENDAR_DAY", + "method": { "type": "WEEKLY", "daysOfWeek": ["FRI"] } + }, + "platformFeeVatPayer": "MERCHANT", + "isHidden": false, + "appliedAt": "2023-08-09T07:39:17.207733Z" + } + ``` -
+ **Response (월-일 정산)** -
+ ```json + {"id": "contract_2", + "graphqlId": "NTpjb250cmFjdF8y", + "memo": "contract 2", + "platformFee": {"type": "FIXED_RATE", "rate": 10000}, + "settlementCycle": {"lagDays": 2, + "datePolicy": "CALENDAR_DAY", + "method": {"type": "MANUALDATES", "dates": ["month": 1, "day": 1]}}, + "platformFeeVatPayer": "MERCHANT", + "isHidden": false, + "appliedAt": "2023-08-09T07:39:17.207733Z"} + ``` + + - method.**manualDates** dicionary +--- - manualDates attribute +### 계약 생성 - - - - -
+`POST https://api.portone.io/platform/contracts` - manualDates.**dates** +
+
+ 새로운 계약을 생성합니다. - 정산 주기가 특정 분기 혹은 지정된 날짜('MM-DD')일때 지정된 날짜들을 지정 할 수 있습니다. 최대 여덜가지 날짜를 지정 할 수 있습니다. + **Parameters** - dates attribute + **id** optional string - - - - - - - -
+ 계약객체에 부여하는 고유 아이디. 전달하지 않을경우 response에서 포트원이 임의로 발급해 드립니다. - dates.**month** int64 + --- - 달로써 1-12 사이의 값을 가집니다. + **memo** optional string -
+ 계약객체 내부 표기를 위한 메모 - dates.**day** int64 + --- - 일로써 1-31 사이의 값을 가집니다. + **platformFee** required dictionary - 만약에 없는 일을 지정할 경우 에러를 반환합니다. -
+ 중개수수료. 기본 **Fee** attribute 을 사용한다. - 여덜가지 이상의 날짜를 지정 하고 싶으시면 문의 부탁드립니다. + **Amount** (정액 수수료) 혹은 **dRate** (정률 수수료) 둘 중 하나만 전달 하셔야 합니다. -
+ + + - -
+ platformFee.**Amount** int64 -
-
+ + + platformFee.**Rate** int64 -- 정산주기 값 설정 예시 + 정률일 경우 10^-5표기. 즉 10% → 10000 으로 입력. + + + -```javascript -settlementCycle = { - lay_days: 3, - method: { - monthly: { - daysOfMonth: [15, 31], - }, - }, - datePolicy: "HOLIDAY_BEFORE", -}; -``` + --- -case 1: 10일 주문완료 (settlementStartDate) + **settlementCycle** required dictionary -- d + 3일 = 13일 -- 13일의 그다음 정산일 = 15일 -- if 15일이 영업일이라면 정산일 = 15일 -- elif 15일이 영업일이 아니라면 i.e. 토요일 이라면 정산일 = 14일 + 정산주기 Attribute. 지체일, 정산일, 기준일로 구성되어있다. 해당 요소들의 조합으로 정산일을 계산한다. -case 2: 13일 주문완료 + + + + ---- + + + ---- + + + +
+ settlementCycle.**lagDays** int64 -- d + 3일 = 16일 -- 16일의 그다음 정산일 = 31일 -- if 31일이 영업일이라면 정산일 = 31일 -- elif 31일이 영업일이 아니라면 i.e. 토요일 이라면 정산일 = 30일 + 지체일(d+n의 n).정산시작일(통상주문완료일) 로 부터 더해진다음 날짜로부터 가장 가까운 날에 정산이 된다. 최소 1 최대 10 까지 지정할 수 있다. +
+ settlementCycle.**datePolicy** enum -**platformFeeVatPayer** optional + 기준일이며 정산일 계산시 공휴일을 고려하기 위함이다. 값은 달력일, 전 영업일, 후 영업일 이렇게 3가지가 있다. + 값: CALENDAR\_DAY, HOLIDAY\_BEFORE, HOLIDAY\_AFTER -부가세 여부 + + + + -PARTNER: 부가세 파트너 부담 + + + -MERCHANT: 부가세 파트너 미부담 + + + +
+ **CALENDAR\_DAY** 달력일. 정산일 계산시 공휴일을 고려하지 않습니다. +
+ **HOLIDAY\_BEFORE** 전 영업일. 정산일 계산시 공휴일을 고려하여 공휴일이 정산일이 되는 경우에는 공휴일 전 영업일로 정산일을 계산합니다. +
+ **HOLIDAY\_AFTER** 후 영업일. 정산일 계산시 공휴일을 고려하여 공휴일이 정산일이 되는 경우에는 공휴일 후 영업일로 정산일을 계산합니다. +
+
+ settlementCycle.**method** dictionary - -
- -**Request Example** - -one of logic 을 다 담았습니다. - -```json -{ - "id": "string", - "memo": "string", - "platformFee": { - "fixedRate": 0, - "fixedAmount": 0 - }, - "settlementCycle": { - "lagDays": 0, - "datePolicy": "CALENDAR_DAY", - "method": { - "daily": {}, - "weekly": { - "daysOfWeek": ["FRI"] - }, - "monthly": { - "daysOfMonth": [0] - }, - "manualDates": { - "dates": [ - { - "month": 0, - "day": 0 - } - ] - } - } - }, - "platformFeeVatPayer": "MERCHANT" -} -``` - -**Response** - -생성된 계약 객체가 반환됩니다. - -```json -{ - "id": "contract_2", - "graphqlId": "NTpjb250cmFjdF8y", - "memo": "contract 2", - "platformFee": { "type": "FIXED_RATE", "rate": 10000 }, - "settlementCycle": { - "lagDays": 2, - "datePolicy": "CALENDAR_DAY", - "method": { "type": "WEEKLY", "daysOfWeek": ["FRI"] } - }, - "platformFeeVatPayer": "MERCHANT", - "isHidden": false, - "appliedAt": "2023-08-09T07:39:17.207733Z" -} -``` + 정산주기 관련되서 매일, 주에 n회, 달에 n회, 특정 분기 혹은 지정된 날짜에 정산을 할수 있도록 정산주기의 기간별 종류를 정할 수 있다. 값으론 daily, weekly, monthly, manualDates 가 있습니다. -
- + 계약별 정산 주기의 method는 매일, 주 n회, 달 n회, 지정된 날짜 중 하나만 택할 수 있습니다. ---- + + + + -
-
+
+ + - -
- -**Request** - -```shell -curl https://api.portone.com/v2/platform/contract/{id}\ - -h {'Bearer Token {YOUR TOKEN}'} \ -``` - -**Response** - -조회한 아이디의 계약객체가 반환됩니다. - -```json -{ - "contract": { - "id": "BBG4AY9P95", - "graphqlId": "NTpCQkc0QVk5UDk1", - "memo": "contract A", - "platformFee": { - "type": "FIXED_RATE", - "rate": 10000 - }, - "settlementCycle": { - "lagDays": 2, - "datePolicy": "HOLIDAY_AFTER", - "method": { - "type": "DAILY" - } - }, - "platformFeeVatPayer": "PARTNER", - "isHidden": false, - "appliedAt": "2023-08-15T14:31:23.586857Z" - } -} -``` +
+ + -주어진 아이디에 대응되는 계약을 업데이트합니다. + + + +
+ method.**daily** json dicionary -### 계약 조회 + 정산 주기가 매일일때 단순히 빈 json '{}' 을 입력하면 됩니다. -`GET https://api.portone.io/platform/contracts{id}` + 혹시나 격일 과 같은 특정 패턴에 정산을 지정하고 싶으시면 문의 부탁드립니다. +
+ method.**weekly** dicionary -**Parameters** + weekly attribute -None + + + + +
+ weekly.**daysOfWeek** enum + + 정산 주기가 주 n회일때 n, 특정 요일들을 지정 할 수 있습니다. 최대 두가지 요일을 지정 할 수 있습니다. + i.e. \['MON', 'WED'] 는 매주 월요일, 수요일에 정산을 한다는 의미입니다. + 두가지 이상의 요일을 지정 하고 싶으시면 문의 부탁드립니다. + + 요일 enum + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ **MON** 월요일 +
+ **TUE** 화요일 +
+ **WED** 수요일 +
+ **THU** 목요일 +
+ **FRI** 금요일 +
+ **SAT** 토요일 +
+ **SUN** 일요일 +
+
+
+ method.**monthly** dictionary - - + monthly attribute ---- + + + + +
+ monthly.**daysOfMonth** list of int64 -### 계약 수정 + 정산 주기가 달 n회일때 n, 특정 날짜들을 지정 할 수 있습니다. 최대 두가지 날짜를 지정 할 수 있습니다. + i.e. \[1, 15] 는 매월 1일, 15일에 정산을 한다는 의미입니다. -`PATCH https://api.portone.io/platform/contracts/{id}` + 31 의 경우에는 월말로 지정됩니다. -
-
+ 두가지 이상의 날짜를 지정 하고 싶으시면 문의 부탁드립니다. +
+
+ method.**manualDates** dicionary -해당 api는 호출 시점에 변경사항을 적용합니다. 변경사항을 미래 시점에 적용하고 싶다면 POST /v2/platform/contracts/{'{id}'}/schedule api를 사용하세요. + manualDates attribute -계약을 업데이트 하면 api 호출 시점 이후의 **settlementStartDate**를 가진 해당 계약의 정산에 변경사항이 적용됩니다. + + + + +
+ manualDates.**dates** -**Parameters** + 정산 주기가 특정 분기 혹은 지정된 날짜('MM-DD')일때 지정된 날짜들을 지정 할 수 있습니다. 최대 여덜가지 날짜를 지정 할 수 있습니다. -**id** required string (url path) + dates attribute -업데이트 하고자 하는 계약의 아이디 + + + + -**memo** optional string + + + +
+ dates.**month** int64 ---- + 달로써 1-12 사이의 값을 가집니다. +
+ dates.**day** int64 -계약객체 내부 표기를 위한 메모 + 일로써 1-31 사이의 값을 가집니다. ---- + 만약에 없는 일을 지정할 경우 에러를 반환합니다. +
-**platformFee** required dictionary + 여덜가지 이상의 날짜를 지정 하고 싶으시면 문의 부탁드립니다. +
+
+
-중개수수료. 기본 **Fee** attribute 을 사용한다. + - 정산주기 값 설정 예시 -**Amount** (정액 수수료) 혹은 **Rate** (정률 수수료) 둘 중 하나만 전달 하셔야 합니다. + ```javascript + settlementCycle = { + lay_days: 3, + method: { + monthly: { + daysOfMonth: [15, 31], + }, + }, + datePolicy: "HOLIDAY_BEFORE", + }; + ``` - - - + - d + 3일 = 16일 + - 16일의 그다음 정산일 = 31일 + - if 31일이 영업일이라면 정산일 = 31일 + - elif 31일이 영업일이 아니라면 i.e. 토요일 이라면 정산일 = 30일 - - - + PARTNER: 부가세 파트너 부담 - -
+ case 1: 10일 주문완료 (settlementStartDate) - platformFee.**Amount** int64 + - d + 3일 = 13일 + - 13일의 그다음 정산일 = 15일 + - if 15일이 영업일이라면 정산일 = 15일 + - elif 15일이 영업일이 아니라면 i.e. 토요일 이라면 정산일 = 14일 - 정액일 경우 사용하는 parameter. 현재로서 정액 플랫폼 중개 수수료는 원화만 지원한다. + case 2: 13일 주문완료 -
+ --- - platformFee.**Rate** int64 + **platformFeeVatPayer** optional - 정률일 경우 10^-5표기. 즉 10% → 10000 으로 입력. + 부가세 여부 -
+ MERCHANT: 부가세 파트너 미부담 ---- + --- +
-**settlementCycle** required dictionary +
+ **Request Example** -정산주기 Attribute. 지체일, 정산일, 기준일로 구성되어있다. 해당 요소들의 조합으로 정산일을 계산한다. + one of logic 을 다 담았습니다. - - - + ```json + { + "id": "contract_2", + "graphqlId": "NTpjb250cmFjdF8y", + "memo": "contract 2", + "platformFee": { "type": "FIXED_RATE", "rate": 10000 }, + "settlementCycle": { + "lagDays": 2, + "datePolicy": "CALENDAR_DAY", + "method": { "type": "WEEKLY", "daysOfWeek": ["FRI"] } + }, + "platformFeeVatPayer": "MERCHANT", + "isHidden": false, + "appliedAt": "2023-08-09T07:39:17.207733Z" + } + ``` + + - - - + ```json + { + "contract": { + "id": "BBG4AY9P95", + "graphqlId": "NTpCQkc0QVk5UDk1", + "memo": "contract A", + "platformFee": { + "type": "FIXED_RATE", + "rate": 10000 + }, + "settlementCycle": { + "lagDays": 2, + "datePolicy": "HOLIDAY_AFTER", + "method": { + "type": "DAILY" + } + }, + "platformFeeVatPayer": "PARTNER", + "isHidden": false, + "appliedAt": "2023-08-15T14:31:23.586857Z" + } + } + ``` + + - - - -
+ ```json + { + "id": "string", + "memo": "string", + "platformFee": { + "fixedRate": 0, + "fixedAmount": 0 + }, + "settlementCycle": { + "lagDays": 0, + "datePolicy": "CALENDAR_DAY", + "method": { + "daily": {}, + "weekly": { + "daysOfWeek": ["FRI"] + }, + "monthly": { + "daysOfMonth": [0] + }, + "manualDates": { + "dates": [ + { + "month": 0, + "day": 0 + } + ] + } + } + }, + "platformFeeVatPayer": "MERCHANT" + } + ``` - settlementCycle.**lagDays** int64 + **Response** - 지체일(d+n의 n).정산시작일(통상주문완료일) 로 부터 더해진다음 날짜로부터 가장 가까운 날에 정산이 된다. 최소 1 최대 10 까지 지정할 수 있다. + 생성된 계약 객체가 반환됩니다. -
+--- - settlementCycle.**datePolicy** enum +### 계약 조회 - 기준일이며 정산일 계산시 공휴일을 고려하기 위함이다. 값은 달력일, 전 영업일, 후 영업일 이렇게 3가지가 있다. - 값: CALENDAR_DAY, HOLIDAY_BEFORE, HOLIDAY_AFTER +`GET https://api.portone.io/platform/contracts{id}` - - - - - - - - - - -
+
+
+ **Parameters** - **CALENDAR_DAY** 달력일. 정산일 계산시 공휴일을 고려하지 않습니다. + None +
-
+
+ **Request** - **HOLIDAY_BEFORE** 전 영업일. 정산일 계산시 공휴일을 고려하여 공휴일이 정산일이 되는 경우에는 공휴일 전 영업일로 정산일을 계산합니다. + ```shell + curl https://api.portone.com/v2/platform/contract/{id}\ + -h {'Bearer Token {YOUR TOKEN}'} \ + ``` -
+ **Response** - **HOLIDAY_AFTER** 후 영업일. 정산일 계산시 공휴일을 고려하여 공휴일이 정산일이 되는 경우에는 공휴일 후 영업일로 정산일을 계산합니다. + 조회한 아이디의 계약객체가 반환됩니다. -
-
+--- - settlementCycle.**method** dictionary +### 계약 수정 - 정산주기 관련되서 매일, 주에 n회, 달에 n회, 특정 분기 혹은 지정된 날짜에 정산을 할수 있도록 정산주기의 기간별 종류를 정할 수 있다. 값으론 daily, weekly, monthly, manualDates 가 있습니다. +`PATCH https://api.portone.io/platform/contracts/{id}` - 계약별 정산 주기의 method는 매일, 주 n회, 달 n회, 지정된 날짜 중 하나만 택할 수 있습니다. +
+
+ 주어진 아이디에 대응되는 계약을 업데이트합니다. - - - - - - + +
+ 해당 api는 호출 시점에 변경사항을 적용합니다. 변경사항을 미래 시점에 적용하고 싶다면 POST /v2/platform/contracts/{'{id}'}/schedule api를 사용하세요. - method.**daily** json dicionary + 계약을 업데이트 하면 api 호출 시점 이후의 **settlementStartDate**를 가진 해당 계약의 정산에 변경사항이 적용됩니다. - 정산 주기가 매일일때 단순히 빈 json '{}' 을 입력하면 됩니다. + **Parameters** - 혹시나 격일 과 같은 특정 패턴에 정산을 지정하고 싶으시면 문의 부탁드립니다. + **id** required string (url path) -
+ 업데이트 하고자 하는 계약의 아이디 - method.**weekly** dicionary + --- - weekly attribute + **memo** optional string - - - + - - - + +
+ 계약객체 내부 표기를 위한 메모 - weekly.**daysOfWeek** enum + --- - 정산 주기가 주 n회일때 n, 특정 요일들을 지정 할 수 있습니다. 최대 두가지 요일을 지정 할 수 있습니다. - i.e. ['MON', 'WED'] 는 매주 월요일, 수요일에 정산을 한다는 의미입니다. - 두가지 이상의 요일을 지정 하고 싶으시면 문의 부탁드립니다. + **platformFee** required dictionary - 요일 enum + 중개수수료. 기본 **Fee** attribute 을 사용한다. - - - - - - - - - + - - -
+ **Amount** (정액 수수료) 혹은 **Rate** (정률 수수료) 둘 중 하나만 전달 하셔야 합니다. - **MON** 월요일 + + + - - - + - **TUE** 화요일 + + - - - + +
+ platformFee.**Amount** int64 -
+ 정액일 경우 사용하는 parameter. 현재로서 정액 플랫폼 중개 수수료는 원화만 지원한다. +
+ platformFee.**Rate** int64 -
+ 정률일 경우 10^-5표기. 즉 10% → 10000 으로 입력. +
- **WED** 수요일 + --- -
+ **settlementCycle** required dictionary - **THU** 목요일 + 정산주기 Attribute. 지체일, 정산일, 기준일로 구성되어있다. 해당 요소들의 조합으로 정산일을 계산한다. -
+ + + + - - - - + - - - + + +
+ settlementCycle.**lagDays** int64 - **FRI** 금요일 + 지체일(d+n의 n).정산시작일(통상주문완료일) 로 부터 더해진다음 날짜로부터 가장 가까운 날에 정산이 된다. 최소 1 최대 10 까지 지정할 수 있다. +
+
+ settlementCycle.**datePolicy** enum - **SAT** 토요일 + 기준일이며 정산일 계산시 공휴일을 고려하기 위함이다. 값은 달력일, 전 영업일, 후 영업일 이렇게 3가지가 있다. + 값: CALENDAR\_DAY, HOLIDAY\_BEFORE, HOLIDAY\_AFTER -
+ + + + - **SUN** 일요일 + + + - - -
+ **CALENDAR\_DAY** 달력일. 정산일 계산시 공휴일을 고려하지 않습니다. +
+ **HOLIDAY\_BEFORE** 전 영업일. 정산일 계산시 공휴일을 고려하여 공휴일이 정산일이 되는 경우에는 공휴일 전 영업일로 정산일을 계산합니다. +
+
+ **HOLIDAY\_AFTER** 후 영업일. 정산일 계산시 공휴일을 고려하여 공휴일이 정산일이 되는 경우에는 공휴일 후 영업일로 정산일을 계산합니다. +
+
+
+ settlementCycle.**method** dictionary -
+ 정산주기 관련되서 매일, 주에 n회, 달에 n회, 특정 분기 혹은 지정된 날짜에 정산을 할수 있도록 정산주기의 기간별 종류를 정할 수 있다. 값으론 daily, weekly, monthly, manualDates 가 있습니다. - method.**monthly** dictionary + 계약별 정산 주기의 method는 매일, 주 n회, 달 n회, 지정된 날짜 중 하나만 택할 수 있습니다. - monthly attribute + + + - - - + + 여덜가지 이상의 날짜를 지정 하고 싶으시면 문의 부탁드립니다. + + +
+ method.**daily** json dicionary - - - + - 정산 주기가 달 n회일때 n, 특정 날짜들을 지정 할 수 있습니다. 최대 두가지 날짜를 지정 할 수 있습니다. - i.e. [1, 15] 는 매월 1일, 15일에 정산을 한다는 의미입니다. + + + - - -
+ 정산 주기가 매일일때 단순히 빈 json '{}' 을 입력하면 됩니다. - monthly.**daysOfMonth** list of int64 + 혹시나 격일 과 같은 특정 패턴에 정산을 지정하고 싶으시면 문의 부탁드립니다. +
+ method.**weekly** dicionary - 31 의 경우에는 월말로 지정됩니다. + weekly attribute - 두가지 이상의 날짜를 지정 하고 싶으시면 문의 부탁드립니다. + + + + +
+ weekly.**daysOfWeek** enum + + 정산 주기가 주 n회일때 n, 특정 요일들을 지정 할 수 있습니다. 최대 두가지 요일을 지정 할 수 있습니다. + i.e. \['MON', 'WED'] 는 매주 월요일, 수요일에 정산을 한다는 의미입니다. + 두가지 이상의 요일을 지정 하고 싶으시면 문의 부탁드립니다. + + 요일 enum + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ **MON** 월요일 +
+ **TUE** 화요일 +
+ **WED** 수요일 +
+ **THU** 목요일 +
+ **FRI** 금요일 +
+ **SAT** 토요일 +
+ **SUN** 일요일 +
+
+
-
+
+ method.**monthly** dictionary - method.**manualDates** dicionary + monthly attribute - manualDates attribute + + + + - dates attribute + + - -
+ monthly.**daysOfMonth** list of int64 - - - + +
+ 정산 주기가 달 n회일때 n, 특정 날짜들을 지정 할 수 있습니다. 최대 두가지 날짜를 지정 할 수 있습니다. + i.e. \[1, 15] 는 매월 1일, 15일에 정산을 한다는 의미입니다. - manualDates.**dates** + 31 의 경우에는 월말로 지정됩니다. - 정산 주기가 특정 분기 혹은 지정된 날짜('MM-DD')일때 지정된 날짜들을 지정 할 수 있습니다. 최대 여덜가지 날짜를 지정 할 수 있습니다. + 두가지 이상의 날짜를 지정 하고 싶으시면 문의 부탁드립니다. +
+
+ method.**manualDates** dicionary - - - - -
+ manualDates attribute - dates.**month** int64 + + + - - - + +
+ manualDates.**dates** - 달로써 1-12 사이의 값을 가집니다. + 정산 주기가 특정 분기 혹은 지정된 날짜('MM-DD')일때 지정된 날짜들을 지정 할 수 있습니다. 최대 여덜가지 날짜를 지정 할 수 있습니다. -
+ dates attribute - dates.**day** int64 + + + + - 만약에 없는 일을 지정할 경우 에러를 반환합니다. + + - -
+ dates.**month** int64 - 일로써 1-31 사이의 값을 가집니다. + 달로써 1-12 사이의 값을 가집니다. +
+ dates.**day** int64 -
+ 일로써 1-31 사이의 값을 가집니다. - 여덜가지 이상의 날짜를 지정 하고 싶으시면 문의 부탁드립니다. + 만약에 없는 일을 지정할 경우 에러를 반환합니다. +
-
-
-
+
+
-
+ --- ---- + **platformVatPayer** optional enum -**platformVatPayer** optional enum + 부가세 여부 -부가세 여부 + PARTNER: 부가세 파트너 부담 -PARTNER: 부가세 파트너 부담 + MERCHANT: 부가세 파트너 미부담 -MERCHANT: 부가세 파트너 미부담 + --- ---- + **isHidden** optional boolean -**isHidden** optional boolean + 계약 숨김 여부. 기본 값은 false 입니다. +
-계약 숨김 여부. 기본 값은 false 입니다. +
+ **Request Example** -
-
- -**Request Example** - -```json -{ - "memo": "string", - "platformFee": { - "fixedRate": 0, - "fixedAmount": 0 - }, - "settlementCycle": { - "lagDays": 0, - "datePolicy": "CALENDAR_DAY", - "method": { - "daily": {}, - "weekly": { - "daysOfWeek": ["FRI"] - }, - "monthly": { - "daysOfMonth": [0] + ```json + { + "memo": "string", + "platformFee": { + "fixedRate": 0, + "fixedAmount": 0 }, - "manualDates": { - "dates": [ - { - "month": 0, - "day": 0 + "settlementCycle": { + "lagDays": 0, + "datePolicy": "CALENDAR_DAY", + "method": { + "daily": {}, + "weekly": { + "daysOfWeek": ["FRI"] + }, + "monthly": { + "daysOfMonth": [0] + }, + "manualDates": { + "dates": [ + { + "month": 0, + "day": 0 + } + ] } - ] - } + } + }, + "platformFeeVatPayer": "MERCHANT", + "isHidden": true } - }, - "platformFeeVatPayer": "MERCHANT", - "isHidden": true -} -``` - -**Response** - -```json -{ - "id": "contract_2", - "graphqlId": "NTpjb250cmFjdF8y", - "memo": "contract 2", - "platformFee": { "type": "FIXED_RATE", "rate": 10000 }, - "settlementCycle": { - "lagDays": 2, - "datePolicy": "CALENDAR_DAY", - "method": { "type": "WEEKLY", "daysOfWeek": ["FRI"] } - }, - "platformFeeVatPayer": "MERCHANT", - "isHidden": false, - "appliedAt": "2023-08-09T07:39:17.207733Z" -} -``` + ``` + **Response** + + ```json + { + "id": "contract_2", + "graphqlId": "NTpjb250cmFjdF8y", + "memo": "contract 2", + "platformFee": { "type": "FIXED_RATE", "rate": 10000 }, + "settlementCycle": { + "lagDays": 2, + "datePolicy": "CALENDAR_DAY", + "method": { "type": "WEEKLY", "daysOfWeek": ["FRI"] } + }, + "platformFeeVatPayer": "MERCHANT", + "isHidden": false, + "appliedAt": "2023-08-09T07:39:17.207733Z" + } + ```
@@ -3302,123 +3100,108 @@ MERCHANT: 부가세 파트너 미부담 `GET https://api.portone.io/platform/contracts` -
-
- -페이지 기반으로 여러 계약을 조회합니다. - -**page** optional - -요청할 페이지 정보 - -페이지 번호를 통한 다건 조회 API에 필요한 입력 정보 - - - - - - - - - - -
- - page.**size** integer required 각 페이지 당 포함할 객체 수. 기본값은 10 - -
- - page.**number** integer required 페이지 번호. 0 부터 시작합니다. - -
- ---- - -**filter** dictionary - -다건 조회시 적용하고 싶은 필터 값. +
+
+ 페이지 기반으로 여러 계약을 조회합니다. - - - - - + 다건 조회시 적용하고 싶은 필터 값. - - - + + ---- + + + +
+ **page** optional - filter.**includeHidden** boolean optional + 요청할 페이지 정보 - true일 경우 숨김 처리된 파트너가 조회됩니다. + 페이지 번호를 통한 다건 조회 API에 필요한 입력 정보 - 기본값은 false입니다. + + + + - + + + +
+ page.**size** integer required 각 페이지 당 포함할 객체 수. 기본값은 10 +
+ page.**number** integer required 페이지 번호. 0 부터 시작합니다. +
-
+ --- - filter.**tags** list of string optional 파트너에게 부여한 태그 리스트 값. + **filter** dictionary -
+ + + + 기본값은 false입니다. + + - -
+ filter.**includeHidden** boolean optional - filter.**keyword** one of dictionary 검색 조건. 조건중 한 값을 지정하여 - %like% 검색한다. + true일 경우 숨김 처리된 파트너가 조회됩니다. -
+
+ filter.**tags** list of string optional 파트너에게 부여한 태그 리스트 값. +
+ filter.**keyword** one of dictionary 검색 조건. 조건중 한 값을 지정하여 + %like% 검색한다. +
-
-
+ --- +
-**Request** +
+ **Request** -```shell -curl -X DELETE https://api.portone.com/v2/platform/contract/{id}/numbered-pages \ - -u {api_key} -``` + ```shell + curl -X DELETE https://api.portone.com/v2/platform/contract/{id}/numbered-pages \ + -u {api_key} + ``` -**Response** + **Response** -request로 전달된 검색조건에 대응하는 여러 계약들이 반환됩니다. + request로 전달된 검색조건에 대응하는 여러 계약들이 반환됩니다. -```json -{ - "items": [ + ```json { - "id": "contract_1", - "memo": "셀러 기본 계약 1", - "platformFee": { - "rate": 100000000 - }, - "settlementCycle": { - "lagDays": 3, - "method": "monthly", - "method": { - "weekly": { - "daysOfWeek": ["FRI"] - } - }, - "datePolicy": "HOLIDAY_BEFORE" - }, - "vatPayer": "PARTNER", - "isHidden": false, - "appliedAt": "2021-01-01T00:00:00Z" //api 호출 시점 - } /// ... - ], - "page": { - "size": 10, - "number": 0, - "totalCount": 10 - } -} -``` - -
+ "items": [ + { + "id": "contract_1", + "memo": "셀러 기본 계약 1", + "platformFee": { + "rate": 100000000 + }, + "settlementCycle": { + "lagDays": 3, + "method": "monthly", + "method": { + "weekly": { + "daysOfWeek": ["FRI"] + } + }, + "datePolicy": "HOLIDAY_BEFORE" + }, + "vatPayer": "PARTNER", + "isHidden": false, + "appliedAt": "2021-01-01T00:00:00Z" //api 호출 시점 + } /// ... + ], + "page": { + "size": 10, + "number": 0, + "totalCount": 10 + } + } + ``` +
--- @@ -3427,98 +3210,95 @@ request로 전달된 검색조건에 대응하는 여러 계약들이 반환됩 `POST https://api.portone.io/platform/contracts/{id}/schedule` -
-
+
+
+ 주어진 아이디에 대응되는 계약에 업데이트를 예약합니다. -주어진 아이디에 대응되는 계약에 업데이트를 예약합니다. + "update" 필드에 업데이트를 예약할 정보를 입력합니다. -"update" 필드에 업데이트를 예약할 정보를 입력합니다. + "appliedAt" 필드에 적용되길 원하는 시점을 입력합니다. -"appliedAt" 필드에 적용되길 원하는 시점을 입력합니다. + **Parameter** -**Parameter** + **update** dictionary required -**update** dictionary required + 예약 업데이트 하고 싶은 계약 정보 + 기존 [계약 수정](#계약-수정) API와 동일한 파라미터를 사용합니다. -예약 업데이트 하고 싶은 계약 정보 -기존 [계약 수정](#계약-수정) API와 동일한 파라미터를 사용합니다. + **appliedAt** Datetime required -**appliedAt** Datetime required + 업데이트가 적용되길 원하는 시점 입니다.다. -업데이트가 적용되길 원하는 시점 입니다.다. + **settlementStartDate** 기접으로 적용됩니다. 예를 들어 appliedAt 이 t-0 이라면 t-0 이후의 settlementStartDate 인 해당 계약의 정산건들은 업데이트가 적용됩니다. +
-**settlementStartDate** 기접으로 적용됩니다. 예를 들어 appliedAt 이 t-0 이라면 t-0 이후의 settlementStartDate 인 해당 계약의 정산건들은 업데이트가 적용됩니다. +
+ **Request** -
-
- -**Request** - -```json -{ - "update": { - "memo": "string", - "platformFee": { - "fixedRate": 0, - "fixedAmount": 0 - }, - "settlementCycle": { - "lagDays": 0, - "datePolicy": "CALENDAR_DAY", - "method": { - "daily": {}, - "weekly": { - "daysOfWeek": ["FRI"] - }, - "monthly": { - "daysOfMonth": [0] + ```json + { + "update": { + "memo": "string", + "platformFee": { + "fixedRate": 0, + "fixedAmount": 0 }, - "manualDates": { - "dates": [ - { - "month": 0, - "day": 0 + "settlementCycle": { + "lagDays": 0, + "datePolicy": "CALENDAR_DAY", + "method": { + "daily": {}, + "weekly": { + "daysOfWeek": ["FRI"] + }, + "monthly": { + "daysOfMonth": [0] + }, + "manualDates": { + "dates": [ + { + "month": 0, + "day": 0 + } + ] } - ] - } - } - }, - "platformFeeVatPayer": "MERCHANT", - "isHidden": true - }, - "appliedAt": "2023-08-15T15:06:48.520Z" -} -``` - -**Response** - -```json -{ - "scheduledContract": { - "id": "contract_1", - "graphqlId": "aslkdflkdmvl==", - "memo": "셀러 기본 계약 1", - "platformFee": { - "rate": 100000000 - }, - "settlementCycle": { - "lagDays": 2, - "method": "weekly", - "method": { - "weekly": { - "daysOfWeek": ["FRI"] - } + } + }, + "platformFeeVatPayer": "MERCHANT", + "isHidden": true }, - "datePolicy": "HOLIDAY_BEFORE" - }, - "platformVatPayer": "PARTNER", - "isHidden": false, - "appliedAt": "2023-05-01T00:00:00Z" //예약 시점 - } -} -``` + "appliedAt": "2023-08-15T15:06:48.520Z" + } + ``` -
+ **Response** + + ```json + { + "scheduledContract": { + "id": "contract_1", + "graphqlId": "aslkdflkdmvl==", + "memo": "셀러 기본 계약 1", + "platformFee": { + "rate": 100000000 + }, + "settlementCycle": { + "lagDays": 2, + "method": "weekly", + "method": { + "weekly": { + "daysOfWeek": ["FRI"] + } + }, + "datePolicy": "HOLIDAY_BEFORE" + }, + "platformVatPayer": "PARTNER", + "isHidden": false, + "appliedAt": "2023-05-01T00:00:00Z" //예약 시점 + } + } + ``` +
--- @@ -3527,360 +3307,341 @@ request로 전달된 검색조건에 대응하는 여러 계약들이 반환됩 `PUT https://api.portone.io/platform/contracts/{id}/schedule` -
-
- -주어진 아이디에 대응되는 계약에 예약 업데이트를 재설정합니다. - -"update" 필드에 업데이트를 예약할 정보를 입력합니다. - -"appliedAt" 필드에 적용되길 원하는 시점을 입력합니다. - -해당 계약 에 대해서 이미 예약 업데이트가 존재하는 경우에는 해당 api를 사용해야하며 , 해당 api를 통해 업데이트 할경우 기존 예약 업데이트는 삭제됩니다. - -**Parameter** - -**update** dictionary required - -예약 업데이트 하고 싶은 계약 정보 -기존 [계약 수정](#계약-수정) API와 동일한 파라미터를 사용합니다. - -**appliedAt** Datetime required - -업데이트가 적용되길 원하는 시점 입니다.다. - -**settlementStartDate** 기접으로 적용됩니다. 예를 들어 appliedAt 이 t-0 이라면 t-0 이후의 settlementStartDate 인 해당 계약의 정산건들은 업데이트가 적용됩니다. - -
-
- -**Response** - -```json -{ - "scheduledContract": { - "id": "contract_1", - "memo": "셀러 기본 계약 1", - "platformFee": { - "rate": 10000 - }, - "settlementCycle": { - "lagDays": 2, - "method": "weekly", - "method": { - "weekly": { - "daysOfWeek": ["MON"] - } - }, - "datePolicy": "HOLIDAY_BEFORE" - }, - "platformVatPayer": "PARTNER", - "isHidden": false, - "appliedAt": "2023-06-01T00:00:00Z" //예약 시점 - } -} -``` +
+
+ 주어진 아이디에 대응되는 계약에 예약 업데이트를 재설정합니다. -
-
+ "update" 필드에 업데이트를 예약할 정보를 입력합니다. ---- + "appliedAt" 필드에 적용되길 원하는 시점을 입력합니다. -### 계약 예약 업데이트 조회 + 해당 계약 에 대해서 이미 예약 업데이트가 존재하는 경우에는 해당 api를 사용해야하며 , 해당 api를 통해 업데이트 할경우 기존 예약 업데이트는 삭제됩니다. -`GET https://api.portone.io/platform/contracts/{id}/schedule` + **Parameter** -
-
+ **update** dictionary required -주어진 아이디에 대응되는 계약에 예약 업데이트를 조회합니다 + 예약 업데이트 하고 싶은 계약 정보 + 기존 [계약 수정](#계약-수정) API와 동일한 파라미터를 사용합니다. -**Parameter** + **appliedAt** Datetime required -**id** required string (url path) + 업데이트가 적용되길 원하는 시점 입니다.다. -예약 업데이트를 조회할 계약의 아이디 + **settlementStartDate** 기접으로 적용됩니다. 예를 들어 appliedAt 이 t-0 이라면 t-0 이후의 settlementStartDate 인 해당 계약의 정산건들은 업데이트가 적용됩니다. +
-
-
- -**Response** - -```json -{ - "scheduledContract": { - "id": "contract_1", - "memo": "셀러 기본 계약 1", - "platformFee": { - "rate": 10000 - }, - "settlementCycle": { - "lagDays": 2, - "method": "weekly", - "method": { - "weekly": { - "daysOfWeek": ["MON"] - } - }, - "datePolicy": "HOLIDAY_BEFORE" - }, - "platformFeeVatPayer": "PARTNER", - "isHidden": false, - "appliedAt": "2023-06-01T00:00:00Z" //예약 시점 - } -} -``` +
+ **Response** -
+ ```json + { + "scheduledContract": { + "id": "contract_1", + "memo": "셀러 기본 계약 1", + "platformFee": { + "rate": 10000 + }, + "settlementCycle": { + "lagDays": 2, + "method": "weekly", + "method": { + "weekly": { + "daysOfWeek": ["MON"] + } + }, + "datePolicy": "HOLIDAY_BEFORE" + }, + "platformVatPayer": "PARTNER", + "isHidden": false, + "appliedAt": "2023-06-01T00:00:00Z" //예약 시점 + } + } + ``` +
--- -### 계약 예약 업데이트 삭제 +### 계약 예약 업데이트 조회 -`DELETE https://api.portone.io/platform/contracts/{id}/schedule` +`GET https://api.portone.io/platform/contracts/{id}/schedule` -
-
+
+
+ 주어진 아이디에 대응되는 계약에 예약 업데이트를 조회합니다 -주어진 아이디에 대응되는 계약에 예약 업데이트를 조회합니다 + **Parameter** -**Parameter** + **id** required string (url path) -**id** required string url path + 예약 업데이트를 조회할 계약의 아이디 +
-예약 업데이트를 삭제 할 계약의 아이디 +
+ **Response** + ```json + { + "scheduledContract": { + "id": "contract_1", + "memo": "셀러 기본 계약 1", + "platformFee": { + "rate": 10000 + }, + "settlementCycle": { + "lagDays": 2, + "method": "weekly", + "method": { + "weekly": { + "daysOfWeek": ["MON"] + } + }, + "datePolicy": "HOLIDAY_BEFORE" + }, + "platformFeeVatPayer": "PARTNER", + "isHidden": false, + "appliedAt": "2023-06-01T00:00:00Z" //예약 시점 + } + } + ``` +
-
-**Response** +--- + +### 계약 예약 업데이트 삭제 -200 성공 응답. 삭제된 예약 업데이트는 조회되지 않습니다. +`DELETE https://api.portone.io/platform/contracts/{id}/schedule` -
-
+
+
+ 주어진 아이디에 대응되는 계약에 예약 업데이트를 조회합니다 -## 파트너 + **Parameter** -
-
+ **id** required string url path -`파트너` 객체는 고객사가 정산해줘야할 대상입니다. + 예약 업데이트를 삭제 할 계약의 아이디 +
-기본 사업자 정보와 정산정보, 그리고 적용될 계약의 정보를 등록 및 관리할 수 있습니다. +
+ **Response** + 200 성공 응답. 삭제된 예약 업데이트는 조회되지 않습니다. +
-
-#### Endpoints +## 파트너 -```text -POST /platform/partners -POST /platform/partners/batch -GET /platform/partners/{id} -POST /platform/partners/{id} -POST /platform/partners/{id}/schedule -PUT /platform/partners/{id}/schedule -GET /platform/partners/{id}/schedule -DELETE /platform/partners/{id}/schedule -GET /platform/partner-filter-options -GET /platform/partners-dashbaord +
+
+ `파트너` 객체는 고객사가 정산해줘야할 대상입니다. -``` + 기본 사업자 정보와 정산정보, 그리고 적용될 계약의 정보를 등록 및 관리할 수 있습니다. +
-
+
+ ### Endpoints + + ```text + POST /platform/partners + POST /platform/partners/batch + GET /platform/partners/{id} + POST /platform/partners/{id} + POST /platform/partners/{id}/schedule + PUT /platform/partners/{id}/schedule + GET /platform/partners/{id}/schedule + DELETE /platform/partners/{id}/schedule + GET /platform/partner-filter-options + GET /platform/partners-dashbaord + + ``` +
--- ### 파트너 객체 -
-
- -**Attributes** - -**id** string - -파트너 고유 아이디. 전달해 주시거나 발급받으실 수 있습니다. - ---- +
+
+ **Attributes** -**graphqlId** string + **id** string -파트너 고유 아이디. 포트원 내부 용도 + 파트너 고유 아이디. 전달해 주시거나 발급받으실 수 있습니다. ---- + --- -**name** string + **graphqlId** string -파트너 법인명 혹은 이름. + 파트너 고유 아이디. 포트원 내부 용도 ---- + --- -**email** string + **name** string -파트너 이메일 + 파트너 법인명 혹은 이름. ---- + --- -**businessRegistrationNumber** string + **email** string -파트너 사업자번호. 개인 혹은 법인 사업자일때만 존재합니다. '-' 를 제외해야 합니다. + 파트너 이메일 ---- + --- -**account** dictionary + **businessRegistrationNumber** string -정산 계좌 Attribute + 파트너 사업자번호. 개인 혹은 법인 사업자일때만 존재합니다. '-' 를 제외해야 합니다. - - - - - -
+ --- - account.**bank** enum or string + **account** dictionary - 은행 이름. + 정산 계좌 Attribute - \- currnecy가 KRW일시 증권사가 제외된 한국 은행 코드별상의 [은행값 enum](#은행-enum-values) 하단 참고. 해당 은행값 외의 은행은 에러 처리\ - \- currency 가 KRW가 아닐때 해외 은행 string값으로 입력 가능 + + + + 은행 이름. - - - + - account.**currency** enum + + + - + + - - + - account.**number** string + + + - + + - - +
+ account.**bank** enum or string -
+ \- currnecy가 KRW일시 증권사가 제외된 한국 은행 코드별상의 [은행값 enum](#은행-enum-values) 하단 참고. 해당 은행값 외의 은행은 에러 처리\ + \- currency 가 KRW가 아닐때 해외 은행 string값으로 입력 가능 +
+ account.**currency** enum - 화페로써 현재로썬 KRW, JPY, USD만 지원한다. + 화페로써 현재로썬 KRW, JPY, USD만 지원한다. +
+ account.**number** string -
+ 계좌번호. currency가 KRW일경우 따로 예금주 조회 API를 통해 검증한다. 그 외의 화폐일 경우 따로 검증하지는 않는다. +
+ account.**holder** string - 계좌번호. currency가 KRW일경우 따로 예금주 조회 API를 통해 검증한다. 그 외의 화폐일 경우 따로 검증하지는 않는다. + 예금주. currency가 KRW일경우 따로 예금주 조회 API를 통해 검증한다. 그 외의 화폐일 경우 따로 검증하지는 않는다. +
+ account.**status** enum -
+ 계좌 상태. - account.**holder** string + + + + + - 예금주. currency가 KRW일경우 따로 예금주 조회 API를 통해 검증한다. 그 외의 화폐일 경우 따로 검증하지는 않는다. + + + + - + + + + - - - + + + - account.**status** enum + + + + - 계좌 상태. -
enumvalues
VERIFYING계좌 인증 중
VERIFIED계좌 인증 완료됨
+
VERIFY\_FAILED계좌 인증 실패함
EXPIRED계좌 인증 만료됨
- - - - - - - - - - - - - - - - - - - - - - - - + + + + +
enumvalues
VERIFYING계좌 인증 중
VERIFIED계좌 인증 완료됨
VERIFY_FAILED계좌 인증 실패함
EXPIRED계좌 인증 만료됨
UNKNOWN알 수 없는 상태
UNKNOWN알 수 없는 상태
+
-
---- + --- -**defaultContractId** string + **defaultContractId** string -파트너의 기본 계약 아이디 + 파트너의 기본 계약 아이디 -기본 계약 아이디란 파트너가 정산을 받을 때 적용되는 계약을 의미합니다. 파트너 정산시 여러개의 계약을 적용 할 수 있으나, 정산 API에 파트너 아이디만 전달 할 경우 기본 계약이 적용됩니다. + 기본 계약 아이디란 파트너가 정산을 받을 때 적용되는 계약을 의미합니다. 파트너 정산시 여러개의 계약을 적용 할 수 있으나, 정산 API에 파트너 아이디만 전달 할 경우 기본 계약이 적용됩니다. ---- + --- -**memo** string + **memo** string -파트너 메모. 내부 구분용으로 사용하실 수 있습니다. + 파트너 메모. 내부 구분용으로 사용하실 수 있습니다. ---- + --- -**tags** list of string + **tags** list of string -파트너 태그. 내부 구분용으로 사용하실 수 있습니다. + 파트너 태그. 내부 구분용으로 사용하실 수 있습니다. ---- + --- -**isHidden** boolean + **isHidden** boolean -파트너 숨김 여부. true일 경우 파트너 목록에서 숨김 처리됩니다. + 파트너 숨김 여부. true일 경우 파트너 목록에서 숨김 처리됩니다. -숨김이란 soft delete이라고 생각하시면 됩니다. + 숨김이란 soft delete이라고 생각하시면 됩니다. ---- + --- -**appliedAt** Datetime + **appliedAt** Datetime -해당 파트너가 업데이트 된 시각 + 해당 파트너가 업데이트 된 시각 +
-
-
- -#### Response - -```json -{ - "partner": { - "id": "partnerA", - "graphqlId": "NDpwYXJ0bmVyQQ==", - "name": "파이썬 강사", - "email": "kjnkyj12@gmail.com", - "businessRegistrationNumber": "1178178260", - "account": { - "bank": "SHINHAN", - "currency": "KRW", - "number": "10358907249", - "holder": "김준일", - "status": "VERIFIED" - }, - "status": "APPROVED", - "defaultContractId": "contractA", - "memo": "잭슨 테스트 예시문", - "tags": ["파이썬"], - "isHidden": false, - "appliedAt": "2023-08-11T11:19:58.829787Z" - } -} -``` +
+ #### Response -
+ ```json + { + "partner": { + "id": "partnerA", + "graphqlId": "NDpwYXJ0bmVyQQ==", + "name": "파이썬 강사", + "email": "kjnkyj12@gmail.com", + "businessRegistrationNumber": "1178178260", + "account": { + "bank": "SHINHAN", + "currency": "KRW", + "number": "10358907249", + "holder": "김준일", + "status": "VERIFIED" + }, + "status": "APPROVED", + "defaultContractId": "contractA", + "memo": "잭슨 테스트 예시문", + "tags": ["파이썬"], + "isHidden": false, + "appliedAt": "2023-08-11T11:19:58.829787Z" + } + } + ``` +
--- @@ -3889,158 +3650,146 @@ GET /platform/partners-dashbaord `POST https://api.portone.io/platform/partners` -
-
- -**Parameters** - -**id** optional - -파트너에 부여하는 고유 아이디. 고객사 서버에 등록된 파트너지칭 아이디와 동일해야 합니다. 따로 없다면 포트원이 발급해 드립니다. - ---- - -**name** string required - -파트너를 지칭하는 사업자명 및 이름 - ---- - -**email** string required +
+
+ **Parameters** -파트너 이메일 + **id** optional ---- + 파트너에 부여하는 고유 아이디. 고객사 서버에 등록된 파트너지칭 아이디와 동일해야 합니다. 따로 없다면 포트원이 발급해 드립니다. -**businessRegistrationNumber** string optional + --- -파트너 사업자번호. 검증하지는 않음. 번호 기호 둘다 가능 + **name** string required ---- + 파트너를 지칭하는 사업자명 및 이름 -**account** dictionary requried + --- -정산 계좌 Attribute + **email** string required - - - + --- - - - + --- - -
+ 파트너 이메일 - account.**bank** enum or string required + --- - 은행 이름. + **businessRegistrationNumber** string optional - \- currnecy가 KRW일시 증권사가 제외된 한국 은행 코드별상의 [은행값 enum](#은행-enum-values) 하단 참고. 해당 은행값 외의 은행은 에러 처리\ - \- currency 가 KRW가 아닐때 해외 은행 string값으로 입력 가능 + 파트너 사업자번호. 검증하지는 않음. 번호 기호 둘다 가능 -
+ **account** dictionary requried - account.**currency** enum required + 정산 계좌 Attribute - 화페로써 현재로썬 KRW, JPY, USD만 지원한다. + + + + 은행 이름. - - - + - account.**number** string required + + + - + + - - + - account.**holder** string required + + + +
+ account.**bank** enum or string required -
+ \- currnecy가 KRW일시 증권사가 제외된 한국 은행 코드별상의 [은행값 enum](#은행-enum-values) 하단 참고. 해당 은행값 외의 은행은 에러 처리\ + \- currency 가 KRW가 아닐때 해외 은행 string값으로 입력 가능 +
+ account.**currency** enum required - 계좌번호. currency가 KRW일경우 따로 예금주 조회 API를 통해 검증한다. 그 외의 화폐일 경우 따로 검증하지는 않는다. + 화페로써 현재로썬 KRW, JPY, USD만 지원한다. +
+ account.**number** string required -
+ 계좌번호. currency가 KRW일경우 따로 예금주 조회 API를 통해 검증한다. 그 외의 화폐일 경우 따로 검증하지는 않는다. +
+ account.**holder** string required - 예금주. currency가 KRW일경우 따로 예금주 조회 API를 통해 검증한다. 그 외의 화폐일 경우 따로 검증하지는 않는다. + 예금주. currency가 KRW일경우 따로 예금주 조회 API를 통해 검증한다. 그 외의 화폐일 경우 따로 검증하지는 않는다. +
-
+ **defaultContractId** string required ---- + 이미 존재하는 계약객체의 아이디를 등록해야합니다. -**defaultContractId** string required + --- -이미 존재하는 계약객체의 아이디를 등록해야합니다. + **memo** string optional ---- + 256자까지 가능합니다. -**memo** string optional + --- -256자까지 가능합니다. + **tag** list of string optional ---- + 최대 10개까지 가능합니다. -**tag** list of string optional + --- +
-최대 10개까지 가능합니다. +
+ **Request** ---- + ```json + { + "id": "string", + "name": "string", + "email": "string", + "businessRegistrationNumber": "string", + "account": { + "bank": "BNP", + "currency": "AED", + "number": "string", + "holder": "string" + }, + "defaultContractId": "string", + "memo": "string", + "tags": ["string"] + } + ``` -
+ **Response** -
-**Request** - -```json -{ - "id": "string", - "name": "string", - "email": "string", - "businessRegistrationNumber": "string", - "account": { - "bank": "BNP", - "currency": "AED", - "number": "string", - "holder": "string" - }, - "defaultContractId": "string", - "memo": "string", - "tags": ["string"] -} -``` - -**Response** - -파트너 객체가 반환됩니다. - -```json -{ - "partner": { - "id": "partnerA", - "graphqlId": "NDpwYXJ0bmVyQQ==", - "name": "파이썬 강사", - "email": "kjnkyj12@gmail.com", - "businessRegistrationNumber": "1178178260", - "account": { - "bank": "SHINHAN", - "currency": "KRW", - "number": "10358907249", - "holder": "김준일", - "status": "VERIFIED" - }, - "status": "APPROVED", - "defaultContractId": "contractA", - "memo": "잭슨 테스트 예시문", - "tags": ["파이썬"], - "isHidden": false, - "appliedAt": "2023-08-11T11:19:58.829787Z" - } -} -``` + 파트너 객체가 반환됩니다. -
+ ```json + { + "partner": { + "id": "partnerA", + "graphqlId": "NDpwYXJ0bmVyQQ==", + "name": "파이썬 강사", + "email": "kjnkyj12@gmail.com", + "businessRegistrationNumber": "1178178260", + "account": { + "bank": "SHINHAN", + "currency": "KRW", + "number": "10358907249", + "holder": "김준일", + "status": "VERIFIED" + }, + "status": "APPROVED", + "defaultContractId": "contractA", + "memo": "잭슨 테스트 예시문", + "tags": ["파이썬"], + "isHidden": false, + "appliedAt": "2023-08-11T11:19:58.829787Z" + } + } + ``` +
--- @@ -4049,50 +3798,47 @@ GET /platform/partners-dashbaord `GET https://api.portone.io/platform/partners/{id}` -
-
+
+
+ **Parameters** -**Parameters** + **id** required (url path) -**id** required (url path) + 조회하고 싶은 파트너 고유 아이디 -조회하고 싶은 파트너 고유 아이디 + --- +
---- +
+ **Response** -
-
- -**Response** - -파트너 객체가 반환됩니다. - -```json -{ - "partner": { - "id": "partnerA", - "graphqlId": "NDpwYXJ0bmVyQQ==", - "name": "파이썬 강사", - "email": "kjnkyj12@gmail.com", - "businessRegistrationNumber": "1178178260", - "account": { - "bank": "SHINHAN", - "currency": "KRW", - "number": "10358907249", - "holder": "김준일", - "status": "VERIFIED" - }, - "status": "APPROVED", - "defaultContractId": "contractA", - "memo": "잭슨 테스트 예시문", - "tags": ["파이썬"], - "isHidden": false, - "appliedAt": "2023-08-11T11:19:58.829787Z" - } -} -``` + 파트너 객체가 반환됩니다. -
+ ```json + { + "partner": { + "id": "partnerA", + "graphqlId": "NDpwYXJ0bmVyQQ==", + "name": "파이썬 강사", + "email": "kjnkyj12@gmail.com", + "businessRegistrationNumber": "1178178260", + "account": { + "bank": "SHINHAN", + "currency": "KRW", + "number": "10358907249", + "holder": "김준일", + "status": "VERIFIED" + }, + "status": "APPROVED", + "defaultContractId": "contractA", + "memo": "잭슨 테스트 예시문", + "tags": ["파이썬"], + "isHidden": false, + "appliedAt": "2023-08-11T11:19:58.829787Z" + } + } + ``` +
--- @@ -4101,134 +3847,181 @@ GET /platform/partners-dashbaord `GET https://api.portone.io/platform/partners` -
-
+
+
+ 페이지 기반으로 여러 파트너를 조회합니다. + + **Parameters** -페이지 기반으로 여러 파트너를 조회합니다. + --- -**Parameters** + **page** optional ---- + 요청할 페이지 정보 -**page** optional + 페이지 번호를 통한 다건 조회 API에 필요한 입력 정보 -요청할 페이지 정보 + + + + -페이지 번호를 통한 다건 조회 API에 필요한 입력 정보 + + + +
+ page.**size** integer required 각 페이지 당 포함할 객체 수. 기본값은 10 +
page.**number** integer required 페이지 번호. 0 부터 시작합니다.
- - - - - - - -
- page.**size** integer required 각 페이지 당 포함할 객체 수. 기본값은 10 -
page.**number** integer required 페이지 번호. 0 부터 시작합니다.
+ --- ---- + **filter** dictionary -**filter** dictionary + 다건 조회시 적용하고 싶은 필터 값. -다건 조회시 적용하고 싶은 필터 값. + + + + -
+ filter.**includeHidden** boolean optional + + true일 경우 숨김 처리된 파트너가 조회됩니다. + + 기본값은 false입니다. +
- - + + - filter.**includeHidden** boolean optional + + + - true일 경우 숨김 처리된 파트너가 조회됩니다. + + + - - - - - - - + + +
+
+ filter.**tags** list of string optional 파트너에게 부여한 태그 리스트 값. +
+ filter.**keyword** one of dictionary 검색 조건. 조건중 한 값을 지정하여 + %like% 검색한다. + + \- keyword.id 파트너 아이디 \ + \- keyword.name 파트너 이름 \ + \- keyword.email 파트너 이메일 \ + \- keyword.businessRegistrationNumber 파트너 사업자 번호 \ + \- keyword.defaultContractId 파트너 기본 계약 아이디 \ + \- keyword.memo 파트너 메모 \ + \- keyword.accountBank 파트너 계좌 은행 \ + \- keyword.accountCurrency 파트너 계좌 통화 \ + \- keyword.accountNumber 파트너 계좌 번호\ + \- keyword.accountHolder 파트너 계좌 예금주 +
+ filter.**banks** list of string - 기본값은 false입니다. + 파트너 계좌 은행 리스트 값. +
- filter.**tags** list of string optional 파트너에게 부여한 태그 리스트 값. -
- filter.**keyword** one of dictionary 검색 조건. 조건중 한 값을 지정하여 - %like% 검색한다. +
+ filter.accountCurrencies list of enum - \- keyword.id 파트너 아이디 \ - \- keyword.name 파트너 이름 \ - \- keyword.email 파트너 이메일 \ - \- keyword.businessRegistrationNumber 파트너 사업자 번호 \ - \- keyword.defaultContractId 파트너 기본 계약 아이디 \ - \- keyword.memo 파트너 메모 \ - \- keyword.accountBank 파트너 계좌 은행 \ - \- keyword.accountCurrency 파트너 계좌 통화 \ - \- keyword.accountNumber 파트너 계좌 번호\ - \- keyword.accountHolder 파트너 계좌 예금주 + 파트너 계좌 통화 리스트 값. + KRW, USD, JPY +
- + --- +
- - - - filter.**banks** list of string +
+ **Request** - 파트너 계좌 은행 리스트 값. - + ```json + { + "page": { + "number": 0, + "size": 0 + }, + "filter": { + "includeHidden": true, + "tags": ["string"], + "banks": ["BNP"], + "accountCurrencies": ["AED"], + "keyword": { + "id": "string", + "name": "string", + "email": "string", + "businessRegistrationNumber": "string", + "defaultContractId": "string", + "memo": "string", + "accountNumber": "string", + "accountHolder": "string" + } + } + } + ``` - - - - filter.accountCurrencies list of enum + **Response** - 파트너 계좌 통화 리스트 값. - KRW, USD, JPY - + 여러 파트너 객체들이 리스트 형태로 반환됩니다. - - + ```json + { + "items": [ + { + "id": "string", + "graphqlId": "string", + "name": "string", + "email": "string", + "businessRegistrationNumber": "string", + "account": { + "bank": "BNP", + "currency": "AED", + "number": "string", + "holder": "string", + "status": "EXPIRED" + }, + "status": "APPROVED", + "defaultContractId": "string", + "memo": "string", + "tags": ["string"], + "isHidden": true, + "appliedAt": "2023-08-15T16:06:03.321Z" + } + ], + "page": { + "number": 0, + "size": 0, + "totalCount": 0 + } + } + ``` +
+
--- -
+### 파트너 수정 + +`PATCH https://api.portone.io/platform/partners/{id}` + +
- **Request** - -```json -{ - "page": { - "number": 0, - "size": 0 - }, - "filter": { - "includeHidden": true, - "tags": ["string"], - "banks": ["BNP"], - "accountCurrencies": ["AED"], - "keyword": { - "id": "string", - "name": "string", - "email": "string", - "businessRegistrationNumber": "string", - "defaultContractId": "string", - "memo": "string", - "accountNumber": "string", - "accountHolder": "string" - } - } -} -``` + 주어진 아이디에 대응하는 파트너 정보를 업데이트 합니다. + + **Parameters** -**Response** + id 를 제외한 모든 값을 수정할 수 있습니다. + [파트너 생성](#파트너-생성) API의 파라미터와 동일합니다. +
-여러 파트너 객체들이 리스트 형태로 반환됩니다. +
+ **Request** -```json -{ - "items": [ + ```json { - "id": "string", - "graphqlId": "string", "name": "string", "email": "string", "businessRegistrationNumber": "string", @@ -4236,284 +4029,227 @@ GET /platform/partners-dashbaord "bank": "BNP", "currency": "AED", "number": "string", - "holder": "string", - "status": "EXPIRED" + "holder": "string" }, - "status": "APPROVED", "defaultContractId": "string", "memo": "string", "tags": ["string"], - "isHidden": true, - "appliedAt": "2023-08-15T16:06:03.321Z" + "isHidden": true } - ], - "page": { - "number": 0, - "size": 0, - "totalCount": 0 - } -} -``` - -
-
- ---- + ``` -### 파트너 수정 - -`PATCH https://api.portone.io/platform/partners/{id}` - -
-
+ **Response** -주어진 아이디에 대응하는 파트너 정보를 업데이트 합니다. + 업데이트 된 파트너 객체가 반환됩니다. -**Parameters** + ```json + { + "partner": { + "id": "partnerA", + "graphqlId": "NDpwYXJ0bmVyQQ==", + "name": "파이썬 강사", + "email": "kjnkyj12@gmail.com", + "businessRegistrationNumber": "1178178260", + "account": { + "bank": "SHINHAN", + "currency": "KRW", + "number": "10358907249", + "holder": "김준일", + "status": "VERIFIED" + }, + "status": "APPROVED", + "defaultContractId": "contractA", + "memo": "잭슨 테스트 예시문", + "tags": ["파이썬"], + "isHidden": false, + "appliedAt": "2023-08-11T11:19:58.829787Z" + } + } + ``` -id 를 제외한 모든 값을 수정할 수 있습니다. -[파트너 생성](#파트너-생성) API의 파라미터와 동일합니다. + --- + \- UnauthorizedError: 인증 정보가 올바르지 않은 경우 +
-
-**Request** - -```json -{ - "name": "string", - "email": "string", - "businessRegistrationNumber": "string", - "account": { - "bank": "BNP", - "currency": "AED", - "number": "string", - "holder": "string" - }, - "defaultContractId": "string", - "memo": "string", - "tags": ["string"], - "isHidden": true -} -``` - -**Response** - -업데이트 된 파트너 객체가 반환됩니다. - -```json -{ - "partner": { - "id": "partnerA", - "graphqlId": "NDpwYXJ0bmVyQQ==", - "name": "파이썬 강사", - "email": "kjnkyj12@gmail.com", - "businessRegistrationNumber": "1178178260", - "account": { - "bank": "SHINHAN", - "currency": "KRW", - "number": "10358907249", - "holder": "김준일", - "status": "VERIFIED" - }, - "status": "APPROVED", - "defaultContractId": "contractA", - "memo": "잭슨 테스트 예시문", - "tags": ["파이썬"], - "isHidden": false, - "appliedAt": "2023-08-11T11:19:58.829787Z" - } -} -``` --- -\- UnauthorizedError: 인증 정보가 올바르지 않은 경우 - -
+### 파트너 예약 업데이트 -
+`POST https://api.portone.io/platform/partners/{id}/schedule` ---- +
+
+ 주어진 아이디에 대응하는 파트너의 업데이트를 예약합니다. -### 파트너 예약 업데이트 + **Parameters** -`POST https://api.portone.io/platform/partners/{id}/schedule` + --- -
-
-주어진 아이디에 대응하는 파트너의 업데이트를 예약합니다. + **id** required string url path -**Parameters** + 파트너 아이디. ---- + --- -**id** required string url path + **update** required json dicionary -파트너 아이디. + 업데이트 할 파트너의 정보를 담은 json dictionary + [파트너 생성](#파트너-생성) API의 파라미터와 동일합니다. ---- + --- -**update** required json dicionary + **appliedAt** required Datetime -업데이트 할 파트너의 정보를 담은 json dictionary -[파트너 생성](#파트너-생성) API의 파라미터와 동일합니다. + 업데이트를 적용할 시간. + 정산 시작일(settlementStartDate) 기준으로 시간이 적용됩니다. + 예를들어 2일에 파트너 기본계약 업데이트를 예약했으면 1일까지 정산시작일이 되어있는 해당 파트너의 정산 건은 구버전의 계약이 적용되고 + 2일부터는 새로운 계약이 적용됩니다. +
---- +
+ **Request** -**appliedAt** required Datetime + ```json + { + "update": { + "name": "string", + "email": "string", + "businessRegistrationNumber": "string", + "account": { + "bank": "BNP", + "currency": "AED", + "number": "string", + "holder": "string" + }, + "defaultContractId": "string", + "memo": "string", + "tags": ["string"], + "isHidden": true + }, + "appliedAt": "2023-08-15T16:20:15.312Z" + } + ``` -업데이트를 적용할 시간. -정산 시작일(settlementStartDate) 기준으로 시간이 적용됩니다. -예를들어 2일에 파트너 기본계약 업데이트를 예약했으면 1일까지 정산시작일이 되어있는 해당 파트너의 정산 건은 구버전의 계약이 적용되고 -2일부터는 새로운 계약이 적용됩니다. + **Response** -
-
- -**Request** - -```json -{ - "update": { - "name": "string", - "email": "string", - "businessRegistrationNumber": "string", - "account": { - "bank": "BNP", - "currency": "AED", - "number": "string", - "holder": "string" - }, - "defaultContractId": "string", - "memo": "string", - "tags": ["string"], - "isHidden": true - }, - "appliedAt": "2023-08-15T16:20:15.312Z" -} -``` - -**Response** - -성공 응답으로 예약된 파트너 객체가 반환됩니다. - -```json -{ - "scheduledPartner": { - "id": "string", - "graphqlId": "string", - "name": "string", - "email": "string", - "businessRegistrationNumber": "string", - "account": { - "bank": "BNP", - "currency": "AED", - "number": "string", - "holder": "string", - "status": "EXPIRED" - }, - "status": "APPROVED", - "defaultContractId": "string", - "memo": "string", - "tags": ["string"], - "isHidden": true, - "appliedAt": "2023-08-15T16:20:15.397Z" - } -} -``` + 성공 응답으로 예약된 파트너 객체가 반환됩니다. -
+ ```json + { + "scheduledPartner": { + "id": "string", + "graphqlId": "string", + "name": "string", + "email": "string", + "businessRegistrationNumber": "string", + "account": { + "bank": "BNP", + "currency": "AED", + "number": "string", + "holder": "string", + "status": "EXPIRED" + }, + "status": "APPROVED", + "defaultContractId": "string", + "memo": "string", + "tags": ["string"], + "isHidden": true, + "appliedAt": "2023-08-15T16:20:15.397Z" + } + } + ``` +
### 파트너 예약 업데이트 재설정 `PUT https://api.portone.io/platform/partners/{id}/schedule` -
-
-주어진 아이디에 대응하는 파트너의 업데이트를 재설정 합니다. -기존에 예약이 예정되어 있는 업데이트가 있다면 취소되고 새로운 업데이트가 예약됩니다. +
+
+ 주어진 아이디에 대응하는 파트너의 업데이트를 재설정 합니다. + 기존에 예약이 예정되어 있는 업데이트가 있다면 취소되고 새로운 업데이트가 예약됩니다. + + **Parameters** -**Parameters** + --- ---- + **id** required string -**id** required string + 파트너 아이디. -파트너 아이디. + --- ---- + **update** required json dicionary -**update** required json dicionary + 업데이트 할 파트너의 정보를 담은 json dictionary + [파트너 생성](#파트너-생성) API의 파라미터와 동일합니다. -업데이트 할 파트너의 정보를 담은 json dictionary -[파트너 생성](#파트너-생성) API의 파라미터와 동일합니다. + --- ---- + **appliedAt** required Datetime -**appliedAt** required Datetime + 업데이트를 적용할 시간. + 정산 시작일(settlementStartDate) 기준으로 시간이 적용됩니다. + 예를들어 2일에 파트너 기본계약 업데이트를 예약했으면 1일까지 정산시작일이 되어있는 해당 파트너의 정산 건은 구버전의 계약이 적용되고 + 2일부터는 새로운 계약이 적용됩니다. +
-업데이트를 적용할 시간. -정산 시작일(settlementStartDate) 기준으로 시간이 적용됩니다. -예를들어 2일에 파트너 기본계약 업데이트를 예약했으면 1일까지 정산시작일이 되어있는 해당 파트너의 정산 건은 구버전의 계약이 적용되고 -2일부터는 새로운 계약이 적용됩니다. +
+ **Request** -
-
- -**Request** - -```json -{ - "update": { - "name": "string", - "email": "string", - "businessRegistrationNumber": "string", - "account": { - "bank": "BNP", - "currency": "AED", - "number": "string", - "holder": "string" - }, - "defaultContractId": "string", - "memo": "string", - "tags": ["string"], - "isHidden": true - }, - "appliedAt": "2023-08-15T16:23:15.265Z" -} -``` - -**Response** - -성공 응답으로 예약된 파트너 객체가 반환됩니다. - -```json -{ - "scheduledPartner": { - "id": "string", - "graphqlId": "string", - "name": "string", - "email": "string", - "businessRegistrationNumber": "string", - "account": { - "bank": "BNP", - "currency": "AED", - "number": "string", - "holder": "string", - "status": "EXPIRED" - }, - "status": "APPROVED", - "defaultContractId": "string", - "memo": "string", - "tags": ["string"], - "isHidden": true, - "appliedAt": "2023-08-15T16:23:15.340Z" - } -} -``` + ```json + { + "update": { + "name": "string", + "email": "string", + "businessRegistrationNumber": "string", + "account": { + "bank": "BNP", + "currency": "AED", + "number": "string", + "holder": "string" + }, + "defaultContractId": "string", + "memo": "string", + "tags": ["string"], + "isHidden": true + }, + "appliedAt": "2023-08-15T16:23:15.265Z" + } + ``` -
+ **Response** + + 성공 응답으로 예약된 파트너 객체가 반환됩니다. + + ```json + { + "scheduledPartner": { + "id": "string", + "graphqlId": "string", + "name": "string", + "email": "string", + "businessRegistrationNumber": "string", + "account": { + "bank": "BNP", + "currency": "AED", + "number": "string", + "holder": "string", + "status": "EXPIRED" + }, + "status": "APPROVED", + "defaultContractId": "string", + "memo": "string", + "tags": ["string"], + "isHidden": true, + "appliedAt": "2023-08-15T16:23:15.340Z" + } + } + ``` +
--- @@ -4522,25 +4258,23 @@ id 를 제외한 모든 값을 수정할 수 있습니다. `DELETE https://api.portone.io/platform/partners/{id}/schedule` -
-
-주어진 아이디에 대응하는 파트너의 업데이트를 취소합니다. - -**Parameters** - ---- +
+
+ 주어진 아이디에 대응하는 파트너의 업데이트를 취소합니다. -**id** required string + **Parameters** -파트너 아이디. + --- -
-
+ **id** required string -**Response** -성공 응답(200) 이 반환됩니다. + 파트너 아이디. +
-
+
+ **Response** + 성공 응답(200) 이 반환됩니다. +
--- @@ -4593,33 +4327,30 @@ id 를 제외한 모든 값을 수정할 수 있습니다. ## 할인 정책 -
-
- -`할인 정책 ` 객체는 고객사의 주문건에 대해서 쿠폰 및 포인트와 같은 할인금액이 적용될시 이에대해서 파트너 정산에 할인금과 할인에 따른 파트너와의 분담율을 적용하고자 사용할 수 있는 객체입니다. - -할인 정책에 대한 아이디와 메모 그리고 파트너 분담율로 정보 구성이 되어있습니다. +
+
+ `할인 정책 ` 객체는 고객사의 주문건에 대해서 쿠폰 및 포인트와 같은 할인금액이 적용될시 이에대해서 파트너 정산에 할인금과 할인에 따른 파트너와의 분담율을 적용하고자 사용할 수 있는 객체입니다. -현재 구조로는 할인금액 전달할시 꼭 해당 할인에 대한 할인 정책 아이디를 동반해서 전달해주셔야 합니다. + 할인 정책에 대한 아이디와 메모 그리고 파트너 분담율로 정보 구성이 되어있습니다. -
-
- -**Endpoints** - -```text -POST /platform/discount-share-policies -GET /platform/discount-share-policies/{id} -GET /platform/discount-share-policies -PATCH /platform/discount-share/{id} -POST /platform/discount-share/{id}/schedule -GET /platform/discount-share/{id}/schedule -PUT /platform/discount-share/{id}/schedule -DELETE /platform/discount-share/{id}/schedule -GET /platform/discount-share-policy-filter-options (To Be Documented) -``` + 현재 구조로는 할인금액 전달할시 꼭 해당 할인에 대한 할인 정책 아이디를 동반해서 전달해주셔야 합니다. +
-
+
+ **Endpoints** + + ```text + POST /platform/discount-share-policies + GET /platform/discount-share-policies/{id} + GET /platform/discount-share-policies + PATCH /platform/discount-share/{id} + POST /platform/discount-share/{id}/schedule + GET /platform/discount-share/{id}/schedule + PUT /platform/discount-share/{id}/schedule + DELETE /platform/discount-share/{id}/schedule + GET /platform/discount-share-policy-filter-options (To Be Documented) + ``` +
--- @@ -4628,58 +4359,55 @@ GET /platform/discount-share-policy-filter-options (To Be Documented) `POST https://api.portone.io/platform/discount-share-policies` -
-
+
+
+ **Parameters** + + **id** optional -**Parameters** + 할인 정책 고유아이디. 고객사 서버에 저장되고 통용되는 아이디로 지정해주세요. 없다면 포트원에서 임의로 발급해드리며 이를 저장해주세요. -**id** optional + --- -할인 정책 고유아이디. 고객사 서버에 저장되고 통용되는 아이디로 지정해주세요. 없다면 포트원에서 임의로 발급해드리며 이를 저장해주세요. + **partnerShareRate** required ---- + 할인 분담율. 10^-5처리 값입니다. 예) 10% = 10000 -**partnerShareRate** required + --- -할인 분담율. 10^-5처리 값입니다. 예) 10% = 10000 + **memo** optional ---- + 할인 정책 내부 메모. 예) 파트너 브랜드 쿠폰 +
-**memo** optional +
+ **Request** + + ```json + { + "id": "string", + "partnerShareRate": 0, + "memo": "string" + } + ``` -할인 정책 내부 메모. 예) 파트너 브랜드 쿠폰 + **Response** -
-
- -**Request** - -```json -{ - "id": "string", - "partnerShareRate": 0, - "memo": "string" -} -``` - -**Response** - -생성된 할인 정책 객체가 반환됩니다. - -```json -{ - "discountSharePolicy": { - "id": "string", - "graphqlId": "string", - "partnerShareRate": 0, - "memo": "string", - "isHidden": true, - "appliedAt": "2023-08-15T16:48:24.842Z" - } -} -``` + 생성된 할인 정책 객체가 반환됩니다. -
+ ```json + { + "discountSharePolicy": { + "id": "string", + "graphqlId": "string", + "partnerShareRate": 0, + "memo": "string", + "isHidden": true, + "appliedAt": "2023-08-15T16:48:24.842Z" + } + } + ``` +
--- @@ -4688,34 +4416,32 @@ GET /platform/discount-share-policy-filter-options (To Be Documented) `GET https://api.portone.io/platform/discount-share-policies/{id}` -
-
- -**Parameters** - -**id** required (url path) +
+
+ **Parameters** -조회할 할인 정책 아이디 + **id** required (url path) -
-
+ 조회할 할인 정책 아이디 +
-**Response** +
+ **Response** -조회 대상 할인 정책이 반환됩니다. + 조회 대상 할인 정책이 반환됩니다. -```json -{ - "id": "string", - "graphqlId": "string", - "partnerShareRate": 0, - "memo": "string", - "isHidden": true, - "appliedAt": "2023-08-15T16:55:36.587Z" -} -``` + ```json + { + "id": "string", + "graphqlId": "string", + "partnerShareRate": 0, + "memo": "string", + "isHidden": true, + "appliedAt": "2023-08-15T16:55:36.587Z" + } + ``` -**Error Code** + **Error Code** |Code|Description | |:---|:----------------------------------------------------------------------------------------------------------------------------| @@ -4733,146 +4459,131 @@ GET /platform/discount-share-policy-filter-options (To Be Documented) `GET https://api.portone.io/platform/discount-share-policies` -
-
- -**Parameters** - -**page** optional - -페이지 기반의 다건 조회 갯수 조건 - -page attributes - - - - - - - - +
+
+ **Parameters** -
-
- - page.**number** optional 기본값은 1 - - 검색 결과에대한 페이징. size에 따라 offset 값이라고 생각하면 됩니다. - -
- - page.**size** optional 기본값은 10 - - 각 page당 조회될 할인 정책 객체 갯수. - -
+ **page** optional ---- + 페이지 기반의 다건 조회 갯수 조건 -**filter** required + page attributes -검색 조건 + + + + -
+ page.**number** optional 기본값은 1 -filter attributes + 검색 결과에대한 페이징. size에 따라 offset 값이라고 생각하면 됩니다. +
- - + + +
+
+ page.**size** optional 기본값은 10 - filter.**includeHidden** boolean optional 기본값은 false + 각 page당 조회될 할인 정책 객체 갯수. +
- true로 설정시 삭제된 할인 정책 객체도 조회됩니다. + --- - + **filter** required - - - + 검색 조건 - filter.**partnerShareRates** list of int64 optional + filter attributes - 파트너 분담율로 구성된 리스트. 해당 리스트에 포함된 분담율과 매칭되는 모든 할인 정책 객체들을 반환한다. + + + + true로 설정시 삭제된 할인 정책 객체도 조회됩니다. + + - - - + + - 통합검색을 위한 조건. 할인 정책 다건조회에 대해서는 할인유형 아이디 (id)와 메모 (memo)를 기반으로 검색 가능합니다. 검색 로직은 %like% 검색입니다. + + + \- keyword.all string \ + 메모 및 아이디 값에 대한 검색. 해당 검색으로 진행시 메모 및 아이디 검색을 추가할 수 없습니다. + + +
+ filter.**includeHidden** boolean optional 기본값은 false -
+
+ filter.**partnerShareRates** list of int64 optional - filter.**keyword** dictionary optional + 파트너 분담율로 구성된 리스트. 해당 리스트에 포함된 분담율과 매칭되는 모든 할인 정책 객체들을 반환한다. +
+ filter.**keyword** dictionary optional - \- keyword.memo string \ - 메모 값에 대한 검색. 해당 검색으로 진행시 id 검색을 추가할 수 없습니다. + 통합검색을 위한 조건. 할인 정책 다건조회에 대해서는 할인유형 아이디 (id)와 메모 (memo)를 기반으로 검색 가능합니다. 검색 로직은 %like% 검색입니다. - \- keyword.id string \ - 아이디 값에 대한 검색. 해당 검색으로 진행시 메모 검색을 추가할 수 없습니다. + \- keyword.memo string \ + 메모 값에 대한 검색. 해당 검색으로 진행시 id 검색을 추가할 수 없습니다. - \- keyword.all string \ - 메모 및 아이디 값에 대한 검색. 해당 검색으로 진행시 메모 및 아이디 검색을 추가할 수 없습니다. + \- keyword.id string \ + 아이디 값에 대한 검색. 해당 검색으로 진행시 메모 검색을 추가할 수 없습니다. -
- - + --- +
---- +
+ **Request** -
-
- -**Request** - -```json -{ - "page": { - "number": 0, - "size": 0 - }, - "filter": { - "includeHidden": true, - "partnerShareRates": [0], - "keyword": { - "id": "string", - "memo": "string", - "all": "string" + ```json + { + "page": { + "number": 0, + "size": 0 + }, + "filter": { + "includeHidden": true, + "partnerShareRates": [0], + "keyword": { + "id": "string", + "memo": "string", + "all": "string" + } + } } - } -} -``` + ``` -**Response** + **Response** -```json -{ - "items": [ + ```json { - "id": "string", - "graphqlId": "string", - "partnerShareRate": 0, - "memo": "string", - "isHidden": true, - "appliedAt": "2023-08-15T17:00:00.572Z" + "items": [ + { + "id": "string", + "graphqlId": "string", + "partnerShareRate": 0, + "memo": "string", + "isHidden": true, + "appliedAt": "2023-08-15T17:00:00.572Z" + } + ], + "page": { + "number": 0, + "size": 0, + "totalCount": 0 + } } - ], - "page": { - "number": 0, - "size": 0, - "totalCount": 0 - } -} -``` + ``` -**Error Code** - -|Code|Description | -|:---|:----------------------------------------------------------------------------------------------------------------------------| -|400 |InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우. 허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.| -|401 |UnauthorizedError: 인증 정보가 올바르지 않은 경우 | -|403 |PlatformNotEnabledError: 플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우 | + **Error Code** -
+ |Code|Description | + |:---|:----------------------------------------------------------------------------------------------------------------------------| + |400 |InvalidRequestError: 요청된 입력 정보가 유효하지 않은 경우. 허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.| + |401 |UnauthorizedError: 인증 정보가 올바르지 않은 경우 | + |403 |PlatformNotEnabledError: 플랫폼 기능이 활성화되지 않아 요청을 처리할 수 없는 경우 | +
--- @@ -4883,60 +4594,58 @@ filter attributes `PATCH https://api.portone.io/platform/discount-share-policies/{id}` -
-
+
+
+ Parameters + + **id** required (url path) -Parameters + 할인 정책 아이디 -**id** required (url path) + **partnerShareRate** optional 기본값은 0 -할인 정책 아이디 + 할인 분담율. 10^5처리 값입니다. 예) 10% = 1000 -**partnerShareRate** optional 기본값은 0 + --- -할인 분담율. 10^5처리 값입니다. 예) 10% = 1000 + **memo** optional ---- + 할인 정책 내부 메모. 예) 파트너 브랜드 쿠폰 -**memo** optional + --- -할인 정책 내부 메모. 예) 파트너 브랜드 쿠폰 + **isHidden** boolean optional 기본값은 fals본 ---- + 숨김 처리 여부. true로 설정시 해당 할인 정책은 숨김됩니다 +
-**isHidden** boolean optional 기본값은 fals본 +
+ **Request** + + ```json + { + "partnerShareRate": 0, + "memo": "string", + "isHidden": true + } + ``` -숨김 처리 여부. true로 설정시 해당 할인 정책은 숨김됩니다 + **Response** -
-
- -**Request** - -```json -{ - "partnerShareRate": 0, - "memo": "string", - "isHidden": true -} -``` - -**Response** - -```json -{ - "discountSharePolicy": { - "id": "string", - "graphqlId": "string", - "partnerShareRate": 0, - "memo": "string", - "isHidden": true, - "appliedAt": "2023-08-15T17:03:19.203Z" - } -} -``` - -**Error Code** + ```json + { + "discountSharePolicy": { + "id": "string", + "graphqlId": "string", + "partnerShareRate": 0, + "memo": "string", + "isHidden": true, + "appliedAt": "2023-08-15T17:03:19.203Z" + } + } + ``` + + **Error Code** |Code|Description | |:---|:----------------------------------------------------------------------------------------------------------------------------| @@ -4954,21 +4663,18 @@ Parameters `DELETE https://api.portone.io/platform/discount-share-policies/{id}` -
-
- -**Parameters** - -**id** required (url path) - -
-
+
+
+ **Parameters** -**Response** + **id** required (url path) +
-200 응답이 떨어집니다. +
+ **Response** -
+ 200 응답이 떨어집니다. +
--- @@ -4977,61 +4683,61 @@ Parameters `POST https://api.portone.io/platform/discount-share-policies/{id}/schedule` -
-
-“update” 필드에 업데이트를 예약할 정보를 입력합니다. +
+
+ “update” 필드에 업데이트를 예약할 정보를 입력합니다. + + “appliedAt” 필드에 적용되길 원하는 시점을 입력합니다 -“appliedAt” 필드에 적용되길 원하는 시점을 입력합니다 + **Parameters** -**Parameters** + **id** string required (url path) -**id** string required (url path) + 할인 정책 아이디 -할인 정책 아이디 + **update** dictionary required -**update** dictionary required + 예약 업데이트 하고 싶은 할인 정책 정보 -예약 업데이트 하고 싶은 할인 정책 정보 + 기존 [할인 정책 수정 API](#할인-정책-수정) 와 동일한 파라미터를 사용합니다. -기존 [할인 정책 수정 API](#할인-정책-수정) 와 동일한 파라미터를 사용합니다. + **appliedAt** Datetime required -**appliedAt** Datetime required + 업데이트가 적용되길 원하는 시점 입니다 -업데이트가 적용되길 원하는 시점 입니다 + **settlementStartDate** 기접으로 적용됩니다. 예를 들어 appliedAt 이 t-0 이라면 t-0 이후의 settlementStartDate 인 해당 계약의 정산건들은 업데이트가 적용됩니다. +
-**settlementStartDate** 기접으로 적용됩니다. 예를 들어 appliedAt 이 t-0 이라면 t-0 이후의 settlementStartDate 인 해당 계약의 정산건들은 업데이트가 적용됩니다. +
+ **Request** -
-
-**Request** - -```json -{ - "update": { - "partnerShareRate": 0, - "memo": "string", - "isHidden": true - }, - "appliedAt": "2023-08-15T17:09:36.812Z" -} -``` - -**Response** - -```json -{ - "scheduledDiscountSharePolicy": { - "id": "string", - "graphqlId": "string", - "partnerShareRate": 0, - "memo": "string", - "isHidden": true, - "appliedAt": "2023-08-15T17:09:36.816Z" - } -} -``` - -**Error Code** + ```json + { + "update": { + "partnerShareRate": 0, + "memo": "string", + "isHidden": true + }, + "appliedAt": "2023-08-15T17:09:36.812Z" + } + ``` + + **Response** + + ```json + { + "scheduledDiscountSharePolicy": { + "id": "string", + "graphqlId": "string", + "partnerShareRate": 0, + "memo": "string", + "isHidden": true, + "appliedAt": "2023-08-15T17:09:36.816Z" + } + } + ``` + + **Error Code** |Code|Description | |:---|:----------------------------------------------------------------------------------------------------------------------------| @@ -5048,64 +4754,63 @@ Parameters `PUT https://api.portone.io/platform/discount-share-policies/{id}/schedule` -
-
+
+
+ “update” 필드에 업데이트를 예약할 정보를 입력합니다. + + “appliedAt” 필드에 적용되길 원하는 시점을 입력합니다 + + 해당 정책 에 대해서 이미 예약 업데이트가 존재하는 경우에는 해당 api를 사용해야하며 , 해당 api를 통해 업데이트 할경우 기존 예약 업데이트는 삭제됩니다. -“update” 필드에 업데이트를 예약할 정보를 입력합니다. + **Parameters** -“appliedAt” 필드에 적용되길 원하는 시점을 입력합니다 + **id** string required (url path) -해당 정책 에 대해서 이미 예약 업데이트가 존재하는 경우에는 해당 api를 사용해야하며 , 해당 api를 통해 업데이트 할경우 기존 예약 업데이트는 삭제됩니다. + 할인 정책 아이디 -**Parameters** + **update** dictionary required -**id** string required (url path) + 예약 업데이트 하고 싶은 할인 정책 정보 -할인 정책 아이디 + 기존 [할인 정책 수정 API](#할인-정책-수정) 와 동일한 파라미터를 사용합니다. -**update** dictionary required + **appliedAt** Datetime required -예약 업데이트 하고 싶은 할인 정책 정보 + 업데이트가 적용되길 원하는 시점 입니다 -기존 [할인 정책 수정 API](#할인-정책-수정) 와 동일한 파라미터를 사용합니다. + **settlementStartDate** 기접으로 적용됩니다. 예를 들어 appliedAt 이 t-0 이라면 t-0 이후의 settlementStartDate 인 해당 계약의 정산건들은 업데이트가 적용됩니다. +
-**appliedAt** Datetime required +
+ **Request** -업데이트가 적용되길 원하는 시점 입니다 + ```json + { + "update": { + "partnerShareRate": 0, + "memo": "string", + "isHidden": true + }, + "appliedAt": "2023-08-15T17:09:36.812Z" + } + ``` -**settlementStartDate** 기접으로 적용됩니다. 예를 들어 appliedAt 이 t-0 이라면 t-0 이후의 settlementStartDate 인 해당 계약의 정산건들은 업데이트가 적용됩니다. + **Response** -
-
-**Request** - -```json -{ - "update": { - "partnerShareRate": 0, - "memo": "string", - "isHidden": true - }, - "appliedAt": "2023-08-15T17:09:36.812Z" -} -``` - -**Response** - -```json -{ - "scheduledDiscountSharePolicy": { - "id": "string", - "graphqlId": "string", - "partnerShareRate": 0, - "memo": "string", - "isHidden": true, - "appliedAt": "2023-08-15T17:09:36.816Z" - } -} -``` - -**Error Code** + ```json + { + "scheduledDiscountSharePolicy": { + "id": "string", + "graphqlId": "string", + "partnerShareRate": 0, + "memo": "string", + "isHidden": true, + "appliedAt": "2023-08-15T17:09:36.816Z" + } + } + ``` + + **Error Code** |Code|Description | |:---|:----------------------------------------------------------------------------------------------------------------------------| @@ -5121,32 +4826,30 @@ Parameters `PUT https://api.portone.io/platform/discount-share-policies/{id}/schedule` -
-
- -**Parameters** - -**id** string required (url path) +
+
+ **Parameters** -할인 정책 아이디 + **id** string required (url path) -
-
+ 할인 정책 아이디 +
-**Response** +
+ **Response** -```json -{ - "id": "string", - "graphqlId": "string", - "partnerShareRate": 0, - "memo": "string", - "isHidden": true, - "appliedAt": "2023-08-15T17:21:52.542Z" -} -``` + ```json + { + "id": "string", + "graphqlId": "string", + "partnerShareRate": 0, + "memo": "string", + "isHidden": true, + "appliedAt": "2023-08-15T17:21:52.542Z" + } + ``` -**Error Code** + **Error Code** |Code|Description | |:---|:----------------------------------------------------------------------------------------------------------------------------| @@ -5162,23 +4865,21 @@ Parameters `PUT https://api.portone.io/platform/discount-share-policies/{id}/schedule` -
-
- -**Parameters** - -**id** string required (url path) +
+
+ **Parameters** -예약된 업데이트를 제거하고 싶은 할인 정책 아이디의 + **id** string required (url path) -
-
+ 예약된 업데이트를 제거하고 싶은 할인 정책 아이디의 +
-**Response** +
+ **Response** -200 OK + 200 OK -**Error Code** + **Error Code** |Code|Description | |:---|:----------------------------------------------------------------------------------------------------------------------------| @@ -5192,119 +4893,108 @@ Parameters ## 추가 수수료 -
-
- -`추가 수수료` 객체는 고객사의 주문건에 대해서 단순 중개수수료에 더불어 추가로 부여되는 서비스에대한 수수료 입니다. 대표적인 사용 예시로 풀필먼트 수수료, 로켓배송 수수료, 마케팅채널 수수료등이 있습니다. - -
-
- -**Endpoints** - -```text -POST /platform/additional-fee-policies -GET /platform/additional-fee-policies/{id} -GET /platform/additional-fee-policies -PATCH /platform/additional-fee-policies/{id} -POST /platform/additional-fee-policies/{id}/schedule -PATCH /platform/additional-fee-policies/{id}/schedule -GET /platform/additional-fee-policies/{id}/schedule -DELETE /platform/additional-fee-policies/{id}/schedule -GET /platform/additional-fee-policy-filter-options (To Be Documented) -``` +
+
+ `추가 수수료` 객체는 고객사의 주문건에 대해서 단순 중개수수료에 더불어 추가로 부여되는 서비스에대한 수수료 입니다. 대표적인 사용 예시로 풀필먼트 수수료, 로켓배송 수수료, 마케팅채널 수수료등이 있습니다. +
-
+
+ **Endpoints** + + ```text + POST /platform/additional-fee-policies + GET /platform/additional-fee-policies/{id} + GET /platform/additional-fee-policies + PATCH /platform/additional-fee-policies/{id} + POST /platform/additional-fee-policies/{id}/schedule + PATCH /platform/additional-fee-policies/{id}/schedule + GET /platform/additional-fee-policies/{id}/schedule + DELETE /platform/additional-fee-policies/{id}/schedule + GET /platform/additional-fee-policy-filter-options (To Be Documented) + ``` +
--- ### 추가 수수료 객체 -
-
- -**Parameter** - -**id** string - -추가수수료의 고유 아이디 - ---- - -**fee** dictionary - -추가 수수료 정보를 보여주는 fee attribute +
+
+ **Parameter** - - - + **fee** dictionary - - - + +
+ **id** string - fees.**amount int64** + 추가수수료의 고유 아이디 - 정액일 경우 사용하는 parameter. 현재로서 정액 플랫폼 중개 수수료는 원화만 지원한다. + --- -
+ 추가 수수료 정보를 보여주는 fee attribute - fees.**rate int64** + + + + - + + -
+ fees.**amount int64** - 정률일경우 10^-5처리 된다. 10% = 10000 + 정액일 경우 사용하는 parameter. 현재로서 정액 플랫폼 중개 수수료는 원화만 지원한다. +
+ fees.**rate int64** -
+ 정률일경우 10^-5처리 된다. 10% = 10000 +
---- + --- -**memo** string + **memo** string -추가 수수료 내부 구분을 위한 내부 메모 + 추가 수수료 내부 구분을 위한 내부 메모 ---- + --- -**vatPayer** enum + **vatPayer** enum -해당 계약의 중개수수료에 대해서 부가세 포함 여부. -값: PARTNER, MERCHANT + 해당 계약의 중개수수료에 대해서 부가세 포함 여부. + 값: PARTNER, MERCHANT -PARTNER: 부가세 파트너 부담 + PARTNER: 부가세 파트너 부담 -MERCHANT: 부가세 파트너 미부담 + MERCHANT: 부가세 파트너 미부담 ---- + --- -**isHidden** boolean + **isHidden** boolean -숨김처리 여부. 파트너 정산의 객체들에 대해서 삭제는 soft delete임을 참고해 주세요! 이는 삭리시 해당 삭제된 객체와 동일한 아이디를 발급할경우 새롭게 생성된 객체가 overwrite 합니다. + 숨김처리 여부. 파트너 정산의 객체들에 대해서 삭제는 soft delete임을 참고해 주세요! 이는 삭리시 해당 삭제된 객체와 동일한 아이디를 발급할경우 새롭게 생성된 객체가 overwrite 합니다. ---- + --- +
-
-
- -**Response** - -```json -{ - "id": "addtional_fee_1", - "graphqlId": "MzphZGR0aW9uYWxfZmVlXzE=", - "fee": { - "type": "FIXED_RATE", - "rate": 5000 - }, - "memo": "테스트 추가수수료", - "vatPayer": "PARTNER", - "isHidden": false, - "appliedAt": "2023-08-09T07:41:12.393974Z" -} -``` +
+ **Response** -
+ ```json + { + "id": "addtional_fee_1", + "graphqlId": "MzphZGR0aW9uYWxfZmVlXzE=", + "fee": { + "type": "FIXED_RATE", + "rate": 5000 + }, + "memo": "테스트 추가수수료", + "vatPayer": "PARTNER", + "isHidden": false, + "appliedAt": "2023-08-09T07:41:12.393974Z" + } + ``` +
--- @@ -5313,261 +5003,235 @@ MERCHANT: 부가세 파트너 미부담 `POST https://api.portone.io/platform/additional-fee-policies` -
-
- -**Parameters** - -**id** required - -추가수수료의 고유 아이디 +
+
+ **Parameters** ---- + **id** required -**fee** required + 추가수수료의 고유 아이디 -추가 수수료 정보를 보여주는 fee attribute + --- - - - + **memo** optional - -
+ **fee** required - fees.**amount int64** + 추가 수수료 정보를 보여주는 fee attribute - 정액일 경우 사용하는 parameter. 현재로서 정액 플랫폼 중개 수수료는 원화만 지원한다. + + + + 정액일 경우 사용하는 parameter. 현재로서 정액 플랫폼 중개 수수료는 원화만 지원한다. + + - - - + + +
+ fees.**amount int64** -
+
+ fees.**rate int64** - fees.**rate int64** + 정률일경우 10^-5처리 된다. 10% = 10000 +
- 정률일경우 10^-5처리 된다. 10% = 10000 + --- -
+ 추가 수수료 내부 구분을 위한 내부 메모 ---- + --- -**memo** optional + **vatPayer** optional 기본값은 PARTNER -추가 수수료 내부 구분을 위한 내부 메모 + 부가세 부담여부 ---- + PARTNER: 부가세 파트너 부담 -**vatPayer** optional 기본값은 PARTNER + MERCHANT: 부가세 파트너 미부담 -부가세 부담여부 + --- +
-PARTNER: 부가세 파트너 부담 +
+ **Request** -MERCHANT: 부가세 파트너 미부담 + ```json + { + "id": "string", + "fee": { + "fixedRate": 0, + "fixedAmount": 0 + }, + "memo": "string", + "vatPayer": "MERCHANT" + } + ``` ---- + **Response** -
-
- -**Request** - -```json -{ - "id": "string", - "fee": { - "fixedRate": 0, - "fixedAmount": 0 - }, - "memo": "string", - "vatPayer": "MERCHANT" -} -``` - -**Response** - -추가 수수료 객체가 반환됩니다. - -```json -{ - "id": "addtional_fee_1", - "graphqlId": "MzphZGR0aW9uYWxfZmVlXzE=", - "fee": { - "type": "FIXED_RATE", - "rate": 5000 - }, - "memo": "테스트 추가수수료", - "vatPayer": "PARTNER", - "isHidden": false, - "appliedAt": "2023-08-09T07:41:12.393974Z" -} -``` + 추가 수수료 객체가 반환됩니다. -
+ ```json + { + "id": "addtional_fee_1", + "graphqlId": "MzphZGR0aW9uYWxfZmVlXzE=", + "fee": { + "type": "FIXED_RATE", + "rate": 5000 + }, + "memo": "테스트 추가수수료", + "vatPayer": "PARTNER", + "isHidden": false, + "appliedAt": "2023-08-09T07:41:12.393974Z" + } + ``` +
--- ### 추가 수수료 조회 -
-
+
+
+ **Parameters** -**Parameters** + **id** required (url path) +
-**id** required (url path) +
+ **Response** -
-
- -**Response** - -추가 수수료 객체가 반환됩니다. - -```json -{ - "id": "addtional_fee_1", - "graphqlId": "MzphZGR0aW9uYWxfZmVlXzE=", - "fee": { - "type": "FIXED_RATE", - "rate": 5000 - }, - "memo": "테스트 추가수수료", - "vatPayer": "PARTNER", - "isHidden": false, - "appliedAt": "2023-08-09T07:41:12.393974Z" -} -``` + 추가 수수료 객체가 반환됩니다. -
+ ```json + { + "id": "addtional_fee_1", + "graphqlId": "MzphZGR0aW9uYWxfZmVlXzE=", + "fee": { + "type": "FIXED_RATE", + "rate": 5000 + }, + "memo": "테스트 추가수수료", + "vatPayer": "PARTNER", + "isHidden": false, + "appliedAt": "2023-08-09T07:41:12.393974Z" + } + ``` +
--- ### 추가 수수료 다건 조회 -
-
- -**Parameter** - -Parameters - -**page** optional - -페이지 기반의 다건 조회 갯수 조건 - -page attributes - - - - - - - - + Parameters - -
- - page.**number** optional 기본값은 1 - - 검색 결과에대한 페이징. size에 따라 offset 값이라고 생각하면 됩니다. - -
- - page.**size** optional 기본값은 10 - - 각 page당 조회될 할인 정책 객체 갯수. +
+
+ **Parameter** -
+ **page** optional ---- + 페이지 기반의 다건 조회 갯수 조건 -**filter** required + page attributes -검색 조건 + + + + -
+ page.**number** optional 기본값은 1 -filter attributes + 검색 결과에대한 페이징. size에 따라 offset 값이라고 생각하면 됩니다. +
- - + + +
+
+ page.**size** optional 기본값은 10 - filter.**includeHidden** boolean optional 기본값은 false + 각 page당 조회될 할인 정책 객체 갯수. +
- + --- - - - + **filter** required - filter.**ids** optional + 검색 조건 - 추가 수수료 객체 고유 아이디로 구성된 리스트 + filter attributes - + + + + - - - + + - 부가세 적용 여부 검색 MERCHANT , PARTNER + + + 부가세 적용 여부 검색 MERCHANT , PARTNER + + +
+ filter.**includeHidden** boolean optional 기본값은 false +
+
+ filter.**ids** optional - filter.**vatPayers** enum + 추가 수수료 객체 고유 아이디로 구성된 리스트 +
+ filter.**vatPayers** enum -
- - + --- +
---- +
+ **Request** -
-
- -**Request** - -```json -{ - "page": { - "number": 0, - "size": 0 - }, - "filter": { - "includeHidden": true, - "ids": ["string"], - "vatPayers": ["MERCHANT"] - } -} -``` - -```json -{ - "items": [ + ```json { - "id": "string", - "graphqlId": "string", - "fee": { - "amount": 0 + "page": { + "number": 0, + "size": 0 }, - "memo": "string", - "vatPayer": "MERCHANT", - "isHidden": true, - "appliedAt": "2023-08-15T17:47:27.702Z" + "filter": { + "includeHidden": true, + "ids": ["string"], + "vatPayers": ["MERCHANT"] + } } - ], - "page": { - "number": 0, - "size": 0, - "totalCount": 0 - } -} -``` + ``` -
+ ```json + { + "items": [ + { + "id": "string", + "graphqlId": "string", + "fee": { + "amount": 0 + }, + "memo": "string", + "vatPayer": "MERCHANT", + "isHidden": true, + "appliedAt": "2023-08-15T17:47:27.702Z" + } + ], + "page": { + "number": 0, + "size": 0, + "totalCount": 0 + } + } + ``` +
--- @@ -5576,319 +5240,286 @@ filter attributes `PATCH https://api.portone.io/platform/additional-fee-policies` -
-
+
+
+ **Parameters** -**Parameters** + **id** required (url path) -**id** required (url path) + 추가수수료 고유 아이디 -추가수수료 고유 아이디 + --- ---- + 나머지 파라미터는 [추가수수료 생성](#추가-수수료-생성) 과 동일합니다. +
-나머지 파라미터는 [추가수수료 생성](#추가-수수료-생성) 과 동일합니다. +
+ **Request** -
-
- -**Request** - -```json -{ - "fee": { - "fixedRate": 0, - "fixedAmount": 0 - }, - "memo": "string", - "vatPayer": "MERCHANT", - "isHidden": true -} -``` - -**Resposne** - -```json -{ - "id": "addtional_fee_1", - "graphqlId": "MzphZGR0aW9uYWxfZmVlXzE=", - "fee": { - "type": "FIXED_RATE", - "rate": 5000 - }, - "memo": "테스트 추가수수료", - "vatPayer": "PARTNER", - "isHidden": false, - "appliedAt": "2023-08-09T07:41:12.393974Z" -} -``` + ```json + { + "fee": { + "fixedRate": 0, + "fixedAmount": 0 + }, + "memo": "string", + "vatPayer": "MERCHANT", + "isHidden": true + } + ``` -
+ **Resposne** + + ```json + { + "id": "addtional_fee_1", + "graphqlId": "MzphZGR0aW9uYWxfZmVlXzE=", + "fee": { + "type": "FIXED_RATE", + "rate": 5000 + }, + "memo": "테스트 추가수수료", + "vatPayer": "PARTNER", + "isHidden": false, + "appliedAt": "2023-08-09T07:41:12.393974Z" + } + ``` +
--- ## 파트너 정산 설정 -
-
- -`파트너 정산 설정` 객체는 고객사가 파트너에게 정산해줄때 적용될 기본적인 설정을 의미합니다. 정산 계산시 적용될 소수점 처리방식, 각 항목 (중개 수수료, 추가 수수료 ,할인 분담, 결제수수료 (TBA)) 에 대한 구체적 계산 수식을 설정 할 수 있으며 추가로 결제(PG)수수료 파트너 부담여부를 설정 할 수 있습니다. - -파트너 정산을 사용하는 고객사당 단일객체가 발급되며 삭제가 불가능 합니다. - -
-
+
+
+ `파트너 정산 설정` 객체는 고객사가 파트너에게 정산해줄때 적용될 기본적인 설정을 의미합니다. 정산 계산시 적용될 소수점 처리방식, 각 항목 (중개 수수료, 추가 수수료 ,할인 분담, 결제수수료 (TBA)) 에 대한 구체적 계산 수식을 설정 할 수 있으며 추가로 결제(PG)수수료 파트너 부담여부를 설정 할 수 있습니다. -**Endpoints** + 파트너 정산을 사용하는 고객사당 단일객체가 발급되며 삭제가 불가능 합니다. +
-```text -PATCH /platform -GET /platform -``` +
+ **Endpoints** -
+ ```text + PATCH /platform + GET /platform + ``` +
--- ### 파트너 정산 설정 객체 -
-
- -**Parameter** - -**merchantId** string - -포트원이 부여한 고객사 고유 아이디 - ---- - -**roundType** enum - -정산식 계산시 적용될 소수점 처리 방식. 내림, 올림, 반올림이 있다. 각각의 수수료와 부가세 및 할인 분담금액을 계산할때 적용된다. - -- OFF: 반올림 -- DOWN: 내림 -- UP: 올림 - ---- - -**settlementFormula** dicitionary - -전체 정산과 각 수수료 및 할인분담금을 계산하는데 적용되는 수식에 대한 값입니다. 다만 현재는 해당 값은 `관리자콘솔 > 파트너 정산 > 계약관리 > 수식` 에서 확인 및 수정하실 수 있으십니다. - - - - + **merchantId** string - - - + **roundType** enum - - - + --- - - - +
-
- - **settlementFormula.platformFee**\ - 중개수수료 수식 +
+
+ **Parameter** -
-
-
+ 포트원이 부여한 고객사 고유 아이디 - **settlementFormula.channelFee (TBA)**\ - 결제수수료 수식 + --- -
-
-
+ 정산식 계산시 적용될 소수점 처리 방식. 내림, 올림, 반올림이 있다. 각각의 수수료와 부가세 및 할인 분담금액을 계산할때 적용된다. - **settlementFormula.discountShare**\ - 할인분담금 수식 + - OFF: 반올림 + - DOWN: 내림 + - UP: 올림 -
-
-
+ **settlementFormula** dicitionary - **settlementFormula.additionalFee**\ - 추가 수수료 수식 + 전체 정산과 각 수수료 및 할인분담금을 계산하는데 적용되는 수식에 대한 값입니다. 다만 현재는 해당 값은 `관리자콘솔 > 파트너 정산 > 계약관리 > 수식` 에서 확인 및 수정하실 수 있으십니다. -
-
+ + + - -
+
+ **settlementFormula.platformFee**\ + 중개수수료 수식 +
+
+ + +
+ **settlementFormula.channelFee (TBA)**\ + 결제수수료 수식 +
+ + ---- + + +
+ **settlementFormula.discountShare**\ + 할인분담금 수식 +
+ + -
-
+ + +
+ **settlementFormula.additionalFee**\ + 추가 수수료 수식 +
+ + + -**Response** + --- +
-파트너정산을 사용하실수 있는 고객사는 기본으로 해당 값이 설정이 됩니다. +
+ **Response** -```json -{ - "merchantId": "merchant-58c965f5-85f7-4c49-b770-cc11f3294bda", - "graphqlId": "MTptZXJjaGFudC01OGM5NjVmNS04NWY3LTRjNDktYjc3MC1jYzExZjMyOTRiZGE=", - "roundType": "DOWN", - "settlementFormula": { - "platformFee": "(주문금액 * 플랫폼수수료율) + 플랫폼수수료액", - "discountShare": "할인금액 * 할인분담률", - "additionalFee": "(주문금액 * 추가수수료율) + 추가수수료액" - } -} -``` + 파트너정산을 사용하실수 있는 고객사는 기본으로 해당 값이 설정이 됩니다. -
+ ```json + { + "merchantId": "merchant-58c965f5-85f7-4c49-b770-cc11f3294bda", + "graphqlId": "MTptZXJjaGFudC01OGM5NjVmNS04NWY3LTRjNDktYjc3MC1jYzExZjMyOTRiZGE=", + "roundType": "DOWN", + "settlementFormula": { + "platformFee": "(주문금액 * 플랫폼수수료율) + 플랫폼수수료액", + "discountShare": "할인금액 * 할인분담률", + "additionalFee": "(주문금액 * 추가수수료율) + 추가수수료액" + } + } + ``` +
### 파트너 정산 설정 수정 `PATCH https://api.portone.io/platform` -
-
- -**Parameter** - -**roundType** enum - -정산식 계산시 적용될 소수점 처리 방식. 내림, 올림, 반올림이 있다. 각각의 수수료와 부가세 및 할인 분담금액을 계산할때 적용된다. - -- OFF: 반올림 -- DOWN: 내림 -- UP: 올림 - ---- - -**settlementFormula** dicitionary - -전체 정산과 각 수수료 및 할인분담금을 계산하는데 적용되는 수식에 대한 값입니다. +
+
+ **Parameter** - - - + - OFF: 반올림 + - DOWN: 내림 + - UP: 올림 - - - + 전체 정산과 각 수수료 및 할인분담금을 계산하는데 적용되는 수식에 대한 값입니다. - - - +
+ **Request** -
-
-
+ **roundType** enum - **settlementFormula.platformFee**\ - 중개수수료 수식 + 정산식 계산시 적용될 소수점 처리 방식. 내림, 올림, 반올림이 있다. 각각의 수수료와 부가세 및 할인 분담금액을 계산할때 적용된다. -
-
-
+ --- - **settlementFormula.channelFee (TBA)**\ - 결제수수료 수식 + **settlementFormula** dicitionary -
-
-
+ + + + - **settlementFormula.discountShare**\ - 할인분담금 수식 + + + - - + + + - - - + + +
+
+ **settlementFormula.platformFee**\ + 중개수수료 수식 +
+
+
+ **settlementFormula.channelFee (TBA)**\ + 결제수수료 수식 +
+
+
+ **settlementFormula.discountShare**\ + 할인분담금 수식 +
+
-
+
+
+ **settlementFormula.additionalFee**\ + 추가 수수료 수식 +
+
- **settlementFormula.additionalFee**\ - 추가 수수료 수식 + --- +
- -
+ ```json + { + "roundType": "DOWN", + "settlementFormula": { + "platformFee": "string", + "discountShare": "string", + "additionalFee": "string" + } + } + ``` ---- + **Response** -
-
- -**Request** - -```json -{ - "roundType": "DOWN", - "settlementFormula": { - "platformFee": "string", - "discountShare": "string", - "additionalFee": "string" - } -} -``` - -**Response** - -파트너정산을 사용하실수 있는 고객사는 기본으로 해당 값이 설정이 됩니다. - -```json -{ - "merchantId": "merchant-58c965f5-85f7-4c49-b770-cc11f3294bda", - "graphqlId": "MTptZXJjaGFudC01OGM5NjVmNS04NWY3LTRjNDktYjc3MC1jYzExZjMyOTRiZGE=", - "roundType": "DOWN", - "settlementFormula": { - "platformFee": "(주문금액 * 플랫폼수수료율) + 플랫폼수수료액", - "discountShare": "할인금액 * 할인분담률", - "additionalFee": "(주문금액 * 추가수수료율) + 추가수수료액" - } -} -``` + 파트너정산을 사용하실수 있는 고객사는 기본으로 해당 값이 설정이 됩니다. -
+ ```json + { + "merchantId": "merchant-58c965f5-85f7-4c49-b770-cc11f3294bda", + "graphqlId": "MTptZXJjaGFudC01OGM5NjVmNS04NWY3LTRjNDktYjc3MC1jYzExZjMyOTRiZGE=", + "roundType": "DOWN", + "settlementFormula": { + "platformFee": "(주문금액 * 플랫폼수수료율) + 플랫폼수수료액", + "discountShare": "할인금액 * 할인분담률", + "additionalFee": "(주문금액 * 추가수수료율) + 추가수수료액" + } + } + ``` +
### 파트너 정산 설정 조회 `GET https://api.portone.io/platform` -
-
- -**Parameter** - -없음.고객사의 플랫폼 정보를 조회합니다. 요청된 Authorization header 를 통해 자동으로 요청자의 고객사를 특정합니다. - -
-
+
+
+ **Parameter** -**Response** + 없음.고객사의 플랫폼 정보를 조회합니다. 요청된 Authorization header 를 통해 자동으로 요청자의 고객사를 특정합니다. +
-파트너정산을 사용하실수 있는 고객사는 기본으로 해당 값이 설정이 됩니다. +
+ **Response** -```json -{ - "merchantId": "merchant-58c965f5-85f7-4c49-b770-cc11f3294bda", - "graphqlId": "MTptZXJjaGFudC01OGM5NjVmNS04NWY3LTRjNDktYjc3MC1jYzExZjMyOTRiZGE=", - "roundType": "DOWN", - "settlementFormula": { - "platformFee": "(주문금액 * 플랫폼수수료율) + 플랫폼수수료액", - "discountShare": "할인금액 * 할인분담률", - "additionalFee": "(주문금액 * 추가수수료율) + 추가수수료액" - } -} -``` + 파트너정산을 사용하실수 있는 고객사는 기본으로 해당 값이 설정이 됩니다. -
+ ```json + { + "merchantId": "merchant-58c965f5-85f7-4c49-b770-cc11f3294bda", + "graphqlId": "MTptZXJjaGFudC01OGM5NjVmNS04NWY3LTRjNDktYjc3MC1jYzExZjMyOTRiZGE=", + "roundType": "DOWN", + "settlementFormula": { + "platformFee": "(주문금액 * 플랫폼수수료율) + 플랫폼수수료액", + "discountShare": "할인금액 * 할인분담률", + "additionalFee": "(주문금액 * 추가수수료율) + 추가수수료액" + } + } + ``` +