배포 체크리스트

코드에 추가한 API 키가 내 상점의 라이브 키인지 확인하세요. 라이브 키는 앞에 live_가, 테스트 키는 앞에 test_가 붙어 있어요. 왼쪽 메뉴 상단에 선택된 내 상점아이디(MID)도 다시 한번 확인하세요.

코드 레포지토리 등 외부에 시크릿 키가 노출되지 않도록 주의하세요. 시크릿 키는 공개적으로 접근할 수 있거나 버전 관리 시스템으로 접근할 수 있는 코드에 포함되면 안 돼요.

* GitHub에서 제공하는 Gitleaks와 같은 자동화 도구를 사용하면 손쉽게 관리할 수 있어요.

내가 제공하려는 API 버전이 API 키에 잘 적용됐는지 확인하세요. API 버전에 따라 API에 전송할 수 있는 파라미터의 종류, 응답 필드 등이 달라져요. 릴리즈 노트와 코어 API 문서를 참고해서 버전 별 차이를 파악하고 개발자센터에서 버전을 변경하세요.

* 가장 최신 API 버전은 2022-11-16이에요.

카드 결제를 제공하려면 카드사 심사가 필요해요. 카드사 심사는 각 카드사에서 어떤 서비스를 어떻게 판매하는지 확인하고 카드 결제를 허용해주는 과정이에요. 각 카드사의 결제가 모두 잘 동작하는지는 결제수단별 테스트를 참고해서 테스트해보세요.

* 주요 카드사: 국민, 삼성, 신한, 현대, 하나, 농협, 비씨, 롯데

휴대폰 결제를 지원하려면 각 이동 통신사 심사를 통과해야 해요. 각 이동 통신사의 결제가 모두 잘 동작하는지는 결제수단별 테스트를 참고해서 테스트해보세요.

* 주요 이동 통신사: SKT, LGT, KT

상품권 결제를 지원하려면 모든 종류의 상품권 심사를 모두 통과해야 해요. 각 상품권 결제가 모두 잘 동작하는지는 결제수단별 테스트를 참고해서 테스트해보세요.

* 상품권: 문화상품권, 도서문화상품권, 게임문화상품권

주요 카드사 앱과 앱카드, 간편결제 서비스(토스페이, 페이코, 삼성페이, SSG 페이, 카카오페이), 퀵계좌와 뱅크페이 등 제공할 서비스가 전부 잘 동작하는지 테스트 하세요.

라이브 환경이 아닌 테스트 환경에서는 조금 다르게 동작할 수 있어요. 테스트 환경 문서에서 차이를 확인하세요.

다음 흐름이 모두 문제없이 진행되는지 확인하세요. 결제 완료, 즉 승인에 성공하면 HTTP 200 OK와 Payment 객체를 받습니다.

1️⃣ 결제창 실행·결제 UI 그리기

• 결제창이 실행되지 않거나 결제 UI가 나타나지 않는다면 브라우저 개발자 도구로 JavaScript 에러가 있지 않은지, 네트워크 탭에서 호출이 실패하는 요청이 있는지 확인하세요.

2️⃣ 선택한 결제수단(카드사 자체창·앱카드 등) 실행

• 모바일 웹 환경에서 카드사·간편결제사 앱이 없다는 메시지가 돌아오고 더 이상 진행되지 않거나, 모바일 앱 환경에서 자동으로 앱스토어나 플레이스토어로 이동할 때 카드사나 간편결제사 앱이 다운로드 되어 있는지 확인하세요. 모바일 앱에서 웹뷰를 사용한다면 앱 스킴 리스트와 관련 코드가 제대로 추가되어 있는지 확인하세요.

3️⃣ 상점 브라우저 페이지·상점 앱으로 이동

• 결제 결과에 따라 페이지 이동이 되지 않을 때 successUrl과 failUrl이 올바르게 들어가 있는지 확인하세요.

4️⃣ 결제 완료

• 결제 승인 API가 제대로 요청되었는지 확인하세요.

• 결제 완료 후 페이지 이동까지 구현했다면 결제 결과에 따라 성공 혹은 실패 페이지로 이동하는 흐름도 확인하세요.

결제 취소를 한 뒤 Paymen.status가 CANCELED인지, Payment 객체의 cancels 필드에 취소 객체가 추가됐는지 확인하세요.

부분 취소를 여러 번 한 뒤 다음과 같이 Payment.cancels 필드에 취소 객체가 여러 개 돌아왔는지 확인하세요.

SDK와 API 에러를 핸들링 할 수 있는지 확인하세요.

SDK 메서드 응답은 리다이렉트 URL 또는 Promise로 처리할 수 있어요. 사용하는 방법에 따라 에러 핸들링이 제대로 되는지 확인하세요.

API 요청이 정상적으로 처리되지 않으면 응답으로 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다. API 별 에러 코드와 메시지는 에러 코드에서 확인할 수 있어요.

카드 결제의 할부 개월 수와 무이자 여부를 선택했을 때 결제 금액 및 할인 정보가 올바르게 변경됐는지 확인하세요. 토스페이먼츠 SDK 파라미터로 적용했다면 값이 올바르게 적용되었는지 확인하세요.

Payment.cashReceipts.receiptUrl의 주소로 현금영수증이 발행됐는지 확인할 수 있어요.

개발자센터의 웹훅 목록에서 이벤트 타입이 DEPOSIT_CALLBACK인 웹훅이 등록되어 있는지 확인하세요. 웹훅 이벤트를 등록하는 방법은 웹훅 가이드에서 확인할 수 있어요.

개발자센터의 웹훅 목록에 웹훅이 등록되어 있다면 입금됐을 때, 즉 가상계좌 결제 상태가 바뀌었을 때 웹훅 URL로 알림이 발송돼요.

아래와 같은 이벤트 본문이 등록한 웹훅 URL로 전송됐는지 확인하세요. 이벤트 본문의 secret 값이 결제 승인 응답으로 돌아온 Payment 객체의 secret 값과 같은지도 확인하세요. 값이 같다면 토스페이먼츠 서버에서 돌아온 올바른 요청이에요.

현금영수증은 구매자가 가상계좌에 입금한 뒤에 발급돼요. 입금 전에는 현금영수증을 확인할 수 없어요. 테스트 환경에서는 개발자센터의 테스트 거래내역 페이지에서 가장 오른쪽 칼럼의 입금처리・취소 기능으로 실제 입금 동작과 동일하게 테스트할 수 있어요.

입금 후에는 Payment.cashReceipts.receiptUrl의 주소로 현금영수증이 발행됐는지 확인할 수 있어요. 테스트 환경에서 영수증 링크는 생성되지만, 실제 데이터는 제공되지 않습니다.

에스크로 서비스를 계약했는지 확인해 보세요. 배송정보 등록 기능과 구매 확정 기능이 잘 구축되어 있다면 배송이 완료된 후 구매 확정 이메일을 받을 수 있어요. 구매 확정을 선택하면 에스크로를 사용한 결제가 완료돼요. 에스크로 문서를 확인해 보세요.

Chrome, Edge, Firefox, Safari, Whale 환경 각각에서 결제 흐름이 정상적으로 작동하는지 확인하세요. 몇 가지 브라우저만 테스트하면 다른 브라우저에서 발생할 수 있는 문제를 놓칠 수 있어요.

모바일 앱에서 Android와 iOS 환경 각각에 대해 결제 흐름이 정상적으로 이루어지는지, 카드사 앱 및 백신 앱으로의 이동이 잘 이루어지는지 확인하세요.