FORM-SUBMIT 연동 API
HTML Form을 직접 생성하여 결제창을 호출하는 방법을 설명합니다. SDK 의존성 없이 연동할 수 있습니다.
기본 구조
<form id="paymentForm" method="POST" action="{BASE_URL}{ACTION_PATH}" target="{TARGET}">
<input type="hidden" name="mchtId" value="상점아이디" />
<input type="hidden" name="method" value="결제수단" />
<!-- ... 결제수단별 파라미터 -->
</form>
<script>
document.getElementById('paymentForm').submit();
</script>
| 항목 | 테스트 환경 | 운영 환경 |
|---|---|---|
| BASE_URL | https://tbnpg.settlebank.co.kr | https://npg.settlebank.co.kr |
POST 방식 필수
Form의 method는 반드시 POST입니다. GET 방식은 지원하지 않습니다.
결제수단별 Action URL
| 결제수단 | method | Action URL |
|---|---|---|
| 신용카드 | card | /card/main.do |
| 신용카드 (직호출) | card | /card/cardDirect.do |
| 신용카드 (해외) | card | /card/abroad/main.do |
| 계좌이체 | bank | /bank/main.do |
| 가상계좌 | vbank | /vbank/main.do |
| 가상계좌 010 | vbank010 | /vbank010/main.do |
| 휴대폰결제 | mobile | /mobile/main.do |
| 틴캐시 | teencash | /gift/teenCash/main.do |
| 컬쳐캐쉬 | culturecash | /gift/cultureCash/main.do |
| 스마트문상 | smartcash | /gift/smartCash/main.do |
| 북앤라이프 | booknlife | /gift/booknlife/main.do |
| 티머니 | tmoney | /tmoney/main.do |
| 포인트 | point | /point/main.do |
| 간편결제 | corp | /corp/main.do |
UI 타입별 구현
팝업 방식
function openPaymentPopup() {
const width = 430;
const height = 660;
const left = (screen.width - width) / 2;
const top = (screen.height - height) / 2;
const popup = window.open('', 'paymentPopup',
`width=${width},height=${height},left=${left},top=${top},scrollbars=yes`
);
if (!popup) {
alert('팝업이 차단되었습니다. 팝업 차단을 해제해주세요.');
return;
}
document.getElementById('paymentForm').target = 'paymentPopup';
document.getElementById('paymentForm').submit();
}
현재 창 방식
<form id="paymentForm" method="POST"
action="https://tbnpg.settlebank.co.kr/card/main.do"
target="_self">
<!-- 파라미터 -->
</form>
- 현재 창에서 결제창으로 이동
- 결제 완료 후
nextUrl로 리다이렉트
새 탭 방식
<form id="paymentForm" method="POST"
action="https://tbnpg.settlebank.co.kr/card/main.do"
target="_blank">
<!-- 파라미터 -->
</form>
- 새 탭에서 결제창 표시
- 브라우저 기본 동작 사용
SDK와의 차이점
| 항목 | SDK | FORM-SUBMIT |
|---|---|---|
| 스크립트 로드 | 필요 | 불필요 |
| UI 타입 | popup, iframe, self, blank | popup, self, blank |
| 콜백 함수 | X | X |
| Action URL | 자동 처리 | 직접 지정 |
| Form 생성 | 자동 | 직접 생성 |
| 팝업 처리 | 자동 | 직접 구현 |
NOTE
결제 결과 수신
SDK와 FORM 방식 모두 결제 결과는 notiUrl(Server-to-Server)로 수신합니다. 실제 주문 처리는 반드시 notiUrl에서 수행해야 합니다.
서버 사이드 처리
FORM-SUBMIT 방식도 SDK와 동일하게 백엔드에서 거래금액 암호화(AES-256)와 위변조 방지 해시(SHA-256)를 생성해야 합니다.
NOTE
암호화 및 해시 생성 규칙
AES-256 암호화 규칙, SHA-256 해시 생성 순서, 테스트 키 정보는 연동 준비하기 문서를 참고하세요. 연동 준비하기 — 암복호화 및 위변조 방지
보안 주의
암호화 키와 해시 키는 반드시 서버에서만 사용해야 합니다. 클라이언트에 노출하면 안 됩니다.
결제 결과 처리
FORM-SUBMIT 방식에서 결제 완료 후 다음 URL로 리다이렉트됩니다.
결과 수신 방식
| URL | 설명 | 전달 방식 |
|---|---|---|
nextUrl | 결제 성공 시 | POST 방식으로 결과 파라미터 전달 |
cancUrl | 결제 실패/취소 시 | POST 방식으로 결과 파라미터 전달 |
notiUrl | 결제 완료 시 (서버 통신) | POST 방식으로 Server-to-Server 전송 |
실제 주문 처리는 notiUrl에서
nextUrl은 브라우저를 통해 전달되므로 네트워크 오류로 누락될 수 있습니다. 실제 주문 처리(재고 차감, DB 업데이트)는 반드시 notiUrl에서 수행해야 합니다.
응답 파라미터
결제 완료 후 nextUrl로 전달되는 주요 파라미터입니다.
| 파라미터 | 타입 | 설명 |
|---|---|---|
outStatCd | AN(4) | 거래상태 코드 |
outRsltCd | AN(4) | 상세 결과 코드 (실패 시) |
outRsltMsg | AHN(200) | 결과 메시지 |
trdNo | AN(40) | 헥토파이낸셜 거래번호 |
mchtTrdNo | AN(100) | 상점 주문번호 |
trdAmt | N(12) | 거래금액 |
method | A(10) | 결제수단 |
주요 거래상태 코드: 0021 (성공), 0031 (실패), 0041 (대기), 0051 (진행중)
자세한 결과 처리 방법은 노티(notiUrl) 연동 가이드를 참고하세요.
결제수단별 파라미터
FORM-SUBMIT 연동 방법은 모든 결제수단에서 동일합니다. 각 결제수단별 상세 파라미터와 Action URL은 결제창 연동 문서를 참고하세요.
NOTE
결제수단별 파라미터 및 Action URL
신용카드, 계좌이체, 가상계좌, 휴대폰결제 등 16개 결제수단의 상세 파라미터와 Action URL은 결제창 연동 문서에서 확인하세요. 결제창 연동 — 결제수단별 파라미터
