PortOne MCP Server

--- title: 결제 내역 조회 description: >- 포트원을 통해 발생한 결제 내역을 상태별로 조회하고, 부분 취소 및 전체 취소 기능을 이용하여 결제 건을 관리할 수 있으며, 이에 대해 안내합니다. targetVersions: - v1 - v2 --- (관련 이미지 첨부) ## 기준 시각 - **상태 승인 시각**(default) : 최종 결제 상태로 업데이트된 시각을 기준으로 조회합니다. (결제 취소건의 경우 취소 시각을 기준으로 조회됩니다.) - **결제 요청 시각** : 결제를 요청한 시각을 기준으로 결제 건을 조회합니다. <div class="hint" data-style="info"> **기준 시각에 따라 조회 결과가 다르게 표시됩니다.** 예를 들어 4/1 결제 후 4/5에 결제 취소한 경우, 상태 승인 시각을 기준으로 4/1\~4/4로 기간을 설정한 후 검색하면 해당 거래건은 결과에 포함되지 않습니다. </div> ## 내역 검색 결제 정보를 검색하여 거래건을 특정할 수 있습니다. <ul> <li> **전체** : 입력한 단어와 여러 결제 정보 필드 중 매칭되는 거래 건을 표시합니다. 여러 필드에서 일부 혹은 전부 일치하는 경우 검색 결과에 표시됩니다. 또한, 검색의 경우 단어의 앞에서부터 일치하는 경우에만 표시되며 중간만 일치하는 경우 원하는 검색 결과를 얻지 못할 수 있습니다. </li> <li>**포트원 거래번호** : 포트원 거래번호 (`imp_uid`) 데이터 중 입력한 텍스트와 일치하는 데이터가 표시됩니다.</li> <!-- VERSION-SPECIFIC: V1 ONLY CONTENT START --> <li>**가맹점 거래번호** : 가맹점 거래번호 (`merchant_uid`) 데이터 중 입력한 텍스트와 일치하는 데이터가 표시됩니다.</li> <li>**주문명** : 주문명 (`name`) 데이터 중 입력한 텍스트와 일치하는 데이터가 표시됩니다.</li> <li>**카드사 승인번호** : 카드사 승인번호 데이터 중 입력한 텍스트와 일치하는 데이터가 표시됩니다.</li> <li>**고객 이름** : 고객 이름 (`buyer_name`) 데이터 중 입력한 텍스트와 일치하는 데이터가 표시됩니다.</li> <li>**고객 휴대폰 번호** : 고객 휴대폰 번호 (`buyer_tel`) 데이터 중 입력한 텍스트와 일치하는 데이터가 표시됩니다.</li> <li>**고객 이메일** : 고객 이메일 (`buyer_email`) 데이터 중 입력한 텍스트와 일치하는 데이터가 표시됩니다.</li> <li>**고객 주소** : 고객 주소 (`buyer_addr`) 데이터 중 입력한 텍스트와 일치하는 데이터가 표시됩니다.</li> <li>**고객 우편번호** : 고객 우편번호(`buyer_postcode`) 데이터 중 입력한 텍스트와 일치하는 데이터가 표시됩니다.</li> <!-- VERSION-SPECIFIC: V1 ONLY CONTENT END --> <!-- VERSION-SPECIFIC: V2 ONLY CONTENT START --> <li>**가맹점 거래번호** : 가맹점 거래번호 (`paymentId`) 데이터 중 입력한 텍스트와 일치하는 데이터가 표시됩니다.</li> <li>**주문명** : 주문명 (`orderName`) 데이터 중 입력한 텍스트와 일치하는 데이터가 표시됩니다.</li> <li>**카드사 승인번호** : 카드사 승인번호 데이터 중 입력한 텍스트와 일치하는 데이터가 표시됩니다.</li> <li>**고객 이름** : 고객 이름 (`customer.fullname`) 데이터 중 입력한 텍스트와 일치하는 데이터가 표시됩니다.</li> <li>**고객 휴대폰 번호** : 고객 휴대폰 번호 (`customer.phoneNumber`) 데이터 중 입력한 텍스트와 일치하는 데이터가 표시됩니다.</li> <li>**고객 이메일** : 고객 이메일 (`customer.email`) 데이터 중 입력한 텍스트와 일치하는 데이터가 표시됩니다.</li> <li>**고객 주소** : 고객 주소 (`customer.address`) 데이터 중 입력한 텍스트와 일치하는 데이터가 표시됩니다.</li> <li>**고객 우편번호** : 고객 우편번호(`customer.zipcode`) 데이터 중 입력한 텍스트와 일치하는 데이터가 표시됩니다.</li> <!-- VERSION-SPECIFIC: V2 ONLY CONTENT END --> <li>**결제대행사 승인번호** : 결제대행사(PG사) 승인번호 데이터 중 입력한 텍스트와 일치하는 데이터가 표시됩니다.</li> <li> **카드번호** : 카드번호 데이터 중 입력한 텍스트와 일치하는 데이터가 표시됩니다. 카드 번호의 경우 결제대행사에 따라 마스킹되는 부분이 다르므로, 앞에 6\~8자리(BIN)번호 혹은 뒷 4자리로 검색하시길 권장드립니다. </li> <li>**상점아이디** : 결제대행사 상점아이디 데이터 중 입력한 텍스트와 일치하는 데이터가 표시됩니다.</li> <li>**결제환경** : 결제환경(PC/MOBILE/API) 데이터 중 입력한 텍스트와 일치하는 데이터가 표시됩니다. 검색하는 경우 대문자로 검색해야 합니다.</li> <li> **실시간 계좌 은행** : 실시간 계좌이체 거래 건에 한하여 실시간 계좌 은행 데이터 중 입력한 택스트와 일치하는 데이터가 표시됩니다. (ex. 실시간 계좌이체 거래 건의 계좌은행이 토스뱅크인 경우 ) </li> <li>**가상계좌 은행** : 가상계좌 거래 건에 한하여 가상계좌 은행 데이터 중 입력한 텍스트와 일치하는 데이터가 표시됩니다.</li> <li>**계좌번호** : 가상계좌 거래 건에 한하여 계좌번호 데이터 중 입력한 텍스트와 일치하는 데이터가 표시됩니다.</li> <li>**입금자명** : 가상계좌 거래 건에 한하여 입금자명 데이터 중 입력한 텍스트와 일치하는 데이터가 표시됩니다.</li> <li> **현금영수증 발급번호** : 실시간 계좌이체 또는 가상계좌 거래 시 현금영수증을 발급한 거래 건에 한하여 현금영수증 발급번호(국세청 승인번호) 데이터 중 입력한 텍스트와 일치하는 데이터가 표시됩니다. </li> <li> **취소 사유** : 결제 취소 건에 한하여 취소 사유 데이터 중 입력한 텍스트와 일치하는 데이터가 표시됩니다. 포트원 어드민콘솔에서 취소한 경우 취소 사유는 **관리자페이지취소**로 일괄 입력됩니다. </li> <li>**카드사명** : 카드사명 데이터 중 입력한 텍스트와 일치하는 데이터가 표시됩니다.</li> <li>**할부개월수** : 카드 결제 시 할부가 적용된 거래 건에 한하여 할부개월수 데이터 중 입력한 텍스트와 일치하는 데이터가 표시됩니다.</li> </ul> ## 필터 필터에 따라 결제 내역을 필터링하여 조회할 수 있습니다. 필터는 결제상태, 결제수단, 결제대행사, 결제유형, 결제모드에 따라 다중 선택할 수 있습니다. ### 결제상태 - **전체** : 모든 결제 상태의 거래를 조회합니다. - **결제 완료** : **결제 완료** (status : PAID) 상태인 거래 건만 표시됩니다. 결제 취소건은 포함되지 않습니다. - **결제 예정** : **결제 예정** (status : READY) 상태인 거래 건만 표시됩니다. - 결제창이 화면에 표시되는 순간 결제 예정 상태로 거래 건이 저장됩니다. - 일반적으로 결제 승인이되면 결제 완료 상태로 업데이트 됩니다. 다만, 결제 도중 모종의 이유로 고객이 결제창을 이탈하는 경우에는 해당 거래 건은 계속 결제 예정 상태로 남게 됩니다. - **결제 실패** : **결제 실패** (status : FAILED) 상태인 거래 건만 표시됩니다. - **결제 취소** : **전체 취소** (status : CANCELLED) 및 **부분 취소** (PARTIAL\_CANCELLED) 상태인 거래 건만 표시됩니다. - **승인 대기** : **승인 대기** (status : PENDING) 상태인 거래 건만 표시됩니다. - 승인 대기 상태는 페이팔(SPB/RT) 거래 건에서만 발생하며, 결제 및 환불 요청 완료 후 실제 승인되기까지 결제상태를 의미합니다. ### 결제수단 <ul> <li>**전체** : 모든 결제 수단의 거래를 조회합니다.</li> <!-- VERSION-SPECIFIC: V1 ONLY CONTENT START --> <li> **카드결제** : 결제 요청 시 결제 수단을 카드(`pay_method : card`)로 지정하여 호출한 뒤 신용카드, 체크카드, 법인카드, 기프트카드 등 카드로 진행된 거래 건만 표시됩니다. </li> <li> **실시간 계좌이체** : 결제 요청 시 결제 수단을 실시간 계좌이체(`pay_method : trans`)로 지정하여 호출한 뒤 계좌이체로 진행된 거래 건만 표시됩니다. </li> <li> **가상계좌** : 결제 요청 시 결제 수단을 가상계좌 (`pay_method : vbank`)로 지정하여 호출한 뒤 가상계좌로 진행된 거래 건만 표시됩니다. </li> <li> **휴대폰 소액결제** : 결제 요청 시 결제 수단을 휴대폰 소액결제 (`pay_method : phome`)로 지정하여 호출한 뒤 휴대폰 소액결제로 진행된 거래 건만 표시됩니다. </li> <li> **문화상품권** : 결제 요청 시 결제 수단을 문화상품권 (`pay_method : culturegift`)로 지정하여 호출한 뒤 문화상품권으로 진행된 거래 건만 표시됩니다. 문화상품권의 경우 웰컴페이먼츠만 지원합니다. </li> <li> **컬쳐랜드** : 결제 요청 시 결제 수단을 컬쳐랜드 문화상품권 (`pay_method : cultureland`)로 지정하여 호출한 뒤 컬쳐랜드 문화상품권으로 진행된 거래 건만 표시됩니다. </li> <li> **스마트문상** : 결제 요청 시 결제 수단을 스마트문상(`pay_method : smartculture`)로 지정하여 호출한 뒤 스마트문상 ((구)게임문화상품권)으로 진행된 거래 건만 표시됩니다. </li> <li> **북앤라이프** : 결제 요청 시 결제 수단을 북앤라이프(`pay_method : booknlife`)로 지정하여 호출한 뒤 도서문화상품권으로 진행된 거래 건만 표시됩니다. </li> <!-- VERSION-SPECIFIC: V1 ONLY CONTENT END --> <!-- VERSION-SPECIFIC: V2 ONLY CONTENT START --> <li> **카드결제** : 결제 요청 시 결제 수단을 카드(`payMethod : CARD`)로 지정하여 호출한 뒤 신용카드, 체크카드, 법인카드, 기프트카드 등 카드로 진행된 거래 건만 표시됩니다. </li> <li> **실시간 계좌이체** : 결제 요청 시 결제 수단을 실시간 계좌이체(`payMethod : TRANSFER`)로 지정하여 호출한 뒤 계좌이체로 진행된 거래 건만 표시됩니다. </li> <li> **가상계좌** : 결제 요청 시 결제 수단을 가상계좌 (`payMethod : VIRTUAL_ACCOUNT`)로 지정하여 호출한 뒤 가상계좌로 진행된 거래 건만 표시됩니다. </li> <li> **휴대폰 소액결제** : 결제 요청 시 결제 수단을 휴대폰 소액결제 (`payMethod : MOBILE`)로 지정하여 호출한 뒤 휴대폰 소액결제로 진행된 거래 건만 표시됩니다. </li> <li>**문화상품권** : 문화상품권의 경우 V1 결제모듈의 웰컴페이먼츠만 지원합니다.</li> <li> **컬쳐랜드** : 결제 요청 시 결제 수단을 컬쳐랜드 문화상품권 (`payMethod : GIFT_CERTIFICATE`, `giftCertificate.giftCertificateType : CULTURELAND`)로 지정하여 호출한 뒤 컬쳐랜드 문화상품권으로 진행된 거래 건만 표시됩니다. </li> <li> **스마트문상** : 결제 요청 시 결제 수단을 스마트문상 (`payMethod : GIFT_CERTIFICATE`, `giftCertificate.giftCertificateType : SMART_MUNSANG`)로 지정하여 호출한 뒤 스마트문상 ((구)게임문화상품권)으로 진행된 거래 건만 표시됩니다. </li> <li> **북앤라이프** : 결제 요청 시 결제 수단을 북앤라이프 (`payMethod : GIFT_CERTIFICATE`, `giftCertificate.giftCertificateType : BOOKNLIFE`)로 지정하여 호출한 뒤 도서문화상품권으로 진행된 거래 건만 표시됩니다. </li> <!-- VERSION-SPECIFIC: V2 ONLY CONTENT END --> <li> **포인트결제** : 실제 승인된 결제가 포인트로 진행된 거래 건만 표시됩니다. - 예를 들어 네이버페이 포인트 사용 결제 건 등이 해당됩니다. </li> <li>**기타** : 결제 수단을 알 수 없거나 해외 현지 결제 수단으로 진행된 거래 건만 표시됩니다.</li> </ul> ### 결제대행사 - **전체** : 모든 결제대행사의 거래를 조회합니다. - 결제대행사 필터는 `pg_provider`를 기준으로 구분됩니다. ### 결제유형 - **전체** : 모든 결제유형의 거래를 조회합니다. - **정기 결제** : 발급한 빌링키로 시도된 결제 거래 건만 표시됩니다. - **일반 결제** : SDK 및 API로 시도된 일회성 결제 거래 건만 표시됩니다. ### 결제모드 - **전체** : 모든 결제모드의 거래를 조회합니다. - **실결제** : 실연동 채널로 시도된 결제 거래 건만 표시됩니다. - **테스트 결제** : 테스트 채널로 시도된 결제 거래 건만 표시됩니다. 기본적으로 체크 표시가 해제되어있으니 테스트 거래 건을 조회할 실 때 필터에서 체크한 후 검색을 해야 합니다. ## 순거래액 총 거래액, 총 거래취소 금액, 순 거래액 집계 금액은 홈 대시보드에서 확인하시거나 결제 데이터 분석 서비스에서 상세히 확인하실 수 있습니다. ## 엑셀다운로드 조회된 거래 내역을 엑셀 파일 형식으로 로컬에 다운로드 받을 수 있습니다. 엑셀 다운로드 클릭 시 원하는 정보를 선택하여 커스텀할 수 있습니다.