> For the complete documentation index, see [llms.txt](https://tech.x2bee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tech.x2bee.com/api-guide/back-office/settlement-bo/pg.md).

# PG 승인 대사 관리

EC 시스템의 결제 내역과 PG사(이니시스)의 승인 내역 간의 대사를 수행합니다. 주요 기능으로는 PG승인대사 및 PG정산대사가 있으며, 이를 통해 금액 불일치 시 조정 및 입금 확정/취소 처리가 가능합니다.

***

## 주요 기능

* **PG승인대사**
  * EC 결제금액과 PG 거래금액이 동일한 건에 대해 정산대사를 진행합니다.
  * 수수료를 고려한 입금금액이 EC 입금 예정액과 일치하지 않을 경우 기타조정금액을 조정합니다.
  * 입금확정 및 확정취소 처리가 가능합니다.
  * PG 정산정보 수신 시 자동으로 입금확정 처리를 진행합니다.
* **PG정산대사**
  * PG승인목록 중 EC 결제금액과 PG 거래금액이 동일한 건에 대해 정산대사를 진행합니다.
  * 수수료를 고려한 입금금액이 EC 입금 예정액과 일치하지 않을 경우 기타조정금액을 조정합니다.
  * 입금확정 및 확정취소 처리가 가능합니다.
  * PG 정산정보 수신 시 자동으로 입금확정 처리를 진행합니다.

## 프로세스 정의

사이트의 결제/취소 내역과 PG사의 승인/승인취소 내역을 대사 합니다.

승인 시 금액이 일치하는 건에 대해 입금정보와 정산정보를 대사 합니다.

<figure><img src="/files/zsw3wLCFcMUZdf4ZORfO" alt=""><figcaption></figcaption></figure>

{% stepper %}
{% step %}

### PG승인대사 요약 조회

선택한 조회조건에 대한 요약 정보를 조회합니다.

* EC승인내역, PG승인내역, 두 내역에 대한 차이내역을 조회합니다.
* 각 건수를 클릭하면 상세 목록을 조회합니다.
  {% endstep %}

{% step %}

### PG승인대사 목록 조회

선택한 조회조건에 대한 목록을 조회합니다.

* 결제 건에 대한 정보와 EC, PG 금액 대사결과, 불일치사유를 조회합니다.
* 주문번호 클릭 시 주문클레임처리 화면으로 이동합니다.
  {% endstep %}

{% step %}

### PG승인정보 수신

Api-common 서버를 호출해 PG사의 승인 정보를 수신합니다.
{% endstep %}

{% step %}

### PG승인대사목록 수신

PG사 api를 통해 PG사 승인 정보를 가져와 저장합니다.

* 넘어온 데이터가 있을 시 저장합니다.
* 입금확정이 된 거래번호는 제외하고 저장합니다.
  {% endstep %}

{% step %}

### PG승인대사 불일치사유 저장

EC 결제 건과 PG사 승인 건의 금액이 일치하지 않을 시 (누락 포함) 불일치 사유를 등록합니다.
{% endstep %}

{% step %}

### PG정산대사 요약 조회

선택한 조회조건에 대한 요약 정보를 조회합니다.

* EC 시스템의 결제금액, 예정수수료, 입금예정액과 PG사 승인금액, 결제수수료, 입금금액의 합과 조정금액의 합, EC-PG 차이를 조회합니다.
  {% endstep %}

{% step %}

### PG정산대사 목록 조회

선택한 조회조건에 대한 목록을 조회합니다.

* 정산 정보와 입금금액 차이, 조정사유를 조회합니다.
* 주문번호 클릭 시 주문클레임처리 화면으로 이동합니다.
  {% endstep %}

{% step %}

### PG정산정보 수신

Api-common 서버를 호출해 PG사의 정산 정보를 수신합니다.
{% endstep %}

{% step %}

### PG정산대사목록 수신

PG사 api를 통해 PG사 정산 정보를 가져와 저장합니다.

* 유효 데이터만 저장합니다.
* 입금확정이 된 거래번호는 제외하고 저장합니다.
  {% endstep %}

{% step %}

### PG정산대사 조정사유 저장

EC 입금예정액과 PG 입금금액 차이가 존재할 시 조정사유 및 조정금액을 저장합니다.

* 조정금액은 입금금액차이 \~ 0 이 될 때까지 입니다.
  {% endstep %}

{% step %}

### PG정산대사 입금확정/입금확정취소 처리

입금금액차이가 0 인 건에 한해 입금확정 처리를 할 수 있습니다.
{% endstep %}
{% endstepper %}

## API 기능 목록\_PG승인대사

<table><thead><tr><th width="123.4444580078125">API</th><th width="274.888916015625">설명</th><th width="93.5556640625" align="center">Server</th><th width="96.888916015625" align="center">메소드</th><th>비고</th></tr></thead><tbody><tr><td>PG승인대사 요약조회</td><td>PG승인대사 목록에 대한 요약 건수 및 합계를 조회합니다.</td><td align="center">BO</td><td align="center">POST</td><td><a href="http://apibo.x2bee.com/content?bo=settlement&#x26;depth=PG%EC%8A%B9%EC%9D%B8%EB%8C%80%EC%82%AC&#x26;path=getPgApprovalCompareSummary">🔗API 확인하기 ></a></td></tr><tr><td>PG승인대사 목록조회</td><td>PG승인대사 목록을 조회합니다.</td><td align="center">BO</td><td align="center">POST</td><td><a href="http://apibo.x2bee.com/content?bo=settlement&#x26;depth=PG%EC%8A%B9%EC%9D%B8%EB%8C%80%EC%82%AC&#x26;path=getPgApprovalCompareList">🔗API 확인하기 ></a></td></tr><tr><td>PG승인정보 수신</td><td>특정 날짜, PG사에 대한 PG 승인 목록을 수신합니다. <br>PG승인대사목록 수신 - /api/common/v1/adjust/pgCompare/receivePgApprovalList</td><td align="center">BO</td><td align="center">POST</td><td><a href="http://apibo.x2bee.com/content?bo=settlement&#x26;depth=PG%EC%8A%B9%EC%9D%B8%EB%8C%80%EC%82%AC&#x26;path=savePgApprovalList">🔗API 확인하기 ></a></td></tr><tr><td>PG승인대사 불일치사유 저장</td><td>PG 승인 건과 EC 결제 건의 대사 불일치 사유를 저장합니다.</td><td align="center">BO</td><td align="center">POST</td><td><a href="http://apibo.x2bee.com/content?bo=settlement&#x26;depth=PG%EC%8A%B9%EC%9D%B8%EB%8C%80%EC%82%AC&#x26;path=savePgApprovalCompareDscdCaus">🔗API 확인하기 ></a></td></tr><tr><td>PG승인대사목록 수신</td><td>특정 날짜, PG사에 대한 PG 승인 목록을 PG사 인터페이스를 통해 수신합니다. <br>PG승인대사목록 수신 - /api/common/v1/adjust/pgCompare/receivePgApprovalList</td><td align="center">BO</td><td align="center">POST</td><td><a href="http://apibo.x2bee.com/content?bo=settlement&#x26;depth=PG%EC%8A%B9%EC%9D%B8%EB%8C%80%EC%82%AC&#x26;path=savePgApprovalList">🔗API 확인하기 ></a></td></tr></tbody></table>

## API 기능 목록\_PG정산대사

<table><thead><tr><th width="129">API</th><th width="299.5556640625">설명</th><th width="92.4444580078125" align="center">Server</th><th width="90.22216796875" align="center">메소드</th><th>비고</th></tr></thead><tbody><tr><td>PG정산대사 요약 조회</td><td>PG정산대사 목록에 대한 요약정보를 조회합니다.</td><td align="center">BO</td><td align="center">POST</td><td><a href="https://apibo.x2bee.com/content?bo=settlement&#x26;depth=PG%EC%A0%95%EC%82%B0%EB%8C%80%EC%82%AC&#x26;path=getPgAdjustCompareSummary">🔗API 확인하기 ></a></td></tr><tr><td>PG정산대사 목록 조회</td><td>PG정산대사 목록을 조회합니다.</td><td align="center">BO</td><td align="center">POST</td><td><a href="http://apibo.x2bee.com/content?bo=settlement&#x26;depth=PG%EC%A0%95%EC%82%B0%EB%8C%80%EC%82%AC&#x26;path=getPgAdjustCompareList">🔗API 확인하기 ></a></td></tr><tr><td>PG정산대사 조정사유 저장</td><td>입금금액이 불일치하는 건에 대해 금액을 조정하고 사유를 저장합니다.</td><td align="center">BO</td><td align="center">POST</td><td><a href="http://apibo.x2bee.com/content?bo=settlement&#x26;depth=PG%EC%A0%95%EC%82%B0%EB%8C%80%EC%82%AC&#x26;path=savePgAdjustCompareAjstCaus">🔗API 확인하기 ></a></td></tr><tr><td>PG정산정보 수신</td><td>특정 날짜, PG사에 대한 PG 정산 목록을 수신합니다. <br>*PG정산대사목록 수신 - /api/common/v1/adjust/pgCompare/receivePgAdjustList</td><td align="center">BO</td><td align="center">POST</td><td><a href="http://apibo.x2bee.com/content?bo=settlement&#x26;depth=PG%EC%A0%95%EC%82%B0%EB%8C%80%EC%82%AC&#x26;path=savePgApprovalList_1">🔗API 확인하기 ></a></td></tr><tr><td>PG정산대사 입금확정/입금확정 취소 <br>처리</td><td>입금금액이 일치하는 건에 대해 입금을 확정 처리하거나 입금확정에 대한 취소처리를 합니다.</td><td align="center">BO</td><td align="center">POST</td><td><a href="http://apibo.x2bee.com/content?bo=settlement&#x26;depth=PG%EC%A0%95%EC%82%B0%EB%8C%80%EC%82%AC&#x26;path=processDepositConfirmAndCancel">🔗API 확인하기 ></a></td></tr><tr><td>PG 정산대사목록 수신</td><td>특정 날짜, PG사에 대한 PG 정산 목록을 PG사 인터페이스를 통해 수신합니다. <br>*PG정산대사목록 수신 - /api/common/v1/adjust/pgCompare/receivePgAdjustList</td><td align="center">BO</td><td align="center">POST</td><td><a href="http://apibo.x2bee.com/content?bo=settlement&#x26;depth=PG%EC%A0%95%EC%82%B0%EB%8C%80%EC%82%AC&#x26;path=savePgApprovalList_1">🔗API 확인하기 ></a></td></tr></tbody></table>

## 용어 정의

<table><thead><tr><th width="142.8887939453125">명칭</th><th>설명</th><th data-hidden>비고</th></tr></thead><tbody><tr><td>PG사 (Payment Gateway)</td><td><p>카드결제, 간편결제, 계좌이체, 가상계좌(무통장입금), 상품권결제, 휴대폰결제 등 다양한 결제 방식을 사용할 수 있게 연결해주는 역할을 합니다. </p><p>‘전자결제 지급 대행사’를 뜻합니다.</p></td><td></td></tr></tbody></table>

## 기타 참고사항

* 현재 이니시스 mid는 개인으로 발급받지 않고 공용 mid를 사용하고 있어 모든 테스트 데이터가 넘어오기 때문에 X2BEE 주문만 구별해주기 위해 승인대사, 정산대사 저장 시 X2BEE 주문 정규식 패턴에 맞는 주문번호만 저장하고 있다.
  * Pattern.compile("^\d{4}(0\[1-9]|1\[0-2])(0\[1-9]|\[12]\d|3\[01])O\d{6}$")
* **PG승인대사**
  * Api-common 의 PG승인정보 수신 api 에서는 request 에 넘어온 PG사에 대해 application.yml 의 “pg.compare” 레벨로 등록 되어있는 mid 에 대한 승인 정보를 가져옵니다.
  * 승인정보 수신 시 PG사 별 데이터 및 유효성 체크
    * 이니시스(Inicis)
      * 유효성체크: 넘어온 데이터가 **0001**(가맹점 서버에 등록되지 않은 IP 로 조회했을 경우), **0003**(가맹점관리자 사이트에서 데이터 항목설정을 하지 않았을 경우) 으로 시작하면 예외 처리
      * 데이터: 모든 내역이 String 으로 넘어오기 때문에 승인 건 당 \*\*“\
        ”\*\*로 split 후 각 항목을 \*\*“|”\*\*로 split 한다.
  * 매입 전 취소 (당일취소) 일 때는 PG 승인목록에 결제승인 데이터가 존재하지 않아서 EC 시스템과 대사해주기 위해 승인 데이터를 직접 생성합니다.
* **PG정산대사**
  * 정산정보 수신 시 PG사 별 데이터 및 유효성 체크
    * 이니시스(Inicis)
      * 유효성체크: 넘어온 데이터의 Header 를 쪼갰을 때, 21번쨰 데이터(에러코드) 가 “**02**(잘못된 날짜형식), **03**(mid 패스워드 오류), **04**(IP권한오류), **99**(알수없는 오류)” 이면 예외 처리
      * 데이터: 모든 내역이 String 으로 넘어오기 때문에 승인 건 당 \*\*“\
        ”\*\*로 split 후 실제 데이터(B로 시작하는 row)를 추려서 각 항목을 \*\*“|”\*\*로 split 한다.