diff --git a/src/content/blog/2024-03/tgs.mdx b/src/content/blog/2024-03/tgs.mdx index 2f6b4cd08..ece60244d 100644 --- a/src/content/blog/2024-03/tgs.mdx +++ b/src/content/blog/2024-03/tgs.mdx @@ -66,7 +66,7 @@ V1을 완전히 버리고 V2로 넘어가는 것이 아니기 때문에 하나 |taxScopeAmount |Number |O |과세 대상 금액. 과세 대상 금액 + 면세 대상 금액 + 컵 보증금 금액 (옵션) = 총 결제 금액 | |taxExScopeAmount |Number |O |면세 대상 금액. 과세 대상 금액 + 면세 대상 금액 + 컵 보증금 금액 (옵션) = 총 결제 금액 | |environmentDepositAmount |Number | |1회용 컵에 담은 상품의 결제건인 경우에만 필수값이며, 그 외에는 전달할 필요가 없습니다. 컵 보증금 금액. 과세 대상 금액 + 면세 대상 금액 + 컵 보증금 금액 (옵션) = 총 결제 금액 | -|returnUrl |String |O |결제 인증 결과 전달 URL. 결제 완료 후 이동할 URL(returnUrl + 고객사 파라미터 전달이 가능합니다). 네이버페이는 결제 작업 완료 후, 고객사가 등록한 returnUrl로 리디렉션을 수행합니다. 고객사는 이를 활용하여 내부 처리를 수행하거나 구매자에게 결제 결과 화면을 노출할 수 있습니다. | +|returnUrl |String |O |결제 인증 결과 전달 URL. 결제 완료 후 이동할 URL(returnUrl + 고객사 파라미터 전달이 가능합니다). 네이버페이는 결제 작업 완료 후, 고객사가 등록한 returnUrl로 리디렉션을 수행합니다. 고객사는 이를 활용하여 내부 처리를 수행하거나 구매자에게 결제 결과 화면을 노출할 수 있습니다. | |purchaserName |String | |구매자 성명. 결제 상품이 보험 및 위험 업종 등인 경우에만 필수 값입니다. 그 외에는 전달할 필요가 없습니다 | |purchaserBirthday |String | |구매자 생년월일(yyyymmdd). 결제 상품이 보험 및 위험 업종 등인 경우에만 필수 값입니다. 그 외에는 전달할 필요가 없습니다 | |extraDeduction |Boolean| |도서 / 공연 / 영화 소득공제 대상 여부. 문화체육관광부에서 인증한 소득공제 제공 사업자가 대상 상품을 판매하는 경우 필수 값입니다. 해당 파라미터를 사용하기 위해서는 별도 요청을 주셔야 합니다. true : 대상, false : 비 대상 | diff --git a/src/content/docs/en/ready/2-pg/pg/undefined-2.mdx b/src/content/docs/en/ready/2-pg/pg/undefined-2.mdx index d086c61f2..c3239af8e 100644 --- a/src/content/docs/en/ready/2-pg/pg/undefined-2.mdx +++ b/src/content/docs/en/ready/2-pg/pg/undefined-2.mdx @@ -4,37 +4,34 @@ description: 네이버페이(결제형) PG설정 방법을 안내합니다. --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; -import Tabs from "~/components/gitbook/tabs/Tabs.astro"; import Tab from "~/components/gitbook/tabs/Tab.astro"; +import Tabs from "~/components/gitbook/tabs/Tabs.astro"; +import Hint from "~/components/Hint.astro"; -**네이버페이는 테스트 연동정보를 별도로 제공하지 않습니다. 가입신청 후 연동정보를 받아서 테스트 모드로 연동/개발 할 수 있습니다.** - + **네이버페이는 테스트 연동정보를 별도로 제공하지 않습니다. 가입신청 후 연동정보를 받아서 테스트 모드로 연동/개발 할 수 있습니다.** ## 일반**결제** - -### 테스트 환경 구성방법 - -[아임포트 관리자 콘솔](https://admin.iamport.kr/)→ 시스템설정 → PG설정(**일반결제 및 정기결제**) → PG사 \[간편결제네이버페이(결제) 선택 → 테스트모드 \[ON] → **발급받은 상점정보 입력** → \[전체 저장] 클릭 + + ### 테스트 환경 구성방법 -- **파트너아이디** : 네이버페이 결제형 파트너ID 입력 -- **클라이언트 ID** : 네이버페이측에서 카드사 심사 완료시 고객사로 직접 안내됨 -- **클라이언트 SECRET** : 네이버페이측에서 카드사 심사 완료시 고객사로 직접 안내됨 + [아임포트 관리자 콘솔](https://admin.iamport.kr/)→ 시스템설정 → PG설정(**일반결제 및 정기결제**) → PG사 \[간편결제네이버페이(결제) 선택 → 테스트모드 \[ON] → **발급받은 상점정보 입력** → \[전체 저장] 클릭 -![]() + - **파트너아이디** : 네이버페이 결제형 파트너ID 입력 + - **클라이언트 ID** : 네이버페이측에서 카드사 심사 완료시 고객사로 직접 안내됨 + - **클라이언트 SECRET** : 네이버페이측에서 카드사 심사 완료시 고객사로 직접 안내됨 - + ![]() + - -### **실** 환경 구성방법 + + ### **실** 환경 구성방법 -**테스트모드 OFF** 설정(네이버페이 실 검수가 시작되면 OFF 설정) - - + **테스트모드 OFF** 설정(네이버페이 실 검수가 시작되면 OFF 설정) + ## 정기결제 @@ -42,71 +39,85 @@ import Tab from "~/components/gitbook/tabs/Tab.astro"; ### 네이버페 정기결제는 결제창 방식만 지원합니다. - -### 테스트 환경 구성방법 - -[아임포트 관리자 콘솔](https://admin.iamport.kr/)→ 시스템설정 → PG설정(**일반결제 및 정기결제**) → PG사 \[간편결제네이버페이(결제) 선택 → 테스트모드 \[ON] → **발급받은 상점정보 입력** → \[전체 저장] 클릭 + + ### 테스트 환경 구성방법 -- **파트너아이디** : 네이버페이 결제형 파트너ID 입력 -- **클라이언트 ID** : 네이버페이측에서 카드사 심사 완료시 고객사로 직접 안내됨 -- **클라이언트 SECRET** : 네이버페이측에서 카드사 심사 완료시 고객사로 직접 안내됨 + [아임포트 관리자 콘솔](https://admin.iamport.kr/)→ 시스템설정 → PG설정(**일반결제 및 정기결제**) → PG사 \[간편결제네이버페이(결제) 선택 → 테스트모드 \[ON] → **발급받은 상점정보 입력** → \[전체 저장] 클릭 -![]() + - **파트너아이디** : 네이버페이 결제형 파트너ID 입력 + - **클라이언트 ID** : 네이버페이측에서 카드사 심사 완료시 고객사로 직접 안내됨 + - **클라이언트 SECRET** : 네이버페이측에서 카드사 심사 완료시 고객사로 직접 안내됨 -### 실 환경 구성방법 + ![]() -**테스트모드 OFF** 설정(네이버페이 실 검수가 시작되면 OFF 설정) + ### 실 환경 구성방법 - + **테스트모드 OFF** 설정(네이버페이 실 검수가 시작되면 OFF 설정) + -#### **네이버페이 검수란?** - -네이버페이 결제형 오픈을 위해서는 네이버페이 검수팀으로 부터 기술검수 통과가 진행되어야 합니다. 해당 검수는 **필수**적으로 진행되어야 하며 해당 검수는 모든 연동이 완료된 이후 당사로 검수요청을 주시면 아임포트 1차 검토 이후 이상이 없는 경우 네이버페이로 실 검수 요청하는 프로세스로 진행됩니다. + #### **네이버페이 검수란?** + 네이버페이 결제형 오픈을 위해서는 네이버페이 검수팀으로 부터 기술검수 통과가 진행되어야 합니다. 해당 검수는 **필수**적으로 진행되어야 하며 해당 검수는 모든 연동이 완료된 이후 당사로 검수요청을 주시면 아임포트 1차 검토 이후 이상이 없는 경우 네이버페이로 실 검수 요청하는 프로세스로 진행됩니다.
-

네이버페이 기술검수 요청 방법

- -네이버페이 기술검수를 위해서는 아래 질문리스트를 작성하여 아래 이메일 주소로 검수요청을 주시면 됩니다. - -``` -<사업자 및 계약정보>   -    - 상호명 :  -    - 사업자번호 :  -    - 아임포트계정 :  -    - 네이버페이 결제형 파트너ID : 단건/반복(정기) 이용하실 방식 구분하여 전달 주시기 바랍니다. -    - 검수 진행가능한 URL :  -    - 테스트 가능한 로그인계정 : +

네이버페이 기술검수 요청 방법

+ + 네이버페이 기술검수를 위해서는 아래 질문리스트를 작성하여 아래 이메일 주소로 검수요청을 주시면 됩니다. + + **사업자 및 계약정보** + + - 상호명 : + + - 사업자번호 : + + - 아임포트계정 : + + - 네이버페이 결제형 파트너ID : 단건/반복(정기) 이용하실 방식 구분하여 전달 주시기 바랍니다. + + - 검수 진행가능한 URL : + + - 테스트 가능한 로그인계정 : + - 네이버페이 결제형 연동 개발자 정보(이름/이메일/전화번호): - 네이버페이 결제형 연동 검수 담당자 정보(이름/이메일/전화번호): - - 판매상품 과/면세 여부: ​ - - 에스크로 사용여부: ​ + - 판매상품 과/면세 여부: + - 에스크로 사용여부: - 모바일앱 보유 여부: - - 부분취소 제공여부: ​ - - IMP.request_pay 함수 호출 시 naverProducts 파라미터 설정여부 및 셋팅 예시: - -<질의사항> -1. 일반결제만 연동하는 경우 -    1) 지원하는 PC 웹 브라우저 종류와 최소 버전: -    2) 지원하는 모바일 웹 브라우저 종류와 최소 버전: -    (앱으로만 연동하시는 경우, 지원하는 모바일 OS 종류와 최소 버전: (ex. iOS 12.0.1, Android 8.0)) -    3) 네이버페이 계약 시, 현금영수증 발급을 누가 하도록 결정하셨나요? -    4) 네이버페이 계약 시, 포인트 적립 방식은 자동지급방식으로 계약하셨나요? 직접 건별로 지급하기로 계약하셨나요? - -2. 일반 + 정기결제 모두 연동하는 경우 -   1) 지원하는 PC 웹 브라우저 종류와 최소 버전: -   2) 지원하는 모바일 웹 브라우저 종류와 최소 버전: -  (앱으로만 연동하시는 경우, 지원하는 모바일 OS 종류와 최소 버전: (ex. iOS 12.0.1, Android 8.0)) -   3) 네이버페이 계약 시, 현금영수증 발급을 누가 하도록 결정하셨나요? -   4) 네이버페이 계약 시, 포인트 적립 방식은 자동지급방식으로 계약하셨나요? 직접 건별로 지급하기로 계약하셨나요? -   5) 정기결제 등록 내역 조회를 어떤 방식으로 구현하시고 계신가요? 예) 관리자페이지 반복결제내역 조회 시 / 자체주문 생성 시 정보조회 -   6) 결제 내역 조회를 어떤 방식으로 구현하시고 계신가요? 예) 관리자페이지 결제내역 조회 시 / 자체주문 생성 시 정보조회 / 정산 대사 작업 배치 -   7) 어떤 경우에 정기결제가 해제되나요? 예) 등록생성 실패 시 / 등록된 반복결제항목 해제 시 / 관리자 반복결제 등록항목 해제 -``` - -**email : support@iamport.kr** + - 부분취소 제공여부: + - IMP.request\_pay 함수 호출 시 naverProducts 파라미터 설정여부 및 셋팅 예시: + + **질의사항** + + 1. 일반결제만 연동하는 경우 + + - 지원하는 PC 웹 브라우저 종류와 최소 버전: + + - 지원하는 모바일 웹 브라우저 종류와 최소 버전: + (앱으로만 연동하시는 경우, 지원하는 모바일 OS 종류와 최소 버전: (ex. iOS 12.0.1, Android 8.0)) + + - 네이버페이 계약 시, 현금영수증 발급을 누가 하도록 결정하셨나요? + + - 네이버페이 계약 시, 포인트 적립 방식은 자동지급방식으로 계약하셨나요? 직접 건별로 지급하기로 계약하셨나요? + + 2. 일반 + 정기결제 모두 연동하는 경우 + + - 지원하는 PC 웹 브라우저 종류와 최소 버전: + + - 지원하는 모바일 웹 브라우저 종류와 최소 버전: + (앱으로만 연동하시는 경우, 지원하는 모바일 OS 종류와 최소 버전: (ex. iOS 12.0.1, Android 8.0)) + + - 네이버페이 계약 시, 현금영수증 발급을 누가 하도록 결정하셨나요? + + - 네이버페이 계약 시, 포인트 적립 방식은 자동지급방식으로 계약하셨나요? 직접 건별로 지급하기로 계약하셨나요? + + - 정기결제 등록 내역 조회를 어떤 방식으로 구현하시고 계신가요? 예) 관리자페이지 반복결제내역 조회 시 / 자체주문 생성 시 정보조회 + + - 결제 내역 조회를 어떤 방식으로 구현하시고 계신가요? 예) 관리자페이지 결제내역 조회 시 / 자체주문 생성 시 정보조회 / 정산 대사 작업 배치 + + - 어떤 경우에 정기결제가 해제되나요? 예) 등록생성 실패 시 / 등록된 반복결제항목 해제 시 / 관리자 반복결제 등록항목 해제 + **email : [support@iamport.kr](mailto:support@iamport.kr)**
diff --git a/src/content/docs/ko/api/api.mdx b/src/content/docs/ko/api/api.mdx index 0bb301103..625f42ecc 100644 --- a/src/content/docs/ko/api/api.mdx +++ b/src/content/docs/ko/api/api.mdx @@ -6,7 +6,7 @@ description: 포트원 API 를 소개합니다. import Figure from "~/components/Figure.astro"; import Hint from "~/components/Hint.astro"; -### 포트원 API를 이용하기 위한 HTTP Header 설정을 안내합니다. +## 포트원 API를 이용하기 위한 HTTP Header 설정을 안내합니다. 1. [**/users/getToken**](rest-api-access-token) 에서 **API Key** & **API secret**을 사용해 **`access_token`**을 발급받습니다. 2. API 호출 시 **`access_token`**을 **`Authorization:`** **`access_token`** 또는 **`X-ImpTokenHeader:`** **`access_token`**으로 HTTP header를 통해 전달합니다. diff --git a/src/content/docs/ko/api/billing-key-api/get-billing-key-api.mdx b/src/content/docs/ko/api/billing-key-api/get-billing-key-api.mdx index 21c01fdeb..e7063e5d9 100644 --- a/src/content/docs/ko/api/billing-key-api/get-billing-key-api.mdx +++ b/src/content/docs/ko/api/billing-key-api/get-billing-key-api.mdx @@ -4,193 +4,181 @@ description: 발급된 빌링키 정보를 확인할 수 있습니다. --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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"; -### 구매자의 빌링키 단건 정보를 조회 합니다. +## 구매자의 빌링키 단건 정보를 조회 합니다. - -빌링키 정보를 확인할 수 있습니다. - - - -### Parameters - -#### Path - - - + + 빌링키 정보를 확인할 수 있습니다. + -**빌링키** + ### Parameters - + #### Path - + + + **빌링키** + + -### Responses + ### Responses - - - -**`code`** **\*** **integer** + + + + **`code`** **\*** **integer** -**응답코드** + **응답코드** -0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 + 0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 -**`message`** **\*** **string** + **`message`** **\*** **string** -**응답메세지** + **응답메세지** -code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 + code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 -**`response`** **(CustomerAnnotation, optional)** + **`response`** **(CustomerAnnotation, optional)** + + - - + + + **`code`** **\*** **integer** - - -**`code`** **\*** **integer** + **`응답코드`** -**`응답코드`** + 0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 -0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 + **`message`** **\*** **string** -**`message`** **\*** **string** + **`응답메세지`** -**`응답메세지`** + code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 -code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 + **`customer_uid`** **\*** **string** -**`customer_uid`** **\*** **string** + **`빌링키`** -**`빌링키`** + **`pg_provider`** **\*** **string** -**`pg_provider`** **\*** **string** + **빌링키가 등록된 PG사 구분코드** -**빌링키가 등록된 PG사 구분코드** + **`pg_id`** **\*** **string** -**`pg_id`** **\*** **string** + **빌링키가 등록된 PG사 상점아이디(MID)** -**빌링키가 등록된 PG사 상점아이디(MID)** + **`customer_id`** **string** -**`customer_id`** **string** + **구매자 ID** -**구매자 ID** + **`card_name`** **\*** **string** -**`card_name`** **\*** **string** + **`카드사명`** -**`카드사명`** + **`card_code`** **string** -**`card_code`** **string** + **`카드사 코드`**[**`(링크보기)`**](https://chaifinance.notion.site/53589280bbc94fab938d93257d452216?v=eb405baf52134b3f90d438e3bf763630) -**`카드사 코드`**[**`(링크보기)`**](https://chaifinance.notion.site/53589280bbc94fab938d93257d452216?v=eb405baf52134b3f90d438e3bf763630) + **`card_number`** **string** -**`card_number`** **string** + **`마스킹 카드번호`** -**`마스킹 카드번호`** + **`card_type`** **string** -**`card_type`** **string** + **`카드유형`** -**`카드유형`** + **(주의)해당 정보를 제공하지 않는 일부 PG사의 경우 null 로 응답됨** + (ex. JTNet, 이니시스 -빌링) -**(주의)해당 정보를 제공하지 않는 일부 PG사의 경우 null 로 응답됨** -(ex. JTNet, 이니시스 -빌링) + - 0 : 신용카드 + - 1 : 체크카드 -- 0 : 신용카드 -- 1 : 체크카드 + **`customer_name`** **string** -**`customer_name`** **string** + **`고객성함`** -**`고객성함`** + **`customer_tel`** **string** -**`customer_tel`** **string** + **`고객(카드소지자) 전화번호`** -**`고객(카드소지자) 전화번호`** + **`customer_email`** **string** -**`customer_email`** **string** + **`고객(카드소지자) Email 주소`** -**`고객(카드소지자) Email 주소`** + **`customer_addr`** **string** -**`customer_addr`** **string** + **`고객(카드소지자) 주소`** -**`고객(카드소지자) 주소`** + **`customer_postcode`** **string** -**`customer_postcode`** **string** + **`고객(카드소지자) 우편번호`** -**`고객(카드소지자) 우편번호`** + **`inserted`** **\*** **integer** -**`inserted`** **\*** **integer** + **`빌링키가 등록된 시각`** UNIX timestamp -**`빌링키가 등록된 시각`** UNIX timestamp + **`updated`** **\*** **integer** -**`updated`** **\*** **integer** + **`빌링키가 업데이트된 시각`** UNIX timestamp + + + -**`빌링키가 업데이트된 시각`** UNIX timestamp - - - - - - - -```javascript -{ - // Response -} -``` - - - - -```javascript -{ - // Response -} -``` - - + + ```javascript + { + // Response + } + ``` + + + ```javascript + { + // Response + } + ``` +
-

Response Model Schema

- -```json -{ - "code": 0, - "message": "string", - "response": { - "customer_uid": "string", - "pg_provider": "string", - "pg_id": "string", - "card_name": "string", - "card_code": "string", - "card_number": "string", - "card_type": "null", - "customer_name": "string", - "customer_tel": "string", - "customer_email": "string", - "customer_addr": "string", - "customer_postcode": "string", - "inserted": 0, - "updated": 0 +

Response Model Schema

+ + ```json + { + "code": 0, + "message": "string", + "response": { + "customer_uid": "string", + "pg_provider": "string", + "pg_id": "string", + "card_name": "string", + "card_code": "string", + "card_number": "string", + "card_type": "null", + "customer_name": "string", + "customer_tel": "string", + "customer_email": "string", + "customer_addr": "string", + "customer_postcode": "string", + "inserted": 0, + "updated": 0 + } } -} -``` - + ```
-**Swagger Test Link** - -[**https://api.iamport.kr/#!/subscribe.customer/customer_view**](https://api.iamport.kr/#!/subscribe.customer/customer_view) + **Swagger Test Link** + [**https://api.iamport.kr/#!/subscribe.customer/customer\_view**](https://api.iamport.kr/#!/subscribe.customer/customer_view) diff --git a/src/content/docs/ko/api/cash-receipt-api/get-external-cash-receipt-api.mdx b/src/content/docs/ko/api/cash-receipt-api/get-external-cash-receipt-api.mdx index b6f69d918..b145cc25f 100644 --- a/src/content/docs/ko/api/cash-receipt-api/get-external-cash-receipt-api.mdx +++ b/src/content/docs/ko/api/cash-receipt-api/get-external-cash-receipt-api.mdx @@ -4,150 +4,139 @@ description: 포트원 API를 통해 현금영수증만 발행된 건의 상세 --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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"; -### 현금영수증 발급내역을 조회합니다. +## 현금영수증 발급내역을 조회합니다. - - -포트원 API를 통해 현금영수증만 발행된 건의 상세정보를 조회하는 API입니다. (포트원와 별개로 결제된 현금거래건) - - -### Parameters - -#### Path - - - + + 포트원 API를 통해 현금영수증만 발행된 건의 상세정보를 조회하는 API입니다. (포트원와 별개로 결제된 현금거래건) + -**고객사 주문번호** + ### Parameters - + #### Path -현금영수증 발행 대상 고객사 주문번호 + + + **고객사 주문번호** + - + 현금영수증 발행 대상 고객사 주문번호 + -### Responses + ### Responses - - - -**`code`** **\*** **integer** + + + + **`code`** **\*** **integer** -**응답코드** + **응답코드** -0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 + 0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 -**`message`** **\*** **string** + **`message`** **\*** **string** -**응답메세지** + **응답메세지** -code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 + code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 -**`response`** **`(ExternalReceiptAnnotation, optional)`** + **`response`** **`(ExternalReceiptAnnotation, optional)`** + + - - + + + **`merchant_uid`** **\*** **`string`** - - -**`merchant_uid`** **\*** **`string`** + **`고객사 주문번호`** -**`고객사 주문번호`** + **`receipt_tid`** **`string`** -**`receipt_tid`** **`string`** + **`현금영수증 PG사 발행고유번호`** -**`현금영수증 PG사 발행고유번호`** + **`apply_num`** **\*** **`string`** -**`apply_num`** **\*** **`string`** + **`현금영수증 국세청 발행번호`** -**`현금영수증 국세청 발행번호`** + **`type`** **\*** **`string`** -**`type`** **\*** **`string`** + **`현금영수증 발행대상 타입`** -**`현금영수증 발행대상 타입`** + - 개인 : `person` + - 사업자 : `company` -- 개인 : `person` -- 사업자 : `company` + **`amount`** **\*** **`integer`** -**`amount`** **\*** **`integer`** + **`현금영수증 발행금액`** -**`현금영수증 발행금액`** + **`vat`** **\*** **`integer`** -**`vat`** **\*** **`integer`** + **`현금영수증 발행금액 중 부가세금액`** -**`현금영수증 발행금액 중 부가세금액`** + **`receipt_url`** **`string`** -**`receipt_url`** **`string`** + **`발행된 현금영수증 URL`** -**`발행된 현금영수증 URL`** + **`applied_at`** **\*** **`integer`** -**`applied_at`** **\*** **`integer`** + **현금영수증 발행시각** `UNIX TIMESTAMP` -**현금영수증 발행시각** `UNIX TIMESTAMP` + **`cancelled_at`** **`integer`** -**`cancelled_at`** **`integer`** + **`현금영수증 발행취소시각`** `UNIX TIMESTAMP` + + + -**`현금영수증 발행취소시각`** `UNIX TIMESTAMP` - - - - - - - -```javascript -{ - // Response -} -``` - - - - -```javascript -{ - // Response -} -``` - - + + ```javascript + { + // Response + } + ``` + + + ```javascript + { + // Response + } + ``` +
-

Response Model Schema

- -``` -{ - "code": 0, - "message": "string", - "response": { - "merchant_uid": "string", - "receipt_tid": "string", - "apply_num": "string", - "type": "person", - "amount": 0, - "vat": 0, - "receipt_url": "string", - "applied_at": 0, - "cancelled_at": 0 +

Response Model Schema

+ + ```json + { + "code": 0, + "message": "string", + "response": { + "merchant_uid": "string", + "receipt_tid": "string", + "apply_num": "string", + "type": "person", + "amount": 0, + "vat": 0, + "receipt_url": "string", + "applied_at": 0, + "cancelled_at": 0 + } } -} -``` - + ```
-**Swagger Test Link** + **Swagger Test Link** -[**https://api.iamport.kr/#!/receipts/getExternalReceipt**](https://api.iamport.kr/#!/receipts/getExternalReceipt) + [**https://api.iamport.kr/#!/receipts/getExternalReceipt**](https://api.iamport.kr/#!/receipts/getExternalReceipt) diff --git a/src/content/docs/ko/api/cash-receipt-api/issue-cash-receipt-api.mdx b/src/content/docs/ko/api/cash-receipt-api/issue-cash-receipt-api.mdx index e9ed1c6f0..46083d6b3 100644 --- a/src/content/docs/ko/api/cash-receipt-api/issue-cash-receipt-api.mdx +++ b/src/content/docs/ko/api/cash-receipt-api/issue-cash-receipt-api.mdx @@ -4,19 +4,19 @@ description: 현금영수증을 발급할 수 있습니다. --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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`**)를 기준으로 현금영수증이 발급 됩니다. -imp_uid 거래를 처리하는데 사용된 PG설정값을 그대로 활용합니다. +imp\_uid 거래를 처리하는데 사용된 PG설정값을 그대로 활용합니다. (ex. KCP 거래건이면 KCP를 통해 현금영수증 발행 API처리) 현금영수증 발급 금액은 **현금성 거래의 금액으로 자동 적용**됩니다. 부분취소된 거래인 경우 **남은 잔액으로 발급**됩니다. @@ -24,248 +24,232 @@ imp_uid 거래를 처리하는데 사용된 PG설정값을 그대로 활용합 발행금액의 1/11 이 부가세로 자동 적용되므로, 부가세금액 조정을 위해서는 `tax_free` 파라메터를 활용해주세요.
-

지원되는 PG사 확인하기

- -- **KG 이니시스** -- **NHN KCP** -- **헥토파이낸셜 (구. 세틀뱅크)** -- **나이스페이먼츠** -- **키움페이(구 다우, 페이조아)** -- **KICC** -- **KSNET** -- **스마트로 - 신모듈** -- **토스페이먼츠 - 신모듈** -- **웰컴페이먼츠** - +

지원되는 PG사 확인하기

+ + - **KG 이니시스** + - **NHN KCP** + - **헥토파이낸셜** + - **나이스페이먼츠** + - **키움페이** + - **(이지페이)KICC** + - **KSNET** + - **스마트로(신모듈)** + - **토스페이먼츠(신모듈)** + - **웰컴페이먼츠**
- -현금영수증 발행을 처리하는 포트원 API 입니다. - - - -### Parameters - -#### Path - - - - -**포트원 거래고유번호** - - - - - -#### Body - - - + + 현금영수증 발행을 처리하는 포트원 API 입니다. + -**현금영수증 발행 주문 상품구분** + ### Parameters - + #### Path -(필수: KSNET) + + + **포트원 거래고유번호** + + - - - + #### Body -**현금영수증 발행대상 식별정보** + + + **현금영수증 발행 주문 상품구분** + - + (필수: KSNET) + - - -**현금영수증 식별정보 구분코드** + + + **현금영수증 발행대상 식별정보** + + -(필수 : KICC, 헥토파이낸셜(구 세틀뱅크)) + + **현금영수증 식별정보 구분코드** -(KG이니시스/NHN KCP/나이스페이먼츠/키움페이(구 다우, 페이조아), 웰컴페이먼츠는 identifier 만으로 자동 처리) + (필수 : KICC, 헥토파이낸셜(구 세틀뱅크)) -`person : 주민등록번호` + (KG이니시스/NHN KCP/나이스페이먼츠/키움페이(구 다우, 페이조아), 웰컴페이먼츠는 identifier 만으로 자동 처리) -`business : 사업자등록번호` + `person : 주민등록번호` -`phone : 휴대폰번호` + `business : 사업자등록번호` -`taxcard : 국세청현금영수증카드` + `phone : 휴대폰번호` - - -**현금영수증 발행 타입(대상)** + `taxcard : 국세청현금영수증카드` + -`소득공제용(개인) : person` + + **현금영수증 발행 타입(대상)** -`지출증빙용(법인) : company` + `소득공제용(개인) : person` -`기본값 : person` + `지출증빙용(법인) : company` - - -**발행 상점 고객센터 번호** + `기본값 : person` + -(필수 : 키움페이(구 다우, 페이조아)) + + **발행 상점 고객센터 번호** - - -**상점 사업자 명** + (필수 : 키움페이(구 다우, 페이조아)) + -(필수 : 키움페이(구 다우, 페이조아)) + + **상점 사업자 명** - - -**상점 사업자 번호** + (필수 : 키움페이(구 다우, 페이조아)) + -(필수 : 키움페이(구 다우, 페이조아), 웰컴페이먼츠) + + **상점 사업자 번호** - - -**구매자 이름** + (필수 : 키움페이(구 다우, 페이조아), 웰컴페이먼츠) + -(필수 : KSNET, 스마트로 - 신모듈) + + **구매자 이름** - - -**구매자 Email 주소** + (필수 : KSNET, 스마트로 - 신모듈) + - - -**구매자 전화번호** + + **구매자 Email 주소** + -(필수 : 스마트로 - 신모듈, 웰컴페이먼츠) + + **구매자 전화번호** - - -**현금영수증 발행금액 중 면세금액** + (필수 : 스마트로 - 신모듈, 웰컴페이먼츠) + -지정하지 않으면 0원으로 적용 + + **현금영수증 발행금액 중 면세금액** - - -**부가세 지정 금액** + 지정하지 않으면 0원으로 적용 + -부가세 지정 고객사에 한해 현금영수증 발행 금액 중 부가세 금액으로 부가세를 지정할 수 있습니다. + + **부가세 지정 금액** - + 부가세 지정 고객사에 한해 현금영수증 발행 금액 중 부가세 금액으로 부가세를 지정할 수 있습니다. + -### Responses + ### Responses - - - -**`code`** **\*** **integer** + + + + **`code`** **\*** **integer** -**응답코드** + **응답코드** -0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 + 0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 -**`message`** **\*** **string** + **`message`** **\*** **string** -**응답메세지** + **응답메세지** -code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 + code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 -**`response`** **`(ReceiptAnnotation, optional)`** + **`response`** **`(ReceiptAnnotation, optional)`** + + - - + + + **`imp_uid`** **\*** **`string`** - - -**`imp_uid`** **\*** **`string`** + **포트원 거래고유번호** -**포트원 거래고유번호** + **`receipt_tid`** **`string`** -**`receipt_tid`** **`string`** + **현금영수증 PG사 발행고유번호** -**현금영수증 PG사 발행고유번호** + **`apply_num`** **\*** **`string`** -**`apply_num`** **\*** **`string`** + **현금영수증 국세청 발행번호** -**현금영수증 국세청 발행번호** + **`type`** **\*** **`string`** -**`type`** **\*** **`string`** + **현금영수증 발행 타입(대상)** -**현금영수증 발행 타입(대상)** + - 개인 : `person` + - 사업자 : `company` -- 개인 : `person` -- 사업자 : `company` + **`amount`** **\*** **`integer`** -**`amount`** **\*** **`integer`** + **현금영수증 발행금액** -**현금영수증 발행금액** + **`vat`** **\*** **`integer`** -**`vat`** **\*** **`integer`** + **부가세** -**부가세** + **`receipt_url`** **`string`** -**`receipt_url`** **`string`** + **발행된 현금영수증 URL** -**발행된 현금영수증 URL** + **`applied_at`** **\*** **`integer`** -**`applied_at`** **\*** **`integer`** + **현금영수증 발행시각 (UNIX TIMESTAMP)** -**현금영수증 발행시각 (UNIX TIMESTAMP)** + **`cancelled_at`** **`integer`** -**`cancelled_at`** **`integer`** + **현금영수증 발행취소시각 (UNIX TIMESTAMP)** + + + -**현금영수증 발행취소시각 (UNIX TIMESTAMP)** + + ```javascript + { + // Response + } + ``` + - - + + ```javascript + { + // Response + } + ``` + - + + ```javascript + { + // Response + } + ``` + - -```javascript -{ - // Response -} -``` - - - - -```javascript -{ - // Response -} -``` - - - - -```javascript -{ - // Response -} -``` - - - - -```javascript -{ - // Response -} -``` - - + + ```javascript + { + // Response + } + ``` + -### **주요 요청 파라미터 상세 설명** +### 주요 요청 파라미터 상세 설명 > **`product_type`** **\*** **`string`** > > **현금영수증 발행 주문 상품구분** > > (필수 : KSNET) -> - real: 실물상품 -> - digital: 디지털컨텐츠보 > +> - real: 실물상품 +> - digital: 디지털컨텐츠보 + > **`identifier`** **\*** **`string`** > > **현금영수증 발행대상 식별정보** @@ -293,36 +277,31 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 > **`buyer_tel`** **`string`** > > **구매자 전화번호 (현금영수증 발행 건 사후 추적을 위해 입력을 강력히 권장합니다.)** (필수 : 스마트로-신모듈) -> -> ->
-

Response Model Schema

- -```json -{ - "code": 0, - "message": "string", - "response": { - "imp_uid": "string", - "receipt_tid": "string", - "apply_num": "string", - "type": "person", - "amount": 0, - "vat": 0, - "receipt_url": "string", - "applied_at": 0, - "cancelled_at": 0 +

Response Model Schema

+ + ```json + { + "code": 0, + "message": "string", + "response": { + "imp_uid": "string", + "receipt_tid": "string", + "apply_num": "string", + "type": "person", + "amount": 0, + "vat": 0, + "receipt_url": "string", + "applied_at": 0, + "cancelled_at": 0 + } } -} -``` - + ```
-**Swagger Test Link** - -[**https://api.iamport.kr/#!/receipts/issueReceipt**](https://api.iamport.kr/#!/receipts/issueReceipt) + **Swagger Test Link** + [**https://api.iamport.kr/#!/receipts/issueReceipt**](https://api.iamport.kr/#!/receipts/issueReceipt) diff --git a/src/content/docs/ko/api/cash-receipt-api/issue-external-cash-receipt-api.mdx b/src/content/docs/ko/api/cash-receipt-api/issue-external-cash-receipt-api.mdx index 44e52b51e..6cab176e7 100644 --- a/src/content/docs/ko/api/cash-receipt-api/issue-external-cash-receipt-api.mdx +++ b/src/content/docs/ko/api/cash-receipt-api/issue-external-cash-receipt-api.mdx @@ -4,258 +4,240 @@ description: 포트원과 별개로 거래된 현금결제에 대한 현금영 --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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"; -### 포트원과 별개로 거래된 일반 현금결제에 대해서 현금영수증을 발행합니다. +## 포트원과 별개로 거래된 일반 현금결제에 대해서 현금영수증을 발행합니다.
-

지원되는 PG사 확인하기

- -- **KG 이니시스** -- **NHN KCP** -- **헥토파이낸셜 (구. 세틀뱅크)** -- **(구) 나이스페이먼츠** -- **키움페이(구 다우, 페이조아)** -- **KICC** -- **(신) 스마트로** -- **(신) 나이스페이먼츠** -- **웰컴페이먼츠** - +

지원되는 PG사 확인하기

+ + - **KG 이니시스** + - **NHN KCP** + - **헥토파이낸셜** + - **나이스페이먼츠(구모듈/신모듈)** + - **키움페이** + - **이지페이(KICC)** + - **스마트로(신모듈)** + - **웰컴페이먼츠**
- -포트원와 별개로 거래된 일반 현금결제에 대해, 포트원 내에 설정된 PG사로 현금영수증 발행 요청하는 API입니다. - -단 주문번호는 현금거래 주문번호와 동일한 번호를 기재해야 추후 대사가 가능한점 유념하시기 바랍니다. - -pg 파라메터를 지정하지 않으면, 기본 PG설정값을 이용해 발행시도하게 됩니다. -발행금액의 1/11 이 부가세로 자동 적용되므로, 부가세금액 조정을 위해서는 tax_free 파라메터를 활용해주세요. - - -### Parameters - -#### Path - - - - -**고객사 주문번호** - - - -((신) 스마트로의 경우, 특수문자 포함이 불가능합니다.) - - -#### Body + + 포트원와 별개로 거래된 일반 현금결제에 대해, 포트원 내에 설정된 PG사로 현금영수증 발행 요청하는 API입니다. - - + 단 주문번호는 현금거래 주문번호와 동일한 번호를 기재해야 추후 대사가 가능한점 유념하시기 바랍니다. -**현금영수증 발행 주문명** + pg 파라메터를 지정하지 않으면, 기본 PG설정값을 이용해 발행시도하게 됩니다. + 발행금액의 1/11 이 부가세로 자동 적용되므로, 부가세금액 조정을 위해서는 tax\_free 파라메터를 활용해주세요. + - + ### Parameters - - - + #### Path -**현금영수증 발행 금액** + + + **고객사 주문번호** + - + ((신) 스마트로의 경우, 특수문자 포함이 불가능합니다.) + - - -**현금영수증 발행 주문 상품구분** + #### Body -(필수 : KSNET) + + + **현금영수증 발행 주문명** + + -- real: 실물상품 -- digital: 디지털컨텐츠 + + + **현금영수증 발행 금액** + + - - -**현금영수증 발행대상 식별정보** + + **현금영수증 발행 주문 상품구분** -`국세청현금영수증카드` + (필수 : KSNET) -`휴대폰번호` + - real: 실물상품 + - digital: 디지털컨텐츠 + -`주민등록번호` + + **현금영수증 발행대상 식별정보** -`사업자등록번호` + `국세청현금영수증카드` -을 기재합니다. + `휴대폰번호` - - -**현금영수증 식별정보 구분코드** + `주민등록번호` -`person : 주민등록번호` + `사업자등록번호` -`business : 사업자등록번호` + 을 기재합니다. + -`phone : 휴대폰번호` + + **현금영수증 식별정보 구분코드** -`taxcard : 국세청현금영수증카드` + `person : 주민등록번호` - - -**현금영수증 발행 타입(대상)** + `business : 사업자등록번호` -`소득공제용(개인) : person` + `phone : 휴대폰번호` -`지출증빙용(법인) : company` + `taxcard : 국세청현금영수증카드` + -`기본값 : person` + + **현금영수증 발행 타입(대상)** - - -**구매자 이름** + `소득공제용(개인) : person` - - -**구매자 Email** + `지출증빙용(법인) : company` - - -**구매자 전화번호** + `기본값 : person` + - - -**면세금액** + + **구매자 이름** + - - -**PG 구분코드** + + **구매자 Email** + - - -**부가세 지정 금액** + + **구매자 전화번호** + -부가세 지정 고객사에 한해 현금영수증 발행 금액 중 부가세 금액으로 부가세를 지정할 수 있습니다. - + + **면세금액** + - -**상점 사업자 번호** + + **PG 구분코드** + - + + **부가세 지정 금액** - -**결제건의 결제수단** + 부가세 지정 고객사에 한해 현금영수증 발행 금액 중 부가세 금액으로 부가세를 지정할 수 있습니다. + - + + **상점 사업자 번호** + -### Responses + + **결제건의 결제수단** + - - - -**`code`** **integer** + ### Responses -**응답코드** + + + + **`code`** **integer** -0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 + **응답코드** -**`message`** **string** + 0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 -**응답메세지** + **`message`** **string** -code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 + **응답메세지** -**`response`** **`(ExternalReceiptAnnotation, optional)`** + code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 - - + **`response`** **`(ExternalReceiptAnnotation, optional)`** + + - - -**`merchant_uid`** **\*** **`string`** + + + **`merchant_uid`** **\*** **`string`** -**고객사 주문번호** + **고객사 주문번호** -**`receipt_tid`** **`string`** + **`receipt_tid`** **`string`** -**현금영수증 PG사 발행고유번호** + **현금영수증 PG사 발행고유번호** -**`apply_num`** **\*** **`string`** + **`apply_num`** **\*** **`string`** -**현금영수증 국세청 발행번호** + **현금영수증 국세청 발행번호** -**`type`** **\*** **`string`** + **`type`** **\*** **`string`** -**현금영수증 발행 타입(대상)** + **현금영수증 발행 타입(대상)** -- 개인 : `person` -- 사업자 : `company` + - 개인 : `person` + - 사업자 : `company` -**`amount`** **\*** **`integer`** + **`amount`** **\*** **`integer`** -**현금영수증 발행금액** + **현금영수증 발행금액** -**`vat`** **\*** **`integer`** + **`vat`** **\*** **`integer`** -**현금영수증 발행금액 중 부가세금액** + **현금영수증 발행금액 중 부가세금액** -**`receipt_url`** **`string`** + **`receipt_url`** **`string`** -**발행된 현금영수증 URL** + **발행된 현금영수증 URL** -**`applied_at`** **\*** **`integer`** + **`applied_at`** **\*** **`integer`** -**현금영수증 발행시각 (UNIX TIMESTAMP)** + **현금영수증 발행시각 (UNIX TIMESTAMP)** -**`cancelled_at`** **`integer`** + **`cancelled_at`** **`integer`** -**현금영수증 발행취소시각 (UNIX TIMESTAMP)** + **현금영수증 발행취소시각 (UNIX TIMESTAMP)** + + + - - + + ```javascript + { + // Response + } + ``` + - + + ```javascript + { + // Response + } + ``` + - -```javascript -{ - // Response -} -``` - - - - -```javascript -{ - // Response -} -``` - - - - -```javascript -{ - // Response -} -``` - - - - -```javascript -{ - // Response -} -``` - - + + ```javascript + { + // Response + } + ``` + + + ```javascript + { + // Response + } + ``` + ### **주요 요청 파라미터 상세 설명** @@ -265,9 +247,10 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 > **현금영수증 발행 주문 상품구분** > > (필수 : KSNET) +> > - real: 실물상품 > - digital: 디지털컨텐츠보 -> + > **`identifier`** **\*** **`string`** > > **현금영수증 발행대상 식별정보** @@ -311,39 +294,37 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 > > **`corp_reg_no`** **`string`** > > **상점 사업자 번호** (필수 : 웰컴페이먼츠) -> +> > > **`pay_method`** **`string`** > > **결제건의 결제수단** (필수 : 웰컴페이먼츠) -> +> > 계좌이체 : trans, 가상계좌 : vbank
-

Response Model Schema

- -```json -{ - "code": 0, - "message": "string", - "response": { - "merchant_uid": "string", - "receipt_tid": "string", - "apply_num": "string", - "type": "person", - "amount": 0, - "vat": 0, - "receipt_url": "string", - "applied_at": 0, - "cancelled_at": 0 +

Response Model Schema

+ + ```json + { + "code": 0, + "message": "string", + "response": { + "merchant_uid": "string", + "receipt_tid": "string", + "apply_num": "string", + "type": "person", + "amount": 0, + "vat": 0, + "receipt_url": "string", + "applied_at": 0, + "cancelled_at": 0 + } } -} -``` - + ```
-**Swagger Test Link** - -[**https://api.iamport.kr/#!/receipts/issueExternalReceipt**](https://api.iamport.kr/#!/receipts/issueExternalReceipt) + **Swagger Test Link** + [**https://api.iamport.kr/#!/receipts/issueExternalReceipt**](https://api.iamport.kr/#!/receipts/issueExternalReceipt) diff --git a/src/content/docs/ko/api/cash-receipt-api/revoke-cash-receipt-api.mdx b/src/content/docs/ko/api/cash-receipt-api/revoke-cash-receipt-api.mdx index cb4ae6567..01769acf7 100644 --- a/src/content/docs/ko/api/cash-receipt-api/revoke-cash-receipt-api.mdx +++ b/src/content/docs/ko/api/cash-receipt-api/revoke-cash-receipt-api.mdx @@ -4,27 +4,27 @@ description: 포트원을 통해 발급한 현금영수증 발급거래를 취 --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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"; -### 포트원을 통해 발급한 현금영수증 거래를 취소할 수 있습니다. +## 포트원을 통해 발급한 현금영수증 거래를 취소할 수 있습니다.

지원되는 PG사 확인하기

- **KG 이니시스** - **NHN KCP** -- **핵토파이낸셜(구 세틀뱅크)** -- **NICE Payments** -- **키움페이(구 다우, 페이조아)** -- **토스페이먼츠 - 신모듈** +- **핵토파이낸셜** +- **나이스페이먼츠(구모듈)** +- **키움페이** +- **토스페이먼츠(신모듈)** - **KSNET** -- **스마트로 - 신모듈** +- **스마트로(신모듈)** - **웰컴페이먼츠**
@@ -121,7 +121,7 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 ```javascript { - // Response + // Response } ``` @@ -130,7 +130,7 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 ```javascript { - // Response + // Response } ``` @@ -139,7 +139,7 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 ```javascript { - // Response + // Response } ``` @@ -148,7 +148,7 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 ```javascript { - // Response + // Response } ``` diff --git a/src/content/docs/ko/api/cash-receipt-api/revoke-external-cash-receipt-api.mdx b/src/content/docs/ko/api/cash-receipt-api/revoke-external-cash-receipt-api.mdx index 60d72dd0d..821568885 100644 --- a/src/content/docs/ko/api/cash-receipt-api/revoke-external-cash-receipt-api.mdx +++ b/src/content/docs/ko/api/cash-receipt-api/revoke-external-cash-receipt-api.mdx @@ -4,190 +4,178 @@ description: 포트원과 별개로 거래된 일반 현금결제에 대해서 --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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"; -### 포트원 별개거래로 발생된 현금영수증 거래를 취소합니다. +## 포트원 별개거래로 발생된 현금영수증 거래를 취소합니다.
-

지원되는 PG사 확인하기

- -- **KG 이니시스** -- **NHN KCP** -- **헥토파이낸셜 (세틀뱅크)** -- **(구) 나이스페이먼츠** -- **KICC** -- **(신) 스마트로** -- **(신) 나이스페이먼츠** -- **웰컴페이먼츠** - +

지원되는 PG사 확인하기

+ + - **KG 이니시스** + - **NHN KCP** + - **헥토파이낸셜** + - **나이스페이먼츠(구모듈/신모듈)** + - **이지페이(KICC)** + - **스마트로(신모듈)** + - **나이스페이먼츠(신모듈)** + - **웰컴페이먼츠**
- -포트원과 별개로 거래된 일반 현금결제에 대해 포트원 내에 설정된 PG사로 포트원 API를 이용해 현금영수증을 발행취소하는 API입니다. - -**merchant_uid** - -는 현금결제를 구분할 고유주문번호를 의미하며 발행에 사용된 값을 전달하면 됩니다. - - + + 포트원과 별개로 거래된 일반 현금결제에 대해 포트원 내에 설정된 PG사로 포트원 API를 이용해 현금영수증을 발행취소하는 API입니다. -### Parameters + **merchant\_uid** -#### Path + 는 현금결제를 구분할 고유주문번호를 의미하며 발행에 사용된 값을 전달하면 됩니다. + - -**고객사 주문번호** + ### Parameters -발급취소대상 고객사 주문번호 + #### Path - + + **고객사 주문번호** -### Responses + 발급취소대상 고객사 주문번호 + - - - -**`code`** **\*** **integer** + ### Responses -**응답코드** + + + + **`code`** **\*** **integer** -0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 + **응답코드** -**`message`** **\*** **string** + 0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 -**응답메세지** + **`message`** **\*** **string** -code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 + **응답메세지** -**`response`** **`(ExternalReceiptAnnotation, optional)`** + code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 - - + **`response`** **`(ExternalReceiptAnnotation, optional)`** + + - - -**`merchant_uid`** **\*** **`string`** + + + **`merchant_uid`** **\*** **`string`** -**`고객사 고유주문번호`** + **`고객사 고유주문번호`** -**`receipt_tid`** **`string`** + **`receipt_tid`** **`string`** -**`현금영수증 PG사 발행고유번호`** + **`현금영수증 PG사 발행고유번호`** -**`apply_num`** **\*** **`string`** + **`apply_num`** **\*** **`string`** -**`현금영수증 국세청 발행번호`** + **`현금영수증 국세청 발행번호`** -**`type`** **\*** **`string`** + **`type`** **\*** **`string`** -**`현금영수증 발행대상 타입`** + **`현금영수증 발행대상 타입`** -- 개인 : `person` -- 사업자 : `company` + - 개인 : `person` + - 사업자 : `company` -**`amount`** **\*** **`integer`** + **`amount`** **\*** **`integer`** -**`현금영수증 발행금액`** + **`현금영수증 발행금액`** -**`vat`** **\*** **`integer`** + **`vat`** **\*** **`integer`** -**`현금영수증 발행금액 중 부가세금액`** + **`현금영수증 발행금액 중 부가세금액`** -**`receipt_url`** **`string`** + **`receipt_url`** **`string`** -**`발행된 현금영수증 URL`** + **`발행된 현금영수증 URL`** -**`applied_at`** **\*** **`integer`** + **`applied_at`** **\*** **`integer`** -**현금영수증 발행시각** `UNIX TIMESTAMP` + **현금영수증 발행시각** `UNIX TIMESTAMP` -**`cancelled_at`** **`integer`** + **`cancelled_at`** **`integer`** -**`현금영수증 발행취소시각`** `UNIX TIMESTAMP` + **`현금영수증 발행취소시각`** `UNIX TIMESTAMP` + + + - - + + ```javascript + { + // Response + } + ``` + - + + ```javascript + { + // Response + } + ``` + - -```javascript -{ - // Response -} -``` + + ```javascript + { + // Response + } + ``` + - + + ```javascript + { + // Response + } + ``` + - -```javascript -{ - // Response -} -``` - - - - -```javascript -{ - // Response -} -``` - - - - -```javascript -{ - // Response -} -``` - - - - -```javascript -{ - // Response -} -``` - - + + ```javascript + { + // Response + } + ``` +
-

Response Model Schema

- -``` -{ - "code": 0, - "message": "string", - "response": { - "merchant_uid": "string", - "receipt_tid": "string", - "apply_num": "string", - "type": "person", - "amount": 0, - "vat": 0, - "receipt_url": "string", - "applied_at": 0, - "cancelled_at": 0 +

Response Model Schema

+ + ```json + { + "code": 0, + "message": "string", + "response": { + "merchant_uid": "string", + "receipt_tid": "string", + "apply_num": "string", + "type": "person", + "amount": 0, + "vat": 0, + "receipt_url": "string", + "applied_at": 0, + "cancelled_at": 0 + } } -} -``` - + ```
-**Swagger Test Link** + **Swagger Test Link** -[**https://api.iamport.kr/#!/receipts/revokeExternalReceipt**](https://api.iamport.kr/#!/receipts/revokeExternalReceipt) + [**https://api.iamport.kr/#!/receipts/revokeExternalReceipt**](https://api.iamport.kr/#!/receipts/revokeExternalReceipt) diff --git a/src/content/docs/ko/api/identity-verification-api/confirm-otp-api.mdx b/src/content/docs/ko/api/identity-verification-api/confirm-otp-api.mdx index 4c44c41db..5629b3aba 100644 --- a/src/content/docs/ko/api/identity-verification-api/confirm-otp-api.mdx +++ b/src/content/docs/ko/api/identity-verification-api/confirm-otp-api.mdx @@ -4,15 +4,15 @@ description: 본인인증을 완료하는 API 입니다. --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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)와 SMS 인증번호를 이용하여 본인인증을 완료합니다. +## 포트원 거래고유번호(imp_uid)와 SMS 인증번호를 이용하여 본인인증을 완료합니다. @@ -176,7 +176,7 @@ ISO8601 형식의 문자열. YYYY-MM-DD 10자리 ```javascript { - // Response + // Response } ``` @@ -185,7 +185,7 @@ ISO8601 형식의 문자열. YYYY-MM-DD 10자리 ```javascript { - // Response + // Response } ``` @@ -194,7 +194,7 @@ ISO8601 형식의 문자열. YYYY-MM-DD 10자리 ```javascript { - // Response + // Response } ``` @@ -203,7 +203,7 @@ ISO8601 형식의 문자열. YYYY-MM-DD 10자리 ```javascript { - // Response + // Response } ``` diff --git a/src/content/docs/ko/api/identity-verification-api/delete-certification-api.mdx b/src/content/docs/ko/api/identity-verification-api/delete-certification-api.mdx index c9ac6d9a7..415697f94 100644 --- a/src/content/docs/ko/api/identity-verification-api/delete-certification-api.mdx +++ b/src/content/docs/ko/api/identity-verification-api/delete-certification-api.mdx @@ -12,7 +12,7 @@ import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.astro" import Tabs from "~/components/gitbook/tabs/Tabs.astro"; import Tab from "~/components/gitbook/tabs/Tab.astro"; -### 본인인증결과 정보를 포트원 서버내에서 완전히 삭제 합니다. +## 본인인증결과 정보를 포트원 서버내에서 완전히 삭제 합니다. diff --git a/src/content/docs/ko/api/identity-verification-api/get-certification-api.mdx b/src/content/docs/ko/api/identity-verification-api/get-certification-api.mdx index 0f7a2c9fe..7c0ffb6d0 100644 --- a/src/content/docs/ko/api/identity-verification-api/get-certification-api.mdx +++ b/src/content/docs/ko/api/identity-verification-api/get-certification-api.mdx @@ -4,15 +4,15 @@ description: 본인인증 결과를 조회합니다. --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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"; -### 본인인증된 결과를 조회할 때 사용합니다. +## 본인인증된 결과를 조회할 때 사용합니다. @@ -160,7 +160,7 @@ ISO8601 형식의 문자열. YYYY-MM-DD 10자리 ```javascript { - // Response + // Response } ``` @@ -169,7 +169,7 @@ ISO8601 형식의 문자열. YYYY-MM-DD 10자리 ```javascript { - // Response + // Response } ``` diff --git a/src/content/docs/ko/api/identity-verification-api/request-otp-api.mdx b/src/content/docs/ko/api/identity-verification-api/request-otp-api.mdx index bc6f4860a..671ba9da4 100644 --- a/src/content/docs/ko/api/identity-verification-api/request-otp-api.mdx +++ b/src/content/docs/ko/api/identity-verification-api/request-otp-api.mdx @@ -4,152 +4,140 @@ description: API를 이용하여 본인인증 프로세스를 시작합니다. --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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"; -### 사용자 개인정보를 입력하여 SMS OTP번호 발송 API 입니다. +## 사용자 개인정보를 입력하여 SMS OTP번호 발송 API 입니다. - -사용자 개인정보를 API로 전달하여 통신사로부터 확인되는 경우 OTP(6자리 인증번호)를 사용자에게 SMS로 전달합니다. 통신사 승인을 받은 일부 고객사에 한해 사용하실 수 있으며 현재 **다날**을 통해서만 서비스되고 있습니다. - -본인인증 대상자의 성명, 생년월일 + 주민등록 뒷부분 첫 자리, 휴대폰번호, 통신사 정보를 고객사에서 직접 입력받아 API를 요청하면 됩니다. 전달된 개인정보가 올바른 경우 해당 휴대폰으로 인증번호 SMS가 전송됩니다. - -HTTP Status 200응답 시 imp_uid 가 응답데이터로 전달되며 SMS전송된 인증번호를 본인인증 완료 API로 요청주시면 최종 본인인증 프로세스가 완료됩니다. - - - -### Parameters - -#### Body + + 사용자 개인정보를 API로 전달하여 통신사로부터 확인되는 경우 OTP(6자리 인증번호)를 사용자에게 SMS로 전달합니다. 통신사 승인을 받은 일부 고객사에 한해 사용하실 수 있으며 현재 **다날**을 통해서만 서비스되고 있습니다. - - + 본인인증 대상자의 성명, 생년월일 + 주민등록 뒷부분 첫 자리, 휴대폰번호, 통신사 정보를 고객사에서 직접 입력받아 API를 요청하면 됩니다. 전달된 개인정보가 올바른 경우 해당 휴대폰으로 인증번호 SMS가 전송됩니다. -**본인인증 대상자 성명** + HTTP Status 200응답 시 imp\_uid 가 응답데이터로 전달되며 SMS전송된 인증번호를 본인인증 완료 API로 요청주시면 최종 본인인증 프로세스가 완료됩니다. + - + ### Parameters - - - **휴대폰번호** + #### Body -특수기호가 삽입되어도 무방합니다. + + + **본인인증 대상자 성명** + + -(포트원 내에서 숫자 외에는 정규식으로 모두 제거처리) + + **휴대폰번호** - - -**생년월일** + 특수기호가 삽입되어도 무방합니다. -**`YYMMDD 6자리`** + (포트원 내에서 숫자 외에는 정규식으로 모두 제거처리) + -특수기호가 삽입되어도 무방합니다. + + **생년월일** -(포트원 내에서 숫자 외에는 정규식으로 모두 제거처리) + **`YYMMDD 6자리`** - - -**성별구분코드** + 특수기호가 삽입되어도 무방합니다. -주민번호 뒷부분 첫자리 + (포트원 내에서 숫자 외에는 정규식으로 모두 제거처리) + -(주민등록번호 13자리 중 7번째 자리. 2000년 이전 출생자는 1 또는 2, 2000년 이후 출생자는 3 또는 4) + + **성별구분코드** - - -**통신사구분코드** + 주민번호 뒷부분 첫자리 -**`SKT`** + (주민등록번호 13자리 중 7번째 자리. 2000년 이전 출생자는 1 또는 2, 2000년 이후 출생자는 3 또는 4) + -**`KT`** + + **통신사구분코드** -**`LGT`** + **`SKT`** - - -**알뜰폰 사용 여부** + **`KT`** - - -**고객사 서비스명칭** + **`LGT`** + + + **알뜰폰 사용 여부** + - - -**고객사 주문번호** + + **고객사 서비스명칭** + - - -**PG사 구분코드** + + **고객사 주문번호** + - + + **PG사 구분코드** + -### Responses + ### Responses - - - -**`code`** **\*** **integer** + + + + **`code`** **\*** **integer** -**응답코드** + **응답코드** -0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 + 0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 -**`message`** **\*** **string** + **`message`** **\*** **string** -**응답메세지** + **응답메세지** -code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 + code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 -**response ** **(CertificationOTPAnnotation, optional)** + \*\*response \*\* **(CertificationOTPAnnotation, optional)** + + - - + + + **`imp_uid *`** **`string`** - - -**`imp_uid *`** **`string`** + **`포트원 인증고유번호`** + + + -**`포트원 인증고유번호`** + + ```javascript + { + // Response + } + ``` + - - - - - - -```javascript -{ - // Response -} -``` - - - - -```javascript -{ - // Response -} -``` - - - - -```javascript -{ - // Response -} -``` - - + + ```javascript + { + // Response + } + ``` + + + ```javascript + { + // Response + } + ``` + ### **주요 요청 파라미터 상세 설명** @@ -185,22 +173,21 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 > **danal.\{상점아이디}** 형태로 지정
-

Response Model Schema

- -```json -{ - "code": 0, - "message": "string", - "response": { - "imp_uid": "string" +

Response Model Schema

+ + ```json + { + "code": 0, + "message": "string", + "response": { + "imp_uid": "string" + } } -} -``` - + ```
-**Swagger Test Link** + **Swagger Test Link** -[**https://api.iamport.kr/#!/certifications/requestOTP**](https://api.iamport.kr/#!/certifications/requestOTP) + [**https://api.iamport.kr/#!/certifications/requestOTP**](https://api.iamport.kr/#!/certifications/requestOTP) diff --git a/src/content/docs/ko/api/miscellaneous-api/benepia/pay-benepia-point-api.mdx b/src/content/docs/ko/api/miscellaneous-api/benepia/pay-benepia-point-api.mdx index 236375e0f..4fa0533ea 100644 --- a/src/content/docs/ko/api/miscellaneous-api/benepia/pay-benepia-point-api.mdx +++ b/src/content/docs/ko/api/miscellaneous-api/benepia/pay-benepia-point-api.mdx @@ -4,494 +4,475 @@ description: API를 통해 베네피아 포인트(복지포인트)사용 결제 --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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"; -### 베네피아 포인트를 이용하여 결제를 요청합니다. +## 베네피아 포인트를 이용하여 결제를 요청합니다. - -사용자로부터 전달받은 베네피아 계정 아이디, 비밀번호와 함께 결제정보를 요청하여 베네피아 포인트 사용처리합니다. - -**KCP를 통해서만 진행** - -되므로 KCP사이트코드 발급이 필요합니다. - - - -### Parameters - -#### Body - - - - -**베네피아 계정 아이디** - - + + 사용자로부터 전달받은 베네피아 계정 아이디, 비밀번호와 함께 결제정보를 요청하여 베네피아 포인트 사용처리합니다. - - - + **KCP를 통해서만 진행** -**베네피아 계정 비밀번호** + 되므로 KCP사이트코드 발급이 필요합니다. + - + ### Parameters - - - + #### Body -**고객사 주문번호** + + + **베네피아 계정 아이디** + + - + + + **베네피아 계정 비밀번호** + + -이미 결제가 이뤄진 적이 있는 merchant_uid로는 결제요청이 불가능합니다. + + + **고객사 주문번호** + - - - + 이미 결제가 이뤄진 적이 있는 merchant\_uid로는 결제요청이 불가능합니다. + -**결제요청금액** + + + **결제요청금액** + + - + + + **주문명** + + - - - + + **주문자명** + -**주문명** + + **주문자 Email 주소** + - + + **주문자 전화번호** + - - -**주문자명** + + **주문자 주소** + - - -**주문자 Email 주소** + + **주문자 우편번호** + - - -**주문자 전화번호** + + **PG구분코드** - - -**주문자 주소** + KCP PG설정이 2개 이상인 경우, 결제가 진행되길 원하는 KCP사이트코드를 지정하실 수 있습니다. - - -**주문자 우편번호** + pg 파라메터는 `kcp.{KCP사이트코드}` 형식의 문자열입니다. + pg 파라메터가 누락되는 경우 PG설정 내 KCP설정을 자동 탐색하여 처리하게 됩니다. + - - -**PG구분코드** + + **Notification URL(Webhook URL)** -KCP PG설정이 2개 이상인 경우, 결제가 진행되길 원하는 KCP사이트코드를 지정하실 수 있습니다. + 선언되지 않으면 포트원 관리자 페이지에 정의된 Notification URL값을 사용합니다 + -pg 파라메터는 `kcp.{KCP사이트코드}` 형식의 문자열입니다. -pg 파라메터가 누락되는 경우 PG설정 내 KCP설정을 자동 탐색하여 처리하게 됩니다. + + **결제정보와 함께 저장할 추가정보** - - -**Notification URL(Webhook URL)** + 객체로 전달되는 경우 JSON 문자열로 저장 + -선언되지 않으면 포트원 관리자 페이지에 정의된 Notification URL값을 사용합니다 - - -**결제정보와 함께 저장할 추가정보** + ### Responses -객체로 전달되는 경우 JSON 문자열로 저장 - + + + + **`code`** **\*** **integer** -### Responses + **응답코드** - - - -**`code`** **\*** **integer** + 0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 -**응답코드** + **`message`** **\*** **string** -0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 + **응답메세지** -**`message`** **\*** **string** + code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 -**응답메세지** + **`response`** **`(PaymentAnnotation, optional)`** + + -code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 + + + **`code`** **\*** **integer** -**`response`** **`(PaymentAnnotation, optional)`** + **응답코드** - - + 0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 - - -**`code`** **\*** **integer** + **`message`** **\*** **string** -**응답코드** + **응답메세지** -0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 + code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 -**`message`** **\*** **string** + **`imp_uid`** **\*** **string** -**응답메세지** + **포트원 거래고유번호** -code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 + **`merchant_uid`** **\*** **string** -**`imp_uid`** **\*** **string** + **고객사 주문번호** -**포트원 거래고유번호** + **`pay_method`** **\*** **string** -**`merchant_uid`** **\*** **string** + **결제수단 구분코드** -**고객사 주문번호** + - samsung : 삼성페이 + - card : 신용카드 + - trans : 계좌이체 + - vbank : 가상계좌 + - phone : 휴대폰 + - cultureland : 문화상품권 + - smartculture : 스마트문상 + - booknlife : 도서문화상품권 + - happymoney : 해피머니 + - point : 포인트 + - ssgpay : SSGPAY + - lpay : LPAY + - payco : 페이코 + - kakaopay : 카카오페이 + - tosspay : 토스 + - naverpay : 네이버페이 -**`pay_method`** **\*** **string** + **`channel`** **\*** **string** -**결제수단 구분코드** + **결제환경 구분코드** -- samsung : 삼성페이 -- card : 신용카드 -- trans : 계좌이체 -- vbank : 가상계좌 -- phone : 휴대폰 -- cultureland : 문화상품권 -- smartculture : 스마트문상 -- booknlife : 도서문화상품권 -- happymoney : 해피머니 -- point : 포인트 -- ssgpay : SSGPAY -- lpay : LPAY -- payco : 페이코 -- kakaopay : 카카오페이 -- tosspay : 토스 -- naverpay : 네이버페이 + - pc:(인증방식)PC결제 + - mobile:(인증방식)모바일결제 + - api:정기결제 또는 비인증 결제 -**`channel`** **\*** **string** + **`pg_provider`** **\*** **string** -**결제환경 구분코드** + **PG사 구분코드** -- pc:(인증방식)PC결제 -- mobile:(인증방식)모바일결제 -- api:정기결제 또는 비인증 결제 + **`emb_pg_provider`** **\*** **string** -**`pg_provider`** **\*** **string** + **허브형결제 PG사 구분코드** -**PG사 구분코드** + **`pg_tid`** **\*** **string** -**`emb_pg_provider`** **\*** **string** + **pg사 거래번호** -**허브형결제 PG사 구분코드** + **`pg_id`** **\*** **string** -**`pg_tid`** **\*** **string** + **PG사 MID** -**pg사 거래번호** + **`escrow`** **boolean** -**`pg_id`** **\*** **string** + **에스크로 결제여부** -**PG사 MID** + **`apply_num`** **string** -**`escrow`** **boolean** + **신용카드 승인번호** -**에스크로 결제여부** + **`bank_code`** **string** -**`apply_num`** **string** + **은행 표준코드** (금융결제원 표준코드: [**`(링크보기)`**](../../tip/pg-1) -**신용카드 승인번호** + **`bank_name`** **string** -**`bank_code`** **string** + **은행 명칭** -**은행 표준코드** (금융결제원 표준코드: [**`(링크보기)`**](../../tip/pg-1) + 실시간 계좌이체 결제건의 경우 -**`bank_name`** **string** + **`card_code`** **string** -**은행 명칭** + **카드사 코드번호(금융결제원 표준코드번호 :** [**링크**](https://chaifinance.notion.site/53589280bbc94fab938d93257d452216?v=eb405baf52134b3f90d438e3bf763630) ) -실시간 계좌이체 결제건의 경우 + **`card_name`** **string** -**`card_code`** **string** + **카드사명** -**카드사 코드번호(금융결제원 표준코드번호 :** [**링크**](https://chaifinance.notion.site/53589280bbc94fab938d93257d452216?v=eb405baf52134b3f90d438e3bf763630) ) + **`card_quota`** **integer** -**`card_name`** **string** + **할부개월 수(0이면 일시불)** -**카드사명** + **`card_number`** **string** -**`card_quota`** **integer** + **결제에 사용된 마스킹된 카드번호** -**할부개월 수(0이면 일시불)** + 7\~12번째 자리를 마스킹하는 것이 일반적이지만, PG사의 정책/설정에 따라 다소 차이가 있을 수 있습니다. -**`card_number`** **string** + **`card_type`** **string** -**결제에 사용된 마스킹된 카드번호** + **카드 구분코드** -7~12번째 자리를 마스킹하는 것이 일반적이지만, PG사의 정책/설정에 따라 다소 차이가 있을 수 있습니다. + (주의)해당 정보를 제공하지 않는 일부 PG사의 경우 null 로 응답됨(ex. JTNet, 이니시스-빌링) -**`card_type`** **string** + - 0 : 신용카드 + - 1 : 체크카드 -**카드 구분코드** + **`vbank_code`** **string** -(주의)해당 정보를 제공하지 않는 일부 PG사의 경우 null 로 응답됨(ex. JTNet, 이니시스-빌링) + **가상계좌 은행 표준코드(금융결제원 기준)** -- 0 : 신용카드 -- 1 : 체크카드 + **`vbank_name`** **string** -**`vbank_code`** **string** + **입금받을 가상계좌 은행명** -**가상계좌 은행 표준코드(금융결제원 기준)** + **`vbank_holder`** **string** -**`vbank_name`** **string** + **입금받을 가상계좌 예금주** -**입금받을 가상계좌 은행명** + **`vbank_date`** **string** -**`vbank_holder`** **string** + **입금받을 가상계좌 마감기한 (UNIX timestamp)** -**입금받을 가상계좌 예금주** + **`vbank_issued_at`** **string** -**`vbank_date`** **string** + **가상계좌 생성 시각 (UNIX timestamp)** -**입금받을 가상계좌 마감기한 (UNIX timestamp)** + **`name`** **string** -**`vbank_issued_at`** **string** + **제품명** -**가상계좌 생성 시각 (UNIX timestamp)** + **`amount`** **\*** **integer** -**`name`** **string** + **주문(결제)금액** -**제품명** + **`cancel_amount`** **integer** -**`amount`** **\*** **integer** + **결제취소금액** -**주문(결제)금액** + **`currency`** **string** -**`cancel_amount`** **integer** + **통화구분코드** -**결제취소금액** + **`buyer_name`** **string** -**`currency`** **string** + **주문자명** -**통화구분코드** + **`buyer_email`** **string** -**`buyer_name`** **string** + **주문자 Email주소** -**주문자명** + **`buyer_tel`** **string** -**`buyer_email`** **string** + **주문자 전화번호** -**주문자 Email주소** + **`buyer_addr`** **string** -**`buyer_tel`** **string** + **주문자 주소** -**주문자 전화번호** + **`buyer_postcode`** **string** -**`buyer_addr`** **string** + **주문자 우편번호** -**주문자 주소** + **`custom_data`** **string** -**`buyer_postcode`** **string** + **고객사 custom 데이터** JSON string으로 전달 -**주문자 우편번호** + **`user_agent`** **string** -**`custom_data`** **string** + **UserAgent** 구매자가 결제를 시작한 단말기의 UserAgent 문자열 -**고객사 custom 데이터** JSON string으로 전달 + **`status`** **\*** **string** -**`user_agent`** **string** + **결제상태 구분코드** -**UserAgent** 구매자가 결제를 시작한 단말기의 UserAgent 문자열 + - ready : 미결제 + - paid : 결제완료 + - cancelled : 결제취소 + - failed : 결제실패 -**`status`** **\*** **string** + **`started_at`** **\*** **string** -**결제상태 구분코드** + **결제시작시점 (UNIX timestamp)** -- ready : 미결제 -- paid : 결제완료 -- cancelled : 결제취소 -- failed : 결제실패 + **`paid_at`** **\*** **string** -**`started_at`** **\*** **string** + **결제완료시점 (UNIX timestamp)**\\ -**결제시작시점 (UNIX timestamp)** + **`failed_at`** **\*** **string** -**`paid_at`** **\*** **string** + **결제실패시점 (UNIX timestamp)** -**결제완료시점 (UNIX timestamp)**\\ + **`cancelled_at`** **\*** **string** -**`failed_at`** **\*** **string** + **결제취소시점 (UNIX timestamp)** -**결제실패시점 (UNIX timestamp)** + **`fail_reason`** **string** -**`cancelled_at`** **\*** **string** + **결제실패 사유** -**결제취소시점 (UNIX timestamp)** + **`cancel_reason`** **string** -**`fail_reason`** **string** + **결제취소 사유** -**결제실패 사유** + **`receipt_url`** **string** -**`cancel_reason`** **string** + **신용카드 매출전표 확인 URL** -**결제취소 사유** + **`cash_receipt_issued`** **boolean** -**`receipt_url`** **string** + **현금영수증 자동발급 여부** -**신용카드 매출전표 확인 URL** + **`customer_uid`** **string** -**`cash_receipt_issued`** **boolean** + **해당 결제처리에 사용된 customer\_uid** -**현금영수증 자동발급 여부** + **`customer_uid_usage`** **string** -**`customer_uid`** **string** + **customer\_uid 사용 구분코드** -**해당 결제처리에 사용된 customer_uid** + - null : 일반결제 + - issue : 빌링키 발급 + - payment : 결제 + - payment.scheduled : 예약결제 -**`customer_uid_usage`** **string** + **`cancel_history`** **(Array\[PaymentCancelAnnotation], optional):** -**customer_uid 사용 구분코드** + **취소/부분취소 내역** + + -- null : 일반결제 -- issue : 빌링키 발급 -- payment : 결제 -- payment.scheduled : 예약결제 + + + **cancel\_history array \[]** -**`cancel_history`** **(Array\[PaymentCancelAnnotation], optional):** + **`pg_tid`** **\*** **string** -**취소/부분취소 내역** + **PG사 승인취소번호** - - + **`amount`** **\*** **integer** - - -**cancel\_history array \[]** + **취소 금액** -**`pg_tid`** **\*** **string** + **`cancelled_at`** **\*** **string** -**PG사 승인취소번호** + **결제취소된 시각 UNIX timestamp** -**`amount`** **\*** **integer** + **`reason`** **\*** **string** -**취소 금액** + **결제취소 사유** -**`cancelled_at`** **\*** **string** + **`receipt_url`** **\*** **string** -**결제취소된 시각 UNIX timestamp** + **취소에 대한 매출전표 확인 URL. PG사에 따라 제공되지 않는 경우도 있음** + + + -**`reason`** **\*** **string** - -**결제취소 사유** - -**`receipt_url`** **\*** **string** - -**취소에 대한 매출전표 확인 URL. PG사에 따라 제공되지 않는 경우도 있음** - - - - - - - -```javascript -{ - // Response -} -``` - - - - -```javascript -{ - // Response -} -``` - - + + ```javascript + { + // Response + } + ``` + + + ```javascript + { + // Response + } + ``` +
-

Response Model Schema

- -``` -{ - "code": 0, - "message": "string", - "response": { - "imp_uid": "string", - "merchant_uid": "string", - "pay_method": "string", - "channel": "pc", - "pg_provider": "string", - "emb_pg_provider": "string", - "pg_tid": "string", - "pg_id": "string", - "escrow": true, - "apply_num": "string", - "bank_code": "string", - "bank_name": "string", - "card_code": "string", - "card_name": "string", - "card_quota": 0, - "card_number": "string", - "card_type": "null", - "vbank_code": "string", - "vbank_name": "string", - "vbank_num": "string", - "vbank_holder": "string", - "vbank_date": 0, - "vbank_issued_at": 0, - "name": "string", - "amount": 0, - "cancel_amount": 0, - "currency": "string", - "buyer_name": "string", - "buyer_email": "string", - "buyer_tel": "string", - "buyer_addr": "string", - "buyer_postcode": "string", - "custom_data": "string", - "user_agent": "string", - "status": "ready", - "started_at": 0, - "paid_at": 0, - "failed_at": 0, - "cancelled_at": 0, - "fail_reason": "string", - "cancel_reason": "string", - "receipt_url": "string", - "cancel_history": [ - { - "pg_tid": "string", - "amount": 0, - "cancelled_at": 0, - "reason": "string", - "receipt_url": "string" - } - ], - "cancel_receipt_urls": [ - "string" - ], - "cash_receipt_issued": true, - "customer_uid": "string", - "customer_uid_usage": "issue" +

Response Model Schema

+ + ```json + { + "code": 0, + "message": "string", + "response": { + "imp_uid": "string", + "merchant_uid": "string", + "pay_method": "string", + "channel": "pc", + "pg_provider": "string", + "emb_pg_provider": "string", + "pg_tid": "string", + "pg_id": "string", + "escrow": true, + "apply_num": "string", + "bank_code": "string", + "bank_name": "string", + "card_code": "string", + "card_name": "string", + "card_quota": 0, + "card_number": "string", + "card_type": "null", + "vbank_code": "string", + "vbank_name": "string", + "vbank_num": "string", + "vbank_holder": "string", + "vbank_date": 0, + "vbank_issued_at": 0, + "name": "string", + "amount": 0, + "cancel_amount": 0, + "currency": "string", + "buyer_name": "string", + "buyer_email": "string", + "buyer_tel": "string", + "buyer_addr": "string", + "buyer_postcode": "string", + "custom_data": "string", + "user_agent": "string", + "status": "ready", + "started_at": 0, + "paid_at": 0, + "failed_at": 0, + "cancelled_at": 0, + "fail_reason": "string", + "cancel_reason": "string", + "receipt_url": "string", + "cancel_history": [ + { + "pg_tid": "string", + "amount": 0, + "cancelled_at": 0, + "reason": "string", + "receipt_url": "string" + } + ], + "cancel_receipt_urls": [ + "string" + ], + "cash_receipt_issued": true, + "customer_uid": "string", + "customer_uid_usage": "issue" + } } -} -``` - + ```
-**Swagger Test Link** - -[**https://api.iamport.kr/#!/benepia/payBenepiaPoint**](https://api.iamport.kr/#!/benepia/payBenepiaPoint) + **Swagger Test Link** + [**https://api.iamport.kr/#!/benepia/payBenepiaPoint**](https://api.iamport.kr/#!/benepia/payBenepiaPoint) diff --git a/src/content/docs/ko/api/miscellaneous-api/cvs/issue-cvs-payment-api.mdx b/src/content/docs/ko/api/miscellaneous-api/cvs/issue-cvs-payment-api.mdx index ee3015b03..924b1f9a8 100644 --- a/src/content/docs/ko/api/miscellaneous-api/cvs/issue-cvs-payment-api.mdx +++ b/src/content/docs/ko/api/miscellaneous-api/cvs/issue-cvs-payment-api.mdx @@ -4,395 +4,384 @@ description: 편의점 결제를 위한 수납번호를 발급합니다. --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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"; -### 편의점결제 수납번호(barcode)를 발급 또는 등록합니다. +## 편의점결제 수납번호(barcode)를 발급 또는 등록합니다. - -편의점결제를 위한 수납번호(barcode)를 사전 발급 또는 등록합니다. 고객은 발급 또는 등록된 수납번호(barcode)에 해당되는 바코드 이미지 또는 수납번호를 편의점 방문시 제시함으로써 현장 결제가 이뤄지게 됩니다. - - - -### Parameters - -#### Body - - - - -**주문번호** + + 편의점결제를 위한 수납번호(barcode)를 사전 발급 또는 등록합니다. 고객은 발급 또는 등록된 수납번호(barcode)에 해당되는 바코드 이미지 또는 수납번호를 편의점 방문시 제시함으로써 현장 결제가 이뤄지게 됩니다. + - + ### Parameters -이미 결제가 이뤄진 적이 있는 merchant_uid로는 추가적인 편의점결제 수납번호(barcode) 발급 또는 등록이 불가능합니다. + #### Body - - - + + + **주문번호** + -**결제금액** + 이미 결제가 이뤄진 적이 있는 merchant\_uid로는 추가적인 편의점결제 수납번호(barcode) 발급 또는 등록이 불가능합니다. + - + + + **결제금액** + + - - -**바코드** + + **바코드** + - - -**편의점 수납가능한 결제기한** + + **편의점 수납가능한 결제기한** -Unix Timestamp + Unix Timestamp + - - -**제품명** + + **제품명** + - - -**주문자명** + + **주문자명** + - - -**주문자 E-mail주소** + + **주문자 E-mail주소** + - - -**주문자 전화번호** + + **주문자 전화번호** + - - -**주문자 주소** + + **주문자 주소** + - - -**주문자 우편번호** + + **주문자 우편번호** + - - -**PG구분코드** + + **PG구분코드** + - - -**수납가능여부 체크 URL** + + **수납가능여부 체크 URL** + - - -**편의점결제 수납성공 시 통지받을 URL** + + **편의점결제 수납성공 시 통지받을 URL** -선언되지 않으면 포트원 관리자 페이지에 정의된 Notification URL값을 사용 + 선언되지 않으면 포트원 관리자 페이지에 정의된 Notification URL값을 사용 + - - -**결제정보와 함께 저장할 custom_data** + + **결제정보와 함께 저장할 custom\_data** -객체로 전달되는 경우 JSON 문자열로 저장 - + 객체로 전달되는 경우 JSON 문자열로 저장 + -### Responses + ### Responses - - - -**`code`** **integer** + + + + **`code`** **integer** -**응답코드** + **응답코드** -0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 + 0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 -**`message`** **string** + **`message`** **string** -**응답메세지** + **응답메세지** -code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 + code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 -**`response`** **`(PaymentAnnotation, optional)`** + **`response`** **`(PaymentAnnotation, optional)`** + + - - + + + **`code`** **\*** **integer** - - -**`code`** **\*** **integer** + **응답코드** -**응답코드** + 0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 -0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 + **`message`** **\*** **string** -**`message`** **\*** **string** + **응답메세지** -**응답메세지** + code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 -code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 + **`imp_uid`** **\*** **string** -**`imp_uid`** **\*** **string** + **포트원 거래고유번호** -**포트원 거래고유번호** + **`merchant_uid`** **\*** **string** -**`merchant_uid`** **\*** **string** + **고객사 주문번호** -**고객사 주문번호** + **`pay_method`** **\*** **string** -**`pay_method`** **\*** **string** + **결제수단 구분코드** -**결제수단 구분코드** + - samsung : 삼성페이 + - card : 신용카드 + - trans : 계좌이체 + - vbank : 가상계좌 + - phone : 휴대폰 + - cultureland : 문화상품권 + - smartculture : 스마트문상 + - booknlife : 도서문화상품권 + - happymoney : 해피머니 + - point : 포인트 + - ssgpay : SSGPAY + - lpay : LPAY + - payco : 페이코 + - kakaopay : 카카오페이 + - tosspay : 토스 + - naverpay : 네이버페이 -- samsung : 삼성페이 -- card : 신용카드 -- trans : 계좌이체 -- vbank : 가상계좌 -- phone : 휴대폰 -- cultureland : 문화상품권 -- smartculture : 스마트문상 -- booknlife : 도서문화상품권 -- happymoney : 해피머니 -- point : 포인트 -- ssgpay : SSGPAY -- lpay : LPAY -- payco : 페이코 -- kakaopay : 카카오페이 -- tosspay : 토스 -- naverpay : 네이버페이 + **`channel`** **\*** **string** -**`channel`** **\*** **string** + **결제환경 구분코드** -**결제환경 구분코드** + - pc:(인증방식)PC결제 + - mobile:(인증방식)모바일결제 + - api:정기결제 또는 비인증 결제 -- pc:(인증방식)PC결제 -- mobile:(인증방식)모바일결제 -- api:정기결제 또는 비인증 결제 + **`pg_provider`** **\*** **string** -**`pg_provider`** **\*** **string** + **PG사 구분코드** -**PG사 구분코드** + **`emb_pg_provider`** **\*** **string** -**`emb_pg_provider`** **\*** **string** + **허브형결제 PG사 구분코드** -**허브형결제 PG사 구분코드** + **`pg_tid`** **\*** **string** -**`pg_tid`** **\*** **string** + **pg사 거래번호** -**pg사 거래번호** + **`pg_id`** **\*** **string** -**`pg_id`** **\*** **string** + **PG사 MID** -**PG사 MID** + **`escrow`** **boolean** -**`escrow`** **boolean** + **에스크로 결제여부** -**에스크로 결제여부** + **`apply_num`** **string** -**`apply_num`** **string** + **신용카드 승인번호** -**신용카드 승인번호** + **`bank_code`** **string** -**`bank_code`** **string** + **은행 표준코드** (금융결제원 표준코드: [**`(링크보기)`**](../../tip/pg-1) -**은행 표준코드** (금융결제원 표준코드: [**`(링크보기)`**](../../tip/pg-1) + **`bank_name`** **string** -**`bank_name`** **string** + **은행 명칭** -**은행 명칭** + 실시간 계좌이체 결제건의 경우 -실시간 계좌이체 결제건의 경우 + **`card_code`** **string** -**`card_code`** **string** + **카드사 코드번호(금융결제원 표준코드번호 :** [**링크**](https://chaifinance.notion.site/53589280bbc94fab938d93257d452216?v=eb405baf52134b3f90d438e3bf763630) ) -**카드사 코드번호(금융결제원 표준코드번호 :** [**링크**](https://chaifinance.notion.site/53589280bbc94fab938d93257d452216?v=eb405baf52134b3f90d438e3bf763630) ) + **`card_name`** **string** -**`card_name`** **string** + **카드사명** -**카드사명** + **`card_quota`** **integer** -**`card_quota`** **integer** + **할부개월 수(0이면 일시불)** -**할부개월 수(0이면 일시불)** + **`card_number`** **string** -**`card_number`** **string** + **결제에 사용된 마스킹된 카드번호** -**결제에 사용된 마스킹된 카드번호** + 7\~12번째 자리를 마스킹하는 것이 일반적이지만, PG사의 정책/설정에 따라 다소 차이가 있을 수 있습니다. -7~12번째 자리를 마스킹하는 것이 일반적이지만, PG사의 정책/설정에 따라 다소 차이가 있을 수 있습니다. + **`card_type`** **string** -**`card_type`** **string** + **카드 구분코드** -**카드 구분코드** + (주의)해당 정보를 제공하지 않는 일부 PG사의 경우 null 로 응답됨(ex. JTNet, 이니시스-빌링) -(주의)해당 정보를 제공하지 않는 일부 PG사의 경우 null 로 응답됨(ex. JTNet, 이니시스-빌링) + - 0 : 신용카드 + - 1 : 체크카드 -- 0 : 신용카드 -- 1 : 체크카드 + **`vbank_code`** **string** -**`vbank_code`** **string** + **가상계좌 은행 표준코드(금융결제원 기준)** -**가상계좌 은행 표준코드(금융결제원 기준)** + **`vbank_name`** **string** -**`vbank_name`** **string** + **입금받을 가상계좌 은행명** -**입금받을 가상계좌 은행명** + **`vbank_holder`** **string** -**`vbank_holder`** **string** + **입금받을 가상계좌 예금주** -**입금받을 가상계좌 예금주** + **`vbank_date`** **string** -**`vbank_date`** **string** + **입금받을 가상계좌 마감기한 (UNIX timestamp)** -**입금받을 가상계좌 마감기한 (UNIX timestamp)** + **`vbank_issued_at`** **string** -**`vbank_issued_at`** **string** + **가상계좌 생성 시각 (UNIX timestamp)** -**가상계좌 생성 시각 (UNIX timestamp)** + **`name`** **string** -**`name`** **string** + **제품명** -**제품명** + **`amount`** **\*** **integer** -**`amount`** **\*** **integer** + **주문(결제)금액** -**주문(결제)금액** + **`cancel_amount`** **integer** -**`cancel_amount`** **integer** + **결제취소금액** -**결제취소금액** + **`currency`** **string** -**`currency`** **string** + **통화구분코드** -**통화구분코드** + **`buyer_name`** **string** -**`buyer_name`** **string** + **주문자명** -**주문자명** + **`buyer_email`** **string** -**`buyer_email`** **string** + **주문자 Email주소** -**주문자 Email주소** + **`buyer_tel`** **string** -**`buyer_tel`** **string** + **주문자 전화번호** -**주문자 전화번호** + **`buyer_addr`** **string** -**`buyer_addr`** **string** + **주문자 주소** -**주문자 주소** + **`buyer_postcode`** **string** -**`buyer_postcode`** **string** + **주문자 우편번호** -**주문자 우편번호** + **`custom_data`** **string** -**`custom_data`** **string** + **고객사 custom 데이터** JSON string으로 전달 -**고객사 custom 데이터** JSON string으로 전달 + **`user_agent`** **string** -**`user_agent`** **string** + **UserAgent** 구매자가 결제를 시작한 단말기의 UserAgent 문자열 -**UserAgent** 구매자가 결제를 시작한 단말기의 UserAgent 문자열 + **`status`** **\*** **string** -**`status`** **\*** **string** + **결제상태 구분코드** -**결제상태 구분코드** + - ready : 미결제 + - paid : 결제완료 + - cancelled : 결제취소 + - failed : 결제실패 -- ready : 미결제 -- paid : 결제완료 -- cancelled : 결제취소 -- failed : 결제실패 + **`started_at`** **\*** **string** -**`started_at`** **\*** **string** + **결제시작시점 (UNIX timestamp)** -**결제시작시점 (UNIX timestamp)** + **`paid_at`** **\*** **string** -**`paid_at`** **\*** **string** + **결제완료시점 (UNIX timestamp)**\\ -**결제완료시점 (UNIX timestamp)**\\ + **`failed_at`** **\*** **string** -**`failed_at`** **\*** **string** + **결제실패시점 (UNIX timestamp)** -**결제실패시점 (UNIX timestamp)** + **`cancelled_at`** **\*** **string** -**`cancelled_at`** **\*** **string** + **결제취소시점 (UNIX timestamp)** -**결제취소시점 (UNIX timestamp)** + **`fail_reason`** **string** -**`fail_reason`** **string** + **결제실패 사유** -**결제실패 사유** + **`cancel_reason`** **string** -**`cancel_reason`** **string** + **결제취소 사유** -**결제취소 사유** + **`receipt_url`** **string** -**`receipt_url`** **string** + **신용카드 매출전표 확인 URL** -**신용카드 매출전표 확인 URL** + **`cash_receipt_issued`** **boolean** -**`cash_receipt_issued`** **boolean** + **현금영수증 자동발급 여부** -**현금영수증 자동발급 여부** + **`customer_uid`** **string** -**`customer_uid`** **string** + **해당 결제처리에 사용된 customer\_uid** -**해당 결제처리에 사용된 customer_uid** + **`customer_uid_usage`** **string** -**`customer_uid_usage`** **string** + **customer\_uid 사용 구분코드** -**customer_uid 사용 구분코드** + - null : 일반결제 + - issue : 빌링키 발급 + - payment : 결제 + - payment.scheduled : 예약결제 -- null : 일반결제 -- issue : 빌링키 발급 -- payment : 결제 -- payment.scheduled : 예약결제 + **`cancel_history`** **(Array\[PaymentCancelAnnotation], optional):** -**`cancel_history`** **(Array\[PaymentCancelAnnotation], optional):** + **취소/부분취소 내역** + + -**취소/부분취소 내역** + + + **cancel\_history array \[]** - - + **`pg_tid`** **\*** **string** - - -**cancel\_history array \[]** + **PG사 승인취소번호** -**`pg_tid`** **\*** **string** + **`amount`** **\*** **integer** -**PG사 승인취소번호** + **취소 금액** -**`amount`** **\*** **integer** + **`cancelled_at`** **\*** **string** -**취소 금액** + **결제취소된 시각 UNIX timestamp** -**`cancelled_at`** **\*** **string** + **`reason`** **\*** **string** -**결제취소된 시각 UNIX timestamp** + **결제취소 사유** -**`reason`** **\*** **string** + **`receipt_url`** **\*** **string** -**결제취소 사유** - -**`receipt_url`** **\*** **string** - -**취소에 대한 매출전표 확인 URL. PG사에 따라 제공되지 않는 경우도 있음** - - - - - - - -```javascript -{ - // Response -} -``` - - + **취소에 대한 매출전표 확인 URL. PG사에 따라 제공되지 않는 경우도 있음** + + + + + ```javascript + { + // Response + } + ``` + ### **주요 요청 파라미터 상세 설명** @@ -405,13 +394,13 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 > 수납번호(barcode)를 발급요청하지 않고 고객사에서 관리하는 바코드(barcode)번호를 등록하여 > 수납번호로 활용할 수 있습니다. -> **expired_at** **integer** +> **expired\_at** **integer** > > **`편의점 수납가능한 결제기한`** > > 정의하지 않으면 갤럭시아컴즈와 계약시 협의한 기본값이 적용됩니다. -> **`pg`** **\`\`**** ``** **`string`** +> **`pg`** **\`\`**\*\* \`\`\*\* **`string`** > > **`PG사 구분자`** > @@ -426,6 +415,7 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 > 설정된 결제에 대해서는 해당 URL로 아래와 같은 형식의 데이터가 Webhook(HTTP POST)으로 전송됩니다. > > **`200응답 == 수납가능 / 그 외응답 == 수납불가 처리`** +> > ```json > { > "event" : "Galaxia.Cvs.Confirm", @@ -440,77 +430,75 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 > ```
-

Response Model Schema

- -```json -{ - "code": 0, - "message": "string", - "response": { - "imp_uid": "string", - "merchant_uid": "string", - "pay_method": "string", - "channel": "pc", - "pg_provider": "string", - "emb_pg_provider": "string", - "pg_tid": "string", - "pg_id": "string", - "escrow": true, - "apply_num": "string", - "bank_code": "string", - "bank_name": "string", - "card_code": "string", - "card_name": "string", - "card_quota": 0, - "card_number": "string", - "card_type": "null", - "vbank_code": "string", - "vbank_name": "string", - "vbank_num": "string", - "vbank_holder": "string", - "vbank_date": 0, - "vbank_issued_at": 0, - "name": "string", - "amount": 0, - "cancel_amount": 0, - "currency": "string", - "buyer_name": "string", - "buyer_email": "string", - "buyer_tel": "string", - "buyer_addr": "string", - "buyer_postcode": "string", - "custom_data": "string", - "user_agent": "string", - "status": "ready", - "started_at": 0, - "paid_at": 0, - "failed_at": 0, - "cancelled_at": 0, - "fail_reason": "string", - "cancel_reason": "string", - "receipt_url": "string", - "cancel_history": [ - { - "pg_tid": "string", - "amount": 0, - "cancelled_at": 0, - "reason": "string", - "receipt_url": "string" - } - ], - "cancel_receipt_urls": ["string"], - "cash_receipt_issued": true, - "customer_uid": "string", - "customer_uid_usage": "issue" +

Response Model Schema

+ + ```json + { + "code": 0, + "message": "string", + "response": { + "imp_uid": "string", + "merchant_uid": "string", + "pay_method": "string", + "channel": "pc", + "pg_provider": "string", + "emb_pg_provider": "string", + "pg_tid": "string", + "pg_id": "string", + "escrow": true, + "apply_num": "string", + "bank_code": "string", + "bank_name": "string", + "card_code": "string", + "card_name": "string", + "card_quota": 0, + "card_number": "string", + "card_type": "null", + "vbank_code": "string", + "vbank_name": "string", + "vbank_num": "string", + "vbank_holder": "string", + "vbank_date": 0, + "vbank_issued_at": 0, + "name": "string", + "amount": 0, + "cancel_amount": 0, + "currency": "string", + "buyer_name": "string", + "buyer_email": "string", + "buyer_tel": "string", + "buyer_addr": "string", + "buyer_postcode": "string", + "custom_data": "string", + "user_agent": "string", + "status": "ready", + "started_at": 0, + "paid_at": 0, + "failed_at": 0, + "cancelled_at": 0, + "fail_reason": "string", + "cancel_reason": "string", + "receipt_url": "string", + "cancel_history": [ + { + "pg_tid": "string", + "amount": 0, + "cancelled_at": 0, + "reason": "string", + "receipt_url": "string" + } + ], + "cancel_receipt_urls": ["string"], + "cash_receipt_issued": true, + "customer_uid": "string", + "customer_uid_usage": "issue" + } } -} -``` - + ```
-**Swagger Test Link** - -[**https://api.iamport.kr/#!/cvs/issueCvsPayment**](https://api.iamport.kr/#!/cvs/issueCvsPayment) + **Swagger Test Link** + [**https://api.iamport.kr/#!/cvs/issueCvsPayment**](https://api.iamport.kr/#!/cvs/issueCvsPayment) diff --git a/src/content/docs/ko/api/miscellaneous-api/cvs/revoke-cvs-payment-api.mdx b/src/content/docs/ko/api/miscellaneous-api/cvs/revoke-cvs-payment-api.mdx index dfbec56c3..133a1142d 100644 --- a/src/content/docs/ko/api/miscellaneous-api/cvs/revoke-cvs-payment-api.mdx +++ b/src/content/docs/ko/api/miscellaneous-api/cvs/revoke-cvs-payment-api.mdx @@ -4,406 +4,396 @@ description: 편의점결제 발급/등록된 수납번호(barcode)를 말소처 --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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"; -### 수납번호(barcode)로 결제가 이뤄지지 않도록 말소처리하는 API입니다. +## 수납번호(barcode)로 결제가 이뤄지지 않도록 말소처리하는 API입니다. - -고객에게 이미 발급/등록된 편의점결제 수납번호(barcode)가 아직 수납 전일 때, 재고소진 등에 상황에 따라 해당 수납번호(barcode)로 결제가 이뤄지지 않도록 말소처리하는 API입니다. - - - -### Parameters - -#### Path + + 고객에게 이미 발급/등록된 편의점결제 수납번호(barcode)가 아직 수납 전일 때, 재고소진 등에 상황에 따라 해당 수납번호(barcode)로 결제가 이뤄지지 않도록 말소처리하는 API입니다. + - -**포트원 거래고유번호** + ### Parameters -편의접결제 수납번호(barcode) 발급/등록된 포트원 거래고유번호 + #### Path - + + **포트원 거래고유번호** -### Responses + 편의접결제 수납번호(barcode) 발급/등록된 포트원 거래고유번호 + - - - -**`code`** **\*** **integer** + ### Responses -**응답코드** + + + + **`code`** **\*** **integer** -0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 + **응답코드** -**`message`** **\*** **string** + 0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 -**응답메세지** + **`message`** **\*** **string** -code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 + **응답메세지** -**`response`** **`(PaymentAnnotation, optional)`** + code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 - - + **`response`** **`(PaymentAnnotation, optional)`** + + - - -**`code`** **\*** **integer** + + + **`code`** **\*** **integer** -**응답코드** + **응답코드** -0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 + 0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 -**`message`** **\*** **string** + **`message`** **\*** **string** -**응답메세지** + **응답메세지** -code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 + code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 -**`imp_uid`** **\*** **string** + **`imp_uid`** **\*** **string** -**포트원 거래고유번호** + **포트원 거래고유번호** -**`merchant_uid`** **\*** **string** + **`merchant_uid`** **\*** **string** -**고객사 주문번호** + **고객사 주문번호** -**`pay_method`** **\*** **string** + **`pay_method`** **\*** **string** -**결제수단 구분코드** + **결제수단 구분코드** -- samsung : 삼성페이 -- card : 신용카드 -- trans : 계좌이체 -- vbank : 가상계좌 -- phone : 휴대폰 -- cultureland : 문화상품권 -- smartculture : 스마트문상 -- booknlife : 도서문화상품권 -- happymoney : 해피머니 -- point : 포인트 -- ssgpay : SSGPAY -- lpay : LPAY -- payco : 페이코 -- kakaopay : 카카오페이 -- tosspay : 토스 -- naverpay : 네이버페이 + - samsung : 삼성페이 + - card : 신용카드 + - trans : 계좌이체 + - vbank : 가상계좌 + - phone : 휴대폰 + - cultureland : 문화상품권 + - smartculture : 스마트문상 + - booknlife : 도서문화상품권 + - happymoney : 해피머니 + - point : 포인트 + - ssgpay : SSGPAY + - lpay : LPAY + - payco : 페이코 + - kakaopay : 카카오페이 + - tosspay : 토스 + - naverpay : 네이버페이 -**`channel`** **\*** **string** + **`channel`** **\*** **string** -**결제환경 구분코드** + **결제환경 구분코드** -- pc:(인증방식)PC결제 -- mobile:(인증방식)모바일결제 -- api:정기결제 또는 비인증 결제 + - pc:(인증방식)PC결제 + - mobile:(인증방식)모바일결제 + - api:정기결제 또는 비인증 결제 -**`pg_provider`** **\*** **string** + **`pg_provider`** **\*** **string** -**PG사 구분코드** + **PG사 구분코드** -**`emb_pg_provider`** **\*** **string** + **`emb_pg_provider`** **\*** **string** -**허브형결제 PG사 구분코드** + **허브형결제 PG사 구분코드** -**`pg_tid`** **\*** **string** + **`pg_tid`** **\*** **string** -**pg사 거래번호** + **pg사 거래번호** -**`pg_id`** **\*** **string** + **`pg_id`** **\*** **string** -**PG사 MID** + **PG사 MID** -**`escrow`** **boolean** + **`escrow`** **boolean** -**에스크로 결제여부** + **에스크로 결제여부** -**`apply_num`** **string** + **`apply_num`** **string** -**신용카드 승인번호** + **신용카드 승인번호** -**`bank_code`** **string** + **`bank_code`** **string** -**은행 표준코드** (금융결제원 표준코드: [**`(링크보기)`**](../../tip/pg-1) + **은행 표준코드** (금융결제원 표준코드: [**`(링크보기)`**](../../tip/pg-1) -**`bank_name`** **string** + **`bank_name`** **string** -**은행 명칭** + **은행 명칭** -실시간 계좌이체 결제건의 경우 + 실시간 계좌이체 결제건의 경우 -**`card_code`** **string** + **`card_code`** **string** -**카드사 코드번호(금융결제원 표준코드번호 :** [**링크**](https://chaifinance.notion.site/53589280bbc94fab938d93257d452216?v=eb405baf52134b3f90d438e3bf763630) ) + **카드사 코드번호(금융결제원 표준코드번호 :** [**링크**](https://chaifinance.notion.site/53589280bbc94fab938d93257d452216?v=eb405baf52134b3f90d438e3bf763630) ) -**`card_name`** **string** + **`card_name`** **string** -**카드사명** + **카드사명** -**`card_quota`** **integer** + **`card_quota`** **integer** -**할부개월 수(0이면 일시불)** + **할부개월 수(0이면 일시불)** -**`card_number`** **string** + **`card_number`** **string** -**결제에 사용된 마스킹된 카드번호** + **결제에 사용된 마스킹된 카드번호** -7~12번째 자리를 마스킹하는 것이 일반적이지만, PG사의 정책/설정에 따라 다소 차이가 있을 수 있습니다. + 7\~12번째 자리를 마스킹하는 것이 일반적이지만, PG사의 정책/설정에 따라 다소 차이가 있을 수 있습니다. -**`card_type`** **string** + **`card_type`** **string** -**카드 구분코드** + **카드 구분코드** -(주의)해당 정보를 제공하지 않는 일부 PG사의 경우 null 로 응답됨(ex. JTNet, 이니시스-빌링) + (주의)해당 정보를 제공하지 않는 일부 PG사의 경우 null 로 응답됨(ex. JTNet, 이니시스-빌링) -- 0 : 신용카드 -- 1 : 체크카드 + - 0 : 신용카드 + - 1 : 체크카드 -**`vbank_code`** **string** + **`vbank_code`** **string** -**가상계좌 은행 표준코드(금융결제원 기준)** + **가상계좌 은행 표준코드(금융결제원 기준)** -**`vbank_name`** **string** + **`vbank_name`** **string** -**입금받을 가상계좌 은행명** + **입금받을 가상계좌 은행명** -**`vbank_holder`** **string** + **`vbank_holder`** **string** -**입금받을 가상계좌 예금주** + **입금받을 가상계좌 예금주** -**`vbank_date`** **string** + **`vbank_date`** **string** -**입금받을 가상계좌 마감기한 (UNIX timestamp)** + **입금받을 가상계좌 마감기한 (UNIX timestamp)** -**`vbank_issued_at`** **string** + **`vbank_issued_at`** **string** -**가상계좌 생성 시각 (UNIX timestamp)** + **가상계좌 생성 시각 (UNIX timestamp)** -**`name`** **string** + **`name`** **string** -**제품명** + **제품명** -**`amount`** **\*** **integer** + **`amount`** **\*** **integer** -**주문(결제)금액** + **주문(결제)금액** -**`cancel_amount`** **integer** + **`cancel_amount`** **integer** -**결제취소금액** + **결제취소금액** -**`currency`** **string** + **`currency`** **string** -**통화구분코드** + **통화구분코드** -**`buyer_name`** **string** + **`buyer_name`** **string** -**주문자명** + **주문자명** -**`buyer_email`** **string** + **`buyer_email`** **string** -**주문자 Email주소** + **주문자 Email주소** -**`buyer_tel`** **string** + **`buyer_tel`** **string** -**주문자 전화번호** + **주문자 전화번호** -**`buyer_addr`** **string** + **`buyer_addr`** **string** -**주문자 주소** + **주문자 주소** -**`buyer_postcode`** **string** + **`buyer_postcode`** **string** -**주문자 우편번호** + **주문자 우편번호** -**`custom_data`** **string** + **`custom_data`** **string** -**고객사 custom 데이터** JSON string으로 전달 + **고객사 custom 데이터** JSON string으로 전달 -**`user_agent`** **string** + **`user_agent`** **string** -**UserAgent** 구매자가 결제를 시작한 단말기의 UserAgent 문자열 + **UserAgent** 구매자가 결제를 시작한 단말기의 UserAgent 문자열 -**`status`** **\*** **string** + **`status`** **\*** **string** -**결제상태 구분코드** + **결제상태 구분코드** -- ready : 미결제 -- paid : 결제완료 -- cancelled : 결제취소 -- failed : 결제실패 + - ready : 미결제 + - paid : 결제완료 + - cancelled : 결제취소 + - failed : 결제실패 -**`started_at`** **\*** **string** + **`started_at`** **\*** **string** -**결제시작시점 (UNIX timestamp)** + **결제시작시점 (UNIX timestamp)** -**`paid_at`** **\*** **string** + **`paid_at`** **\*** **string** -**결제완료시점 (UNIX timestamp)**\\ + **결제완료시점 (UNIX timestamp)**\\ -**`failed_at`** **\*** **string** + **`failed_at`** **\*** **string** -**결제실패시점 (UNIX timestamp)** + **결제실패시점 (UNIX timestamp)** -**`cancelled_at`** **\*** **string** + **`cancelled_at`** **\*** **string** -**결제취소시점 (UNIX timestamp)** + **결제취소시점 (UNIX timestamp)** -**`fail_reason`** **string** + **`fail_reason`** **string** -**결제실패 사유** + **결제실패 사유** -**`cancel_reason`** **string** + **`cancel_reason`** **string** -**결제취소 사유** + **결제취소 사유** -**`receipt_url`** **string** + **`receipt_url`** **string** -**신용카드 매출전표 확인 URL** + **신용카드 매출전표 확인 URL** -**`cash_receipt_issued`** **boolean** + **`cash_receipt_issued`** **boolean** -**현금영수증 자동발급 여부** + **현금영수증 자동발급 여부** -**`customer_uid`** **string** + **`customer_uid`** **string** -**해당 결제처리에 사용된 customer_uid** + **해당 결제처리에 사용된 customer\_uid** -**`customer_uid_usage`** **string** + **`customer_uid_usage`** **string** -**customer_uid 사용 구분코드** + **customer\_uid 사용 구분코드** -- null : 일반결제 -- issue : 빌링키 발급 -- payment : 결제 -- payment.scheduled : 예약결제 + - null : 일반결제 + - issue : 빌링키 발급 + - payment : 결제 + - payment.scheduled : 예약결제 -**`cancel_history`** **(Array\[PaymentCancelAnnotation], optional):** + **`cancel_history`** **(Array\[PaymentCancelAnnotation], optional):** -**취소/부분취소 내역** + **취소/부분취소 내역** + + - - + + + **cancel\_history array \[]** - - -**cancel\_history array \[]** + **`pg_tid`** **\*** **string** -**`pg_tid`** **\*** **string** + **PG사 승인취소번호** -**PG사 승인취소번호** + **`amount`** **\*** **integer** -**`amount`** **\*** **integer** + **취소 금액** -**취소 금액** + **`cancelled_at`** **\*** **string** -**`cancelled_at`** **\*** **string** + **결제취소된 시각 UNIX timestamp** -**결제취소된 시각 UNIX timestamp** + **`reason`** **\*** **string** -**`reason`** **\*** **string** + **결제취소 사유** -**결제취소 사유** + **`receipt_url`** **\*** **string** -**`receipt_url`** **\*** **string** - -**취소에 대한 매출전표 확인 URL. PG사에 따라 제공되지 않는 경우도 있음** - - - - - - - -```javascript -{ - // Response -} -``` - - + **취소에 대한 매출전표 확인 URL. PG사에 따라 제공되지 않는 경우도 있음** + + + + + ```javascript + { + // Response + } + ``` +
-

Response Model Schema

- -``` -{ - "code": 0, - "message": "string", - "response": { - "imp_uid": "string", - "merchant_uid": "string", - "pay_method": "string", - "channel": "pc", - "pg_provider": "string", - "emb_pg_provider": "string", - "pg_tid": "string", - "pg_id": "string", - "escrow": true, - "apply_num": "string", - "bank_code": "string", - "bank_name": "string", - "card_code": "string", - "card_name": "string", - "card_quota": 0, - "card_number": "string", - "card_type": "null", - "vbank_code": "string", - "vbank_name": "string", - "vbank_num": "string", - "vbank_holder": "string", - "vbank_date": 0, - "vbank_issued_at": 0, - "name": "string", - "amount": 0, - "cancel_amount": 0, - "currency": "string", - "buyer_name": "string", - "buyer_email": "string", - "buyer_tel": "string", - "buyer_addr": "string", - "buyer_postcode": "string", - "custom_data": "string", - "user_agent": "string", - "status": "ready", - "started_at": 0, - "paid_at": 0, - "failed_at": 0, - "cancelled_at": 0, - "fail_reason": "string", - "cancel_reason": "string", - "receipt_url": "string", - "cancel_history": [ - { - "pg_tid": "string", - "amount": 0, - "cancelled_at": 0, - "reason": "string", - "receipt_url": "string" - } - ], - "cancel_receipt_urls": [ - "string" - ], - "cash_receipt_issued": true, - "customer_uid": "string", - "customer_uid_usage": "issue" +

Response Model Schema

+ + ```json + { + "code": 0, + "message": "string", + "response": { + "imp_uid": "string", + "merchant_uid": "string", + "pay_method": "string", + "channel": "pc", + "pg_provider": "string", + "emb_pg_provider": "string", + "pg_tid": "string", + "pg_id": "string", + "escrow": true, + "apply_num": "string", + "bank_code": "string", + "bank_name": "string", + "card_code": "string", + "card_name": "string", + "card_quota": 0, + "card_number": "string", + "card_type": "null", + "vbank_code": "string", + "vbank_name": "string", + "vbank_num": "string", + "vbank_holder": "string", + "vbank_date": 0, + "vbank_issued_at": 0, + "name": "string", + "amount": 0, + "cancel_amount": 0, + "currency": "string", + "buyer_name": "string", + "buyer_email": "string", + "buyer_tel": "string", + "buyer_addr": "string", + "buyer_postcode": "string", + "custom_data": "string", + "user_agent": "string", + "status": "ready", + "started_at": 0, + "paid_at": 0, + "failed_at": 0, + "cancelled_at": 0, + "fail_reason": "string", + "cancel_reason": "string", + "receipt_url": "string", + "cancel_history": [ + { + "pg_tid": "string", + "amount": 0, + "cancelled_at": 0, + "reason": "string", + "receipt_url": "string" + } + ], + "cancel_receipt_urls": [ + "string" + ], + "cash_receipt_issued": true, + "customer_uid": "string", + "customer_uid_usage": "issue" + } } -} -``` - + ```
-**Swagger Test Link** - -[**https://api.iamport.kr/#!/cvs/revokeCvsPayment**](https://api.iamport.kr/#!/cvs/revokeCvsPayment) + **Swagger Test Link** + [**https://api.iamport.kr/#!/cvs/revokeCvsPayment**](https://api.iamport.kr/#!/cvs/revokeCvsPayment) diff --git a/src/content/docs/ko/api/non-authenticated-payment-api/again-api.mdx b/src/content/docs/ko/api/non-authenticated-payment-api/again-api.mdx index e52bfd1b3..6b0a5efa3 100644 --- a/src/content/docs/ko/api/non-authenticated-payment-api/again-api.mdx +++ b/src/content/docs/ko/api/non-authenticated-payment-api/again-api.mdx @@ -4,15 +4,15 @@ description: 저장된 빌링키(customer_uid)를 이용하여 결제를 요청 --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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"; -### 저장된 빌링키(customer_uid)로 결제를 요청 할수 있습니다. +## 저장된 빌링키(customer_uid)로 결제를 요청 할수 있습니다. @@ -422,7 +422,7 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 ```javascript { - // Response + // Response } ``` diff --git a/src/content/docs/ko/api/non-authenticated-payment-api/onetime-api.mdx b/src/content/docs/ko/api/non-authenticated-payment-api/onetime-api.mdx index 5156e0a5f..776b6be72 100644 --- a/src/content/docs/ko/api/non-authenticated-payment-api/onetime-api.mdx +++ b/src/content/docs/ko/api/non-authenticated-payment-api/onetime-api.mdx @@ -4,15 +4,15 @@ description: 카드정보를 기입하여 1회성 결제를 요청할 수 있습 --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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"; -### 카드정보만으로 결제를 요청할 수 있습니다. +## 카드정보만으로 결제를 요청할 수 있습니다. @@ -458,7 +458,7 @@ JSON string으로 전달 ```javascript { - // Response + // Response } ``` diff --git a/src/content/docs/ko/api/payment-api/all-api.mdx b/src/content/docs/ko/api/payment-api/all-api.mdx index 483207817..9b9f3ad0c 100644 --- a/src/content/docs/ko/api/payment-api/all-api.mdx +++ b/src/content/docs/ko/api/payment-api/all-api.mdx @@ -4,15 +4,15 @@ description: 주문번호 및 상태기준으로 결제내역을 조회 합니 --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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"; -### 주문번호 기준 결제내역을 복수조회 합니다. 동일한 주문번호가 복수개인 경우 존재하는 모든 거래가 조회됩니다. +## 주문번호 기준 결제내역을 복수조회 합니다. 동일한 주문번호가 복수개인 경우 존재하는 모든 거래가 조회됩니다. @@ -376,7 +376,7 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 ```javascript { - // Response + // Response } ``` @@ -385,7 +385,7 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 ```javascript { - // Response + // Response } ``` @@ -394,7 +394,7 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 ```javascript { - // Response + // Response } ``` diff --git a/src/content/docs/ko/api/payment-api/cancel-payment-api.mdx b/src/content/docs/ko/api/payment-api/cancel-payment-api.mdx index e6d8d16b0..8e7edd7bc 100644 --- a/src/content/docs/ko/api/payment-api/cancel-payment-api.mdx +++ b/src/content/docs/ko/api/payment-api/cancel-payment-api.mdx @@ -4,385 +4,373 @@ description: 모든 결제내역을 취소할 수 있는 API 를 안내합니다 --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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"; -### **결제수단 및 PG사와 상관없이 취소 및 부분취소가 가능합니다.** +## 결제수단 및 PG사와 상관없이 취소 및 부분취소가 가능합니다. - -신용카드/실시간계좌이체/휴대폰 소액결제의 경우 즉시 취소처리가 이뤄지게 되며 가상계좌의 경우는 환불받으실 계좌정보를 같이 전달해주시면 환불정보가 PG사에 등록되어 익영업일에 처리됩니다. - -**(가상계좌 환불, 휴대폰소액결제 익월 환불(KCP)시 관련 특약계약 필요)** - - - -### Parameters - -#### Body - - - - -**포트원 거래고유번호** + + 신용카드/실시간계좌이체/휴대폰 소액결제의 경우 즉시 취소처리가 이뤄지게 되며 가상계좌의 경우는 환불받으실 계좌정보를 같이 전달해주시면 환불정보가 PG사에 등록되어 익영업일에 처리됩니다. - + **(가상계좌 환불, 휴대폰소액결제 익월 환불(KCP)시 관련 특약계약 필요)** + - - -**고객사 주문번호 (imp_uid 누락시 필수)** + ### Parameters - - -취소 요청금액(**누락시 전액취소**) + #### Body - - -취소요청금액 중 면세금액 (**누락되면 0원처리**) + + + **포트원 거래고유번호** + + - - -부가세 지정(기본값: null) -**결제 시 부가세를 지정했던 경우 필수** 입력 바랍니다. + + **고객사 주문번호 (imp\_uid 누락시 필수)** + -지원 PG사 + + 취소 요청금액(**누락시 전액취소**) + -\-(구) 나이스페이먼츠 + + 취소요청금액 중 면세금액 (**누락되면 0원처리**) + -\-KG이니시스 + + 부가세 지정(기본값: null) + **결제 시 부가세를 지정했던 경우 필수** 입력 바랍니다. -\-(신) 나이스페이먼츠 + 지원 PG사 -\-웰컴페이먼츠 + -(구) 나이스페이먼츠 - + -KG이니시스 - -현재시점의 취소 가능한 잔액 + -(신) 나이스페이먼츠 - - -취소사유 + -웰컴페이먼츠 + - - -환불계좌 예금주(가상계좌 취소 시 필수) + + 현재시점의 취소 가능한 잔액 + - - -환불계좌 예금주 연락처(가상계좌 취소 시 사용,(구)/(신) 스마트로의 경우 필수값임)** + + 취소사유 + - - -환불계좌 은행코드 [**`(은행코드표)`**](../../tip/pg-1) (가상계좌 취소 시 필수) + + 환불계좌 예금주(가상계좌 취소 시 필수) + - - -환불계좌 계좌번호 (가상계좌 취소 시 필수) + + 환불계좌 예금주 연락처(가상계좌 취소 시 사용,(구)/(신) 스마트로의 경우 필수값임)\*\* + - - -추가 파라미터 + + 환불계좌 은행코드 [**`(은행코드표)`**](../../tip/pg-1) (가상계좌 취소 시 필수) + - + + 환불계좌 계좌번호 (가상계좌 취소 시 필수) + -### Responses + + 추가 파라미터 + - - - -**`code`** **integer** + ### Responses -**응답코드** + + + + **`code`** **integer** -0이면 정상적인 조회, 0이 아닌 값이면 message를 확인해봐야 합니다 + **응답코드** -**`message`** **string** + 0이면 정상적인 조회, 0이 아닌 값이면 message를 확인해봐야 합니다 -**응답메세지** + **`message`** **string** -code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 + **응답메세지** -**`response`** **(PagedPaymentAnnotation, optional)** + code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 - - + **`response`** **(PagedPaymentAnnotation, optional)** + + - - -**`code`** **\*** **integer** + + + **`code`** **\*** **integer** -**응답코드** + **응답코드** -0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 + 0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 -**`message`** **\*** **string** + **`message`** **\*** **string** -**응답메세지** + **응답메세지** -code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 + code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 -**`imp_uid`** **\*** **string** + **`imp_uid`** **\*** **string** -**포트원 거래고유번호** + **포트원 거래고유번호** -**`merchant_uid`** **\*** **string** + **`merchant_uid`** **\*** **string** -**고객사 주문번호** + **고객사 주문번호** -**`pay_method`** **\*** **string** + **`pay_method`** **\*** **string** -**결제수단 구분코드** + **결제수단 구분코드** -- samsung : 삼성페이 -- card : 신용카드 -- trans : 계좌이체 -- vbank : 가상계좌 -- phone : 휴대폰 -- cultureland : 문화상품권 -- smartculture : 스마트문상 -- booknlife : 도서문화상품권 -- happymoney : 해피머니 -- point : 포인트 -- ssgpay : SSGPAY -- lpay : LPAY -- payco : 페이코 -- kakaopay : 카카오페이 -- tosspay : 토스 -- naverpay : 네이버페이 + - samsung : 삼성페이 + - card : 신용카드 + - trans : 계좌이체 + - vbank : 가상계좌 + - phone : 휴대폰 + - cultureland : 문화상품권 + - smartculture : 스마트문상 + - booknlife : 도서문화상품권 + - happymoney : 해피머니 + - point : 포인트 + - ssgpay : SSGPAY + - lpay : LPAY + - payco : 페이코 + - kakaopay : 카카오페이 + - tosspay : 토스 + - naverpay : 네이버페이 -**`channel`** **\*** **string** + **`channel`** **\*** **string** -**결제환경 구분코드** + **결제환경 구분코드** -- pc:(인증방식)PC결제 -- mobile:(인증방식)모바일결제 -- api:정기결제 또는 비인증 결제 + - pc:(인증방식)PC결제 + - mobile:(인증방식)모바일결제 + - api:정기결제 또는 비인증 결제 -**`pg_provider`** **\*** **string** + **`pg_provider`** **\*** **string** -**PG사 구분코드** + **PG사 구분코드** -**`emb_pg_provider`** **\*** **string** + **`emb_pg_provider`** **\*** **string** -**허브형결제 PG사 구분코드** + **허브형결제 PG사 구분코드** -**`pg_tid`** **\*** **string** + **`pg_tid`** **\*** **string** -**pg사 거래번호** + **pg사 거래번호** -**`pg_id`** **\*** **string** + **`pg_id`** **\*** **string** -**PG사 MID** + **PG사 MID** -**`escrow`** **boolean** + **`escrow`** **boolean** -**에스크로 결제여부** + **에스크로 결제여부** -**`apply_num`** **string** + **`apply_num`** **string** -**신용카드 승인번호** + **신용카드 승인번호** -**`bank_code`** **string** + **`bank_code`** **string** -**은행 표준코드** (금융결제원 표준코드: [**`(링크보기)`**](../../tip/pg-1) + **은행 표준코드** (금융결제원 표준코드: [**`(링크보기)`**](../../tip/pg-1) -**`bank_name`** **string** + **`bank_name`** **string** -**은행 명칭** + **은행 명칭** -실시간 계좌이체 결제건의 경우 + 실시간 계좌이체 결제건의 경우 -**`card_code`** **string** + **`card_code`** **string** -**카드사 코드번호(금융결제원 표준코드번호 :** [**링크**](https://chaifinance.notion.site/53589280bbc94fab938d93257d452216?v=eb405baf52134b3f90d438e3bf763630) ) + **카드사 코드번호(금융결제원 표준코드번호 :** [**링크**](https://chaifinance.notion.site/53589280bbc94fab938d93257d452216?v=eb405baf52134b3f90d438e3bf763630) ) -**`card_name`** **string** + **`card_name`** **string** -**카드사명** + **카드사명** -**`card_quota`** **integer** + **`card_quota`** **integer** -**할부개월 수(0이면 일시불)** + **할부개월 수(0이면 일시불)** -**`card_number`** **string** + **`card_number`** **string** -**결제에 사용된 마스킹된 카드번호** + **결제에 사용된 마스킹된 카드번호** -7~12번째 자리를 마스킹하는 것이 일반적이지만, PG사의 정책/설정에 따라 다소 차이가 있을 수 있습니다. + 7\~12번째 자리를 마스킹하는 것이 일반적이지만, PG사의 정책/설정에 따라 다소 차이가 있을 수 있습니다. -**`card_type`** **string** + **`card_type`** **string** -**카드 구분코드** + **카드 구분코드** -(주의)해당 정보를 제공하지 않는 일부 PG사의 경우 null 로 응답됨(ex. JTNet, 이니시스-빌링) + (주의)해당 정보를 제공하지 않는 일부 PG사의 경우 null 로 응답됨(ex. JTNet, 이니시스-빌링) -- 0 : 신용카드 -- 1 : 체크카드 + - 0 : 신용카드 + - 1 : 체크카드 -**`vbank_code`** **string** + **`vbank_code`** **string** -**가상계좌 은행 표준코드(금융결제원 기준)** + **가상계좌 은행 표준코드(금융결제원 기준)** -**`vbank_name`** **string** + **`vbank_name`** **string** -**입금받을 가상계좌 은행명** + **입금받을 가상계좌 은행명** -**`vbank_holder`** **string** + **`vbank_holder`** **string** -**입금받을 가상계좌 예금주** + **입금받을 가상계좌 예금주** -**`vbank_date`** **string** + **`vbank_date`** **string** -**입금받을 가상계좌 마감기한 (UNIX timestamp)** + **입금받을 가상계좌 마감기한 (UNIX timestamp)** -**`vbank_issued_at`** **string** + **`vbank_issued_at`** **string** -**가상계좌 생성 시각 (UNIX timestamp)** + **가상계좌 생성 시각 (UNIX timestamp)** -**`name`** **string** + **`name`** **string** -**제품명** + **제품명** -**`amount`** **\*** **integer** + **`amount`** **\*** **integer** -**주문(결제)금액** + **주문(결제)금액** -**`cancel_amount`** **integer** + **`cancel_amount`** **integer** -**결제취소금액** + **결제취소금액** -**`currency`** **string** + **`currency`** **string** -**통화구분코드** + **통화구분코드** -**`buyer_name`** **string** + **`buyer_name`** **string** -**주문자명** + **주문자명** -**`buyer_email`** **string** + **`buyer_email`** **string** -**주문자 Email주소** + **주문자 Email주소** -**`buyer_tel`** **string** + **`buyer_tel`** **string** -**주문자 전화번호** + **주문자 전화번호** -**`buyer_addr`** **string** + **`buyer_addr`** **string** -**주문자 주소** + **주문자 주소** -**`buyer_postcode`** **string** + **`buyer_postcode`** **string** -**주문자 우편번호** + **주문자 우편번호** -**`custom_data`** **string** + **`custom_data`** **string** -**고객사 custom 데이터** JSON string으로 전달 + **고객사 custom 데이터** JSON string으로 전달 -**`user_agent`** **string** + **`user_agent`** **string** -**UserAgent** 구매자가 결제를 시작한 단말기의 UserAgent 문자열 + **UserAgent** 구매자가 결제를 시작한 단말기의 UserAgent 문자열 -**`status`** **\*** **string** + **`status`** **\*** **string** -**결제상태 구분코드** + **결제상태 구분코드** -- ready : 미결제 -- paid : 결제완료 -- cancelled : 결제취소 -- failed : 결제실패 + - ready : 미결제 + - paid : 결제완료 + - cancelled : 결제취소 + - failed : 결제실패 -**`started_at`** **\*** **string** + **`started_at`** **\*** **string** -**결제시작시점 (UNIX timestamp)** + **결제시작시점 (UNIX timestamp)** -**`paid_at`** **\*** **string** + **`paid_at`** **\*** **string** -**결제완료시점 (UNIX timestamp)**\\ + **결제완료시점 (UNIX timestamp)**\\ -**`failed_at`** **\*** **string** + **`failed_at`** **\*** **string** -**결제실패시점 (UNIX timestamp)** + **결제실패시점 (UNIX timestamp)** -**`cancelled_at`** **\*** **string** + **`cancelled_at`** **\*** **string** -**결제취소시점 (UNIX timestamp)** + **결제취소시점 (UNIX timestamp)** -**`fail_reason`** **string** + **`fail_reason`** **string** -**결제실패 사유** + **결제실패 사유** -**`cancel_reason`** **string** + **`cancel_reason`** **string** -**결제취소 사유** + **결제취소 사유** -**`receipt_url`** **string** + **`receipt_url`** **string** -**신용카드 매출전표 확인 URL** + **신용카드 매출전표 확인 URL** -**`cash_receipt_issued`** **boolean** + **`cash_receipt_issued`** **boolean** -**현금영수증 자동발급 여부** + **현금영수증 자동발급 여부** -**`customer_uid`** **string** + **`customer_uid`** **string** -**해당 결제처리에 사용된 customer_uid** + **해당 결제처리에 사용된 customer\_uid** -**`customer_uid_usage`** **string** + **`customer_uid_usage`** **string** -**customer_uid 사용 구분코드** + **customer\_uid 사용 구분코드** -- null : 일반결제 -- issue : 빌링키 발급 -- payment : 결제 -- payment.scheduled : 예약결제 + - null : 일반결제 + - issue : 빌링키 발급 + - payment : 결제 + - payment.scheduled : 예약결제 -**`cancel_history`** **(Array\[PaymentCancelAnnotation], optional):** + **`cancel_history`** **(Array\[PaymentCancelAnnotation], optional):** -**취소/부분취소 내역** + **취소/부분취소 내역** + + - - + + + **cancel\_history array \[]** - - -**cancel\_history array \[]** + **`pg_tid`** **\*** **string** -**`pg_tid`** **\*** **string** + **PG사 승인취소번호** -**PG사 승인취소번호** + **`amount`** **\*** **integer** -**`amount`** **\*** **integer** + **취소 금액** -**취소 금액** + **`cancelled_at`** **\*** **string** -**`cancelled_at`** **\*** **string** + **결제취소된 시각 UNIX timestamp** -**결제취소된 시각 UNIX timestamp** + **`reason`** **\*** **string** -**`reason`** **\*** **string** + **결제취소 사유** -**결제취소 사유** + **`receipt_url`** **\*** **string** -**`receipt_url`** **\*** **string** - -**취소에 대한 매출전표 확인 URL. PG사에 따라 제공되지 않는 경우도 있음** - - - - - - - - - + **취소에 대한 매출전표 확인 URL. PG사에 따라 제공되지 않는 경우도 있음** + + + + ### **주요 요청 파라미터 상세 설명** @@ -409,102 +397,101 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 > > **면세금액** > -> 부분취소시 면세 금액이 포함된 경우 반드시 취소 면세금액(tax_free)을 포함하여 요청해야합니다. -> 아래 PG사의 경우 tax_free 미입력시 자동으로 0원 처리 되지 않으므로 면세 결제에 한하여 필수 입력 바랍니다. +> 부분취소시 면세 금액이 포함된 경우 반드시 취소 면세금액(tax\_free)을 포함하여 요청해야합니다. +> 아래 PG사의 경우 tax\_free 미입력시 자동으로 0원 처리 되지 않으므로 면세 결제에 한하여 필수 입력 바랍니다. +> > - kakao > - kcp -> - kcp_quick +> - kcp\_quick > - kicc > - nice > - payco -> - nice_v2 +> - nice\_v2 > - welcome > **`extra`** **object** > -> 추가 파라미터. +> 추가 파라미터 > > 네이버페이 사용시 `extra.requester`를 설정해야 합니다. > -> - `customer`: 구매자에 의한 요청 -> - `admin`: (기본값) 관리자에 의한 요청 -> -> 예시) `{ "extra": { "requester": "customer" } }` +> > - `customer`: 구매자에 의한 요청 +> > +> > - `admin`: (기본값) 관리자에 의한 요청 +> > 예시) `{ "extra": { "requester": "customer" } }`
-

Response Model Schema

- -```json -{ - "code": 0, - "message": "string", - "response": { - "imp_uid": "string", - "merchant_uid": "string", - "pay_method": "string", - "channel": "pc", - "pg_provider": "string", - "emb_pg_provider": "string", - "pg_tid": "string", - "pg_id": "string", - "escrow": true, - "apply_num": "string", - "bank_code": "string", - "bank_name": "string", - "card_code": "string", - "card_name": "string", - "card_quota": 0, - "card_number": "string", - "card_type": "null", - "vbank_code": "string", - "vbank_name": "string", - "vbank_num": "string", - "vbank_holder": "string", - "vbank_date": 0, - "vbank_issued_at": 0, - "name": "string", - "amount": 0, - "cancel_amount": 0, - "currency": "string", - "buyer_name": "string", - "buyer_email": "string", - "buyer_tel": "string", - "buyer_addr": "string", - "buyer_postcode": "string", - "custom_data": "string", - "user_agent": "string", - "status": "ready", - "started_at": 0, - "paid_at": 0, - "failed_at": 0, - "cancelled_at": 0, - "fail_reason": "string", - "cancel_reason": "string", - "receipt_url": "string", - "cancel_history": [ - { - "pg_tid": "string", - "amount": 0, - "cancelled_at": 0, - "reason": "string", - "receipt_url": "string" - } - ], - "cancel_receipt_urls": [ - "string" - ], - "cash_receipt_issued": true, - "customer_uid": "string", - "customer_uid_usage": "issue" +

Response Model Schema

+ + ```json + { + "code": 0, + "message": "string", + "response": { + "imp_uid": "string", + "merchant_uid": "string", + "pay_method": "string", + "channel": "pc", + "pg_provider": "string", + "emb_pg_provider": "string", + "pg_tid": "string", + "pg_id": "string", + "escrow": true, + "apply_num": "string", + "bank_code": "string", + "bank_name": "string", + "card_code": "string", + "card_name": "string", + "card_quota": 0, + "card_number": "string", + "card_type": "null", + "vbank_code": "string", + "vbank_name": "string", + "vbank_num": "string", + "vbank_holder": "string", + "vbank_date": 0, + "vbank_issued_at": 0, + "name": "string", + "amount": 0, + "cancel_amount": 0, + "currency": "string", + "buyer_name": "string", + "buyer_email": "string", + "buyer_tel": "string", + "buyer_addr": "string", + "buyer_postcode": "string", + "custom_data": "string", + "user_agent": "string", + "status": "ready", + "started_at": 0, + "paid_at": 0, + "failed_at": 0, + "cancelled_at": 0, + "fail_reason": "string", + "cancel_reason": "string", + "receipt_url": "string", + "cancel_history": [ + { + "pg_tid": "string", + "amount": 0, + "cancelled_at": 0, + "reason": "string", + "receipt_url": "string" + } + ], + "cancel_receipt_urls": [ + "string" + ], + "cash_receipt_issued": true, + "customer_uid": "string", + "customer_uid_usage": "issue" + } } -} -``` - + ```
-**Swagger Test Link** - -[**https://api.iamport.kr/#!/payments/cancelPayment**](https://api.iamport.kr/#!/payments/cancelPayment) + **Swagger Test Link** + [**https://api.iamport.kr/#!/payments/cancelPayment**](https://api.iamport.kr/#!/payments/cancelPayment) diff --git a/src/content/docs/ko/api/payment-api/customer-payments-api.mdx b/src/content/docs/ko/api/payment-api/customer-payments-api.mdx index bd669f0a3..9800ff591 100644 --- a/src/content/docs/ko/api/payment-api/customer-payments-api.mdx +++ b/src/content/docs/ko/api/payment-api/customer-payments-api.mdx @@ -4,15 +4,15 @@ description: 빌링키로 결제된 복수 결제 내역을 확인할 수 있습 --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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"; -### 구매자의 빌링키로 결제된 결제목록을 조회합니다. +## 구매자의 빌링키로 결제된 결제목록을 조회합니다. @@ -332,7 +332,7 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 ```javascript { - // Response + // Response } ``` @@ -341,7 +341,7 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 ```javascript { - // Response + // Response } ``` diff --git a/src/content/docs/ko/api/payment-api/edit-prepare-payment-api.mdx b/src/content/docs/ko/api/payment-api/edit-prepare-payment-api.mdx index af5db4651..da231b048 100644 --- a/src/content/docs/ko/api/payment-api/edit-prepare-payment-api.mdx +++ b/src/content/docs/ko/api/payment-api/edit-prepare-payment-api.mdx @@ -4,120 +4,105 @@ description: POST /payments/prepare 로 이미 등록된 결제사전정보에 --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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"; -### [**결제금액 사전등록 API**](api-5) 로 등록된 금액을 수정합니다. +## [**결제금액 사전등록 API**](api-5) 로 등록된 금액을 수정합니다. - - - - -### Parameters - -#### Body - - - - -**고객사 주문번호** + - + ### Parameters - - - + #### Body -**결제 예정금액** + + + **고객사 주문번호** + + - + + + **결제 예정금액** + + - + ### Responses -### Responses + + + + **`code`** **\*** **integer** - - - -**`code`** **\*** **integer** + **응답코드** -**응답코드** + 0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 -0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 + **`message`** **\*** **string** -**`message`** **\*** **string** + **응답메세지** -**응답메세지** + code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 -code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 + + **`response (PaymentPrepareAnnotation, optional)`** + + + - - **`response (PaymentPrepareAnnotation, optional)`** - + + + **merchant\_uid** **\*** **`string`** - - + **고객사 주문번호** - - -**merchant\_uid** **\*** **`string`** + **`amount`** **\*** **`number`** -**고객사 주문번호** + **결제 예정 금액** + + + -**`amount`** **\*** **`number`** - -**결제 예정 금액** - - - - - - - -```javascript -{ - // Response -} -``` - - - - -```javascript -{ - // Response -} -``` - - + + ```javascript + { + // Response + } + ``` + + + ```javascript + { + // Response + } + ``` +
-

Response Model Schema

- -``` -{ - "code": 0, - "message": "string", - "response": { - "merchant_uid": "string", - "amount": 0 +

Response Model Schema

+ + ```json + { + "code": 0, + "message": "string", + "response": { + "merchant_uid": "string", + "amount": 0 + } } -} -``` - + ```
-**Swagger Test Link** - -[**https://api.iamport.kr/#!/payments.validation/editPreparePayment**](https://api.iamport.kr/#!/payments.validation/editPreparePayment) + **Swagger Test Link** + [**https://api.iamport.kr/#!/payments.validation/editPreparePayment**](https://api.iamport.kr/#!/payments.validation/editPreparePayment) diff --git a/src/content/docs/ko/api/payment-api/get-payment-by-impuid-api.mdx b/src/content/docs/ko/api/payment-api/get-payment-by-impuid-api.mdx index 1a44fa15c..3bf2c1917 100644 --- a/src/content/docs/ko/api/payment-api/get-payment-by-impuid-api.mdx +++ b/src/content/docs/ko/api/payment-api/get-payment-by-impuid-api.mdx @@ -4,15 +4,15 @@ description: 포트원 고유번호를 이용하여 결제내역을 조회할 --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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"; -### 포트원 고유번호로 결제내역을 확인합니다. +## 포트원 고유번호로 결제내역을 확인합니다. @@ -323,7 +323,7 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 ```javascript { - // Response + // Response } ``` @@ -332,7 +332,7 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 ```javascript { - // Response + // Response } ``` diff --git a/src/content/docs/ko/api/payment-api/get-payment-by-status-api.mdx b/src/content/docs/ko/api/payment-api/get-payment-by-status-api.mdx index 02b05e4a4..d00750d4a 100644 --- a/src/content/docs/ko/api/payment-api/get-payment-by-status-api.mdx +++ b/src/content/docs/ko/api/payment-api/get-payment-by-status-api.mdx @@ -4,15 +4,15 @@ description: 결제 상태값을 기준으로 거래내역을 조회할 수 있 --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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"; -### 결제상태값으로 결제내역을 복수조회 합니다. +## 결제상태값으로 결제내역을 복수조회 합니다. @@ -387,7 +387,7 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 ```javascript { - // Response + // Response } ``` @@ -396,7 +396,7 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 ```javascript { - // Response + // Response } ``` diff --git a/src/content/docs/ko/api/payment-api/get-payment-list-by-impuid-api.mdx b/src/content/docs/ko/api/payment-api/get-payment-list-by-impuid-api.mdx index 0f6bb94c7..c7a84d120 100644 --- a/src/content/docs/ko/api/payment-api/get-payment-list-by-impuid-api.mdx +++ b/src/content/docs/ko/api/payment-api/get-payment-list-by-impuid-api.mdx @@ -4,421 +4,409 @@ description: 거래고유번호 또는 주문번호로 결제내역을 복수조 --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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"; -### 복수의 포트원 고유번호 또는 고객사 주문번호로 결제내역을 조회합니다. +## 복수의 포트원 고유번호 또는 고객사 주문번호로 결제내역을 조회합니다. - -**호출예시**\ -`/payments?imp_uid[]=imp_448280090638&imp_uid[]=imp_448280090639&merchant_uid[]=merchant_143434085216` - -최대 100개 - - - -### Parameters - -#### Query - - - -**포트원 거래고유번호** - - - -**고객사 주문번호** - - + + **호출예시**\ + `/payments?imp_uid[]=imp_448280090638&imp_uid[]=imp_448280090639&merchant_uid[]=merchant_143434085216` -### Responses + 최대 100개 + - - - -**`code`** **\*** **integer** + ### Parameters -**응답코드** + #### Query -0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 + + **포트원 거래고유번호** + -**`message`** **\*** **string** + + **고객사 주문번호** + -**응답메세지** + ### Responses -code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 + + + + **`code`** **\*** **integer** -**`response`** **(Array\[PaymentAnnotation], optional)** + **응답코드** - - + 0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 - - -**`code`** **\*** **integer** + **`message`** **\*** **string** -**응답코드** + **응답메세지** -0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 + code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 -**`message`** **\*** **string** + **`response`** **(Array\[PaymentAnnotation], optional)** + + -**응답메세지** + + + **`code`** **\*** **integer** -code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 + **응답코드** -**`imp_uid`** **\*** **string** + 0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 -**포트원 거래고유번호** + **`message`** **\*** **string** -**`merchant_uid`** **\*** **string** + **응답메세지** -**고객사 주문번호** + code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 -**`pay_method`** **\*** **string** + **`imp_uid`** **\*** **string** -**결제수단 구분코드** + **포트원 거래고유번호** -- samsung : 삼성페이 -- card : 신용카드 -- trans : 계좌이체 -- vbank : 가상계좌 -- phone : 휴대폰 -- cultureland : 문화상품권 -- smartculture : 스마트문상 -- booknlife : 도서문화상품권 -- happymoney : 해피머니 -- point : 포인트 -- ssgpay : SSGPAY -- lpay : LPAY -- payco : 페이코 -- kakaopay : 카카오페이 -- tosspay : 토스 -- naverpay : 네이버페이 + **`merchant_uid`** **\*** **string** -**`channel`** **\*** **string** + **고객사 주문번호** -**결제환경 구분코드** + **`pay_method`** **\*** **string** -- pc:(인증방식)PC결제 -- mobile:(인증방식)모바일결제 -- api:정기결제 또는 비인증 결제 + **결제수단 구분코드** -**`pg_provider`** **\*** **string** + - samsung : 삼성페이 + - card : 신용카드 + - trans : 계좌이체 + - vbank : 가상계좌 + - phone : 휴대폰 + - cultureland : 문화상품권 + - smartculture : 스마트문상 + - booknlife : 도서문화상품권 + - happymoney : 해피머니 + - point : 포인트 + - ssgpay : SSGPAY + - lpay : LPAY + - payco : 페이코 + - kakaopay : 카카오페이 + - tosspay : 토스 + - naverpay : 네이버페이 -**PG사 구분코드** + **`channel`** **\*** **string** -**`emb_pg_provider`** **\*** **string** + **결제환경 구분코드** -**허브형결제 PG사 구분코드** + - pc:(인증방식)PC결제 + - mobile:(인증방식)모바일결제 + - api:정기결제 또는 비인증 결제 -**`pg_tid`** **\*** **string** + **`pg_provider`** **\*** **string** -**pg사 거래번호** + **PG사 구분코드** -**`pg_id`** **\*** **string** + **`emb_pg_provider`** **\*** **string** -**PG사 MID** + **허브형결제 PG사 구분코드** -**`escrow`** **boolean** + **`pg_tid`** **\*** **string** -**에스크로 결제여부** + **pg사 거래번호** -**`apply_num`** **string** + **`pg_id`** **\*** **string** -**신용카드 승인번호** + **PG사 MID** -**`bank_code`** **string** + **`escrow`** **boolean** -**은행 표준코드** (금융결제원 표준코드: [**`(링크보기)`**](../../tip/pg-1) + **에스크로 결제여부** -**`bank_name`** **string** + **`apply_num`** **string** -**은행 명칭** + **신용카드 승인번호** -실시간 계좌이체 결제건의 경우 + **`bank_code`** **string** -**`card_code`** **string** + **은행 표준코드** (금융결제원 표준코드: [**`(링크보기)`**](../../tip/pg-1) -**카드사 코드번호(금융결제원 표준코드번호 :** [**링크**](https://chaifinance.notion.site/53589280bbc94fab938d93257d452216?v=eb405baf52134b3f90d438e3bf763630) ) + **`bank_name`** **string** -**`card_name`** **string** + **은행 명칭** -**카드사명** + 실시간 계좌이체 결제건의 경우 -**`card_quota`** **integer** + **`card_code`** **string** -**할부개월 수(0이면 일시불)** + **카드사 코드번호(금융결제원 표준코드번호 :** [**링크**](https://chaifinance.notion.site/53589280bbc94fab938d93257d452216?v=eb405baf52134b3f90d438e3bf763630) ) -**`card_number`** **string** + **`card_name`** **string** -**결제에 사용된 마스킹된 카드번호** + **카드사명** -7~12번째 자리를 마스킹하는 것이 일반적이지만, PG사의 정책/설정에 따라 다소 차이가 있을 수 있습니다. + **`card_quota`** **integer** -**`card_type`** **string** + **할부개월 수(0이면 일시불)** -**카드 구분코드** + **`card_number`** **string** -(주의)해당 정보를 제공하지 않는 일부 PG사의 경우 null 로 응답됨(ex. JTNet, 이니시스-빌링) + **결제에 사용된 마스킹된 카드번호** -- 0 : 신용카드 -- 1 : 체크카드 + 7\~12번째 자리를 마스킹하는 것이 일반적이지만, PG사의 정책/설정에 따라 다소 차이가 있을 수 있습니다. -**`vbank_code`** **string** + **`card_type`** **string** -**가상계좌 은행 표준코드(금융결제원 기준)** + **카드 구분코드** -**`vbank_name`** **string** + (주의)해당 정보를 제공하지 않는 일부 PG사의 경우 null 로 응답됨(ex. JTNet, 이니시스-빌링) -**입금받을 가상계좌 은행명** + - 0 : 신용카드 + - 1 : 체크카드 -**`vbank_holder`** **string** + **`vbank_code`** **string** -**입금받을 가상계좌 예금주** + **가상계좌 은행 표준코드(금융결제원 기준)** -**`vbank_date`** **string** + **`vbank_name`** **string** -**입금받을 가상계좌 마감기한 (UNIX timestamp)** + **입금받을 가상계좌 은행명** -**`vbank_issued_at`** **string** + **`vbank_holder`** **string** -**가상계좌 생성 시각 (UNIX timestamp)** + **입금받을 가상계좌 예금주** -**`name`** **string** + **`vbank_date`** **string** -**제품명** + **입금받을 가상계좌 마감기한 (UNIX timestamp)** -**`amount`** **\*** **integer** + **`vbank_issued_at`** **string** -**주문(결제)금액** + **가상계좌 생성 시각 (UNIX timestamp)** -**`cancel_amount`** **integer** + **`name`** **string** -**결제취소금액** + **제품명** -**`currency`** **string** + **`amount`** **\*** **integer** -**통화구분코드** + **주문(결제)금액** -**`buyer_name`** **string** + **`cancel_amount`** **integer** -**주문자명** + **결제취소금액** -**`buyer_email`** **string** + **`currency`** **string** -**주문자 Email주소** + **통화구분코드** -**`buyer_tel`** **string** + **`buyer_name`** **string** -**주문자 전화번호** + **주문자명** -**`buyer_addr`** **string** + **`buyer_email`** **string** -**주문자 주소** + **주문자 Email주소** -**`buyer_postcode`** **string** + **`buyer_tel`** **string** -**주문자 우편번호** + **주문자 전화번호** -**`custom_data`** **string** + **`buyer_addr`** **string** -**고객사 custom 데이터** JSON string으로 전달 + **주문자 주소** -**`user_agent`** **string** + **`buyer_postcode`** **string** -**UserAgent** 구매자가 결제를 시작한 단말기의 UserAgent 문자열 + **주문자 우편번호** -**`status`** **\*** **string** + **`custom_data`** **string** -**결제상태 구분코드** + **고객사 custom 데이터** JSON string으로 전달 -- ready : 미결제 -- paid : 결제완료 -- cancelled : 결제취소 -- failed : 결제실패 + **`user_agent`** **string** -**`started_at`** **\*** **string** + **UserAgent** 구매자가 결제를 시작한 단말기의 UserAgent 문자열 -**결제시작시점 (UNIX timestamp)** + **`status`** **\*** **string** -**`paid_at`** **\*** **string** + **결제상태 구분코드** -**결제완료시점 (UNIX timestamp)**\\ + - ready : 미결제 + - paid : 결제완료 + - cancelled : 결제취소 + - failed : 결제실패 -**`failed_at`** **\*** **string** + **`started_at`** **\*** **string** -**결제실패시점 (UNIX timestamp)** + **결제시작시점 (UNIX timestamp)** -**`cancelled_at`** **\*** **string** + **`paid_at`** **\*** **string** -**결제취소시점 (UNIX timestamp)** + **결제완료시점 (UNIX timestamp)**\\ -**`fail_reason`** **string** + **`failed_at`** **\*** **string** -**결제실패 사유** + **결제실패시점 (UNIX timestamp)** -**`cancel_reason`** **string** + **`cancelled_at`** **\*** **string** -**결제취소 사유** + **결제취소시점 (UNIX timestamp)** -**`receipt_url`** **string** + **`fail_reason`** **string** -**신용카드 매출전표 확인 URL** + **결제실패 사유** -**`cash_receipt_issued`** **boolean** + **`cancel_reason`** **string** -**현금영수증 자동발급 여부** + **결제취소 사유** -**`customer_uid`** **string** + **`receipt_url`** **string** -**해당 결제처리에 사용된 customer_uid** + **신용카드 매출전표 확인 URL** -**`customer_uid_usage`** **string** + **`cash_receipt_issued`** **boolean** -**customer_uid 사용 구분코드** + **현금영수증 자동발급 여부** -- null : 일반결제 -- issue : 빌링키 발급 -- payment : 결제 -- payment.scheduled : 예약결제 + **`customer_uid`** **string** -**`cancel_history`** **(Array\[PaymentCancelAnnotation], optional):** + **해당 결제처리에 사용된 customer\_uid** -**취소/부분취소 내역** + **`customer_uid_usage`** **string** - - + **customer\_uid 사용 구분코드** - - -**cancel\_history array \[]** + - null : 일반결제 + - issue : 빌링키 발급 + - payment : 결제 + - payment.scheduled : 예약결제 -**`pg_tid`** **\*** **string** + **`cancel_history`** **(Array\[PaymentCancelAnnotation], optional):** -**PG사 승인취소번호** + **취소/부분취소 내역** + + -**`amount`** **\*** **integer** + + + **cancel\_history array \[]** -**취소 금액** + **`pg_tid`** **\*** **string** -**`cancelled_at`** **\*** **string** + **PG사 승인취소번호** -**결제취소된 시각 UNIX timestamp** + **`amount`** **\*** **integer** -**`reason`** **\*** **string** + **취소 금액** -**결제취소 사유** + **`cancelled_at`** **\*** **string** -**`receipt_url`** **\*** **string** + **결제취소된 시각 UNIX timestamp** -**취소에 대한 매출전표 확인 URL. PG사에 따라 제공되지 않는 경우도 있음** + **`reason`** **\*** **string** - - + **결제취소 사유** - + **`receipt_url`** **\*** **string** - -```javascript -{ - // Response -} -``` + **취소에 대한 매출전표 확인 URL. PG사에 따라 제공되지 않는 경우도 있음** + + + - - - -```javascript -{ - // Response -} -``` - - - - - -
-

Response Model Schema

+ + ```javascript + { + // Response + } + ``` + -```json -{ - "code": 0, - "message": "string", - "response": [ + + ```javascript { - "imp_uid": "string", - "merchant_uid": "string", - "pay_method": "string", - "channel": "pc", - "pg_provider": "string", - "emb_pg_provider": "string", - "pg_tid": "string", - "pg_id": "string", - "escrow": true, - "apply_num": "string", - "bank_code": "string", - "bank_name": "string", - "card_code": "string", - "card_name": "string", - "card_quota": 0, - "card_number": "string", - "card_type": "null", - "vbank_code": "string", - "vbank_name": "string", - "vbank_num": "string", - "vbank_holder": "string", - "vbank_date": 0, - "vbank_issued_at": 0, - "name": "string", - "amount": 0, - "cancel_amount": 0, - "currency": "string", - "buyer_name": "string", - "buyer_email": "string", - "buyer_tel": "string", - "buyer_addr": "string", - "buyer_postcode": "string", - "custom_data": "string", - "user_agent": "string", - "status": "ready", - "started_at": 0, - "paid_at": 0, - "failed_at": 0, - "cancelled_at": 0, - "fail_reason": "string", - "cancel_reason": "string", - "receipt_url": "string", - "cancel_history": [ - { - "pg_tid": "string", - "amount": 0, - "cancelled_at": 0, - "reason": "string", - "receipt_url": "string" - } - ], - "cancel_receipt_urls": ["string"], - "cash_receipt_issued": true, - "customer_uid": "string", - "customer_uid_usage": "issue" + // Response } - ] -} -``` + ``` + + +
+

Response Model Schema

+ + ```json + { + "code": 0, + "message": "string", + "response": [ + { + "imp_uid": "string", + "merchant_uid": "string", + "pay_method": "string", + "channel": "pc", + "pg_provider": "string", + "emb_pg_provider": "string", + "pg_tid": "string", + "pg_id": "string", + "escrow": true, + "apply_num": "string", + "bank_code": "string", + "bank_name": "string", + "card_code": "string", + "card_name": "string", + "card_quota": 0, + "card_number": "string", + "card_type": "null", + "vbank_code": "string", + "vbank_name": "string", + "vbank_num": "string", + "vbank_holder": "string", + "vbank_date": 0, + "vbank_issued_at": 0, + "name": "string", + "amount": 0, + "cancel_amount": 0, + "currency": "string", + "buyer_name": "string", + "buyer_email": "string", + "buyer_tel": "string", + "buyer_addr": "string", + "buyer_postcode": "string", + "custom_data": "string", + "user_agent": "string", + "status": "ready", + "started_at": 0, + "paid_at": 0, + "failed_at": 0, + "cancelled_at": 0, + "fail_reason": "string", + "cancel_reason": "string", + "receipt_url": "string", + "cancel_history": [ + { + "pg_tid": "string", + "amount": 0, + "cancelled_at": 0, + "reason": "string", + "receipt_url": "string" + } + ], + "cancel_receipt_urls": ["string"], + "cash_receipt_issued": true, + "customer_uid": "string", + "customer_uid_usage": "issue" + } + ] + } + ```
-**Swagger Test Link** - -[**https://api.iamport.kr/#!/payments/getPaymentListByImpUid**](https://api.iamport.kr/#!/payments/getPaymentListByImpUid) + **Swagger Test Link** + [**https://api.iamport.kr/#!/payments/getPaymentListByImpUid**](https://api.iamport.kr/#!/payments/getPaymentListByImpUid) diff --git a/src/content/docs/ko/api/payment-api/get-payment-prepare-by-merchantuid-api.mdx b/src/content/docs/ko/api/payment-api/get-payment-prepare-by-merchantuid-api.mdx index 17c1ce932..342ec570a 100644 --- a/src/content/docs/ko/api/payment-api/get-payment-prepare-by-merchantuid-api.mdx +++ b/src/content/docs/ko/api/payment-api/get-payment-prepare-by-merchantuid-api.mdx @@ -4,103 +4,91 @@ description: 사전등록된 결제금액 정보를 조회합니다 --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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"; -### [**결제금액 사전등록 API**](api-5) 로 등록된 금액을 조회합니다. +## [**결제금액 사전등록 API**](api-5) 로 등록된 금액을 조회합니다. - - - - -### Parameters - -#### Body - - - + -**고객사 주문번호** + ### Parameters - + #### Body - + + + **고객사 주문번호** + + -### Responses + ### Responses - - - -**`code`** **\*** **integer** + + + + **`code`** **\*** **integer** -**응답코드** + **응답코드** -0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 + 0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다 -**`message`** **\*** **string** + **`message`** **\*** **string** -**응답메세지** + **응답메세지** -code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 + code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다 - - **`response (PaymentPrepareAnnotation, optional)`** - + + **`response (PaymentPrepareAnnotation, optional)`** + + + - - + + + **merchant\_uid** **\*** **`string`** - - -**merchant\_uid** **\*** **`string`** + \*\*고객사 주문번호 \*\* -**고객사 주문번호 ** + **`amount`** **\*** **`number`** -**`amount`** **\*** **`number`** - -**`결제 예정 금액`** - - - - - - - -```javascript -{ - // Response -} -``` - - + **`결제 예정 금액`** + + + + + ```javascript + { + // Response + } + ``` +
-

Response Model Schema

- -``` -{ - "code": 0, - "message": "string", - "response": { - "merchant_uid": "string", - "amount": 0 +

Response Model Schema

+ + ```json + { + "code": 0, + "message": "string", + "response": { + "merchant_uid": "string", + "amount": 0 + } } -} -``` - + ```
-**Swagger Test Link** - -[**https://api.iamport.kr/#!/payments.validation/getPaymentPrepareByMerchantUid**](https://api.iamport.kr/#!/payments.validation/getPaymentPrepareByMerchantUid) + **Swagger Test Link** + [**https://api.iamport.kr/#!/payments.validation/getPaymentPrepareByMerchantUid**](https://api.iamport.kr/#!/payments.validation/getPaymentPrepareByMerchantUid) diff --git a/src/content/docs/ko/api/payment-api/prepare-payment-api.mdx b/src/content/docs/ko/api/payment-api/prepare-payment-api.mdx index b31d8c167..d3b02a44e 100644 --- a/src/content/docs/ko/api/payment-api/prepare-payment-api.mdx +++ b/src/content/docs/ko/api/payment-api/prepare-payment-api.mdx @@ -4,15 +4,15 @@ description: 인증 결제시 결제금액을 사전등록 하여 금액 위변 --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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"; -### 인증결제를 진행할 때 결제금액 위변조 시 결제진행자체를 block 하기 위해 결제예정금액을 사전등록하는 기능 +## 인증결제를 진행할 때 결제금액 위변조 시 결제진행자체를 block 하기 위해 결제예정금액을 사전등록하는 기능 @@ -82,7 +82,7 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 ```javascript { - // Response + // Response } ``` diff --git a/src/content/docs/ko/api/payment-api/uq-api.mdx b/src/content/docs/ko/api/payment-api/uq-api.mdx index 88a4b5f03..7f6ec98a1 100644 --- a/src/content/docs/ko/api/payment-api/uq-api.mdx +++ b/src/content/docs/ko/api/payment-api/uq-api.mdx @@ -4,15 +4,15 @@ description: 주문번호를 기준으로 결제내역을 조회합니다. 동 --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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"; -### 주문번호 기준으로 결제내역을 조회합니다. 주문번호 유일성이 유지됩니다.(정렬조건에 따라 최우선 조회건 기준) +## 주문번호 기준으로 결제내역을 조회합니다. 주문번호 유일성이 유지됩니다.(정렬조건에 따라 최우선 조회건 기준) @@ -345,7 +345,7 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 ```javascript { - // Response + // Response } ``` @@ -354,7 +354,7 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 ```javascript { - // Response + // Response } ``` diff --git a/src/content/docs/ko/api/pg-api/save-paymentwall-delivery-api.mdx b/src/content/docs/ko/api/pg-api/save-paymentwall-delivery-api.mdx index ec506edd9..8f868a471 100644 --- a/src/content/docs/ko/api/pg-api/save-paymentwall-delivery-api.mdx +++ b/src/content/docs/ko/api/pg-api/save-paymentwall-delivery-api.mdx @@ -4,15 +4,15 @@ description: 페이먼트월 PG 사 이용시 실물상품 배송등록을 수 --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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"; -### 배송정보를 등록합니다. +## 배송정보를 등록합니다. 이커머스(실물 상품) 비즈니스의 경우 페이먼트월에서 필수적으로 요구되는 배송정보 등록 API @@ -213,7 +213,7 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 ```javascript { - // Response + // Response } ``` diff --git a/src/content/docs/ko/api/rest-api-access-token.mdx b/src/content/docs/ko/api/rest-api-access-token.mdx index 09937ade3..ee6f97fbe 100644 --- a/src/content/docs/ko/api/rest-api-access-token.mdx +++ b/src/content/docs/ko/api/rest-api-access-token.mdx @@ -4,11 +4,11 @@ description: Access Token 을 발급하는 방법을 설명합니다. --- 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"; -### 포트원의 모든 REST API 이용을 위해서는 토큰 발급 및 설정이 필수입니다. +## 포트원의 모든 REST API 이용을 위해서는 토큰 발급 및 설정이 필수입니다. 결제 정보와 같은 사적 리소스(private resource)에 대한 접근 권한을 얻으려면 고객사는 access token을 발급 받아서 포트원 REST API 요청에 포함해야 합니다. @@ -41,19 +41,20 @@ REST API([POST https://api.iamport.kr/users/getToken](https://api.iamport.kr/#!/ ```javascript title="server-side" // 인증 토큰 발급 받기 - axios({ - url: "https://api.iamport.kr/users/getToken", - // POST method - method: "post", - // "Content-Type": "application/json" - headers: { "Content-Type": "application/json" }, - data: { - // REST API키 - imp_key: "imp_apikey", - // REST API Secret - imp_secret: "ekKoeW8RyKuT0zgaZsUtXXTLQ4AhPFW3ZGseDA6bkA5lamv9OqDMnxyeB9wqOsuO9W3Mx9YSJ4dTqJ3f" - } - }); +axios({ + url: "https://api.iamport.kr/users/getToken", + // POST method + method: "post", + // "Content-Type": "application/json" + headers: { "Content-Type": "application/json" }, + data: { + // REST API키 + imp_key: "imp_apikey", + // REST API Secret + imp_secret: + "ekKoeW8RyKuT0zgaZsUtXXTLQ4AhPFW3ZGseDA6bkA5lamv9OqDMnxyeB9wqOsuO9W3Mx9YSJ4dTqJ3f", + }, +}); ``` diff --git a/src/content/docs/ko/api/subscription-payment-api/cancel-scheduled-payment-api.mdx b/src/content/docs/ko/api/subscription-payment-api/cancel-scheduled-payment-api.mdx index b04aebc8b..3ab847874 100644 --- a/src/content/docs/ko/api/subscription-payment-api/cancel-scheduled-payment-api.mdx +++ b/src/content/docs/ko/api/subscription-payment-api/cancel-scheduled-payment-api.mdx @@ -4,15 +4,15 @@ description: 예약된 결제내역을 취소할 수 있는 API 입니다. --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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"; -### 예약된 결제가 실행되기전에 해당 예약을 취소할 수 있는 API 입니다. +## 예약된 결제가 실행되기전에 해당 예약을 취소할 수 있는 API 입니다. @@ -171,7 +171,7 @@ e.g.) KRW, USD, VND, ... Default: KRW ```javascript { - // Response + // Response } ``` diff --git a/src/content/docs/ko/api/subscription-payment-api/get-scheduled-payment-api.mdx b/src/content/docs/ko/api/subscription-payment-api/get-scheduled-payment-api.mdx index c1ac32629..028dc5dd2 100644 --- a/src/content/docs/ko/api/subscription-payment-api/get-scheduled-payment-api.mdx +++ b/src/content/docs/ko/api/subscription-payment-api/get-scheduled-payment-api.mdx @@ -4,15 +4,15 @@ description: 주문번호를 이용하여 예약된 단건결제를 조회할 --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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"; -### 예약 거래주문번호(merchant\_uid)로 결제예약정보를 조회할 수 있습니다. +## 예약 거래주문번호(merchant\_uid)로 결제예약정보를 조회할 수 있습니다. @@ -162,7 +162,7 @@ e.g.) KRW, USD, VND, ... Default: KRW ```javascript { - // Response + // Response } ``` @@ -171,7 +171,7 @@ e.g.) KRW, USD, VND, ... Default: KRW ```javascript { - // Response + // Response } ``` diff --git a/src/content/docs/ko/api/subscription-payment-api/get-scheduled-payments-api.mdx b/src/content/docs/ko/api/subscription-payment-api/get-scheduled-payments-api.mdx index 10ecca153..166f34228 100644 --- a/src/content/docs/ko/api/subscription-payment-api/get-scheduled-payments-api.mdx +++ b/src/content/docs/ko/api/subscription-payment-api/get-scheduled-payments-api.mdx @@ -4,15 +4,15 @@ description: 예약된 결제내역을 조회할 수 있는 API 입니다. --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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"; -### 기간범위를 지정하여 결제예약목록을 조회할 수 있습니다. +## 기간범위를 지정하여 결제예약목록을 조회할 수 있습니다. @@ -204,7 +204,7 @@ e.g.) KRW, USD, VND, ... Default: KRW ```javascript { - // Response + // Response } ``` @@ -213,7 +213,7 @@ e.g.) KRW, USD, VND, ... Default: KRW ```javascript { - // Response + // Response } ``` diff --git a/src/content/docs/ko/api/subscription-payment-api/get-scheduled-payments-by-billing-key-api.mdx b/src/content/docs/ko/api/subscription-payment-api/get-scheduled-payments-by-billing-key-api.mdx index 897d91607..ca452392d 100644 --- a/src/content/docs/ko/api/subscription-payment-api/get-scheduled-payments-by-billing-key-api.mdx +++ b/src/content/docs/ko/api/subscription-payment-api/get-scheduled-payments-by-billing-key-api.mdx @@ -4,15 +4,15 @@ description: customer_uid 기준으로 예약된 내역을 조회할 수 있는 --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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"; -### customer\_uid 별 결제예약목록을 조회할 수 있습니다 +## customer\_uid 별 결제예약목록을 조회할 수 있습니다 @@ -199,7 +199,7 @@ e.g.) KRW, USD, VND, ... Default: KRW ```javascript { - // Response + // Response } ``` @@ -208,7 +208,7 @@ e.g.) KRW, USD, VND, ... Default: KRW ```javascript { - // Response + // Response } ``` diff --git a/src/content/docs/ko/api/tier-api/add-tier-api.mdx b/src/content/docs/ko/api/tier-api/add-tier-api.mdx index f6e2a85f7..993a4dc59 100644 --- a/src/content/docs/ko/api/tier-api/add-tier-api.mdx +++ b/src/content/docs/ko/api/tier-api/add-tier-api.mdx @@ -4,15 +4,15 @@ description: 대표상점에 대한 하위상점의 정보를 등록합니다. --- import Details from "~/components/gitbook/Details.astro"; -import Hint from "~/components/Hint.astro"; import Swagger from "~/components/gitbook/swagger/Swagger.astro"; import SwaggerDescription from "~/components/gitbook/swagger/SwaggerDescription.astro"; import SwaggerParameter from "~/components/gitbook/swagger/SwaggerParameter.astro"; import SwaggerResponse from "~/components/gitbook/swagger/SwaggerResponse.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"; -### 대표상점에 대한 하위상점의 정보를 등록합니다. +## 대표상점에 대한 하위상점의 정보를 등록합니다. @@ -100,7 +100,7 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 ```javascript { - // Response + // Response } ``` @@ -109,7 +109,7 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 ```javascript { - // Response + // Response } ``` @@ -118,7 +118,7 @@ code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같 ```javascript { - // Response + // Response } ``` diff --git a/src/content/docs/ko/auth/guide-1/bill/rest-api.mdx b/src/content/docs/ko/auth/guide-1/bill/rest-api.mdx index 827c095c6..93ebf0be4 100644 --- a/src/content/docs/ko/auth/guide-1/bill/rest-api.mdx +++ b/src/content/docs/ko/auth/guide-1/bill/rest-api.mdx @@ -4,9 +4,9 @@ description: 포트원 REST API 를 이용하여 손쉽게 빌링키를 획득 --- import Codepen from "~/components/gitbook/Codepen.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"; 포트원 REST API 를 이용하여 빌링키를 획득하여 결제를 요청할 수 있습니다. 고객 카드정보를 이용하여 빌링키 발급을 요청하면 포트원 서버가 PG사의 API를 호출하여 빌링키를 발급받습니다. 이 과정에서 @@ -15,136 +15,131 @@ import Tab from "~/components/gitbook/tabs/Tab.astro"; - **장점**: 고객사가 원하는 형태의 화면으로 **카드정보 입력란을 커스터마이징**할 수 있다. - **단점**: **개인정보 이용약관**을 명시해야 하며 PG사 및 카드사 심사가 까다롭고 개인정보 유출에 유의해야 합니다. -#### 고객사 UI/UX 친화적인 결제 환경을 계획하고 계시다면 API 연동 개발을 선택하시면 됩니다. +## 고객사 UI/UX 친화적인 결제 환경을 계획하고 계시다면 API 연동 개발을 선택하시면 됩니다. ### **STEP 01.** 카드 정보 입력받기 -카드 정보를 입력하는 필드들을 다음과 같이 작성합니다. 요청 시 **customer_uid**를 저장 할 히든필드를 +카드 정보를 입력하는 필드들을 다음과 같이 작성합니다. 요청 시 **customer\_uid**를 저장 할 히든필드를 작성합니다. 법인카드(개인명의로 발급된 _기명카드_ 제외)의 경우 `birth` 파라미터에 \_사업자번호 -10자리\_를 입력하시면 됩니다. 결제하기 버튼 클릭 시 입력 값들과 customer_uid로 +10자리\_를 입력하시면 됩니다. 결제하기 버튼 클릭 시 입력 값들과 customer\_uid로 `/subscription/issue-billing`에 대해`POST`요청이 호출되는 예제입니다. -**customer\_uid 란?** + **customer\_uid 란?** -PG사가 발급한 빌링키와 1:1로 맵핑되는 고객사가 지정한 고유값입니다. customer_uid 는 카드번호 단위로구분되서 저장되어야 합니다. - -예) **홍길동** 고객이 **A카드** 빌링키를 요청하는 경우 customer_uid는 **회원별 카드번호 단위**로 고유하게 발급되어야 합니다. + PG사가 발급한 빌링키와 1:1로 맵핑되는 고객사가 지정한 고유값입니다. customer\_uid 는 카드번호 단위로구분되서 저장되어야 합니다. + 예) **홍길동** 고객이 **A카드** 빌링키를 요청하는 경우 customer\_uid는 **회원별 카드번호 단위**로 고유하게 발급되어야 합니다. -이전 빌링키 발급에 사용된 customer\_uid 를 재 사용하는 경우 가장 마지막 빌링키 발급에 사용된 카드번호의 빌링키로 대체됩니다.(**기존에 발급된 빌링키는 자동으로 해지되지 않습니다.**) - + 이전 빌링키 발급에 사용된 customer\_uid 를 재 사용하는 경우 가장 마지막 빌링키 발급에 사용된 카드번호의 빌링키로 대체됩니다.(**기존에 발급된 빌링키는 자동으로 해지되지 않습니다.**) -**빌링키 발급을 위한 카드정보** - -- **카드번호** -- **유효기간** -- **생년월일** -- **비밀번호 앞 두자리** + **빌링키 발급을 위한 카드정보** + - **카드번호** + - **유효기간** + - **생년월일** + - **비밀번호 앞 두자리** - -```html title="client-side" -
- -
- - -
-
- - -
-
- - -
-
- - -
- - -
-``` - - - - -```jsx title="client-side" -// React.js - class CardForm extends React.Components { - constructor(props) { - super(props); - this.state = { - cardNumber: "", - expiry: "", - birth: "", - pwd2Digit: "", - customer_uid: "gildong_0001_1234", - }; - } - ... - handleInputChange = (event) => { - const { value, name } = event.target; - this.setState({ - [name]: value, - }); - }; - ... - handleFormSubmit = (event) => { - event.preventDefault(); - const { cardNumber, expiry, birth, pwd2Digit, customer_uid } = this.state; - axios({ - // 예: https://www.myservice.com/subscription/issue-billing - url: "{빌링키 발급 요청을 받을 서비스 URL}", - method: "post", - data: { - cardNumber, - expiry, - birth, - pwd2Digit, - customer_uid, + + ```html title="client-side" +
+ +
+ + +
+
+ + +
+
+ + +
+
+ + +
+ + +
+ ``` + + + + ```jsx title="client-side" + // React.js + class CardForm extends React.Components { + constructor(props) { + super(props); + this.state = { + cardNumber: "", + expiry: "", + birth: "", + pwd2Digit: "", + customer_uid: "gildong_0001_1234", + }; } - }).then(rsp => { ... - }); - }; - ... - render() { - const { cardNumber, expiry, birth, pwd2Digit } = this.state; - return ( -
- - - - - -
- ) - } - } -``` - - + handleInputChange = (event) => { + const { value, name } = event.target; + this.setState({ + [name]: value, + }); + }; + ... + handleFormSubmit = (event) => { + event.preventDefault(); + const { cardNumber, expiry, birth, pwd2Digit, customer_uid } = this.state; + axios({ + // 예: https://www.myservice.com/subscription/issue-billing + url: "{빌링키 발급 요청을 받을 서비스 URL}", + method: "post", + data: { + cardNumber, + expiry, + birth, + pwd2Digit, + customer_uid, + } + }).then(rsp => { + ... + }); + }; + ... + render() { + const { cardNumber, expiry, birth, pwd2Digit } = this.state; + return ( +
+ + + + + +
+ ) + } + } + ``` + @@ -155,96 +150,98 @@ PG사가 발급한 빌링키와 1:1로 맵핑되는 고객사가 지정한 고 추출합니다.`/subscription/issue-billing`에 대한 `POST`요청을 처리하는 **API endpoint**의 예제입니다. - -```javascript title="server-side" -// "/subscription/issue-billing"에 대한 POST 요청을 처리 - app.post("/subscriptions/issue-billing", async (req, res) => { - try { - const { - card_number, // 카드 번호 - expiry, // 카드 유효기간 - birth, // 생년월일 - pwd_2digit, // 카드 비밀번호 앞 두자리, - customer_uid, // 카드(빌링키)와 1:1로 대응하는 값 - } = req.body; // req의 body에서 카드정보 추출 - ... - } catch (e) { - res.status(400).send(e); - } - }); -``` - - + + ```javascript title="server-side" + // "/subscription/issue-billing"에 대한 POST 요청을 처리 + app.post("/subscriptions/issue-billing", async (req, res) => { + try { + const { + card_number, // 카드 번호 + expiry, // 카드 유효기간 + birth, // 생년월일 + pwd_2digit, // 카드 비밀번호 앞 두자리, + customer_uid, // 카드(빌링키)와 1:1로 대응하는 값 + } = req.body; // req의 body에서 카드정보 추출 + //....중략...... + } catch (e) { + res.status(400).send(e); + } + }); + ``` + ### **STEP 03.** 빌링키 발급 요청 및 응답 처리하기 -당사가 제공하는 [**빌링키 발급 REST API** ](../../../api/api-4/)를 통해 빌링키 발급을 요청하고 결과값에 따라 응답을 반환하는 예제입니다. +당사가 제공하는 [**빌링키 발급 REST API**](../../../api/api-4/)를 통해 빌링키 발급을 요청하고 결과값에 따라 응답을 반환하는 예제입니다. - -```javascript title="server-side" -// "/subscription/issue-billing"에 대한 POST 요청을 처리 + + ```javascript title="server-side" + // "/subscription/issue-billing"에 대한 POST 요청을 처리 app.post("/subscriptions/issue-billing", async (req, res) => { try { const { - card_number, // 카드 번호 - expiry, // 카드 유효기간 - birth, // 생년월일 - pwd_2digit, // 카드 비밀번호 앞 두자리 + card_number, // 카드 번호 + expiry, // 카드 유효기간 + birth, // 생년월일 + pwd_2digit, // 카드 비밀번호 앞 두자리 customer_uid, // 카드(빌링키)와 1:1로 대응하는 값 - } = req.body; // req의 body에서 카드정보 추출 - ... + } = req.body; // req의 body에서 카드정보 추출 + //....중략...... // 인증 토큰 발급 받기 const getToken = await axios({ url: "https://api.iamport.kr/users/getToken", - method: "post", // POST method - headers: { "Content-Type": "application/json" }, + method: "post", // POST method + headers: { "Content-Type": "application/json" }, data: { imp_key: "imp_apikey", // REST API 키 - imp_secret: "ekKoeW8RyKuT0zgaZsUtXXTLQ4AhPFW3ZGseDA6bkA5lamv9OqDMnxyeB9wqOsuO9W3Mx9YSJ4dTqJ3f" - } + imp_secret: + "ekKoeW8RyKuT0zgaZsUtXXTLQ4AhPFW3ZGseDA6bkA5lamv9OqDMnxyeB9wqOsuO9W3Mx9YSJ4dTqJ3f", + }, }); const { access_token } = getToken.data; // 인증 토큰 - ... + //....중략..... // 빌링키 발급 요청 const issueBilling = await axios({ url: `https://api.iamport.kr/subscribe/customers/${customer_uid}`, method: "post", // 인증 토큰 Authorization header에 추가 - headers: { "Authorization": access_token }, + headers: { Authorization: access_token }, data: { card_number, // 카드 번호 - expiry, // 카드 유효기간 - birth, // 생년월일 - pwd_2digit, // 카드 비밀번호 앞 두자리 + expiry, // 카드 유효기간 + birth, // 생년월일 + pwd_2digit, // 카드 비밀번호 앞 두자리 pg: YOUR_PG_HERE, // 빌링키 발급에 사용할 PG - } + }, }); - ... + //...중략... const { code, message } = issueBilling.data; - if (code === 0) { // 빌링키 발급 성공 - res.send({ status: "success", message: "Billing has successfully issued" }); - } else { // 빌링키 발급 실패 + if (code === 0) { + // 빌링키 발급 성공 + res.send({ + status: "success", + message: "Billing has successfully issued", + }); + } else { + // 빌링키 발급 실패 res.send({ status: "failed", message }); } } catch (e) { res.status(400).send(e); } }); -``` - - + ``` + -**REST API 를 이용하기 위해서는** [**Access Token**](../../../api/rest-api-access-token) **획득이 선행되어야 하는점 잊지 마세요** - + **REST API 를 이용하기 위해서는** [**Access Token**](../../../api/rest-api-access-token) **획득이 선행되어야 하는점 잊지 마세요** -**빌링키 발급과 결제 요청을 한번에 하기** - -키인결제 REST API [**`/subscribe/payments/onetime`**](../../../api/api-4/)를 사용하면 빌링키 발급과 최초 결제를 같이 요청할 수 있습니다. + **빌링키 발급과 결제 요청을 한번에 하기** + 키인결제 REST API [**`/subscribe/payments/onetime`**](../../../api/api-4/)를 사용하면 빌링키 발급과 최초 결제를 같이 요청할 수 있습니다. diff --git a/src/content/docs/ko/auth/guide-2/readme.mdx b/src/content/docs/ko/auth/guide-2/readme.mdx index 2e434c563..e4e2367ee 100644 --- a/src/content/docs/ko/auth/guide-2/readme.mdx +++ b/src/content/docs/ko/auth/guide-2/readme.mdx @@ -4,138 +4,129 @@ description: 포트원 결제취소 API를 이용한 결제취소 방법을 안 --- import Codepen from "~/components/gitbook/Codepen.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"; -### **STEP 01.** 취소 요청하기 +## **STEP 01.** 취소 요청하기 필요한 취소 정보를 서버로 전달하여 취소 요청을 진행합니다. 가상계좌 환불의 경우 환불수령 계좌 정보를 추가 파라미터로 전달해야 합니다. 다음은 환불요청을 하기 위해 서버로 해당 정보를 전달하는 예제입니다. - -```html title="client-side" - - - -``` - - - - - - -```jsx title="client-side" -class CancelPay extends React.Component { - cancelPay = () => { - axios({ - url: "{환불요청을 받을 서비스 URL}", // 예: http://www.myservice.com/payments/cancel - method: "POST", - headers: { - "Content-Type": "application/json, - }, - data: { - merchant_uid: "{결제건의 주문번호}", // 주문번호 - cancel_request_amount: 2000, // 환불금액 - reason: "테스트 결제 환불" // 환불사유 - refund_holder: "홍길동", // [가상계좌 환불시 필수입력] 환불 수령계좌 예금주 - refund_bank: "88" // [가상계좌 환불시 필수입력] 환불 수령계좌 은행코드(예: KG이니시스의 경우 신한은행은 88번) - refund_account: "56211105948400" // [가상계좌 환불시 필수입력] 환불 수령계좌 번호 + + ```html title="client-side" + + + + ``` + + + + + + ```jsx title="client-side" + class CancelPay extends React.Component { + cancelPay = () => { + axios({ + url: "{환불요청을 받을 서비스 URL}", // 예: http://www.myservice.com/payments/cancel + method: "POST", + headers: { + "Content-Type": "application/json, + }, + data: { + merchant_uid: "{결제건의 주문번호}", // 주문번호 + cancel_request_amount: 2000, // 환불금액 + reason: "테스트 결제 환불" // 환불사유 + refund_holder: "홍길동", // [가상계좌 환불시 필수입력] 환불 수령계좌 예금주 + refund_bank: "88" // [가상계좌 환불시 필수입력] 환불 수령계좌 은행코드(예: KG이니시스의 경우 신한은행은 88번) + refund_account: "56211105948400" // [가상계좌 환불시 필수입력] 환불 수령계좌 번호 + } + }); + } + render() { + return ; + } + } + ``` + ### **STEP 02.** 결제정보 조회하기 -아래와 같이 결제정보를 저장하는 **`Payments`**라는 테이블을 생성했다고 가정합니다. +아래와 같이 결제정보를 저장하는 \*\*`Payments`\*\*라는 테이블을 생성했다고 가정합니다. ```javascript title="server-side" /* ... model/payments.js ... */ - var mongoose = require('mongoose'); - var Schema = mongoose.Schema; - ... - var PaymentsSchema = new Schema({ - imp_uid: String, // 포트원 `unique key`(환불 요청시 `unique key`로 사용) - merchant_uid: String, // 주문번호(결제정보 조회시 사용) - amount: { type: Number, default: 0 }, // 결제 금액(환불 가능 금액 계산시 사용) - // 환불 된 총 금액(환불 가능 금액 계산시 사용) - cancel_amount: { type: Number, default: 0 }, - ... - }); - ... - module.exports = mongoose.model('Payments', PaymentsSchema); +var mongoose = require("mongoose"); +var Schema = mongoose.Schema; +var PaymentsSchema = new Schema({ + imp_uid: String, // 포트원 `unique key`(환불 요청시 `unique key`로 사용) + merchant_uid: String, // 주문번호(결제정보 조회시 사용) + amount: { type: Number, default: 0 }, // 결제 금액(환불 가능 금액 계산시 사용) + // 환불 된 총 금액(환불 가능 금액 계산시 사용) + cancel_amount: { type: Number, default: 0 }, +}); +module.exports = mongoose.model("Payments", PaymentsSchema); ``` 클라이언트에서 받은 주문번호(**`merchant_uid`**)를 사용해서 해당 주문의 결제정보를 **`Payments`** 테이블에서 조회합니다. ```javascript title="server-side" /* ... 중략 ... */ - var Payments = require('./models/payments'); - app.post('/payments/cancel', async (req, res, next) => { - try { - /* 액세스 토큰(access token) 발급 */ - /* ... 중략 ... */ - /* 결제정보 조회 */ - const { body } = req; - const { merchant_uid } = body; // 클라이언트로부터 전달받은 주문번호 - Payments.find({ merchant_uid }, async function(err, payment) { - if (err) { - return res.json(err); - } - const paymentData = payment[0]; // 조회된 결제정보 - /* 포트원 REST API로 결제환불 요청 */ - ... - }); - } catch (error) { - res.status(400).send(error); - } - }); - +var Payments = require("./models/payments"); +app.post("/payments/cancel", async (req, res, next) => { + try { + /* 액세스 토큰(access token) 발급 */ + /* ... 중략 ... */ + /* 결제정보 조회 */ + const { body } = req; + const { merchant_uid } = body; // 클라이언트로부터 전달받은 주문번호 + Payments.find({ merchant_uid }, async function (err, payment) { + if (err) { + return res.json(err); + } + const paymentData = payment[0]; // 조회된 결제정보 + /* 포트원 REST API로 결제환불 요청 */ + }); + } catch (error) { + res.status(400).send(error); + } +}); ``` ### **STEP 03.** 아임**포트 서버에 취소 요청하기** -취소 요청을 하기 위해서 먼저 [**REST API access token**](../../api/rest-api-access-token) 을 발급받습니다. 발급받은 액세스 토큰(**`access token`**)을 이용하여[ **아임****포트 취소 API**](../../api/api-1/api) 를 호출하여 결제 취소를 요청합니다. +취소 요청을 하기 위해서 먼저 [**REST API access token**](../../api/rest-api-access-token) 을 발급받습니다. 발급받은 액세스 토큰(**`access token`**)을 이용하여[**포트원 취소 API**](../../api/api-1/api) 를 호출하여 결제 취소를 요청합니다. -**휴대폰 소액결제 환불 시 유의사항** - -- **결제가 이루어진 월과 환불을 요청하는 월이 다를 경우, 전액환불도 불가능**합니다. 예를 들어, 1월 31일 결제건은 2월 1일에 환불할 수 없습니다. + **휴대폰 소액결제 환불 시 유의사항** + - **결제가 이루어진 월과 환불을 요청하는 월이 다를 경우, 전액환불도 불가능**합니다. 예를 들어, 1월 31일 결제건은 2월 1일에 환불할 수 없습니다. #### 아래는 환불요청 시 유의해야 하는 파라미터들입니다. @@ -152,68 +143,66 @@ class CancelPay extends React.Component { > **환불 가능 금액**(`checksum`) > -> 환불이 가능한 금액을 입력합니다. 예를 들어, 10**,**000원짜리 제품의 `checksum`은 10,000입니다. +> 환불이 가능한 금액을 입력합니다. 예를 들어, 10\*\*,\*\*000원짜리 제품의 `checksum`은 10,000입니다. > 만약 10,000원짜리 제품이 과거 1,000원 부분환불 되었다면, 이후 환불시 `checksum`은 > 9,000입니다.입력된 `checksum`을 사용해서 서버와 포트원 서버간에 환불 가능 금액이 일치하는지 > 확인합니다. 만약 일치하지 않으면 환불 요청은 실패하며 미 입력시 검증은 실행되지 않습니다. -**checksum을 입력해야 하는 이유** + **checksum을 입력해야 하는 이유** -`checksum`은 필수입력은 아니지만 **서버와 포트원 서버간에 환불 가능 금액을 검증하기** 위해서 입력을 권장합니다. + `checksum`은 필수입력은 아니지만 **서버와 포트원 서버간에 환불 가능 금액을 검증하기** 위해서 입력을 권장합니다. -예를 들어, 10**,**000원짜리 제품에 대한 1,000원 부분환불 요청이 포트원 서버에서 완료하였으나 고객사가 서버 혹은 DB오류로 이를 반영하지 못했다면? 포트원 서버의 checksum은 9,000이 되고, 고객사 서버의 checksum은 그대로 10,000이 됩니다. - -이후 남은 금액을 환불하려고 할때 `checksum(10,000)`을 입력하면, 해당 값이 포트원 서버의 `checksum(9,000)`과 일치하지 않으므로 요청은 실패합니다. + 예를 들어, 10\*\*,\*\*000원짜리 제품에 대한 1,000원 부분환불 요청이 포트원 서버에서 완료하였으나 고객사가 서버 혹은 DB오류로 이를 반영하지 못했다면? 포트원 서버의 checksum은 9,000이 되고, 고객사 서버의 checksum은 그대로 10,000이 됩니다. + 이후 남은 금액을 환불하려고 할때 `checksum(10,000)`을 입력하면, 해당 값이 포트원 서버의 `checksum(9,000)`과 일치하지 않으므로 요청은 실패합니다. #### 아래는 환불 요청을 하는 예제입니다. ```javascript title="Node.js" /* ... 중략 ... */ - app.post('/payments/cancel', async (req, res, next) => { - try { - /* 액세스 토큰(access token) 발급 */ +app.post("/payments/cancel", async (req, res, next) => { + try { + /* 액세스 토큰(access token) 발급 */ + /* ... 중략 ... */ + /* 결제정보 조회 */ + const { body } = req; + // 클라이언트로부터 전달받은 주문번호, 환불사유, 환불금액 + const { merchant_uid, reason, cancel_request_amount } = body; + Payments.find({ merchant_uid }, async function (err, payment) { /* ... 중략 ... */ - /* 결제정보 조회 */ - const { body } = req; - // 클라이언트로부터 전달받은 주문번호, 환불사유, 환불금액 - const { merchant_uid, reason, cancel_request_amount } = body; - Payments.find({ merchant_uid }, async function(err, payment) { - /* ... 중략 ... */ - const paymentData = payment[0]; // 조회된 결제정보 - // 조회한 결제정보로부터 imp_uid, amount(결제금액), cancel_amount(환불된 총 금액) 추출 - const { imp_uid, amount, cancel_amount } = paymentData; - // 환불 가능 금액(= 결제금액 - 환불 된 총 금액) 계산 - const cancelableAmount = amount - cancel_amount; - if (cancelableAmount <= 0) { // 이미 전액 환불된 경우 - return res.status(400).json({ message: "이미 전액환불된 주문입니다." }); - } - ... - /* 포트원 REST API로 결제환불 요청 */ - const getCancelData = await axios({ - url: "https://api.iamport.kr/payments/cancel", - method: "post", - headers: { - "Content-Type": "application/json", - "Authorization": access_token // 포트원 서버로부터 발급받은 엑세스 토큰 - }, - data: { - reason, // 고객사 클라이언트로부터 받은 환불사유 - imp_uid, // imp_uid를 환불 `unique key`로 입력 - amount: cancel_request_amount, // 고객사 클라이언트로부터 받은 환불금액 - checksum: cancelableAmount // [권장] 환불 가능 금액 입력 - } - }); - const { response } = getCancelData.data; // 환불 결과 - /* 환불 결과 동기화 */ - ... + const paymentData = payment[0]; // 조회된 결제정보 + // 조회한 결제정보로부터 imp_uid, amount(결제금액), cancel_amount(환불된 총 금액) 추출 + const { imp_uid, amount, cancel_amount } = paymentData; + // 환불 가능 금액(= 결제금액 - 환불 된 총 금액) 계산 + const cancelableAmount = amount - cancel_amount; + if (cancelableAmount <= 0) { + // 이미 전액 환불된 경우 + return res.status(400).json({ message: "이미 전액환불된 주문입니다." }); + } + /* 포트원 REST API로 결제환불 요청 */ + const getCancelData = await axios({ + url: "https://api.iamport.kr/payments/cancel", + method: "post", + headers: { + "Content-Type": "application/json", + Authorization: access_token, // 포트원 서버로부터 발급받은 엑세스 토큰 + }, + data: { + reason, // 고객사 클라이언트로부터 받은 환불사유 + imp_uid, // imp_uid를 환불 `unique key`로 입력 + amount: cancel_request_amount, // 고객사 클라이언트로부터 받은 환불금액 + checksum: cancelableAmount, // [권장] 환불 가능 금액 입력 + }, }); - } catch (error) { - res.status(400).send(error); - } - }) + const { response } = getCancelData.data; // 환불 결과 + /* 환불 결과 동기화 */ + }); + } catch (error) { + res.status(400).send(error); + } +}); ``` ### **STEP 04.** 환불 결과 저장하기 @@ -244,7 +233,7 @@ app.post("/payments/cancel", async (req, res, next) => { return res.json(err); } res.json(payment); // 고객사 클라이언트로 환불 결과 반환 - } + }, ); }); } catch (error) { @@ -254,10 +243,9 @@ app.post("/payments/cancel", async (req, res, next) => { ``` -**취소 시 유의할 점** - -REST API[**(POST https://api.iamport.kr/payments/cancel)**](../../api/api-1/api) 요청에 대한 **응답 코드가 200**이라도 응답 body의 code가 0이 아니면 **환불에 실패했다는 의미**입니다. 실패 사유는 body의 message를 통해 확인하셔야 합니다. + **취소 시 유의할 점** + REST API[**(POST https://api.iamport.kr/payments/cancel)**](../../api/api-1/api) 요청에 대한 **응답 코드가 200**이라도 응답 body의 code가 0이 아니면 **환불에 실패했다는 의미**입니다. 실패 사유는 body의 message를 통해 확인하셔야 합니다. ### **STEP 04.** 환불 응답 처리하기 @@ -265,46 +253,43 @@ REST API[**(POST https://api.iamport.kr/payments/cancel)**](../../api/api-1/api) 취소요청에 대한 응답을 클라이언트에게 처리하는 로직을 아래와 같이 작성합니다. - -```html title="client-side" - - - -``` - - - - -```jsx title="client-side" -class CancelPay extends React.Component { - cancelPay = () => { - axios({ - /* ... 중략 ... */ - }).then(response => { // 환불 성공시 로직 - alert("환불 성공"); - }).catch(error => { // 환불 실패시 로직 - alert("환불 실패"); - }); - } - ... - render() { - return ; - } -} -``` - - + + ```html title="client-side" + + + + ``` + + + + ```jsx title="client-side" + class CancelPay extends React.Component { + cancelPay = () => { + axios({ + /* ... 중략 ... */ + }).then(response => { // 환불 성공시 로직 + alert("환불 성공"); + }).catch(error => { // 환불 실패시 로직 + alert("환불 실패"); + }); + } + render() { + return ; + } + } + ``` + diff --git a/src/content/docs/ko/auth/guide/2.mdx b/src/content/docs/ko/auth/guide/2.mdx index f62723afe..1693a9ebb 100644 --- a/src/content/docs/ko/auth/guide/2.mdx +++ b/src/content/docs/ko/auth/guide/2.mdx @@ -3,32 +3,30 @@ title: 2. 객체 초기화 하기 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 객체를 초기화 합니다. +## 주문 페이지에서 고객사 식별코드를 이용하여 IMP 객체를 초기화 합니다. -아래 초기화 함수를 **2회 이상** 중복되게 호출하지 않도록 주의해주세요. + 아래 초기화 함수를 **2회 이상** 중복되게 호출하지 않도록 주의해주세요. - -```javascript title="client-side" -IMP.init('고객사 식별코드') // 예: 'imp00000000a' -``` - + + ```javascript title="client-side" + IMP.init("고객사 식별코드"); // 예: 'imp00000000a' + ``` + -  - -#### 하위상점 결제창 호출 방법 +## 하위상점 결제창 호출 방법 하위 상점인 경우 `IMP.init()` 대신, `IMP.agency('고객사 식별코드', '하위 상점 티어코드')`를 호출해야 합니다. ```javascript // IMP.init() 대신 아래 함수를 사용해야함 -IMP.agency('고객사 식별코드', '티어코드') // 예: 'imp00000000a', '123' +IMP.agency("고객사 식별코드", "티어코드"); // 예: 'imp00000000a', '123' ``` diff --git a/src/content/docs/ko/auth/guide/3.mdx b/src/content/docs/ko/auth/guide/3.mdx index d02c5a027..c990b9f3a 100644 --- a/src/content/docs/ko/auth/guide/3.mdx +++ b/src/content/docs/ko/auth/guide/3.mdx @@ -3,10 +3,10 @@ title: 3. 결제 요청하기 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 Youtube from "~/components/gitbook/Youtube.astro"; +import Hint from "~/components/Hint.astro"; [**IMP 객체 초기화**](2)가 완료 되었으면 이제 결제창을 호출할 차례입니다. @@ -15,22 +15,26 @@ import Youtube from "~/components/gitbook/Youtube.astro"; ```javascript - function requestPay() { - IMP.request_pay({ +function requestPay() { + IMP.request_pay( + { pg: "kcp.{상점ID}", pay_method: "card", - merchant_uid: "ORD20180131-0000011", // 주문번호 + merchant_uid: "ORD20180131-0000011", // 주문번호 name: "노르웨이 회전 의자", - amount: 64900, // 숫자 타입 + amount: 64900, // 숫자 타입 buyer_email: "gildong@gmail.com", buyer_name: "홍길동", buyer_tel: "010-4242-4242", buyer_addr: "서울특별시 강남구 신사동", - buyer_postcode: "01181" - }, function (rsp) { // callback + buyer_postcode: "01181", + }, + function (rsp) { + // callback //rsp.imp_uid 값으로 결제 단건조회 API를 호출하여 결제결과를 판단합니다. - }); - } + }, + ); +} ``` @@ -52,13 +56,9 @@ class RequestPay extends React.Component { buyer_postcode: "01181" }, rsp => { // callback if (rsp.success) { - ..., // 결제 성공 시 로직, - ... } else { - ..., // 결제 실패 시 로직, - ... } }); } @@ -68,11 +68,12 @@ class RequestPay extends React.Component { ```javascript - + }, + ); + }, + }, +}; ``` diff --git a/src/content/docs/ko/auth/guide/4/iframe.mdx b/src/content/docs/ko/auth/guide/4/iframe.mdx index f7e30500a..7ddf3e6bd 100644 --- a/src/content/docs/ko/auth/guide/4/iframe.mdx +++ b/src/content/docs/ko/auth/guide/4/iframe.mdx @@ -3,12 +3,12 @@ title: iframe 결제창 결과처리 description: 대부분의 PC환경에서 적용되는 iframe 방식 결제창 환경에서의 결과처리 방법을 안내합니다. --- -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"; -#### **iframe** 이란? +## iframe 이란? **다른 HTML 페이지를 현재 페이지에 포함**시킬 수 있는 요소입니다.\ 자세한 내용은 [MDN iframe 문서](https://developer.mozilla.org/ko/docs/Web/HTML/Element/iframe)를 참고해주세요. @@ -22,9 +22,12 @@ import Tab from "~/components/gitbook/tabs/Tab.astro"; ```javascript -IMP.request_pay({ /** 요청 객체를 추가해주세요 */ }, - rsp => { - if (rsp.success) { +IMP.request_pay( + { + /** 요청 객체를 추가해주세요 */ + }, + (rsp) => { + if (rsp.success) { // axios로 HTTP 요청 axios({ url: "{서버의 결제 정보를 받는 endpoint}", @@ -32,41 +35,48 @@ IMP.request_pay({ /** 요청 객체를 추가해주세요 */ }, headers: { "Content-Type": "application/json" }, data: { imp_uid: rsp.imp_uid, - merchant_uid: rsp.merchant_uid - } + merchant_uid: rsp.merchant_uid, + }, }).then((data) => { // 서버 결제 API 성공시 로직 - }) + }); } else { alert(`결제에 실패하였습니다. 에러 내용: ${rsp.error_msg}`); } - }); + }, +); ``` ```javascript -IMP.request_pay({ /** 요청 객체를 추가해주세요 */ }, +IMP.request_pay( + { + /** 요청 객체를 추가해주세요 */ + }, function (rsp) { if (rsp.success) { // 결제 성공 시: 결제 승인 또는 가상계좌 발급에 성공한 경우 // jQuery로 HTTP 요청 - jQuery.ajax({ - url: "{서버의 결제 정보를 받는 고객사 endpoint}", - method: "POST", - headers: { "Content-Type": "application/json" }, - data: { - imp_uid: rsp.imp_uid, // 결제 고유번호 - merchant_uid: rsp.merchant_uid // 주문번호 - } - }).done(function (data) { - // 고객사 서버 결제 API 성공시 로직 - }) + jQuery + .ajax({ + url: "{서버의 결제 정보를 받는 고객사 endpoint}", + method: "POST", + headers: { "Content-Type": "application/json" }, + data: { + imp_uid: rsp.imp_uid, // 결제 고유번호 + merchant_uid: rsp.merchant_uid, // 주문번호 + }, + }) + .done(function (data) { + // 고객사 서버 결제 API 성공시 로직 + }); } else { alert("결제에 실패하였습니다. 에러 내용: " + rsp.error_msg); } - }); + }, +); ``` diff --git a/src/content/docs/ko/auth/guide/4/redirect.mdx b/src/content/docs/ko/auth/guide/4/redirect.mdx index f8049734b..a9bd8f1cd 100644 --- a/src/content/docs/ko/auth/guide/4/redirect.mdx +++ b/src/content/docs/ko/auth/guide/4/redirect.mdx @@ -4,55 +4,53 @@ description: 새로운 창으로 리디렉션되어 결제가 진행되는 환 --- 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"; > 아래 예제 코드는 결제창 형태가 **새로운 페이지로 리디렉션되어** 결제가 진행되는 대부분의 **모바일 환경**에서의 결제요청애 대한 응답을 처리하는 부분입니다. - -```javascript -IMP.request_pay({ - /* 결제 요청 객체를 채워주세요. */ - m_redirect_url: "{리디렉션 될 URL}" -}, /* callback */); // 리디렉션 방식의 경우 callback은 실행되지 않습니다. -``` - - + + ```javascript + IMP.request_pay( + { + /* 결제 요청 객체를 채워주세요. */ + m_redirect_url: "{리디렉션 될 URL}", + } /* callback */, + ); // 리디렉션 방식의 경우 callback은 실행되지 않습니다. + ``` + -위와 같이 **request_pay** 함수 파라미터로 **m_redirect_url** 을 설정하면 **결제 완료** 이후 해당 URL 주소로 결제 결과를 **쿼리스트링(Query String)** 형태로 전송해 드립니다. +위와 같이 **request\_pay** 함수 파라미터로 **m\_redirect\_url** 을 설정하면 **결제 완료** 이후 해당 URL 주소로 결제 결과를 **쿼리스트링(Query String)** 형태로 전송해 드립니다. -**Query String 이란?** - -URL 뒤에 데이터를 전달하는 가장 단순한 방법으로 주로 GET 요청과 함께 데이터를 전송할 때 사용합니다. + **Query String 이란?** + URL 뒤에 데이터를 전달하는 가장 단순한 방법으로 주로 GET 요청과 함께 데이터를 전송할 때 사용합니다. -결제 결과를 수신받을 endpoint url 주소를 m_redirect_url 에 설정하시면 결제결과 수신이 가능합니다. +결제 결과를 수신받을 endpoint url 주소를 m\_redirect\_url 에 설정하시면 결제결과 수신이 가능합니다. 아래 파라미터를 설정하신 URL 을 통해 Query String 형태로 수신받을수 있습니다. 아래는 Query String 으로 리디렉션되는 URL 예제입니다. - -```url -curl https://myservice.com/payments/complete?imp_uid=결제건을_특정하는_포트원_번호&merchant_uid=고객사_주문번호&imp_success=true -``` - - - - -``` -curl https://myservice.com/payments/complete?imp_uid=결제건을_특정하는_포트원_번호&merchant_uid=고객사_주문번호&imp_success=false&error_code=에러_코드(현재_정리된_체계는_없음)&error_msg=에러_메시지 -``` - - + + ```url + curl https://myservice.com/payments/complete?imp_uid=결제건을_특정하는_포트원_번호&merchant_uid=고객사_주문번호&imp_success=true + ``` + + + + ```url + curl https://myservice.com/payments/complete?imp_uid=결제건을_특정하는_포트원_번호&merchant_uid=고객사_주문번호&imp_success=false&error_code=에러_코드(현재_정리된_체계는_없음)&error_msg=에러_메시지 + ``` + | 파라미터명 | 설명 | 비고 | @@ -67,36 +65,33 @@ curl https://myservice.com/payments/complete?imp_uid=결제건을_특정하는_ > > `결제완료`는 아래의 모든 경우를 포함합니다. > -> 1. **결제 성공**(결제 상태: `paid`, imp_success: `true`) -> 2. **결제 실패**(결제 상태: `failed`, imp_success: `false`) +> 1. **결제 성공**(결제 상태: `paid`, imp\_success: `true`) +> 2. **결제 실패**(결제 상태: `failed`, imp\_success: `false`) > 3. PG 모듈 설정이 올바르지 않아, **결제 창이 열리지 않음** > 4. 사용자가 임의로 X 버튼이나 취소 버튼을 눌러 **결제를 종료**함 > 5. 카드 정보 불일치, 한도 초과, 잔액 부족 등의 사유로 **결제가 중단**됨 -> 6. 가상계좌 **발급 완료(**결제 상태: `ready`, imp_success: `true`) +> 6. 가상계좌 \*\*발급 완료(\*\*결제 상태: `ready`, imp\_success: `true`) -**결제창이 리디렉션되어 새로운 페이지에서 활성화되는 경우 결제 결과는 callback 으로 받을 수 없습니다.** - + **결제창이 리디렉션되어 새로운 페이지에서 활성화되는 경우 결제 결과는 callback 으로 받을 수 없습니다.** -최종 결제결과 로직처리는 반드시 [**웹훅**](../../../result/webhook)을 이용하여 안정적으로 처리해 주셔야 합니다. - -웹훅연동을 생략하시는 경우 결제결과를 정상적으로 수신받지 못하는 상황이 발생합니다. + 최종 결제결과 로직처리는 반드시 [**웹훅**](../../../result/webhook)을 이용하여 안정적으로 처리해 주셔야 합니다. + 웹훅연동을 생략하시는 경우 결제결과를 정상적으로 수신받지 못하는 상황이 발생합니다. -**imp\_success 파라미터** - -`imp_success` 파라미터는 **결제 프로세스 정상 종료 -여부**를 의미합니다. 하지만 클라이언트 상에서 자바스크립트 함수를 호출해서 결제창이 -열리므로 **결제금액이 위변조 되었을 가능성**이 있기 때문에 **이 값으로 결제의 성공 -여부를 판단해서는 안됩니다**. 결제의 성공 여부에 따라 아래와 같이 처리합니다. + **imp\_success 파라미터** -- imp_success = true: 결제 정보(imp_uid, merchant_uid)를 서버에 전달해서 결제금액의 위변조 여부를 검증한 후 최종적으로 결제 성공 여부를 판단해야 합니다. -- Imp_success = false: 결제가 실패했음을 사용자에게 알립니다. + `imp_success` 파라미터는 **결제 프로세스 정상 종료 + 여부**를 의미합니다. 하지만 클라이언트 상에서 자바스크립트 함수를 호출해서 결제창이 + 열리므로 **결제금액이 위변조 되었을 가능성**이 있기 때문에 **이 값으로 결제의 성공 + 여부를 판단해서는 안됩니다**. 결제의 성공 여부에 따라 아래와 같이 처리합니다. -\* 일부 PG사에 한해 `imp_success`가 아닌 `success` 파라미터가 전달되거나 아예 전달되지 않는 경우(예: KG이니시스 - 실시간 계좌이체)도 있으니 주의하셔야 합니다. + - imp\_success = true: 결제 정보(imp\_uid, merchant\_uid)를 서버에 전달해서 결제금액의 위변조 여부를 검증한 후 최종적으로 결제 성공 여부를 판단해야 합니다. + - Imp\_success = false: 결제가 실패했음을 사용자에게 알립니다. + \* 일부 PG사에 한해 `imp_success`가 아닌 `success` 파라미터가 전달되거나 아예 전달되지 않는 경우(예: KG이니시스 - 실시간 계좌이체)도 있으니 주의하셔야 합니다. diff --git a/src/content/docs/ko/auth/guide/5/post.mdx b/src/content/docs/ko/auth/guide/5/post.mdx index 6e93a8d8c..b2f9d6f43 100644 --- a/src/content/docs/ko/auth/guide/5/post.mdx +++ b/src/content/docs/ko/auth/guide/5/post.mdx @@ -3,142 +3,137 @@ title: 결제정보 사후 검증하기 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"; 결제 정보를 사후 검증하는 과정은 크게 세 단계로 이루어집니다. - 응답받은 내용을 바탕으로 실 결제 금액과 결제요청금액(고객사 자체 데이터베이스)을 비교 -- 결제 상세내역 조회를 위해 포트원 [**결제 단건 조회 API** ](https://developers.portone.io/api/rest-v1/payment#get%20%2Fpayments%2F%7Bimp_uid%7D)요청 -- 포트원 결제고유번호(**imp_uid**), 고객사 주문번호(**merchant_uid**)를 프론트엔드로부터 수신 +- 결제 상세내역 조회를 위해 포트원 [**결제 단건 조회 API**](https://developers.portone.io/api/rest-v1/payment#get%20%2Fpayments%2F%7Bimp_uid%7D)요청 +- 포트원 결제고유번호(**imp\_uid**), 고객사 주문번호(**merchant\_uid**)를 프론트엔드로부터 수신 -### **STEP 01** 결제결과 서버 수신 +## **STEP 01** 결제결과 서버 수신 - -결제정보를 받은 고객사 endpoint URL 에 대한 POST 요청을 수신하는 예제 - -```javascript -app.use(bodyParser.json()); -// "{서버의 결제 정보를 받는 고객사 endpoint}" POST 요청 수신부 -app.post("/payments/complete", async (req, res) => { - try { - // req의 body에서 imp_uid, merchant_uid 추출 - const { imp_uid, merchant_uid } = req.body; - } catch (e) { - res.status(400).send(e); - } -}); -``` - - + + 결제정보를 받은 고객사 endpoint URL 에 대한 POST 요청을 수신하는 예제 + + ```javascript + app.use(bodyParser.json()); + // "{서버의 결제 정보를 받는 고객사 endpoint}" POST 요청 수신부 + app.post("/payments/complete", async (req, res) => { + try { + // req의 body에서 imp_uid, merchant_uid 추출 + const { imp_uid, merchant_uid } = req.body; + } catch (e) { + res.status(400).send(e); + } + }); + ``` + ### **STEP 02** 결제내역 단건 조회 - -수신받은 포트원 **결제고유번호**(imp\_uid)로 [**결제단건조회**](https://api.iamport.kr/#!/payments/getPaymentByImpUid) **API** 를 호출하여 결제정보 획득 예제 - -```javascript -app.use(bodyParser.json()); -app.post("/payments/complete", async (req, res) => { - try { - // req의 body에서 imp_uid, merchant_uid 추출 - const { imp_uid, merchant_uid } = req.body; - ... - // 액세스 토큰(access token) 발급 받기 - const getToken = await axios({ - url: "https://api.iamport.kr/users/getToken", - method: "post", // POST method - headers: { "Content-Type": "application/json" }, - data: { - imp_key: "imp_apikey", // REST API 키 - imp_secret: "ekKoeW8RyKuT0zgaZsUtXXTLQ4AhPFW3ZGseDA6bkA5lamv9OqDMnxyeB9wqOsuO9W3Mx9YSJ4dTqJ3f" // REST API Secret + + 수신받은 포트원 **결제고유번호**(imp\_uid)로 [**결제단건조회**](https://api.iamport.kr/#!/payments/getPaymentByImpUid) **API** 를 호출하여 결제정보 획득 예제 + + ```javascript + app.use(bodyParser.json()); + app.post("/payments/complete", async (req, res) => { + try { + // req의 body에서 imp_uid, merchant_uid 추출 + const { imp_uid, merchant_uid } = req.body; + // 액세스 토큰(access token) 발급 받기 + const getToken = await axios({ + url: "https://api.iamport.kr/users/getToken", + method: "post", // POST method + 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 getPaymentData = await axios({ + // imp_uid 전달 + url: `https://api.iamport.kr/payments/${imp_uid}`, + // GET method + method: "get", + // 인증 토큰 Authorization header에 추가 + headers: { Authorization: access_token }, + }); + const paymentData = getPaymentData.data.response; // 조회한 결제 정보 + } catch (e) { + res.status(400).send(e); } }); - const { access_token } = getToken.data; // 인증 토큰 - ... - // imp_uid로 포트원 서버에서 결제 정보 조회 - const getPaymentData = await axios({ - // imp_uid 전달 - url: `https://api.iamport.kr/payments/${imp_uid}`, - // GET method - method: "get", - // 인증 토큰 Authorization header에 추가 - headers: { "Authorization": access_token } - }); - const paymentData = getPaymentData.data.response; // 조회한 결제 정보 - ... - } catch (e) { - res.status(400).send(e); - } -}); -``` - - + ``` + ### **STEP 03** 결제정보 검증 - -결제된 실 금액과 요청 금액을 비교하여 **결제금액 위변조여부 검증** 및 DB저장 예시 - -```javascript -app.use(bodyParser.json()); -app.post("/payments/complete", async (req, res) => { - try { - // req의 body에서 imp_uid, merchant_uid 추출 - const { imp_uid, merchant_uid } = req.body; - - // 액세스 토큰(access token) 발급 받기 - // 코드 생략 - - // imp_uid로 포트원 서버에서 결제 정보 조회 - // 코드 생략 - - const paymentData = getPaymentData.data.response; // 조회한 결제 정보 - // ... - // DB에서 결제되어야 하는 금액 조회 - const order = await Orders.findById(paymentData.merchant_uid); - const amountToBePaid = order.amount; // 결제 되어야 하는 금액 - // ... - // 결제 검증하기 - const { amount, status } = paymentData; - // 결제금액 일치. 결제 된 금액 === 결제 되어야 하는 금액 - if (amount === amountToBePaid) { - await Orders.findByIdAndUpdate(merchant_uid, { $set: paymentData }); // DB에 결제 정보 저장 - // ... - switch (status) { - case "ready": // 가상계좌 발급 - // DB에 가상계좌 발급 정보 저장 - const { vbank_num, vbank_date, vbank_name } = paymentData; - await Users.findByIdAndUpdate("/* 고객 id */", { - $set: { vbank_num, vbank_date, vbank_name }, - }); - // 가상계좌 발급 안내 문자메시지 발송 - SMS.send({ - text: `가상계좌 발급이 성공되었습니다. 계좌 정보 ${vbank_num} ${vbank_date} ${vbank_name}`, - }); - res.send({ status: "vbankIssued", message: "가상계좌 발급 성공" }); - break; - case "paid": // 결제 완료 - res.send({ status: "success", message: "일반 결제 성공" }); - break; + + 결제된 실 금액과 요청 금액을 비교하여 **결제금액 위변조여부 검증** 및 DB저장 예시 + + ```javascript + app.use(bodyParser.json()); + app.post("/payments/complete", async (req, res) => { + try { + // req의 body에서 imp_uid, merchant_uid 추출 + const { imp_uid, merchant_uid } = req.body; + + // 액세스 토큰(access token) 발급 받기 + // 코드 생략 + + // imp_uid로 포트원 서버에서 결제 정보 조회 + // 코드 생략 + + const paymentData = getPaymentData.data.response; // 조회한 결제 정보 + // ... + // DB에서 결제되어야 하는 금액 조회 + const order = await Orders.findById(paymentData.merchant_uid); + const amountToBePaid = order.amount; // 결제 되어야 하는 금액 + // ... + // 결제 검증하기 + const { amount, status } = paymentData; + // 결제금액 일치. 결제 된 금액 === 결제 되어야 하는 금액 + if (amount === amountToBePaid) { + await Orders.findByIdAndUpdate(merchant_uid, { $set: paymentData }); // DB에 결제 정보 저장 + // ... + switch (status) { + case "ready": // 가상계좌 발급 + // DB에 가상계좌 발급 정보 저장 + const { vbank_num, vbank_date, vbank_name } = paymentData; + await Users.findByIdAndUpdate("/* 고객 id */", { + $set: { vbank_num, vbank_date, vbank_name }, + }); + // 가상계좌 발급 안내 문자메시지 발송 + SMS.send({ + text: `가상계좌 발급이 성공되었습니다. 계좌 정보 ${vbank_num} ${vbank_date} ${vbank_name}`, + }); + res.send({ status: "vbankIssued", message: "가상계좌 발급 성공" }); + break; + case "paid": // 결제 완료 + res.send({ status: "success", message: "일반 결제 성공" }); + break; + } + } else { + // 결제금액 불일치. 위/변조 된 결제 + throw { status: "forgery", message: "위조된 결제시도" }; + } + } catch (e) { + res.status(400).send(e); } - } else { - // 결제금액 불일치. 위/변조 된 결제 - throw { status: "forgery", message: "위조된 결제시도" }; - } - } catch (e) { - res.status(400).send(e); - } -}); -``` - - + }); + ``` + 처음 요청한 금액은 **`merchant_uid`** 로 데이터베이스에서 조회하고 실제 결제금액은 **`imp_uid`로 @@ -146,11 +141,9 @@ app.post("/payments/complete", async (req, res) => { 결제 상태(`status`**)에 따라 알맞은 응답을 반환하고 실패 시 에러 메세지를 출력합니다. -결제결과 DB 처리는 [**웹훅(Webhook)을 연동**](../../../result/webhook)하여 수신되는 데이터를 기준으로 처리하셔야 결제결과 누락없이 안정적인 결과처리를 완료하실 수 있습니다. - + 결제결과 DB 처리는 [**웹훅(Webhook)을 연동**](../../../result/webhook)하여 수신되는 데이터를 기준으로 처리하셔야 결제결과 누락없이 안정적인 결과처리를 완료하실 수 있습니다. -[**Confirm Process**](../../../tip/confirm-process) 기능을 사용하여서도 결제금액 검증을 할 수 있습니다. - + [**Confirm Process**](../../../tip/confirm-process) 기능을 사용하여서도 결제금액 검증을 할 수 있습니다. diff --git a/src/content/docs/ko/auth/guide/5/pre.mdx b/src/content/docs/ko/auth/guide/5/pre.mdx index 0ad1d323b..a1f835f0d 100644 --- a/src/content/docs/ko/auth/guide/5/pre.mdx +++ b/src/content/docs/ko/auth/guide/5/pre.mdx @@ -1,11 +1,11 @@ --- title: 결제정보 사전 검증하기 -description: '' +description: 결제 정보 사전 검증 방법을 안내합니다. --- import ContentRef from "~/components/gitbook/ContentRef.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"; 결제정보 사전 검증은 클라이언트 변조를 원천적으로 차단하기 위한 필수 절차입니다. @@ -24,7 +24,7 @@ await axios({ data: { merchant_uid: "...", // 고객사 주문번호 amount: 420000, // 결제 예정금액 - } + }, }); ``` diff --git a/src/content/docs/ko/auth/guide/5/readme.mdx b/src/content/docs/ko/auth/guide/5/readme.mdx index ba0045803..14b596585 100644 --- a/src/content/docs/ko/auth/guide/5/readme.mdx +++ b/src/content/docs/ko/auth/guide/5/readme.mdx @@ -19,9 +19,11 @@ description: 안정적인 결제서비스를 제공할 수 있도록 결제결 1. [백엔드 - 사전 검증](pre) - [**결제금액 사전등록 API**](../../../api/api-1/api-5) 요청 + 2. [프론트엔드 - 결제 요청](../3.) - SDK `IMP.request_pay` 호출 + 3. [백엔드 - 사후 검증](post) - 1. 포트원 결제고유번호(**imp_uid**), 고객사 주문번호(**merchant_uid**)를 프론트엔드로부터 수신 - 2. 결제 상세내역 조회를 위해 포트원 [**결제 단건 조회 API** ](https://api.iamport.kr/#!/payments/getPaymentByImpUid)요청 + 1. 포트원 결제고유번호(**imp\_uid**), 고객사 주문번호(**merchant\_uid**)를 프론트엔드로부터 수신 + 2. 결제 상세내역 조회를 위해 포트원 [**결제 단건 조회 API**](https://api.iamport.kr/#!/payments/getPaymentByImpUid)요청 3. 응답받은 내용을 바탕으로 실 결제 금액과 결제요청금액(고객사 자체 데이터베이스)을 비교 diff --git a/src/content/docs/ko/auth/guide/6.mdx b/src/content/docs/ko/auth/guide/6.mdx index 54a9bc887..33c98b8ca 100644 --- a/src/content/docs/ko/auth/guide/6.mdx +++ b/src/content/docs/ko/auth/guide/6.mdx @@ -3,45 +3,46 @@ title: 6. 결제완료 처리하기 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"; **Iframe** 방식으로 진행되는 대부분의 PC환경 결제인 경우 결제응답은 **callback** 함수로 받아볼 수 있으며 고객사 서버에서 결제결과 처리가 최종적으로 완료되면 아래 예제처럼 결제 성공유무에 따른 분기를 통해 결과 메세지 처리를 진행 하실 수 있습니다. - -```javascript -IMP.request_pay( - {/* 결제 요청 객체 */}, - async requestPayResponse => { - const { success, error_msg } = requestPayResponse; - if (!success) { - alert(`결제에 실패하였습니다. 에러 내용: ${error_msg}`); - return; - } - // 이전 단계에서 구현한 결제정보 사후 검증 API 호출 - const res = await axios({ - url: "/payments/complete", - method: "post", - headers: { "Content-Type": "application/json" }, - data: { imp_uid: "...", merchant_uid: "..." }, - }); - switch (res.status) { - case: "vbankIssued": - // 가상계좌 발급 시 로직 - break; - case: "success": - // 결제 성공 시 로직 - break; - } - } -); -``` - - + + ```javascript + IMP.request_pay( + { + /* 결제 요청 객체 */ + }, + async (requestPayResponse) => { + const { success, error_msg } = requestPayResponse; + if (!success) { + alert(`결제에 실패하였습니다. 에러 내용: ${error_msg}`); + return; + } + // 이전 단계에서 구현한 결제정보 사후 검증 API 호출 + const res = await axios({ + url: "/payments/complete", + method: "post", + headers: { "Content-Type": "application/json" }, + data: { imp_uid: "...", merchant_uid: "..." }, + }); + switch (res.data.status) { + case "vbankIssued": + // 가상계좌 발급 시 로직 + break; + case "success": + // 결제 성공 시 로직 + break; + } + }, + ); + ``` + 새로운 페이지로 리디렉션되어 결제가 진행되는 대부분의 **모바일환경**에서의 결제는 @@ -49,18 +50,17 @@ IMP.request_pay( 진행해 주시면 됩니다. -**error\_msg, error\_code 정의** - -결제 실패 시 응답으로 내려가는 해당 파라미터는 PG사에서 내려준 오류코드와 메세지를 2차 가공없이 그대로 내려드리고 있습니다. + **error\_msg, error\_code 정의** + 결제 실패 시 응답으로 내려가는 해당 파라미터는 PG사에서 내려준 오류코드와 메세지를 2차 가공없이 그대로 내려드리고 있습니다. -인증결제 과정에서 다음과 같은 사용자 동작이 일어날 경우 [**비정상 접근입니다.**]와 같은 오류가 발생할 수 있습니다. + 인증결제 과정에서 다음과 같은 사용자 동작이 일어날 경우 \[**비정상 접근입니다.**]와 같은 오류가 발생할 수 있습니다. -1. PG사 결제창 페이지 내 새로고침하는 경우 -2. 결제 진행 중 뒤로가기 버튼으로 카드사 ACS창으로 이동한 후 추가로 뒤로가기 버튼 클릭하여 PG사 결제창으로 돌아오는 경우 -3. 카드사 ACS 창 내 새로고침하는 경우 (카드사별로 상이) + 1. PG사 결제창 페이지 내 새로고침하는 경우 + 2. 결제 진행 중 뒤로가기 버튼으로 카드사 ACS창으로 이동한 후 추가로 뒤로가기 버튼 클릭하여 PG사 결제창으로 돌아오는 경우 + 3. 카드사 ACS 창 내 새로고침하는 경우 (카드사별로 상이) -결제페이지에서 뒤로가기 또는 새로고침 등의 동작을 방지하면 위 오류를 줄일 수 있습니다. + 결제페이지에서 뒤로가기 또는 새로고침 등의 동작을 방지하면 위 오류를 줄일 수 있습니다. diff --git a/src/content/docs/ko/auth/guide/def.mdx b/src/content/docs/ko/auth/guide/def.mdx index 00c11c992..bbc0c28d1 100644 --- a/src/content/docs/ko/auth/guide/def.mdx +++ b/src/content/docs/ko/auth/guide/def.mdx @@ -14,11 +14,10 @@ import Hint from "~/components/Hint.astro";
-실 결제요청을 위한 통신은 고객사 서버와 PG사 서버간에 직접적으로 이루어지며 해당 결제요청과정에서 카드정보는 포함되어 있지 않습니다. - + 실 결제요청을 위한 통신은 고객사 서버와 PG사 서버간에 직접적으로 이루어지며 해당 결제요청과정에서 카드정보는 포함되어 있지 않습니다. -#### 인증결제는 인증방법에 따라 전통적으로 아래 두가지 형태 구분됩니다. +## 인증결제는 인증방법에 따라 전통적으로 아래 두가지 형태 구분됩니다. - ISP 결제 : 공개키 기반의 전자인증서를 통해 사전에 등록된 카드정보를 인증하는 방식 - MPI 결제 : 카드번호, CVC, 안심클릭 비밀번호를 입력하여 카드정보를 인증하는 방식 @@ -29,4 +28,4 @@ import Hint from "~/components/Hint.astro";
-#### 포트원을 통해 인증결제를 연동하시면 매우 손쉽게 결제연동을 완료하실 수 있습니다. +## 포트원을 통해 인증결제를 연동하시면 매우 손쉽게 결제연동을 완료하실 수 있습니다. diff --git a/src/content/docs/ko/console/guide/reg.mdx b/src/content/docs/ko/console/guide/reg.mdx index ae56bad0e..3e5e4b6a3 100644 --- a/src/content/docs/ko/console/guide/reg.mdx +++ b/src/content/docs/ko/console/guide/reg.mdx @@ -1,6 +1,6 @@ --- title: 전자결제 신청 -description: "" +description: 전자결제 신청 방법을 안내합니다. --- import Figure from "~/components/Figure.astro"; @@ -62,7 +62,7 @@ import image11 from "./_assets/reg/console_011.png"; - 서비스 형태 선택 : 연동하시는 서비스의 형태를 선택해 주세요. (웹/앱) - 서비스 URL 입력 : 결제대행사 계약을 위해 연동하시는 서비스(웹/앱)에 기본구성 구현은 필수 사항입니다. - - 결제대행사 계약을 위한 서비스 기본 구성 요건 [[바로가기](https://guide.portone.io/6e20063c-1305-475f-a71a-c4d5cd5f3556)] + - 결제대행사 계약을 위한 서비스 기본 구성 요건 \[[바로가기](https://guide.portone.io/6e20063c-1305-475f-a71a-c4d5cd5f3556)] ### 최종 확인 @@ -101,7 +101,7 @@ import image11 from "./_assets/reg/console_011.png"; 표기됩니다. - 주의사항: 사이트를 워드프레스 우커머스 플러그인으로 제작하시는 경우, 지원 가능한 PG사가 구분되어 - 있으니 참고하시어 선택해주세요. [[워드프레스 우커머스 플러그인 지원 PG + 있으니 참고하시어 선택해주세요. \[[워드프레스 우커머스 플러그인 지원 PG 목록](https://guide.portone.io/49f92e2b-1927-4165-967c-1f3a78c5cd33)] ### 결제수단 담기 @@ -109,8 +109,8 @@ import image11 from "./_assets/reg/console_011.png"; - 원하는 결제대행사의 결제수단을 클릭하면 장바구니에 담기고, 장바구니에서 선택한 결제대행사 및 결제수단을 확인할 수 있습니다. -- 장바구니에서 특정 결제대행사를 삭제하고 싶은 경우, [`X`]버튼 클릭 후 [`저장`] 을 클릭하세요. - 결제수단 추가를 원하는 경우 [`돌아가기`]버튼을 클릭하여 다시 선택이 가능합니다. +- 장바구니에서 특정 결제대행사를 삭제하고 싶은 경우, \[`X`]버튼 클릭 후 \[`저장`] 을 클릭하세요. + 결제수단 추가를 원하는 경우 \[`돌아가기`]버튼을 클릭하여 다시 선택이 가능합니다. ### 추가 정보 입력 @@ -145,7 +145,7 @@ import image11 from "./_assets/reg/console_011.png"; - 결제대행사(PG사)와 계약을 위해서는 신청하신 PG사의 모듈 연동이 필요합니다. -- 연동 매뉴얼 [[바로가기](https://developers.portone.io/docs/ko/readme)] +- 연동 매뉴얼 \[[바로가기](https://developers.portone.io/docs/ko/readme)] - `다날 휴대폰 본인인증 서비스`는 테스트 모드를 지원하지 않으므로 다날과 계약 완료 후 발급된 연동 정보로 실 운영 모드를 세팅한 뒤 연동 개발 진행 부탁드립니다. diff --git a/src/content/docs/ko/etc/all/0.mdx b/src/content/docs/ko/etc/all/0.mdx index f90fe50fb..63975cfa1 100644 --- a/src/content/docs/ko/etc/all/0.mdx +++ b/src/content/docs/ko/etc/all/0.mdx @@ -3,11 +3,11 @@ title: 통합인증 준비하기 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"; -### 통합인증을 연동할 페이지에 포트원 라이브러리를 추가합니다. +## 통합인증을 연동할 페이지에 포트원 라이브러리를 추가합니다. 신용카드 본인인증 기능은 **포트원 JavaScript v1.1.8**부터 지원합니다. diff --git a/src/content/docs/ko/etc/credit-auth/1.mdx b/src/content/docs/ko/etc/credit-auth/1.mdx index ade3ead01..2f9dfe792 100644 --- a/src/content/docs/ko/etc/credit-auth/1.mdx +++ b/src/content/docs/ko/etc/credit-auth/1.mdx @@ -3,11 +3,11 @@ title: 1. 본인인증 준비하기 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"; -### 본인인증을 연동할 페이지에 포트원 라이브러리를 추가합니다. +## 본인인증을 연동할 페이지에 포트원 라이브러리를 추가합니다. 신용카드 본인인증 기능은 **포트원 JavaScript v1.1.7**부터 지원합니다. @@ -44,8 +44,8 @@ IMP.init("{고객사 식별코드}"); // 예: imp00000000 ```javascript title="client-side" - const IMP = window.IMP; // 생략 가능 - IMP.init({고객사 식별코드}); // 예: "imp00000000" +const IMP = window.IMP; // 생략 가능 +IMP.init({ 고객사_식별코드 }); // 예: "imp00000000" ```