> For the complete documentation index, see [llms.txt](https://developers.payssam.kr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.payssam.kr/api/api-v2/call-back.md).
# 콜백
## 파트너 하위 사업장 연동 결과 동기화 콜백
> 파트너 하위 사업장 연동 과정에서 연동 상태 변경을 페이민트 -> 파트너사에게 전달합니다.\
> 파트너사는 아래 전문을 수신할 수 있는 엔드포인트를 구축해야 해야 합니다.\
> 구축하신 엔드포인트의 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"]}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://developers.payssam.kr/api/api-v2/call-back.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.