Version 2
새로 나온토스페이먼츠 가상계좌 결제창에서 가상계좌를 발급받고, 입금 결과를 웹훅으로 받는 방법입니다.
경남은행, 광주은행, KB국민은행, IBK기업은행, NH농협은행, DGB대구은행, 부산은행, 새마을금고, Sh수협은행, 신한은행, 우리은행, 우체국예금보험, 하나은행에서 가상계좌를 발급받을 수 있습니다.
아니요. 결제 금액만 정확히 입금된다면 주문한 고객과 입금명이 달라도 결제는 정상적으로 처리됩니다.
현금영수증은 고객이 가상계좌에 입금한 뒤에 발급됩니다. 입금 전에는 현금영수증을 확인할 수 없습니다.
개발자센터의 API 키 메뉴에서 API 개별 연동 키를 확인하세요.
토스페이먼츠와 전자결제 계약 전이어도 회원가입하면 나만의 테스트 상점 키를 확인하고 테스트 결제내역, 웹훅 등 기능을 사용할 수 있어요. 로그인한 상태라면 코드의 키 값이 테스트 상점 키입니다. 로그인하지 않아도 문서 테스트 키로 테스트 연동할 수 있어요.
토스페이먼츠와 전자결제를 완료했다면 개발자센터의 API 키 메뉴에서 일반결제로 계약된 상점아이디(MID)를 선택한 다음에 클라이언트 키와 시크릿 키를 확인하세요. 테스트 키와 라이브키의 차이점도 확인하고 연동을 시작하세요.
먼저 주문서 페이지에 결제창을 연동할게요. 아래 코드는 주문서 페이지의 예시에요.
스크립트 태그 또는 패키지 매니저로 토스페이먼츠 SDK를 설치하고, 클라이언트 키로 SDK를 초기화하세요. 다음, payment()
메서드로 결제창 인스턴스를 생성하세요. 아래 코드에서는 payment
라는 인스턴스를 생성했어요.
그럼 이제 결제창을 띄울 준비가 됐어요. payment.requestPayment()
메서드를 호출하면 결제 요청이 시작되고, 결제창이 열려요. 메서드의 파라미터로 결제수단(VIRTUAL_ACCOUNT
), 주문번호, 결제금액, successUrl
, failUrl
등 필요한 정보를 설정하세요. 그리고 주문서의 '결제하기' 버튼에 결제 요청 메서드를 이벤트로 등록해주세요.
모바일 환경에서는 iframe이나 frame 위에서 결제창을 호출하면 안 돼요. 모바일 환경에서는 결제창을 호출할 때 항상 페이지가 이동하고, iframe 위에서는 특정 결제수단이 정상적으로 작동하지 않아요.
위 코드를 실행한 다음에 '결제하기' 버튼을 누르면 아래와 같은 결제창이 열려요. 테스트하고 싶은 은행을 선택하고 결제 정보를 입력하세요. 테스트 클라이언트 키를 사용했다면 실제로 결제되지 않으니 안심하세요.
결제창에서 구매자의 결제수단을 인증하는데요. 인증 결과는 리다이렉트 URL로 확인할 수 있어요.
결제 인증이 성공했다면 성공 리다이렉트 URL(successUrl
)의 쿼리 파라미터로 결제 정보를 확인하고 검증해주세요. 인증이 실패했다면 이동한 실패 리다이렉트 URL(failUrl
)의 쿼리 파라미터로 에러를 확인해주세요.
결제 정보가 모두 인증됐다면, successUrl
로 이동해요. 해당 URL에 아래 세 가지 쿼리 파라미터가 추가돼요.
쿼리 파라미터의 amount
값과 requestPayment()
의 amount
파라미터 값이 같은지 반드시 확인하세요. 클라이언트에서 결제 금액을 조작하는 행위를 방지할 수 있습니다. 만약 값이 다르다면 결제를 취소하고 구매자에게 알려주세요.
서버에 paymentKey
, amount
, orderId
값을 저장하세요. paymentKey
는 토스페이먼츠에서 각 주문에 발급하는 고유 키 값이에요. 결제 승인, 취소, 조회 등에 사용되기 때문에 꼭 저장해주세요.
만약에 결제 정보가 틀려서 결제 인증이 실패했다면, failUrl
로 이동해요. 해당 URL에는 아래 세 가지 쿼리 파라미터가 추가돼요. 에러 코드와 메시지를 확인해서 구매자에게 적절한 안내 메시지를 보여주세요.
오류원인
구매자에 의해 결제가 취소되면 PAY_PROCESS_CANCELED
에러가 발생합니다. 결제 과정이 중단된 것이라서 failUrl
로 orderId
가 전달되지 않아요.
오류원인
결제가 실패하면 PAY_PROCESS_ABORTED
에러가 발생합니다.
해결 방법
-
오류 메시지를 확인하세요. 계약 관련 오류는 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.
-
기타 오류는 토스페이먼츠 실시간 기술지원 채널에서 문의해주세요.
오류원인
구매자가 입력한 카드 정보에 문제가 있다면 REJECT_CARD_COMPANY
에러가 발생합니다.
해결 방법
- 오류 메시지를 확인하고 구매자에게 안내를 해주세요.
마지막 단계로 결제 승인 API를 호출하세요. 첫 단계에서 확인한 API 개별 연동 키 > 시크릿 키를 사용해요.
시크릿 키와 :
을 base64로 인코딩해서 Basic 인증 헤더를 아래와 같이 만들어주세요. :
을 빠트리지 않도록 주의하세요. 비밀번호가 없다는 것을 알리기 위해 시크릿 키 뒤에 콜론을 추가합니다.
시크릿 키는 클라이언트, GitHub 등 외부에 노출되면 안 됩니다.
시크릿 키 뒤에 :
을 추가하고 base64로 인코딩합니다. :
을 빠트리지 않도록 주의하세요.
아래 명령어를 터미널에서 실행하면 인코딩된 값을 얻을 수 있습니다.
결제 승인 API의 헤더에 인코딩한 시크릿 키 인증 헤더를 추가하세요. 요청 본문 파라미터에는 앞 단계에서 리다이렉트 URL로 받은 paymentKey
, orderId
, amount
를 넣어주세요. 아래 예제 코드에는 내 테스트 결제의 paymentKey
값을 넣어 실행해주세요.
결제 승인 API의 결과로 HTTP 200 OK
와 함께 Payment 객체가 돌아오면 가상계좌가 정상적으로 발급됐어요.
Payment 객체에 구매자가 선택한 결제수단 정보가 있는지 확인하세요. 가상계좌 결제는 아래와 같이 virtualAccount
필드에 결제 정보를 확인할 수 있어요.
응답으로 받은 Payment 객체가 아래 예시와 다르다면 API 버전을 확인하세요. 개발자센터의 API 키 메뉴에서 설정된 API 버전을 확인하고 변경할 수 있어요. API 버전 업데이트 사항은 릴리즈 노트에서 확인할 수 있습니다.
결제 승인에 실패하면 HTTP 4XX
또는 5XX
코드와 에러 객체를 받습니다. 결제 승인의 전체 오류 목록은 에러 코드를 참고하세요. 테스트 환경에서 결제 승인 실패를 재현해보고 싶다면 토스페이먼츠 API 테스트 헤더를 사용해보세요.
오류원인
결제 승인에서 요청에 문제가 있으면 NOT_FOUND_PAYMENT_SESSION
에러가 발생합니다.
해결 방법
-
결제 요청이 완료된 이후 10분 이내에 결제를 승인해야 됩니다. 10분이 지나면 결제 데이터가 유실되어 승인이 불가합니다.
-
결제 요청했을 때 돌려받은
paymentKey
와 결제 승인에 사용한paymentKey
가 같은 값인지 확인하세요. -
결제 요청에 사용한 클라이언트 키와 결제 승인에 사용한 시크릿 키가 매칭된 키값인지 확인하세요.
오류원인
카드사에서 해당 카드를 거절했을 때 REJECT_CARD_COMPANY
에러가 발생합니다. 원인은 비밀번호 오류, 한도 초과, 포인트 부족 등 다양합니다.
해결 방법
에러 메시지를 확인해서 원인을 파악하고 고객에게 올바른 안내를 해주세요.
오류원인
API 키값 또는 주문번호가 최초 요청한 값과 다르면 FORBIDDEN_REQUEST
가 발생합니다.
해결 방법
-
결제 요청에 사용한 클라이언트 키와 API 호출에 사용한 시크릿 키가 매칭된 키값인지 확인하세요.
-
orderId
,paymentKey
값이 최초 결제 요청한 값과 같은지 확인하세요.
가상계좌는 다른 결제수단과 다르게 결제 승인 API를 호출하면 가상계좌가 발급된 것이지, 결제가 완료된 게 아닙니다. 결제의 상태를 나타내는 Payment 객체의 status
필드도 WAITING_FOR_DEPOSIT
이고요. 고객이 입금한 시점에 결제가 완료되고 Payment 객체의 상태가 DONE
으로 바뀌어요.
직접 테스트 입금을 하고 비동기적으로 바뀌는 결제 상태는 웹훅으로 확인하세요. 금액이 입금되거나 결제가 취소되는 등 가상계좌 결제 상태가 바뀌면 토스페이먼츠에서 웹훅을 발송해요.
테스트 환경에서 발급된 계좌로 직접 입금할 수 없지만, 개발자센터의 테스트 거래내역 페이지에서 가장 오른쪽 컬럼의 입금처리・취소를 선택해보세요. 실제 동작과 동일하게 테스트 할 수 있습니다.
- 개발자센터의 웹훅 메뉴에서
DEPOSIT_CALLBACK
웹훅을 등록하세요. - 입금이 완료되면 결제 상태가
DONE
으로 바뀌고 아래와 같은 이벤트 본문이 등록한 웹훅 URL로 전송됩니다. - 이벤트 본문의
secret
값이 결제 승인 응답으로 돌아온 Payment 객체의secret
값과 같은지 확인하세요. 값이 같다면 토스페이먼츠 서버에서 돌아온 올바른 요청입니다.
가상계좌 발급 요청이 정상적으로 승인된 응답에만 secret
값이 있고, 이후에 결제 조회를 할 때는 보안 이유로 secret
값이 null
로 돌아옵니다.