# Welcome 결제선생 API는 모바일 청구서 발송부터 실시간 수납 확인까지, 비대면 결제의 전 과정을 제어하는 통합 인터페이스를 제공합니다. 비즈니스와 완벽하게 연동되는 최적의 결제 환경을 구축하세요 ## **알아보기**

:book-blank:

이해하기

결제선생에 대해 알아보세요 /pages/PbYb0GukRhiS4qCHdRal

:diagram-project:

기획하기

제공되는 기능을 확인하세요/pages/aOjs4gC5WzIpifbjuGsn

:square-terminal:

연동하기

API 스팩 문서를 확인하세요./spaces/kF1BaptaFyVqmoi3Hn7Z/pages/c4jNo9NyQHlwX9aBJG0T#v2-api
## **온보딩 가이드** 결제선생 API를 비즈니스에 도입하기 위한 연동 절차를 안내합니다. 아래 단계에 따라 파트너 제휴 계약을 완료하고, 실제 API를 호출할 수 있는 `Live API Key`를 발급 받으세요. {% stepper %} {% step %} #### **상담 신청하기** * 결제선생 API 이용을 원하시면 상담 신청을 작성해 주세요. * 담당자가 연락 드리고 파트너 제휴 및 연동 관련한 전반적인 내용을 안내 드립니다. 상담 신청하기 {% endstep %} {% step %} #### **파트너 제휴 계약** * 상담을 통해 서비스 이용 조건 협의하고 파트너 계약을 체결합니다. * 계약이 완료되면 개발 테스트를 위한 `Sandbox API Key` 를 별도로 전달해 드립니다. {% endstep %} {% step %} #### **연동 검수** * 제공된 `Sandbox API Key`를 사용하여 실제 연동 개발을 진행합니다. * 개발이 완료되면, 안정적인 서비스 제공을 위해 결제선생 기술지원팀의 검수 과정을 거쳐야 합니다. * 검수가 완료되면 [운영 정보](#user-content-fn-1)[^1]를 전달해 드립니다. 검수 요청 방법 알아보기 {% endstep %} {% step %} #### **배포** * 검수가 승인되면 상용 환경(Production)에서 사용할 수 있는 `Live API Key`가 발급 됩니다. * 최종 배포 전, 필수 점검 사항을 확인하여 안전하게 서비스를 오픈하세요. 배포 체크리스트 확인하기 {% endstep %} {% step %} #### **운영 및 쌤포인트 관리** * 서비스가 오픈되면 알림톡 청구서 발송을 위한 쌤포인트가 필요하며, 원활한 서비스 이용을 위해 쌤포인트 잔액을 주기적으로 확인하고 충전해 주세요. [쌤포인트 충전 방법 알아보기](/understanding/ssampoint) {% endstep %} {% endstepper %} *** ## :circle-info: :messages-question: 더 궁금한 내용이 있나요? [자주하는 질문](https://developers.payssam.kr/faq/) :message-code: 기술지원이 필요하신가요? [이메일 보내기](mailto:partner_dev@paymint.co.kr) [^1]: API 호출 URL, Live API Key # 나눠서 결제 오픈 예정 결제선생 API의 신규 기능인 나눠서 결제가 오픈 예정입니다.\ 하나의 청구서로 여러번 분할 결제할 수 있는 최적의 결제 흐름을 구현해 보세요. ### 운영 반영 및 일정 안내 | 구분 | 내용 | 일정 | | ----------- | ------------------- | ------ | | 운영 반영일 | 운영 환경 나눠서 결제 API 반영 | 8월 31일 | | API 규격 업데이트 | API V2 상세 규격 업데이트 | 8월 31일 | {% hint style="warning" %} V2 스펙에 추가되는 기능입니다.\ V1 → V2 마이그레이션을 준비 중이라면, 8월 31일 배포 이후에 진행하시는 것을 권장합니다. {% endhint %} ### 나눠서 결제 주요 제공 기능 * 하나의 청구서를 최대 6번까지 나누어 결제가 가능합니다. * 결제 금액을 직접 입력하거나 비율로 나누어 결제가 가능합니다. * 나눠서 결제할 때마다 파트너사 서버로 결제 완료 웹훅이 발송됩니다. * 결제건 전체 취소, 개별 취소도 가능합니다. * 결제를 취소하면 취소 금액만큼 잔여 결제 필요 금액이 복원됩니다. 고객은 복원된 금액을 다시 결제할 수 있습니다. ### 변경 사항
기능as isto be
결제 횟수 1번 최대 6번
승인 동기화1회 /건 최대 6회 /건
승인 동기화 (확장)결제건 승인동기화취소, 파기, 현금 수납처리
결제 취소전체 취소전체 취소, 결제건 별 취소
조회단건 조회거래 건 별 조회
### API 스펙 및 정책 안내 * 나눠서 결제는 **API V2** 스펙에 추가됩니다. * 나눠서 결제 적용하지 않고 **API V2 기존 기능만** 이용 가능합니다. {% hint style="warning" %} 본 기능은 V2 전용으로, **API V1 버전에서는 이용이 불가**합니다. {% endhint %} *** ## :circle-info: :messages-question: 더 궁금한 내용이 있나요? [자주하는 질문](https://developers.payssam.kr/faq/) :message-code: 기술지원이 필요하신가요? [이메일 보내기](mailto:partner_dev@paymint.co.kr) # 결제선생 ## 결제선생의 역할 점점 커져가고 있는 비대면결제 시장의 중심에는 결제선생이 있습니다. 결제선생의 역할과 오프라인 결제 과정을 자세히 알아보세요. 결제선생은 학원, 병원, 출장서비스 등 오프라인 매장에서 모바일 청구서를 카카오톡이나 문자로 발송해 결제 받을 수 있는 편리한 비대면결제서비스입니다. 별도 단말기 없이 결제선생을 통해 결제 요청, 수납 내역 관리, 현금영수증 발행을 처리하며, 낮은 수수료와 실시간 수납 알림이 주요 특징입니다.
결제선생은 편리한 비대면결제서비스를 제공한 대가로 가맹점으로부터 청구서 발송 비용을 받습니다. 그 외 카드사에 지불하는 결제수수료 외에 추가적인 결제수수료는 없습니다. ## 정산 정산은 상품이나 서비스를 판매한 거래 대금 중에서 가맹점이 받을 수 있는 실제 금액을 계산하는 과정을 말합니다. 카드사는 판매 대금에서 결제수수료가 차감한 금액을 계산해 가맹점에 실제 지급되는 금액을 정산 금액이라고 합니다.
결제선생은 가맹점, 결제고객, 카드사간의 카드거래에서 거래를 위한 중개 업무를 담당하며, 결제 대금에 대한 정산 업무를 하지 않습니다. ## 결제 수수료 및 정산주기 #### 결제 수수료 결제 수수료란 가맹점이 결제시스템을 이용하는 대가로 총 결제 금액에서 결제시스템 제공회사(카드사, PG등)에게 지불하는 수수료의 비율입니다. #### 정산주기 정산주기는 결제고객이 카드로 결제한 대금이 가맹점 계좌로 입금되기까지 걸리는 기간을 의미하며, 보통 D+2\~3 영업일이 일반적이며 카드사별 상이할 수 있습니다. 정산주기에서 주말, 공휴일은 제외됩니다. 만약 만약 정산주기가 D+2인 카드사는 금요일 매출에 대한정산은 다음 주 화요일에 입금됩니다. {% hint style="info" %} 결제수수료와 정산주기에 대한 구체적인 내용은 결제선생 이용가이드를 참고해주세요. [자세히 보기](https://guide.payssam.kr/ko/articles/feerate-4c498682) {% endhint %} # 모바일청구서 모바일청구서는 결제고객이 실제로 결제를 진행하는 웹 기반의 결제 페이지입니다. 파트너사가 API로 청구서를 발송하면, 고객은 별도의 앱 설치 없이 카카오톡을 통해 이 페이지에 접근하여 수납을 완료합니다.
## 모바일청구서 결제 방법 고객은 회원가입 절차 없이, 알림톡 수신 ➔ 청구서 확인 ➔ 결제하기 3단계로 모바일청구서에 대한 결제가 이루어집니다.
#### 단계별 상세 흐름 {% stepper %} {% step %} ### 알림톡 수신 1. 가맹점에서 고객의 휴대전화번호로 청구서를 발송하면 고객의 카카오톡 '결제선생 채널'로 청구서 알림톡이 도착합니다. 2. 알림톡에는 청구 금액, 청구 사유, 납부 기한이 메시지에 명시됩니다. 3. 납부하기 가기 버튼을 터치하면 모바일청구서 웹페이지가 열립니다. {% endstep %} {% step %} ### 청구서 확인 1. 모바일청구서 화면 상단에 발급처, 청구사유, 금액 확인합니다. 2. 원하는 결제수단을 선택하고 결제하기 버튼을 누르면 해당 결제수단에 따라 결제하기가 진행됩니다. {% endstep %} {% step %} ### 결제하기 결제하기는 결제수단별로 다른 방식으로 결제가 진행됩니다. * 간편결제 : 선택한 간편결제앱이 열리면 등록된 카드 또는 머니를 선택 후 인증하여 결제합니다. * 일반결제 : 결제할 카드의 카드번호, 유효기간, 생년월일, 카드 비밀번호 앞2자리를 입력하여 결제합니다. * 자동결제 : 자동결제 등록을 위해 서명을 입력하고 선택한 간편결제앱이 열리면 등록된 카드를선택 후 인증하면 자동결제 등록 및 결제가 함께 이루어집니다. {% hint style="info" %} #### **참고** 모바일청구서의 결제 화면(UI)은 결제선생이 제공되므로, 파트너사는 결제 페이지를 직접 개발할 필요가 없습니다. 파트너사는 오직 청구 정보만 API로 전송하면 됩니다. {% endhint %} {% endstep %} {% endstepper %} ## 결제수단 결제선생 모바일청구서는 고객의 편의를 위해 다양한 결제 방식을 통합 제공합니다. {% hint style="info" %} #### **결제수단 관리** 모바일청구서에 표시된는 결제수단은 파트너 또는 가맹점이 직접 설정할 수 없으며, 결제선생 파트너 담당자과 상담을 통해 변경할 수 있습니다. {% endhint %} #### 간편결제 앱 간 연동(App-to-App)을 통해 비밀번호나 생체 인증만으로 빠르게 결제합니다. * 제공사 : 9개 카드사앱, 카카오페이, 네이버페이, 엘페이 {% hint style="info" %} 카카오페이머니, 네이버페이머니 결제 가능 {% endhint %} #### 자동결제 결제고객이 매월 반복적으로 청구서를 받는 경우 자동결제로 등록하면, 이후 받는 청구설에 별도 인증 없이 자동으로 결제되는 방식입니다. * 등록 방식 : 고객이 최초 1회 본인 인증 후 카드 등록 * 자동결제 시점 : 자동결제 등록 후 받은 청구건에 대해 다음날 오전 10시에 자동으로 결제할 수 있습니다. * 자동결제 변경, 해지 : 결제고객은 받은 모바일청구서 화면에서 등록된 자동결제를 변경 및 해지 할 수 있습니다. #### 일반결제 법인카드와 같이 앱카드에 등록할 수 없는 카드로 결제를 원하는 경우 사용하는 방식으로 카드번호와 유효기간 등 인증에 필요한 카드정보를 입력하여 결제하는 방식을 제공합니다. {% hint style="warning" %} 인증이 불가능한 무기명 선불카드, 지역화폐 결제는 결제할 수 없습니다. {% endhint %} #### 지역화폐 청구서를 발송한 가맹점의 소재지에 따라 결제 가능한 지역화폐를 안내하고 결제방법을 소개합니다. *** ## :circle-info: :messages-question: 더 궁금한 내용이 있나요? [자주하는 질문](https://developers.payssam.kr/faq/) :message-code: 기술지원이 필요하신가요? [이메일 보내기](mailto:partner_dev@paymint.co.kr) # 결제선생 API 소개 결제선생 API(Application Programming Interface)는 고객에게 청구서를 발송하고 수납관리 등 청구・수납 전 과정을 파트너의 플랫폼 안에서 별도의 결제 시스템을 구축하지 않고도 편리하게 구현할 수 있도록 도와줍니다. * 고객에게 모바일 청구서 발송 * 다양한 결제수단을 통한 수납 처리 * 결제 상태 확인 및 관리 * 실시간 결제 알림 수신 * 현금영수증 발급 ### **이런 서비스에 적합합니다.** 결제선생 API는 다음과 같이 오프라인 매장 중심 사업자의 디지털 수납 전환구조의 서비스에 적합합니다. * 학원 관리 프로그램 * 예약 기반 서비스 * 병원 진료비 결제 솔루션 * A/S 및 출장 서비스 *** ## :circle-info: :messages-question: 더 궁금한 내용이 있나요? [자주하는 질문](https://developers.payssam.kr/faq/) :message-code: 기술지원이 필요하신가요? [이메일 보내기](mailto:partner_dev@paymint.co.kr) # 파트너와 하위사업장 결제선생 API를 이용하기 위해서 먼저 파트너 구조를 이해해야 합니다. ## **파트너** 파트너는 결제선생과 파트너 제휴 계약을 통해 결제선생 API 이용 권한을 취득한 사업자를 의미합니다. 파트너는 결제선생에서 제공하는 API를 활용하여 플랫폼을 이용하는 가맹점에게 청구, 수납 기능을 제공할 수 있습니다.
## 하위사업장 파트너의 가맹점이 결제선생 API를 통해 청구서 발송하기 위해서는 먼저 해당 가맹점이 결제선생에 사업장으로 등록되어 있어야하며, 추가적으로 결제선생에서 해당 사업장이 파트너의 하위사업장으로 등록되어야합니다.
사업장이 파트너의 하위사업장으로 등록할 수 있는 방법은 경우에 따라 두 가지가 있습니다.
등록될 하위사업장이 많이 않은 경우 등록된 사업장정보와 `Merchant`값을 파트너 메일로 요청해 주시면 수동으로 담당자가 연결을 도와드립니다.
하위사업장 등록 빈번한 경우 하위사업장 등록 API를 활용하여 자동화할 수 있습니다. [하위사업장 등록 API 자세히 보기](/development/merchant)
# 쌤포인트
## 쌤포인트란? 쌤포인트는 결제선생 서비스를 이용하기 위해 사용하는 선불형 충전 포인트입니다. 청구서 발송 등 유료 서비스를 이용할 때 쌤포인트를 사용합니다. ## 쌤포인트 소진 청구서 발송 API를 사용하여 청구서를 발송할 경우 파트너 제휴 계약시 설정된 소진 대상사업장에 충전된 쌤포인트가 사용됩니다. #### 쌤포인트 소진 시점 청구서 발송 API 요청 등 유료서비스 정상적으로 처리된 시점에 쌤포인트가 차감됩니다. #### 쌤포인트 소진 대상사업장 파트너제휴 계약 시 파트너사의 비즈니스 구조에 따라 쌤포인트 소진 대상사업장을 두 가지 방식 중 한 가지 방식으로 설정할 수 있습니다.
방식설명
파트너 일관 관리파트너 관리 주체로 청구서 발송 기능을 가맹점에게 재판매 하는 경우
사업장 개별 관리가맹점이 관리 주체로 파트너는 청구서 발송 기능을 제공하는 경우
각 방식별 파트너사의 운영에 따라 선택하여 설정할 수 있습니다.
비교 항목파트너 일관 관리사업장 개별 관리
쌤포인트 충전 주체파트너각 하위사업장
쌤포인트 소진 사업장파트너 관리 사업장각 하위사업장
적합한 운영 형태재판매기능 제공
## 쌤포인트 관리 {% hint style="danger" %} 소진 대상 사업장의 포인트 잔액이 부족할 경우 API 호출이 제한될 수 있습니다. 쌤포인트 잔여 수량 확인 API로 잔액을 확인하세요. [쌤포인트](/api/api-v2/ssam-point) {% endhint %} ### 쌤포인트 충전 파트너 관리 사업장에 쌤포인트는 방법은 다음과 같습니다. {% tabs %} {% tab title="카드 결제 (권장)" %} 카드 결제 시 원하는 만큼 쌤포인트를 즉시 충전할 수 있으며, 별도의 세금계산서 발행 절차가 필요 없습니다. *** **결제선생 매니저 사이트에서 충전하기** 이용 관리자 권한이 있는 경우 매니저 사이트에서 직접 충전할 수 있습니다. 1. [결제선생 매니저 사이트](https://manager.payssam.kr/) 접속 및 로그인 2. 내 관리 사업장 ➔ 파트너 관리 사업장 선택 3. 홈 ➔ 쌤포인트 ➔ 쌤포인트 충전 버튼 클릭 4. 원하는 만큼 충전포인트를 선택하여 충전 *** **간편 충전 링크에서 충전하기** 파트너 관리 사업장의 로그인 정보를 모르는 회계/총무팀 담당자도 링크를 통해 즉시 충전이 가능합니다. 1. 간편 충전 링크 접속 2. 원하는 만큼 충전포인트를 선택하여 충전 {% hint style="info" %} 간편 충전 링크는 파트너 계약 과정에서 별도 안내됩니다. {% endhint %} {% endtab %} {% tab title="계좌이체" %} 계좌이체 방식은 입금 확인 후 담당자가 수동으로 충전을 처리됩니다. *** **충전 절차** 1. 입금 진행 : 아래 계좌로 충전할 금액을 입금합니다. * 입금액 : 500,000원 (최소 충전 금액) * 입금계좌 : 하나은행 374-910027-50304 (예금주: 페이민트) 2. 충전 요청 : 입금 후 아래 이메일로 충전 요청을 보냅니다. * 접수 이메일 : * 기재 내용 : 사업자명, 입금자명, 입금액 {% hint style="warning" %} 주의 사항 * 계좌이체 충전은 평일 근무 시간에만 처리가 가능합니다. * 근무시간 (월\~목 : 09:30 \~ 18:30, 금 : 09:30 \~ 13:30) * 주말이나 야간에 충전이 필요한 경우 카드 결제 방식으로 충전해 주세요. {% endhint %} {% endtab %} {% endtabs %} ### 쌤포인트 잔액 확인 쌤포인트 잔액을 확인 방법은 다음과 같습니다. #### 매니저사이트
1. [결제선생 매니저 사이트](https://manager.payssam.kr/) 접속 및 로그인 2. 내 관리 사업장 ➔ 파트너 관리 사업장 선택 3. 좌측 상단에서 쌤포인트 잔액을 확인하실 수 있습니다. #### 간편 충전 링크 간편 충전 링크는 파트너 제휴가 완료되면 별로 안내되는 URL로 접속하면 로그인 없이도 충전 할 수 있습니다. 1. 간편 충전 링크 접속 2. 사업장명 아래에서 쌤포인트 잔액을 확인하실 수 있습니다.
#### 자동 충전 쌤포인트 충전량을 관리하기 힘드시다면 자동 충전을 사용해보세요 * 간편 충전 링크 접속 * 자동충전을 선택하면 쌤포인트가 모자른 경우 자동으로 충전 할 수 있습 #### 쌤포인트 조회 API API를 통해 파트너 관리 사업장 또는 하위사업장의 쌤포인트 잔액을 확인 할 수 있습니다. * 파트너 관리 사업장 : [쌤포인트 잔액 조회 API 레퍼런스 보기](/api/api-v1/ssam-point) * 하위사업장 : [하위 사업장 포인트 조회 API](/api/api-v2/ssam-point#post-read-merchant-remain_count) *** ## :circle-info: :messages-question: 더 궁금한 내용이 있나요? [자주하는 질문](https://developers.payssam.kr/faq/) :message-code: 기술지원이 필요하신가요? [이메일 보내기](mailto:partner_dev@paymint.co.kr) # 이용 사례 결제선생 API는 학원, 병원, 피트니스, 렌탈 서비스 등 정기적 혹은 비정기적인 수납이 발생하는 모든 비즈니스에 유연하게 적용될 수 있습니다. 파트너사의 서비스 특성에 맞춰 결제선생을 어떻게 활용할 수 있는지 대표적인 시나리오를 소개합니다. ### :school-flag: 학원 관리 프로그램 학원 프랜차이즈 본사 또는 학원관리프로그램 제공 플랫폼사가 가장 대표적인 활용 사례로, 매월 반복되는 원비 수납 업무를 결제선생을 통해 자동화합니다. #### 기존 방식 * 학부모에게 종이 고지서를 인편으로 전달하거나 문자로 계좌번호를 발송합니다. * 학부모가 입금 시 '홍길동' 대신 '길동모'로 입금하여, 관리자가 엑셀을 열고 일일이 대조해야 합니다. * 카드 결제를 위해 학생이 실물 카드를 들고 등원해야 합니다. #### 결제선생 도입 후 1. 청구 생성 : 원장님이 학원 관리 프로그램에서 청구서 발송 버튼을 클릭합니다. 2. 알림톡 발송 : 학부모의 카카오톡으로 상세 내역(수강료, 교재비 등)이 담긴 청구서가 도착합니다. 3. 즉시 결제 : 학부모는 앱 설치 없이 10초 만에 결제를 완료합니다. 4. 자동 수납 : 결제 완료 즉시 학원 관리 프로그램의 수납 상태가 `미납` :arrow-right: `완납`으로 자동 변경됩니다. *** ### :hospital: 병원 진료비 결제 솔루션 진료 예약 및 진료비 수납에 활용됩니다. #### 기존 방식 * 수납 창구, 키오스크 대기 줄이 길어 대기시간이 오래 걸립니다. * 환자 보호자가 멀리 있어 병원비를 대신 결제해주기 어렵습니다. * 수납 대기 줄이 길어 병원 로비가 혼잡합니다. #### 결제선생 도입 후 1. 사전 결제 : 고객이 예약금을 결제하면 CRM에서 예약이 최종 `확정` 처리됩니다. 2. 원격 수납 : 병원에 방문하지 않은 보호자에게 알림톡을 보내 수납을 요청할 수 있습니다. *** ### :dumbbell: 피트니스 매월 발생하는 회원권 결제와 PT/레슨비 요청을 간편하게 처리합니다. #### 기존 방식 * 회원권 만료가 임박한 회원에게 일일이 전화를 걸어 연장을 권유해야 합니다. * 트레이너가 수업료를 개인 계좌로 받거나, 카운터에서만 결제가 가능해 매출 누락이 우려됩니다. #### 결제선생 도입 후 1. 갱신 알림 : 회원권 만료 3일 전, 시스템이 자동으로 재등록 청구서를 발송합니다. 2. 비대면 연장 : 회원은 헬스장에 가지 않고도 집에서 회원권을 연장 결제합니다. 3. 투명한 매출 : 모든 결제 내역이 전산에 기록되므로 정확한 매출 관리가 가능합니다. *** ### :toolbox: A/S 및 출장 서비스 가전 수리, 청소 대행 등 현장에서 비용이 확정되는 서비스에 적합합니다. #### 기존 방식 * 현장 기사님이 무선 카드 단말기를 들고 다녀야 하며, 단말기 고장 시 난감합니다. * 현금 영수증 발행 요청 시 절차가 번거롭습니다. #### 결제선생 도입 후 1. 현장 발송 : 기사님이 수리 완료 후, 전용 앱에서 고객 번호만 입력하여 청구서를 띄워줍니다. 2. 현장 결제 : 고객은 자신의 폰으로 알림톡을 받아 그 자리에서 결제합니다. (카드 단말기 불필요) *** ## :circle-info: :messages-question: 더 궁금한 내용이 있나요? [자주하는 질문](https://developers.payssam.kr/faq/) :message-code: 기술지원이 필요하신가요? [이메일 보내기](mailto:partner_dev@paymint.co.kr) # 연동 환경 정보 결제선생 파트너 연동을 위한 기본적인 환경 정보와 접근 정책에 대해 안내드립니다. ## 파트너 연결 환경 결제선생의 파트너 연동에는 2가지 환경이 제공됩니다. ### 도메인 정보 #### API V2.0
statusdomaindescriptionenv
SANDBOXhttps://sandbox.paymint.co.kr/partnerv2 버전의 신규 시스템개발
PROD연동 검수 완료 후 별도 제공운영
#### API V1.0
statusdomaindescriptionenv
SANDBOXhttps://stg.paymint.co.kr/partnerv1 버전의 기존 시스템개발
PROD연동 검수 완료 후 별도 제공운영
#### 포트 번호 **허용 포트 : http(80), https(443)** 페이민트에서는 파트너의 편의성을 위하여 http, https 통신 모두 지원하고 있습니다.\ 다만 결제 정보와 개인 정보를 강화를 위하여 기본적으로 https 통신을 권장합니다. #### IP 자체 방화벽을 구축하고 계실 경우 아래의 IP주소를 접근 제어 목록에 등록해주세요. * 52.78.118.82 * 52.78.236.125 * 52.79.214.146 * 3.36.243.225 * 3.39.97.44 * 13.209.0.172 * 13.209.248.179 #### TLS 페이민트에서는 TLS 버전 1.2 이상만 지원합니다. \ 하위 TLS 버전을 사용하고 계시다면 1.2 이상 버전을 사용해야합니다. # API 키 결제선생 파트너는 인증에 API key를 사용합니다. API 연동에 필요한 통신과 사업장을 인증하는 역할을 합니다. ## API key 이해하기 결제선생 파트너 연동 시 각 파트너별로 고유한 API key를 발급받게 됩니다.\ API key는 사업장 정보를 인증함과 동시에 결제선생 API에서 유효한 파트너를 통해 호출되었다는 인증도 같이 진행됩니다.\ 따라서 발급받은 API key가 외부에 유출되지 않도록 유의하셔야 합니다. ## API key 발급 받기 API key는 파트너가 임의로 사용할 수 없습니다.\ 운영환경과 개발환경에 따라 API key가 엄격하게 구분되어 있으며 각 API key의 발급 시점이 별도로 존재합니다.\ (개발환경 API KEY는 V1, V2는 혼용이 가능합니다)
Sandbox API key 발급받기 개발 환경 API key는 페이민트를 통해 파트너 계약을 맺음과 동시에 발급이 진행됩니다.\ 발급받은 개발 환경 API key는 개발 환경에서만 사용할 수 있습니다.
Live API Key 발급받기 운영 환경 API key는 개발환경에서 연동검수 완료 이후에 발급됩니다\ 발급받은 운영 환경 API key는 운영 환경에서만 사용할 수 있습니다.
{% hint style="info" %} #### API Key와 Merchant 구분 * `Merchant` 값은 하위사업장을 구분하는 값으로 일반적인 상점아이디(MID)와 유사합니다. * 파트너에서 생성한 `Merchant` 는 결제선생에 전달되면 해당 사업장은 파트너의 하위사업장으로 등록됩니다. {% endhint %} ## 버전별 API key 사용하기 API key는 결제선생 api가 제공하는 v1, v2 버전의 모든 API에서 제한없이 사용할 수 있습니다 # 요청·응답 결제선생 파트너에서는 REST API(Representational State Transfer API) 형태로 서비스를 제공하고 있습니다. ### 요청 본문 결제선생 API를 호출할 때는 Json 형식을 사용해주세요. Charset의 경우에는 국제 표준 인코딩 방식인 UTF-8만 지원합니다. | key | value | description | | ------------ | ---------------- | ----------- | | Content-Type | application/json | 요청 데이터 타입 | | charset | UTF-8 | 언어 설정 | ### 응답 본문 API 요청시 페이민트의 서버가 클라이언트 서버에게 전달하는 데이터 양식입니다. 모든 API 응답, 요청 본문은 JSON 형식입니다. **API v2 객체** ```json { "code": "0000", //응답 코드 "message": "Success", //응답 메세지 "data": { //응답 데이터 객체 } } ``` **API v1 객체** ```json { "code": "0000", //응답 코드 "message": "Success", //응답 메세지 "apikey": "partner-api-key", "member": "partner-merchant-1", "merchant": "partner-user-1", //api별 데이터 추가 } ``` **응답 HTTP 상태 코드** | HTTP 상태 코드 | 설명 | | -------------------- | -------------------------------------------------------------------------------- | | `200 - OK` | 요청이 성공적으로 처리되었습니다. | | `400 - Bad Request` | 요청을 처리할 수 없습니다. 필수 파라미터를 보내지 않았거나, 파라미터 포맷이 잘못되었을 때 돌아오는 응답입니다. 요청 파라미터를 확인해주세요. | | `404 - Not Found` | 요청한 리소스가 존재하지 않습니다. 요청한 API 주소를 다시 한번 확인해보세요. | | `500 - Server Error` | 결제선생 서버에서 에러가 발생했습니다. | # 웹뷰 연동하기 모바일 웹뷰 결제는 앱투앱(App to App) 이동이 필요한데요. 결제기관의 앱스킴 목록과 OS별 이동 방법을 알아보세요. 모바일 결제에서는 어떤 과정이 있을까요? 구매자의 입장에서 생각해볼게요. 상점 앱에서 결제하기를 누르면 구매자가 선택한 카드사·은행 앱으로 이동하는데요. 이 과정이 바로 앱투앱 이동입니다. 이동하고 싶은 카드사·은행 앱의 앱스킴을 미리 등록해야 문제없이 앱투앱 이동을 할 수 있어요. 온라인 결제 과정에서 등록해야 되는 앱스킴을 알려드릴게요. ## 앱스킴 리스트 내 상점 앱에서 인증을 위해 이동하게 되는 3rd-party 앱에는 ISP 앱, 카드사별 앱카드 등이 있습니다. 필요한 앱스킴을 추가해보세요.
카드사·본인확인기관앱스킴
국민카드kb-acp://, liivbank:/, newliiv://, kbbank://
농협카드nhappcardansimclick://, nhallonepayansimclick://, nonghyupcardansimclick://
롯데카드lottesmartpay://, lotteappcard://
삼성카드mpocket.online.ansimclick://, mpocket.ansimclick.cert://, vguardstart://, samsungpay://,monimopay://, monimopayauth://
신한카드shinhan-sr-ansimclick://, smshinhanansimclick://
우리카드com.wooricard.wcard://, newsmartpib://
하나카드cloudpay://, hanawalletmembers://
현대카드hdcardappcardansimclick://, smhyundaiansimclick://
간편결제shinsegaeeasypayment://, payco://, lpayapp://
ISP(BC/국민)ispmobile://
카카오페이kakaobank://
네이버페이
Lpay
# 청구서 발송 및 파기 ## 청구서 발송 청구서 발송은 파트너사가 페이민트에 요청하면, 페이민트가 고객에게 카카오 알림톡으로 청구서를 발송하는 구조입니다. {% hint style="info" icon="file-lines" %} [청구서 발송 및 파기](/api/api-v2/send#post-bill) {% endhint %}
#### **주요 파라미터 안내**
파라미터설명
bill_issuer청구서에 노출되는 발급처명입니다. 값을 전달하면 해당 값이 노출되고, 미전달 시 사업장명이 기본 노출됩니다.
expire_dt청구서 유효기간으로 YYYY-MM-DD 형식이며, 입력일 자정까지 유효합니다.
callbackURL고객 결제 완료 후 승인 결과를 수신할 파트너사 URL입니다. 이 값이 정확하지 않으면 승인동기화를 받을 수 없으므로 반드시 정확히 입력해주세요.
{% hint style="warning" %} #### 주의사항 * `bill_id`는 중복 불가합니다. 이미 사용된 bill\_id로 발송 요청 시 `9800` 에러가 반환됩니다. * `hash` 값은 phone 유무에 따라 생성 규칙이 달라지므로 반드시 확인해주세요. * `price`는 String 타입(최대 10자리)이며, 숫자만 입력합니다. {% endhint %} {% hint style="warning" %} #### 주의사항 URL 방식에서 자동결제를 사용하는 경우 phone 필드 주의\ sendType=URL로 청구서를 발송할 때, phone 필드에 실제 전화번호를 사용하면 동일 가맹점 내 여러 고객의 전화번호가 겹칠 경우 다른 고객의 카드로 자동결제가 처리될 수 있습니다.\ URL 방식에서 RP를 함께 사용하는 경우, phone 필드에 실제 전화번호 대신 파트너 시스템의 고유 고객 식별자를 넣을 것을 권장합니다.\ phone 필드는 핸드폰 번호 형식 검증이 없으므로 "user-001", "member\_abc" 같은 값을 그대로 사용할 수 있습니다. {% endhint %} ## ### 청구서 재발송 이미 발송된 청구서를 고객에게 다시 보내는 기능입니다. 청구서 자체는 동일하며, 카카오톡 알림톡이 새로 발송되면서 **발송톡(쌤포인트)이 차감**됩니다. {% hint style="info" icon="file-lines" %} [청구서 발송 및 파기](/api/api-v2/send#post-bill-resend) {% endhint %} #### **사용 시나리오** * 고객이 핸드폰을 분실한 경우 * 기존 알림톡을 삭제하여 청구서 링크를 찾을 수 없는 경우 {% hint style="warning" %} #### 주의사항 * 재발송 시에도 쌤포인트가 차감되므로, 불필요한 재발송은 피해야 합니다. * 기존 `bill_id`를 그대로 사용해야 합니다. {% endhint %} ## 청구서 파기 결제가 진행되지 않은(미결제 상태인) 청구서를 파기하는 기능입니다. {% hint style="info" icon="file-lines" %} [청구서 발송 및 파기](/api/api-v2/send#post-bill-destroy) {% endhint %}
{% hint style="warning" %} #### 주의사항 * **결제가 완료된 청구서는 파기할 수 없습니다.** 결제 완료 건은 "결제 취소" API를 사용해야 합니다. * 파기와 취소는 다른 개념입니다. 파기는 미결제 청구서를 무효화하는 것이고, 취소는 이미 결제된 건을 환불 처리하는 것입니다. * `hash`는 `{bill_id} + "," + {price}` 로 생성합니다. * 매니저사이트/매니저앱에서 직접 청구서 파기된 경우 API를 통해 `callback`이 전달되지 않습니다. {% endhint %} # 수납 및 결제취소 ## 수납 시 승인동기화 고객이 청구서를 통해 결제를 완료하면, 페이민트가 파트너사의 `callbackURL`로 승인 결과를 전달합니다. 이 과정을 "승인동기화"라고 합니다. {% hint style="info" icon="file-lines" %} [수납 및 결제취소](/api/api-v1/acceptance#post-callbackurl) {% endhint %}
#### **핵심 포인트** * 호출 방향이 **페이민트 → 파트너사**입니다. 파트너사는 이 데이터를 수신할 REST API를 미리 구현해두어야 합니다. * 결제 실패 및 취소 건은 파트너사로 결과를 전달하지 않습니다. 결제 성공 건만 결과를 전달합니다. * 파트너사는 승인 결과를 수신한 후 반드시 아래의 형태와 값을 동일하게 세팅하여 정상 응답을 반환해야 합니다. \ 이 응답 데이터가 일치하지 않으면 검수가 완료되지 않습니다. ```json //response coee { "code": "0000", "msg": "성공하였습니다." } ``` #### **수신 데이터에서 확인할 주요 필드**
파라미터설명
appr_state결제 상태 : F:결제완료, W:미결제, C:취소, D:파기
appr_pay_type결제수단 : CARD_VAN, KEYIN, OFFLINE_CARD, OFFLINE_CASH
appr_num승인번호 : 결제 취소 시 원거래 승인번호로 필요합니다.
appr_dt승인일시 : YYYYMMDDHHMMSS
{% hint style="warning" %} #### 주의사항 * 결제 실패, 결제 취소 시 상태값을 전달되지 않습니다. * 연동검수 시 승인동기화에 대한 정상 수신 응답 `0000`을 반환 받아야 검수가 완료됩니다. * 승인동기화 데이터는 파트너사가 자체적으로 저장·관리해야 합니다. * 현금영수증 결제인 경우 appr\_cash\_num, appr\_cash\_trader, appr\_cash\_issuance\_number 필드가 함께 전달됩니다. {% endhint %} ## 결제 취소 이미 결제가 완료된 건에 대한 결제를 취소 처리합니다. {% hint style="info" icon="file-lines" %} [수납 및 결제취소](/api/api-v2/acceptance#post-bill-cancel) {% endhint %}
{% hint style="warning" %} #### 주의사항 * 취소 시 `bill_id`는 원래 발송 요청 시 사용한 값과 동일해야 합니다. * `hash`는 `{bill_id} + "," + {price}` 로 생성합니다. (발송 요청과 달리 phone이 포함되지 않습니다.) * 이미 취소된 건을 다시 취소하면 `9970` 에러가 반환됩니다. * 취소 응답에는 `appr_num`(취소 거래번호), `appr_origin_num`(원거래 승인번호), `appr_cancel_dt`(취소일시)가 포함됩니다. * 매니저사이트/매니저앱에서 직접 결제 취소 및 청구서가 파기된 경우 API를 통해 `callback`이 전달되지 않습니다. {% endhint %} ## 결제 상태 조회 승인동기화 콜백을 놓쳤거나, 현재 청구서의 결제 상태를 확인하고 싶을 때 사용합니다. {% hint style="info" icon="file-lines" %} [수납 및 결제취소](/api/api-v2/acceptance#post-bill-read) {% endhint %} #### **사용 시나리오** * 콜백 수신 실패 시 결제 여부 확인 * 고객 문의 대응 시 현재 상태 조회 * 취소/파기 처리 전 상태 사전 확인 # 나눠서 결제 하나의 청구서에서 여러 결제를 처리하는 나눠서 결제 연동을 안내합니다. ## 나눠서 결제 나눠서 결제는 기존 V2 API의 청구서(`billId`)를 여러 번 결제하는 방식입니다.\ 각 결제 건은 고유한 `paymentId`를 가집니다. \ \ 하나의 청구서를 분할하여 여러 차례 나누어 결제하거나, 결제건별로 부분취소가 가능합니다.\
### 기존 결제와 차이점 | 구분 | 기존 단건 결제 | 나눠서 결제 | | ------ | ------------------ | --------------------------- | | 구조 | `billId` 1개당 결제 1건 | `billId` 1개에 여러 `paymentId` | | 승인 동기화 | 청구서당 1회 | 결제 건별로 여러 번 | | 결제 취소 | 청구서 전체 취소 | `paymentId`를 지정해 개별 취소 | | 상태 조회 | 단건 승인 결과 | `payments` 배열의 전체 결제 내역 | ### 핵심 연동 포인트 `billId`는 청구서를 식별합니다. `paymentId`는 해당 청구서의 개별 결제를 식별합니다. `billId`와 `paymentId` 조합은 결제 건을 고유하게 식별합니다. \ 승인 동기화 콜백을 받으면 두 값을 함께 저장하세요. {% hint style="warning" %} {% endhint %} ### 처리 흐름 {% stepper %} {% step %} #### 청구서를 생성합니다 `POST /bill`을 호출해 청구서를 발송하거나 결제 URL을 생성합니다. `sendType`은 `TALK` 또는 `URL`을 사용합니다. {% endstep %} {% step %} #### 승인 동기화를 수신합니다 결제가 승인되면 등록한 `callbackUrl`로 결과가 전달됩니다. 콜백마다 `paymentId`를 확인하고 결제 건을 저장하세요. 정상 처리 후 성공 응답을 반환하세요. {% endstep %} {% step %} #### 필요하면 개별 결제를 취소합니다 `POST /bill/cancel` 요청의 `bill` 객체에 취소할 `paymentId`를 포함합니다. 특정 결제 건만 취소할 수 있습니다. {% endstep %} {% step %} #### 결제 내역을 조회합니다 `POST /bill/read/detail`을 호출해 청구서의 전체 결제 내역을 확인합니다. 응답의 `payments` 배열에서 누적 결제와 각 결제 상태를 확인하세요. {% endstep %} {% endstepper %} ### API 목록 | API | Method / URI | 용도 | | ------ | ------------------------ | -------------------------------- | | 청구서 생성 | `POST /bill` | 청구서를 발송하거나 결제 URL을 생성합니다. | | 승인 동기화 | `POST {callbackUrl}` | 승인 결과와 `paymentId`를 파트너사에 전달합니다. | | 결제 취소 | `POST /bill/cancel` | `paymentId`를 지정해 결제 건을 취소합니다. | | 청구서 파기 | `POST /bill/destroy` | 결제가 진행되지 않은 청구서를 파기합니다. | | 상세 조회 | `POST /bill/read/detail` | 청구서의 전체 결제 내역을 조회합니다. | ### 주요 파라미터 #### `paymentId` 승인 동기화 콜백에서 전달하는 결제 고유 번호입니다. 개별 결제 취소 시 필수입니다. `billId`와 함께 저장하세요. #### `payments` 상세 조회 응답에 포함되는 결제 내역 목록입니다. 각 항목에서 다음 정보를 확인할 수 있습니다. * `paymentTotalAmount`: 결제 금액 * `paymentStatus`: 결제 상태 * `doneApprovedAt`: 승인 완료 일시 ### 개발 유의사항 #### 콜백 중복 처리 동일한 `billId`의 콜백이 여러 번 전달될 수 있습니다. `paymentId`를 기본 키 또는 고유 키로 관리하세요. 이미 처리한 `paymentId`는 중복 반영하지 마세요. #### 부분 취소 전체 청구서가 아닌 특정 결제 건을 취소할 수 있습니다. 취소 요청 시 반드시 대상 결제의 `paymentId`를 포함하세요. #### 테스트 환경 개발 환경인 `stg.paymint.co.kr`에서는 20,000원 이상만 청구서를 생성할 수 있습니다. # 하위사업장 등록 하위사업장 등록 API는 파트너의 가맹점이 결제선생 사업장으로 등록하고 파트너의 하위사업장으로 등록하는 프로세스를 제공합니다. 하위사업장 등록 API는 하위사업장 등록이 빈번하게 발생하는 비즈니스 환경의 경우 운영 효율을 높일 수 있습니다. {% hint style="info" icon="file-lines" %} [하위사업장 가입 및 등록](/api/api-v2/sub-business) {% endhint %} ## 하위사업장 등록 URL 요청 하위사업장 등록 API를 요청하여 반환 받은 `URL` 를 가맹점에게 제공하세요.
#### API 호출 시 전달 파라미터
파라미터필수 여부설명
멤버 ID (Member ID)필수파트너사에서 관리하는 회원 식별값
머천트 ID (Merchant ID)필수파트너사에서 관리하는 사업장 식별값
사업자등록번호선택등록하려고 하는 가맹점의 사업자등록번호
콜백 URL필수연동 결과를 수신받을 파트너사 서버 URL
리다이렉트 URL선택연동 완료 후 이동할 파트너사 페이지 URL
## 하위사업장 등록 화면 플로우 가맹점은 `URL`을 통해 결제선생이 제공하는 화면에 접속하여 회원가입 또는 로그인하여 사업장을 파트너의 하위사업장으로 등록할 수 있습니다. #### 파라미터 및 연결 상태에 따른 표시 화면 API 호출 시 전달된 파라미터와 결제선생에 등록된 회원, 사업장의 상태에 따라 표시되는 화면이 달라집니다.
조건설명
멤버 ID 연결 여부파트너가 전달한 멤버 ID가 결제선생 회원과 연결되어 있는지 확인
머천트 ID 연결 여부파트너가 전달한 머천트 ID가 결제선생 사업장과 연결되어 있는지 확인
사업자등록번호 조회전달된 사업자등록번호로 등록된 사업장이 있는지 조회
#### 플로우 단계별 Callback 각 단계가 완료될때마다 관련 내용을 해당 관련 Callback를 전달합니다.
단계Callback설명
로그인 완료맴버 ID 연결기존 회원의 멤버 ID 연결
회원가입 완료맴버 ID 연결신규 가입한 회원의 멤버 ID 연결
사업장 등록심사중신규 사업장 등록 요청이 될 경우
사업장 등록 심사보완심사 결과 보안 상태가 될 경우
사업장 등록 심사반려심사 결과 반려 상태가 될 경우
사업장 등록 심사개시심사 결과 개시 상태가 될 경우
사업장 연결 완료머천트 ID 연결기존 결제선생에 등록된 사업장이 연결될 경우
## 표시 화면 안내 ### 회원가입 멤버 ID가 결제선생 회원과 연결되지 않은 경우 회원가입 화면이 제공됩니다.
### 사업장 등록 신규 사업장을 등록하는 흐름입니다.
**등록 절차** 1. 사업자등록번호 입력 (파트너에서 제공한 번호가 있으면 자동 노출, 변경 가능) 2. 사업장 정보 입력 (간판상호, 지점명, 사업장 전화번호 등) 3. 서류 첨부 (사업자등록증, 대표자 본인인증/신분증 등) 4. 약관 동의 (VAN 서비스 이용약관, 카드가맹 관련 동의) 5. 심사 요청 완료 ### 로그인 사업자등록번호로 조회된 기존 사업장이 있으나 멤버 ID가 연결되지 않은 경우, 로그인 화면이 제공됩니다.
### 사업장 연결 로그인한 회원이 관리하는 사업장 목록이 표시되며, 파트너와 연결할 사업장을 선택합니다.
### 연결된 사업장 정보 머천트 ID가 연결된 사업장과 연결 정보를 확인 할 수 있습니다.
## 클라이언트 환경별 지원 방식 결제선생 화면은 파트너사의 클라이언트 환경에 따라 다른 방식으로 제공됩니다.
환경구분새창 (blank)페이지 이동 (self)
PC - APP인앱 브라우저XO
PC - APP외부 브라우저X-
PC - WEB-OO
Mobile - APP인앱 브라우저XO
Mobile - APP외부 브라우저X-
Mobile - WEB-OO
{% hint style="warning" %} #### 주의사항 * **iframe 제공 불가**: 보안 정책상 iframe 내에서 결제선생 화면을 제공할 수 없습니다. * **리다이렉트 URL**: 파트너사의 환경에서 리다이렉트 URL이 정상 작동할 수 있는 구조여야 합니다. * 웹 환경: 리다이렉트 URL로 페이지 이동 * 앱 환경: 창닫기 브릿지 통신 {% endhint %} # 쌤포인트 조회 ## 쌤포인트 조회 API 호출을 통해 쌤포인트를 조회할 수 있습니다. 최초 계약조건으로 쌤포인트가 소진되는 `파트너 관리 사업장`, `하위 사업장` 에서 소진될 수 있습니다. {% hint style="info" icon="file-lines" %} 파트너 관리 사업장 : [쌤포인트](/api/api-v2/ssam-point#post-read-remain_count) 하위 사업장 : [쌤포인트](/api/api-v2/ssam-point#post-read-merchant-remain_count) {% endhint %} ```json { "code": "0000", "message": "성공하였습니다.", "data": { "balance": 1, "chargeUrl": "https://쌤포인트_충전_ur" } } ``` ## 쌤포인트 충전 URL 쌤포인트 조회 시 쌤포인트를 조회할 수 있는 충전 URL을 전달드립니다.\ `chargeUrl` 의 값에 전달된 URL을 활용하여 쌤포인트를 충전할 사용자에게 노출해주세요. {% hint style="info" %} [쌤포인트 충전 방법](/understanding/ssampoint) {% endhint %} # 연동 검수 요청하기 테스트 검수 - 연동개발이 정상적으로 되었는지 페이민트 내부적으로 로그를 확인하는 검수가 필요합니다.\ 아래 항목에 테스트를 진행하신 거래건의 BILL-ID 입력하여 결제선생 기술지원팀 메일로 회신해 주세요. {% hint style="info" %} 결제선생 기술지원팀 : {% endhint %} 연동개발 검수 완료 확인 후 운영정보를 제공해 드립니다. \ **BILL-ID 필요 정보** * 결제승인 : * 승인취소 : * 청구서 파기 : * 청구서 조회 : * 승인 동기화 (1. 결제승인 건에 대해 페이민트 쪽에서 "0000" 응답을 받으면 검수완료) 연동 개발관련 궁금하신 내용은 개발지원 메일로 문의해 주세요. # 기타 연동 케이스 # 세금처리 결제선생에서 청구서를 발송할 때, 해당 거래의 과세 유형(과세/면세)을 설정할 수 있습니다. 과세 유형에 따라 고객에게 표시되는 금액 구성과 현금영수증 발급 시 세금 계산 방식이 달라지므로, 파트너사의 업종 및 상품 특성에 맞게 올바르게 설정해야 합니다. ## 과세 유형 구분 과세 유형은 크게 세 가지로 나뉩니다. * **과세**: 부가가치세(VAT)가 포함된 거래입니다. 결제 금액에서 공급가액과 부가세(10%)가 자동으로 분리되어 표시됩니다. 일반적인 상품 판매, 서비스 제공 등 대부분의 거래가 이에 해당합니다. * **면세**: 부가가치세가 면제되는 거래입니다. 결제 금액 전체가 공급가액으로 처리되며 부가세는 0원입니다. 교육 서비스, 의료, 도서 등 부가가치세법상 면세 대상 업종에 해당하는 경우 사용합니다. ## 과세 설정 방식 과세/면세 설정은 **사업장 단위**로 결제선생 매니저사이트에서 관리됩니다. 사업장 설정에서 부가세 설정 메뉴를 통해 기본 과세 유형을 지정할 수 있습니다. API 연동 시에는 사업장에 설정된 과세 유형이 기본 적용되므로, 별도의 파라미터 전달 없이도 사업장 설정을 따릅니다. ## 현금영수증 발급 시 세금 처리 현금영수증 발급 API를 통해 현금영수증을 발급할 때는 파트너사에서 공급가액(`supply_price`)과 세액(`tax`)을 직접 구분하여 전달해야 합니다. * **과세 거래의 경우**: 결제 금액에서 부가세를 분리하여 전달합니다. 예를 들어 결제 금액이 11,000원이면 공급가액 10,000원, 세액 1,000원으로 분리합니다. * **면세 거래의 경우**: 결제 금액 전체를 공급가액으로 전달하고, 세액은 0으로 설정합니다. 예를 들어 결제 금액이 10,000원이면 공급가액 10,000원, 세액 0원으로 전달합니다. {% hint style="warning" %} #### 주의사항 * 사업장의 과세 유형이 실제 업종과 맞는지 반드시 확인하세요. 면세 사업자가 과세로 설정되어 있거나 그 반대인 경우, 세금계산서 및 현금영수증 발급에 문제가 발생할 수 있습니다. * 현금영수증 발급 시 `price`는 반드시 `supply_price + tax`와 일치해야 합니다. 금액이 불일치하면 발급이 실패합니다. * 과세 유형 변경이 필요한 경우 결제선생 매니저사이트의 부가세 설정에서 변경하거나, 결제선생 파트너 메일로 문의하세요. {% endhint %} # 발급처 청구서 발급처명은 고객이 청구서를 받았을 때 "어디에서 보낸 청구서인지"를 나타내는 표시 정보입니다. 알림톡 또는 청구서 화면에서 고객에게 노출되므로, 고객이 쉽게 인식할 수 있는 이름으로 설정하는 것이 중요합니다. ## 발급처명 결정 규칙 청구서 발급처명은 발송 요청 API의 `bill_issuer` 파라미터를 통해 제어합니다. 동작 방식은 다음과 같습니다. * `bill_issuer` 파라미터를 전달한 경우 : 전달한 값이 청구서의 발급처명으로 표시됩니다. 파트너사에서 원하는 이름을 직접 지정할 수 있습니다. * `bill_issuer` 파라미터를 전달하지 않은 경우 : 결제선생에 등록된 사업장명이 기본 발급처명으로 사용됩니다. ## 활용 시나리오 * 단독사업자 : 모든 청구서에 동일한 브랜드명을 노출하고 싶다면 `bill_issuer`에 브랜드명을 고정하여 전달합니다. 예를 들어 본사명이 "주식회사 ABC교육"이지만 고객에게는 "ABC학원"으로 보여주고 싶은 경우에 활용합니다. * 다수 지점 운영 : 지점별로 다른 발급처명을 표시해야 하는 경우, 발송 요청 시마다 해당 지점의 이름을 `bill_issuer`에 동적으로 전달합니다. 예를 들어 "ABC학원 강남점", "ABC학원 서초점"과 같이 지점을 구분할 수 있습니다. * 제휴사업자 : 플랫폼 파트너사가 다수의 하위사업장 청구서를 발송하는 경우, 각 하위사업장의 이름을 `bill_issuer`로 전달하면 고객에게 실제 서비스를 제공하는 사업장명이 표시됩니다. * 발급처명을 별도 관리하지 않는 경우: `bill_issuer`를 전달하지 않으면 사업장 등록 시 입력한 사업장명이 자동으로 사용되므로, 별도 설정 없이 기본값을 사용할 수 있습니다. {% hint style="warning" %} #### 주의사항 * `bill_issuer`는 최대 50자까지 입력 가능합니다. 고객이 청구서를 확인하는 환경(알림톡, 모바일 화면 등)을 고려하여 간결하게 작성하는 것을 권장합니다. * 발급처명은 고객이 결제 주체를 인식하는 핵심 정보입니다. 고객이 혼란을 느끼지 않도록 실제 서비스명 또는 매장명과 일치시키세요. * 발급처명은 청구서마다 개별 설정이 가능합니다. 동일 사업장에서도 청구서별로 다른 발급처명을 표시할 수 있으므로, 파트너사 내부 정책에 맞게 유연하게 활용하세요. * 승인동기화(콜백) 응답에도 `bill_issuer` 값이 포함되어 반환되므로, 파트너사에서 발급처별 거래 관리가 필요한 경우 이 값을 활용할 수 있습니다. {% endhint %} # 배포 체크리스트 연동검수를 완료하고 운영 배포를 하기전 체크리스트를 확인해보세요 ### API key / URL 확인 * [ ] 운영환경의 API key를 사용하고 있나요? * [ ] 개발 환경의 URL을 사용하고 있나요? # 연동 환경 정보 결제선생 파트너 연동을 위한 기본적인 환경 정보와 접근 정책에 대해 안내드립니다. ## 파트너 연결 환경 결제선생의 파트너 연동에는 2가지 환경이 제공됩니다. ### 도메인 정보 #### API V2.0
statusdomaindescriptionenv
SANDBOXhttps://sandbox.paymint.co.kr/partnerv2 버전의 신규 시스템개발
PROD연동 검수 완료 후 별도 제공운영
#### API V1.0
statusdomaindescriptionenv
SANDBOXhttps://stg.paymint.co.kr/partnerv1 버전의 기존 시스템개발
PROD연동 검수 완료 후 별도 제공운영
#### 포트 번호 **허용 포트 : http(80), https(443)** 페이민트에서는 파트너의 편의성을 위하여 http, https 통신 모두 지원하고 있습니다.\ 다만 결제 정보와 개인 정보를 강화를 위하여 기본적으로 https 통신을 권장합니다. #### IP 자체 방화벽을 구축하고 계실 경우 아래의 IP주소를 접근 제어 목록에 등록해주세요. * 52.78.118.82 * 52.78.236.125 * 52.79.214.146 * 3.36.243.225 * 3.39.97.44 * 13.209.0.172 * 13.209.248.179 #### TLS 페이민트에서는 TLS 버전 1.2 이상만 지원합니다. \ 하위 TLS 버전을 사용하고 계시다면 1.2 이상 버전을 사용해야합니다. *** ## :circle-info: :messages-question: 더 궁금한 내용이 있나요? [자주하는 질문](https://developers.payssam.kr/faq/) :message-code: 기술지원이 필요하신가요? [이메일 보내기](mailto:partner_dev@paymint.co.kr) # API key 결제선생 파트너는 인증에 API key를 사용합니다. API 연동에 필요한 통신과 사업장을 인증하는 역할을 합니다. ## API key 이해하기 결제선생 파트너 연동 시 각 파트너별로 고유한 API key를 발급받게 됩니다.\ API key는 사업장 정보를 인증함과 동시에 결제선생 API에서 유효한 파트너를 통해 호출되었다는 인증도 같이 진행됩니다.\ 따라서 발급받은 API key가 외부에 유출되지 않도록 유의하셔야 합니다. **개발환경키는 파트너 계약을 맺음과 동시에 발급이 되며,**\ **운영키를 발급받기 위해서는 개발환경에서 연동검수가 완료되어야 합니다.** *** ## :circle-info: :messages-question: 더 궁금한 내용이 있나요? [자주하는 질문](https://developers.payssam.kr/faq/) :message-code: 기술지원이 필요하신가요? [이메일 보내기](mailto:partner_dev@paymint.co.kr) # Merchant ID # 요청·응답 결제선생 파트너에서는 REST API(Representational State Transfer API) 형태로 서비스를 제공하고 있습니다. ## 요청 본문 결제선생 API를 호출할 때는 Json 형식을 사용해주세요.\ Charset의 경우에는 국제 표준 인코딩 방식인 UTF-8만 지원합니다.
keyvaluedescription
Content-Typeapplication/json요청 데이터 타입
charsetUTF-8언어 설정
## 응답 본문 API 요청시 페이민트의 서버가 클라이언트 서버에게 전달하는 데이터 양식입니다.\ 모든 API 응답, 요청 본문은 JSON 형식입니다. #### API v2 객체 
{
  "code": "0000", //응답 코드
  "msg": "Success", //응답 메세지
  "data": { //응답 데이터 객체
  }
}
#### API v1 객체 ```json { "code": "0000", //응답 코드 "message": "Success", //응답 메세지 "apikey": "partner-api-key", "member": "partner-merchant-1", "merchant": "partner-user-1", //api별 데이터 추가 } ``` #### 응답 HTTP 상태 코드
HTTP 상태 코드설명
200 - OK요청이 성공적으로 처리되었습니다.
400 - Bad Request요청을 처리할 수 없습니다. 필수 파라미터를 보내지 않았거나, 파라미터 포맷이 잘못되었을 때 돌아오는 응답입니다. 요청 파라미터를 확인해주세요.
404 - Not Found요청한 리소스가 존재하지 않습니다. 요청한 API 주소를 다시 한번 확인해보세요.
500 - Server Error결제선생 서버에서 에러가 발생했습니다.
[^1]: # API 버전 V1, V2 API의 버전 차이에 대해 확인 해보세요 결제선생은 두가지 버전의 API를 제공하고 있습니다. ### V2 API > **현재 권장 버전입니다.** 신규 연동시 V2 API 사용을 권장합니다. * 최신 기능이 반영된 현행 버전이며, 이후 지속적으로 기능 업데이트 예정입니다. * 새로운 기능 추가 및 개선은 V2 API에만 적용됩니다. * 보안 패치 및 버그 수정도 V2 API를 기준으로 제공됩니다. * 기존 V1 사용 파트너사는 V2로의 마이그레이션을 권장드립니다. ### v1 API > **신규 연동을 권장하지 않습니다.** 기존 연동 유지 목적의 레거시 버전입니다. * 하위 호환성 유지를 위해 운영 중이나, 추가 기능 개발이 중단된 레거시 버전입니다. * 신규 기능, 개선 사항은 반영되지 않습니다. * 중대한 보안 이슈 외에는 업데이트가 제공되지 않습니다. # 청구서 청구서를 발송하고 관리하는 API를 안내합니다. *** ## 청구서 발송
> 결제 금액을 결제 고객에게 청구하기 위해 청구서를 생성하고\ > sendType에 따라 청구서를 발송합니다.\ > \ > 발송방식 sendType\ > TALK : 생성된 청구서를 결제선생이 발송하는 방식\ > URL : 생성된 청구서의 URL을 전달하는 방식
```json {"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/bill":{"post":{"tags":["청구서 발송/파기"],"summary":" 청구서 발송\n","description":" 결제 금액을 결제 고객에게 청구하기 위해 청구서를 생성하고\n sendType에 따라 청구서를 발송합니다.\n\n 발송방식 sendType\n TALK : 생성된 청구서를 결제선생이 발송하는 방식\n URL : 생성된 청구서의 URL을 전달하는 방식\n","operationId":"billSend","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillRequest"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponseBillResponse"}}}}}}}},"components":{"schemas":{"BillRequest":{"type":"object","description":"청구서 생성 요청 (sendType=TALK: 카카오톡 발송 / sendType=URL: URL만 응답)","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32,"minLength":0},"member":{"type":"string","description":"파트너 사용자 코드","maxLength":60,"minLength":0},"merchant":{"type":"string","description":"파트너 매장 코드","maxLength":60,"minLength":0},"bill":{"$ref":"#/components/schemas/CreateBillInfo"}},"required":["apiKey","member","merchant"]},"CreateBillInfo":{"type":"object","properties":{"billId":{"type":"string","description":"청구서 ID","maxLength":20,"minLength":1},"sendType":{"type":"string","description":"발송 방식: TALK (카카오톡 발송) 또는 URL (URL만 응답)","enum":["TALK","URL"]},"billIssuer":{"type":"string","description":"청구서 발급처명","maxLength":50,"minLength":0},"productName":{"type":"string","description":"청구 사유","minLength":1},"price":{"type":"string","description":"결제 금액","minLength":1},"supplyPrice":{"type":"string","description":"공급가액"},"tax":{"type":"string","description":"세액"},"memberName":{"type":"string","description":"고객명","minLength":1},"phone":{"type":"string","description":"고객 전화번호","minLength":1},"message":{"type":"string","description":"안내메세지"},"expireDt":{"type":"string","description":"유효기간 YYYY-MM-DD"},"hash":{"type":"string","description":" 통신 암호 키\n {phone} 값이 설정된 경우 {bill_id} + \",\" + {phone} + \",\" + {price} 값으로 Hash 생성\n {phone} 값이 설정되어 있지 않은 경우 {bill_id} + \",\" + {price} 값으로 Hash 생성\n SHA-256으로 생성합니다\n","minLength":1},"callbackUrl":{"type":"string","description":"결제 완료 콜백 URL","minLength":1},"pageRedirectUrl":{"type":"string","description":"결제 완료 후 리다이렉트 URL (sendType=URL 인 경우에만 활성화)"}},"required":["billId","callbackUrl","hash","memberName","phone","price","productName","sendType"]},"BaseResponseBillResponse":{"type":"object","description":"공통 API 응답 포맷 (api.spec: code/message/data)","properties":{"code":{"type":"string","description":"응답 코드"},"message":{"type":"string","description":"응답 메시지"},"data":{"$ref":"#/components/schemas/BillResponse","description":"응답 데이터"}}},"BillResponse":{"type":"object","description":"청구서 생성 응답","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32,"minLength":0},"member":{"type":"string","description":"파트너 사용자 코드","maxLength":60,"minLength":0},"merchant":{"type":"string","description":"파트너 매장 코드","maxLength":60,"minLength":0},"billId":{"type":"string","description":"청구서 ID"},"hash":{"type":"string","description":"요청 시 전달된 해시값"},"shortUrl":{"type":"string","description":"생성된 청구서 단축 URL"}},"required":["apiKey","member","merchant"]}}}} ``` ## 카카오톡 재발송 > 기발송된 청구서를 재발송합니다.\ > 청구 내용은 동일하며 알림톡이 새로 발송되므로 쌤포인트는 차감됩니다.\ > \ > 사용 시나리오\ > \- 고객이 핸드폰을 분실한경우\ > \- 기존 알림톡을 삭제하여 청구서 링크를 찾을 수 없는 경우
```json {"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/bill/resend":{"post":{"tags":["청구서 발송/파기"],"summary":"카카오톡 재발송","description":" 기발송된 청구서를 재발송합니다.\n 청구 내용은 동일하며 알림톡이 새로 발송되므로 쌤포인트는 차감됩니다.\n\n 사용 시나리오\n - 고객이 핸드폰을 분실한경우\n - 기존 알림톡을 삭제하여 청구서 링크를 찾을 수 없는 경우\n","operationId":"billResend","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillResendRequest"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponseBillResendResponse"}}}}}}}},"components":{"schemas":{"BillResendRequest":{"type":"object","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32,"minLength":0},"member":{"type":"string","description":"파트너 사용자 코드","maxLength":60,"minLength":0},"merchant":{"type":"string","description":"파트너 매장 코드","maxLength":60,"minLength":0},"bill":{"$ref":"#/components/schemas/ResendBillInfo"}},"required":["apiKey","member","merchant"]},"ResendBillInfo":{"type":"object","properties":{"billId":{"type":"string","description":"청구서 ID","maxLength":20,"minLength":1}},"required":["billId"]},"BaseResponseBillResendResponse":{"type":"object","description":"공통 API 응답 포맷 (api.spec: code/message/data)","properties":{"code":{"type":"string","description":"응답 코드"},"message":{"type":"string","description":"응답 메시지"},"data":{"$ref":"#/components/schemas/BillResendResponse","description":"응답 데이터"}}},"BillResendResponse":{"type":"object","description":"카카오톡 청구서 재발송 응답","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키"},"billId":{"type":"string","description":"재발송된 청구서 ID"}}}}}} ``` ## 청구서 단건 조회 > 발송된 청구서에 대한 결제 상태를 조회합니다.\ > \ > appr\_state : F(결제완료), W(미결제), C(취소), D(파기)\ > 각 상태는 다음과 같이 변경될 수 있습니다.\ > 1\. W(미결제) -> F(결제완료) -> C(취소)\ > 2\. W(미결제) -> D(파기)
```json {"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/bill/read":{"post":{"tags":["청구서 ERP 연동 (취소/조회)"],"summary":"청구서 단건 조회","description":" 발송된 청구서에 대한 결제 상태를 조회합니다.\n\n appr_state : F(결제완료), W(미결제), C(취소), D(파기)\n 각 상태는 다음과 같이 변경될 수 있습니다.\n 1. W(미결제) -> F(결제완료) -> C(취소)\n 2. W(미결제) -> D(파기)\n","operationId":"billRead","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillReadPortRequest"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponseBillReadPortResponse"}}}}}}}},"components":{"schemas":{"BillReadPortRequest":{"type":"object","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32,"minLength":0},"member":{"type":"string","description":"파트너 사용자 코드","maxLength":60,"minLength":0},"merchant":{"type":"string","description":"파트너 매장 코드","maxLength":60,"minLength":0},"bill":{"$ref":"#/components/schemas/ReadBillInfo"}},"required":["apiKey","member","merchant"]},"ReadBillInfo":{"type":"object","properties":{"billId":{"type":"string","description":"청구서 ID","maxLength":20,"minLength":1}},"required":["billId"]},"BaseResponseBillReadPortResponse":{"type":"object","description":"공통 API 응답 포맷 (api.spec: code/message/data)","properties":{"code":{"type":"string","description":"응답 코드"},"message":{"type":"string","description":"응답 메시지"},"data":{"$ref":"#/components/schemas/BillReadPortResponse","description":"응답 데이터"}}},"BillReadPortResponse":{"type":"object","description":"원장 단건 조회 응답 — v1 SyncVO.Approval 과 동일한 필드 구성","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키"},"billId":{"type":"string","description":"청구서 ID"},"apprPayType":{"type":"string","description":"결제수단 코드 (간편결제 0 등)"},"apprCardType":{"type":"string","description":"카드 종류 (신용/체크/정보없음 등)"},"apprDt":{"type":"string","description":"승인 일시 (YYYYMMDDhhmmss)"},"apprOriginDt":{"type":"string","description":"원거래 승인 일시"},"apprPrice":{"type":"string","description":"승인 금액"},"apprIssuer":{"type":"string","description":"카드명 또는 은행명"},"apprIssuerCd":{"type":"string","description":"발행사 코드 또는 은행 코드"},"apprIssuerNum":{"type":"string","description":"카드번호 또는 계좌번호"},"apprAcquirerCd":{"type":"string","description":"매입사 코드"},"apprAcquirerNm":{"type":"string","description":"매입사명"},"apprNum":{"type":"string","description":"승인/취소 거래번호"},"apprOriginNum":{"type":"string","description":"원거래 승인번호"},"apprResCd":{"type":"string","description":"응답 코드"},"apprMonthly":{"type":"string","description":"할부 개월수 (0: 일시불)"},"apprState":{"type":"string","description":"승인 상태 (F:승인, W:대기, C:취소, D:파기)"},"apprCashNum":{"type":"string","description":"현금영수증 승인번호"},"apprCashTrader":{"type":"string","description":"현금영수증 발급 구분"},"apprCashIssuanceNumber":{"type":"string","description":"현금영수증 발급 요청 번호"},"apprCardMerchantNum":{"type":"string","description":"신용카드 가맹점 정보 (헬스케어 스펙)"},"catId":{"type":"string","description":"단말기 번호 (헬스케어 스펙)"},"dscTxNum":{"type":"string","description":"거래 고유번호 (헬스케어 스펙)"},"cardType":{"type":"string","description":"페이민트 공통 카드 타입 (영남대/KOCES 전용)"},"apprSign":{"type":"string","description":"전자서명 데이터 (헬스케어 스펙, Base64)"},"udItem":{"$ref":"#/components/schemas/JsonNode","description":"사용자 정의 항목 (원장 저장 시 전달된 JSON)"}}},"JsonNode":{}}}} ``` ## 청구서 파기 > 결제를 진행할 수 없도록 발송된 청구서를 파기합니다.\ > 결제가 승인되기 전에만 파기가 가능하며, 결제가 승인된 후에는 파기할 수 없습니다.\ > \ > \- 청구서를 잘못 보낸경우 사용합니다.
```json {"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/bill/destroy":{"post":{"tags":["청구서 발송/파기"],"summary":"청구서 파기","description":" 결제를 진행할 수 없도록 발송된 청구서를 파기합니다.\n 결제가 승인되기 전에만 파기가 가능하며, 결제가 승인된 후에는 파기할 수 없습니다.\n\n - 청구서를 잘못 보낸경우 사용합니다.\n","operationId":"billDestroy","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillDestroyRequest"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponseBillDestroyResponse"}}}}}}}},"components":{"schemas":{"BillDestroyRequest":{"type":"object","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32,"minLength":0},"member":{"type":"string","description":"파트너 사용자 코드","maxLength":60,"minLength":0},"merchant":{"type":"string","description":"파트너 매장 코드","maxLength":60,"minLength":0},"bill":{"$ref":"#/components/schemas/DestroyBillInfo"}},"required":["apiKey","member","merchant"]},"DestroyBillInfo":{"type":"object","properties":{"billId":{"type":"string","description":"청구서 ID","maxLength":20,"minLength":1},"price":{"type":"string","description":"결제 금액","minLength":1},"hash":{"type":"string","description":" 통신 암호 키\n {phone} 값이 설정된 경우 {bill_id} + \",\" + {phone} + \",\" + {price} 값으로 Hash 생성\n {phone} 값이 설정되어 있지 않은 경우 {bill_id} + \",\" + {price} 값으로 Hash 생성\n SHA-256으로 생성합니다\n","minLength":1}},"required":["billId","hash","price"]},"BaseResponseBillDestroyResponse":{"type":"object","description":"공통 API 응답 포맷 (api.spec: code/message/data)","properties":{"code":{"type":"string","description":"응답 코드"},"message":{"type":"string","description":"응답 메시지"},"data":{"$ref":"#/components/schemas/BillDestroyResponse","description":"응답 데이터"}}},"BillDestroyResponse":{"type":"object","description":"청구서 파기 응답","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키"},"billId":{"type":"string","description":"파기된 청구서 ID"}}}}}} ``` ## 청구서 결제 취소 > 결제가 완료된 청구서의 결제 상태를 승인 -> 승인취소 처리 합니다.\ > 결제가 완료되지 않은 청구서는 사용할 수 없습니다.
```json {"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/bill/cancel":{"post":{"tags":["청구서 ERP 연동 (취소/조회)"],"summary":"청구서 결제 취소","description":" 결제가 완료된 청구서의 결제 상태를 승인 -> 승인취소 처리 합니다.\n 결제가 완료되지 않은 청구서는 사용할 수 없습니다.\n","operationId":"billCancel","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillCancelPortRequest"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponseBillCancelPortResponse"}}}}}}}},"components":{"schemas":{"BillCancelPortRequest":{"type":"object","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32,"minLength":0},"member":{"type":"string","description":"파트너 사용자 코드","maxLength":60,"minLength":0},"merchant":{"type":"string","description":"파트너 매장 코드","maxLength":60,"minLength":0},"bill":{"$ref":"#/components/schemas/CancelBillInfo"}},"required":["apiKey","member","merchant"]},"CancelBillInfo":{"type":"object","properties":{"billId":{"type":"string","description":"청구서 ID","maxLength":20,"minLength":1},"price":{"type":"string","description":"결제 금액","minLength":1},"cancelReason":{"type":"string","description":"취소사유","maxLength":20,"minLength":0},"hash":{"type":"string","description":" 통신 암호 키\n {phone} 값이 설정된 경우 {bill_id} + \",\" + {phone} + \",\" + {price} 값으로 Hash 생성\n {phone} 값이 설정되어 있지 않은 경우 {bill_id} + \",\" + {price} 값으로 Hash 생성\n SHA-256으로 생성합니다\n","minLength":1}},"required":["billId","hash","price"]},"BaseResponseBillCancelPortResponse":{"type":"object","description":"공통 API 응답 포맷 (api.spec: code/message/data)","properties":{"code":{"type":"string","description":"응답 코드"},"message":{"type":"string","description":"응답 메시지"},"data":{"$ref":"#/components/schemas/BillCancelPortResponse","description":"응답 데이터"}}},"BillCancelPortResponse":{"type":"object","description":"청구서 결제 취소 응답","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키"},"member":{"type":"string","description":"파트너 매장 코드"},"merchant":{"type":"string","description":"파트너 사용자 코드"},"billId":{"type":"string","description":"청구서 ID"},"hash":{"type":"string","description":"요청 시 전달된 해시값"},"apprNum":{"type":"string","description":"취소 승인 거래번호"},"apprOriginNum":{"type":"string","description":"원거래 승인번호"},"apprCancelDt":{"type":"string","description":"취소 일시 (YYYYMMDDhhmmss)"}}}}}} ``` # 청구서 발송 및 파기 ## 청구서 발송
> 결제 금액을 결제 고객에게 청구하기 위해 청구서를 생성하고\ > sendType에 따라 청구서를 발송합니다.\ > \ > 발송방식 sendType\ > TALK : 생성된 청구서를 결제선생이 발송하는 방식\ > URL : 생성된 청구서의 URL을 전달하는 방식
```json {"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/bill":{"post":{"tags":["청구서 발송/파기"],"summary":" 청구서 발송\n","description":" 결제 금액을 결제 고객에게 청구하기 위해 청구서를 생성하고\n sendType에 따라 청구서를 발송합니다.\n\n 발송방식 sendType\n TALK : 생성된 청구서를 결제선생이 발송하는 방식\n URL : 생성된 청구서의 URL을 전달하는 방식\n","operationId":"billSend","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillRequest"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponseBillResponse"}}}}}}}},"components":{"schemas":{"BillRequest":{"type":"object","description":"청구서 생성 요청 (sendType=TALK: 카카오톡 발송 / sendType=URL: URL만 응답)","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32,"minLength":0},"member":{"type":"string","description":"파트너 사용자 코드","maxLength":60,"minLength":0},"merchant":{"type":"string","description":"파트너 매장 코드","maxLength":60,"minLength":0},"bill":{"$ref":"#/components/schemas/CreateBillInfo"}},"required":["apiKey","member","merchant"]},"CreateBillInfo":{"type":"object","properties":{"billId":{"type":"string","description":"청구서 ID","maxLength":20,"minLength":1},"sendType":{"type":"string","description":"발송 방식: TALK (카카오톡 발송) 또는 URL (URL만 응답)","enum":["TALK","URL"]},"billIssuer":{"type":"string","description":"청구서 발급처명","maxLength":50,"minLength":0},"productName":{"type":"string","description":"청구 사유","minLength":1},"price":{"type":"string","description":"결제 금액","minLength":1},"supplyPrice":{"type":"string","description":"공급가액"},"tax":{"type":"string","description":"세액"},"memberName":{"type":"string","description":"고객명","minLength":1},"phone":{"type":"string","description":"고객 전화번호","minLength":1},"message":{"type":"string","description":"안내메세지"},"expireDt":{"type":"string","description":"유효기간 YYYY-MM-DD"},"hash":{"type":"string","description":" 통신 암호 키\n {phone} 값이 설정된 경우 {bill_id} + \",\" + {phone} + \",\" + {price} 값으로 Hash 생성\n {phone} 값이 설정되어 있지 않은 경우 {bill_id} + \",\" + {price} 값으로 Hash 생성\n SHA-256으로 생성합니다\n","minLength":1},"callbackUrl":{"type":"string","description":"결제 완료 콜백 URL","minLength":1},"pageRedirectUrl":{"type":"string","description":"결제 완료 후 리다이렉트 URL (sendType=URL 인 경우에만 활성화)"}},"required":["billId","callbackUrl","hash","memberName","phone","price","productName","sendType"]},"BaseResponseBillResponse":{"type":"object","description":"공통 API 응답 포맷 (api.spec: code/message/data)","properties":{"code":{"type":"string","description":"응답 코드"},"message":{"type":"string","description":"응답 메시지"},"data":{"$ref":"#/components/schemas/BillResponse","description":"응답 데이터"}}},"BillResponse":{"type":"object","description":"청구서 생성 응답","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32,"minLength":0},"member":{"type":"string","description":"파트너 사용자 코드","maxLength":60,"minLength":0},"merchant":{"type":"string","description":"파트너 매장 코드","maxLength":60,"minLength":0},"billId":{"type":"string","description":"청구서 ID"},"hash":{"type":"string","description":"요청 시 전달된 해시값"},"shortUrl":{"type":"string","description":"생성된 청구서 단축 URL"}},"required":["apiKey","member","merchant"]}}}} ``` ## 청구서 파기 > 결제를 진행할 수 없도록 발송된 청구서를 파기합니다.\ > 결제가 승인되기 전에만 파기가 가능하며, 결제가 승인된 후에는 파기할 수 없습니다.\ > \ > \- 청구서를 잘못 보낸경우 사용합니다.
```json {"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/bill/destroy":{"post":{"tags":["청구서 발송/파기"],"summary":"청구서 파기","description":" 결제를 진행할 수 없도록 발송된 청구서를 파기합니다.\n 결제가 승인되기 전에만 파기가 가능하며, 결제가 승인된 후에는 파기할 수 없습니다.\n\n - 청구서를 잘못 보낸경우 사용합니다.\n","operationId":"billDestroy","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillDestroyRequest"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponseBillDestroyResponse"}}}}}}}},"components":{"schemas":{"BillDestroyRequest":{"type":"object","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32,"minLength":0},"member":{"type":"string","description":"파트너 사용자 코드","maxLength":60,"minLength":0},"merchant":{"type":"string","description":"파트너 매장 코드","maxLength":60,"minLength":0},"bill":{"$ref":"#/components/schemas/DestroyBillInfo"}},"required":["apiKey","member","merchant"]},"DestroyBillInfo":{"type":"object","properties":{"billId":{"type":"string","description":"청구서 ID","maxLength":20,"minLength":1},"price":{"type":"string","description":"결제 금액","minLength":1},"hash":{"type":"string","description":" 통신 암호 키\n {phone} 값이 설정된 경우 {bill_id} + \",\" + {phone} + \",\" + {price} 값으로 Hash 생성\n {phone} 값이 설정되어 있지 않은 경우 {bill_id} + \",\" + {price} 값으로 Hash 생성\n SHA-256으로 생성합니다\n","minLength":1}},"required":["billId","hash","price"]},"BaseResponseBillDestroyResponse":{"type":"object","description":"공통 API 응답 포맷 (api.spec: code/message/data)","properties":{"code":{"type":"string","description":"응답 코드"},"message":{"type":"string","description":"응답 메시지"},"data":{"$ref":"#/components/schemas/BillDestroyResponse","description":"응답 데이터"}}},"BillDestroyResponse":{"type":"object","description":"청구서 파기 응답","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키"},"billId":{"type":"string","description":"파기된 청구서 ID"}}}}}} ``` ## 카카오톡 재발송 > 기발송된 청구서를 재발송합니다.\ > 청구 내용은 동일하며 알림톡이 새로 발송되므로 쌤포인트는 차감됩니다.\ > \ > 사용 시나리오\ > \- 고객이 핸드폰을 분실한경우\ > \- 기존 알림톡을 삭제하여 청구서 링크를 찾을 수 없는 경우
```json {"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/bill/resend":{"post":{"tags":["청구서 발송/파기"],"summary":"카카오톡 재발송","description":" 기발송된 청구서를 재발송합니다.\n 청구 내용은 동일하며 알림톡이 새로 발송되므로 쌤포인트는 차감됩니다.\n\n 사용 시나리오\n - 고객이 핸드폰을 분실한경우\n - 기존 알림톡을 삭제하여 청구서 링크를 찾을 수 없는 경우\n","operationId":"billResend","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillResendRequest"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponseBillResendResponse"}}}}}}}},"components":{"schemas":{"BillResendRequest":{"type":"object","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32,"minLength":0},"member":{"type":"string","description":"파트너 사용자 코드","maxLength":60,"minLength":0},"merchant":{"type":"string","description":"파트너 매장 코드","maxLength":60,"minLength":0},"bill":{"$ref":"#/components/schemas/ResendBillInfo"}},"required":["apiKey","member","merchant"]},"ResendBillInfo":{"type":"object","properties":{"billId":{"type":"string","description":"청구서 ID","maxLength":20,"minLength":1}},"required":["billId"]},"BaseResponseBillResendResponse":{"type":"object","description":"공통 API 응답 포맷 (api.spec: code/message/data)","properties":{"code":{"type":"string","description":"응답 코드"},"message":{"type":"string","description":"응답 메시지"},"data":{"$ref":"#/components/schemas/BillResendResponse","description":"응답 데이터"}}},"BillResendResponse":{"type":"object","description":"카카오톡 청구서 재발송 응답","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키"},"billId":{"type":"string","description":"재발송된 청구서 ID"}}}}}} ``` # 수납 및 결제취소 ## 청구서 결제 취소 > 결제가 완료된 청구서의 결제 상태를 승인 -> 승인취소 처리 합니다.\ > 결제가 완료되지 않은 청구서는 사용할 수 없습니다.
```json {"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/bill/cancel":{"post":{"tags":["청구서 ERP 연동 (취소/조회)"],"summary":"청구서 결제 취소","description":" 결제가 완료된 청구서의 결제 상태를 승인 -> 승인취소 처리 합니다.\n 결제가 완료되지 않은 청구서는 사용할 수 없습니다.\n","operationId":"billCancel","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillCancelPortRequest"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponseBillCancelPortResponse"}}}}}}}},"components":{"schemas":{"BillCancelPortRequest":{"type":"object","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32,"minLength":0},"member":{"type":"string","description":"파트너 사용자 코드","maxLength":60,"minLength":0},"merchant":{"type":"string","description":"파트너 매장 코드","maxLength":60,"minLength":0},"bill":{"$ref":"#/components/schemas/CancelBillInfo"}},"required":["apiKey","member","merchant"]},"CancelBillInfo":{"type":"object","properties":{"billId":{"type":"string","description":"청구서 ID","maxLength":20,"minLength":1},"price":{"type":"string","description":"결제 금액","minLength":1},"cancelReason":{"type":"string","description":"취소사유","maxLength":20,"minLength":0},"hash":{"type":"string","description":" 통신 암호 키\n {phone} 값이 설정된 경우 {bill_id} + \",\" + {phone} + \",\" + {price} 값으로 Hash 생성\n {phone} 값이 설정되어 있지 않은 경우 {bill_id} + \",\" + {price} 값으로 Hash 생성\n SHA-256으로 생성합니다\n","minLength":1}},"required":["billId","hash","price"]},"BaseResponseBillCancelPortResponse":{"type":"object","description":"공통 API 응답 포맷 (api.spec: code/message/data)","properties":{"code":{"type":"string","description":"응답 코드"},"message":{"type":"string","description":"응답 메시지"},"data":{"$ref":"#/components/schemas/BillCancelPortResponse","description":"응답 데이터"}}},"BillCancelPortResponse":{"type":"object","description":"청구서 결제 취소 응답","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키"},"member":{"type":"string","description":"파트너 매장 코드"},"merchant":{"type":"string","description":"파트너 사용자 코드"},"billId":{"type":"string","description":"청구서 ID"},"hash":{"type":"string","description":"요청 시 전달된 해시값"},"apprNum":{"type":"string","description":"취소 승인 거래번호"},"apprOriginNum":{"type":"string","description":"원거래 승인번호"},"apprCancelDt":{"type":"string","description":"취소 일시 (YYYYMMDDhhmmss)"}}}}}} ``` ## 청구서 단건 조회 > 발송된 청구서에 대한 결제 상태를 조회합니다.\ > \ > appr\_state : F(결제완료), W(미결제), C(취소), D(파기)\ > 각 상태는 다음과 같이 변경될 수 있습니다.\ > 1\. W(미결제) -> F(결제완료) -> C(취소)\ > 2\. W(미결제) -> D(파기)
```json {"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/bill/read":{"post":{"tags":["청구서 ERP 연동 (취소/조회)"],"summary":"청구서 단건 조회","description":" 발송된 청구서에 대한 결제 상태를 조회합니다.\n\n appr_state : F(결제완료), W(미결제), C(취소), D(파기)\n 각 상태는 다음과 같이 변경될 수 있습니다.\n 1. W(미결제) -> F(결제완료) -> C(취소)\n 2. W(미결제) -> D(파기)\n","operationId":"billRead","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillReadPortRequest"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponseBillReadPortResponse"}}}}}}}},"components":{"schemas":{"BillReadPortRequest":{"type":"object","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32,"minLength":0},"member":{"type":"string","description":"파트너 사용자 코드","maxLength":60,"minLength":0},"merchant":{"type":"string","description":"파트너 매장 코드","maxLength":60,"minLength":0},"bill":{"$ref":"#/components/schemas/ReadBillInfo"}},"required":["apiKey","member","merchant"]},"ReadBillInfo":{"type":"object","properties":{"billId":{"type":"string","description":"청구서 ID","maxLength":20,"minLength":1}},"required":["billId"]},"BaseResponseBillReadPortResponse":{"type":"object","description":"공통 API 응답 포맷 (api.spec: code/message/data)","properties":{"code":{"type":"string","description":"응답 코드"},"message":{"type":"string","description":"응답 메시지"},"data":{"$ref":"#/components/schemas/BillReadPortResponse","description":"응답 데이터"}}},"BillReadPortResponse":{"type":"object","description":"원장 단건 조회 응답 — v1 SyncVO.Approval 과 동일한 필드 구성","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키"},"billId":{"type":"string","description":"청구서 ID"},"apprPayType":{"type":"string","description":"결제수단 코드 (간편결제 0 등)"},"apprCardType":{"type":"string","description":"카드 종류 (신용/체크/정보없음 등)"},"apprDt":{"type":"string","description":"승인 일시 (YYYYMMDDhhmmss)"},"apprOriginDt":{"type":"string","description":"원거래 승인 일시"},"apprPrice":{"type":"string","description":"승인 금액"},"apprIssuer":{"type":"string","description":"카드명 또는 은행명"},"apprIssuerCd":{"type":"string","description":"발행사 코드 또는 은행 코드"},"apprIssuerNum":{"type":"string","description":"카드번호 또는 계좌번호"},"apprAcquirerCd":{"type":"string","description":"매입사 코드"},"apprAcquirerNm":{"type":"string","description":"매입사명"},"apprNum":{"type":"string","description":"승인/취소 거래번호"},"apprOriginNum":{"type":"string","description":"원거래 승인번호"},"apprResCd":{"type":"string","description":"응답 코드"},"apprMonthly":{"type":"string","description":"할부 개월수 (0: 일시불)"},"apprState":{"type":"string","description":"승인 상태 (F:승인, W:대기, C:취소, D:파기)"},"apprCashNum":{"type":"string","description":"현금영수증 승인번호"},"apprCashTrader":{"type":"string","description":"현금영수증 발급 구분"},"apprCashIssuanceNumber":{"type":"string","description":"현금영수증 발급 요청 번호"},"apprCardMerchantNum":{"type":"string","description":"신용카드 가맹점 정보 (헬스케어 스펙)"},"catId":{"type":"string","description":"단말기 번호 (헬스케어 스펙)"},"dscTxNum":{"type":"string","description":"거래 고유번호 (헬스케어 스펙)"},"cardType":{"type":"string","description":"페이민트 공통 카드 타입 (영남대/KOCES 전용)"},"apprSign":{"type":"string","description":"전자서명 데이터 (헬스케어 스펙, Base64)"},"udItem":{"$ref":"#/components/schemas/JsonNode","description":"사용자 정의 항목 (원장 저장 시 전달된 JSON)"}}},"JsonNode":{}}}} ``` # 현금영수증 ## 현금영수증 발행 > 현금영수증을 발급합니다.
```json {"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/cash-receipt/issue":{"post":{"tags":["현금영수증 ERP 연동 (발행/취소/조회)"],"summary":"현금영수증 발행","description":" 현금영수증을 발급합니다.\n","operationId":"cashReceiptIssue","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CashReceiptIssueRequest"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponseCashReceiptIssueResponse"}}}}}}}},"components":{"schemas":{"CashReceiptIssueRequest":{"type":"object","description":"현금 영수증 발생 요청 DTO","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32,"minLength":0},"member":{"type":"string","description":"파트너 사용자 코드","maxLength":60,"minLength":0},"merchant":{"type":"string","description":"파트너 매장 코드","maxLength":60,"minLength":0},"cashReceipt":{"$ref":"#/components/schemas/IssueCashReceiptInfo"}},"required":["apiKey","member","merchant"]},"IssueCashReceiptInfo":{"type":"object","properties":{"billId":{"type":"string","description":"청구서 ID\n문자/숫자 20자리 (중복불가)\n- 개발: 사업자번호 + 10자리 자유롭게 사용\n- 운영: 20자리 자유롭게 사용\n","maxLength":20,"minLength":1},"hash":{"type":"string","description":"통신 암호 키\n{phone} 값이 설정된 경우: {bill_id} + \",\" + {phone} + \",\" + {price} 로 Hash 생성\n{phone} 값이 없는 경우: {bill_id} + \",\" + {price} 로 Hash 생성\nSHA-256으로 생성합니다\n","minLength":1},"price":{"type":"string","description":"결제 금액","minLength":1},"supplyPrice":{"type":"string","description":" 공급가액\n 보내지 않을 경우 사업장의 면,과세 정책을 따라갑니다.\n","minLength":1},"tax":{"type":"string","description":" 세액\n 보내지 않을 경우 사업장의 면,과세 정책을 따라갑니다.\n","minLength":1},"issuanceNumber":{"type":"string","description":"현금영수증 발행 요청 번호","minLength":1},"trader":{"type":"string","description":"현금영수증 발급 구분\n개인:0, 사업자:1\n","minLength":1}},"required":["billId","hash","issuanceNumber","price","supplyPrice","tax","trader"]},"BaseResponseCashReceiptIssueResponse":{"type":"object","description":"공통 API 응답 포맷 (api.spec: code/message/data)","properties":{"code":{"type":"string","description":"응답 코드"},"message":{"type":"string","description":"응답 메시지"},"data":{"$ref":"#/components/schemas/CashReceiptIssueResponse","description":"응답 데이터"}}},"CashReceiptIssueResponse":{"type":"object","description":"현금영수증 발행 응답","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키"},"member":{"type":"string","description":"파트너 매장 코드"},"merchant":{"type":"string","description":"파트너 사용자 코드"},"billId":{"type":"string","description":"청구서 ID"},"hash":{"type":"string","description":"요청 시 전달된 해시값"},"trader":{"type":"string","description":"현금영수증 발급 구분 (소득공제/지출증빙)"},"apprCashNum":{"type":"string","description":"현금영수증 승인번호"},"issuanceNumber":{"type":"string","description":"현금영수증 발급 요청 번호 (휴대폰/주민번호/사업자번호)"}}}}}} ``` ## 현금영수증 취소 > 발급된 현금영수증을 발급 취소합니다.
```json {"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/cash-receipt/cancel":{"post":{"tags":["현금영수증 ERP 연동 (발행/취소/조회)"],"summary":"현금영수증 취소","description":" 발급된 현금영수증을 발급 취소합니다.\n","operationId":"cashReceiptCancel","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CashReceiptCancelRequest"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponseCashReceiptCancelResponse"}}}}}}}},"components":{"schemas":{"CashReceiptCancelRequest":{"type":"object","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32,"minLength":1},"member":{"type":"string","description":"파트너 사용자 코드","maxLength":60,"minLength":1},"merchant":{"type":"string","description":"파트너 매장 코드","maxLength":60,"minLength":1},"cashReceipt":{"$ref":"#/components/schemas/CancelCashReceiptInfo"}},"required":["apiKey","member","merchant"]},"CancelCashReceiptInfo":{"type":"object","properties":{"billId":{"type":"string","description":" 청구서 ID\n 문자/숫자 20자리 (중복불가)\n -개발: 사업자번호 + 10자리 자유롭게 사용\n -운영: 20자리 자유롭게 사용\n","maxLength":20,"minLength":1},"hash":{"type":"string","description":"통신 암호 키\n{phone} 값이 설정된 경우 {bill_id} + \",\" + {phone} + \",\" + {price} 값으로 Hash 생성\n{phone} 값이 설정되어 있지 않은 경우 {bill_id} + \",\" + {price} 값으로 Hash 생성\nSHA-256으로 생성합니다\n","minLength":1},"price":{"type":"string","description":"결제 금액","minLength":1},"trader":{"type":"string","description":"현금영수증 발급 구분\n개인:0, 사업자:1\n","minLength":1}},"required":["billId","hash","price","trader"]},"BaseResponseCashReceiptCancelResponse":{"type":"object","description":"공통 API 응답 포맷 (api.spec: code/message/data)","properties":{"code":{"type":"string","description":"응답 코드"},"message":{"type":"string","description":"응답 메시지"},"data":{"$ref":"#/components/schemas/CashReceiptCancelResponse","description":"응답 데이터"}}},"CashReceiptCancelResponse":{"type":"object","description":"현금영수증 취소 응답","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키"},"member":{"type":"string","description":"파트너 매장 코드"},"merchant":{"type":"string","description":"파트너 사용자 코드"},"billId":{"type":"string","description":"청구서 ID"},"hash":{"type":"string","description":"요청 시 전달된 해시값"},"apprCashNum":{"type":"string","description":"현금영수증 취소 승인번호"}}}}}} ``` ## 현금영수증 단건 조회 > 발급된 현금영수증의 정보를 조회합니다.
```json {"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/cash-receipt/read":{"post":{"tags":["현금영수증 ERP 연동 (발행/취소/조회)"],"summary":"현금영수증 단건 조회","description":" 발급된 현금영수증의 정보를 조회합니다.\n","operationId":"cashReceiptRead","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CashReceiptReadRequest"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponseCashReceiptReadResponse"}}}}}}}},"components":{"schemas":{"CashReceiptReadRequest":{"type":"object","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32,"minLength":1},"member":{"type":"string","description":"파트너 사용자 코드","maxLength":60,"minLength":1},"merchant":{"type":"string","description":"파트너 매장 코드","maxLength":60,"minLength":1},"cashReceipt":{"$ref":"#/components/schemas/ReadCashReceiptInfo"}},"required":["apiKey","member","merchant"]},"ReadCashReceiptInfo":{"type":"object","properties":{"billId":{"type":"string","description":" 청구서 ID\n 문자/숫자 20자리 (중복불가)\n -개발: 사업자번호 + 10자리 자유롭게 사용\n -운영: 20자리 자유롭게 사용\n","maxLength":20,"minLength":1},"hash":{"type":"string","description":"통신 암호 키\n{phone} 값이 설정된 경우 {bill_id} + \",\" + {phone} + \",\" + {price} 값으로 Hash 생성\n{phone} 값이 설정되어 있지 않은 경우 {bill_id} + \",\" + {price} 값으로 Hash 생성\nSHA-256으로 생성합니다\n","minLength":1},"price":{"type":"string","description":"취소 금액","minLength":1}},"required":["billId","hash","price"]},"BaseResponseCashReceiptReadResponse":{"type":"object","description":"공통 API 응답 포맷 (api.spec: code/message/data)","properties":{"code":{"type":"string","description":"응답 코드"},"message":{"type":"string","description":"응답 메시지"},"data":{"$ref":"#/components/schemas/CashReceiptReadResponse","description":"응답 데이터"}}},"CashReceiptReadResponse":{"type":"object","description":"현금영수증 조회 응답","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키"},"member":{"type":"string","description":"파트너 매장 코드"},"merchant":{"type":"string","description":"파트너 사용자 코드"},"billId":{"type":"string","description":"청구서 ID (요청 값 echo)"},"info":{"type":"array","description":"현금영수증 이력 목록 (발행/취소 포함)","items":{"$ref":"#/components/schemas/Info"}}}},"Info":{"type":"object","description":"현금영수증 단건 이력","properties":{"billId":{"type":"string","description":"청구서 ID","maxLength":20},"apprPrice":{"type":"string","description":"승인 금액"},"apprSupplyPrice":{"type":"string","description":"공급가액"},"apprTax":{"type":"string","description":"세액"},"trader":{"type":"string","description":"발급 구분 (소득공제/지출증빙)"},"apprNum":{"type":"string","description":"승인번호"},"apprState":{"type":"string","description":"승인 상태 (F:승인, C:취소)"},"apprDt":{"type":"string","description":"승인 일시 (YYYYMMDDhhmmss)"},"issuanceNumber":{"type":"string","description":"발급 요청 번호 (휴대폰/주민번호/사업자번호)"}},"required":["billId"]}}}} ``` # 하위사업장 하위 사업장을 등록하고 조회합니다. ## 하위 사업장 등록 URL 발급 > 파트너사의 하위 사업장 등록을 위한 접근 URL을 발급합니다.\ > 발급된 URL을 파트너 내부 화면에 연결하여 하위 사업장 등록을 진행할 수 있습니다.\ > \
```json {"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/auth/mapping":{"post":{"tags":["3.1 파트너 하위 사업장 연동, v2"],"summary":"하위 사업장 등록 URL 발급","description":" 파트너사의 하위 사업장 등록을 위한 접근 URL을 발급합니다.\n 발급된 URL을 파트너 내부 화면에 연결하여 하위 사업장 등록을 진행할 수 있습니다.\n\n\n","operationId":"authMapping","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerAuthMappingRequest"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponsePartnerAuthOpenResponse"}}}}}}}},"components":{"schemas":{"PartnerAuthMappingRequest":{"type":"object","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32},"memberId":{"type":"string","description":"파트너 사용자 코드","maxLength":30},"merchantId":{"type":"string","description":"파트너 매장 코드","maxLength":30},"businessNumber":{"type":"string","description":"사업자번호"},"callbackUrl":{"type":"string","description":"결제 승인 후 결제 상태를 통보받을 파트너사의 URL"},"redirectUrl":{"type":"string","description":"하위사업장 가입 완료 이후 페이지 이동을 위한 redirectUrl"}},"required":["apiKey","callbackUrl","memberId","merchantId"]},"BaseResponsePartnerAuthOpenResponse":{"type":"object","description":"공통 API 응답 포맷 (api.spec: code/message/data)","properties":{"code":{"type":"string","description":"응답 코드"},"message":{"type":"string","description":"응답 메시지"},"data":{"$ref":"#/components/schemas/PartnerAuthOpenResponse","description":"응답 데이터"}}},"PartnerAuthOpenResponse":{"type":"object","description":"파트너 인증 URL 응답","properties":{"url":{"type":"string","description":"접근 URL"}}}}}} ``` ## 하위 사업장 매핑 목록 조회 > apiKey로 파트너의 하위 사업장 전체를 조회 합니다. ```json {"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[{"name":"4.1 파트너 기능 이전","description":"manager-if의 기능을 이전한다."}],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/read/mapping":{"post":{"tags":["4.1 파트너 기능 이전"],"summary":"하위 사업장 매핑 목록 조회","description":"apiKey로 파트너의 하위 사업장 전체를 조회 합니다.","operationId":"readMapping","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerReadRequest"}}},"required":true},"responses":{"200":{"description":"성공","content":{"*/*":{"schema":{"$ref":"#/components/schemas/BaseResponseListPartnerAuthMappingListOpenResponse"}}}}}}}},"components":{"schemas":{"PartnerReadRequest":{"type":"object","description":"쌤포인트 조회(관리 사업장) 요청","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32}},"required":["apiKey"]},"BaseResponseListPartnerAuthMappingListOpenResponse":{"type":"object","description":"공통 API 응답 포맷 (api.spec: code/message/data)","properties":{"code":{"type":"string","description":"응답 코드"},"message":{"type":"string","description":"응답 메시지"},"data":{"type":"array","description":"응답 데이터","items":{"$ref":"#/components/schemas/PartnerAuthMappingListOpenResponse"}}}},"PartnerAuthMappingListOpenResponse":{"type":"object","description":" V2 하위 사업장 매핑 단건 응답.\n /auth/mapping 으로 등록된 partner_auth 행 1건이 응답 1건에 매핑됩니다.\n 매핑 단계에 따라 사업장 정보 필드가 null 일 수 있습니다.\n","properties":{"partnerMember":{"type":"string","description":"파트너사가 자사 시스템에서 식별하는 회원 코드."},"partnerMerchant":{"type":"string","description":"파트너사가 자사 시스템에서 식별하는 매장 코드."},"companyNm":{"type":"string","description":"사업장 회사명. 게시 사업장(merchant) 이 있으면 해당 값, 없으면 임시 사업장(temporary_merchant) 값, 둘 다 없으면 null."},"branchNm":{"type":"string","description":"지점명. 게시 사업장 우선, 없으면 임시 사업장 값."},"businessNumber":{"type":"string","description":"사업자등록번호 (숫자 10자리, 하이픈 없음)."},"ceoName":{"type":"string","description":"대표자명. 게시 사업장(merchant) 의 ceo 값. 게시 사업장 미연결 단계에서는 null."},"email":{"type":"string","description":"회원 이메일. 연결된 user_info 의 member_email 값. 회원 미연결 단계에서는 null."},"mappingStatus":{"type":"string","description":"매핑 단계.\n- `LEGACY`: V2 이전 레거시 매핑\n- `INITIALIZED`: 매핑 생성 (회원/사업장 미연결)\n- `MEMBER_MAPPED`: 회원만 연결됨\n- `MERCHANT_OPENING`: 게시 대기\n- `COMPLETED`: 게시 사업장까지 연결 완료\n","enum":["LEGACY","INITIALIZED","MEMBER_MAPPED","MERCHANT_OPENING","COMPLETED"]},"regDt":{"type":"string","format":"date-time","description":"등록 일시 (ISO-8601 LocalDateTime)."},"updDt":{"type":"string","format":"date-time","description":"수정 일시 (ISO-8601 LocalDateTime)."}}}}}} ``` ## 하위 사업장 게시 상태 조회 > apiKey, memberId, merchantId 로 식별된 하위 사업장 매핑의 현재 단계와 사업장 심사 상태를 반환합니다. ```json {"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/auth/mapping/status":{"post":{"tags":["3.1 파트너 하위 사업장 연동, v2"],"summary":"하위 사업장 게시 상태 조회","description":"apiKey, memberId, merchantId 로 식별된 하위 사업장 매핑의 현재 단계와 사업장 심사 상태를 반환합니다.","operationId":"mappingStatus","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerAuthMappingStatusRequest"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponsePartnerAuthMappingStatusOpenResponse"}}}}}}}},"components":{"schemas":{"PartnerAuthMappingStatusRequest":{"type":"object","description":"하위 사업장 게시 상태 확인을 위한 요청 request","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32,"minLength":1},"member":{"type":"string","description":"파트너 사용자 코드","maxLength":60,"minLength":1},"merchant":{"type":"string","description":"파트너 매장 코드","maxLength":60,"minLength":1}},"required":["apiKey","member","merchant"]},"BaseResponsePartnerAuthMappingStatusOpenResponse":{"type":"object","description":"공통 API 응답 포맷 (api.spec: code/message/data)","properties":{"code":{"type":"string","description":"응답 코드"},"message":{"type":"string","description":"응답 메시지"},"data":{"$ref":"#/components/schemas/PartnerAuthMappingStatusOpenResponse","description":"응답 데이터"}}},"PartnerAuthMappingStatusOpenResponse":{"type":"object","description":"하위 사업장 등록 상태 응답. apiKey + member + merchant 로 식별된 매핑의 사업장 정보와 심사 상태를 반환합니다. 임시사업장이 아직 등록되지 않은 단계(INITIALIZED/MEMBER_MAPPED)에서는 사업장 관련 필드가 모두 null 입니다.","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키 (요청 시 전달한 apiKey 와 동일)"},"member":{"type":"string","description":"파트너사가 자사 시스템에서 식별하는 회원 코드. 요청 시 전달한 memberId 와 동일."},"merchant":{"type":"string","description":"파트너사가 자사 시스템에서 식별하는 매장 코드. 요청 시 전달한 merchantId 와 동일."},"companyNm":{"type":"string","description":"사업장 회사명 (사업자등록증상의 상호)."},"branchNm":{"type":"string","description":"지점명."},"businessNumber":{"type":"string","description":"사업자등록번호 (숫자 10자리, 하이픈 없음)."},"reviewStatus":{"type":"string","description":"심사 상태 코드입니다. 임시사업장 등록 이후의 심사 진행 상황을 나타냅니다.\n- `W`: 심사를 위한 매장 정보 작성 중\n- `P`: 심사 요청 완료, 페이민트 내부 심사 진행 중\n- `R`: 심사 반려\n- `S`: 심사 중 서류 보완이 필요한 상태 (추가 자료 제출 필요)\n- `O`: 심사 완료 및 정식 개시됨\n","enum":["W","P","R","S","O"]}}}}}} ``` ## POST /auth/merchant/mapping > 파트너 사업장 맵핑 ```json {"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/auth/merchant/mapping":{"post":{"tags":["3.1 파트너 하위 사업장 연동, v2"],"summary":"파트너 사업장 맵핑","operationId":"createMerchantMapping","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerAuthMerchantMapRequest"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponseVoid"}}}}}}}},"components":{"schemas":{"PartnerAuthMerchantMapRequest":{"type":"object","description":"파트너 사업장 맵핑 요청","properties":{"apiKey":{"type":"string","description":"API 키"},"memberId":{"type":"string","description":"memberId"},"merchantId":{"type":"string","description":"merchantId"},"memberIdx":{"type":"string","description":"memberIdx"},"temporaryMerchantCd":{"type":"string","description":"임시사업장코드"}}},"BaseResponseVoid":{"type":"object","description":"공통 API 응답 포맷 (api.spec: code/message/data)","properties":{"code":{"type":"string","description":"응답 코드"},"message":{"type":"string","description":"응답 메시지"},"data":{"description":"응답 데이터"}}}}}} ``` # 하위사업장 가입 및 등록 파트너의 하위사업장으로 결제선생의 사업장을 연결을 할 수 있습니다 ## 하위 사업장 등록 URL 발급 > 파트너사의 하위 사업장 등록을 위한 접근 URL을 발급합니다.\ > 발급된 URL을 파트너 내부 화면에 연결하여 하위 사업장 등록을 진행할 수 있습니다.\ > \
```json {"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/auth/mapping":{"post":{"tags":["3.1 파트너 하위 사업장 연동, v2"],"summary":"하위 사업장 등록 URL 발급","description":" 파트너사의 하위 사업장 등록을 위한 접근 URL을 발급합니다.\n 발급된 URL을 파트너 내부 화면에 연결하여 하위 사업장 등록을 진행할 수 있습니다.\n\n\n","operationId":"authMapping","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerAuthMappingRequest"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponsePartnerAuthOpenResponse"}}}}}}}},"components":{"schemas":{"PartnerAuthMappingRequest":{"type":"object","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32},"memberId":{"type":"string","description":"파트너 사용자 코드","maxLength":30},"merchantId":{"type":"string","description":"파트너 매장 코드","maxLength":30},"businessNumber":{"type":"string","description":"사업자번호"},"callbackUrl":{"type":"string","description":"결제 승인 후 결제 상태를 통보받을 파트너사의 URL"},"redirectUrl":{"type":"string","description":"하위사업장 가입 완료 이후 페이지 이동을 위한 redirectUrl"}},"required":["apiKey","callbackUrl","memberId","merchantId"]},"BaseResponsePartnerAuthOpenResponse":{"type":"object","description":"공통 API 응답 포맷 (api.spec: code/message/data)","properties":{"code":{"type":"string","description":"응답 코드"},"message":{"type":"string","description":"응답 메시지"},"data":{"$ref":"#/components/schemas/PartnerAuthOpenResponse","description":"응답 데이터"}}},"PartnerAuthOpenResponse":{"type":"object","description":"파트너 인증 URL 응답","properties":{"url":{"type":"string","description":"접근 URL"}}}}}} ``` # 하위 사업장 목록 조회 파트너와 연결된 하위사업장의 목록을 조회할 수 있습니다. ## 하위 사업장 조회 > 파트너의 하위 사업장 리스트를 조회합니다. ```json {"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[{"name":"4.1 파트너 기능 이전","description":"manager-if의 기능을 이전한다."}],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/read/merchant":{"post":{"tags":["4.1 파트너 기능 이전"],"summary":"하위 사업장 조회","description":"파트너의 하위 사업장 리스트를 조회합니다.","operationId":"readMerchant","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerReadRequest"}}},"required":true},"responses":{"200":{"description":"성공","content":{"*/*":{"schema":{"$ref":"#/components/schemas/BaseResponseListMerchantInfoResponse"}}}}}}}},"components":{"schemas":{"PartnerReadRequest":{"type":"object","description":"쌤포인트 조회(관리 사업장) 요청","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32}},"required":["apiKey"]},"BaseResponseListMerchantInfoResponse":{"type":"object","description":"공통 API 응답 포맷 (api.spec: code/message/data)","properties":{"code":{"type":"string","description":"응답 코드"},"message":{"type":"string","description":"응답 메시지"},"data":{"type":"array","description":"응답 데이터","items":{"$ref":"#/components/schemas/MerchantInfoResponse"}}}},"MerchantInfoResponse":{"type":"object","description":"가맹점 정보 data","properties":{"memberId":{"type":"string","description":"파트너 매장 코드","maxLength":30},"merchantId":{"type":"string","description":"파트너 사용자 코드","maxLength":30},"companyName":{"type":"string","description":"사업장명"},"branchName":{"type":"string","description":"지점명"},"ceoName":{"type":"string","description":"대표자 이름"},"email":{"type":"string","description":"관리 회원의 이메일"},"businessNumber":{"type":"string","description":"사업자등록번호"}},"required":["memberId","merchantId"]}}}} ``` ## 하위 사업장 매핑 목록 조회 > apiKey로 파트너의 하위 사업장 전체를 조회 합니다. ```json {"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[{"name":"4.1 파트너 기능 이전","description":"manager-if의 기능을 이전한다."}],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/read/mapping":{"post":{"tags":["4.1 파트너 기능 이전"],"summary":"하위 사업장 매핑 목록 조회","description":"apiKey로 파트너의 하위 사업장 전체를 조회 합니다.","operationId":"readMapping","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerReadRequest"}}},"required":true},"responses":{"200":{"description":"성공","content":{"*/*":{"schema":{"$ref":"#/components/schemas/BaseResponseListPartnerAuthMappingListOpenResponse"}}}}}}}},"components":{"schemas":{"PartnerReadRequest":{"type":"object","description":"쌤포인트 조회(관리 사업장) 요청","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32}},"required":["apiKey"]},"BaseResponseListPartnerAuthMappingListOpenResponse":{"type":"object","description":"공통 API 응답 포맷 (api.spec: code/message/data)","properties":{"code":{"type":"string","description":"응답 코드"},"message":{"type":"string","description":"응답 메시지"},"data":{"type":"array","description":"응답 데이터","items":{"$ref":"#/components/schemas/PartnerAuthMappingListOpenResponse"}}}},"PartnerAuthMappingListOpenResponse":{"type":"object","description":" V2 하위 사업장 매핑 단건 응답.\n /auth/mapping 으로 등록된 partner_auth 행 1건이 응답 1건에 매핑됩니다.\n 매핑 단계에 따라 사업장 정보 필드가 null 일 수 있습니다.\n","properties":{"partnerMember":{"type":"string","description":"파트너사가 자사 시스템에서 식별하는 회원 코드."},"partnerMerchant":{"type":"string","description":"파트너사가 자사 시스템에서 식별하는 매장 코드."},"companyNm":{"type":"string","description":"사업장 회사명. 게시 사업장(merchant) 이 있으면 해당 값, 없으면 임시 사업장(temporary_merchant) 값, 둘 다 없으면 null."},"branchNm":{"type":"string","description":"지점명. 게시 사업장 우선, 없으면 임시 사업장 값."},"businessNumber":{"type":"string","description":"사업자등록번호 (숫자 10자리, 하이픈 없음)."},"ceoName":{"type":"string","description":"대표자명. 게시 사업장(merchant) 의 ceo 값. 게시 사업장 미연결 단계에서는 null."},"email":{"type":"string","description":"회원 이메일. 연결된 user_info 의 member_email 값. 회원 미연결 단계에서는 null."},"mappingStatus":{"type":"string","description":"매핑 단계.\n- `LEGACY`: V2 이전 레거시 매핑\n- `INITIALIZED`: 매핑 생성 (회원/사업장 미연결)\n- `MEMBER_MAPPED`: 회원만 연결됨\n- `MERCHANT_OPENING`: 게시 대기\n- `COMPLETED`: 게시 사업장까지 연결 완료\n","enum":["LEGACY","INITIALIZED","MEMBER_MAPPED","MERCHANT_OPENING","COMPLETED"]},"regDt":{"type":"string","format":"date-time","description":"등록 일시 (ISO-8601 LocalDateTime)."},"updDt":{"type":"string","format":"date-time","description":"수정 일시 (ISO-8601 LocalDateTime)."}}}}}} ``` ## 하위 사업장 게시 상태 조회 > apiKey, memberId, merchantId 로 식별된 하위 사업장 매핑의 현재 단계와 사업장 심사 상태를 반환합니다. ```json {"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/auth/mapping/status":{"post":{"tags":["3.1 파트너 하위 사업장 연동, v2"],"summary":"하위 사업장 게시 상태 조회","description":"apiKey, memberId, merchantId 로 식별된 하위 사업장 매핑의 현재 단계와 사업장 심사 상태를 반환합니다.","operationId":"mappingStatus","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerAuthMappingStatusRequest"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponsePartnerAuthMappingStatusOpenResponse"}}}}}}}},"components":{"schemas":{"PartnerAuthMappingStatusRequest":{"type":"object","description":"하위 사업장 게시 상태 확인을 위한 요청 request","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32,"minLength":1},"member":{"type":"string","description":"파트너 사용자 코드","maxLength":60,"minLength":1},"merchant":{"type":"string","description":"파트너 매장 코드","maxLength":60,"minLength":1}},"required":["apiKey","member","merchant"]},"BaseResponsePartnerAuthMappingStatusOpenResponse":{"type":"object","description":"공통 API 응답 포맷 (api.spec: code/message/data)","properties":{"code":{"type":"string","description":"응답 코드"},"message":{"type":"string","description":"응답 메시지"},"data":{"$ref":"#/components/schemas/PartnerAuthMappingStatusOpenResponse","description":"응답 데이터"}}},"PartnerAuthMappingStatusOpenResponse":{"type":"object","description":"하위 사업장 등록 상태 응답. apiKey + member + merchant 로 식별된 매핑의 사업장 정보와 심사 상태를 반환합니다. 임시사업장이 아직 등록되지 않은 단계(INITIALIZED/MEMBER_MAPPED)에서는 사업장 관련 필드가 모두 null 입니다.","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키 (요청 시 전달한 apiKey 와 동일)"},"member":{"type":"string","description":"파트너사가 자사 시스템에서 식별하는 회원 코드. 요청 시 전달한 memberId 와 동일."},"merchant":{"type":"string","description":"파트너사가 자사 시스템에서 식별하는 매장 코드. 요청 시 전달한 merchantId 와 동일."},"companyNm":{"type":"string","description":"사업장 회사명 (사업자등록증상의 상호)."},"branchNm":{"type":"string","description":"지점명."},"businessNumber":{"type":"string","description":"사업자등록번호 (숫자 10자리, 하이픈 없음)."},"reviewStatus":{"type":"string","description":"심사 상태 코드입니다. 임시사업장 등록 이후의 심사 진행 상황을 나타냅니다.\n- `W`: 심사를 위한 매장 정보 작성 중\n- `P`: 심사 요청 완료, 페이민트 내부 심사 진행 중\n- `R`: 심사 반려\n- `S`: 심사 중 서류 보완이 필요한 상태 (추가 자료 제출 필요)\n- `O`: 심사 완료 및 정식 개시됨\n","enum":["W","P","R","S","O"]}}}}}} ``` # 쌤포인트 파트너 관리 사업장에 충전된 쌤포인트의 잔액을 조회 할 수 있습니다. ## 파트너 관리 사업장 쌤포인트 잔액 조회 > 파트너가 사용 가능한 쌤포인트 잔액을 조회합니다. ```json {"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[{"name":"4.1 파트너 기능 이전","description":"manager-if의 기능을 이전한다."}],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/read/remain_count":{"post":{"tags":["4.1 파트너 기능 이전"],"summary":"파트너 관리 사업장 쌤포인트 잔액 조회","description":"파트너가 사용 가능한 쌤포인트 잔액을 조회합니다.","operationId":"readRemainCount","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerReadRequest"}}},"required":true},"responses":{"200":{"description":"성공","content":{"*/*":{"schema":{"$ref":"#/components/schemas/BaseResponseRemainCountResponse"}}}}}}}},"components":{"schemas":{"PartnerReadRequest":{"type":"object","description":"쌤포인트 조회(관리 사업장) 요청","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32}},"required":["apiKey"]},"BaseResponseRemainCountResponse":{"type":"object","description":"공통 API 응답 포맷 (api.spec: code/message/data)","properties":{"code":{"type":"string","description":"응답 코드"},"message":{"type":"string","description":"응답 메시지"},"data":{"$ref":"#/components/schemas/RemainCountResponse","description":"응답 데이터"}}},"RemainCountResponse":{"type":"object","description":"쌤포인트 잔액","properties":{"balance":{"type":"integer","format":"int32","description":"잔여 포인트"},"chargeUrl":{"type":"string","description":"충전URL"}}}}}} ``` ## 하위 사업장 쌤포인트 잔액 조회 > 파트너가 사용 가능한 쌤포인트(하위 사업장 기준) 잔액을 조회합니다. ```json {"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[{"name":"4.1 파트너 기능 이전","description":"manager-if의 기능을 이전한다."}],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/read/merchant/remain_count":{"post":{"tags":["4.1 파트너 기능 이전"],"summary":"하위 사업장 쌤포인트 잔액 조회","description":"파트너가 사용 가능한 쌤포인트(하위 사업장 기준) 잔액을 조회합니다.","operationId":"readMerchantRemainCount","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerMerchantReadRequest"}}},"required":true},"responses":{"200":{"description":"성공","content":{"*/*":{"schema":{"$ref":"#/components/schemas/BaseResponseRemainCountResponse"}}}}}}}},"components":{"schemas":{"PartnerMerchantReadRequest":{"type":"object","description":"쌤포인트 조회(하위 사업장) 요청","properties":{"apiKey":{"type":"string","description":"파트너 연동을 위한 고유키","maxLength":32,"minLength":1},"member":{"type":"string","description":"파트너 사용자 코드","maxLength":30,"minLength":1},"merchant":{"type":"string","description":"파트너 매장 코드","maxLength":30,"minLength":1}},"required":["apiKey","member","merchant"]},"BaseResponseRemainCountResponse":{"type":"object","description":"공통 API 응답 포맷 (api.spec: code/message/data)","properties":{"code":{"type":"string","description":"응답 코드"},"message":{"type":"string","description":"응답 메시지"},"data":{"$ref":"#/components/schemas/RemainCountResponse","description":"응답 데이터"}}},"RemainCountResponse":{"type":"object","description":"쌤포인트 잔액","properties":{"balance":{"type":"integer","format":"int32","description":"잔여 포인트"},"chargeUrl":{"type":"string","description":"충전URL"}}}}}} ``` # 콜백 결제선생 -> 파트너에게 전달하는 콜백 입니다 ## 파트너 하위 사업장 연동 결과 동기화 콜백 > 파트너 하위 사업장 연동 과정에서 연동 상태 변경을 페이민트 -> 파트너사에게 전달합니다.\ > 파트너사는 아래 전문을 수신할 수 있는 엔드포인트를 구축해야 해야 합니다.\ > 구축하신 엔드포인트의 URL을 '하위 사업장 등록 URL 발급(/auth/mapping)'의 callbackUrl 파라미터로 입력하면,\ > 하위 사업장 연동 결과를 페이민트가 파트너사에 실시간으로 제공합니다.
```json {"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[{"name":"파트너 -> 승인동기화 콜백 예제","description":"파트너가 구현해야하는 엔드포인트"}],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/(승인 동기화 파트너사가 제공하는 callbackUrl)":{"post":{"tags":["파트너 -> 승인동기화 콜백 예제"],"summary":"파트너 하위 사업장 연동 결과 동기화 콜백","description":" 파트너 하위 사업장 연동 과정에서 연동 상태 변경을 페이민트 -> 파트너사에게 전달합니다.\n 파트너사는 아래 전문을 수신할 수 있는 엔드포인트를 구축해야 해야 합니다.\n 구축하신 엔드포인트의 URL을 '하위 사업장 등록 URL 발급(/auth/mapping)'의 callbackUrl 파라미터로 입력하면,\n 하위 사업장 연동 결과를 페이민트가 파트너사에 실시간으로 제공합니다.\n","operationId":"callbackAuthMapping","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerAuthCallbackPayload"}}},"required":true},"responses":{"200":{"description":"파트너 측 수신 성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerAuthCallbackResponse"}}}}}}}},"components":{"schemas":{"PartnerAuthCallbackPayload":{"type":"object","description":"파트너 인증 맵핑 결과 콜백 페이로드","properties":{"memberId":{"type":"string","description":"파트너 사용자 코드"},"merchantId":{"type":"string","description":"파트너 매장 코드"},"member":{"$ref":"#/components/schemas/PartnerAuthCallbackPayload_MemberInfo","description":"사용자 연동 정보"},"merchant":{"$ref":"#/components/schemas/PartnerAuthCallbackPayload_MerchantInfo","description":"매장 연동 정보"}}},"PartnerAuthCallbackPayload_MemberInfo":{"type":"object","description":"사용자 연동 정보","properties":{"id":{"type":"string","description":"페이민트 회원 ID"}}},"PartnerAuthCallbackPayload_MerchantInfo":{"type":"object","description":"매장 연동 정보","properties":{"companyName":{"type":"string","description":"사업장명"},"branchName":{"type":"string","description":"지점명"},"businessNumber":{"type":"string","description":"사업자등록번호"},"reviewStatus":{"type":"string","description":"심사 상태 (N: 심사없음, W: 작성중, P: 심사중, R: 반려, S: 서류보완, O: 개시)"},"reviewMessage":{"type":"string","description":"심사 메시지 (S: 서류보완 요청 메시지, R: 반려 사유, 그 외: null)"},"isDeleted":{"type":"string","description":"삭제 여부"}}},"PartnerAuthCallbackResponse":{"type":"object","description":"파트너 콜백 응답 포맷","properties":{"code":{"type":"string","description":"응답 코드. 0000으로 응답합니다."}},"required":["code"]}}}} ``` ## 결제 승인 동기화 콜백 > 결제 승인이 완료되면 페이민트 -> 파트너사에게 결과를 전달합니다.\ > 파트너사는 아래 전문을 수신할 수 있는 엔드포인트를 구축해야 합니다.\ > 구축하신 엔드포인트의 URL을 '청구서 생성(/bill)'의 callbackUrl 파라미터로 입력하면,\ > 결제 승인 결과를 페이민트가 파트너사에 실시간으로 제공합니다.
```json {"openapi":"3.1.0","info":{"title":"OpenAPI definition","version":"v0"},"tags":[{"name":"4.2 페이민트->파트너의 콜백 예제","description":"파트너가 구현해야하는 엔드포인트"}],"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/(결제 승인 시 파트너사가 제공한 callbackUrl)":{"post":{"tags":["4.2 페이민트->파트너의 콜백 예제"],"summary":"결제 승인 동기화 콜백","description":"결제 승인이 완료되면 페이민트 -> 파트너사에게 결과를 전달합니다.\n파트너사는 아래 전문을 수신할 수 있는 엔드포인트를 구축해야 합니다.\n구축하신 엔드포인트의 URL을 '청구서 생성(/bill)'의 callbackUrl 파라미터로 입력하면,\n결제 승인 결과를 페이민트가 파트너사에 실시간으로 제공합니다.\n","operationId":"callbackSyncApproval","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCallbackClient_SyncApprovalRequest"}}},"required":true},"responses":{"200":{"description":"파트너 측 수신 성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SyncApprovalCallbackResponse"}}}}}}}},"components":{"schemas":{"PartnerCallbackClient_SyncApprovalRequest":{"type":"object","description":"파트너에게 POST 되는 승인동기화 콜백 payload. camelCase 컨벤션.","properties":{"apiKey":{"type":"string","description":"파트너 연동용 API Key"},"billId":{"type":"string","description":"업체용 청구서 ID"},"apprPayType":{"type":"string","description":"결제수단 코드 (간편결제 0 등)"},"apprCardType":{"type":"string","description":"카드 종류 — CardBin 조회 결과. 조회 실패 시 '정보없음'"},"apprDt":{"type":"string","description":"승인 일시 (yyyyMMddHHmmss). 승인동기화에서는 apprOriginDt 와 동일 값"},"apprOriginDt":{"type":"string","description":"원거래 승인 일시 (yyyyMMddHHmmss)"},"apprPrice":{"type":"string","description":"승인 금액 (원 단위 문자열)"},"apprIssuer":{"type":"string","description":"카드명 또는 은행명. 헬스케어(hc-) 건에서 표준 코드 매핑 실패 시 null"},"apprIssuerCd":{"type":"string","description":"발행사 코드 또는 은행 코드. 헬스케어(hc-) 건에서 표준 코드 매핑 실패 시 null"},"apprIssuerNum":{"type":"string","description":"카드번호/계좌번호. 분당제생병원 KSNET+KAKAOPAY+MONEY 케이스에선 바코드번호(approval_otc)로 대체"},"apprAcquirerCd":{"type":"string","description":"매입사 코드. 영남대 KOCES 케이스에선 YoungNamAcquireCode 로 변환"},"apprAcquirerNm":{"type":"string","description":"매입사명"},"apprNum":{"type":"string","description":"승인/취소 거래번호. 승인동기화에서는 apprOriginNum 과 동일 값"},"apprOriginNum":{"type":"string","description":"원거래 승인번호"},"apprResCd":{"type":"string","description":"VAN 응답 코드"},"apprMonthly":{"type":"string","description":"할부 개월수 (0: 일시불)"},"apprState":{"type":"string","description":"승인 상태 (F:승인, W:대기, C:취소, D:파기). 승인동기화는 F 만 파트너에게 전달"},"apprCashNum":{"type":"string","description":"현금영수증 승인번호"},"apprCashTrader":{"type":"string","description":"현금영수증 발급 구분 (personal/corporate 등)"},"apprCashIssuanceNumber":{"type":"string","description":"현금영수증 발급 요청 번호"},"apprCardMerchantNum":{"type":"string","description":"신용카드 가맹점 정보 — 헬스케어(hc-) 전용"},"catId":{"type":"string","description":"단말기 번호 (CAT ID) — 헬스케어(hc-) 전용"},"udItem":{"$ref":"#/components/schemas/JsonNode","description":"사용자 정의 JSON 필드 (bill_user_define.item) — 헬스케어(hc-) 전용"},"dscTxNum":{"type":"string","description":"거래 고유번호 (approval_tx_id) — 헬스케어(hc-) 전용"},"cardType":{"type":"string","description":"페이민트 공통 카드 타입 — 영남대 KOCES 전용 (원장 card_type 컬럼 그대로 전달)"},"apprSign":{"type":"string","description":"전자서명 데이터 (Base64). 3000 byte 초과 시 JPEG 압축/리사이즈 — 헬스케어(hc-) 전용"}}},"JsonNode":{},"SyncApprovalCallbackResponse":{"type":"object","description":"파트너 콜백 응답 포맷","properties":{"code":{"type":"string","description":"응답 코드. 0000으로 응답합니다."}},"required":["code"]}}}} ``` # 에러 코드 v2 ### 기본 응답코드
codestatusmessage발생 조건
0000정상성공하였습니다.모든 V2 API 정상 응답
ERROR실패처리 중 오류가 발생하였습니다.알 수 없는 서버 오류 또는 미분류 예외
### 파트너 에러코드
codestatusmessage발생 조건
PARTNER_001실패V2 버전의 파트너 하위 사업장 연동이 불가능한 파트너입니다.apiKey가 V2 미지원 파트너로 식별된 경우
PARTNER_002실패apiKey 정보를 확인할 수 없습니다.요청에 apiKey가 누락되었거나 형식이 잘못된 경우
PARTNER_003실패정상적인 파트너가 아닙니다.apiKey로 파트너/매장/결제수단을 조회할 수 없는 경우
PARTNER_004실패찾을 수 없는 하위사업장 연동 정보입니다.merchantId 또는 매핑 시퀀스로 매장 인증 정보를 찾지 못한 경우
PARTNER_005실패존재하지 않는 파트너입니다.파트너 조회 실패
PARTNER_006실패적용중인 파트너 계약이 없습니다.파트너 계약(서비스) 상태가 비활성인 경우
PARTNER_007실패제공되지 않는 서비스입니다.파트너에게 해당 서비스(청구서 발송 발송 등) 권한이 없는 경우
### 파트너 맵핑 에러코드
codestatusmessage발생 조건
PARTNER_MAPPING_001실패apiKey, memberId, merchantId는 필수 값입니다.파트너 매핑 요청 시 필수 필드 누락
PARTNER_MAPPING_002실패잘못된 사업장등록번호 포맷입니다. 숫자 10자리를 입력하십시오.사업자등록번호가 10자리 숫자가 아닌 경우
PARTNER_MAPPING_003실패파트너 하위사업장 심사 정보를 확인할 수 없습니다.매장 심사(application) 정보 조회 실패
PARTNER_MAPPING_004실패삭제된 임시사업장을 연동할 수 없습니다.삭제된 임시사업장으로 매핑 시도
PARTNER_MAPPING_005실패해당 파트너사에서 이미 맵핑된 임시사업장입니다.동일 파트너에 중복 매핑 시도
PARTNER_MAPPING_006실패개시된 매장이 존재하지 않습니다.매핑 대상 매장 중 개시 상태인 매장을 찾을 수 없음
PARTNER_MAPPING_007실패처리 불가능한 회원입니다.회원 상태가 매핑/처리 불가 상태인 경우
### 값 검증 에러 코드
codestatusmessage발생조건
VALIDATION_001실패정상적이지 않은 데이터입니다. 연동규격서를 확인하시기 바랍니다.요청값 검증 실패(필드 누락/형식 불일치)
VALIDATION_002실패정상적이지 않은 데이터입니다. 해싱값을 확인하시기 바랍니다.hash 검증 실패
VALIDATION_004실패휴대폰 번호 형식이 올바르지 않습니다.01000000000 등 휴대폰 번호 형식이 올바르지 않을 때
### 결제 에러 코드
codestatusmessage발생조건
PAYMENT_001실패결제를 처리 할 수 없습니다VAN/현금영수증 발행 응답 누락·실패
PAYMENT_002실패결제 취소에 실패하였습니다.결제/현금영수증 취소 시 정산·VAN·은행 응답 실패
PAYMENT_003실패100원 이상 청구할 수 있습니다.청구 금액이 100원 미만
PAYMENT_004실패비정상적인 VAN 입니다.결제수단(payType) 조회 실패 또는 사용 불가
PAYMENT_005실패개발 환경에서는 20000원 이상의 금액만 청구할 수 있습니다.dev 환경에서 청구 금액이 20,000원 미만
### 청구서 에러 코드
codestatusmessage발생조건
BILL_001실패이미 사용된 billId 입니다.동일 billId 로 청구서 재생성 시도
BILL_002실패기 취소된 청구서 입니다.직접 취소 요청 시 취소 가능 상태 아님
BILL_003실패청구서를 찾을 수 없습니다.billId/ledger/현금영수증 단건 조회 실패
BILL_004실패결제카드를 조회할 수 없습니다.Keyin 카드 정보 복호화 실패
BILL_005실패요청한 txId로 청구서를 찾을 수 없습니다.결과 콜백 또는 ledger 조회에서 txId 매칭 실패
BILL_006실패청구서 발송이 가능한 상태가 아닙니다.재발송 시 청구서 상태가 발송 불가
BILL_007실패billId는 20자 이하여야 합니다.요청 billId 길이 초과
BILL_008실패sendType은 필수값입니다. (TALK 또는 URL)v2 청구서 생성시 타입 누락
BILL_009실패BILL_TALK 서비스를 사용할 수 없습니다.파트너 계약시 TALK 타입 계약 되지 않음
BILL_010실패BILL_URL 서비스를 사용할 수 없습니다.파트너 계약시 URL 타입 계약 되지 않음
### 포인트 에러 코드
codestatusmessage발생조건
POINT_001실패포인트가 부족합니다청구서 발송 시 쌤포인트 잔액 부족
### 점검중 에러 코드
codestatusmessage발생조건
MAINTAINED_METHOD실패점검 중입니다.야간작업, 장애 처리 등 점검 필요시
*** ## :circle-info: :messages-question: 더 궁금한 내용이 있나요? [자주하는 질문](https://developers.payssam.kr/faq/) :message-code: 기술지원이 필요하신가요? [이메일 보내기](mailto:partner_dev@paymint.co.kr) # 테스트 # 청구서 청구서를 발송하고 관리하는 API를 안내합니다. ## 청구서 발송 > 결제 금액을 결제 고객에게 청구하기 위하여 청구서를 생성하고 결제 고객에게 알림톡으로 청구서를 전송합니다. ```json {"openapi":"3.0.1","info":{"title":"My Project API","version":"1.0.0"},"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/if/bill/send":{"post":{"tags":["erp-partner-controller"],"summary":"청구서 발송","description":"결제 금액을 결제 고객에게 청구하기 위하여 청구서를 생성하고 결제 고객에게 알림톡으로 청구서를 전송합니다.","operationId":"makeURL_n_TALK","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReqSendBill"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendBill"}}}}}}}},"components":{"schemas":{"ReqSendBill":{"required":["apikey","member","merchant"],"type":"object","properties":{"apikey":{"maxLength":32,"type":"string","description":"파트너 연동을 위한 고유키"},"merchant":{"maxLength":30,"type":"string","description":"파트너 매장 코드"},"member":{"maxLength":30,"type":"string","description":"파트너 사용자 코드"},"bill":{"$ref":"#/components/schemas/Bill"}}},"Bill":{"required":["bill_id","callbackURL","hash","member_nm","phone","price","product_nm"],"type":"object","properties":{"bill_id":{"maxLength":20,"type":"string","description":"청구서 ID \n문자/숫자 20자리 (중복불가) \n -개발: 사업자번호 + 10자리 자유롭게 사용 \n -운영: 20자리 자유롭게 사용"},"bill_issuer":{"maxLength":50,"type":"string","description":"청구서 발급처명 \n청구서가 발급될 때 노출되는 발급처명을 직접 입력한 값으로 노출하기 위해 사용 \n -파라미터 전달시 : 세팅한 값이 발급처명으로 노출 \n -파라미터 미전달시 : 사업장명이 발급처명으로 노출"},"hash":{"type":"string","description":"통신 암호 키 \n{phone} 값이 설정된 경우 {bill_id} + \",\" + {phone} + \",\" + {price} 값으로 Hash 생성 \n{phone} 값이 설정되어 있지 않은 경우 {bill_id} + \",\" + {price} 값으로 Hash 생성"},"product_nm":{"type":"string","description":"청구 사유"},"message":{"type":"string","description":"안내메세지"},"member_nm":{"type":"string","description":"고객명"},"phone":{"type":"string","description":"고객 전화번호"},"price":{"type":"string","description":"결제 금액"},"expire_dt":{"type":"string","description":"유효기간 \nYYYY-MM-DD \n청구서 생성일 자정까지 입력 가능"},"callbackURL":{"type":"string","description":"결제 승인 후 결제 상태를 통보받을 파트너사의 URL"}},"description":"청구서 정보"},"SendBill":{"type":"object","properties":{"code":{"type":"string","description":"응답 코드"},"msg":{"type":"string","description":"응답 메세지"},"apikey":{"maxLength":32,"type":"string","description":"파트너 연동을 위한 고유키"},"member":{"maxLength":30,"type":"string","description":"파트너 매장 코드"},"merchant":{"maxLength":30,"type":"string","description":"파트너 사용자 코드"},"bill_id":{"maxLength":20,"type":"string","description":"청구서 ID \n문자/숫자 20자리 (중복불가) \n -개발: 사업자번호 + 10자리 자유롭게 사용 \n -운영: 20자리 자유롭게 사용"},"hash":{"type":"string","description":"통신 암호 키 \n{phone} 값이 설정된 경우 {bill_id} + \",\" + {phone} + \",\" + {price} 값으로 Hash 생성 \n{phone} 값이 설정되어 있지 않은 경우 {bill_id} + \",\" + {price} 값으로 Hash 생성"}}}}}} ``` ## 청구서 재발송 > 기발송된 청구서를 재발송합니다. \ > 청구 내용은 동일하며 알림톡이 새로 발송되므로 쌤포인트는 차감됩니다. ```json {"openapi":"3.0.1","info":{"title":"My Project API","version":"1.0.0"},"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/if/bill/resend":{"post":{"tags":["erp-partner-controller"],"summary":"청구서 재발송","description":"기발송된 청구서를 재발송합니다. \n청구 내용은 동일하며 알림톡이 새로 발송되므로 쌤포인트는 차감됩니다.","operationId":"resend_TALK","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillReq"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Base"}}}}}}}},"components":{"schemas":{"BillReq":{"required":["apikey","bill_id","member","merchant"],"type":"object","properties":{"apikey":{"maxLength":32,"type":"string","description":"파트너 연동을 위한 고유키"},"merchant":{"maxLength":30,"type":"string","description":"파트너 매장 코드"},"member":{"maxLength":30,"type":"string","description":"파트너 사용자 코드"},"bill_id":{"type":"string","description":"청구서 ID \n문자/숫자 20자리 (중복불가) \n -개발: 사업자번호 + 10자리 자유롭게 사용 \n -운영: 20자리 자유롭게 사용"}}},"Base":{"type":"object","properties":{"code":{"type":"string","description":"응답 코드"},"msg":{"type":"string","description":"응답 메세지"}}}}}} ``` ## 결제 상태 조회 > 발송된 청구서에 대한 결제 상태를 조회합니다. ```json {"openapi":"3.0.1","info":{"title":"My Project API","version":"1.0.0"},"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/if/bill/read":{"post":{"tags":["erp-partner-controller"],"summary":"결제 상태 조회","description":"발송된 청구서에 대한 결제 상태를 조회합니다.","operationId":"readBill","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillReq"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Approval"}}}}}}}},"components":{"schemas":{"BillReq":{"required":["apikey","bill_id","member","merchant"],"type":"object","properties":{"apikey":{"maxLength":32,"type":"string","description":"파트너 연동을 위한 고유키"},"merchant":{"maxLength":30,"type":"string","description":"파트너 매장 코드"},"member":{"maxLength":30,"type":"string","description":"파트너 사용자 코드"},"bill_id":{"type":"string","description":"청구서 ID \n문자/숫자 20자리 (중복불가) \n -개발: 사업자번호 + 10자리 자유롭게 사용 \n -운영: 20자리 자유롭게 사용"}}},"Approval":{"type":"object","properties":{"apikey":{"maxLength":32,"type":"string","description":"파트너 연동을 위한 고유키"},"bill_id":{"maxLength":20,"type":"string","description":"청구서 ID \n문자/숫자 20자리 (중복불가) \n -개발: 사업자번호 + 10자리 자유롭게 사용 \n -운영: 20자리 자유롭게 사용"},"appr_cat_id":{"type":"string","description":"단말기번호"},"appr_pay_type":{"type":"string","description":"결제수단코드"},"appr_card_type":{"type":"string","description":"결제 카드 종류 (신용, 체크, ...)"},"appr_dt":{"type":"string","description":"승인일시"},"appr_origin_dt":{"type":"string","description":"원거래 승인일시"},"appr_price":{"type":"string","description":"승인금액"},"appr_issuer":{"type":"string","description":"결제은행 / 카드명"},"appr_issuer_cd":{"type":"string","description":"발행카드코드/은행코드"},"appr_issuer_num":{"type":"string","description":"결제카드 / 계좌번호"},"appr_acquirer_cd":{"type":"string","description":"매입사코드"},"appr_acquirer_nm":{"type":"string","description":"매입사명"},"appr_num":{"type":"string","description":"응답코드"},"appr_origin_num":{"type":"string","description":"원거래승인번호"},"appr_res_cd":{"type":"string","description":"응답코드"},"appr_monthly":{"type":"string","description":"결제시 할부개월수"},"appr_state":{"type":"string","description":"결제 상태 \nF:결제완료, W:미결제, C:취소, D:파기"},"appr_cash_num":{"type":"string","description":"현금영수증 발급 승인번호"},"appr_cash_trader":{"type":"string","description":"현금영수증 발급 구분 \n개인:0, 사업자:1"},"appr_cash_issuance_number":{"type":"string","description":"현금영수증 발급 요청 번호 \n -현금영수증 발급 시 사용\n\n -자진발급시 \"0100001234\""}}}}}} ``` ## 청구서 파기 > 결제를 진행할 수 없도록 발송된 청구서를 파기합니다. \ > 결제가 승인되기 전에만 파기가 가능하며, 결제가 승인된 후에는 파기할 수 없습니다. ```json {"openapi":"3.0.1","info":{"title":"My Project API","version":"1.0.0"},"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/if/bill/destroy":{"post":{"tags":["erp-partner-controller"],"summary":"청구서 파기","description":"결제를 진행할 수 없도록 발송된 청구서를 파기합니다. \n결제가 승인되기 전에만 파기가 가능하며, 결제가 승인된 후에는 파기할 수 없습니다.","operationId":"billDestroy","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReqDestroyBill"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DestroyBill"}}}}}}}},"components":{"schemas":{"ReqDestroyBill":{"required":["apikey","bill_id","hash","member","merchant","price"],"type":"object","properties":{"apikey":{"maxLength":32,"type":"string","description":"파트너 연동을 위한 고유키"},"merchant":{"maxLength":30,"type":"string","description":"파트너 매장 코드"},"member":{"maxLength":30,"type":"string","description":"파트너 사용자 코드"},"bill_id":{"type":"string","description":"청구서 ID \n문자/숫자 20자리 (중복불가) \n -개발: 사업자번호 + 10자리 자유롭게 사용 \n -운영: 20자리 자유롭게 사용"},"hash":{"type":"string","description":"통신 암호 키 \n{phone} 값이 설정된 경우 {bill_id} + \",\" + {phone} + \",\" + {price} 값으로 Hash 생성 \n{phone} 값이 설정되어 있지 않은 경우 {bill_id} + \",\" + {price} 값으로 Hash 생성"},"price":{"type":"string","description":"결제 금액"}}},"DestroyBill":{"type":"object","properties":{"code":{"type":"string","description":"응답 코드"},"msg":{"type":"string","description":"응답 메세지"},"apikey":{"maxLength":32,"type":"string","description":"파트너 연동을 위한 고유키"},"member":{"maxLength":30,"type":"string","description":"파트너 매장 코드"},"merchant":{"maxLength":30,"type":"string","description":"파트너 사용자 코드"},"bill_id":{"maxLength":20,"type":"string","description":"청구서 ID \n문자/숫자 20자리 (중복불가) \n -개발: 사업자번호 + 10자리 자유롭게 사용 \n -운영: 20자리 자유롭게 사용"},"hash":{"type":"string","description":"통신 암호 키 \n{phone} 값이 설정된 경우 {bill_id} + \",\" + {phone} + \",\" + {price} 값으로 Hash 생성 \n{phone} 값이 설정되어 있지 않은 경우 {bill_id} + \",\" + {price} 값으로 Hash 생성"}}}}}} ``` ## 결제 취소 > 결제가 완료된 청구서의 결제 상태를 승인 -> 승인취소 처리 합니다. ```json {"openapi":"3.0.1","info":{"title":"My Project API","version":"1.0.0"},"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/if/bill/cancel":{"post":{"tags":["erp-partner-controller"],"summary":"결제 취소","description":"결제가 완료된 청구서의 결제 상태를 승인 -> 승인취소 처리 합니다.","operationId":"billCancel","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReqCancelBill"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelBill"}}}}}}}},"components":{"schemas":{"ReqCancelBill":{"required":["apikey","bill_id","hash","member","merchant","price"],"type":"object","properties":{"apikey":{"maxLength":32,"type":"string","description":"파트너 연동을 위한 고유키"},"merchant":{"maxLength":30,"type":"string","description":"파트너 매장 코드"},"member":{"maxLength":30,"type":"string","description":"파트너 사용자 코드"},"bill_id":{"type":"string","description":"청구서 ID \n문자/숫자 20자리 (중복불가) \n -개발: 사업자번호 + 10자리 자유롭게 사용 \n -운영: 20자리 자유롭게 사용"},"hash":{"type":"string","description":"통신 암호 키 \n{phone} 값이 설정된 경우 {bill_id} + \",\" + {phone} + \",\" + {price} 값으로 Hash 생성 \n{phone} 값이 설정되어 있지 않은 경우 {bill_id} + \",\" + {price} 값으로 Hash 생성"},"price":{"type":"string","description":"결제 금액"}}},"CancelBill":{"type":"object","properties":{"code":{"type":"string","description":"응답 코드"},"msg":{"type":"string","description":"응답 메세지"},"apikey":{"maxLength":32,"type":"string","description":"파트너 연동을 위한 고유키"},"member":{"maxLength":30,"type":"string","description":"파트너 매장 코드"},"merchant":{"maxLength":30,"type":"string","description":"파트너 사용자 코드"},"bill_id":{"maxLength":20,"type":"string","description":"청구서 ID \n문자/숫자 20자리 (중복불가) \n -개발: 사업자번호 + 10자리 자유롭게 사용 \n -운영: 20자리 자유롭게 사용"},"hash":{"type":"string","description":"통신 암호 키 \n{phone} 값이 설정된 경우 {bill_id} + \",\" + {phone} + \",\" + {price} 값으로 Hash 생성 \n{phone} 값이 설정되어 있지 않은 경우 {bill_id} + \",\" + {price} 값으로 Hash 생성"},"appr_num":{"type":"string","description":"취소 승인 번호"},"appr_origin_num":{"type":"string","description":"원거래 승인 번호"},"appr_cancel_dt":{"type":"string","description":"취소 일시"}}}}}} ``` # 청구서 발송 및 파기 ## 청구서 발송 > 결제 금액을 결제 고객에게 청구하기 위하여 청구서를 생성하고 결제 고객에게 알림톡으로 청구서를 전송합니다. ```json {"openapi":"3.0.1","info":{"title":"My Project API","version":"1.0.0"},"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/if/bill/send":{"post":{"tags":["erp-partner-controller"],"summary":"청구서 발송","description":"결제 금액을 결제 고객에게 청구하기 위하여 청구서를 생성하고 결제 고객에게 알림톡으로 청구서를 전송합니다.","operationId":"makeURL_n_TALK","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReqSendBill"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendBill"}}}}}}}},"components":{"schemas":{"ReqSendBill":{"required":["apikey","member","merchant"],"type":"object","properties":{"apikey":{"maxLength":32,"type":"string","description":"파트너 연동을 위한 고유키"},"merchant":{"maxLength":30,"type":"string","description":"파트너 매장 코드"},"member":{"maxLength":30,"type":"string","description":"파트너 사용자 코드"},"bill":{"$ref":"#/components/schemas/Bill"}}},"Bill":{"required":["bill_id","callbackURL","hash","member_nm","phone","price","product_nm"],"type":"object","properties":{"bill_id":{"maxLength":20,"type":"string","description":"청구서 ID \n문자/숫자 20자리 (중복불가) \n -개발: 사업자번호 + 10자리 자유롭게 사용 \n -운영: 20자리 자유롭게 사용"},"bill_issuer":{"maxLength":50,"type":"string","description":"청구서 발급처명 \n청구서가 발급될 때 노출되는 발급처명을 직접 입력한 값으로 노출하기 위해 사용 \n -파라미터 전달시 : 세팅한 값이 발급처명으로 노출 \n -파라미터 미전달시 : 사업장명이 발급처명으로 노출"},"hash":{"type":"string","description":"통신 암호 키 \n{phone} 값이 설정된 경우 {bill_id} + \",\" + {phone} + \",\" + {price} 값으로 Hash 생성 \n{phone} 값이 설정되어 있지 않은 경우 {bill_id} + \",\" + {price} 값으로 Hash 생성"},"product_nm":{"type":"string","description":"청구 사유"},"message":{"type":"string","description":"안내메세지"},"member_nm":{"type":"string","description":"고객명"},"phone":{"type":"string","description":"고객 전화번호"},"price":{"type":"string","description":"결제 금액"},"expire_dt":{"type":"string","description":"유효기간 \nYYYY-MM-DD \n청구서 생성일 자정까지 입력 가능"},"callbackURL":{"type":"string","description":"결제 승인 후 결제 상태를 통보받을 파트너사의 URL"}},"description":"청구서 정보"},"SendBill":{"type":"object","properties":{"code":{"type":"string","description":"응답 코드"},"msg":{"type":"string","description":"응답 메세지"},"apikey":{"maxLength":32,"type":"string","description":"파트너 연동을 위한 고유키"},"member":{"maxLength":30,"type":"string","description":"파트너 매장 코드"},"merchant":{"maxLength":30,"type":"string","description":"파트너 사용자 코드"},"bill_id":{"maxLength":20,"type":"string","description":"청구서 ID \n문자/숫자 20자리 (중복불가) \n -개발: 사업자번호 + 10자리 자유롭게 사용 \n -운영: 20자리 자유롭게 사용"},"hash":{"type":"string","description":"통신 암호 키 \n{phone} 값이 설정된 경우 {bill_id} + \",\" + {phone} + \",\" + {price} 값으로 Hash 생성 \n{phone} 값이 설정되어 있지 않은 경우 {bill_id} + \",\" + {price} 값으로 Hash 생성"}}}}}} ``` ## 청구서 파기 > 결제를 진행할 수 없도록 발송된 청구서를 파기합니다. \ > 결제가 승인되기 전에만 파기가 가능하며, 결제가 승인된 후에는 파기할 수 없습니다. ```json {"openapi":"3.0.1","info":{"title":"My Project API","version":"1.0.0"},"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/if/bill/destroy":{"post":{"tags":["erp-partner-controller"],"summary":"청구서 파기","description":"결제를 진행할 수 없도록 발송된 청구서를 파기합니다. \n결제가 승인되기 전에만 파기가 가능하며, 결제가 승인된 후에는 파기할 수 없습니다.","operationId":"billDestroy","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReqDestroyBill"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DestroyBill"}}}}}}}},"components":{"schemas":{"ReqDestroyBill":{"required":["apikey","bill_id","hash","member","merchant","price"],"type":"object","properties":{"apikey":{"maxLength":32,"type":"string","description":"파트너 연동을 위한 고유키"},"merchant":{"maxLength":30,"type":"string","description":"파트너 매장 코드"},"member":{"maxLength":30,"type":"string","description":"파트너 사용자 코드"},"bill_id":{"type":"string","description":"청구서 ID \n문자/숫자 20자리 (중복불가) \n -개발: 사업자번호 + 10자리 자유롭게 사용 \n -운영: 20자리 자유롭게 사용"},"hash":{"type":"string","description":"통신 암호 키 \n{phone} 값이 설정된 경우 {bill_id} + \",\" + {phone} + \",\" + {price} 값으로 Hash 생성 \n{phone} 값이 설정되어 있지 않은 경우 {bill_id} + \",\" + {price} 값으로 Hash 생성"},"price":{"type":"string","description":"결제 금액"}}},"DestroyBill":{"type":"object","properties":{"code":{"type":"string","description":"응답 코드"},"msg":{"type":"string","description":"응답 메세지"},"apikey":{"maxLength":32,"type":"string","description":"파트너 연동을 위한 고유키"},"member":{"maxLength":30,"type":"string","description":"파트너 매장 코드"},"merchant":{"maxLength":30,"type":"string","description":"파트너 사용자 코드"},"bill_id":{"maxLength":20,"type":"string","description":"청구서 ID \n문자/숫자 20자리 (중복불가) \n -개발: 사업자번호 + 10자리 자유롭게 사용 \n -운영: 20자리 자유롭게 사용"},"hash":{"type":"string","description":"통신 암호 키 \n{phone} 값이 설정된 경우 {bill_id} + \",\" + {phone} + \",\" + {price} 값으로 Hash 생성 \n{phone} 값이 설정되어 있지 않은 경우 {bill_id} + \",\" + {price} 값으로 Hash 생성"}}}}}} ``` ## 청구서 재발송 > 기발송된 청구서를 재발송합니다. \ > 청구 내용은 동일하며 알림톡이 새로 발송되므로 쌤포인트는 차감됩니다. ```json {"openapi":"3.0.1","info":{"title":"My Project API","version":"1.0.0"},"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/if/bill/resend":{"post":{"tags":["erp-partner-controller"],"summary":"청구서 재발송","description":"기발송된 청구서를 재발송합니다. \n청구 내용은 동일하며 알림톡이 새로 발송되므로 쌤포인트는 차감됩니다.","operationId":"resend_TALK","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillReq"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Base"}}}}}}}},"components":{"schemas":{"BillReq":{"required":["apikey","bill_id","member","merchant"],"type":"object","properties":{"apikey":{"maxLength":32,"type":"string","description":"파트너 연동을 위한 고유키"},"merchant":{"maxLength":30,"type":"string","description":"파트너 매장 코드"},"member":{"maxLength":30,"type":"string","description":"파트너 사용자 코드"},"bill_id":{"type":"string","description":"청구서 ID \n문자/숫자 20자리 (중복불가) \n -개발: 사업자번호 + 10자리 자유롭게 사용 \n -운영: 20자리 자유롭게 사용"}}},"Base":{"type":"object","properties":{"code":{"type":"string","description":"응답 코드"},"msg":{"type":"string","description":"응답 메세지"}}}}}} ``` # 수납 및 결제취소 ## 결제 취소 > 결제가 완료된 청구서의 결제 상태를 승인 -> 승인취소 처리 합니다. ```json {"openapi":"3.0.1","info":{"title":"My Project API","version":"1.0.0"},"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/if/bill/cancel":{"post":{"tags":["erp-partner-controller"],"summary":"결제 취소","description":"결제가 완료된 청구서의 결제 상태를 승인 -> 승인취소 처리 합니다.","operationId":"billCancel","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReqCancelBill"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelBill"}}}}}}}},"components":{"schemas":{"ReqCancelBill":{"required":["apikey","bill_id","hash","member","merchant","price"],"type":"object","properties":{"apikey":{"maxLength":32,"type":"string","description":"파트너 연동을 위한 고유키"},"merchant":{"maxLength":30,"type":"string","description":"파트너 매장 코드"},"member":{"maxLength":30,"type":"string","description":"파트너 사용자 코드"},"bill_id":{"type":"string","description":"청구서 ID \n문자/숫자 20자리 (중복불가) \n -개발: 사업자번호 + 10자리 자유롭게 사용 \n -운영: 20자리 자유롭게 사용"},"hash":{"type":"string","description":"통신 암호 키 \n{phone} 값이 설정된 경우 {bill_id} + \",\" + {phone} + \",\" + {price} 값으로 Hash 생성 \n{phone} 값이 설정되어 있지 않은 경우 {bill_id} + \",\" + {price} 값으로 Hash 생성"},"price":{"type":"string","description":"결제 금액"}}},"CancelBill":{"type":"object","properties":{"code":{"type":"string","description":"응답 코드"},"msg":{"type":"string","description":"응답 메세지"},"apikey":{"maxLength":32,"type":"string","description":"파트너 연동을 위한 고유키"},"member":{"maxLength":30,"type":"string","description":"파트너 매장 코드"},"merchant":{"maxLength":30,"type":"string","description":"파트너 사용자 코드"},"bill_id":{"maxLength":20,"type":"string","description":"청구서 ID \n문자/숫자 20자리 (중복불가) \n -개발: 사업자번호 + 10자리 자유롭게 사용 \n -운영: 20자리 자유롭게 사용"},"hash":{"type":"string","description":"통신 암호 키 \n{phone} 값이 설정된 경우 {bill_id} + \",\" + {phone} + \",\" + {price} 값으로 Hash 생성 \n{phone} 값이 설정되어 있지 않은 경우 {bill_id} + \",\" + {price} 값으로 Hash 생성"},"appr_num":{"type":"string","description":"취소 승인 번호"},"appr_origin_num":{"type":"string","description":"원거래 승인 번호"},"appr_cancel_dt":{"type":"string","description":"취소 일시"}}}}}} ``` ## 결제 상태 조회 > 발송된 청구서에 대한 결제 상태를 조회합니다. ```json {"openapi":"3.0.1","info":{"title":"My Project API","version":"1.0.0"},"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/if/bill/read":{"post":{"tags":["erp-partner-controller"],"summary":"결제 상태 조회","description":"발송된 청구서에 대한 결제 상태를 조회합니다.","operationId":"readBill","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillReq"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Approval"}}}}}}}},"components":{"schemas":{"BillReq":{"required":["apikey","bill_id","member","merchant"],"type":"object","properties":{"apikey":{"maxLength":32,"type":"string","description":"파트너 연동을 위한 고유키"},"merchant":{"maxLength":30,"type":"string","description":"파트너 매장 코드"},"member":{"maxLength":30,"type":"string","description":"파트너 사용자 코드"},"bill_id":{"type":"string","description":"청구서 ID \n문자/숫자 20자리 (중복불가) \n -개발: 사업자번호 + 10자리 자유롭게 사용 \n -운영: 20자리 자유롭게 사용"}}},"Approval":{"type":"object","properties":{"apikey":{"maxLength":32,"type":"string","description":"파트너 연동을 위한 고유키"},"bill_id":{"maxLength":20,"type":"string","description":"청구서 ID \n문자/숫자 20자리 (중복불가) \n -개발: 사업자번호 + 10자리 자유롭게 사용 \n -운영: 20자리 자유롭게 사용"},"appr_cat_id":{"type":"string","description":"단말기번호"},"appr_pay_type":{"type":"string","description":"결제수단코드"},"appr_card_type":{"type":"string","description":"결제 카드 종류 (신용, 체크, ...)"},"appr_dt":{"type":"string","description":"승인일시"},"appr_origin_dt":{"type":"string","description":"원거래 승인일시"},"appr_price":{"type":"string","description":"승인금액"},"appr_issuer":{"type":"string","description":"결제은행 / 카드명"},"appr_issuer_cd":{"type":"string","description":"발행카드코드/은행코드"},"appr_issuer_num":{"type":"string","description":"결제카드 / 계좌번호"},"appr_acquirer_cd":{"type":"string","description":"매입사코드"},"appr_acquirer_nm":{"type":"string","description":"매입사명"},"appr_num":{"type":"string","description":"응답코드"},"appr_origin_num":{"type":"string","description":"원거래승인번호"},"appr_res_cd":{"type":"string","description":"응답코드"},"appr_monthly":{"type":"string","description":"결제시 할부개월수"},"appr_state":{"type":"string","description":"결제 상태 \nF:결제완료, W:미결제, C:취소, D:파기"},"appr_cash_num":{"type":"string","description":"현금영수증 발급 승인번호"},"appr_cash_trader":{"type":"string","description":"현금영수증 발급 구분 \n개인:0, 사업자:1"},"appr_cash_issuance_number":{"type":"string","description":"현금영수증 발급 요청 번호 \n -현금영수증 발급 시 사용\n\n -자진발급시 \"0100001234\""}}}}}} ``` # 현금영수증 ## 현금영수증 발급 > 현금영수증을 발급합니다. ```json {"openapi":"3.0.1","info":{"title":"My Project API","version":"1.0.0"},"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/if/cash-receipt/issue":{"post":{"tags":["erp-cash-receipt-controller"],"summary":"현금영수증 발급","description":"현금영수증을 발급합니다.","operationId":"issue","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReqIssueCashReceipt"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssueCashReceipt"}}}}}}}},"components":{"schemas":{"ReqIssueCashReceipt":{"required":["apikey","member","merchant"],"type":"object","properties":{"apikey":{"maxLength":32,"type":"string","description":"파트너 연동을 위한 고유키"},"merchant":{"maxLength":30,"type":"string","description":"파트너 매장 코드"},"member":{"maxLength":30,"type":"string","description":"파트너 사용자 코드"},"bill":{"$ref":"#/components/schemas/ReqCashReceipt"}}},"ReqCashReceipt":{"required":["bill_id","hash","issuance_number","price","supply_price","tax","trader"],"type":"object","properties":{"bill_id":{"maxLength":20,"type":"string","description":"청구서 ID \n문자/숫자 20자리 (중복불가) \n -개발: 사업자번호 + 10자리 자유롭게 사용 \n -운영: 20자리 자유롭게 사용"},"hash":{"type":"string","description":"통신 암호 키 \n{phone} 값이 설정된 경우 {bill_id} + \",\" + {phone} + \",\" + {price} 값으로 Hash 생성 \n{phone} 값이 설정되어 있지 않은 경우 {bill_id} + \",\" + {price} 값으로 Hash 생성"},"price":{"type":"string","description":"현금영수증 금액 \n{supply_price} + {tax}"},"supply_price":{"type":"string","description":"공급가액 \n -price에서 tax를 뺀 값을 입력 \n -tax가 0인 경우 price와 동일하게 입력"},"tax":{"type":"string","description":"세금 \n -세금이 없는 경우 0 입력"},"issuance_number":{"type":"string","description":"현금영수증 발급 요청 번호 \n -현금영수증 발급 시 사용\n\n -자진발급시 \"0100001234\""},"trader":{"type":"string","description":"현금영수증 발급 구분 \n개인:0, 사업자:1"}}},"IssueCashReceipt":{"type":"object","properties":{"code":{"type":"string","description":"응답 코드"},"msg":{"type":"string","description":"응답 메세지"},"apikey":{"maxLength":32,"type":"string","description":"파트너 연동을 위한 고유키"},"member":{"maxLength":30,"type":"string","description":"파트너 매장 코드"},"merchant":{"maxLength":30,"type":"string","description":"파트너 사용자 코드"},"bill_id":{"maxLength":20,"type":"string","description":"청구서 ID \n문자/숫자 20자리 (중복불가) \n -개발: 사업자번호 + 10자리 자유롭게 사용 \n -운영: 20자리 자유롭게 사용"},"hash":{"type":"string","description":"통신 암호 키 \n{phone} 값이 설정된 경우 {bill_id} + \",\" + {phone} + \",\" + {price} 값으로 Hash 생성 \n{phone} 값이 설정되어 있지 않은 경우 {bill_id} + \",\" + {price} 값으로 Hash 생성"},"trader":{"type":"string","description":"현금영수증 발급 구분 \n개인:0, 사업자:1"},"appr_cash_num":{"type":"string","description":"현금영수증 발급 승인번호"},"issuance_number":{"type":"string","description":"현금영수증 발급 요청 번호 \n -현금영수증 발급 시 사용\n\n -자진발급시 \"0100001234\""}}}}}} ``` ## 현금영수증 발급 취소 > 발급된 현금영수증을 발급 취소합니다. ```json {"openapi":"3.0.1","info":{"title":"My Project API","version":"1.0.0"},"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/if/cash-receipt/cancel":{"post":{"tags":["erp-cash-receipt-controller"],"summary":"현금영수증 발급 취소","description":"발급된 현금영수증을 발급 취소합니다.","operationId":"cancel_1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReqCancelCashReceipt"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelCashReceipt"}}}}}}}},"components":{"schemas":{"ReqCancelCashReceipt":{"required":["apikey","bill_id","hash","member","merchant","price","trader"],"type":"object","properties":{"apikey":{"maxLength":32,"type":"string","description":"파트너 연동을 위한 고유키"},"merchant":{"maxLength":30,"type":"string","description":"파트너 매장 코드"},"member":{"maxLength":30,"type":"string","description":"파트너 사용자 코드"},"bill_id":{"type":"string","description":"청구서 ID \n문자/숫자 20자리 (중복불가) \n -개발: 사업자번호 + 10자리 자유롭게 사용 \n -운영: 20자리 자유롭게 사용"},"hash":{"type":"string","description":"통신 암호 키 \n{phone} 값이 설정된 경우 {bill_id} + \",\" + {phone} + \",\" + {price} 값으로 Hash 생성 \n{phone} 값이 설정되어 있지 않은 경우 {bill_id} + \",\" + {price} 값으로 Hash 생성"},"price":{"type":"string","description":"결제 금액"},"trader":{"type":"string","description":"현금영수증 발급 구분 \n개인:0, 사업자:1"}}},"CancelCashReceipt":{"type":"object","properties":{"code":{"type":"string","description":"응답 코드"},"msg":{"type":"string","description":"응답 메세지"},"apikey":{"maxLength":32,"type":"string","description":"파트너 연동을 위한 고유키"},"member":{"maxLength":30,"type":"string","description":"파트너 매장 코드"},"merchant":{"maxLength":30,"type":"string","description":"파트너 사용자 코드"},"bill_id":{"maxLength":20,"type":"string","description":"청구서 ID \n문자/숫자 20자리 (중복불가) \n -개발: 사업자번호 + 10자리 자유롭게 사용 \n -운영: 20자리 자유롭게 사용"},"hash":{"type":"string","description":"통신 암호 키 \n{phone} 값이 설정된 경우 {bill_id} + \",\" + {phone} + \",\" + {price} 값으로 Hash 생성 \n{phone} 값이 설정되어 있지 않은 경우 {bill_id} + \",\" + {price} 값으로 Hash 생성"},"appr_cash_num":{"type":"string","description":"현금영수증 발급 승인번호"}}}}}} ``` ## 현금영수증 조회 > 발급된 현금영수증의 정보를 조회합니다. ```json {"openapi":"3.0.1","info":{"title":"My Project API","version":"1.0.0"},"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/if/cash-receipt/read":{"post":{"tags":["erp-cash-receipt-controller"],"summary":"현금영수증 조회","description":"발급된 현금영수증의 정보를 조회합니다.","operationId":"read","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReqReadCashReceipt"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadCashReceipt"}}}}}}}},"components":{"schemas":{"ReqReadCashReceipt":{"required":["apikey","bill_id","hash","member","merchant","price"],"type":"object","properties":{"apikey":{"maxLength":32,"type":"string","description":"파트너 연동을 위한 고유키"},"merchant":{"maxLength":30,"type":"string","description":"파트너 매장 코드"},"member":{"maxLength":30,"type":"string","description":"파트너 사용자 코드"},"bill_id":{"type":"string","description":"청구서 ID \n문자/숫자 20자리 (중복불가) \n -개발: 사업자번호 + 10자리 자유롭게 사용 \n -운영: 20자리 자유롭게 사용"},"hash":{"type":"string","description":"통신 암호 키 \n{phone} 값이 설정된 경우 {bill_id} + \",\" + {phone} + \",\" + {price} 값으로 Hash 생성 \n{phone} 값이 설정되어 있지 않은 경우 {bill_id} + \",\" + {price} 값으로 Hash 생성"},"price":{"type":"string","description":"결제 금액"}}},"ReadCashReceipt":{"type":"object","properties":{"code":{"type":"string","description":"응답 코드"},"msg":{"type":"string","description":"응답 메세지"},"apikey":{"maxLength":32,"type":"string","description":"파트너 연동을 위한 고유키"},"member":{"maxLength":30,"type":"string","description":"파트너 매장 코드"},"merchant":{"maxLength":30,"type":"string","description":"파트너 사용자 코드"},"bill_id":{"maxLength":20,"type":"string","description":"청구서 ID \n문자/숫자 20자리 (중복불가) \n -개발: 사업자번호 + 10자리 자유롭게 사용 \n -운영: 20자리 자유롭게 사용"},"info":{"type":"array","items":{"$ref":"#/components/schemas/CashReceipt"}}}},"CashReceipt":{"type":"object","properties":{"appr_price":{"type":"string","description":"승인금액"},"appr_supply_price":{"type":"string","description":"공급가액"},"appr_tax":{"type":"string","description":"세금"},"appr_num":{"type":"string","description":"응답코드"},"appr_state":{"type":"string","description":"결제 상태 \nF:결제완료, W:미결제, C:취소, D:파기"},"appr_dt":{"type":"string","description":"승인일시"},"trader":{"type":"string","description":"현금영수증 발급 구분 \n개인:0, 사업자:1"},"issuance_number":{"type":"string","description":"현금영수증 발급 요청 번호 \n -현금영수증 발급 시 사용\n\n -자진발급시 \"0100001234\""}}}}}} ``` # 쌤포인트 ## 쌤포인트 잔액 조회 > 잔여 쌤포인트 금액을 조회합니다. ```json {"openapi":"3.0.1","info":{"title":"My Project API","version":"1.0.0"},"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/if/read/remain_count":{"post":{"tags":["erp-read-controller"],"summary":"쌤포인트 잔액 조회","description":"잔여 쌤포인트 금액을 조회합니다.","operationId":"getPartnerRemainPoint","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIKEY"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SsamPointRemainCount"}}}}}}}},"components":{"schemas":{"APIKEY":{"required":["apikey"],"type":"object","properties":{"apikey":{"type":"string","description":"파트너 연동을 위한 고유키"}}},"SsamPointRemainCount":{"type":"object","properties":{"code":{"type":"string","description":"응답 코드"},"msg":{"type":"string","description":"응답 메세지"},"info":{"$ref":"#/components/schemas/remainInfo"}}},"remainInfo":{"type":"object","properties":{"remain_count":{"type":"integer","description":"잔여 쌤포인트","format":"int32"}}}}}} ``` # 콜백 결제선생 -> 파트너에게 전달하는 콜백 입니다 ## 결제 상태 동기화 > 청구서를 통한 결제가 완료되면 페이민트 -> 파트너사에게 결제 상태를 전달합니다. \ > 파트너사는 해당 URL로 결제 상태를 수신하여 자사 시스템에 반영합니다. \ > 파트너사는 페이민트를 통해 결과를 수신할 수 있도록 REST api 형태로 URL을 전달해야합니다. \ > \ > 아래의 필드들을 토대로 페이민트가 호출할 수 있도록 개발 후 수신 응답을 response 양식에 맞춰 개발해야 합니다. \ > response 성공 예제 데이터가 동일한 양식으로 데이터가 오지 않거나 응답 오류가 발생할 경우 페이민트는 24시간동안 매시간마다 동기화를 재시도합니다. ```json {"openapi":"3.0.1","info":{"title":"My Project API","version":"1.0.0"},"servers":[{"url":null,"description":"Generated server url"}],"paths":{"/{파트너사가 제공하는 callbackUrl}":{"post":{"tags":["erp-callback-controller"],"summary":"결제 상태 동기화","description":"청구서를 통한 결제가 완료되면 페이민트 -> 파트너사에게 결제 상태를 전달합니다. \n파트너사는 해당 URL로 결제 상태를 수신하여 자사 시스템에 반영합니다. \n파트너사는 페이민트를 통해 결과를 수신할 수 있도록 REST api 형태로 URL을 전달해야합니다. \n\n아래의 필드들을 토대로 페이민트가 호출할 수 있도록 개발 후 수신 응답을 response 양식에 맞춰 개발해야 합니다. \nresponse 성공 예제 데이터가 동일한 양식으로 데이터가 오지 않거나 응답 오류가 발생할 경우 페이민트는 24시간동안 매시간마다 동기화를 재시도합니다.","operationId":"makeURL","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErpCallbackVO"}}},"required":true},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Base"}}}}}}}},"components":{"schemas":{"ErpCallbackVO":{"required":["apikey","appr_state","bill_id"],"type":"object","properties":{"apikey":{"maxLength":32,"type":"string","description":"파트너 연동을 위한 고유키"},"bill_id":{"maxLength":20,"type":"string","description":"청구서 ID\n\n문자/숫자 20자리 (중복불가)\n\n -개발: 사업자번호 + 10자리 자유롭게 사용\n\n -운영: 20자리 자유롭게 사용"},"appr_card_type":{"type":"string","description":"결제카드종류"},"appr_pay_type":{"type":"string","description":"결제수단코드"},"appr_dt":{"type":"string","description":"승인일시"},"appr_origin_dt":{"type":"string","description":"원거래 승인일시"},"appr_price":{"type":"string","description":"승인금액"},"appr_num":{"type":"string","description":"승인번호"},"appr_origin_num":{"type":"string","description":"원거래승인번호"},"appr_state":{"type":"string","description":"결제 상태\n\nF:결제완료, W:미결제, C:취소, D:파기"},"appr_issuer":{"type":"string","description":"결제은행 / 카드명"},"appr_issuer_cd":{"type":"string","description":"발행카드코드/은행코드"},"appr_issuer_num":{"type":"string","description":"결제카드 / 계좌번호"},"appr_acquirer_cd":{"type":"string","description":"매입사코드"},"appr_acquirer_nm":{"type":"string","description":"매입사명"},"appr_res_cd":{"type":"string","description":"응답코드"},"appr_monthly":{"type":"string","description":"결제시 할부개월수"},"appr_cash_num":{"type":"string","description":"현금영수증 발급 승인번호"},"appr_cash_trader":{"type":"string","description":"현금영수증 발급 구분\n\n개인:0, 사업자:1"},"appr_cash_issuance_number":{"type":"string","description":"현금영수증 발급 요청 번호\n\n-현금영수증 발급 시 사용\n\n-자진발급시 \"0100001234\""}}},"Base":{"type":"object","properties":{"code":{"type":"string","description":"응답 코드"},"msg":{"type":"string","description":"응답 메세지"}}}}}} ``` # 에러 코드 v1
codestatusmessage
0000정상성공하였습니다.
9999실패처리 중에 오류가 발생했습니다. (또는 정의되지 않은 오류 메세지)
9800실패이미 사용된 Bill_ID 입니다.
9970실패기 취소된 청구서 입니다.
9971실패기 결제된 청구서 입니다.
9980실패청구서를 찾을 수 없습니다.
9870실패동기화 대상이 없습니다. (Callback URL오류)
5000실패SYSTEM ERROR
1003실패접근이 불가한 사용자 입니다.
# 자주하는 질문 ## 자동결제
Q. 구독 서비스는 어떻게 만들어야 하나요? 구독 서비스는 [청구서 발송 API](/api/api-v2/send#post-bill-send) 사용해서 직접 구축해야 합니다.\ 1달 주기로 결제가 필요한 상품이면 1달마다 청구서 발송 API를 호출하면 됩니다.
Q. 구독을 취소하면 어떻게 해야 하나요? 다음 결제일에 구독을 취소한 구매자로 청구서를 발송하지 않으면 됩니다.
Q. 구독 결제 금액이나 결제 주기가 변경되면 어떻게 해야 되나요? 결제 금액이 변경 되었다면 [청구서 발송 API](/api/api-v2/send#post-bill-send) 를 호출할 때 price 파라미터를 변경된 결제 금액으로 설정하면 됩니다.
*** ## 청구서
Q.청구서는 기간별 조회가 가능한가요? 현재 API를 통한 청구서 조회는 단건 조회만 가능합니다.\ 청구서 기간별 조회가 필요한 경우 [청구서 조회 API](/api/api-v2/acceptance#post-bill-read)를 사용하여 직접 구축해야 합니다.
*** ## 개발/테스트 환경
Q.테스트 환경에서 결제가 가능한가요? 네 결제선생은 테스트 환경에서 실제 결제를 지원하고 있습니다.\ 다만 일부 특정 카드사의 사정에 따라 결제 테스트가 지원되지 않을 수도 있습니다 결제 가능 카드 * 현대카드, 하나카드, 신한카드 결제 불가능 카드 * 삼성카드, KB국민카드, BC카드, 롯데카드, 우리카드, NH농협카드
Q. 테스트를 완료 했는데 apikey 발급을 어떻게 받나요? 테스트가 완료된 경우 연동 검수 단계를 거쳐 운영에서 사용할 수 있는 apikey를 발급받을 수 있게됩니다.
Q. 테스트 환경에서 결제가 잘 됐는데, 라이브 환경에서 이상해요 1. `apikey`, `member`, `merchant`의 값을 확인해주세요 2. 호출하는 url을 확인해주세요\ 개발 환경과 운영 환경의 도메인(url)은 다른 url 이에요 3. 라이브 환경에서는 대표자 소유의 카드 결제가 실패돼요
*** ## 웹훅(CallBack)
Q. 웹훅 이벤트가 도착하지 않아요 웹훅 URL을 정확하게 입력했는지 다시 한번 확인해주세요 청구서 발송은 매번 새로운 웹훅을 파라미터로 받고 있어요 정확하게 url을 입력했는지 확인해주세요
Q. 웹훅을 어떨 때 받을 수 있나요? [웹훅](/api/api-v2/sub-business#post-callbackurl)은 청구서 결제 완료, 청구서 취소, 하위 사업장 등록 처리가 되었을 때 보내고 있습니다
*** ## 포인트
Q. 쌤포인트가 부족하다고 나와요 포인트 잔액을 확인해주세요\ 자세한 내용은 [링크](#undefined-7)를 참조해주세요
Q. 쌤포인트는 자동충전할 수 없나요? 쌤포인트는 자동 충전이 가능합니다\ 자세한 내용은 링크를 참조해주세요
*** ### API 버전
Q. 기존에 파트너 계약을 맺고 있는데 V2 API 호출하려면 API KEY를 새로 발급 받아야하나요? 기존 파트너 계약을 맺고 있는 파트너 사업자는 V1에서 사용하던 API KEY로 V2 API를 사용할 수 있습니다.
Q. V2 버전에서도 청구서 URL 이용 가능한가요? 청구서 발송의 sendType이 URL인 경우 이용 가능합니다.\ 자세한 내용은 [링크](/api/api-v2/send#post-bill)를 참조해주세요
# API V2 결제선생 파트너 API의 새로운 기능과 변경 사항을 알려드려요. {% updates format="full" %} {% update date="2026-06-11" %} ## API V2 요청 파라미터 명세 수정 v2.0.1 ### 변경 요약 `member` / `merchant` 필드 최대 길이 확장 *** ### 수정 내용 #### 1. `member` / `merchant` 필드 최대 길이 확장 전체 V2 API 엔드포인트에서 `member`(파트너 사용자 코드)와 `merchant`(파트너 매장 코드)의 최대 허용 길이를 확장했습니다. | 필드 | 변경 전 | 변경 후 | | ---------- | ---- | ---- | | `member` | 30자 | 60자 | | `merchant` | 30자 | 60자 | **적용 API** * 청구서 생성 (`POST /bill`) * 청구서 결제 취소 (`POST /bill/cancel`) * 청구서 파기 (`POST /bill/destroy`) * 청구서 조회 (`POST /bill/read`) * 청구서 재발송 (`POST /bill/resend`) * RP 청구서 결제 (`POST /bill/rp`) * RP 자동결제 수단 등록 (`POST /rp/manage`) * RP 자동결제 수단 삭제 (`POST /rp/delete`) * 현금영수증 발행 (`POST /cash-receipt/issue`) * 현금영수증 취소 (`POST /cash-receipt/cancel`) * 현금영수증 조회 (`POST /cash-receipt/read`) * 고객 결제 수단 조회 (`POST /customer/pay-method`) * 하위 사업장 게시 상태 확인 (`POST /partner/auth/mapping-status`) {% endupdate %} {% update date="2026-05-13" %} ## 결제선생 파트너 개발자센터 공식 Release v2.0.0 결제선생 개발자센터 정식 오픈과 함께 제공되는 V2 API 기능 목록입니다. 상세 규격은 각 섹션의 연동가이드를 참고해 주세요. ### 제공 기능 #### 청구서 발송 및 파기 * **카카오톡 청구서 발송** — 청구서 생성 후 고객에게 카카오톡 발송 * **청구서 재발송** — 카카오톡 재발송 * **청구서 파기** — 미결제 청구서 파기 #### 수납 및 결제취소 * **결제 승인** - 청구서를 통한 결제 * **결제 취소** — 승인된 거래 취소 처리 * **거래 내역 조회** — billId 기준 단건 조회 #### 현금 영수증 * **발행 / 취소 / 조회** #### 하위사업장 가입 및 등록 * **하위 사업장 등록 URL 발급** — 파트너 고객 사업장 연동용 URL * **하위 사업장 매핑 및 상태 조회** — 연동 현황 확인 * **하위 사업장 연동 상태 콜백** #### 하위 사업장 조회 * **하위 사업장 리스트 조회** * **파트너 정보 조회 / callbackUrl 변경** #### 쌤포인트 잔액 조회 * **잔액 조회** — 관리 사업장 / 하위 사업장 기준 #### Callback * **결제 승인 결과 콜백** — 파트너 callbackUrl로 결제 결과 전달 * **승인 결과 재전송 관제** — 콜백 실패 시 자동 재전송 (승인일시기준으로 24시간내에 1시간 마다 자동 재전송) #### 기타 * **에러 코드 v2 정리** *** 문의: 상세 규격 및 연동 방법은 개발자센터 연동가이드를 참고해 주세요. {% endupdate %} {% endupdates %} # API V1 {% updates format="full" %} {% update date="2026-05-13" %} ## 결제선생 파트너 개발자센터 공식 Release 현재 운영 중인 V1 연동규격서 기준 제공 기능 목록입니다. \ 사업 모델에 따라 **T(v1.2.5)** / **U(v1.2.6)** 두 가지 규격이 제공되며, 규격별로 일부 기능이 상이합니다. * **T (v1.2.5)**: 카카오톡 알림톡 기반 청구서 발송 모델 * **U (v1.2.6)**: 청구서 URL 발급 모델 ### 제공 기능 #### 청구서 발송 및 파기 * **카카오톡 청구서 발송** `T` — 알림톡으로 결제 청구서 발송 * **청구서 URL 발급** `U` — 결제 가능한 청구서 URL을 응답으로 반환 * **청구서 재발송** `T` — 알림톡 재발송 * **청구서 파기** `T` `U` — 미결제 청구서 파기 #### 수납 및 결제취소 * **결제 취소** `T` `U` — 승인된 거래 취소 처리 * **결제 상태 조회** `T` `U` — billId 기준 단건 조회 * **카드 인증** `T` `U` — 카드 유효성 인증 #### 현금 영수증 * **발행 / 취소 / 조회** `T` `U` #### 가맹점 / 매장 조회 * **가맹점 정보 조회** `T` `U` * **매장 개시상태 조회** `T` `U` — 가맹점 개시 상태 확인 #### 쌤포인트 잔액 조회 * **잔액 조회** `T` `U` #### Callback * **승인 동기화 콜백** `T` `U` — 파트너 callbackURL로 결제 승인 결과 전달 #### 기타 * **에러 코드 v1 정리** *** 연동규격서: `가맹점_연동규격서_v1.2.5_T.pdf`, `가맹점_연동규격서_v1.2.6_U.pdf` {% endupdate %} {% endupdates %}