오픈뱅킹 연동 플로우

간편현금결제(오픈뱅킹)의 전체 프로세스는 인증 → 계좌등록 → 결제 3단계로 구성됩니다.

전체 흐름

고객

가맹점 서버

헥토파이낸셜

11. 결제 요청

1. 결제 요청

22. ARS 인증 요청

2. ARS 인증 요청

33. ARS 인증 전화 발신

3. ARS 인증 전화 발신

44. 인증 완료 전달

4. 인증 완료 전달

55. ARS 인증 확인 → trdNo 획득

5. ARS 인증 확인 → trdNo 획득

66. 계좌 등록 (오픈뱅킹용)

6. 계좌 등록 (오픈뱅킹용)

77. 결제 (오픈뱅킹용)

7. 결제 (오픈뱅킹용)

88. 결제 결과 응답

8. 결제 결과 응답

NOTE

최초 1회 등록

계좌등록(6단계)은 최초 1회만 수행합니다. 이미 등록된 계좌로 결제 시에는 인증~계좌등록 단계 없이 바로 결제 API를 호출할 수 있습니다.

NOTE

펌뱅킹 기존 고객 오픈뱅킹 추가 등록

펌뱅킹으로 이미 계좌가 등록된 고객은 '오픈뱅킹 계좌등록' API를 별도로 호출하여 오픈뱅킹 서비스를 추가할 수 있습니다. 최초 등록 시에는 '계좌 등록 (오픈뱅킹용)' API 하나로 펌뱅킹과 오픈뱅킹을 동시에 등록 처리합니다.

1단계: ARS 계좌점유인증

고객 전화를 통한 ARS 인증으로 계좌 점유를 확인하고 거래번호(trdNo)를 획득합니다.

순서	API	URI	설명
1	ARS 인증 요청	`POST /v1/api/auth/ars`	고객 전화로 ARS 인증 발신
2	ARS 인증 확인	`POST /v1/api/auth/arscheck`	ARS 인증 결과 조회 및 trdNo 획득

NOTE

trdNo 보관 필수

ARS 인증 확인 API 응답으로 받은 거래번호(trdNo)는 다음 단계인 계좌 등록 시 필수 파라미터입니다. 가맹점 서버에서 임시 보관해야 합니다.

NOTE

ARS 인증 API는 펌뱅킹 공통 API

ARS 인증 요청/확인은 간편현금결제(펌뱅킹) 인증 서비스의 /v1/api/auth/ 경로를 사용합니다.

ARS 인증 API 문서

ARS 인증 요청

ARS 자동응답 인증 발신

ARS 인증 확인

ARS 인증 결과 조회 및 trdNo 획득

2단계: 계좌 등록 (오픈뱅킹용)

ARS 인증에서 획득한 trdNo를 사용하여 계좌를 등록합니다. 한 번의 API 호출로 펌뱅킹과 오픈뱅킹 계좌를 동시에 등록합니다.

API	URI	설명
계좌등록 (오픈뱅킹용)	`POST /v2/api/acnt/reg`	ARS trdNo를 이용한 펌뱅킹+오픈뱅킹 동시 등록
오픈뱅킹 계좌등록	`POST /v2/api/acnt/obreg`	기존 펌뱅킹 고객의 오픈뱅킹 추가 등록

응답 필드	설명
`custAcntKey`	등록된 계좌의 일련번호 (결제 시 사용)
`svcDivCd`	등록된 서비스 구분 (1: 펌뱅킹, 2: 오픈뱅킹, 3: 동시등록)
`fintechUseNo`	오픈뱅킹 사용자 계좌 식별번호
`obPayerNo`	오픈뱅킹 납부자번호

계좌관리 API 문서

계좌 등록 (오픈뱅킹용)

ARS trdNo를 이용한 펌뱅킹+오픈뱅킹 동시 등록

오픈뱅킹 계좌등록

기존 펌뱅킹 고객의 오픈뱅킹 추가 등록

오픈뱅킹 서비스 해지

등록된 오픈뱅킹 서비스 해지

3단계: 결제 (오픈뱅킹용)

등록된 계좌로 결제를 실행합니다. 고객 계좌에서 가맹점의 오픈뱅킹 모계좌로 현금이 이체됩니다.

API	URI	설명
결제 (오픈뱅킹용)	`POST /v2/api/pay/confirm`	오픈뱅킹 출금이체 결제 승인
결제 취소/환불	`POST /v1/api/pay/cancel`	결제 취소 및 환불 처리
송금	`POST /v2/api/pay/rmt`	가맹점 → 고객 계좌 송금

이체 서비스 API 문서

결제 (오픈뱅킹용)

오픈뱅킹 출금이체 결제 승인

결제 취소/환불

결제 취소 및 환불 처리

송금

가맹점 → 고객 계좌 송금

전체 API 목록

간편현금결제(오픈뱅킹)에서 제공하는 전체 API 목록입니다. 모든 API는 POST 메서드를 사용합니다.

NOTE

v2 vs v1 경로 구분

오픈뱅킹 전용 API는 /v2/api/... 경로를 사용합니다. 취소/환불 및 조회 API는 펌뱅킹과 동일한 /v1/api/... 경로를 공유합니다.

계좌관리 (2개)

API 명	URI	비고
계좌등록 (오픈뱅킹용)	`/v2/api/acnt/reg`	ARS trdNo 필요, 펌뱅킹+OB 동시 등록
오픈뱅킹 계좌등록	`/v2/api/acnt/obreg`	기존 펌뱅킹 고객의 OB 추가 등록

이체 서비스 (3개)

API 명	URI	비고
결제 (오픈뱅킹용)	`/v2/api/pay/confirm`
결제 취소/환불	`/v1/api/pay/cancel`	펌뱅킹 공유
송금	`/v2/api/pay/rmt`

자금반환청구 (2개)

API 명	URI
자금반환청구 요청	`/v2/api/fundsReturn/req`
자금반환청구 확인	`/v2/api/fundsReturn/check`

조회 서비스 (3개)

API 명	URI	비고
거래결과조회	`/v1/api/pay/morw`	펌뱅킹 공유
거래내역조회	`/v1/api/pay/translist`	펌뱅킹 공유
계좌목록조회	`/v1/api/acnt/list`	펌뱅킹 공유

계정관리 (1개)

API 명	URI
오픈뱅킹 서비스 해지	`/v2/api/member/withdraw`

요청/응답 기본 구조

모든 API의 요청과 응답은 JSON 형식을 사용합니다.

요청 예시

{
  "hdInfo": "SPAY_RP0W_1.0",
  "mchtId": "가맹점 ID",
  "mchtTrdNo": "ORDER20240101100000",
  "reqDt": "20240101",
  "reqTm": "100000",
  "mchtCustId": "AES암호화된 고객아이디",
  "trdAmt": "AES암호화된 결제금액",
  "pktHash": "SHA256 해쉬값"
}

응답 성공/실패 구분

필드	성공	실패
`outStatCd`	`0021`	`0031`
`outRsltCd`	`0000`	오류 코드

파라미터 검증 실패 시 응답 예시

{
  "outStatCd": "0031",
  "outRsltCd": "ST09",
  "outRsltMsg": "유효하지 않는 요청전문"
}

다음 단계

기능별 상세 문서

계좌관리

계좌 등록, 오픈뱅킹 등록, 서비스 해지

결제/송금

결제 승인, 취소/환불, 송금

자금반환청구

자금반환청구 요청 및 확인

조회 서비스

거래결과, 거래내역, 계좌목록 조회

더 궁금한 내용이 있나요?

FAQ

기술지원이 필요한가요?

코드 샘플

HectoFinancial GitHub