토스페이먼츠에 가장 많이 물어보는 질문 세 가지

2023년 9월 6일 ・ 읽는 시간 8분

이번 포스트에서는 토스페이먼츠를 연동하는 개발자가 가장 많이 물어보는 질문 세 가지를 담아봤어요. 결제 연동 단계에 따라 하나씩 알아볼게요.

클라이언트 키와 시크릿 키는 각각 SDK와 API를 사용하기 위한 키예요. 한 세트로 써야 하죠. 클라이언트 키는 SDK를, 시크릿 키는 API를 사용할 때 사용자를 인증하는 값이에요. 중요한 건, 결제 연동할 때 A세트의 클라이언트 키로 결제 요청을 했다면, 결제 승인 API를 호출할 때도 A세트의 시크릿 키를 사용해야 해요. 만약 B세트의 키를 A세트의 키와 조합해서 쓰면 오류가 나요. 두 키는 항상 ‘세트’로 묶여 있고, 쌍을 잘 맞춰줘야 한다는 걸 기억해 주세요.

• 매칭되지 않은 키를 사용하거나 테스트 또는 라이브 키를 섞어 사용하면 INVALID_API_KEY 오류가 발생해요.

키 세트는 상점아이디(MID) 별로 발급이 되는데요, 계약을 하지 않아도 회원가입만 하면 “개발자용 테스트상점”이라는 이름으로 다음과 같이 테스트용 키가 발급돼요. “개발자용 테스트상점”에는 테스트용 키만 있어요.

계약을 하고 나면 내 상점아이디(MID)에 테스트, 라이브 키가 발급돼요. 테스트 키는 실제로 결제가 나지 않아 연동 과정에서 사용하면 유용해요. 라이브 키는 라이브 배포할 때 사용해 주세요.

만약 일반 결제가 아닌 키인이나 빌링, 브랜드페이 등을 추가로 계약하면 해당 결제 서비스에 대한 상점아이디와 키 세트가 새로 발급돼요. 서로 다른 결제수단이라고 판단하기 때문이에요. 이렇게 여러 결제 서비스를 계약했을 때 키 조합이 섞이면 오류가 나니 조심해주세요.

SDK 없이 API로만 연동한다면, 선택한 결제 서비스의 시크릿 키만 사용하면 돼요. 개발자센터에서 내 API 키의 버전을 확인하고, 쉽게 바꿀 수 있어요.

successUrl은 ‘최종 결제’가 성공해서 이동하는 주소가 아니에요. 결제 요청 결과를 확인하기 위한 URL이에요.

전체 결제 과정을 간단히 알아볼게요. 결제 과정은 요청-인증-승인 세 가지로 이루어져 있어요.

1. 요청은 말 그대로 구매자가 “결제하기” 버튼을 눌러서 결제를 요청하는 거예요.
2. 결제 요청 후에는 인증이 이어져요. 인증은 카드사에서 해요. 요청받은 결제 정보, 즉 고객의 신용카드 정보와 결제 금액을 확인해서 이 거래가 유효하며 결제를 허용해도 되는지 확인하죠. 그 결과가 리다이렉트 URL로 돌아와요.
3. 마지막으로 승인은 이렇게 인증된 결제를 카드사에 승인해달라고 요청하는 과정이에요. 이렇게 승인까지 성공으로 끝나야 최종 결제를 마친 거예요.

토스페이먼츠 결제 요청 메서드 requestPayment()의 파라미터에는 successUrl, failUrl이 있어요. 두 파라미터를 리다이렉트 URL 라고 부르는데요. 리다이렉트 URL은 결제 요청에 성공하거나 실패한 후에 사용자가 돌아갈 수 있는 웹사이트의 URL을 뜻해요. 결제 연동 과정에서 요청 결과를 확인할 때 사용하죠.

결제 요청에 성공하면 리다이렉트 URL에 돌아온 값들로 최종 결제 승인 API를 호출할 수 있어요. 즉, successUrl을 통해 결제 요청 결과를 알려주고, 그 결과로 결제 승인까지 할 수 있는 중간 역할을 하는 거죠.

successUrl로 이동한 뒤 10분 안에 최종 결제 승인 API까지 호출해야 결제가 완료되는데요. ‘결제를 끝까지 다 했는데, 테스트 결제내역에 결제상태가 ‘완료’가 아닌 ‘만료’로 뜬다’면 successUrl 까지 이동한 것으로 결제가 완료됐다고 생각하고 결제 승인 API를 호출하지 않았기 때문이에요.

결제에 승인 말고 요청이나 인증은 뭔지 복잡하죠? 결제 흐름을 좀 더 자세히 알고 싶다면 결제 흐름 이해하기를 참고하세요.

앞서 설명한 테스트 키로 결제했다면 실제로 결제가 일어나지 않아요. 그래서 내 카드 등으로 결제 기록을 찾을 수 없는데요. 이런 테스트 결제 기록은 토스페이먼츠는 개발자센터의 테스트 결제내역에서 확인할 수 있어요. 날짜 별, 결제수단 별로 결제내역을 조회할 수 있어요. 주문 일시, 결제 일시, 주문 번호, 결제 상태, 구매자명, 결제액 등 자세한 정보를 확인해보세요.

취소와 관련된 기록 중 부분 취소 금액이나 취소일시는 제공하지 않고 있으니 유의해주세요. 취소 관련 기록이 궁금하다면 결제 조회 API를 호출해서 Payment 객체의 cancels 필드를 확인해주세요.

가상계좌 결제를 테스트 했다면 가장 오른쪽 컬럼에서 결제를 취소하거나 가상계좌 입금을 처리할 수 있어요.

• 취소를 선택하면 결제 취소 API를 호출하지 않고 테스트 결제를 취소할 수 있어요.
• 입금처리를 선택하면 가상계좌에 입금되는 액션을 테스트할 수 있어요.

라이브로 결제한 기록은 상점관리자에서 확인할 수 있어요.

자주 묻는 질문에서 더 많은 질문과 답을 확인해보세요.

Writer 한주연 Graphic 이은호, 이나눔