modooapi-workers-penny — 연동 메뉴얼

계좌 1원 인증(Checkpay 체크페이) — 내부 전용, 중앙 토큰 인증, relay 경유. 예금주 계좌에 1원을 이체하고 입금 적요의 코드로 계좌 소유를 확인한다(Checkpay/쿠콘, CPIF_AFFL_720). 흐름: 플랫폼 →(Bearer) POST /api/verify/request {bankCode, accountNumber, name} → 1원 입금(적요+숫자) → 사용자가 통장 적요의 코드 확인 → POST /api/verify/confirm {bankCode, accountNumber, code}. 서명: AES-256-CBC(EV)+HMAC-SHA256(VV). Step1=CPIF_AFFL_720(1원 이체), Step2=CPIF_AFFL_721(코드검증). 예금주명(name) 필수(memb_nm). 요청 유효 5분, 계좌별 제한(60초 3회/600초 6회). Checkpay 호출은 relay 고정 IP(209.71.88.78) 경유(화이트IP). 시각 KST. 미설정 시 stub 모드.

연동 가이드

## 2단계 인증 흐름 1) POST /api/verify/request {bankCode, accountNumber, name} — 예금주 계좌로 1원을 이체한다. 통장 적요에 '모두+숫자3자리'(예: 모두475)가 찍힌다. 응답의 verificationId 를 보관. 2) 사용자가 통장(앱/문자)에서 적요의 숫자 3자리를 확인. 3) POST /api/verify/confirm {bankCode, accountNumber, code} — 숫자 3자리를 검증한다. 5분 내 1회. ## 필드 - bankCode: 표준 은행코드 3자리(예: 농협 011, 카카오뱅크 090). accountNumber: 숫자만(하이픈 제거). - name: 예금주명(필수, Checkpay memb_nm). 예금주 불일치 시 1원 이체가 거절될 수 있다. - code: 통장 적요의 숫자 3자리. ## 운영 메모 - Checkpay 호출은 relay 고정 IP(209.71.88.78) 경유 — 화이트리스트 등록 IP. Step1/Step2 운영 검증 완료. - 요청 유효 5분, 계좌별 제한(60초 3회 / 600초 6회). - 계좌번호는 마스킹 저장(개인정보 비저장). 시각 KST(+09:00). - 기관코드·암복호화키(32자) 미설정 시 stub(개발) 모드로 동작 — 실 이체 없이 응답에 코드가 내려온다. - 연동 키 관리: https://penny.modooapi.com/console (CONSOLE_SECRET 관리자 전용).

인증

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

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

엔드포인트

GET/helpGET/help/promptGET/healthPOST/api/verify/requestPOST/api/verify/confirmGET/api/verifications/:vid

GET /help 공개

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

GET /help/prompt 공개

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

GET /health 공개

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

POST /api/verify/request 🔒 토큰

1원 이체 요청(인증 시작)

예금주 계좌로 1원을 이체한다(Checkpay). 적요에 '모두+숫자' 코드가 찍힌다. name(예금주명) 필수. 응답의 verificationId 로 상태 조회.

요청

{ "bankCode": "081", "accountNumber": "36191042607707", "name": "박준영", "ref": "signup-abc" }

응답

{ "success": true, "data": {
  "verificationId": "9f2c…", "expiresInSeconds": 300,
  "message": "1원이 입금되었습니다. 입금자명을 확인해주세요." } }

POST /api/verify/confirm 🔒 토큰

입금자명(숫자 3자리) 검증

사용자가 통장에서 확인한 입금자명 숫자 3자리를 검증한다. 요청 정보는 5분 후 만료된다.

요청

{ "bankCode": "004", "accountNumber": "12345678901234", "code": "123" }

응답

{ "success": true, "data": {
  "verificationId": "9f2c…", "verified": true, "message": "계좌 인증이 완료되었습니다." } }

GET /api/verifications/:vid 🔒 토큰

인증 상태 조회(verificationId 기준)

계좌번호는 마스킹되어 저장된다(개인정보 비저장).

응답

{ "success": true, "data": {
  "vid": "9f2c…", "bank_code": "004", "account_masked": "1234**********",
  "status": "verified", "requested_at": "…", "verified_at": "…" } }

AI 에이전트 연동

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

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

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

- Base URL: https://penny.modooapi.com
- 인증: modooapi.com/console 에서 발급한 중앙 액세스 토큰을 모든 /api/* 요청에 `Authorization: Bearer <token>` 헤더로 전송한다.
- 공통 응답: 성공 { "success": true, "data": ... }, 실패 { "success": false, "error": "<메시지>" }.
- 개요: 예금주 계좌에 1원을 이체하고 입금 적요의 코드로 계좌 소유를 확인한다(Checkpay/쿠콘, CPIF_AFFL_720). 흐름: 플랫폼 →(Bearer) POST /api/verify/request {bankCode, accountNumber, name} → 1원 입금(적요+숫자) → 사용자가 통장 적요의 코드 확인 → POST /api/verify/confirm {bankCode, accountNumber, code}. 서명: AES-256-CBC(EV)+HMAC-SHA256(VV). Step1=CPIF_AFFL_720(1원 이체), Step2=CPIF_AFFL_721(코드검증). 예금주명(name) 필수(memb_nm). 요청 유효 5분, 계좌별 제한(60초 3회/600초 6회). Checkpay 호출은 relay 고정 IP(209.71.88.78) 경유(화이트IP). 시각 KST. 미설정 시 stub 모드.

## 연동 가이드
## 2단계 인증 흐름
1) POST /api/verify/request {bankCode, accountNumber, name} — 예금주 계좌로 1원을 이체한다. 통장 적요에 '모두+숫자3자리'(예: 모두475)가 찍힌다. 응답의 verificationId 를 보관.
2) 사용자가 통장(앱/문자)에서 적요의 숫자 3자리를 확인.
3) POST /api/verify/confirm {bankCode, accountNumber, code} — 숫자 3자리를 검증한다. 5분 내 1회.

## 필드
- bankCode: 표준 은행코드 3자리(예: 농협 011, 카카오뱅크 090). accountNumber: 숫자만(하이픈 제거).
- name: 예금주명(필수, Checkpay memb_nm). 예금주 불일치 시 1원 이체가 거절될 수 있다.
- code: 통장 적요의 숫자 3자리.

## 운영 메모
- Checkpay 호출은 relay 고정 IP(209.71.88.78) 경유 — 화이트리스트 등록 IP. Step1/Step2 운영 검증 완료.
- 요청 유효 5분, 계좌별 제한(60초 3회 / 600초 6회).
- 계좌번호는 마스킹 저장(개인정보 비저장). 시각 KST(+09:00).
- 기관코드·암복호화키(32자) 미설정 시 stub(개발) 모드로 동작 — 실 이체 없이 응답에 코드가 내려온다.
- 연동 키 관리: https://penny.modooapi.com/console (CONSOLE_SECRET 관리자 전용).

## 엔드포인트

### POST https://penny.modooapi.com/api/verify/request  [🔒 토큰]
1원 이체 요청(인증 시작) — 예금주 계좌로 1원을 이체한다(Checkpay). 적요에 '모두+숫자' 코드가 찍힌다. name(예금주명) 필수. 응답의 verificationId 로 상태 조회.
요청:
{ "bankCode": "081", "accountNumber": "36191042607707", "name": "박준영", "ref": "signup-abc" }
응답:
{ "success": true, "data": {
  "verificationId": "9f2c…", "expiresInSeconds": 300,
  "message": "1원이 입금되었습니다. 입금자명을 확인해주세요." } }

### POST https://penny.modooapi.com/api/verify/confirm  [🔒 토큰]
입금자명(숫자 3자리) 검증 — 사용자가 통장에서 확인한 입금자명 숫자 3자리를 검증한다. 요청 정보는 5분 후 만료된다.
요청:
{ "bankCode": "004", "accountNumber": "12345678901234", "code": "123" }
응답:
{ "success": true, "data": {
  "verificationId": "9f2c…", "verified": true, "message": "계좌 인증이 완료되었습니다." } }

### GET https://penny.modooapi.com/api/verifications/:vid  [🔒 토큰]
인증 상태 조회(verificationId 기준) — 계좌번호는 마스킹되어 저장된다(개인정보 비저장).
응답:
{ "success": true, "data": {
  "vid": "9f2c…", "bank_code": "004", "account_masked": "1234**********",
  "status": "verified", "requested_at": "…", "verified_at": "…" } }

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

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