# 토스페이 결제 연동 가이드 > 토스페이(Toss Pay) 가맹점을 위한 결제 연동 문서입니다. 온라인 결제(생성, 구매자 인증, 승인, 환불, 자동 결제, 현금영수증)의 튜토리얼·가이드·API 레퍼런스와 오프라인 결제 문서를 담고 있습니다. - 문서 사이트: https://docs-pay.toss.im - 전체 문서 텍스트: /llms-full.txt ## 온라인 - 시작하기 - [토스페이 연동 시작하기](/tutorial): 이 튜토리얼은 토스페이 온라인 결제를 처음 연동하는 개발자를 위한 문서예요. 구매자가 매번 인증하는 일반 결제(단건 결제)를 기준으로, 순서대로 따라 하면 결제 생성부터 구매자 인증, 결제 승인, 라이브 전환까지 첫… - [1. 개발 준비하기](/tutorial/step-1): 이 단계에서는 가맹점 계정을 만들고 API Key를 확인해요. API Key는 결제 생성, 승인, 환불 등 모든 API 호출에서 가맹점을 인증하는 수단이라 연동을 시작하기 전에 꼭 준비해야 해요. - [2. 결제 생성하기](/tutorial/step-2): 이 단계에서는 결제 생성 API를 호출해서 결제 건을 만들어요. 결제를 생성하면 구매자를 보낼 결제창 URL(checkoutPage)과 결제 고유 번호(payToken)를 받아요. 이 두 값이 다음 단계의 재료가 돼… - [3. 결제창 연결하기](/tutorial/step-3): 이 단계에서는 구매자를 토스페이 결제창으로 보내요. 2단계에서 받은 checkoutPage URL로 구매자를 이동시키기만 하면, 결제 수단 선택부터 인증까지 토스가 알아서 진행해요. - [4. 인증 결과 처리하기](/tutorial/step-4): 이 단계에서는 인증을 마치고 돌아온 구매자를 처리해요. 구매자가 결제 비밀번호를 입력해 인증을 완료하면, 토스는 2단계에서 결제 생성 시 전달한 retUrl로 구매자를 보내요. - [5. 결제 승인과 콜백 처리하기](/tutorial/step-5): 이 단계에서는 결제를 최종 완료 처리해요. 2단계에서 설정한 autoExecute 값에 따라 가맹점이 할 일이 달라져요. - [6. 테스트와 라이브 전환하기](/tutorial/step-6): 마지막 단계에서는 연동한 결제 흐름을 시나리오별로 점검하고, 실거래용 API Key로 전환해서 서비스를 오픈해요. - [자동 결제 시작하기](/tutorial/billing): 빌링키를 한 번 발급받아 구매자 인증 없이 반복 결제하는 자동 결제 연동 튜토리얼이에요. - [1. 빌링키 생성하기](/tutorial/billing-step-1): 빌링키 생성 API를 호출해 사용자별 빌링키와 인증 URI를 받아요. - [2. 사용자 인증 받기](/tutorial/billing-step-2): OS별 인증 URI로 사용자를 토스 앱에 보내 결제수단을 등록하고 자동 결제를 인증해요. - [3. 활성화 확인하기](/tutorial/billing-step-3): 콜백 수신과 상태 조회로 빌링키가 결제 가능한 ACTIVE 상태인지 확인해요. - [4. 자동 결제 승인하기](/tutorial/billing-step-4): 활성화된 빌링키로 구매자 인증 없이 결제를 실행해요. - [5. 빌링키 관리하기](/tutorial/billing-step-5): 구독 해지에 따른 빌링키 삭제와 삭제 콜백 대응까지 운영을 준비해요. ## 온라인 - 가이드 - [결제 생성하기](/guide/create): 결제 생성 요청에 대해 좀 더 자세히 알아봅니다. 아래 예제는 결제 생성 API가 지원하는 모든 파라미터를 사용한 코드입니다. - [결제 승인하기](/guide/excute): 구매자 인증이 완료된 '대기' 상태에서 재고상태 확인 후 결제를 진행할 수 있습니다. 아래 예제는 승인 API가 지원하는 파라미터 중 일부를 사용한 코드입니다. - [결제 환불하기](/guide/refund): 결제 완료 건의 결제 금액 중 일부 또는 전부를 구매자에게 돌려줍니다. 환불 요청에 성공하는 즉시, 토스 머니로 결제된 거래건은 구매자의 계좌로 요청하신 금액이 입금되며, 카드결제 거래건은 승인취소 됩니다. 환불한 … - [결제 상태 알아보기](/guide/check-status): 결제가 생성되고 진행됨에 따라 결제의 '상태'는 끊임없이 바뀝니다. 상점 운영을 위해선 특정 결제건이 현재 어떤 상태인지 파악할 일이 많을 것입니다. 결제가 잘 끝난 것인지, 취소된 것은 아닌지. 환불 요청에 들어왔… - [신용카드 매출전표](/guide/credit-check): 신용카드 매출전표를 확인하시려면 아래의 URL로 이동하시면 됩니다. - [토스 은행 코드](/guide/bank-code): 토스머니 결제의 경우 사용자가 선택한 계좌의 정보를 함께 전달합니다. - [토스 카드(매입사) 코드](/guide/card-code): 토스에서 정의한 카드사 코드는 다음과 같습니다. - [결제 에러 응답코드](/guide/error-code): 토스페이 에러코드는 예고 없이 업데이트 될 수 있습니다. 추가되더라도 오류가 발생하지 않도록 연동 부탁드립니다. ## 온라인 - API 레퍼런스 - [토스페이 API 소개](/reference): 토스를 통한 결제 서비스를 사용하기 위한 API입니다. 토스페이를 활용한 개발을 처음 시작하신다면, 좀 더 친절한 안내를 먼저 확인해보세요! '토스페이 시작하기' 문서로 바로가기 - [결제 생성](/reference/normal/create): 결제 건을 생성합니다. - [결제 결과 callback (resultCallback)](/reference/normal/result-callback): 결제 처리가 완료되면 결제 상태가 변경되고, 토스는 가맹점 서버로 변경 사항을 알려드립니다. - [가맹점 결제 승인](/reference/normal/execute): 자동 승인 설정을 false로 사용하는 가맹점에서만 처리하는 로직입니다. - [개요](/reference/billing): 빌링키 방식으로 자동결제를 연동할 수 있도록 구현한 API입니다. 토스 결제서버는 가맹점의 빌링키 생성요청에 따라 구매자가 인증할 수 있는 유니크한 '결제 인증 URL'을 생성하고, 가맹점을 통해 구매자는 토스 앱을… - [빌링키 생성 요청](/reference/billing/create): 토스 자동결제를 등록하기 위해서는 사용자를 식별할 수 있는 고유한 빌링키를 생성해야 합니다. API 요청의 응답으로 성공 여부와 함께 토스 앱 인증 URL을 전달합니다. - [빌링키 처리결과 callback](/reference/billing/result-callback): 사용자가 토스 앱을 통해 빌링 등록을 '성공적'으로 완료한 경우 토스 서버는 가맹점이 설정한 resultCallback URL을 통해 결과를 전달합니다. 대부분의 자동결제 등록 실패에 대해서는 사용자의 재시도를 고려… - [자동결제(bill) 승인 요청](/reference/billing/bill): 빌링키 생성결과 callback에서 전달받은 빌링키로 가맹점은 승인 요청을 할 수 있습니다. 유효시간이나 최대 횟수를 제한하지 않으니 승인요청 API를 활용해서 결제를 진행할 수 있습니다. - [빌링키 상태 조회](/reference/billing/billing-key-status): 가맹점은 생성된 빌링키를 관리하고 회원 관리의 목적으로 빌링키의 상태를 조회할 수 있습니다. 사용자가 토스앱에서 결제수단을 변경한 경우 결제수단(payMethod) 정보가 업데이트될 수 있습니다. - [빌링키 삭제 요청](/reference/billing/remove): 생성된 빌링키를 삭제합니다. 삭제된 빌링키는 더 이상 자동결제에 사용할 수 없습니다. - [결제 환불](/reference/common/refunds): 결제 완료 건의 결제 금액 중 일부 또는 전부를 구매자에게 돌려줍니다. - [결제 상태 확인](/reference/common/status): 생성된 결제건의 거래 상태와 거래 트랜잭션을 조회할 수 있습니다. 상황에 따라, 승인 혹은 환불 응답을 수신하지 못한 경우에도 활용 가능합니다. - [토스 현금영수증 API 소개](/reference/cache-receipt): 본 문서는 토스페이 결제 가맹점에서 현금영수증을 발급하거나 취소, 상태 확인 및 현금영수증 이미지 주소를 얻고자 할 때 사용할 API에 대한 가이드를 제공합니다. - [현금 영수증 발급](/reference/cache-receipt/issue): 해당 결제가 status = PAY_COMPLETE으로 완료되었을 때, 현금 영수증 발급이 가능합니다. - [현금 영수증 취소](/reference/cache-receipt/revoke): 해당 결제가 status = PAY_COMPLETE으로 완료되었고, 발급 요청된 현금 영수증이 있을 때에만 호출 가능합니다. - [현금 영수증 상태 확인](/reference/cache-receipt/info): 발급된 현금영수증의 상태를 조회합니다. 국세청 전송 상태, 발급 완료 여부 등을 확인할 수 있습니다. - [현금 영수증 팝업 주소 전달](/reference/cache-receipt/popup-uri): 토스 결제 가맹점을 이용한 고객이 현금영수증의 발급 및 취소된 것의 발급 이미지 등을 요구할 때, 해당 API를 호출하여 리턴되는 팝업 Uri 값으로 대응이 가능합니다. - [토스 정산 API 소개](/reference/settlement): 토스 결제 서비스를 통한 매출과 정산 금액 확인을 위한 API입니다. 페이징 개념이 적용되며, 페이징 단위는 1,000건입니다. 다음 페이징이 존재하면 nextCursor라는 응답값이 리턴되며, 이를 포함하여 호출하… - [정산 API](/reference/settlement/detail): 지급일 또는 거래 승인일 기준으로 정산 상세 내역을 조회합니다. ## 자주 묻는 질문 - [자주 묻는 질문](/faq-v2): 토스페이 온라인 직연동 테스트 및 운영 과정에서 자주 발생하는 문제와 해결 방법을 정리했습니다. ## 온라인 - 서비스 정책 - [수수료 정책](/policy/fee): 토스 간편결제 결제대행 수수료 정책은 다음과 같습니다. - [서비스 정책](/policy/service): 만 14세 이상이면 누구나 회원 가입 후 토스페이를 이용할 수 있습니다.토스머니는 자신의 은행 계좌를 통해 자동 충전할 수 있고, 카드 결제는 본인 명의의 카드를 등록해서 사용할 수 있습니다. - [환불 정책](/policy/refund): 토스 간편결제 환불 정책은 다음과 같습니다. - [정산 / 지급 정책](/policy/settle): 가맹점에 지급할 총 금액을 언제 지급할지 계산하고 계산된 금액을 가맹점에 지급하는 과정입니다. ## 오프라인 - 서비스 소개 - [토스페이 소개](/offline/introduce/tosspay): 토스페이 오프라인 결제는 사용자가 매장에서 QR이나 페이스페이를 이용해 쉽게 결제할 수 있는 서비스예요. 매장에서는 POS와 리더기만 있으면 토스페이를 바로 도입할 수 있으며, 대부분의 결제 처리는 VAN을 통해 이뤄져요. - [페이스페이 소개](/offline/introduce/facepay): 페이스페이는 얼굴인증으로 빠르고 편리하게 결제하는 서비스예요. ## 오프라인 - 준비하기 - [대리점 계약](/offline/prepare/subscription/agency): 일반 가맹점을 대상으로 토스페이 오프라인 결제 계약을 진행하는 방법을 안내해요. - [프랜차이즈 계약](/offline/prepare/subscription/franchise): 프랜차이즈 본사 및 가맹점을 대상으로 토스페이 오프라인 결제 계약을 진행하는 방법을 안내해요. - [단말기 설치](/offline/prepare/device-onboarding): 토스플레이스 단말기를 처음 설치하거나 사용하는 분들을 위한 설치 가이드를 안내해요. - [결제](/offline/prepare/payment): 토스페이 준비사항에 대해 안내해요. - [페이스페이](/offline/prepare/facepay): 페이스페이를 위해 사전에 확인이 필요한 사항은 다음과 같아요. ## 오프라인 - 개발하기 - [토스페이 연동](/offline/develop/tosspay): 토스 오프라인 결제는 토스페이를 지원하는 가맹점에서 앱을 통한 바코드 인식을 통해 결제가 가능한 서비스예요. 이 페이지에서는 토스페이 연동 방법에 대해 안내해요. - [토스페이 토큰](/offline/develop/tosspay/token): 토스페이 토큰은 각 거래를 고유하게 식별하는 값이에요. 이 페이지에서는 토스페이 토큰에 대해 안내해요. - [페이스페이](/offline/develop/facepay): 결제의 새로운 혁신, 페이스페이에 대해 안내해요 ## 오프라인 - 운영하기 - [가맹점 운영 가이드](/offline/operation/store): 가맹점 운영 방법을 안내해요. - [VAN 대리점 운영 가이드](/offline/operation/agency): VAN 대리점 운영 가이드에 대해 안내해요. - [프로모션 가이드](/offline/operation/promotion): 토스페이 결제가 가능한 프랜차이즈 브랜드라면 오프라인 매장에서 사용할 수 있는 프로모션 운영이 가능해요. - [정산 가이드](/offline/operation/settlement): 가맹점에 정산 금액을 어떻게 계산하고 언제 지급하는지에 대한 전체 과정을 안내해요. ## 오프라인 - 서비스 정책 - [결제 정책](/offline/policy/payment): 토스페이 오프라인 결제의 운영 제한사항(연령, 결제 한도, 최소 결제 금액 등)과 결제 수단별 조건, 수수료, 정산 방식에 대해 안내해요. - [정산 정책](/offline/policy/settlement): 결제수단 - [지원 VAN](/offline/policy/van): 토스페이에서는 다음과 같은 밴사를 지원해요. ## 오프라인 - 자주 묻는 질문 - [페이스페이](/offline/faq/facepay): 토스 앱에서 ‘토스 페이스페이’ 등록을 완료했다면 누구나 사용할 수 있어요. - [페이스페이 결제 실패](/offline/faq/facepay-fail): 결제 실패 시 확인 사항에 대해 안내해요. - [프로모션](/offline/faq/promotion): 진행 중인 프로모션이라도 배너 이미지 교체는 가능해요. ## AI 도구로 연동하기 - [AI 도구로 연동하기](/ai-tools): LLM이 읽기 좋은 llms.txt로 토스페이 문서를 AI 코딩 도구에 제공하는 방법을 안내해요.