자주 묻는 질문

토스페이먼츠 SDK는 다양한 개발 언어로 사용할 수 있어요. 코드 샘플로 더 자세히 알아보세요.

아니요, 테스트 환경에서 발급된 가상계좌는 앞에 'X'가 붙고 실제로 입금할 수 없는 계좌입니다. 대신 입금을 한 것처럼 동작하는 입금・취소 이벤트를 제공합니다.

1. 개발자센터의 테스트 결제내역 메뉴로 이동하세요.

2. 가상계좌 API를 호출한 내역을 확인하세요. 날짜 별, 결제수단 별로 결제내역을 조회할 수 있어요.

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

아니요, 테스트 환경은 토스페이, 네이버페이, 카카오페이 결제만 지원해요. 토스페이, 네이버페이만 모든 테스트 키로 연동할 수 있습니다. 카카오페이는 계약 후 발급받는 내 테스트 키로 연동할 수 있습니다. 페이코 등 기타 간편결제는 라이브 키로 테스트하세요.

live_ck로 시작하는 라이브 클라이언트 키와 live_sk로 시작하는 라이브 시크릿 키를 이용했는지 확인해주세요.

9개의 주요 카드사(신한, 삼성, 현대, 롯데, KB국민, NH농협, 하나, 비씨, 우리)에서 카드사 심사를 마쳐야 합니다. 카드사 심사는 카드사에서 전자결제 심사를 신청한 온라인 쇼핑몰을 심사하여 소비자를 보호하기 위한 과정입니다. 카드사가 각 사 정책에 따라 진행합니다.

카드사 심사 때는 실제 판매가 이뤄지는 쇼핑몰 사이트, 앱에서 상품의 형태, 정기결제 상품이 있는지, 결제창은 잘 열리는지 등을 확인합니다. 또, 테스트키를 이용해 결제창을 연동해 둔 것을 확인합니다. 카드사 심사에 대한 더 자세한 내용이 궁금하다면 토스비즈니스피드의 전자결제 심사, 한 번에 통과하는 방법을 참고하세요.

토스페이먼츠에 카드사 심사를 요청한 뒤 7-10일 후 심사가 완료되었다면 라이브 환경에서 결제를 할 수 있습니다. 심사 현황은 상점관리자 > 이용정보 메뉴에서 확인할 수 있습니다. 모든 카드사 심사가 끝났다면 토스페이먼츠에서 카드사 심사 완료 소식을 알림톡으로 발송해드리고 있습니다. 내 상점의 카드사 심사 과정이 더 궁금하다면 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.

네, 테스트 환경에서 특정 에러를 재현하고 싶다면 토스페이먼츠 API 테스트 헤더를 사용하세요.

TossPayments-Test-Code: {TEST_CODE}

{TEST_CODE} 자리에 재현하고 싶은 에러 코드를 넣고 API를 실행하세요. test_ 로 시작하는 테스트 API 키를 사용해주세요. 라이브 환경에서는 테스트 코드 헤더가 무시됩니다.

예를 들어, 카드 번호 결제 API에 잘못된 유효기간을 넣었을 때 돌아오는 응답을 보고 싶다면 아래와 같이 INVALID_CARD_EXPIRATION를 테스트 헤더에 추가하세요.

curl --request POST \
  --url https://api.tosspayments.com/v1/payments/key-in \
  --header 'Authorization: ' \
  --header 'Content-Type: application/json' \
  --header 'TossPayments-Test-Code: INVALID_CARD_EXPIRATION' \

권장하는 웹뷰 방식으로 구현했다면 별도의 대응은 필요하지 않습니다.

구현상 위와 같은 방식을 사용하기 어렵다면 아래와 같이 AndroidManifest.xml에 패키지 명을 추가해야 합니다.

<manifest package="com.example.game">
    <queries>
        <package android:name="com.example.store" />
        <package android:name="com.example.services" />
    </queries>
    ...
</manifest>

예외적으로 모든 앱을 찾거나(query) 실행해야 하면 아래와 같이 QUERY_ALL_PACKAGES 권한을 사용해서 모든 패키지를 허용할 수 있습니다.

<manifest>
	<uses-permission android:name="android.permission.QUERY_ALL_PACKAGES" />
</manifest>

더 궁금한 점이 있다면 토스페이먼츠 결제연동팀 이메일이나 디스코드로 문의해주세요.

하나의 상점아이디(MID)에 매칭되어 발급된 클라이언트 키, 시크릿 키를 함께 사용하세요. 매칭되지 않은 키를 사용하거나 테스트 또는 라이브 키를 섞어 사용하면 INVALID_API_KEY 오류가 내려옵니다.

API 키는 토스페이먼츠에 로그인한 뒤에 개발자센터의 API 키 메뉴에서 확인할 수 있어요.

로그인을 하지 않고 문서에 있는 테스트 키를 결제 연동에 사용할 수 있지만, 결제 내역을 확인할 수 없어요.

라이브 API 키는 토스페이먼츠와 계약을 완료하면 발급돼요. 토스페이먼츠에 로그인한 뒤에 내 상점 이름을 클릭하고 '개발 정보' 버튼을 누르면 라이브 API 키를 확인할 수 있어요.

개발자센터에서 API 응답 버전을 직접 변경할 수 있습니다. 버전에 따라 요청 파라미터, 응답 내용이 변경될 수 있습니다. 릴리즈 노트에서 각 버전에서 변경된 필드 정보를 확인해 보고, 필요한 버전을 선택해 사용하세요.

API 문서 상단 왼쪽에 API 버전을 선택할 수 있어요. 문서에서 보여주는 모든 응답 예시는 가장 최신 버전을 기준으로 작성되어 있습니다. 더 자세한 내용은 API 버전 정책을 참고하세요.

오류원인

API 키를 잘못 입력하면 UNAUTHORIZED_KEY 에러가 발생합니다.

해결 방법

• 클라이언트 키와 매칭된 시크릿 키를 사용하고 있는지 확인하세요. API 키는 토스페이먼츠에 로그인한 뒤에 개발자센터의 API 키 메뉴에서 확인할 수 있어요.

• 시크릿 키 인코딩을 다시 확인하세요. 시크릿 키 뒤에 :을 추가하고 base64로 인코딩해서 사용해야 됩니다.

같은 paymentKey로 반복적인 요청을 보내면 DUPLICATED_REQUEST 에러가 발생합니다.

특정 결제수단 및 방법은 별도의 상점아이디(MID)가 발급돼요. 에를 들어, PayPal은 국내 일반결제와 수수료 및 정산 과정이 다르기 때문에 각 결제수단은 따로 상점아이디(MID)가 발급돼요. 토스페이먼츠와 계약된 결제수단은 상점관리자 > 계약・운영 > 이용정보 > 상점아이디(MID) 선택 > 결제・부가서비스 탭에서 확인할 수 있어요.

연동하는 결제수단이 계약된 상점아이디의 API 키를 사용하세요. 개발자센터 메뉴 상단에서 상점아이디(MID)를 선택할 수 있어요.

만약 사용하고 싶은 결제수단이 계약된 상태가 아니라면, 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.

SDK를 추가 및 초기화했는지 확인하세요. requestPayment()의 필수 파라미터가 모두 포함되어 있고 각 파라미터의 데이터 타입이 올바른지 확인하세요.

requestPayment()의 successUrl, failUrl 파라미터가 잘 설정됐는지 확인하세요. 잘 설정됐다면 결제 승인 API가 제대로 요청되었는지 확인하세요.

결제 승인, 취소 및 조회 API 응답에서 매출 전표나 현금영수증을 볼 수 있는 페이지 주소를 제공합니다. 카드 매출 전표는 receipt.url을, 현금영수증은 cashReceipt.receiptUrl 필드를 참고하세요.

테스트 환경에서는 링크가 제공되지만 실제로 영수증이 발급되지 않아요.

결제가 완료된 이후에 따로 현금영수증 발급 API를 사용했기 때문이에요. 결제 요청과 현금영수증 요청에 같은 orderId를 사용해도 현금영수증 정보는 해당 결제의 Payment 객체에 동기화되지 않아요. API로 발급된 현금영수증의 정보는 현금영수증 조회 API로 확인하세요.

애플페이는 iPhone 및 Mac Safari 에서만 노출돼요.

식스샵에서 결제위젯을 제한적으로 사용할 수 있어요. 자세한 내용은 식스샵으로 문의해주세요. 다른 호스팅사에서는 결제위젯을 지원하지 않아요.

네, 결제위젯을 사용하면 한 번의 연동으로 네이버페이, 카카오페이 등 모든 간편결제 수단을 구매자에게 제공할 수 있어요. 네이버페이는 모든 테스트 키로 연동할 수 있고, 카카오페이는 계약 후 발급받는 내 테스트 키로 연동할 수 있습니다.

결제위젯 연동이 더 쉽고, 공수도 적게 들어요. 결제위젯은 한번에 모든 결제수단(카드, 간편결제, 가상계좌 등)을 연동할 수 있어요. 서버 개발에 드는 공수는 결제창과 비슷하지만, 클라이언트 개발 공수와 운영 비용은 결제위젯이 훨씬 적어요. 결제위젯을 쓰면, 코드 없이 어드민에서 다양한 커스텀(UI 디자인, 프로모션, 결제수단별 기능)까지 할 수 있어서 운영이 편해져요.

계약 전에 제공되는 '개발자용 테스트상점' 키로 결제위젯을 연동하면 발생하는 에러입니다. 계약 전에는 아래 테스트 키로 결제위젯을 연동하세요. 커스터마이징 기능은 어드민 체험하기에서 직접해 볼 수 있지만 아래 테스트 키와 연동되지 않습니다.

결제위젯 SDK는 Web, Native Android, Native iOS, React Native, Flutter를 지원하고 있어요.

네. ready 이벤트로 결제 UI 렌더링 완료 이벤트를 받을 수 있습니다.

const paymentMethodWidget = paymentWidget.renderPaymentMethods(
  "#payment-method",
  { value: 50000 },
  { variantKey: "DEFAULT" }
);

paymentMethods.on('ready', () => {
  // 결제 버튼 활성화
})

네. getSelectedPaymentMethod()를 호출해서 고객이 선택한 결제수단을 확인할 수 있습니다.

토스페이먼츠에서 발급하지 않은 클라이언트 키 혹은 시크릿 키를 사용했을 때 발생합니다. 개발자센터에 들어가서 키 값을 다시 확인하고 시크릿 키 인증을 올바르게 했는지 확인해주세요.

결제위젯을 생성하지 않은 클라이언트 키로 연동을 시도하면 발생합니다. 상점관리자에서 결제위젯 UI를 추가하세요.

발급된 빌링키를 삭제하는 API는 제공되지 않습니다. 발급된 빌링키가 더 이상 필요하지 않으면 데이터베이스에서 삭제하고 더 이상 사용하지 않으면 됩니다.

혹시 누군가가 빌링키 정보를 알고 있더라도 빌링키와 매핑된 customerKey를 모른다면 결제가 불가능합니다. 빌링키를 사용한 결제는 빌링키를 발급할 때 같이 전달된 customerKey와 매핑이 되어있기 때문에, 결제 요청을 할 때 빌링키와 customerKey가 같이 전달되어야 결제가 진행됩니다.

아니요, 빌링키는 유효기간이 없어요. 등록한 카드가 유효하면 빌링키도 계속 유효합니다.

테스트 환경에서는 카드 번호의 앞 여섯 자리(BIN 번호)만 유효해도 자동결제가 등록됩니다. 라이브 환경에서는 전체 카드 번호가 유효해야 등록됩니다.

별도로 제공하지 않습니다. 자동결제에 등록할 카드의 유효성 여부는 빌링키 발급을 요청할 때 카드사를 통해 확인합니다. 만약 유효하지 않다면 에러를 응답합니다. 카드 잔고 부족이나 한도 초과는 결제 승인을 요청할 때 카드사를 통해 확인합니다.

새로운 카드 정보로 빌링키를 다시 발급받으세요. 별도로 빌링키를 갱신하는 과정은 없습니다.

다음 결제일에 구독을 취소한 고객의 빌링키, 고객키로 카드 자동결제 승인 API를 호출하지 않으면 됩니다.

카드 자동결제 승인 API를 호출할 때 amount 파라미터를 변경된 결제 금액으로 설정하면 됩니다.

카드 자동결제 승인 API를 호출하는 주기를 변경해주세요.

먼저 웹훅 URL을 정확하게 입력했는지 다시 한번 확인해주세요.

상점에서 사용하고 있는 네트워크의 방화벽 정책에 따라 웹훅이 정상적으로 도착하지 않을 수 있습니다. 방화벽 설정에서 웹훅 URL에 지정된 포트 번호로 인바운드 트래픽(Inbound Traffic)을 허용해주세요. 자세한 내용은 방화벽 가이드에서 확인해보세요. 또한, 상점 서버의 HTTP 클라이언트 환경이 TLS 1.2 이상을 지원하는지 확인해주세요.

토스페이먼츠 웹훅은 JSON 포맷을 사용합니다. 상점 서버에서 JSON 요청을 처리할 수 있는지 확인해주세요.

가상계좌가 만료되어도 따로 웹훅을 보내고 있지 않습니다.

가상계좌 웹훅은 가상계좌에 고객이 입금했거나 은행이나 계좌 문제로 입금 금액이 취소되거나, 입금 후 주문 취소로 인해 입금이 취소된 것과 같이 결제 상태가 변경되면 전송됩니다.

만료 시간은 가상계좌가 발급되는 시점에 정해지고, 이후에는 수정할 수 없습니다.

가상계좌 만료 이후에 주문을 취소하려면 가상계좌를 발급할 때 설정한 만료시간을 저장해 두었다가 그 시간까지 입금이 되지 않으면 자동으로 주문 취소를 할 수 있도록 작업을 추가하면 됩니다.

더 자세한 내용은 가상계좌 웹훅 연동 가이드를 참고하세요.

웹훅을 받은 뒤 10 초 이내로 HTTP 2xx 응답을 보내주세요. 안 그러면 토스페이먼츠에서 웹훅 전송이 실패한 걸로 판단하고 최대 7회까지 웹훅을 재전송해요.

토스페이먼츠 개발자센터에서 이력을 확인하고 싶은 웹훅을 선택하세요. 웹훅 성공, 전송 중, 실패 이력이 나옵니다. 이벤트 발생 시간을 누르면 웹훅 데이터도 확인할 수 있어요.

301 상태 코드는 영구 이동(Moved Permanently)를 뜻합니다. 웹훅 주소로 등록한 URL에 변경이 있는지 확인 부탁드립니다. 웹훅 URL에 리다이렉트가 없는지 확인해주세요.

라이브 환경에서 실제로 지급 가능한 정산금액을 실제 계좌로 입금해서 테스트해주세요. 테스트 환경에서는 실제 지급이 불가능하기 때문에 웹훅도 테스트할 수 없어요.

모바일 기기에 카드사 앱이 잘 설치됐는지 확인하세요. 웹뷰를 사용하고 있다면 앱스킴 리스트와 관련 코드가 맞게 추가되어 있는지 확인하세요.

appScheme 파라미터에 내 상점의 앱스킴을 등록해주세요. 페이북 앱에서 결제가 완료되면 정상적으로 내 상점 앱으로 다시 이동합니다.

네, 토스페이먼츠 결제위젯은 Flutter SDK를 제공합니다.

오류원인

결제 승인에서 요청에 문제가 있으면 NOT_FOUND_PAYMENT_SESSION 에러가 발생합니다.

해결 방법

• 결제 요청이 완료된 이후 10분 이내에 결제를 승인해야 됩니다. 10분이 지나면 결제 데이터가 유실되어 승인이 불가합니다.

• 결제 요청했을 때 사용한 paymentKey와 결제 승인에 사용한 paymentKey가 같은 값인지 확인하세요.

• 결제 요청에 사용한 클라이언트 키와 결제 승인에 사용한 시크릿 키가 매칭된 키값인지 확인하세요.

오류원인

상점 계약 또는 원천사 문제가 있을 때 PAY_PROCESS_ABORTED 에러가 발생합니다.

해결 방법

• 토스페이먼츠와 계약, 카드사 심사 등 모든 계약 과정이 완료됐는지 확인하세요. 계약 상태는 1544-7772로 문의해주세요.

• 계약이 모두 완료됐어도 테스트 키와 라이브 키가 동기화 안 되어있을 수도 있습니다. 라이브 키로 테스트하거나 디스코드에서 확인 요청해주세요.

• 테스트 환경에서 간편결제는 토스페이, 네이버페이, 카카오페이만 지원해요. 토스페이, 네이버페이만 모든 테스트 키로 연동할 수 있습니다. 카카오페이는 계약 후 발급받는 내 테스트 키로 연동할 수 있습니다. 페이코 등 기타 간편결제는 라이브 키로 테스트하세요.

• 인증실패 등 원천사 에러 메시지를 받았다면, PG와 관련없는 에러입니다. 원천사에 문의해주세요.

오류원인

카드사에서 해당 카드를 거절했을 때 REJECT_CARD_COMPANY 에러가 발생합니다. 원인은 비밀번호 오류, 한도 초과, 포인트 부족 등 다양합니다.

해결 방법

에러 메시지를 확인해서 원인을 파악하고 고객에게 올바른 안내를 해주세요.

오류원인

결제수단 문제, 상점 계약 문제, 결제 승인에 문제가 있을 때 FAILED_PAYMENT_INTERNAL_SYSTEM_PROCESSING 에러가 발생합니다.

해결 방법

• 결제수단(카드, 휴대폰, 가상계좌 등)에 문제가 있다면 에러 메시지를 참고해주세요. 비밀번호 입력 오류, 한도 초과, 은행 점검 시간 등 문제가 발생할 수 있어요.

• 복합결제(카드, 포인트, 계좌를 함께 사용하는 결제) 계약이 안 되어 있다는 메시지를 받으면 1544-7772로 문의해서 복합결제 계약을 신청해주세요.

• 결제 승인을 두 번 호출하거나 요청이 끝난 뒤에 10분 이내로 결제 승인을 요청하지 않으면 발생할 수 있어요. 결제 승인 요청을 다시 확인해주세요.

오류원인

자동결제(빌링) 계약이 안 되어 있거나 0원으로 결제를 시도하면 발생하는 에러입니다.

해결 방법

• 1544-7772로 전화해서 사용하고 싶은 결제수단이 잘 계약되어 있는지 다시 확인하세요.

• 100원부터 결제를 시도해주세요.

• 카드번호를 맞게 입력했는지 확인하세요.

오류원인

API 키값 또는 주문번호가 최초 요청한 값과 다르면 FORBIDDEN_REQUEST가 발생합니다.

해결 방법

• 결제 요청에 사용한 클라이언트 키와 API 호출에 사용한 시크릿 키가 매칭된 키값인지 확인하세요.

• orderId, paymentKey 값이 최초 결제 요청한 값과 같은지 확인하세요.

오류원인

계약되지 않은 결제수단 또는 방법으로 결제를 시도하면 NOT_SUPPORTED_METHOD 에러가 발생합니다.

해결 방법

• 자동결제(빌링)는 추가 계약이 필요한 서비스입니다. 1544-7772로 문의해서 계약을 진행한 뒤에 다시 시도해주세요.

• 자동결제 계약을 완료했다면, 자동결제용 MID와 연결된 API키를 사용하고 있는지 확인해주세요.

• 브랜드페이를 사용하고 있다면 Access Token을 발급받기 위한 리다이렉트 URL을 등록했는지 확인하세요.

오류원인

결제 취소를 요청할 때 API 키 값이 잘못되었거나, 이미 취소된 결제이면 NOT_CANCELABLE_PAYMENT 에러가 발생합니다.

해결 방법

• 결제 요청에 사용한 클라이언트 키와 결제 취소 API 호출에 사용한 시크릿 키가 매칭된 키값인지 확인하세요.

• 시크릿 키 인코딩을 다시 확인하세요. 시크릿 키 뒤에 :을 추가하고 base64로 인코딩해서 사용해야 됩니다.

• 결제 취소 API를 두 번 이상 호출하고 있는지 확인해주세요. 이미 취소된 결제를 다시 취소하면 에러가 발생합니다.

• 결제 취소 API 요청 파라미터를 다시 확인하세요. 필수 값을 누락했거나 면세 금액이 없는데 taxFreeAmount를 사용하고 있으면 에러가 발생합니다.

오류원인

취소를 요청한 금액이 승인된 금액보다 크면 NOT_CANCELABLE_AMOUNT 에러가 발생합니다.

해결 방법

• 취소 또는 부분취소를 요청한 금액이 최종 승인된 금액보다 큽니다. 승인 금액을 다시 확인하고 취소 금액과 비교해보세요.

• 취소면세금액이 기존 면세금액보다 큽니다. 면세금액을 다시 확인해도 원인이 파악이 안 된다면 디스코드로 문의해주세요.

오류원인

사용자가 결제 중에 결제창을 닫으면 PAY_PROCESS_CANCELED 에러가 발생합니다. 해당 에러가 일어나면 결제 요청 시 등록한 failUrl로 이동합니다. 다만 주문이 생성되지 않고 고객이 이탈한 것이기 때문에 failUrl 쿼리 파라미터로 code, message가 넘어오지만 orderId는 넘어오지 않습니다.

사업자등록번호와 구 상점관리자에 등록된 이메일 주소를 입력하면 새로운 홈페이지 계정으로 연결해드리는 기능을 제공하고 있습니다. 토스페이먼츠 홈페이지에 로그인한 뒤 기존 상점 불러오기를 이용해주세요.

구 모듈 에러코드 페이지에서 에러 목록을 확인하세요. code에는 매핑된 에러 코드가, message에는 구 모듈 에러 메시지 혹은 결제 기관(카드사, 은행, 국세청 등)에서 보내준 에러를 표시합니다.

예를 들어 다음과 같은 형태입니다.

{
  "code": "FAILED_PAYMENT_INTERNAL_SYSTEM_PROCESSING",
  "message": "[0314] 공인인증서 폐기됨(재발급 후 결제요망)"
}