modooapi-workers-hecto — 연동 메뉴얼

헥토(Hecto) PG 결제 게이트웨이 — 내부 전용, 중앙 토큰 인증, relay 경유. 헥토파이낸셜 내통장결제. 흐름: 플랫폼 →(Bearer) POST /api/payments → {payUrl} 수신 → 사용자를 payUrl 로 이동 → 헥토 SettlePay 결제창 → 사용자 인증 → /callback 수신 → 서버승인(relay 고정IP) → returnUrl 로 리다이렉트. 결제값/CI 는 GET /api/payments/:ordNo 로 조회. 환불은 POST /api/refunds(전액).

인증

🔒 토큰 modooapi.com/console 발급 토큰을 Authorization: Bearer <token>

🔑 관리자콘솔 로그인 🛡 IP제한등록 발신 IP 공개인증 없음

엔드포인트

GET/helpGET/help/promptGET/healthPOST/api/paymentsGET/api/payments/:ordNoGET/api/payments/:ordNo/logsPOST/api/refundsGET/api/refunds/:ordNoGET/pay/:sessionPOST/callbackPOST/cancel

GET /help 공개

이 워커의 설명·연동 메뉴얼(HTML/JSON)

GET /help/prompt 공개

AI 에이전트 연동 프롬프트(text/plain)

GET /health 공개

가동 상태(status 워커가 집계)

POST /api/payments 🔒 토큰

결제 개시 → payUrl 발급

결제 세션 생성. 응답의 payUrl 로 사용자를 보내면 헥토 결제창이 열린다. custCi(본인인증 CI)는 플랫폼이 전달.

요청

{ "amount": 12800, "productNm": "상품권", "custCi": "<PASS CI>",
  "returnUrl": "https://platform.example.com/result", "cphoneNo": "01012345678", "ref": "order-123" }

응답

{ "success": true, "data": {
  "ordNo": "HP_order-123_213600219", "payUrl": "https://hecto.modooapi.com/pay/<session>", "expiresInSeconds": 600 } }

GET /api/payments/:ordNo 🔒 토큰

결제 상태·결제값·CI 조회

응답

{ "success": true, "data": { "ordNo": "HP_...", "status": "success",
  "trNo": "<헥토 거래번호>", "payPrice": 12800, "authNo": "...", "resultCd": "0", "ci": "<복호화 CI>" } }

GET /api/payments/:ordNo/logs 🔒 토큰

거래 요청/응답 로그(마스킹)

응답

{ "success": true, "data": [ { "direction": "response", "api_name": "APIPayApprov", "payload": {...} } ] }

POST /api/refunds 🔒 토큰

전액 환불(APIPayCancel)

요청

{ "ordNo": "HP_order-123_213600219", "reason": "고객요청" }

응답

{ "success": true, "data": { "ordNo": "HP_...", "refundOrdNo": "HR_...", "status": "success", "cancelTrNo": "..." } }

GET /api/refunds/:ordNo 🔒 토큰

환불 상태 조회(원결제 ordNo 기준)

응답

{ "success": true, "data": { "ord_no": "HR_...", "status": "success", "cancel_price": 12800 } }

GET /pay/:session 공개

결제창 launch 페이지(사용자 브라우저)

POST /api/payments 가 발급한 payUrl. SettlePay.js 로드 후 헥토 결제창을 연다.

POST /callback 공개

헥토 결제 결과 콜백(사용자 브라우저 form POST)

헥토 인증 결과 수신. mercntId·resultCd·ordNo 검증 후 APIPayApprov 서버승인으로 결제 확정, returnUrl 로 리다이렉트. 서명 없음 → 승인 API 가 신뢰원천.

POST /cancel 공개

사용자 취소 콜백 → returnUrl?status=cancelled

AI 에이전트 연동

연동 프롬프트 펼치기 (text 원문: GET https://hecto.modooapi.com/help/prompt)

# modooapi-workers-hecto 연동 가이드 (AI 에이전트용)

너는 modooapi 의 "modooapi-workers-hecto" API 를 호출하는 통합 에이전트다. 아래 명세대로 정확히 요청을 구성하라.

- Base URL: https://hecto.modooapi.com
- 인증: modooapi.com/console 에서 발급한 중앙 액세스 토큰을 모든 /api/* 요청에 `Authorization: Bearer <token>` 헤더로 전송한다.
- 공통 응답: 성공 { "success": true, "data": ... }, 실패 { "success": false, "error": "<메시지>" }.
- 개요: 헥토파이낸셜 내통장결제. 흐름: 플랫폼 →(Bearer) POST /api/payments → {payUrl} 수신 → 사용자를 payUrl 로 이동 → 헥토 SettlePay 결제창 → 사용자 인증 → /callback 수신 → 서버승인(relay 고정IP) → returnUrl 로 리다이렉트. 결제값/CI 는 GET /api/payments/:ordNo 로 조회. 환불은 POST /api/refunds(전액).

## 엔드포인트

### POST https://hecto.modooapi.com/api/payments  [🔒 토큰]
결제 개시 → payUrl 발급 — 결제 세션 생성. 응답의 payUrl 로 사용자를 보내면 헥토 결제창이 열린다. custCi(본인인증 CI)는 플랫폼이 전달.
요청:
{ "amount": 12800, "productNm": "상품권", "custCi": "<PASS CI>",
  "returnUrl": "https://platform.example.com/result", "cphoneNo": "01012345678", "ref": "order-123" }
응답:
{ "success": true, "data": {
  "ordNo": "HP_order-123_213600219", "payUrl": "https://hecto.modooapi.com/pay/<session>", "expiresInSeconds": 600 } }

### GET https://hecto.modooapi.com/api/payments/:ordNo  [🔒 토큰]
결제 상태·결제값·CI 조회
응답:
{ "success": true, "data": { "ordNo": "HP_...", "status": "success",
  "trNo": "<헥토 거래번호>", "payPrice": 12800, "authNo": "...", "resultCd": "0", "ci": "<복호화 CI>" } }

### GET https://hecto.modooapi.com/api/payments/:ordNo/logs  [🔒 토큰]
거래 요청/응답 로그(마스킹)
응답:
{ "success": true, "data": [ { "direction": "response", "api_name": "APIPayApprov", "payload": {...} } ] }

### POST https://hecto.modooapi.com/api/refunds  [🔒 토큰]
전액 환불(APIPayCancel)
요청:
{ "ordNo": "HP_order-123_213600219", "reason": "고객요청" }
응답:
{ "success": true, "data": { "ordNo": "HP_...", "refundOrdNo": "HR_...", "status": "success", "cancelTrNo": "..." } }

### GET https://hecto.modooapi.com/api/refunds/:ordNo  [🔒 토큰]
환불 상태 조회(원결제 ordNo 기준)
응답:
{ "success": true, "data": { "ord_no": "HR_...", "status": "success", "cancel_price": 12800 } }

### GET https://hecto.modooapi.com/pay/:session  [공개]
결제창 launch 페이지(사용자 브라우저) — POST /api/payments 가 발급한 payUrl. SettlePay.js 로드 후 헥토 결제창을 연다.

### POST https://hecto.modooapi.com/callback  [공개]
헥토 결제 결과 콜백(사용자 브라우저 form POST) — 헥토 인증 결과 수신. mercntId·resultCd·ordNo 검증 후 APIPayApprov 서버승인으로 결제 확정, returnUrl 로 리다이렉트. 서명 없음 → 승인 API 가 신뢰원천.

### POST https://hecto.modooapi.com/cancel  [공개]
사용자 취소 콜백 → returnUrl?status=cancelled

## 규칙
- 금액은 정수(원). 날짜/시각은 명세 포맷을 따른다.
- 토큰이 없거나 무효면 401. 권한/IP 오류는 403. 입력 오류는 400.
- 실패 시 error 메시지와 (있으면) resCode 를 사용자에게 그대로 전달하라.

modooapi · modooapi-workers-hecto · JSON: GET /help + Accept: application/json