가상계좌 입금통보

가상계좌 결제수단의 경우 가상계좌번호 채번과 입금이 분리되어 있는 결제 방식입니다.

고객이 채번된 가상계좌번호로 입금하는 경우, 채번 시 전달된 요청파라미터 "vactNotiUrl"로 결제 관련 파라미터가 전달됩니다.

서비스 흐름

가상계좌 결제 흐름

계좌 발급: 결제 승인 시 가상계좌번호가 발급됩니다.
입금 대기: 사용자에게 가상계좌 정보를 안내합니다.
사용자 입금: 사용자가 은행 앱, ATM 등을 통해 직접 입금합니다. (시스템 외부)
입금 통보: 입금이 확인되면 KPN이 vactNotiUrl로 통보합니다.
주문 처리: 가맹점은 통보를 받고 주문을 완료 처리합니다.

입금 통보 상세

입금 통보 프로세스

고객이 채번된 가상계좌번호로 입금하는 경우, 채번 시 전달된 요청 파라미터 vactNotiUrl로 결제 관련 파라미터가 전달됩니다.

응답 필수

가맹점에서 정상적으로 처리된 후 응답 값으로 "ACK=200OKOK" (String) 를 반드시 반환해야 합니다.

다른 결제수단도 웹훅을 받고 싶다면?

결제 결과 통보 서비스를 이용하세요. 단, 해당 서비스 사용 시 응답 형식이 다르므로 별도 연동이 필요합니다.

응답(전달) 파라미터

가상계좌에 입금이 완료되면 다음 파라미터가 vactNotiUrl로 전달됩니다.

POST

가맹점 도메인/{vactNotiUrl}

Base URL가맹점 도메인

Content-Typeapplication/x-www-form-urlencoded

필수

조건부 필수

key	타입	최대크기	필수	설명
`MxID`	String	12		가맹점 ID
	String	2		서비스종류
`Currency`	String	3		통화코드
`MxIssueNO`	String	32		주문번호 (가맹점 자체 주문번호)
`MxIssueDate`	String	14		주문시간 (YYYYMMDDHHMMSS)
`Amount`	String	12		결제금액
	String	8		응답코드
`ReplyMessage`	String	-	-	응답 메세지
`MxHASH256`	String	64		Hash 검증: SHA256(MxID + passKey + MxIssueNO + MxIssueDate + Amount + Currency)
`VactNo`	String	32		가상계좌번호
`CashYN`	String	1	-	현금영수증 발급여부
`CashCardNO`	String	20	-	현금영수증 발급번호
`Remitter`	String	10	-	송금인
`TID`	String	40		거래 ID
`CashAuthNO`	String	12	-	현금영수증 승인번호
	String	1	-	현금영수증 발행구분
`AuthDate`	String	14	-	입금완료 시: 입금 시간 (YYYYMMDDHHMMSS), 입금취소 시: 입금 취소시간 (YYYYMMDDHHMMSS)

중요 사항

입금 통보 URL(vactNotiUrl)은 외부에서 접근 가능한 공개 URL이어야 합니다.
반드시 ACK=200OKOK 응답을 반환해야 합니다.
Hash 검증을 통해 요청의 무결성을 확인하세요.
입금 완료(00003000)와 입금 취소(00003100) 모두 처리해야 합니다.

입금 완료 후 취소 불가

가상계좌는 입금 완료 후 결제 취소가 불가능합니다. 환불이 필요한 경우 환불 서비스를 이용하세요.

입금통보 테스트 API

테스트 환경에서는 실 입금이 불가능합니다. 따라서 개발계에서 입금 시, 통보가 정상적으로 처리되는지 확인하기 위하여, 테스트용 API를 공유드리고 있습니다.

주의사항

해당 API는 실제 입금 처리 로직을 거치지 않습니다. 입금 통보가 나갈 수 있도록 상태 값을 업데이트하는 테스트용 API입니다.

요청 파라미터

POST

https://dev.firstpay.co.kr/api/v1/test/vact/deposit

Base URLhttps://dev.firstpay.co.kr

Content-Typeapplication/json

필수

조건부 필수

key	타입	최대크기	필수	설명
`mxId`	String	12		가맹점 ID
`mxIssueNo`	String	32		주문번호 (유니크한 값 권장)

요청 예시

json

{
  "mxId": "testcorp",
  "mxIssueNo": "testcorpYYYYMMDD00001"
}

응답 파라미터

API 응답은 서비스 API 공통 형식을 따릅니다. data 필드 상세는 아래와 같습니다.

필수

조건부 필수

key	타입	최대크기	설명
`mxId`	String	12	가맹점 ID
`mxIssueNo`	String	32	주문번호
`referenceNo`	String	14	참조번호
`acctNo`	String	32	가상계좌번호

응답 예시

json

{
  "code": "0000",
  "message": "성공",
  "data": {
      "mxId": "testcorp",
      "mxIssueNo": "testcorp_20260304023744",
      "referenceNo": "260304V3000001",
      "acctNo": "0041111222200013"
  },
  "status": "OK",
  "requestId": "c5a089ef-10ba-4a9c-b9d2-aabe166132a3",
  "requestAt": "2026-03-04T14:38:12.508791497",
  "responseAt": "2026-03-04T14:38:13.199389018"
}