# 토스페이 결제 연동 가이드
> 토스페이(Toss Pay) 가맹점을 위한 결제 연동 문서입니다. 온라인 결제(생성, 구매자 인증, 승인, 환불, 자동 결제, 현금영수증)의 튜토리얼·가이드·API 레퍼런스와 오프라인 결제 문서를 담고 있습니다.
- 문서 사이트: https://docs-pay.toss.im
- 전체 문서 텍스트: /llms-full.txt
---
# 토스페이 연동 시작하기
URL: /tutorial
이 튜토리얼은 토스페이 온라인 결제를 처음 연동하는 개발자를 위한 문서예요. 구매자가 매번 인증하는 일반 결제(단건 결제)를 기준으로, 순서대로 따라 하면 결제 생성부터 구매자 인증, 결제 승인, 라이브 전환까지 첫 결제를 완주할 수 있어요. 실제 출금이 일어나지 않는 테스트용 API Key로 진행하니 부담 없이 시작해도 돼요.
## 결제가 완료되기까지의 흐름
토스페이 결제는 세 주체가 참여해요. 가맹점 서버가 결제를 생성하면 구매자가 토스 앱에서 결제 수단을 선택해 인증하고, 토스 서버가 결제를 완료 처리한 뒤 결과를 가맹점 서버에 알려줘요. 전체 흐름은 다음 그림과 같아요.
## 미리 준비할 것
튜토리얼을 진행하려면 다음이 필요해요.
- 계약을 완료했다면 토스페이 파트너스에서 발급받은 테스트용 API Key를 준비하세요. 계약 전이라면 공용 테스트용 API Key(sk_test_w5lNQylNqa5lNQe013Nq)로도 따라 할 수 있어요.
- 결제 생성 API를 호출하고 결제 결과 콜백을 받을 가맹점 서버가 필요해요. 콜백 URL은 외부에서 접근할 수 있어야 해요.
- 구매자를 토스페이 결제창으로 이동시킬 결제 화면(웹 페이지 또는 앱의 WebView)이 필요해요.
## 핵심 용어
튜토리얼 전체에서 반복해서 쓰는 용어예요.
| 용어 | 설명 |
| payToken | 결제 건 하나를 구분하는 토스 고유 값이에요. 승인, 환불, 상태 조회 등 모든 후속 처리에 사용해요. |
| checkoutPage | 구매자가 결제를 진행하는 토스페이 웹 페이지 URL이에요. 결제를 생성하면 응답으로 받아요. |
| autoExecute | 구매자 인증이 끝났을 때 토스가 결제를 자동으로 승인할지 결정하는 옵션이에요. 값에 따라 연동 방식이 달라져요. |
## 일반 결제 연동 단계
여섯 단계로 진행해요. 각 단계는 이전 단계의 결과를 이어받으니 순서대로 읽는 것을 추천해요.
### 1. 개발 준비하기
가맹점 계정과 테스트용·실거래용 API Key를 준비해요.
### 2. 결제 생성하기
결제 생성 API를 호출하고 checkoutPage와 payToken을 받아요.
### 3. 결제창 연결하기
구매자를 checkoutPage로 보내 결제 수단 선택과 인증을 진행해요.
### 4. 인증 결과 처리하기
retUrl로 돌아온 구매자의 인증 결과를 확인해요.
### 5. 결제 승인과 콜백 처리하기
결제를 최종 승인하고 콜백으로 완료를 확인해요.
### 6. 테스트와 라이브 전환하기
시나리오별로 점검하고 실거래용 API Key로 전환해요.
연동 전에 결제를 먼저 경험해 보고 싶다면 데모 체험하기에서 실제 결제 흐름을 미리 볼 수 있어요.
AI 도구로 연동을 개발하고 있다면 LLM이 읽기 좋은 /llms.txt를 제공해요. 활용 방법은 AI 도구로 연동하기를 참고하세요.
## 다른 결제 방식 연동하기
구독, 멤버십처럼 반복 결제가 필요하다면 빌링키 기반의 자동 결제를 연동하세요. 자동 결제 튜토리얼에서 빌링키 발급부터 자동 결제 승인까지 안내해요.
---
# 1. 개발 준비하기
URL: /tutorial/step-1
이 단계에서는 가맹점 계정을 만들고 API Key를 확인해요. API Key는 결제 생성, 승인, 환불 등 모든 API 호출에서 가맹점을 인증하는 수단이라 연동을 시작하기 전에 꼭 준비해야 해요.
## 가맹점 계정 신청하기
먼저 계약 문의로 가맹점 가입을 신청해요. 가입이 승인되면 가맹점 계정이 발급되고, 토스페이 파트너스에 로그인해서 상점을 관리할 수 있어요.
계약이 아직 완료되지 않았다면 공용 테스트용 API Key(sk_test_w5lNQylNqa5lNQe013Nq)로 튜토리얼을 먼저 진행할 수 있어요. 다만 여러 가맹점이 함께 쓰는 Key라서 다른 가맹점의 테스트 거래가 섞일 수 있어요.
## API Key 확인하기
토스페이 파트너스에 로그인한 뒤 가맹점 정보 > API Key 정보에서 상점의 API Key를 확인할 수 있어요.
API Key는 테스트용과 실거래용 두 가지가 발급돼요. 둘 다 운영 환경에서 사용하는 Key이고, 어떤 Key를 쓰는지에 따라 테스트 결제와 실거래가 구분돼요.
| 구분 | 테스트용 API Key | 실거래용 API Key |
| Key 형태 | sk_test_로 시작 | sk_live_로 시작 |
| 금원 이동 | 없음 (머니·계좌 출금 없음, 카드 승인 없음) | 실제 출금과 정산이 발생해요. |
| 용도 | 개발과 테스트. 승인 응답까지 실제 결제와 동일하게 확인할 수 있어요. | 실제 구매자에게 서비스를 오픈할 때 사용해요. |
| 제약 | 현금영수증 발급 테스트 불가 | 없음 |
튜토리얼에서는 테스트용 API Key를 사용해요. 실거래용 API Key로 전환하는 시점과 주의사항은 6. 테스트와 라이브 전환하기에서 다뤄요.
API Key가 유출되지 않도록 주의하세요. API Key가 외부에 노출되면 원치 않는 결제 생성이나 환불이 발생해서 상점에 금전적 손실이 생길 수 있어요. API Key는 서버에만 보관하고, 웹 페이지나 앱 코드처럼 외부에서 볼 수 있는 곳에 넣지 마세요.
## 다음 단계
API Key를 준비했다면 이제 첫 결제를 만들 차례예요. 2. 결제 생성하기로 이동하세요.
---
# 2. 결제 생성하기
URL: /tutorial/step-2
이 단계에서는 결제 생성 API를 호출해서 결제 건을 만들어요. 결제를 생성하면 구매자를 보낼 결제창 URL(checkoutPage)과 결제 고유 번호(payToken)를 받아요. 이 두 값이 다음 단계의 재료가 돼요.
구매자가 'A상점'에서 35,000원짜리 'B티셔츠'를 골라 결제를 요청한 상황을 가정할게요. 이때 가맹점 서버는 토스 결제 서버에 결제 생성을 요청해야 해요.
결제 생성 API Endpoint POST https://pay.toss.im/api/v2/payments
## 결제 생성 API 호출하기
가맹점 서버에서 다음과 같이 결제 생성 API를 호출해요. 필수 파라미터만 담은 예제이고, apiKey에는 1단계에서 확인한 테스트용 API Key를 넣어요.
```
curl https://pay.toss.im/api/v2/payments \
-H "Content-Type: application/json" \
-d '{
"orderNo": "2026-0712-000001",
"amount": 35000,
"amountTaxFree": 0,
"productDesc": "B티셔츠",
"apiKey": "sk_test_w5lNQylNqa5lNQe013Nq",
"autoExecute": true,
"callbackVersion": "V2",
"resultCallback": "https://example-shop.com/api/payments/callback",
"retUrl": "https://example-shop.com/payments/complete",
"retCancelUrl": "https://example-shop.com/payments/cancel"
}'
```
각 파라미터의 역할은 다음과 같아요.
| 파라미터 | 필수 | 설명 |
| orderNo | 필수 | 상점 주문번호예요. 나중에 상점의 주문 정보와 토스 결제 정보를 매칭할 때 사용해요. 가맹점별로 매회 유니크해야 하고, 중복되면 결제 생성이 실패해요. |
| amount | 필수 | 구매자에게 받을 총 결제 금액이에요. |
| amountTaxFree | 필수 | 결제 금액 중 비과세 금액이에요. 비과세 상품이 없다면 0을 넣어요. |
| productDesc | 필수 | 결제할 상품 정보예요. |
| apiKey | 필수 | 상점의 API Key예요. 테스트용 Key를 넣으면 테스트 결제가, 실거래용 Key를 넣으면 실제 출금되는 결제가 생성돼요. |
| autoExecute | 필수 | 자동 승인 설정이에요. true면 구매자 인증이 완료됐을 때 토스가 알아서 결제를 승인해요. false면 가맹점이 직접 승인 API를 호출해야 해요. |
| resultCallback | autoExecute: true면 필수 | 결제 결과를 받을 가맹점 서버 URL이에요. 토스 서버가 출금을 완료하면 이 URL로 결과를 POST 요청해요. |
| callbackVersion | autoExecute: true면 필수 | 콜백 버전이에요. 신규 연동이라면 V2를 사용하세요. |
| retUrl | 필수 | 구매자가 결제 인증을 완료하면 이동시킬 가맹점 페이지 URL이에요. 결제 완료 화면으로 이동시키는 용도로만 쓰여요. |
| retCancelUrl | 필수 | 구매자가 결제창에서 결제를 중단했을 때 이동시킬 가맹점 페이지 URL이에요. |
과세·부가세 금액 구성, 결제 만료 시각 같은 선택 파라미터를 포함한 전체 목록은 결제 생성 API 레퍼런스에서 확인할 수 있어요.
## 응답 확인하기
결제 생성에 성공하면 토스가 다음과 같이 응답해요.
```
{
"code": 0,
"payToken": "example-payToken",
"checkoutPage": "https://pay.toss.im/payfront/auth?payToken=example-payToken",
"status": 200
}
```
- code가 0이면 결제 생성에 성공한 거예요. 그 외에는 오류 코드와 메시지가 전달돼요. 오류 코드의 의미는 에러 코드에서 확인하세요.
- checkoutPage는 구매자가 결제를 진행할 토스페이 결제창 URL이에요. 다음 단계에서 구매자를 이 URL로 보내요.
- payToken은 이 결제 건을 구분하는 토스 고유 값이에요. 결제 승인, 환불, 상태 조회 모두 이 값으로 요청하니 주문 정보와 함께 저장해 두세요.
- status는 HTTP 상태 코드예요. 성공 여부 판단은 code 값으로 하세요.
## 다음 단계
checkoutPage와 payToken을 받았다면 이제 구매자를 결제창으로 보낼 차례예요. 3. 결제창 연결하기로 이동하세요.
---
# 3. 결제창 연결하기
URL: /tutorial/step-3
이 단계에서는 구매자를 토스페이 결제창으로 보내요. 2단계에서 받은 checkoutPage URL로 구매자를 이동시키기만 하면, 결제 수단 선택부터 인증까지 토스가 알아서 진행해요.
## checkoutPage로 이동시키기
결제 생성 응답으로 받은 checkoutPage는 다음과 같은 형태예요. 결제마다 다른 URL이 발급돼요.
```
https://pay.toss.im/payfront/auth?payToken=example-payToken
```
구매자의 브라우저를 이 URL로 리다이렉트하세요. 이때 두 가지를 주의해야 해요.
checkoutPage를 iframe으로 열지 마세요. iframe 안에서 checkoutPage를 로드하면 구매자 인증 후에 retUrl로 리다이렉트되지 않아서 결제 승인이 안 될 수 있어요. 반드시 페이지 전체를 이동시키세요.
Android 앱의 WebView에서 여는 경우 shouldOverrideUrlLoading을 확인하세요. 이 메서드가 모든 경우에 true를 반환하면 WebView에서 retUrl로 리다이렉트되지 않아 결제 승인이 안 돼요. retUrl로의 이동이 정상 동작하도록 구현해야 해요. 다음 문서를 참고하세요. - shouldOverrideUrlLoading 문서 - shouldOverrideUrlLoading 가이드
## 구매자의 결제 진행 과정 이해하기
구매자는 결제창에서 결제 수단을 선택하고 인증을 진행해요. 이 구간은 토스 앱과 토스 서버가 통신하는 구간이라 가맹점이 처리할 일은 없지만, 구매자가 어떤 화면을 보는지 알아두면 문의 대응에 도움이 돼요.
- 토스 회원은 결제 수단을 선택하고 토스 비밀번호를 입력하면 인증이 완료돼요.
- 토스 비회원은 토스 앱을 설치하고 가입한 뒤 결제를 진행해요.
토스머니를 선택하면 계좌 유효성 검증과 충전 단계를 거치고, 카드 결제를 선택하면 카드 소유자 확인 후 카드 추가부터 진행할 수 있어요.
토스페이는 앱 결제 방식을 지원해요. PC 웹 브라우저에서 결제하는 경우 구매자의 휴대폰으로 결제 푸시 알림을 보내고, 인증은 토스 앱에서 진행해요. 결제 보안을 위해 웹 키보드 방식의 웹 결제는 제공하지 않아요.
테스트 결제도 같은 방식으로 인증해요. 테스트용 API Key로 생성한 결제도 본인 휴대폰의 토스 앱으로 인증하면 돼요. 실제 출금 없이 인증부터 승인까지 실거래와 동일하게 진행돼요.
## 다음 단계
구매자가 인증을 마치면 토스가 구매자를 retUrl로 돌려보내요. 4. 인증 결과 처리하기에서 이 결과를 처리해요.
---
# 4. 인증 결과 처리하기
URL: /tutorial/step-4
이 단계에서는 인증을 마치고 돌아온 구매자를 처리해요. 구매자가 결제 비밀번호를 입력해 인증을 완료하면, 토스는 2단계에서 결제 생성 시 전달한 retUrl로 구매자를 보내요.
## retUrl로 전달되는 파라미터 확인하기
토스는 구매자를 retUrl로 보내면서 인증 결과를 쿼리 스트링 파라미터로 함께 전달해요.
- 모든 결제에는 인증 결과(status), 주문번호(orderNo), 결제 수단(payMethod)이 전달돼요.
- 카드 결제에는 카드사 코드(cardCompany)와 카드 BIN 번호(cardBinNum)가 추가돼요.
- 토스머니·계좌 결제에는 은행 코드(bankCode)가 추가돼요.
실제로 전달되는 URL은 다음과 같은 형태예요.
```
// 카드 결제
https://example-shop.com/payments/complete?status=PAY_COMPLETE&orderNo=2026-0712-000001&payMethod=CARD&cardCompany=1&cardBinNum=123456
// 토스머니·계좌 결제
https://example-shop.com/payments/complete?status=PAY_COMPLETE&orderNo=2026-0712-000001&payMethod=TOSS_MONEY&bankCode=004
```
## status 값으로 분기하기
status 값은 결제 생성 시 설정한 autoExecute 값에 따라 달라져요.
| autoExecute | status | 의미 |
| true | PAY_COMPLETE | 결제가 이미 완료됐어요. 토스가 인증 완료와 동시에 자동으로 승인했어요. |
| false | PAY_APPROVED | 구매자 인증만 완료된 대기 상태예요. 가맹점이 승인 API를 호출해야 결제가 완료돼요. |
retUrl은 화면 이동용이에요. retUrl 파라미터만 보고 주문을 완료 처리하지 마세요. 결제 완료의 최종 확인은 다음 단계에서 다루는 콜백 수신 또는 결제 상태 확인 API로 해야 안전해요.
## 네이티브 앱에서 연동하는 경우 (App to App)
가맹점 자체 앱(iOS/Android)에서 결제하는 경우, 결제 생성 시 retAppScheme 파라미터에 앱 스킴 값(예: testshop://)을 함께 전달하면 인증 완료 후 가맹점 앱으로 복귀시킬 수 있어요. iOS는 자동으로 앱 전환이 되지 않아서 retAppScheme 구현을 권장해요.
이때 두 파라미터의 역할이 달라요.
- retUrl은 App to App 환경에서도 여전히 필수예요. autoExecute 값과 무관하게 항상 호출되고, status 값만 다르게 전달돼요.
- retAppScheme은 가맹점 앱을 포그라운드로 복귀시키는 용도예요. 결제 결과 정보는 담고 있지 않아요.
승인 처리는 retUrl 기준으로 한 번만 트리거하세요. 웹뷰로 결제창을 감싼 구조에서는 인증 완료 시 retAppScheme과 retUrl이 각각 독립적으로 호출될 수 있어요. autoExecute: false로 승인 API를 직접 호출하는 가맹점이 retAppScheme 호출 시점에도 승인을 트리거하면, 동일 주문에 승인 요청이 중복 발생할 수 있어요.
## 다음 단계
인증까지 끝났으니 이제 결제를 완료하는 마지막 관문이 남았어요. 5. 결제 승인과 콜백 처리하기에서 autoExecute 설정별 완료 처리 방법을 알아봐요.
---
# 5. 결제 승인과 콜백 처리하기
URL: /tutorial/step-5
이 단계에서는 결제를 최종 완료 처리해요. 2단계에서 설정한 autoExecute 값에 따라 가맹점이 할 일이 달라져요.
- autoExecute: true로 생성했다면 토스가 자동으로 승인하니, 가맹점은 콜백을 받아서 결제 완료를 확인해요.
- autoExecute: false로 생성했다면 가맹점이 승인 API를 직접 호출해서 결제를 완료해요.
## 자동 승인이면 콜백으로 완료 확인하기
autoExecute: true로 결제를 생성했다면, 토스는 출금을 완료한 뒤 결제 생성 시 전달받은 resultCallback URL로 결제 결과를 POST 요청해요. 가맹점 서버는 이 콜백을 받았을 때 주문을 결제 완료 상태로 변경하고 재고 차감 같은 후속 로직을 처리하면 돼요.
콜백 V2 기준으로 다음과 같은 본문이 전달돼요. 카드 결제라면 카드 승인 정보가 함께 포함돼요.
```
{
"status": "PAY_COMPLETE",
"payToken": "example-payToken",
"orderNo": "2026-0712-000001",
"payMethod": "CARD",
"amount": 35000,
"discountedAmount": 0,
"paidAmount": 35000,
"paidTs": "2026-07-12 14:22:37",
"transactionId": "dc3b951a-9781-462e-ab5a-b8a0bea0222a"
}
```
- status에는 결제 완료 시 PAY_COMPLETE가 전달돼요. 결제 완료 이외의 상태는 콜백으로 전달되지 않아요.
- paidAmount는 할인 금액을 제외하고 실제 지불 수단으로 승인된 금액이에요.
카드 승인 정보를 포함한 전체 필드는 결제 결과 callback 레퍼런스에서 확인할 수 있어요.
콜백을 받으려면 방화벽을 먼저 확인하세요. 가맹점 서버가 자체 방화벽을 사용한다면 토스페이의 IP를 허용해야 콜백이 도착해요. 방화벽 정보를 확인하세요.
## 수동 승인이면 승인 API 호출하기
autoExecute: false로 결제를 생성했다면, 4단계에서 PAY_APPROVED 상태를 확인한 뒤 재고 확인 같은 검증을 마치고 승인 API를 호출해요. 승인이 완료되어야 실제 출금이 일어나요.
결제 승인 API Endpoint POST https://pay.toss.im/api/v2/execute
결제를 생성한 상점의 apiKey와 승인할 결제 건의 payToken 두 가지만 있으면 돼요.
```
curl https://pay.toss.im/api/v2/execute \
-H "Content-Type: application/json" \
-d '{
"apiKey": "sk_test_w5lNQylNqa5lNQe013Nq",
"payToken": "example-payToken"
}'
```
결제 금액 검증 같은 선택 파라미터는 가맹점 결제 승인 레퍼런스에서 확인할 수 있어요.
## 응답을 못 받았다면 결제 상태 확인하기
네트워크 문제로 승인 응답이나 콜백을 받지 못할 수도 있어요. 이럴 때는 결제 상태 확인 API로 해당 결제 건의 현재 상태를 직접 조회할 수 있어요. apiKey와 payToken(또는 orderNo)으로 조회해요.
결제 상태 확인 API Endpoint POST https://pay.toss.im/api/v2/status
```
curl https://pay.toss.im/api/v2/status \
-H "Content-Type: application/json" \
-d '{
"apiKey": "sk_test_w5lNQylNqa5lNQe013Nq",
"payToken": "example-payToken"
}'
```
응답의 payStatus가 PAY_COMPLETE면 결제가 완료된 거예요. retUrl 파라미터와 콜백 본문에서는 필드명이 status였지만, 상태 확인 API 응답에서는 payStatus라는 이름으로 같은 상태 값을 전달해요. 상태 값 전체 목록은 결제 상태 레퍼런스를 참고하세요.
## 다음 단계
첫 결제를 완주했어요. 이제 실제 오픈 전에 점검할 것들이 남았어요. 6. 테스트와 라이브 전환하기로 이동하세요.
---
# 6. 테스트와 라이브 전환하기
URL: /tutorial/step-6
마지막 단계에서는 연동한 결제 흐름을 시나리오별로 점검하고, 실거래용 API Key로 전환해서 서비스를 오픈해요.
## 시나리오별로 점검하기
테스트용 API Key는 실제 금원 이동 없이 승인 응답까지 실거래와 동일하게 동작해요. 구매자 인증은 본인 휴대폰의 토스 앱으로 직접 진행하면 되니, 다음 시나리오를 모두 확인해 보세요.
- 결제 생성부터 인증, 승인(또는 자동 승인)까지 완료되고 콜백이 정상 수신되는지 확인해요.
- 구매자가 결제창에서 결제를 중단했을 때 retCancelUrl로 이동하는지 확인해요.
- 콜백을 받지 못한 상황을 가정하고 결제 상태 확인 API로 상태를 복구할 수 있는지 확인해요.
- 완료된 결제 건을 환불 API로 전액·부분 환불해 보세요.
현금영수증 발급은 테스트용 API Key로 확인할 수 없어요. 테스트용 Key는 금원이 이동하지 않아 현금영수증이 발급되지 않아요. 현금영수증은 실거래용 API Key로 소액 결제해서 확인한 뒤 반드시 취소 처리하세요.
테스트 중 공격성 요청에 주의하세요. 운영 환경에서 테스트용 API Key를 사용하더라도 순간적으로 요청을 많이 보내면 IP가 자동 차단될 수 있어요.
## 실거래용 API Key로 전환하기
점검을 마쳤다면 결제 생성 요청의 apiKey를 실거래용(sk_live_)으로 변경하고 서비스를 오픈해요.
오픈 전에 반드시 실거래용 API Key로 변경했는지 확인하세요. 테스트용 API Key로 서비스를 오픈하면 구매자의 결제는 성공한 것처럼 보이지만 실제 출금이 없어서, 가맹점이 금액을 받지 못한 채 상품과 서비스를 제공하게 되는 위험이 있어요.
## 다음 단계
기본 결제 연동이 끝났어요. 운영에 필요한 기능은 다음 문서에서 확인할 수 있어요.
- 완료된 결제의 전액·부분 환불은 결제 환불하기를 참고하세요.
- 결제 건의 현재 상태 조회는 결제 상태 알아보기를 참고하세요.
- API 응답의 오류 코드 목록은 에러 코드를 참고하세요.
- 자동 결제, 현금영수증, 정산 조회 등 전체 API 명세는 API 레퍼런스를 참고하세요.
---
# 자동 결제 시작하기
URL: /tutorial/billing
이 튜토리얼은 구독, 멤버십처럼 반복 결제가 필요한 서비스를 위한 문서예요. 순서대로 따라 하면 빌링키 발급부터 사용자 인증, 자동 결제 승인, 빌링키 관리까지 완주할 수 있어요. 일반 결제 튜토리얼처럼 실제 출금이 일어나지 않는 테스트용 API Key로 진행해요.
## 자동 결제가 일반 결제와 다른 점
일반 결제는 결제할 때마다 구매자가 토스 앱에서 인증해요. 자동 결제는 최초 한 번만 인증해서 빌링키를 활성화하고, 그 뒤로는 가맹점 서버가 빌링키로 승인 API를 호출할 때마다 인증 없이 결제돼요. 승인 요청의 유효시간이나 횟수 제한이 없어서 월 구독 같은 반복 청구에 맞아요.
| 구분 | 일반 결제 | 자동 결제 |
| 구매자 인증 | 매 결제마다 | 최초 등록 시 한 번 |
| 결제 실행 | 인증 완료 후 승인 | 가맹점이 원하는 시점에 승인 API 호출 |
| 핵심 식별자 | payToken (결제 건 단위) | billingKey (사용자 결제수단 단위) |
| 결제 수단 | 토스머니, 카드 | 토스머니, 카드 |
전체 흐름은 다음 그림과 같아요. 빌링키 생성과 사용자 인증(1회)을 거쳐 활성화되면, 이후에는 승인 요청만 반복돼요.
## 빌링키의 상태
빌링키는 상태를 가지고, 튜토리얼의 매 단계가 이 상태를 중심으로 진행돼요. 생성하면 CREATE로 시작하고, 사용자가 인증을 완료하면 ACTIVE가 되어 결제에 쓸 수 있어요. 상태는 상태 조회 API로 언제든 확인할 수 있어요.
| status | 의미 | 다루는 단계 |
| CREATE | 빌링키가 생성됐지만 아직 사용자가 인증하지 않은 상태예요. | 1. 빌링키 생성하기 |
| ACTIVE | 활성화 완료. 승인 API로 결제할 수 있는 유일한 상태예요. | 3. 활성화 확인하기 |
| REMOVE | 삭제된 상태예요. | 5. 빌링키 관리하기 |
| CANCEL | 취소된 상태예요. | 5. 빌링키 관리하기 |
| FAIL | 등록에 실패한 상태예요. | 3. 활성화 확인하기 |
## 미리 준비할 것
- API Key는 일반 결제와 같아요. 계약 전이라면 공용 테스트용 API Key(sk_test_w5lNQylNqa5lNQe013Nq)로 따라 할 수 있어요.
- 빌링키 생성 API를 호출하고 활성화 콜백을 받을 가맹점 서버가 필요해요. 콜백 URL은 외부에서 접근 가능해야 해요.
- 토스 앱이 설치된 휴대폰이 필요해요. 별도 테스트 계정이나 SDK 없이 본인 토스 앱으로 인증을 진행해요.
## 연동 단계
다섯 단계로 진행해요. 각 단계는 이전 단계의 결과를 이어받으니 순서대로 읽는 것을 추천해요.
### 1. 빌링키 생성하기
빌링키 생성 API를 호출하고 인증 URI를 받아요.
### 2. 사용자 인증 받기
OS별 인증 URI로 사용자를 보내 토스 앱에서 결제수단을 등록해요.
### 3. 활성화 확인하기
콜백과 상태 조회로 빌링키가 ACTIVE인지 확인해요.
### 4. 자동 결제 승인하기
활성화된 빌링키로 인증 없이 결제를 실행해요.
### 5. 빌링키 관리하기
상태 조회와 삭제, 삭제 콜백 대응까지 운영을 준비해요.
일반 결제를 아직 연동하지 않았다면 일반 결제 튜토리얼을 먼저 읽는 것을 추천해요. API Key 준비, 테스트 방법, 라이브 전환 등 공통 내용은 이 튜토리얼에서 반복하지 않아요.
---
# 1. 빌링키 생성하기
URL: /tutorial/billing-step-1
이 단계에서는 사용자를 식별하는 고유한 빌링키를 만들어요. 빌링키를 생성하면 사용자를 인증시킬 OS별 인증 URI를 함께 받고, 이 URI가 다음 단계의 재료가 돼요.
빌링키 생성 API Endpoint POST https://pay.toss.im/api/v1/billing-key
## 빌링키 생성 API 호출하기
가맹점 서버에서 다음과 같이 호출해요. 필수 파라미터 위주의 예제예요.
```
curl https://pay.toss.im/api/v1/billing-key \
-H "Content-Type: application/json" \
-d '{
"apiKey": "sk_test_w5lNQylNqa5lNQe013Nq",
"userId": "tutorial-user-001",
"productDesc": "프리미엄 멤버십 월 구독",
"resultCallback": "https://example-shop.com/api/billing/callback",
"returnSuccessUrl": "https://example-shop.com/billing/success",
"returnFailureUrl": "https://example-shop.com/billing/failure"
}'
```
| 파라미터 | 필수 | 설명 |
| apiKey | 필수 | 상점의 API Key예요. 이후 승인·조회·삭제 요청 모두 이 Key와 동일해야 해요. |
| userId | 필수 | 가맹점의 사용자 식별 값이에요. 가맹점 회원 아이디를 쓸 수 있고, 승인 정보와 매칭하기 위해 유니크한 값을 권장해요. |
| productDesc | 필수 | 토스 결제창에 표기될 자동 결제 상품명이에요. |
| resultCallback | 필수 | 사용자가 인증을 완료하면 결과를 받을 가맹점 서버 URL이에요. 보안상 HTTPS를 권장해요. |
| returnSuccessUrl | retAppScheme 없으면 필수 | 인증 성공 후 사용자를 이동시킬 가맹점 페이지예요. |
| returnFailureUrl | 선택 | 인증 실패 시 사용자를 이동시킬 가맹점 페이지예요. |
| retAppScheme | 선택 (App to App이면 권장) | 가맹점 자체 앱에서 등록하는 경우 인증 완료 후 앱으로 복귀시킬 앱 스킴이에요. iOS는 자동 앱 전환이 되지 않아 특히 필요해요. |
| displayId | 선택 | 같은 사용자로 빌링키를 여러 개 만들고 싶을 때 쓰는 다중 빌링키 식별 값이에요. |
전체 파라미터는 빌링키 생성 요청 레퍼런스에서 확인할 수 있어요.
## 응답 확인하기
생성에 성공하면 이렇게 응답해요.
```
{
"code": 0,
"billingKey": "example-billingKey",
"checkoutAndroidUri": "intent://pay/billingKey?billingKey=example-billingKey...#Intent;scheme=supertoss;package=viva.republica.toss;end",
"checkoutIosUri": "https://ul.toss.im?scheme=supertoss%3A%2F%2Fpay%2FbillingKey...",
"checkoutUri": "https://pay.toss.im/payfront/web/billing?billingKey=example-billingKey"
}
```
- billingKey는 이 사용자의 결제수단을 가리키는 고유 값이에요. 승인, 상태 조회, 삭제 모두 이 값으로 요청하니 userId와 함께 저장해 두세요.
- checkoutAndroidUri, checkoutIosUri, checkoutUri는 사용자를 인증시킬 URI예요. 다음 단계에서 사용자의 환경에 맞게 골라 사용해요.
이 시점의 빌링키는 아직 결제에 쓸 수 없는 CREATE(생성됨) 상태예요. 사용자가 인증을 완료해 ACTIVE가 되어야 승인할 수 있어요. 상태 전체는 개요의 빌링키 상태 표를 참고하세요.
한 상점에서 사용자당 빌링키는 하나만 허용돼요. 같은 userId로 다시 생성하면 새 빌링키가 발급되고, 상태 조회도 최신 빌링키 기준으로 응답해요. 결제수단을 여러 개 등록하려면 displayId로 구분하세요.
## 다음 단계
인증 URI를 받았으니 사용자를 토스 앱으로 보낼 차례예요. 2. 사용자 인증 받기로 이동하세요.
---
# 2. 사용자 인증 받기
URL: /tutorial/billing-step-2
이 단계에서는 사용자를 토스 앱으로 보내 자동 결제 등록을 인증받아요. 1단계에서 받은 인증 URI로 이동시키면, 결제수단 선택과 인증은 토스 앱이 진행해요.
## 환경에 맞는 인증 URI로 이동시키기
빌링키 생성 응답에는 인증 URI가 세 개 있어요. 사용자의 접속 환경을 판단해서 맞는 URI로 이동시키세요.
| 응답 필드 | 환경 | 동작 |
| checkoutAndroidUri | Android | intent:// 스킴으로 토스 앱을 직접 호출해요. |
| checkoutIosUri | iOS | 유니버설 링크로 토스 앱을 호출해요. |
| checkoutUri | PC 웹 등 그 외 | 토스페이 웹 페이지를 열어요. retAppScheme을 보냈다면 원링크(onelink)로 제공돼요. |
사용자는 토스 앱에서 자동 결제에 사용할 결제수단(토스머니, 카드)을 선택하고 인증을 완료해요. 인증이 끝나면 결제 생성 시 전달한 returnSuccessUrl(실패 시 returnFailureUrl)로 사용자가 이동해요.
curl로 따라 하는 중이라면, 응답의 checkoutUri를 토스 앱이 설치된 휴대폰 브라우저에서 열어 인증을 진행하면 돼요.
테스트도 본인 토스 앱으로 진행해요. 별도 테스트 계정이나 SDK를 제공하지 않으므로, 토스 앱을 설치하고 최신 버전으로 인증을 진행하세요. 테스트용 API Key로 생성한 빌링키는 승인해도 실제 출금이 일어나지 않아요.
가맹점 자체 앱(App to App)에서 등록한다면 retAppScheme을 함께 보내세요. 특히 iOS는 자동으로 앱 전환이 되지 않아서, 인증 완료 후 가맹점 앱으로 복귀시키려면 빌링키 생성 시 retAppScheme이 필요해요. 일반 결제의 App to App 안내와 같은 원리예요.
## 인증 완료를 화면 이동만으로 판단하지 않기
returnSuccessUrl 이동은 사용자를 완료 화면으로 보내는 용도예요. 빌링키가 실제로 활성화됐는지는 다음 단계에서 다루는 콜백 수신과 상태 조회로 확인해야 안전해요.
## 다음 단계
사용자가 인증을 마치면 토스가 가맹점 서버로 결과를 알려줘요. 3. 활성화 확인하기로 이동하세요.
---
# 3. 활성화 확인하기
URL: /tutorial/billing-step-3
이 단계에서는 빌링키가 결제에 쓸 수 있는 상태가 됐는지 확인해요. 사용자가 인증을 완료하면 토스가 1단계에서 전달한 resultCallback URL로 결과를 보내줘요.
## 활성화 콜백 받기
사용자가 등록을 성공적으로 마치면 토스 서버가 가맹점 콜백 URL로 POST 요청을 보내요. 핵심 필드는 다음과 같고, 카드 등록이면 카드 정보가, 토스머니면 계좌 정보가 함께 와요.
```
{
"action": "ACTIVATED",
"userId": "tutorial-user-001",
"billingKey": "example-billingKey",
"payMethod": "CARD"
}
```
- action이 ACTIVATED면 빌링키가 활성화된 거예요. 가맹점 DB에서 해당 userId의 구독 상태를 활성으로 바꾸면 돼요.
- 토스 쪽 사정으로 빌링키가 삭제되면 action: "REMOVED" 콜백이 올 수 있어요. 이 경우 구독을 중지하고 재등록을 안내해야 해요.
전체 페이로드는 빌링키 처리결과 callback 레퍼런스에서 확인할 수 있어요.
콜백에는 반드시 HTTP 200으로 응답하세요. 200 외의 응답은 미수신으로 간주해서 토스가 3분 간격으로 최대 4번 재시도해요. 등록 실패는 사용자의 재시도를 고려해 대부분 전달되지 않고, 재시도가 불가능한 실패(CI 불일치로 차단 등)만 실패 결과가 전달돼요.
## 상태 조회로 확인하기
콜백을 받지 못했거나 현재 상태를 직접 확인하고 싶다면 상태 조회 API를 사용해요. userId로 조회해요.
```
curl https://pay.toss.im/api/v1/billing-key/status \
-H "Content-Type: application/json" \
-d '{
"apiKey": "sk_test_w5lNQylNqa5lNQe013Nq",
"userId": "tutorial-user-001"
}'
```
응답의 status로 빌링키의 현재 상태를 알 수 있어요.
```
{
"code": 0,
"userId": "tutorial-user-001",
"billingKey": "example-billingKey",
"status": "ACTIVE",
"payMethod": "CARD"
}
```
status가 ACTIVE면 결제할 수 있는 상태예요. 인증이 아직 안 끝났다면 CREATE로, 등록에 실패했다면 FAIL로 응답돼요. 상태별 의미는 개요의 빌링키 상태 표를 참고하세요.
사용자가 토스 앱에서 결제수단을 바꾸면 payMethod가 업데이트될 수 있으니, 회원 관리 화면에 결제수단을 보여준다면 이 API로 최신 값을 확인하세요.
payMethod는 ACTIVE가 된 뒤에 확정돼요. 인증 전(CREATE) 상태에서도 기본값이 채워져 응답되니, 이 필드가 있다는 것만으로 결제수단 등록이 끝났다고 판단하지 마세요. 등록 완료 판단은 status로 해요.
## 다음 단계
ACTIVE를 확인했다면 이제 인증 없이 결제할 수 있어요. 4. 자동 결제 승인하기로 이동하세요.
---
# 4. 자동 결제 승인하기
URL: /tutorial/billing-step-4
이 단계에서는 활성화된 빌링키로 실제 결제를 실행해요. 매월 구독료를 청구하는 시점처럼 가맹점이 원하는 때에 승인 API를 호출하면 되고, 유효시간이나 횟수 제한이 없어요. 청구 주기 관리(매월 1일 청구 등)는 가맹점 서버의 스케줄러가 담당해요.
자동 결제 승인 API Endpoint POST https://pay.toss.im/api/v1/billing-key/bill
## 승인 API 호출하기
```
curl https://pay.toss.im/api/v1/billing-key/bill \
-H "Content-Type: application/json" \
-d '{
"apiKey": "sk_test_w5lNQylNqa5lNQe013Nq",
"billingKey": "example-billingKey",
"orderNo": "subscribe-2026-07-0001",
"productDesc": "프리미엄 멤버십 월 구독",
"amount": 9900,
"amountTaxFree": 0,
"spreadOut": 0,
"cashReceipt": true,
"cashReceiptTradeOption": "GENERAL",
"sendFailPush": true
}'
```
| 파라미터 | 필수 | 설명 |
| apiKey | 필수 | 빌링키 생성 때 사용한 API Key와 동일해야 해요. |
| billingKey | 필수 | 3단계에서 활성화를 확인한 빌링키예요. |
| orderNo | 필수 | 가맹점 주문번호예요. 유니크하게 관리하고, 허용 특수문자는 _ - : . ^ @ =예요. |
| productDesc | 필수 | 상품 설명이에요. |
| amount | 필수 | 결제 요청 금액이에요. |
| amountTaxFree | 필수 | 결제 금액 중 비과세 금액이에요. 없으면 0을 넣어요. |
| spreadOut | 필수 | 카드 할부 개월 수예요. 0이 일시불이고, 5만 원 미만은 일시불만 가능해요. |
| cashReceipt | 필수 | 토스 현금영수증 자동발행 사용 여부예요. |
| cashReceiptTradeOption | 필수 | 현금영수증 발행 유형이에요. GENERAL(일반), CULTURE(문화비), PUBLIC_TP(대중교통) 중 선택해요. |
| sendFailPush | 필수 | 결제 실패 시 사용자에게 실패 알림을 보낼지 여부예요. |
과세 금액 구성, 선승인 같은 선택 파라미터는 자동 결제 승인 요청 레퍼런스에서 확인할 수 있어요.
## 응답 확인하기
승인에 성공하면 결제 결과가 바로 응답으로 와요. 일반 결제와 달리 별도 콜백을 기다릴 필요 없이 이 응답으로 완료 처리하면 돼요.
```
{
"code": 0,
"mode": "TEST",
"payToken": "example-payToken",
"orderNo": "subscribe-2026-07-0001",
"payMethod": "CARD",
"amount": 9900,
"discountedAmount": 0,
"paidAmount": 9900,
"approvalTime": "2026-07-14 12:00:00",
"transactionId": "example-transaction-id"
}
```
- code가 0이면 성공이에요. 실패하면 code: -1과 함께 errorCode, msg가 전달되니 이 값으로 분기하세요.
- payToken은 이 결제 건의 고유 값이에요. 환불이나 결제 상태 조회는 일반 결제와 같은 API를 이 값으로 호출해요.
- mode가 TEST면 테스트용 API Key로 승인된 결제라 실제 출금이 없어요.
- 카드 결제면 카드 승인 정보(cardCompanyName, cardAuthorizationNo 등)가 함께 와요.
활성화 전에 승인하면 실패해요. 빌링키가 ACTIVE가 아닐 때 승인을 호출하면 COMMON_BILLING_KEY_NOT_FOUND("자동결제 정보를 찾을 수 없습니다") 에러가 응답돼요. 승인 전에 활성화 확인을 거치고, 실패 시 상태 조회로 원인을 확인하세요. 그 외 오류는 에러 코드를 참고하세요.
## 환불과 결제 조회
승인된 결제 건의 환불과 상태 조회는 일반 결제와 같은 API를 사용해요.
- 환불은 결제 환불하기에서 payToken으로 요청해요.
- 결제 건 상태는 결제 상태 알아보기로 조회해요.
## 다음 단계
결제까지 완주했어요. 마지막으로 빌링키 운영에 필요한 관리 기능을 알아봐요. 5. 빌링키 관리하기로 이동하세요.
---
# 5. 빌링키 관리하기
URL: /tutorial/billing-step-5
마지막 단계에서는 운영 중 필요한 빌링키 관리를 다뤄요. 사용자가 구독을 해지하면 빌링키를 삭제하고, 토스 쪽에서 삭제가 발생하는 경우에도 대응해야 해요.
## 빌링키 삭제하기
사용자가 구독을 해지하거나 탈퇴하면 빌링키를 삭제하세요. 삭제된 빌링키는 더 이상 자동 결제에 사용할 수 없어요.
```
curl https://pay.toss.im/api/v1/billing-key/remove \
-H "Content-Type: application/json" \
-d '{
"apiKey": "sk_test_w5lNQylNqa5lNQe013Nq",
"billingKey": "example-billingKey"
}'
```
응답의 code가 0이면 삭제 완료예요.
## 토스 쪽 삭제에 대응하기
토스 쪽에서 삭제가 발생하면 가맹점 콜백 URL로 action: "REMOVED" 콜백이 올 수 있어요. 이 콜백을 받으면 해당 사용자의 구독을 중지하고, 계속 이용하려면 재등록(1단계부터 다시)을 안내하세요.
승인 실패만으로 구독 상태를 판단하지 마세요. 콜백 유실 가능성도 있으니, 승인이 COMMON_BILLING_KEY_NOT_FOUND로 실패하면 상태 조회 API로 빌링키 상태를 확인해서 REMOVE, CANCEL이면 구독 중지 처리하는 방어 로직을 권장해요.
## 테스트와 라이브 전환
테스트 방법과 실거래용 API Key 전환은 일반 결제와 같아요. 6. 테스트와 라이브 전환하기를 참고하되, 자동 결제에서는 이 시나리오를 추가로 점검하세요.
- 빌링키 생성부터 인증, 활성화 콜백 수신, 승인까지 전체 흐름이 이어지는지 확인해요.
- 같은 orderNo로 중복 승인이 발생하지 않는지 확인해요.
- 삭제 후 승인이 실패하는지, REMOVED 콜백 처리가 동작하는지 확인해요.
- 승인 결제 건의 환불이 정상 동작하는지 확인해요.
## 더 알아보기
- 자동 결제 전체 API 명세는 자동 결제 API 레퍼런스를 참고하세요.
- 승인된 결제의 환불은 결제 환불하기를 참고하세요.
- API 오류 코드 목록은 에러 코드를 참고하세요.
---
# 결제 생성하기
URL: /guide/create
결제 생성 요청에 대해 좀 더 자세히 알아봅니다. 아래 예제는 결제 생성 API가 지원하는 모든 파라미터를 사용한 코드입니다.
## 예제 코드
```
curl https://pay.toss.im/api/v2/payments \
-H "Content-Type: application/json" \
-d '{
"orderNo": "1", # 토스몰 고유의 주문번호 (필수)
"amount": 25000, # 결제 금액 (필수)
"amountTaxFree": 0, # 비과세 금액 (필수)
"productDesc": "A티셔츠", # 상품 정보 (필수)
"apiKey": "sk_test_w5lNQylNqa5lNQe013Nq", # 상점의 API Key (필수)
"retUrl": "https://pay.toss.im/payfront/demo/completed?orderno=1", # 결제 완료 후 연결할 웹 URL (필수)
"retCancelUrl": "https://pay.toss.im/payfront/demo/cancel", # 결제 취소 시 연결할 웹 URL (필수)
"autoExecute": true, # 자동 승인 설정 (필수)
"resultCallback": "https://pay.toss.im/payfront/demo/callback", # 결제 결과 callback 웹 URL (필수-자동승인설정 true의 경우)
"callbackVersion": "V2", # callback 버전 (필수-자동승인설정 true의 경우)
"amountTaxable": 22727, # 결제 금액 중 과세금액
"amountVat": 2273, # 결제 금액 중 부가세
"amountServiceFee": 0, # 결제 금액 중 봉사료
"expiredTime": "2024-06-17 12:47:35", # 결제 만료 예정 시각
"cashReceipt": true # 현금영수증 발급 가능 여부
}'
```
## 결제 생성 API의 Endpoint
POST https://pay.toss.im/api/v2/payments
## 필수 Parameters
결제 생성 요청 시 반드시 아래 9가지 값을 함께 보내주셔야합니다.
- 상점 주문번호 : 추후 상점 주문 정보와 결제 정보를 매칭하기 위해 필요
- 결제 금액 : 손님으로부터 받을 금액
- 비과세 금액 : 손님으로부터 받을 금액중 비과세 금액
- 상품명 : 결제할 상품에 대한 정보
- 상점 API Key : 이곳에 '테스트용 API Key'를 넣으면 테스트 결제가, '실거래용 API Key'를 넣으면 진짜 출금되는 결제가 생성됩니다.
- 구매자 인증 완료 후 연결할 URL : 구매자가 결제를 확인하고 인증 완료하면 이 파라미터를 통해 설정한 URL로 구매자를 보내드립니다. 일반적으로 구매 완료 페이지 또는 구매 완료 페이지로 연결할 수 있는 곳을 지정합니다.
- 구매자가 결제 취소 시 연결할 URL : 구매자가 결제를 취소하면 이 파라미터를 통해 설정한 URL로 구매자를 보내드리고, 토스는 자동으로 해당 거래건을 취소처리 합니다. 상점에서 취소거래 구분이 필요하다면 자체적으로 거래구분 처리 해주세요.
- 자동 승인 설정 : 구매자가 인증을 완료하면 토스가 자동으로 승인을 진행합니다. 가맹점은 결과 값만 확인해 주시면 됩니다.
- 결제 결과 callback URL : 토스 서버가 출금을 성공하면 가맹점 서버로 결제 성공 callback을 요청합니다. 이후 가맹점에서는 결제완료 상태변경 등의 로직을 처리할 수 있습니다. (이 값은 자동 승인 설정이 'true'일 경우에만 필수 값입니다.)
## 모바일 웹뷰 결제 가이드
모바일 웹뷰 결제는 앱투앱(App to App) 이동이 필요합니다. 앱투앱 이동을 위해 필요한 준비사항은 다음과 같습니다.
### 안드로이드
#### Intent URI 사용
```
intent://pay?payToken={payToken}#Intent;scheme=supertoss;package=viva.republica.toss;end`
```
#### Intent URI 파싱 처리
가맹점 앱에서 Intent URI를 파싱하여 처리해야 합니다. 잘못된 Activity로 라우팅되지 않도록 아래와 같이 구현합니다.
```
val intent = Intent.parseUri(url, Intent.URI_INTENT_SCHEME).apply {
// URI를 브라우저에서 열 수 있도록 설정
addCategory(Intent.CATEGORY_BROWSABLE)
component = null
selector = null
}
try {
startActivity(intent)
} catch (_: ActivityNotFoundException) {
// 토스 앱 미설치 시 스토어로 이동
intent.`package`?.let { packageName ->
val marketIntent = Intent(Intent.ACTION_VIEW, Uri.parse("market://details?id=$packageName"))
startActivity(marketIntent)
}
}
```
### 아이폰(iOS)의 경우
#### Universal Link 사용
```
https://ul.toss.im?scheme=supertoss%3A%2F%2Fpay%3FpayToken%3D{payToken}
```
### 주의사항
#### 토스 앱 설치 여부 확인 및 처리
- ‘앱으로 결제하기’ 클릭 시, 앱 설치 유무를 체크합니다
- 설치되어 있는 경우: 앱을 호출
- 설치되어 있지 않은 경우: 앱스토어로 이동
#### iframe 사용 금지 권장
- 토스는 iframe 방식 호출을 공식적으로 지원하지 않습니다.
- 새 창을 띄워 호출하는 방식을 권장합니다.
## 결제 만료 기한 (expiredTime)
이 파라미터를 통해 '결제 생성 후, 언제까지 결제 승인을 진행할 수 있는지' 설정할 수 있습니다. '결제 대기' 상태인 결제건의 만료 기한이 도래하면 토스 서버에서 자동으로 결제를 취소합니다.
상점 혹은 판매 물품에 특성에 따라 결제 만료 기간을 길게 혹은 짧게 설정할 수 있습니다.
재고의 변동이 적고, 구매자의 결제가 급하지 않다면 결제 만료 기한을 길게 설정하세요. 구매자는 먼저 주문만 해두고 원하는 시점에 결제할 수 있습니다. 재고의 변동이 크거나 '결제 대기' 상태를 오래 지속하고싶지 않은 경우엔 결제 만료 기한을 짧게 설정하세요.
결제 만료 기한은 최대 60분이며, 따로 설정하지 않는 경우 기본 15분으로 설정됩니다.
## 현금영수증 발급 가능 여부 (cashReceipt)
현금영수증 발급 가능 여부를 설정할 수 있습니다. 카드결제 혹은 문화상품권이나 백화점상품권, 모바일 쿠폰 등 과세 대상에서 제외되는 유가증권 등의 상품은 현금영수증 발행이 불가하며, 토스 머니와 같이 현금성 결제건에 한하여 현금영수증 발행이 가능합니다.
- true : 현금영수증 발급 가능 (값을 설정하지 않으면 기본 true)
- false : 현금영수증 발급 불가
## 자동 승인 여부 (autoExecute)
토스페이에서는 두 가지 옵션을 제공합니다. 구매자 인증이 완료되면 토스에서 즉시 출금을 시도하고 결제를 완료시키는 방법과 구매 상품의 재고 상황에 따라 '최종 승인'의 주체가 가맹점이 될 수도 있습니다. 결제 상점의 판매 상품에 따라 두 가지 방식을 고려하여 옵션을 활용할 수 있습니다.
결제 생성 시, autoExecute를 'true'로 설정 : 구매자 인증완료 후 출금시도와 함께 결제완료 상태를 전달합니다.
결제 생성 시, autoExecute를 'false'로 설정 : 해당 결제건은 가맹점의 최종 승인 전까진 대기 상태에 머무르게 됩니다. (PAY_APPROVED 상태) 결제 승인 API를 통해 최종 승인 (execute API): PAY_APPROVED 상태의 결제건에 대해 승인을 요청하면 출금을 시도하고 출금 완료 시 결제 완료로 상태를 변경합니다. 이때 토스머니 잔액을 체크하고 잔고가 부족하다면 충전 후 출금됩니다.
아래 그림을 참고하세요.
## 복합과세 처리 (amount-)
전체 결제 금액 중 '비과세' 처리해야할 금액이 섞여있거나 부가세, 봉사료 비중을 원하는대로 설정하고 싶다면 결제 생성 시 '복합과세' 파라미터를 이용하세요.
- amountTaxable : 결제 금액 중 '과세금액' 비중
- amountTaxFree : 결제 금액 중 '비과세금액' 비중
- amountVat : 결제 금액 중 '부가세' 비중
- amountServiceFee : 결제 금액 중 '봉사료' 비중 토스에서는 총 금액과 비과세 금액만 필수로 체크하고 있습니다. 복합과세 설정이 필요하다면 네 가지 값을 설정해 주셔야 하며, 네 가지 값의 합은 총 결제 금액(amount)과 반드시 동일해야 합니다. 동일하지 않을 경우 에러가 발생합니다. 위 파라미터를 통해 설정한 값은 현금 영수증 발행 시 그대로 반영됩니다.
위 파라미터 값을 설정하지 않는 경우, 자동으로 아래와 같이 처리됩니다.
- 부가세 : 전체 금액(amount)을 11로 나눈 후 소수점 첫째 자리에서 올림
- 과세금액 : 전체 금액에서 부가세를 뺀 나머지 값
- 비과세금액, 봉사료 : 0 단, 현금영수증 발행 불가 결제(cashReceipt = false)인 경우, 아래와 같이 처리됩니다.
- 과세금액 : 전체 금액(amount)과 동일
- 부가세, 비과세금액, 봉사료 : 0
---
# 결제 승인하기
URL: /guide/excute
구매자 인증이 완료된 '대기' 상태에서 재고상태 확인 후 결제를 진행할 수 있습니다. 아래 예제는 승인 API가 지원하는 파라미터 중 일부를 사용한 코드입니다.
## 예제 코드
```
curl "https://pay.toss.im/api/v2/execute" \
-H "Content-Type: application/json" \
-d '{
"apiKey":"sk_test_w5lNQylNqa5lNQe013Nq", # 상점의 API Key (필수)
"payToken":"example-payToken", # 결제 고유 번호 (필수)
}'
```
## 결제 생성 API의 Endpoint
POST https://pay.toss.im/api/v2/execute
## 필수 Parameters
'결제 승인'의 필수 파라미터는 2가지 입니다. '어느 가맹점'에서 '어떤 결제건'을 승인하는지 알려주세요!
- 상점 API Key (apiKey) : 결제를 생성한 상점의 API Key가 필요합니다.
- 결제 고유 토큰 (payToken) : 결제 생성 완료 후 받은 결제 고유번호
---
# 결제 환불하기
URL: /guide/refund
결제 완료 건의 결제 금액 중 일부 또는 전부를 구매자에게 돌려줍니다. 환불 요청에 성공하는 즉시, 토스 머니로 결제된 거래건은 구매자의 계좌로 요청하신 금액이 입금되며, 카드결제 거래건은 승인취소 됩니다. 환불한 금액은 상점의 다음 정산에 반영됩니다.
아래 예제는 결제 환불 API가 지원하는 파라미터 중 일부를 사용한 코드입니다.
## 예제 코드
```
curl "https://pay.toss.im/api/v2/refunds" \
-H "Content-Type: application/json" \
-d '{
"apiKey":"sk_test_w5lNQylNqa5lNQe013Nq", # 상점의 API Key (필수)
"payToken":"example-payToken", # 결제 고유 번호 (필수)
"refundNo": "example-refundNo", # 환불 고유 번호 (필수, 반드시 랜덤 생성)
"amount":10000, # 환불할 금액 (선택, 미입력 시 남은 전액 환불 / 부분환불 시 필수)
"amountTaxable":5000, # 환불할 금액 중 과세금액
"amountTaxFree":4000, # 환불할 금액 중 비과세금액 (선택, 없으면 0)
"amountVat":500, # 환불할 금액 중 부가세
"amountServiceFee":500 # 환불할 금액 중 봉사료
}'
```
## 결제 생성 API의 Endpoint
POST https://pay.toss.im/api/v2/refunds
## 필수 Parameters
'결제 환불'의 필수 파라미터는 3가지 입니다.
- 상점 API Key (apiKey) : 결제를 생성한 상점의 API Key가 필요합니다.
- 결제 고유 토큰 (payToken) : 결제 생성 완료 후 받은 결제 고유번호
- 환불 번호 (refundNo) : 환불 고유 번호
## 선택 Parameters
### 환불할 금액 (amount)
총 결제 금액 중 일부만 환불하고자 하는 경우, 이 파라미터 값을 설정해주세요. 금액을 설정하지 않으면 남은 결제 금액 전액을 환불합니다. 부분환불 시에는 반드시 설정해야 합니다.
### 환불할 비과세 금액 (amountTaxFree)
환불할 금액 중 비과세 금액을 지정합니다. 없으면 0으로 처리됩니다.
### 환불 사유 (reason)
결제 환불 사유를 기록해야한다면 이 파라미터를 활용하세요. 최대 255자까지 남길 수 있습니다.
## 복합과세 결제 환불 처리
결제 생성 시, 세부 금액 구성(과세금액/비과세금액/부가세/봉사료)을 지정했다면, 환불 요청 시에도 반드시 어떤 부분에서 환불 처리할지 지정해야 합니다.
환불 요청하는 금액은 '남은 결제 금액'보다 작거나 같아야 하고, 환불할 세부 금액들의 총합은 반드시 전체 환불 금액(amount)과 동일해야 합니다. (다를 시 에러 발생)
---
# 결제 상태 알아보기
URL: /guide/check-status
결제가 생성되고 진행됨에 따라 결제의 '상태'는 끊임없이 바뀝니다. 상점 운영을 위해선 특정 결제건이 현재 어떤 상태인지 파악할 일이 많을 것입니다. 결제가 잘 끝난 것인지, 취소된 것은 아닌지. 환불 요청에 들어왔던 주문은 잘 환불 되었는지...
그럴땐 '결제 상태 확인 API'를 찾아주세요. 상황에 따라 승인,환불 응답을 수신하지 못한 경우에도 활용할 수 있습니다. 아래 예제는 결제 상태 확인 API 호출 코드입니다.
## 예제 코드
```
curl "https://pay.toss.im/api/v2/status" \
-H "Content-Type: application/json" \
-d '{
"apiKey":"sk_test_w5lNQylNqa5lNQe013Nq", # 상점의 API Key (필수)
"payToken":"example-payToken", # 결제 고유 번호 (필수)
}'
```
## 결제 생성 API의 Endpoint
POST https://pay.toss.im/api/v2/status
## 필수 Parameters
필수 파라미터는 딱 2가지 입니다. '어느 가맹점'에서 일어난 '어떤 결제건'을 조회하고 싶은지 알려주세요.
- 상점 API Key (apiKey) : 결제를 생성한 상점의 API Key가 필요합니다.
- 결제 고유 토큰 (payToken) : 결제 생성 완료 후 받은 결제 고유번호
- '결제 고유 토큰 (payToken)' 대신 '상점의 주문번호 (orderNo)'값을 사용할 수도 있습니다.
## 결제 상태 확인 요청에 대한 응답
결제 상태 확인 요청에 대한 응답은 아래와 같은 형태로 받게됩니다. 응답의 일부이며, 상세한 내용은 결제상태 API를 확인해주세요.
```
{
"code": 0, # 응답코드
"payToken": "example-payToken", # 결제 고유 토큰
"orderNo": "1", # 상점의 주문번호
"payStatus": "PAY_COMPLETE", # 결제 상태
"payMethod": "TOSS_MONEY", # 결제 수단
"amount": 15000, # 결제 요청금액
"transactions": [ # 거래 트랜잭션 목록
{
"stepType": "PAY",
"transactionId": "3243c76e-4669-881b-33a3b82ddf49",
"transactionAmount": 15000,
"discountAmount": 300,
"pointAmount": 0,
"paidAmount": 14700,
"regTs": "2020-03-01 12:33:20"
}
],
"createdTs": "2020-03-01 12:33:04", # 최초 결제요청 시간
"paidTs": "2020-03-01 12:33:20" # 결제 완료 처리 시간
}
```
각 항목은 다음과 같은 의미를 가지고 있습니다.
- 응답코드 : 요청에 대한 결과. 성공하면 '0' 입니다.
- 결제 고유 토큰 : 결제 생성 완료 후 받은 결제토큰. '주문번호'로 상태를 조회하면 이 값을 참조하여 '결제 고유번호 값을 알 수 있습니다.
- 상점의 주문번호 : 상점에서 사용하는 주문번호. 'payToken'으로 상태를 조회하면 이 값을 참조하여 '주문번호'를 알 수 있습니다.
- 결제 수단 : 구매자가 선택한 결제수단을 확인할 수 있습니다.
- 결제 상태 : 조회 당시의 결제 상태 (아래 '결제 상태 목록'을 참고하세요)
- 거래 트랜잭션 목록 : 조회 당시에 처리된 트랜잭션 목록(취소,환불 등)
- 최초 결제요청 시간 : 구매자가 최초 결제요청한 시간을 확인할 수 있습니다.
- 결제완료 처리 시간 : 요청에 대한 처리를 완료한 시간을 확인할 수 있습니다.
### 결제 상태 목록
결제 상태는 아래 중 하나입니다. 각 상태에 대한 자세한 설명은 API 명세서 > 결제 상태 문서를 참고하세요.
| 상태코드 | 상태명 |
| PAY_STANDBY | 결제 대기 중 |
| PAY_APPROVED | 구매자 인증 완료 |
| PAY_CANCEL | 결제 취소 |
| PAY_PROGRESS | 결제 진행 중 |
| PAY_COMPLETE | 결제 완료 |
| REFUND_PROGRESS | 환불 진행 중 |
| REFUND_SUCCESS | 환불 성공 |
| SETTLEMENT_COMPLETE | 정산 완료 |
| SETTLEMENT_REFUND_COMPLETE | 환불 정산 완료 |
---
# 신용카드 매출전표
URL: /guide/credit-check
## 1. 매출전표 확인을 위한 호출 URL
신용카드 매출전표를 확인하시려면 아래의 URL로 이동하시면 됩니다.
```
https://pay.toss.im/payfront/web/external/sales-check?payToken=example-payToken&transactionId=12637496-8a46-488c-bc30-febded96656f
```
### 필수 파라미터
필수 파라미터를 Query String 형식으로 추가하여 이용해 주세요.
- payToken: 거래 상태를 확인할 승인 건의 결제 토큰
- transactionId: 특정 트랜잭션 상태 확인
## 2. 매출전표 조회 제한 조건
### 지원 결제수단
신용카드 결제 건만 확인 가능합니다. 토스머니/계좌결제의 경우에는 현금영수증 발급 내역으로 확인해야 합니다.
### 확인 불가 상태
- PAY_APPROVED (구매자 인증 완료), PAY_CANCEL (결제 취소) 등의 미완료 거래 건은 조회할 수 없습니다.
## 3. 매출전표 URL 제공 방식
- 결제 승인 API 호출 시 응답값으로 salesCheckLinkUrl 필드가 포함됩니다.
- 이 URL은 신용카드 매출전표를 확인할 수 있는 링크입니다.
- 가맹점은 salesCheckLinkUrl을 활용해 신용카드 매출전표를 호출하고, 구매자가 추가 인증을 완료하면 매출전표를 확인할 수 있습니다.
## 4. 추가 인증 요구
구매자의 생년월일과 휴대폰번호로 추가 인증 절차가 필요합니다.
---
# 토스 은행 코드
URL: /guide/bank-code
토스머니 결제의 경우 사용자가 선택한 계좌의 정보를 함께 전달합니다.
| 은행 코드 (accountBankCode) | 은행 명 (accountBankName) |
| 002 | KDB산업은행 |
| 003 | IBK기업은행 |
| 004 | KB국민은행 |
| 005 | KEB하나은행 |
| 007 | 수협은행 |
| 011 | NH농협은행 |
| 020 | 우리은행 |
| 023 | SC은행 |
| 027 | 씨티은행 |
| 031 | 대구은행 |
| 032 | 부산은행 |
| 034 | 광주은행 |
| 035 | 제주은행 |
| 037 | 전북은행 |
| 039 | 경남은행 |
| 045 | MG새마을금고 |
| 048 | 신협 |
| 050 | 저축은행 |
| 064 | 산림조합 |
| 071 | 우체국 |
| 081 | 하나은행 |
| 088 | 신한은행 |
| 089 | 케이뱅크 |
| 090 | 카카오뱅크 |
| 092 | 토스뱅크 |
| 103 | SBI저축은행 |
| 218 | KB증권 |
| 230 | 미래에셋증권 |
| 238 | 미래에셋증권 |
| 240 | 삼성증권 |
| 243 | 한국투자증권 |
| 247 | NH투자증권 |
| 261 | 교보증권 |
| 262 | 하이투자증권 |
| 263 | 현대차투자증권 |
| 264 | 키움증권 |
| 265 | 이베스트증권 |
| 266 | SK증권 |
| 267 | 대신증권 |
| 269 | 한화투자증권 |
| 270 | 하나증권 |
| 271 | 토스증권 |
| 278 | 신한투자증권 |
| 279 | DB금융투자 |
| 280 | 유진투자 |
| 287 | 메리츠증권 |
| 888 | 토스머니 |
| 889 | 토스포인트 |
---
# 토스 카드(매입사) 코드
URL: /guide/card-code
토스에서 정의한 카드사 코드는 다음과 같습니다.
미지원 카드사는 현재 준비 중입니다. (매입 카드사 기준입니다.)
| 카드사 이름 | 카드(매입사) 코드 |
| 신한 | 1 |
| 현대 | 2 |
| 삼성 | 3 |
| 국민 | 4 |
| 롯데 | 5 |
| 하나 | 6 |
| 우리 | 7 |
| 농협 | 8 |
| 씨티(미지원) | 9 |
| 비씨(BC) | 10 |
---
# 결제 에러 응답코드
URL: /guide/error-code
- 토스페이 에러코드는 예고 없이 업데이트 될 수 있습니다. 추가되더라도 오류가 발생하지 않도록 연동 부탁드립니다.
- 토스에서는 한 가지 에러코드에 상황별로 다른 오류 메시지를 전달합니다.
여러 상황이 발생할 수 있으니 되도록이면 전달되는 오류 메시지 그대로를 처리해주세요.
## 공통
| 응답 코드 (errorCode) | 사유 (msg) |
| COMMON_SYSTEM_ERROR | 시스템 오류로 인해 통신이 원활하지 않습니다. 문제가 계속되면 토스 고객센터로 문의해주세요. (1599-4905) |
| COMMON_INVALID_PARAMETER | 요청한 값이 바르지 않습니다. |
| COMMON_PAY_ERROR | 문제가 발생하였습니다. |
| COMMON_NOT_ENOUGH_CASH | 충전계좌의 잔액이 부족하여 토스머니 충전이 불가합니다. |
| COMMON_EXCEED_LIMIT | 한도를 초과하였습니다. |
| COMMON_ASSET_GET_ACCOUNT_ERROR | 계좌 정보 조회에 실패하였습니다. |
| COMMON_REFUND_ERROR | 환불이 불가능한 상태입니다. |
| REFUND_REFUND_NO_DUPLICATE | 이미 환불 처리된 refundNo입니다. |
| PAYMENT_DUPLICATION_ORDER_NO | 중복된 주문번호입니다. |
| PAYMENT_EXISTING_PAYMENT | 이미 존재하는 결제입니다. |
| TRANSACTION_PENDING_ERROR | 조금 전 신청하신 결제가 아직 진행 중입니다. 잠시 후 다시 시도해 주세요. 10분 이상 지속되면 토스팀에 문의해 주세요. (1599-4905) |
| INVALID_ACCOUNT_STATUS | 계좌 상태를 확인해 주세요. |
| FRAUD_DETECTION_SYSTEM_ERROR | FDS에 의해 금융거래가 차단된 상태입니다. |
| USER_STATUS_ERROR | 결제 진행이 불가한 사용자입니다. |
| REFUND_ALREADY_REFUNDED | 이미 전액 환불 처리된 거래 건입니다. |
| TRANSACTION_NOT_COMPLETE | 거래가 완료되지 않았습니다. |
| TRANSACTION_NOT_FOUND | 존재하지 않는 거래내역입니다. |
| INACTIVE_USER | 비활성 처리된 사용자입니다. |
| AUTO_CHARGE_NOT_YET_REGISTER_ACCOUNT | 충전계좌가 등록되지 않았습니다. |
## USER (사용자)
| 응답 코드 (errorCode) | 사유 (msg) |
| PAY_UNAUTHORIZED | 결제 요청자와 토스의 계정이 일치해야만 결제가 가능합니다. 확인 후 다시 시도해 주세요. |
| TOSS_APP_UPDATE_IS_REQUIRED | 결제를 진행하려면 최신 버전의 토스 앱을 이용해 주세요. |
| PAY_CANCEL_ITS_NOT_CANCELABLE_STATUS | 결제를 취소할 수 없습니다. 잠시 후 다시 시도해 주세요. 문제가 계속되면 토스 고객센터로 문의해 주세요. (1599-4905) |
| COUPON_ASSIGN_FAIL | 쿠폰 발급에 실패하였습니다. |
| DISCOUNT_CLOSED | 할인 혜택이 마감되었습니다. |
| USER_DISCOUNT_CLOSED | 1인당 할인 횟수를 초과하였습니다. |
| DISCOUNT_NEED_ISSUE | 쿠폰을 발급받아 주세요. |
| DISCOUNT_ALREADY_ISSUED | 쿠폰이 이미 발급되었습니다. |
| AVAILABLE_ONLY_TOSS_MONEY_UNDER_MIN_AMT | %s원 미만 금액은 %s 카드 결제가 불가합니다. |
| AUTO_PAY_TERM_INACTIVE_FAIL | 약관 철회에 실패하였습니다. |
| AGE_POLICY_ERROR | %d세 미만인 경우 토스 %s 서비스를 이용하실 수 없습니다. |
| PAY_FRAUD_DETECTED | 일시적으로 토스 서비스를 이용할 수 없습니다. 문제가 계속되면 토스 고객센터로 문의해 주세요. (1599-4905) |
| BLOCKED_THE_USE_OF_POINT | 법원 압류 판결로 인해 토스 포인트를 쓸 수 없습니다. 궁금한 점은 토스 고객센터(1599-4905)로 문의해 주세요. |
## 카드
| 응답 코드 (errorCode) | 사유 (msg) |
| CARD_SYSTEM_ERROR | 카드사 시스템 점검 중입니다. 잠시 후 다시 시도해 주세요. |
| CARD_BANK_SYSTEM_ERROR | 카드사 거래은행 시스템 점검 중입니다. 잠시 후 다시 시도해 주세요 |
| CARD_NOT_AVAILABLE_SHOP | 해당 카드로 결제가 불가합니다. 다른 결제수단으로 시도하거나 토스 고객센터로 문의해 주세요. (1599-4905) |
| CARD_NOT_AVAILABLE | 도난/분실/거래 정지 카드로 승인이 거절되었습니다. |
| CARD_EXCEED_LIMIT | 사용 한도 초과로 승인이 거절되었습니다. |
| CARD_NOT_ENOUGH_BALANCE | 잔고 부족으로 승인이 거절되었습니다. |
| CARD_SPREADOUT_ERROR | 할부 사용이 불가능한 카드로 승인이 거절되었습니다. |
| CARD_MIN_AMOUNT_ERROR | 금액 오류 (100원 또는 1달러 미만 신용카드 승인 불가) |
| CARD_MIN_AMOUNT_FOR_SPREADOUT_ERROR | 할부 결제는 결제금액이 50,000원 이상이어야 합니다. 일시불로 결제해 주세요. |
## BNPL (후불결제)
| 응답 코드 (errorCode) | 사유 (msg) |
| BNPL_INVALID_REQUEST | 잘못된 요청입니다. |
| BNPL_NOT_EXIST_USER | 존재하지 않는 BNPL 사용자입니다. |
| BNPL_EXCEED_PAYABLE_AMOUNT | BNPL 한도가 초과되었습니다. |
| BNPL_ALREADY_COMPLETED_REQUEST | 이미 처리된 요청입니다. |
| BNPL_IN_PROGRESS_REQUEST | 이미 처리 중인 요청입니다. |
| BNPL_NOT_FOUND_PAYMENT | 존재하지 않는 결제건입니다. |
| BNPL_ALREADY_COMPLETED_REFUND | 환불할 수 없는 결제 건입니다. |
| NOT_SET_BNPL_PAYMENT_ACCOUNT | 후불결제 진행을 위해 납부계좌 설정이 필요합니다. |
## 매출전표
| 응답 코드 (errorCode) | 사유 (msg) |
| SALES_CHECK_NOT_FOUND_USER | 매출전표 조회를 위한 사용자 정보가 존재하지 않습니다. |
| SALES_CHECK_USER_AUTH_FAIL | 매출전표 조회를 위한 사용자 정보 인증에 실패하였습니다. |
| SALES_CHECK_USER_AUTH_DECRYPT_FAIL | 매출전표 조회를 위한 사용자 정보 복호화에 실패하였습니다. |
| SALES_CHECK_CARD_ONLY | 카드결제 건에 대해서만 매출전표 조회가 가능합니다. |
## 자동결제
| 응답 코드(errorCode) | 사유(msg) |
| NOT_SUPPORTED_BILLING_KEY_SHOP | 자동결제를 지원하지 않는 상점입니다. support-pay@toss.im으로 문의해주세요. |
| BILLING_KEY_ALREADY_ACTIVATED | 이미 활성화된 자동결제가 존재합니다. |
| BILLING_KEY_REGISTRATION_CANCELLED | 자동결제 등록이 취소되었습니다. |
| BILLING_KEY_UNREGISTERED_BY_CANCEL | 이미 자동결제 등록이 취소되어 더 이상 진행할 수 없습니다. 처음부터 다시 진행해주세요. |
| BILLING_KEY_AUTH_ERROR | 해당 정기결제 건은 인증 가능한 상태가 아닙니다. |
| BILLING_KEY_EXPIRED_AUTH_TIME | 인증 가능 시간이 만료되었습니다. |
| BILLING_KEY_USER_CI_ERROR | 토스에 등록된 사용자 정보가 일치하지 않습니다. |
| BILLING_KEY_REMOVE_NOT_ALLOWED_SHOP | 자동결제 삭제가 허용된 가맹점이 아닙니다. |
| ALREADY_EXISTED_AUTH | 이미 요청된 인증이 존재합니다. |
| NOT_SUPPORTED_PAYMENT_METHOD | 자동결제에서 지원하지 않는 결제 수단입니다. |
| EXIST_ACTIVATED_BILLING_KEY_USING_THIS_METHOD | 자동결제가 등록된 결제 수단은 삭제할 수 없습니다. 자동결제를 해지해주세요. |
| COMMON_BILLING_KEY_NOT_FOUND | 자동결제 정보를 찾을 수 없습니다. |
| COMMON_NOT_ENOUGH_CASH | 자동충전 금액을 늘리거나 토스머니에 잔액을 충전해주세요. |
| COMMON_INVALID_PARAMETER | 요청한 값이 바르지 않습니다. |
| COMMON_SYSTEM_ERROR | 이미 처리가 진행 중입니다. 잠시 후 다시 시도해주세요. |
| COMMON_INVALID_API_KEY | 바르지 않은 API key입니다. |
| CORE_USER_ERROR | 사용자가 존재하지 않습니다. |
## 리셀러
| 응답 코드 (errorCode) | 사유 (msg) |
| COMMON_PAY_RESELLER_ERROR | 리셀러 결제 처리 중 에러가 발생했습니다. |
| RESELLER_ONLY_CARD_PAYMENT | 카드 결제가 아닙니다. |
| RESELLER_CALLBACK_PROCESS_ERROR | 리셀러 콜백 처리 중 에러가 발생했습니다. |
| NOT_APPROVED_CARD_PAYMENT | 카드로 사용자 승인된 결제가 아닙니다. |
| PAY_CARD_AUTH_REQUEST_ERROR | 카드 인증 요청에 실패하였습니다. |
| NOT_SUPPORTED_RESELLER_SHOP | 리셀러로 지정된 가맹점이 아닙니다. |
## 기타
| 응답 코드 (errorCode) | 사유 (msg) |
| PAYMENT_SHOP_STATE_NOT_NORMAL | 결제 불가 가맹점입니다. 가맹점 고객센터로 문의해 주세요. |
| PAYMENT_SHOP_STATE_CANNOT_REFUND | 결제 불가 가맹점입니다. 가맹점 고객센터로 문의해 주세요. (사고 신고) |
| COMMON_INVALID_API_KEY | 바르지 않은 API key입니다. |
| NOT_INTERNAL_SHOP | 내부 가맹점이 아닙니다. |
| COMMON_BREAK_TIME_OF_BANK | 지금은 은행 점검 시간입니다. 점검이 끝난 후 사용해 주세요. |
| COMMON_UNAUTHORIZED | Unauthorized Access |
| REFUND_EXCEED_DAILY | 환불 금액이 상점의 일일 환불 한도보다 클 수 없습니다. |
| EXECUTE_PAY_NOT_APPROVED | 아직 구매자가 결제를 승인하지 않았습니다. |
| PAUSE_USER | 일시정지 사용자입니다. |
| COMMON_TIMEOUT | 처리 중 지연이 발생하였습니다. 다시 시도해 주세요. |
| COMMON_THROTTLED | 결제 요청이 많아 서비스 이용이 원활하지 않습니다. 잠시 후에 다시 시도해 주세요. |
| COMMON_ITS_NOT_ABLE_TO_CHANGE_STATUS | 요청 가능한 상태가 아닙니다. |
| ESCROW_IMPOSSIBLE_STATUS | 에스크로 상태 변경이 불가능합니다. |
## 현금영수증
| 응답 코드 (errorCode) | 사유 (msg) |
| CASH_RECEIPT_JOIN_MEMBER_FAIL | 현금영수증 연동회원 신규가입이 실패하였습니다. |
| CASH_RECEIPT_REGIST_ISSUE_FAIL | 현금영수증을 발행하지 못했습니다. |
| CASH_RECEIPT_ALREADY_ISSUE_FAIL | 현금영수증이 이미 발행 되었습니다. |
| CASH_RECEIPT_ALREADY_CANCEL_FAIL | 현금영수증이 이미 취소 되었습니다. |
| CASH_RECEIPT_ISSUE_IN_PROGRESS | 현금영수증 발행 진행 중 입니다. |
| CASH_RECEIPT_CANCEL_ISSUE_FAIL | 현금영수증 발행 취소를 하지 못했습니다. |
| CASH_RECEIPT_REVOKE_REGIST_ISSUE_FAIL | 취소 현금영수증을 발행하지 못했습니다. |
| CASH_RECEIPT_GET_INFO_FAIL | 현금영수증 정보 확인에 실패하였습니다. |
| CASH_RECEIPT_NOT_EXIST | 발급된 현금영수증이 존재하지 않습니다. |
| CASH_RECEIPT_GET_POPUP_URI_FAIL | 현금영수증 조회 링크를 가져오지 못했습니다. |
| CASH_RECEIPT_UNKNOWN_STATUS_CODE | 존재하지 않는 현금영수증 상태코드 입니다. |
| CASH_RECEIPT_CANNOT_ISSUE_CARD | 카드 결제는 현금영수증을 발행할 수 없습니다. |
| CASH_RECEIPT_MAINTENANCE_TIME | 현금 영수증 서비스 점검 시간입니다. |
| CASH_RECEIPT_INVALID_USER_INFO | 잘못된 식별번호입니다. |
| CASH_RECEIPT_INVALID_PARAMETER | 요청 값이 잘못되었습니다. |
| NOT_SUPPORTED_CASH_RECEIPT_AGENCY | 지원하지 않는 현금영수증 발행처입니다. |
---
# 토스페이 API 소개
URL: /reference
토스를 통한 결제 서비스를 사용하기 위한 API입니다. 토스페이를 활용한 개발을 처음 시작하신다면, 좀 더 친절한 안내를 먼저 확인해보세요! '토스페이 시작하기' 문서로 바로가기
토스페이 개발 가이드는 수시로 업데이트 됩니다. 사전 예고없이 업데이트 될 수 있으니 지속적으로 확인해 주시길 부탁드립니다.
토스페이는 결제 과정 중의 보안을 위해 pay.toss.im의 결제 API HTTPS는 TLS v1.2 이상만을 지원합니다. SSL은 필수이며 적용이 되어 있지 않은 서버에서는 이용이 불가합니다.
## 지원 브라우저
토스페이 서비스를 지원하는 브라우저는 다음과 같습니다.
PC 브라우저, Android, iOS 모두 TLS 1.2 이상의 환경에서 동작이 가능하며, 디바이스 같은 경우 토스 앱의 최소 지원 버전 기준입니다. 토스 앱 최신버전이 아닌 경우, 결제 진행이 원활하지 않을 수 있으니 가급적 최신 버전의 토스앱을 이용해 주시길 부탁드립니다.
- Safari 12, Chrome 64, Firefox 67, Opera 51, Edge 79 부터 지원
- Android 7.0 Nougat 부터 지원
- iOS 16 부터 지원
- Java 를 사용하시는 경우, jdk 1.8 이상 버전 사용을 권장합니다
토스페이는 iframe 방식을 공식적으로 지원하지 않습니다. iframe 방식을 이용하는 경우 결제가 원활하지 않을 수 있으므로 페이지 전환방식의 연동을 권장드립니다.
또한, 토스페이는 기본적으로 Server to Server 호출 방식을 지향합니다. 웹 브라우저를 통하여 클라이언트 단에서 토스 도메인으로 직접 결제 API를 호출하는 방식을 사용할 경우, 결제와 관련된 데이터가 외부에 노출되어 보안사고가 발생할 수 있으니 유의해 주시길 부탁드립니다.
## 결제 요청 헤더 안내
안정적인 결제 처리를 위해, 결제 요청 시 아래 사항을 지켜주시기 바랍니다.
- 필수 헤더만 포함해 주세요. (Authorization, Content-Type 등)
- 인증 및 세션 유지에 필요한 쿠키 외에는 포함하지 않는 것을 권장합니다.
- 전체 Request Header 크기는 8KB 이하로 유지해 주세요.
결제 요청 헤더의 크기가 8KB 이상이라면, HTTP 431 (Request Header Fields Too Large) 오류가 발생합니다. 이 경우 요청이 토스 시스템까지 도달하지 않아 결제 실패로 이어집니다. 결제 요청의 안정성을 위해 반드시 요청 구조를 점검해 주세요.
## 결제 상태
결제 건이 생성된 후, 결제가 진행됨에 따라 결제 상태가 변경되며, 각 결제 상태마다 판매자 또는 구매자가 요청할 수 있는 행동도 변합니다. 아래는 결제 상태 목록과 각 상태에 대한 설명입니다.
| 결제 상태 코드 | 상태명 | 설명 |
| PAY_STANDBY | 결제 대기 중 | 결제 건이 생성되었고, 구매자의 결제 진행을 대기 중인 상태. 이 상태에서 구매자나 가맹점이 결제를 취소할 수 있습니다. 또한 설정한 '만료 기간'이 도래하면 자동으로 취소됩니다. |
| PAY_APPROVED | 구매자 인증 완료 | 결제를 위한 구매자 인증 완료되고, 가맹점의 최종 승인을 기다리는 상태. ('autoExecute'를 false로 설정한 경우에만 이 단계를 거칩니다. 이 상태에서도 설정한 결제 '유효기간이 만료'되면 자동으로 취소처리 됩니다.) |
| PAY_CANCEL | 결제 취소 | 결제가 완료되기 전에 구매자가 결제를 취소하거나 유효기간이 만료된 거래. (금액 이동 없이 종료된 건) |
| PAY_PROGRESS | 결제 진행 중 | 구매자가 결제를 승인하여 구매자의 계좌에서 결제 금액을 출금 처리 중인 상태입니다. |
| PAY_COMPLETE | 결제 완료 | 구매자 및 가맹점의 결제 승인 및 출금이 정상적으로 완료된 상태입니다. |
| REFUND_PROGRESS | 환불 진행 중 | 전액 또는 부분 환불을 진행 중인 상태로, 완료되기 전까지 다른 환불을 진행할 수 없습니다. |
| REFUND_SUCCESS | 환불 성공 | 전액 또는 부분 환불이 완료되어, 환불 처리한 금액이 구매자의 계좌로 입금 완료된 상태입니다. |
| SETTLEMENT_COMPLETE | 정산 완료 | 결제 완료된 금액에 대해 정산이 완료되어 더 이상 환불이 불가한 상태입니다. (승인일 또는 구매 확정일로부터 1년 경과) |
| SETTLEMENT_REFUND_COMPLETE | 환불 정산 완료 | 전액 또는 부분 환불에 대한 정산이 완료되어 더 이상 환불이 불가한 상태입니다. (승인일 또는 구매 확정일로부터 1년 경과했거나 전액 환불에 대한 정산 완료된 경우) |
## HTTP 응답 코드
| HTTP 응답 코드 | 응답 이름 | 설명 |
| 200 | OK | 정상 |
| 400 | Bad Request | 파라미터 오류 |
| 401 | Unauthorized | 가맹점 API Key 오류 |
| 404 | Not Found | 존재하지 않는 요청 |
| 50x | Server Error | 서버 오류 |
---
# 결제 생성
URL: /reference/normal/create
결제 건을 생성합니다.
결제 생성 완료 후, 구매자의 결제 인증을 얻어 완료처리하는 방법은 토스페이 시작하기 > 3. 결제창 연결하기를 참고하세요.
각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.
POST https://pay.toss.im/api/v2/payments
### 요청 파라미터
apiKey string 필수
가맹점 API Key. 웹 브라우저 혹은 외부에 노출되지 않도록 유의해 주시기 바랍니다. 테스트가 완료되면 운영 오픈 전 반드시 '실거래용 API Key'로 변경 후 체크해주세요!
최대 30자
orderNo string 필수
가맹점의 상품 주문번호. 주문번호는 반드시 가맹점별로 매회 유니크해야 하며, 중복될 경우 결제 생성 요청이 실패합니다. 숫자, 영문자, 특수문자 _-:.^@만 사용 가능하며, 50자 이내여야 합니다. 동일 주문번호는 구매자 인증 완료(PAY_APPROVED) 이후 절대 재사용이 불가합니다. 최초 생성 후 2년이 지난 주문번호는 재사용할 수 없습니다. 테스트 환경과 라이브 환경 간의 주문번호 충돌 방지를 위해 가맹점 관리가 필요합니다.
최대 50자 패턴: ^[\w-:.^@]+$
productDesc string 필수
상품 설명. 상품 설명은 공백으로만 설정할 수 없고, 백슬래시("\")와 따옴표(",")를 포함할 수 없으며 총 255자 이내여야 합니다. 이 값에 한글이 포함되었다면 인코딩에 유의해주세요.
최대 255자
retUrl string 필수
구매자 인증완료 후 연결할 가맹점 웹페이지 URL. 사용자 인증이 완료되는 시점에 인증 데이터와 함께 결제완료 페이지로 이동시킵니다. 이 때, 전달되는 인증 데이터는 아래 링크에서 확인해 보실 수 있습니다. (단, 전달되는 인증 데이터는 결제수단 별로 차이가 있을 수 있습니다.)
최대 255자
retCancelUrl string 필수
토스페이창에 진입한 사용자가 결제를 중단할 때 사용자를 이동시킬 가맹점 취소 페이지. 이 값을 사용하면 토스 서버가 retCancelUrl 을 실행시킬 취소 버튼을 생성하고, 구매자는 브라우저나 앱을 강제로 종료하지 않고 가맹점의 취소 페이지로 이동할 수 있습니다. 구매자 편의를 위하여 반드시 활용해주세요!
최대 255자
amount integer (int64) 필수
총 결제 금액. 카드 결제를 지원하는 가맹점은 최대 10억 원까지, 카드 결제를 지원하지 않는 가맹점은 최대 200만 원까지만 결제 가능합니다. 일부 고액·현금성 상품은 카드사·은행의 1회 한도가 더 낮을 수 있으며, 이 경우 결제가 실패할 수 있습니다.
최대 10자 최소값 1
amountTaxable integer (int64)
결제 금액 중 과세 금액. 별도의 과세액을 설정하지 않고, 비과세 금액을 0원으로 보내주시면 토스페이 서버에서 자동으로 과세와 부가세를 계산합니다.
최대 10자
amountVat integer (int64)
결제 금액 중 부가세. 값이 없으면 환불할 과세 금액을 11로 나눈 후 소수점 첫째 자리에서 올림으로 계산합니다.
최대 10자
amountTaxFree integer (int64) 필수
결제 금액 중 비과세 금액. 판매하시는 상품이 과세 품목이면 해당 값을 0으로 보내주세요. 비과세액은 필수 값이니 빈 값으로 보내주시는 경우 에러가 발생합니다.
최대 10자
amountServiceFee integer (int64)
결제 금액 중 봉사료
최대 10자
disposableCupDeposit integer (int64)
일회용컵 보증금. 결제 금액 중 일회용컵 보증금 금액입니다. 일회용컵 보증금이 포함된 결제는 부분취소가 불가능합니다.
최대 10자
cashReceipt boolean
현금영수증 발급 가능 여부. 현금영수증 기능을 활용하시는 경우 true, 미사용의 경우 false로 선언해 주시기 바랍니다.
cashReceiptTradeOption string
현금영수증 발급 타입. CULTURE: 문화비, GENERAL: 일반 (기본값), PUBLIC_TP: 교통비
가능한 값:
GENERAL CULTURE PUBLIC_TP
resultCallback string
결제 결과 콜백 URL. 자동 승인 설정(autoExecute=true) 시 ResultCallback 구현이 필수이며, 결제 상태 확인을 위해 모든 가맹점에 사용을 권장합니다. 결제 결과를 수신할 가맹점의 외부에서 접근 가능한 URL이어야 하며, localhost, 192.168.x.x 등 내부망 도메인 및 사설 IP는 사용할 수 없습니다.
최대 500자
retAppScheme string
결제 완료 후 연결할 가맹점 측 앱 스킴 값. 가맹점의 결제 구현환경이 App to App인 경우 retAppScheme 값을 선언해 주시면 토스페이 완료 후 가맹점 앱으로 redirect 할 수 있습니다. iOS 앱 결제의 경우 필수 구현을 권장합니다. iOS 특성 상, 자동 앱 전환이 되지 않기 때문에 가맹점 앱 스킴 값을 이 곳에 선언해 주셔야 인증 후 가맹점 앱으로 랜딩됩니다. safari 등 모바일 웹 브라우저에서 자동 전환되지 않는 이슈는 OS 이슈인 점 참고 부탁드립니다. (Ex. testshop://)
최대 255자 패턴: ^$|^[a-zA-Z]*[0-9a-zA-Z\-.]*:.*
expiredTime string
결제 만료 기한 (기본값 15분, 최대 60분 설정 가능). 형식: YYYY-MM-DD HH:MM:SS
최대 20자
autoExecute boolean
자동 승인 여부 설정. 가맹점의 판매 상품에 따라 '자동 승인 설정' 을 활용할 수 있습니다. true 를 선언한 경우 resultCallback 을 필수 값으로 체크합니다.
installment string
할부 제한 타입. USE: 할부 사용 (기본값), NOT_USE: 할부 미사용
가능한 값:
USE NOT_USE INSTALLMENT_ONLY
enablePayMethods string
결제수단 구분 변수. TOSS_MONEY: 토스머니만 노출, CARD: 카드만 노출, null 또는 그 외의 값: 상점에 설정된 기본 결제수단으로 노출
최대 100자
callbackVersion string
결제 결과 콜백 버전. 콜백 버전에 따라 전달되는 응답 값이 다를 수 있으니 최신 버전(V2) 이용을 권장합니다. 이 값이 포함되지 않을 경우 승인 콜백은 V1 버전의 데이터가 전달됩니다. V1: 콜백 데이터를 파라미터 형식으로 전달 (application/x-www-form-urlencoded). V2: 콜백 데이터를 JSON 형식으로 전달.
가능한 값:
NONE V1 V2
### 응답 파라미터
code integer (int32)
응답코드. 0: 성공, -1: 실패 (실패 사유는 msg와 errorCode로 제공)
errorCode string
에러 코드
msg string
응답이 성공이 아닌 경우 설명 메시지
status integer (int32)
HTTP 상태 코드
payToken string
토스페이 토큰. 매회 유니크한 토큰 값이 생성됩니다.
최대 30자
checkoutPage string
결제를 진행할 수 있는 토스페이 웹페이지 URL
최대 255자
### 요청 예제
### 응답 예제
---
# 결제 결과 callback (resultCallback)
URL: /reference/normal/result-callback
결제 처리가 완료되면 결제 상태가 변경되고, 토스는 가맹점 서버로 변경 사항을 알려드립니다.
결제완료 callback을 받았을 때, 결제완료 상태를 변경하시고 재고차감 등의 로직을 처리해 주세요. 자동 승인 설정 시 (autoExecute가 true) 필수적으로 활용해야 합니다.
- callback 연동 전, 방화벽 정보를 반드시 확인해 주세요!
- 생성된 결제 건에 resultCallback 파라미터 값이 있을 경우에만 동작합니다.
- 아래는 callback V2버전이며, 가맹점 측에서는 최신버전의 callback 을 이용해 주시길 부탁드립니다. (callbackVersion 설명참고)
- V1 버전일 경우 결제완료 시 status값이 PAY_SUCCESS로 응답됩니다.
각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.
## 파라미터
status string
결제 상태. `PAY_COMPLETE` 결제 완료 환불 등 '결제 완료' 이외 상태는 전달되지 않습니다.
최대 길이: 20
payToken string
승인된 결제 토큰. 승인된 결제 토큰입니다.
최대 길이: 30
orderNo string
결제생성 구간에서 전달된 가맹점 주문번호. 결제 생성 시 전달된 가맹점 주문번호입니다.
최대 길이: 50
payMethod string
승인된 결제수단. 승인된 결제수단입니다. 카드 승인 건의 경우, 카드 데이터가 함께 포함되어 전달됩니다.
최대 길이: 10
가능한 값:
TOSS_MONEY 토스머니
CARD 카드
amount integer
결제요청된 금액. 최초 가맹점에서 결제 요청된 금액이 반환됩니다.
최대 길이: 10
discountedAmount integer
할인된 금액. 할인된 금액이 반환되며, 할인 적용이 없으면 0으로 반환됩니다. 할인 금액에는 토스 앱에서 자동 적용되는 즉시할인과 토스 포인트 사용 금액이 포함됩니다. 결제 상점에 따라 할인 조건은 차이가 있을 수 있습니다.
최대 길이: 10
paidAmount integer
지불수단 승인금액. 총 금액 중 할인된 금액을 제외한 순수 지불수단 승인금액입니다. 현금영수증 자체 발행을 사용하는 가맹점은 이 값으로 발행 처리해 주시면 됩니다.
최대 길이: 10
paidTs string
결제 완료 처리 시간. 결제 완료 처리 시간입니다. 형식: YYYY-MM-DD HH:MM:SS (예: 2020-04-03 14:22:37)
최대 길이: 20
transactionId string
거래 트랜잭션 아이디. 결제의 거래 구분을 위하여 토스 서버에서 유니크한 값을 생성하여 전달드립니다.
최대 길이: 36
cardCompanyCode integer
승인된 카드사 코드. 승인된 카드사 코드입니다. [카드 코드](/guide/card-code)를 참조해주세요.
최대 길이: 2
cardAuthorizationNo string
카드 승인번호. 카드 승인번호입니다.
최대 길이: 8
spreadOut string
사용자가 선택한 카드 할부개월. 5만원 미만 금액 및 일시불 결제의 경우 0으로 리턴됩니다.
최대 길이: 8
noInterest boolean
카드 무이자 적용 여부. 카드 무이자 적용 여부입니다.
최대 길이: 5
가능한 값:
true 무이자
false 일반
cardMethodType string
카드 타입. 승인된 카드의 타입을 구분할 수 있습니다.
최대 길이: 10
가능한 값:
CREDIT 신용카드
CHECK 체크카드
PREPAYMENT 선불카드
cardNumber string
마스킹된 카드번호. 카드번호 16자리 중 중간자리는 마스킹됩니다.
최대 길이: 20
cardUserType string
카드 사용자 구분. 카드 사용자 구분입니다.
최대 길이: 20
가능한 값:
PERSONAL 본인 카드
PERSONAL_FAMILY 가족 카드
CORP_PERSONAL 법인지정 결제계좌 임직원
CORP_PRIVATE 법인 공용
CORP_COMPANY 법인지정 결제계좌 회사(하나카드만)
cardBinNumber string
카드 BIN 번호. 카드사에서 제공한 카드 BIN 번호입니다 (마스킹되어 있을 수 있습니다). 100% 신뢰는 불가합니다.
최대 길이: 8
cardNum4Print string
사용자가 선택한 카드의 끝 4자리. 사용자가 선택한 카드의 끝 4자리입니다. 사용자가 선택한 결제수단(`payMethod`)이 'CARD'인 경우 카드번호 끝 4자리를 전달합니다 (카드사에 따라 마스킹이 포함되어 있을 수 있습니다).
최대 길이: 4
salesCheckLinkUrl string
신용카드 매출전표 호출 URL. 승인된 카드 결제 건의 매출전표를 확인할 수 있는 URL입니다.
최대 길이: 255
accountBankCode string
은행 코드. 사용자가 선택한 결제수단(`payMethod`)이 'TOSS_MONEY'인 경우 토스가 정의한 은행 코드를 전달합니다.
최대 길이: 3
accountBankName string
은행 명. 은행 명입니다. [은행코드 리스트](/guide/bank-code)
최대 길이: 20
accountNumber string
계좌번호. 계좌번호는 일부 마스킹을 포함하고 있습니다.
최대 길이: 30
## HTTP 응답 코드
| 코드 | 설명 |
| 200 | OK : 정상 |
| 400 | Bad Request : 파라미터 오류 |
| 401 | Unauthorized : 가맹점 API Key 오류 |
| 404 | Not Found : 존재하지 않는 요청 |
| 50x | Server error : 서버 오류 |
| xxx | Server error : 기타 등등 |
## 예제
Example Response
```
POST https://pay.toss.im/payfront/demo/callback (결제 생성 시 가맹점에서 설정한 callback URL)
Content-Type application/json;charset=UTF-8
{
"status": "PAY_COMPLETE",
"payToken": "example-payToken",
"orderNo": "1",
"payMethod": "CARD",
"amount": 3000,
"discountedAmount": 600,
"paidAmount": 2300,
"paidTs": "2020-04-03 14:22:37",
"transactionId" : "dc3b951a-9781-462e-ab5a-b8a0bea0222a",
"cardCompanyCode": 3,
"cardAuthorizationNo": "87654321",
"spreadOut": 0,
"noInterest": false,
"cardMethodType": "CREDIT",
"cardUserType": "PERSONAL",
"cardNumber": "654321******1234",
"cardBinNumber": "654321",
"cardNum4Print": "1234",
"salesCheckLinkUrl": "https://pay.toss.im/payfront/web/external/sales-check?payToken=example-payToken&transactionId=2da1ca05-d91d-410f-976d-7a610242da8a",
//"paidPoint": 0, // 2020.08.06 이후 fadeout 된 레거시 포인트 금액으로 0원으로 나감
}
```
---
# 가맹점 결제 승인
URL: /reference/normal/execute
자동 승인 설정을 false로 사용하는 가맹점에서만 처리하는 로직입니다.
구매자 인증 완료 상태(PAY_APPROVED)의 결제 건을 가맹점이 주체가 되어 최종 승인하고 결제를 완료 처리합니다.
결제 승인에 관한 자세한 내용은 아래 문서를 참고하세요. 토스페이 시작하기 > 결제 승인하기
필수 파라미터는 딱 2가지 입니다. '어느 가맹점'에서 '어떤 결제건'을 최종 승인할지 알려주세요. 필요에 따라 결제건의 유효성 검증을 할 수 있습니다.
각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.
POST https://pay.toss.im/api/v2/execute
### 요청 파라미터
apiKey string 필수
가맹점 API Key. 웹 브라우저 혹은 외부에 노출되지 않도록 유의해 주시기 바랍니다.
최대 30자
payToken string 필수
토스페이 토큰 (승인할 결제 건의 토큰값)
최대 30자
orderNo string
가맹점의 상품 주문번호. 주문번호는 반드시 가맹점별로 매회 유니크해야 하며, 중복될 경우 결제 생성 요청이 실패합니다. 숫자, 영문자, 특수문자 _-:.^@만 사용 가능하며, 50자 이내여야 합니다.
최대 50자
amount integer (int64)
결제 금액
### 응답 파라미터
code integer (int32)
응답코드. 0: 성공, -1: 실패 (실패 사유는 msg와 errorCode로 제공)
errorCode string
에러 코드
msg string
응답이 성공이 아닌 경우 설명 메시지
mode string
결제환경. LIVE: 실거래용, TEST: 테스트용
최대 4자
가능한 값:
TEST LIVE
orderNo string
승인된 상품 주문번호
최대 50자
amount integer (int64)
상품금액. 결제 생성 시 요청된 총 금액
최대 10자
approvalTime string
결제건의 승인 처리 시간 (yyyy-MM-dd HH:mm:ss)
최대 20자
stateMsg string
상태 응답 텍스트 값
최대 120자
discountedAmount integer (int64)
할인된 금액. 할인 적용이 없으면 0. 토스 앱 즉시할인과 토스 포인트 사용금액 포함
최대 10자
paidAmount integer (int64)
지불수단 승인금액. 총 금액 중 할인금액 제외한 순수 지불금액
최대 10자
payMethod string
결제수단. TOSS_MONEY: 토스머니, CARD: 카드
최대 10자
가능한 값:
TOSS_MONEY CARD
payToken string
승인된 결제토큰
transactionId string
거래 트랜잭션 아이디. 매출전표 호출 또는 환불 시 활용 가능
cashReceiptMgtKey string
현금영수증 관리번호 식별값. 토스페이 자체 식별 값으로 국세청 승인번호와 다릅니다.
최대 36자
cardCompanyName string
승인 카드사명
cardAuthorizationNo string
카드 승인번호
spreadOut integer (int32)
사용자가 선택한 카드 할부개월. 5만원 미만 또는 일시불은 0
noInterest boolean
카드 무이자 적용 여부. true: 무이자, false: 일반
salesCheckLinkUrl string
신용카드 매출전표 호출 URL
cardMethodType string
카드 타입. CREDIT: 신용카드, CHECK: 체크카드, PREPAYMENT: 선불카드
가능한 값:
CREDIT CHECK PREPAYMENT NONE
cardNumber string
마스킹된 카드번호
cardUserType string
카드 사용자 구분. PERSONAL: 본인 카드, PERSONAL_FAMILY: 가족 카드, CORP_PERSONAL: 법인지정 결제계좌 임직원, CORP_PRIVATE: 법인 공용
가능한 값:
NONE PERSONAL PERSONAL_FAMILY CORP_PERSONAL CORP_PRIVATE CORP_COMPANY GIFT
cardBinNumber string
카드 BIN 번호
cardNum4Print string
사용자가 선택한 카드의 끝 4자리
accountBankCode string
은행코드
accountBankName string
은행명
accountNumber string
마스킹된 계좌번호
metadata string
메타데이터. 가맹점에서 관리하는 추가 정보
paidPoint integer (int64)
포인트 사용 금액
cardCompanyCode integer (int32)
카드사 코드
### 요청 예제
### 응답 예제
---
# 개요
URL: /reference/billing
빌링키 방식으로 자동결제를 연동할 수 있도록 구현한 API입니다. 토스 결제서버는 가맹점의 빌링키 생성요청에 따라 구매자가 인증할 수 있는 유니크한 '결제 인증 URL'을 생성하고, 가맹점을 통해 구매자는 토스 앱을 통해 인증을 진행할 수 있습니다.
- 사용자의 유니크한 빌링키가 생성되며, 가맹점은 이 빌링키를 관리하고 필요 시 결제 승인 요청을 할 수 있습니다.
- 토스가 제공하는 자동결제는 '토스머니'와 '카드' 결제수단을 제공합니다. 해당 문서는 자동결제 각 API의 기능을 설명합니다.
- 테스트 계정 및 별도의 SDK 파일을 제공하지 않기에, '토스' 앱 설치 후 최신 버전 사용을 권장합니다.
- 결제 도메인은 운영환경으로 제공되며, 결제에서 사용하는 상점 API Key 속성에 따라 실제 출금 여부를 판단합니다.
- 테스트 키(sk_test_xxx...)는 실제 출금되지 않으니 충분히 테스트할 수 있습니다.
- 양사 간 계약이 완료된 후 전용 상점정보를 전달하며, 그 전까지는 가이드에 기재된 테스트 API Key로 진행할 수 있습니다.
각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.
## 자동결제 flow
---
# 빌링키 생성 요청
URL: /reference/billing/create
토스 자동결제를 등록하기 위해서는 사용자를 식별할 수 있는 고유한 빌링키를 생성해야 합니다. API 요청의 응답으로 성공 여부와 함께 토스 앱 인증 URL을 전달합니다.
각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.
POST https://pay.toss.im/api/v1/billing-key
### 요청 파라미터
apiKey string 필수
결제 가맹점의 API Key. 결제 보안상 유의가 필요하며 웹 브라우저에 노출되지 않도록 가맹점의 관리가 필요합니다.
최대 30자
userId string 필수
가맹점 사용자 식별 값. 가맹점에 저장된 회원 아이디를 활용할 수 있습니다. 추후 결제 승인 정보와 매칭하기 위하여 필요하며 유니크한 값을 사용하길 권장합니다. 숫자, 영문자도 가능하되 특수문자는 _ - : . ^ @ = 만 허용합니다.
최대 50자
displayId string
다중 빌링키 식별 값. 동일한 결제수단을 여러 번 등록하고 싶다면, displayId를 사용하여 여러 개의 빌링키를 생성할 수 있습니다.
최대 50자
productDesc string 필수
자동결제 상품명. 토스 결제창에 표기될 가맹점의 자동결제 상품명
최대 255자
resultCallback string 필수
가맹점 설정 콜백 URL. 사용자가 토스 앱을 통해 인증을 완료한 후, 이 URL에 인증 결과 데이터를 전달합니다. 콜백 서버는 보안상의 이유로 HTTPS를 권장하며, 80, 443 이외의 포트 사용은 불가합니다.
최대 500자
retAppScheme string
인증완료 후 연결할 가맹점의 앱 스킴. App to App 결제 환경에서는 토스페이 완료 후 가맹점 앱으로 리디렉션하기 위해 앱 스킴 설정이 필요합니다. 특히 iOS 환경에서는 자동 앱 전환이 되지 않아 필수 구현을 권장합니다.
최대 1500자
encryptedUserCi string
가맹점 유저의 CI값. 가맹점에서 자동결제를 등록하는 사용자의 실명확인을 통해 생성된 사용자 정보를 전달할 수 있습니다.
최대 255자
returnSuccessUrl string
인증성공 후 연결할 가맹점 성공 페이지. retAppScheme이 선언되지 않으면 필수로 보내주셔야 합니다.
최대 1500자
returnFailureUrl string
인증실패 시 연결할 가맹점 실패 페이지
최대 1500자
### 응답 파라미터
code integer (int32)
응답코드. 0: 성공, -1: 실패 (실패 사유는 msg와 errorCode로 제공)
errorCode string
에러 코드
msg string
응답이 성공이 아닌 경우 설명 메시지
billingKey string
생성된 자동결제 사용자 빌링키. 빌링키는 토스 사용자의 고유한 값으로, 한 상점에서 한 개의 빌링키만 허용합니다.
최대 50자
checkoutAndroidUri string
Android 구독 인증 URI. 생성된 자동결제를 인증할 앱 URL. 가맹점은 구매자의 디바이스 OS를 구분해서 해당 URL로 보내주면 됩니다.
최대 255자
checkoutIosUri string
iOS 구독 인증 URI. iOS에서 사용되는 구독 인증 URI로, 토스앱이 설치된 사용자가 앱을 통해 인증을 완료할 수 있도록 합니다.
최대 255자
checkoutUri string
토스 앱 호출 링크. retAppScheme가 포함된 경우 onelink를 제공하고, 포함되지 않은 경우 Web 결제용 payfront 링크를 제공합니다.
최대 255자
### 요청 예제
### 응답 예제
---
# 빌링키 처리결과 callback
URL: /reference/billing/result-callback
사용자가 토스 앱을 통해 빌링 등록을 '성공적'으로 완료한 경우 토스 서버는 가맹점이 설정한 resultCallback URL을 통해 결과를 전달합니다. 대부분의 자동결제 등록 실패에 대해서는 사용자의 재시도를 고려하여 실패 결과를 전달하지 않지만, 더 이상 등록을 진행할 수 없는 상태(재시도 불가)로 판단하면 실패 결과를 전달합니다. 예를 들면 CI(유저) 불일치로 등록이 차단되는 경우가 이에 해당합니다.
- 토스 쪽에서 삭제가 발생되는 경우 토스 pay Server에서 삭제(REMOVED) callback을 보낼 수 있음을 참고해야 합니다.
- callback에 대한 응답의 HTTP status code가 200인 경우에만 '정상' 수신으로 간주하며, 그 외의 응답 코드는 미수신으로 실패한 것으로 인식하여 3분 간격으로 최대 4번 접근을 시도합니다.
- 빌링키 생성결과 callback의 Payload는 다음과 같습니다.
각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.
## 파라미터
action string
요청 처리에 따른 빌링키 상태를 전달합니다.
가능한 값:
ACTIVATED REMOVED
- ACTIVATED : 빌링키 활성화 완료. 빌링키 생성요청에 따라, 토스 → 가맹점으로 '정상처리'를 알리는 콜백 - REMOVED : 빌링키 삭제 완료. 토스 → 가맹점으로 빌링키 삭제를 요청할 수 있다. 그 때, '삭제완료' 상태를 알리는 콜백
processedTs string
상태 처리시간. `action` 에 따라 각 상태의 처리시간을 전달합니다.
userId string
가맹점이 생성한 사용자 식별 값. 가맹점의 요청 값 그대로를 전달합니다.
displayId string
가맹점이 생성한 표시 가능한 빌링키 식별 값. 가맹점의 요청 값 그대로를 전달합니다.
billingKey string
활성화/삭제 자동결제 사용자 빌링키
payMethod string
사용자가 토스에서 인증한 결제수단. 선택한 결제수단에 따라 토스머니(`TOSS_MONEY`) 또는 카드(`CARD`)를 전달합니다.
가능한 값:
TOSS_MONEY CARD
cardMethodType string
승인된 카드의 타입을 구분. 선택한 결제수단에 따라 신용카드(`CREDIT`), 체크카드(`CHECK`), 선불카드(`PREPAYMENT`)를 전달합니다.
가능한 값:
CREDIT CHECK PREPAYMENT
cardUserType string
카드 사용자 구분
가능한 값:
PERSONAL PERSONAL_FAMILY CORP_PERSONAL CORP_PRIVATE CORP_COMPANY
- PERSONAL : 본인 카드 - PERSONAL_FAMILY : 가족 카드 - CORP_PERSONAL : 법인지정 결제계좌 임직원 - CORP_PRIVATE : 법인 공용 - CORP_COMPANY : 법인지정 결제계좌 회사(하나카드만)
cardCompanyNo integer
사용자가 선택한 카드의 카드코드. 사용자가 선택한 결제수단(`payMethod`)이 '카드'인 경우 토스가 정의한 카드코드를 전달합니다.
cardCompanyName string
사용자가 선택한 카드의 카드사명. 사용자가 선택한 결제수단(`payMethod`)이 '카드'인 경우 카드사명을 함께 전달합니다.
cardNumber string
사용자가 선택한 카드의 번호. 카드번호 16자리 중 중간자리는 마스킹됩니다.
cardNum4Print string
사용자가 선택한 카드의 끝 4자리. 사용자가 선택한 결제수단(`payMethod`)이 '카드'인 경우 카드번호를 포함하여 전달합니다.
cardBinNumber string
카드사에서 준 카드 BIN 번호. 마스킹되어 있을 수 있으며, 100% 신뢰는 불가합니다.
accountBankCode string
사용자가 선택한 계좌의 은행코드. 사용자가 선택한 결제수단(`payMethod`)이 '토스머니'인 경우 토스가 정의한 은행코드를 전달합니다.
accountBankName string
사용자가 선택한 계좌의 은행명. [은행코드 리스트](/guide/bank-code)
accountNumber string
사용자가 선택한 계좌번호. 계좌번호는 일부 마스킹을 포함할 수 있습니다.
## 예제
Example Request
```
{
"action": "ACTIVATED",
"processedTs": "2020-04-01 12:34:11",
"userId": "TOSS-TEST-1",
//"displayId": "TEST_SERVICE_1",
"billingKey": "example-billingKey",
"payMethod": "TOSS_MONEY",
"accountBankCode": "88",
"accountBankName": "신한은행",
"accountNumber": "110******676"
}
```
---
# 자동결제(bill) 승인 요청
URL: /reference/billing/bill
빌링키 생성결과 callback에서 전달받은 빌링키로 가맹점은 승인 요청을 할 수 있습니다. 유효시간이나 최대 횟수를 제한하지 않으니 승인요청 API를 활용해서 결제를 진행할 수 있습니다.
각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.
POST https://pay.toss.im/api/v1/billing-key/bill
### 요청 파라미터
apiKey string 필수
결제 가맹점의 API Key. 빌링키 생성요청 시 사용된 API Key와 동일해야 합니다. 결제 보안상 유의가 필요하며 웹 브라우저에 노출되지 않도록 가맹점의 관리가 필요합니다.
최대 30자
billingKey string 필수
빌링키. 빌링키 생성 콜백으로 전달받은 빌링키 값으로, 해당 사용자의 결제수단 식별 용도로 사용됩니다.
최대 50자
orderNo string 필수
가맹점의 상품 주문번호. 최대 50자로 지정하며 숫자, 영문자도 가능하되 특수문자는 _ - : . ^ @ = 만 허용합니다. 주문번호는 가맹점에서 관리하는 유니크한 값이어야 합니다.
최소 0자 최대 50자 패턴: ^[\w-:.^@]+$
productDesc string 필수
상품 설명
최소 0자 최대 255자
spreadOut integer (int32) 필수
할부 개월 수. 카드 결제 시 0~12까지 지정 가능하며, 0은 일시불입니다. 5만원 미만 결제 건은 일시불만 가능합니다.
최대 2자
amount integer (int64) 필수
결제 요청 금액. 카드 가맹점은 최대 10억원, 그 외 가맹점은 최대 200만원까지 가능합니다.
최대 10자
amountTaxFree integer (int64) 필수
결제 요청 금액 중 비과세 금액
최대 10자
amountTaxable integer (int64)
결제 요청 금액 중 과세 금액
최대 10자
amountVat integer (int64)
결제 요청 금액 중 부가세
최대 10자
amountServiceFee integer (int64)
결제 요청 금액 중 봉사료
최대 10자
cashReceipt boolean 필수
토스 현금영수증 자동발행 기능을 사용한다면 매회 결제 시 true 값을, 미 사용하는 경우 false 값을 전달합니다. 기본값은 true입니다.
sendFailPush boolean 필수
빌링키 결제가 실패할 경우, 사용자에게 결제 실패 알람을 발송합니다. 기본값 true
cashReceiptTradeOption string 필수
현금영수증 발행 유형. CULTURE: 문화비, GENERAL: 일반(기본값), PUBLIC_TP: 대중교통
가능한 값:
GENERAL CULTURE PUBLIC_TP
isPreApprove boolean
선승인 여부. true: 선승인 (포인트 사용 X), false 또는 null: 선승인 아님
metadata string
메타데이터. 가맹점에서 관리하는 추가 정보
최대 1024자
### 응답 파라미터
code integer (int32)
응답코드. 0: 성공, -1: 실패 (실패 사유는 msg와 errorCode로 제공)
errorCode string
에러 코드
msg string
응답이 성공이 아닌 경우 설명 메시지
mode string
결제환경. LIVE: 실거래용, TEST: 테스트용
가능한 값:
TEST LIVE
payToken string
결제 토큰
최대 30자
orderNo string
주문번호
최대 50자
payMethod string
결제수단. TOSS_MONEY: 토스머니, CARD: 카드
가능한 값:
TOSS_MONEY CARD
amount integer (int64)
결제 금액
transactionId string
거래 트랜잭션 아이디
최대 36자
approvalTime string
승인 처리 시간 (yyyy-MM-dd HH:mm:ss)
최대 20자
discountedAmount integer (int64)
할인된 금액. 할인 적용이 없으면 0
paidAmount integer (int64)
지불수단 승인금액. 총 금액 중 할인된 금액을 제외한 순수 지불수단 승인금액
cardCompanyName string
카드사명
cardCompanyCode integer (int32)
카드사 코드
cardAuthorizationNo string
카드사 승인번호
최대 8자
salesCheckLinkUrl string
신용카드 매출전표 호출 URL
최대 255자
spreadOut integer (int32)
카드 할부개월. 5만원 미만 금액 및 일시불 결제의 경우 0
noInterest boolean
카드 무이자 적용 여부. true: 무이자, false: 일반
cardMethodType string
카드 타입. CREDIT: 신용카드, CHECK: 체크카드, PREPAYMENT: 선불카드
가능한 값:
CREDIT CHECK PREPAYMENT NONE
accountBankName string
은행명
accountBankCode string
은행코드
accountNumber string
마스킹된 계좌번호
cashReceiptMgtKey string
현금영수증 관리번호 식별값
최대 36자
cardNumber string
마스킹된 카드번호
최대 20자
cardUserType string
카드 사용자 구분. PERSONAL: 본인 카드, PERSONAL_FAMILY: 가족 카드, CORP_PERSONAL: 법인지정 결제계좌 임직원, CORP_PRIVATE: 법인 공용
가능한 값:
NONE PERSONAL PERSONAL_FAMILY CORP_PERSONAL CORP_PRIVATE CORP_COMPANY GIFT
cardBinNumber string
카드 BIN 번호
최대 8자
cardNum4Print string
카드번호 끝 4자리
최대 4자
### 요청 예제
### 응답 예제
---
# 빌링키 상태 조회
URL: /reference/billing/billing-key-status
가맹점은 생성된 빌링키를 관리하고 회원 관리의 목적으로 빌링키의 상태를 조회할 수 있습니다. 사용자가 토스앱에서 결제수단을 변경한 경우 결제수단(payMethod) 정보가 업데이트될 수 있습니다.
각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.
POST https://pay.toss.im/api/v1/billing-key/status
### 요청 파라미터
apiKey string 필수
가맹점 API Key
최대 30자
userId string 필수
가맹점 사용자 식별 값
최대 50자
displayId string
다중 빌링키 식별 값
최대 50자
### 응답 파라미터
code integer (int32)
응답코드. 0: 성공, -1: 실패 (실패 사유는 msg와 errorCode로 제공)
errorCode string
에러 코드
msg string
응답이 성공이 아닌 경우 설명 메시지
### 요청 예제
### 응답 예제
---
# 빌링키 삭제 요청
URL: /reference/billing/remove
생성된 빌링키를 삭제합니다. 삭제된 빌링키는 더 이상 자동결제에 사용할 수 없습니다.
각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.
POST https://pay.toss.im/api/v1/billing-key/remove
### 요청 파라미터
apiKey string 필수
가맹점 API Key
최대 30자
billingKey string 필수
삭제할 빌링키
최대 50자
### 응답 파라미터
code integer (int32)
응답코드. 0: 성공, -1: 실패 (실패 사유는 msg와 errorCode로 제공)
errorCode string
에러 코드
msg string
응답이 성공이 아닌 경우 설명 메시지
### 요청 예제
### 응답 예제
---
# 결제 환불
URL: /reference/common/refunds
결제 완료 건의 결제 금액 중 일부 또는 전부를 구매자에게 돌려줍니다.
기 환불처리된 거래는 원복이 불가하오니 환불 전 반드시 가맹점 측의 체크가 필요합니다.
각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.
POST https://pay.toss.im/api/v2/refunds
### 요청 파라미터
apiKey string 필수
가맹점 API Key. 웹 브라우저 혹은 외부에 노출되지 않도록 유의해 주시기 바랍니다.
최대 30자
payToken string 필수
토스페이 토큰
최대 30자
orderNo string
가맹점 주문번호
최대 50자
refundNo string 필수
환불 번호. 환불 번호는 요청 시 가맹점별로 매회 유니크한 값을 입력해야 하며, 중복 입력 시 환불 요청이 실패합니다. 최대 36자 이내의 문자열을 사용해야 하며 빈 문자열 또는 null로 전달하면 오류가 발생합니다.
최대 36자
reason string
환불 사유. 한글 및 숫자, 영문자, 특수문자를 허용합니다.
최대 255자
amount integer (int64)
환불할 금액. 미입력 시 환불할 결제건의 남은 전액을 환불 처리하며, 부분환불 시 필수로 amount를 활용해주세요. 즉시할인이 적용된 거래의 부분환불이 필요한 경우, 가맹점에서는 환불이 필요한 총 요청 금액만 전달해 주시면 됩니다.
최대 10자 최소값 1
amountTaxable integer (int64)
환불할 금액 중 과세금액
최대 10자
amountVat integer (int64)
환불할 금액 중 부가세. 값이 없으면 환불할 과세금액을 11로 나눈 후 소수점 첫째 자리에서 올림으로 계산합니다.
최대 10자
amountServiceFee integer (int64)
환불할 금액 중 봉사료. 결제 생성 시 봉사료 설정한 경우에만 입력 가능
최대 10자
amountTaxFree integer (int64)
환불할 금액 중 비과세금액. 없으면 0으로 설정합니다.
최대 10자
idempotent boolean
멱등성 적용 여부. true: 사용 (기본값), false: 미사용. 멱등성 적용 시 동일한 요청을 반복적으로 수행하더라도 동일한 결과인 성공으로 응답 처리됩니다.
### 응답 파라미터
code integer (int32)
응답코드. 0: 성공, -1: 실패 (실패 사유는 msg와 errorCode로 제공)
errorCode string
에러 코드
msg string
응답이 성공이 아닌 경우 설명 메시지
refundNo string
환불 번호. 환불요청 시 가맹점이 전달한 refundNo로 리턴됩니다.
approvalTime string
결제건의 환불 처리 시간 (yyyy-MM-dd HH:mm:ss)
최대 20자
cashReceiptMgtKey string
현금영수증 관리번호 식별값
최대 36자
refundableAmount integer (int64)
환불 가능 금액. 환불 성공 후 남은 환불 가능 금액
discountedAmount integer (int64)
할인된 금액. 환불 성공 후 남은 할인적용 금액
paidPoint integer (int64)
포인트 사용 금액
paidAmount integer (int64)
지불수단 승인금액. 환불 성공 후 남은 지불수단의 승인금액
refundedAmount integer (int64)
환불요청 금액. 가맹점에서 환불 요청 시 전달한 amount 금액
refundedDiscountAmount integer (int64)
환불요청 금액 중 실 차감된 할인 금액
refundedPoint integer (int64)
환불된 포인트 금액
refundedPaidAmount integer (int64)
환불요청 금액 중 실 차감된 지불수단 금액
payToken string
환불된 결제토큰
transactionId string
거래 트랜잭션 아이디
payStatus string
결제 상태. PAY_COMPLETE: 결제 완료, REFUND_SUCCESS: 환불 성공 등
payMethod string
결제수단. TOSS_MONEY: 토스머니, CARD: 카드
최대 10자
가능한 값:
TOSS_MONEY CARD
accountBankCode string
은행코드
accountBankName string
은행명
accountNumber string
마스킹된 계좌번호
cardNum4Print string
사용자가 선택한 카드의 끝 4자리
cardNumber string
마스킹된 카드번호
cardBinNumber string
카드 BIN 번호
cardUserType string
카드 사용자 구분. PERSONAL: 본인 카드, PERSONAL_FAMILY: 가족 카드, CORP_PERSONAL: 법인지정 결제계좌 임직원, CORP_PRIVATE: 법인 공용
가능한 값:
NONE PERSONAL PERSONAL_FAMILY CORP_PERSONAL CORP_PRIVATE CORP_COMPANY GIFT
cardMethodType string
카드 타입. CREDIT: 신용카드, CHECK: 체크카드, PREPAYMENT: 선불카드
가능한 값:
CREDIT CHECK PREPAYMENT NONE
### 요청 예제
### 응답 예제
---
# 결제 상태 확인
URL: /reference/common/status
생성된 결제건의 거래 상태와 거래 트랜잭션을 조회할 수 있습니다. 상황에 따라, 승인 혹은 환불 응답을 수신하지 못한 경우에도 활용 가능합니다.
각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.
POST https://pay.toss.im/api/v2/status
### 요청 파라미터
apiKey string 필수
가맹점 API Key. 웹 브라우저 혹은 외부에 노출되지 않도록 유의해 주시기 바랍니다.
최대 30자
payToken string
토스페이 토큰. payToken 또는 orderNo 중 하나를 필수로 전달해야 합니다.
최대 50자
orderNo string
가맹점 주문번호. payToken 또는 orderNo 중 하나를 필수로 전달해야 합니다.
최대 50자
### 응답 파라미터
mode string 필수
결제환경. LIVE: 실거래용, TEST: 테스트용
가능한 값:
TEST LIVE
payToken string 필수
토스페이 토큰
최대 30자
orderNo string 필수
토스페이와 연계된 상점 주문번호
최대 50자
payStatus string 필수
결제 상태. PAY_STANDBY: 결제 대기 중, PAY_APPROVED: 구매자 인증 완료, PAY_CANCEL: 결제 취소, PAY_PROGRESS: 결제 진행 중, PAY_COMPLETE: 결제 완료, REFUND_PROGRESS: 환불 진행 중, REFUND_SUCCESS: 환불 성공, SETTLEMENT_COMPLETE: 정산 완료, SETTLEMENT_REFUND_COMPLETE: 환불 정산 완료
가능한 값:
PAY_STANDBY PAY_APPROVED PAY_COMPLETE PAY_CANCEL REFUND_SUCCESS PAY_PROGRESS SETTLEMENT_COMPLETE SETTLEMENT_REFUND_COMPLETE REFUND_PENDING REFUND_PROGRESS
payMethod string 필수
결제수단. TOSS_MONEY: 토스머니, CARD: 카드
가능한 값:
TOSS_MONEY CARD
amount integer (int64) 필수
가맹점이 토스로 전달한 결제 총 금액
discountedAmount integer (int64) 필수
할인된 금액. 할인 적용이 없으면 0으로 리턴됩니다. 할인 금액에는 토스 앱에서 자동 적용되는 즉시할인과 토스 포인트 사용금액이 포함됩니다.
originDiscountAmount integer (int64) 필수
즉시 할인 적용 금액. 토스페이 창에서 자동으로 적용된 즉시할인 금액이 리턴되며, 할인 적용이 없으면 0으로 리턴됩니다.
discountAmountV2 integer (int64) 필수
즉시 할인 적용 금액. 토스페이 창에서 자동으로 적용된 즉시할인 금액이 리턴되며, 할인 적용이 없으면 0으로 리턴됩니다. 더 이상 사용되지 않습니다 originDiscountAmount를 대신 사용해주세요.
originPaidPoint integer (int64) 필수
토스 포인트 사용금액. 결제에 사용된 토스 포인트 금액이 리턴되며, 미사용의 경우 0으로 리턴됩니다.
paidPointV2 integer (int64) 필수
토스 포인트 사용금액. 결제에 사용된 토스 포인트 금액이 리턴되며, 미사용의 경우 0으로 리턴됩니다. 더 이상 사용되지 않습니다 originPaidPoint를 대신 사용해주세요.
paidAmount integer (int64) 필수
지불수단 승인금액. 가맹점이 요청한 총 금액(amount) 중 할인된 금액을 제외한 순수 지불수단 승인금액입니다.
refundableAmount integer (int64) 필수
환불 가능 잔액. 환불 성공 후 남은 환불 가능 금액
amountTaxable integer (int64) 필수
총 결제 금액 중 적용된 과세 금액
amountTaxFree integer (int64) 필수
총 결제 금액 중 적용된 비과세 금액
amountVat integer (int64) 필수
총 결제 금액 중 적용된 부가세 금액
amountServiceFee integer (int64) 필수
총 결제 금액 중 적용된 봉사료
disposableCupDeposit integer (int64) 필수
일회용 컵 보증금
accountBankCode string
은행 코드. 사용자가 선택한 결제수단(payMethod)이 '토스머니'인 경우 토스가 정의한 은행 코드를 전달합니다.
accountBankName string
은행 명
accountNumber string
계좌번호. 계좌번호는 일부 마스킹을 포함하고 있습니다.
transactions Transaction[] 필수
거래 트랜잭션
createdTs string (date-time) 필수
사용자 최초 결제 요청 시간 (결제 생성 시간)
paidTs string (date-time) 필수
결제 완료 처리 시간
code integer (int32)
응답코드. 0: 성공, -1: 실패 (실패 사유는 msg와 errorCode로 제공)
errorCode string
에러 코드
msg string
응답이 성공이 아닌 경우 설명 메시지
### 요청 예제
### 응답 예제
---
# 토스 현금영수증 API 소개
URL: /reference/cache-receipt
본 문서는 토스페이 결제 가맹점에서 현금영수증을 발급하거나 취소, 상태 확인 및 현금영수증 이미지 주소를 얻고자 할 때 사용할 API에 대한 가이드를 제공합니다.
토스페이 결제 가맹점에서는 해당하는 현금영수증 API를 이용하여 국세청으로 현금영수증을 등록 및 취소, 상태 확인 등을 할 수 있습니다.
이를 위해 토스페이에서는 토스페이먼츠(PG)를 통해 가맹점에게 현금영수증 API를 제공하고, 토스페이먼츠(PG)를 통해 국세청으로 정상 등록이 되면 통상 2일 안에 국세청으로부터 동기화 과정을 거쳐서 현금영수증의 발급이 완료됩니다.
## 유의할 점
### 현금영수증 처리 완료 일시
- 현금영수증 API 를 호출하더라도
- 국세청으로 전송
- 국세청에서 확인 후 승인 또는 거절 등의 단계를 거쳐 처리
과정을 거치므로 현금영수증 API 호출 후 통상 2 ~ 3 일의 시일이 지나야 국세청에 등록이 완료됩니다.
- 현금영수증 취소의 경우, 환불 시 별도의 원장에 기록된 현금영수증 취소 STANDBY가 환불과 동시에 생성되며 뒷단 배치에서 해당 STANDBY를 읽어 현금영수증 취소 처리 후 토스페이먼츠(PG)로 취소 요청이 전달됩니다.
---
# 현금 영수증 발급
URL: /reference/cache-receipt/issue
해당 결제가 status = PAY_COMPLETE으로 완료되었을 때, 현금 영수증 발급이 가능합니다.
각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.
주의 사항: 토스의 결제 금액과 현금영수증의 불일치를 막기 위해 발급 API에서는 금액 정보를 파라미터로 받지 않습니다. 이미 결제 처리가 되어 토스 시스템에 기록된 과세 항목, 비과세 항목 등의 값을 바탕으로 현금영수증 발급이 처리됩니다.
POST https://pay.toss.im/api/v2/issue-cash-receipt
### 요청 파라미터
apiKey string 필수
결제 가맹점의 API Key. API Key는 LIVE 값만 동작하며 TEST 값은 무시됩니다.
최대 255자
payToken string 필수
결제 토큰. 현금영수증 발급 대상 결제는 결제 완료(status = PAY_COMPLETE) 상태여야 합니다.
최대 255자
cashReceiptKey string 필수
발급 주체를 식별할 수 있는 key 값. ex) 개인의 경우 - 휴대폰번호, 사업장의 경우 - 사업자등록번호
최대 255자
cashReceiptKeyType string 필수
현금영수증 keyType. PHONE: 전화번호, CORPORATE: 사업자등록번호, CARD: 카드번호
최대 255자
cashReceiptPurpose string 필수
현금영수증 발급 목적. DEDUCTION: 소득공제용, EVIDENCE: 지출증빙용
최대 255자
needSelfIssue boolean
자진발급 처리 여부. 자진발급 처리를 희망하지 않을 경우 전달하지 않습니다. (기본값 false)
isCurrentCashReceiptKeyUsage boolean
토스 유저의 현재 현금영수증 식별번호로 발급 처리 여부. 해당 값을 true로 전달할 경우 식별번호를 보내지 않아도 토스가 저장하고 있는 유저의 현재 현금영수증 식별 번호로 발급 처리됩니다. (기본값 false)
### 응답 파라미터
code integer (int32)
응답코드. 0: 성공, -1: 실패 (실패 사유는 msg와 errorCode로 제공)
errorCode string
에러 코드
msg string
응답이 성공이 아닌 경우 설명 메시지
status integer (int32)
HTTP status code
cashReceiptMgtKey string
관리번호 값. 발급 요청된 현금영수증을 확인할 수 있는 관리번호 값
supplyCost integer (int64)
공급가액. 과세 금액 + 비과세 금액 (supplyCost = amountTaxable + amountTaxFree)
tax integer (int64)
부가세 (tax = amountVat)
serviceFee integer (int64)
봉사료 (serviceFee = amountServiceFee)
### 요청 예제
### 응답 예제
---
# 현금 영수증 취소
URL: /reference/cache-receipt/revoke
해당 결제가 status = PAY_COMPLETE으로 완료되었고, 발급 요청된 현금 영수증이 있을 때에만 호출 가능합니다.
각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.
주의 사항: 현금영수증 취소 API의 경우에도 금액과 관련된 parameter를 받지 않습니다. 결제 환불 API를 통해 토스 시스템에서 기록된 남은 금액을 바탕으로 현금영수증 취소를 처리합니다. 따라서 전체 환불, 부분 환불의 구분 없이 취소 API를 호출하면, 남은 결제 금액에 맞게 알아서 처리됩니다.
POST https://pay.toss.im/api/v2/revoke-cash-receipt
### 요청 파라미터
apiKey string 필수
결제 가맹점의 API Key. API Key는 LIVE 값만 동작하며 TEST 값은 무시됩니다.
최대 30자
payToken string 필수
결제토큰. 현금영수증 발급 대상 결제는 '결제 완료' 상태여야 합니다. (status = PAY_COMPLETE)
최대 30자
### 응답 파라미터
code integer (int32)
응답코드. 0: 성공, -1: 실패 (실패 사유는 msg와 errorCode로 제공)
errorCode string
에러 코드
msg string
응답이 성공이 아닌 경우 설명 메시지
status integer (int32)
HTTP status code
cashReceiptMgtKey string
관리번호 값. 발급 요청된 현금영수증을 확인할 수 있는 관리번호 값
supplyCost integer (int64)
공급가액. 과세 금액 + 비과세 금액 (supplyCost = amountTaxable + amountTaxFree)
tax integer (int64)
부가세 (tax = amountVat)
serviceFee integer (int64)
봉사료 (serviceFee = amountServiceFee)
### 요청 예제
### 응답 예제
---
# 현금 영수증 상태 확인
URL: /reference/cache-receipt/info
발급된 현금영수증의 상태를 조회합니다. 국세청 전송 상태, 발급 완료 여부 등을 확인할 수 있습니다.
각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.
POST https://pay.toss.im/api/v2/cash-receipt-info
### 요청 파라미터
apiKey string 필수
결제 가맹점의 API Key. API Key는 LIVE 값만 동작하며 TEST 값은 무시됩니다.
최대 30자
payToken string 필수
결제토큰
최대 30자
### 응답 파라미터
code integer (int32)
응답코드. 0: 성공, -1: 실패 (실패 사유는 msg와 errorCode로 제공)
errorCode string
에러 코드
msg string
응답이 성공이 아닌 경우 설명 메시지
cashReceiptMgtKey string
현금영수증 관리번호 값
customerName string
현금영수증 신청 고객명
itemName string
상품명
identityNum string
고객 식별번호. 현금영수증 발급 당시 사용한 고객 식별번호 (예: 휴대폰번호, 사업자등록번호 등)
taxationType string
과세형태 (과세 / 비과세)
totalAmount string
현금영수증 발급 총액
supplyCost string
공급가액 (과세금액 + 비과세금액)
tax string
부가세
serviceFee string
봉사료
tradeUsage string
발급 목적 (소득공제용 / 지출증빙용)
tradeType string
거래유형 (승인거래 / 취소거래)
status string
현금영수증 상태. IN_PROGRESS: 국세청 전송중, ISSUE_APPLIED: 발급 신청 완료, ISSUE_COMPLETE: 발급 완료, ISSUE_FAILED: 발급 실패
ntsResult string
국세청 리턴 결과
confirmNum string
발행승인번호
confirmTs string (date-time)
발행일시. ISO-8601 형식 (예: 2019-03-21T14:02:49)
tradeDate string
등록 요청 날짜
orgConfirmNum string
(취소 거래시) 국세청 승인 원번호
orgTradeDate string
(취소 거래시) 국세청 승인 원거래일시
### 요청 예제
### 응답 예제
---
# 현금 영수증 팝업 주소 전달
URL: /reference/cache-receipt/popup-uri
토스 결제 가맹점을 이용한 고객이 현금영수증의 발급 및 취소된 것의 발급 이미지 등을 요구할 때, 해당 API를 호출하여 리턴되는 팝업 Uri 값으로 대응이 가능합니다.
각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.
POST https://pay.toss.im/api/v2/cash-receipt-popupUri
### 요청 파라미터
apiKey string 필수
결제 가맹점의 API Key. API Key는 LIVE 값만 동작하며 TEST 값은 무시됩니다.
최대 30자
payToken string 필수
결제토큰
최대 30자
### 응답 파라미터
code integer (int32)
응답코드. 0: 성공, -1: 실패 (실패 사유는 msg와 errorCode로 제공)
errorCode string
에러 코드
msg string
응답이 성공이 아닌 경우 설명 메시지
popupUri string
팝빌이 제공하는 현금영수증 팝업 URI
### 요청 예제
### 응답 예제
---
# 토스 정산 API 소개
URL: /reference/settlement
토스 결제 서비스를 통한 매출과 정산 금액 확인을 위한 API입니다. 페이징 개념이 적용되며, 페이징 단위는 1,000건입니다. 다음 페이징이 존재하면 nextCursor라는 응답값이 리턴되며, 이를 포함하여 호출하면 다음 페이징 데이터를 얻을 수 있습니다.
## 용어
| 용어 | 정의 |
| 지급일 | 결제 금액을 가맹점의 결제 계좌로 입금한 날입니다. |
| 거래 승인일 | 결제, 환불 등 거래가 실제로 일어난 날입니다. |
## 정산 API 조회 시 유의사항
- 정산 API는 승인일 기준 D+1일 06:00경에 DW에 참조 테이블 적재가 완료됩니다.
- 따라서 06:00 이후 호출해야 누락 없이 전체 데이터를 조회할 수 있습니다.
- 단, 06:00 직후에는 데이터 수집이 진행 중일 수 있어 응답이 지연되거나 실패할 수 있습니다.
- 이 경우에는 오후 시간대에 재조회하실 것을 권장드립니다.
---
# 정산 API
URL: /reference/settlement/detail
지급일 또는 거래 승인일 기준으로 정산 상세 내역을 조회합니다.
각 API 응답 필드와 에러코드는 사전 공지 없이 추가되거나 변경될 수도 있으니, 추가된 항목으로 인해 오류가 발생하지 않도록 처리에 유의해 주시기 바랍니다.
POST https://pay.toss.im/api/v2/settlement-details
### 요청 파라미터
apiKey string 필수
가맹점 API Key. Test API Key도 입력은 가능하나 테스트 결제는 실제 지급되지 않으므로 정산 대상이 아닙니다.
dateType string 필수
기준 날짜의 형태. DUE: 지급일 (정산 계좌에 입금된 날짜), SETTLE: 거래 승인일 (결제 시점의 날짜)
baseDate string 필수
조회하고자 하는 날짜 (yyyyMMdd 형식). 승인일 기준 최대 1년까지 조회 가능하며, 당일 자 데이터 조회는 제한됩니다.
nextCursor string
페이징 cursor 값. 파라미터가 추가되지 않으면 첫 페이징 데이터가 리턴됩니다.
payMethod string
조회하고자 하는 결제수단. 보내지 않거나 null로 보내면 모든 결제수단에 대해 응답. TOSS_MONEY: 토스머니, CARD: 카드
가능한 값:
TOSS_MONEY CARD
### 응답 파라미터
transactionList SettlementTransaction[]
정산 내역 리스트 (최대 1000개)
nextCursor string
커서 값. 다음 페이징 데이터가 있으면 커서 값을 반환, 마지막 페이징일 경우 빈 스트링을 반환
totalAmount integer (int64)
총 금액 합산. 조회된 전체 건의 총 금액 합산
totalFee integer (int64)
총 수수료 합산. 조회된 전체 건의 총 수수료 합산
totalVat integer (int64)
총 부가세 합산. 조회된 전체 건의 총 부가세 합산
totalFeeVatSum integer (int64)
총 수수료 + 부가세 합산 (totalFee + totalVat)
### 요청 예제
### 응답 예제
---
# 자주 묻는 질문
URL: /faq-v2
## 결제 연동하기
결제 테스트는 어떻게 하나요? 공통
토스페이 계약을 통해 MID가 발급되면, 테스트용, 실거래용 apiKey가 한쌍으로 부여됩니다.
가맹점에 발급되는 MID의 key는 모두 운영 환경에서 사용 가능한 테스트용, 실거래용 apiKey이며, 개발 환경에서 테스트를 희망하는 경우 별도로 요청주시어 개발환경 apiKey를 전달받아 사용하셔야 합니다.
운영 환경
토스페이 운영환경에서 테스트용 apiKey를 사용하여 테스트할 경우 실제 금원 이동없이 승인 응답까지 확인하실 수 있습니다. 테스트 완료 시, apiKey를 실거래용으로 변경한 후 실제 사용자에게 서비스를 오픈하시면 됩니다.
| | 테스트용 apiKey | 실거래용 apiKey |
| Key 형태 | sk_test_****************** | sk_live_****************** |
| 설명 | 테스트 결제 시 사용. 실제 금원 이동 없음 (머니/계좌: 실제 출금 X, 카드: 승인X). 현금영수증 발행 테스트 불가 | 실결제 오픈 시 사용. 실제 금원이동/정산 발생 |
방화벽 정보: 토스페이 운영환경은 any로 허용되어 있어 별도의 IP 등록이 필요치 않습니다. 다만 가맹점에서 자체적으로 방화벽을 사용하고 있는 경우, 토스페이의 IP를 허용해주셔야 합니다. 방화벽 설정하기
현금영수증 발급 테스트: 테스트용 key로 결제 시, 금원이 이동하지 않으므로 현금영수증이 발급되지 않습니다. 현금영수증은 실거래용 apiKey로 테스트하신 후 반드시 취소 처리 부탁드립니다.
API 연동하기 전에 결제를 경험해 볼 수는 없나요? 연동가이드 데모 체험하기를 통해 결제를 경험해볼 수 있습니다.
계약이 완료되지 않아 apiKey를 전달받지 못했어요 계약 전에는 공용 테스트용 API Key (sk_test_w5lNQylNqa5lNQe013Nq)를 사용하여 테스트할 수 있습니다. 다만 여러 가맹점이 공용으로 사용하는 Key이기 때문에 다른 가맹점의 테스트 거래에서도 사용될 수 있다는 점 참고해주시기 바랍니다.
주의사항: 운영 환경에서 테스트용 apiKey를 사용하더라도 순간적인 공격성 요청이 발생하면 IP가 자동으로 차단될 수 있으니 주의해 주세요.
AI 도구로 연동 개발할 때 문서를 어떻게 제공하나요? 공통
토스페이 가이드는 LLM이 읽기 좋은 형태의 문서를 llms.txt 표준으로 제공합니다. 목차 버전인 /llms.txt와 전체 본문 버전인 /llms-full.txt가 있습니다.
Cursor, Claude Code 같은 도구에서 활용하는 방법은 AI 도구로 연동하기에서 안내합니다.
연동하려면 IP 등록이 필요한가요? 공통
토스페이 운영 환경(pay.toss.im)은 방화벽은 오픈되어 있어 별도의 IP 등록이 필요치 않습니다.
가맹점 자체적으로 방화벽을 사용하는 경우, 하기 가이드에 안내된 토스페이의 IP 를 등록해주시기 바랍니다.
방화벽 설정하기
카드 + 토스페이머니 복합결제가 가능한가요? 공통
카드와 토스페이머니는 모두 독립적인 기본 결제수단이므로 복합결제가 불가하며, 기본 결제수단 + 토스포인트일 경우에만 복합결제가 가능합니다.
| 기본 결제수단 | 부가 결제수단 |
| 카드 | 토스포인트 |
| 계좌 | |
| 토스머니/토스페이머니 | |
복합결제 가능한 경우: 기본 결제수단 + 토스포인트
- 카드 + 토스포인트 ⇒ 가능
- 계좌 + 토스포인트 ⇒ 가능
- 토스머니 + 토스포인트 ⇒ 가능
- 카드 + 토스머니 ⇒ 불가능
- 카드 + 계좌 ⇒ 불가능
토스포인트 100%로 결제가 가능한가요? 공통
계좌결제 선택 후 토스포인트를 사용하는 경우, 토스포인트 100%로 결제할 수 있습니다.
토스포인트는 독립적인 지불수단이 아니므로 카드/계좌 선택 후 토스포인트 결제가 가능합니다.
카드 선택 시 최소결제금액 100원 조건이 존재하여 카드 100원 + 나머지 토스포인트 결제로 처리되며, 계좌 선택 시 전액 토스포인트 결제가 가능합니다.
예시: 8000포인트 존재 → 8,000원 상품을 구매할 때
- 카드 선택: 최소 결제금액 100원 + 토스포인트 7900원 사용됨
- 계좌 선택: 최소결제금액 없이 토스포인트 전액 사용 가능
결제 금액 한도가 있나요? 공통
결제수단 1회 결제 한도
| | 최소 결제 금액 | 최대 결제 금액 |
| 토스(페이)머니/계좌결제 | 1원 | 200만원 |
| 카드결제 | 100원 | 고객 카드 한도 (토스페이의 제한은 없음) |
결제고객 토스(페이)머니/계좌 결제 한도
카드 결제의 경우 고객 카드 한도에 따라 적용됩니다.
| | 1회 한도 | 일 한도 | 월 한도 |
| 성인 회원 | 200만원 | 200만원 | 없음 |
| 미성년자 회원 (만 19세 미만) | 50만원 | 100만원 | 200만원 |
가맹점 결제 한도
아래 한도는 표준 한도이며, 가맹점의 판매 품목이나 Risk 등급에 따라 달라질 수 있습니다.
| | 1회 한도 | 일 한도 | 월 한도 |
| 일반 가맹점 | 없음 | 1,000만원 | 1,000만원 |
| 고환금성 가맹점 | 30만원 | 200만원 | 500만원 |
승인결과에서 계좌결제와 토스머니 결제를 구분할 수 있나요? 공통
계좌결제, 토스(페이)머니 모두 payMethod(결제수단) 값이 동일하게 TOSS_MONEY로 응답되므로 두 결제수단의 구분을 위해서는 accountBankCode(은행코드) 값을 확인해주셔야 합니다.
토스머니/토스페이머니 결제 시 888 코드 응답
```
accountBankName: 토스머니
accountBankCode: 888
accountNumber: 0000000000
```
계좌 결제 시 결제계좌의 은행코드 응답
```
accountBankName: 우리은행 // 결제계좌 은행
accountBankCode: 020 // 결제계좌 은행코드
accountNumber: 100*******792 // 결제계좌번호
```
용어정리
- 토스머니: 미성년자(만7세~19세미만) 대상 선불전자지급수단으로, 토스머니 충전 후 결제하는 방식 (성인은 fade out 처리됨)
- 토스페이머니: 성인 대상 선불전자지급수단으로, 토스페이머니 충전 후 결제하는 방식
- 계좌결제: 계좌에서 직접 출금되는 것이 아닌 계좌를 통해 토스머니를 충전한 후, 그 충전된 금액으로 결제하는 방식 (backend 로직: 고객 계좌 → 토스머니통으로 충전 → 결제)
승인결과에서 토스포인트, 즉시할인 금액을 구분하고 싶어요 공통
승인결과 응답 시, 결제 요청금액에서 토스포인트, 즉시할인 사용 금액을 합산하여 discountedAmount 값으로 전달하고 있습니다.
토스포인트, 즉시할인 금액을 합산하여 응답하는 이유
- 토스포인트와 즉시할인 모두 결제금액 자체를 차감하는 역할입니다.
- 토스에서 부담하는 금액이므로 정산 시 수수료는 결제요청금액 기준으로 계산합니다. 따라서 가맹점에서 별도로 토스포인트, 즉시할인 금액을 구분하실 필요가 없습니다.
- 현금영수증 발행 대상이 아닙니다. (토스포인트는 무상지급포인트이기에 현금영수증을 발행하지 않습니다.)
retUrl 이동이 실패하는 경우에는 어떡하나요? 공통
retUrl의 이동은 토스 web page에서 처리되는 로직으로 일반적인 경우 처리를 보장하지만 특별한 상황에서 실패할 수 있습니다.
특별한 상황이란, 구매자가 결제 중에 앱을 종료하거나 백그라운드 처리를 하는 등의 이탈로 JavaScript 로직이 처리될 수 없는 경우입니다.
이 경우 구매자가 다시 결제 화면으로 돌아와서 '결제완료' 버튼을 클릭한다면 retUrl로의 이동을 재시도하게 됩니다. 다만, 구매자가 재시도를 하지 않는 경우에는 retUrl로 이동하지 못하는 상황이 발생할 수 있습니다.
ResultCallback이란 무엇인가요? 공통
ResultCallback은 토스 서버에서 가맹점 서버로 결제 결과를 안전하게 전달하는 서버 간 통신 방식입니다.
ResultCallback은 왜 사용해야 하나요?
- retUrl은 단순히 사용자 브라우저를 리다이렉트하는 용도로, 결제 성공 여부를 토스에서 보장할 수 없습니다.
- 사용자가 중간에 이탈하거나 네트워크 문제가 발생하면, 결제 상태를 알 수 없는 경우가 생깁니다.
- ResultCallback은 서버 to 서버로 결과를 전달하므로 데이터 유실이 없고 안전한 통신 방식으로 결제 상태를 정확히 확인할 수 있습니다.
반드시 ResultCallback을 사용해야 하나요?
- 자동 승인 설정(autoExecute=true)인 경우, 반드시 ResultCallback을 구현해야 합니다.
- 결제 상태의 정확한 확인을 위해 모든 가맹점에서 ResultCallback 사용을 권장합니다.
ResultCallback 사용 시 주의점
ResultCallback에 내부망 주소를 사용하지 마세요
ResultCallback 결제 결과를 전달받기 위해 가맹점이 설정하는 URL로 토스 서버에서 외부 호출이 가능한 주소여야 합니다. localhost, 사설 IP, 내부망 도메인 등은 호출할 수 없어 오류가 발생합니다.
사용 불가 예시
- localhost, 127.0.0.1 등 루프백 주소
- 192.168.x.x, 10.x.x.x, 172.16.x.x ~ 172.31.x.x 등 사설 IP
- .local, .internal 등 내부 전용 도메인
발생할 수 있는 오류 메시지
```
error: resultCallback URL은 해당 가맹점의 URL 혹은 외부 아이피로 지정해 주어야 합니다.
```
해결 방법: ResultCallback의 주소를 공용 도메인 또는 VPN 외부에서도 접근 가능한 서버의 URL로 설정해 주세요.
실패한 콜백 재시도 정책
토스 서버는 실패한 콜백 요청을 최대 4번까지 재시도합니다.
재시도 간격
- 최초 실패 후 3분 간격으로 재시도 진행
- 최종 재시도는 17분 이내에 이루어집니다
타임아웃 처리는 어떻게 하나요? 공통
토스는 일반 은행계좌에서 토스머니로 충전 시 최대 10초의 타임아웃 시간을 설정합니다.
따라서, 가맹점에서는 10초 + 3~5초 정도의 대기 시간을 잡아주시면 타임아웃으로 인한 대사 불일치 거래건이 발생하지 않습니다. (처리 지연으로 가맹점은 취소 처리했으나 토스는 승인되는 케이스 방지)
토스 이슈가 아닌 은행망 이슈를 제외하면 타임아웃으로 인한 거래 지연은 발생하지 않습니다.
- 결제수단 구분 없이 모두 동일하게 설정하셔도 무방합니다.
- 양사간 거래 확인을 위하여 정산대사를 함께 연동하시길 권장드립니다. 요청 가맹점에 한하여 별도로 제공해 드리고 있으며, 신청은 support-pay@toss.im 으로 주시기 바랍니다.
토스 인코딩 방식이 궁금해요 공통
토스 인코딩 방식은 UTF-8 형식을 사용합니다.
가맹점에서 토스 서버로 한글이 포함된 값(주문번호, 상품명 등)을 보내주실 때, UTF-8 형식으로 보내주셔야 정상적인 response 값을 확인하실 수 있습니다.
주의: 깨진 한글이 유입되면 토스 서버는 필수 값 체크를 못해 500에러 등의 오류가 발생할 수 있습니다.
토스 연동을 위한 방화벽 설정 방법이 궁금해요 공통
구매자는 인증을 완료했지만 가맹점 retUrl로 결제 결과가 오지 않거나, 토스 서버로부터 resultCallback 결과를 받지 못할 경우, 먼저 방화벽 설정을 확인해야 합니다.
가맹점에서 토스 서버로 접근하는 경우 (결제 생성, 결제 승인 등의 API)
구조: 가맹점 ➔ 가맹점 방화벽 ➔ 토스페이
가맹점 방화벽의 outbound 정책에 아래 토스 IP를 추가해 주시면 됩니다.
도메인: pay.toss.im (port: 443)
- 117.52.3.202
- 117.52.3.210
- 211.115.96.202
- 211.115.96.210
- 106.249.5.202
- 106.249.5.210
데이터센터 신설로 IP가 추가될 예정입니다. 106.249.5.202, 106.249.5.210 IP에 대해 방화벽 설정을 확인해 주세요.
토스 서버에서 가맹점으로 접근하는 경우 ( resultCallback 포함)
구조: 토스페이 ➔ 가맹점 방화벽 ➔ 가맹점
가맹점 방화벽의 inbound 정책에 아래 토스 IP를 추가해 주시면 됩니다.
도메인: pay.toss.im (port: 443)
- 117.52.3.4
- 117.52.3.11
- 117.52.3.80~87
- 211.115.96.4
- 211.115.96.11
- 211.115.96.80~87
- 106.249.5.80~87
데이터센터 신설로 IP가 추가될 예정입니다. 106.249.5.80~87 IP에 대해 방화벽 설정을 확인해 주세요.
참고 사항
- 토스페이 방화벽은 제한 없이 모두 오픈되어 있습니다.
- 각 케이스 별 구분이 어려울 경우, Outbound와 Inbound 정책에 맞게 모든 토스 IP를 추가할 수 있습니다.
- 가맹점이 설정한 resultCallback URL에 443 이외의 포트가 포함되어 있다면 접근이 어려울 수 있습니다.
- 토스 서버의 IP가 추가되는 경우, 사전에 공지 메일을 발송해 드립니다.
토스페이 온라인 결제 프로세스가 궁금해요 일반결제
STEP1: 결제 생성
- 고객 결제 요청
- 가맹점 서버 → 토스페이로 결제URL 생성 요청
- 토스페이 → 가맹점으로 결제URL(checkoutPage) 응답
- 고객 화면에 checkoutPage를 호출하여 '토스 페이프론트'로 이동
TIP: 결제 생성 단계에서 결제의 전반적인 세팅을 제어할 수 있어요 - 현금영수증 발행 여부 (cashReceipt) - 결제 진행 시 자동 승인 여부 (autoExecute)
STEP2: 토스APP 인증
- 토스 페이프론트에서 [다음] 클릭 시, 토스 APP 호출
- 결제수단 선택 → [결제하기] 클릭 → 생체/비밀번호 인증
- 계좌 결제로 진행한 경우 인증완료 시점에 계좌 출금 → 토스머니 충전
TIP: 인증을 완료했더라도 '승인' 처리하지 않으면 실제 결제는 이루어지지 않습니다. 계좌 결제를 위해 출금된 토스머니도 결제 만료 시점까지 승인 요청하지 않으면 다시 계좌로 입금됩니다.
STEP3: 가맹점 결과페이지 retUrl로 이동
- 토스 APP 인증 완료 후 이전 브라우저 or 앱으로 이동
- 가맹점 결과페이지 retUrl로 이동 (retUrl은 가맹점에서 구현하는 결제 결과 페이지)
TIP: - autoExecute=true로 결제 생성한 경우 자동승인 → 실제 결제 (STEP4 승인요청 단계 진행 안함, resultCallback에서 승인결과 확인) - autoExecute=false로 결제 생성한 경우 STEP4 승인 요청 필요 (승인 요청하지 않으면 실제 결제가 이루어지지 않음, 3~5분이 지나면 결제토큰 만료 PAY_CANCEL)
STEP4: 승인 요청
- 결제생성 시 autoExecute 값을 세팅하지 않거나 'false'로 세팅한 경우, 승인요청 API를 호출해야 실제 결제가 이루어집니다.
- 승인 요청을 위해 결제토큰 값이 필요하나, retUrl 인증결과 데이터에 결제토큰이 포함되어 있지 않습니다. 따라서 결제 생성 단계에서 주문번호와 결제토큰을 함께 저장해두었다가 승인 요청 시 결제토큰을 매핑해서 요청하도록 구현해야 합니다.
STEP5: 승인결과 콜백
- 최종적인 승인 결과를 판단할 수 있는 단계입니다.
- 결제생성 시 resultCallback 필드에 세팅한 URL로 콜백이 전송되며, 자동승인 옵션(autoExecute=true)을 사용하는 경우에는 필수로 사용해야 합니다.
autoExecute 값에 따라 결제 프로세스가 어떻게 달라지나요? 일반결제
autoExecute 옵션은 자동 승인 여부를 제어하는 역할을 합니다.
고객 인증과 동시에 자동으로 승인할 것인지, 가맹점에서 승인 시점을 제어할 것인지에 따라 알맞게 autoExecute 필드 값을 세팅해주시면 됩니다.
autoExecute = true
- 고객이 토스 앱에서 인증 완료 시, 승인이 자동으로 처리됩니다.
- 승인에 대한 결과는 토스페이 → 가맹점 resultCallback으로 전송합니다.
- retUrl 전환 여부와 무관하게 자동으로 결제 승인까지 이루어지므로 편리합니다.
autoExecute = false
- value 값이 없거나, 오세팅된 경우에도 false와 동일하게 동작합니다.
- 가맹점에서 승인요청 API를 호출해야 승인 처리됩니다.
- 가맹점에서 고객인증 ↔ 승인 사이에 내부 처리(재고확인 등) 프로세스 구현할 수 있습니다.
- 인증 후 결제만료시간 3분 내로 승인 요청이 없을 경우, 결제 만료 처리되어 승인 실패됩니다.
결제승인 되지 않았는데 고객은 출금 되었어요 일반결제
토스페이 계좌 결제는 선불전자지급수단으로, 고객 계좌 → 토스머니 충전 → 결제 단계를 거치게 됩니다.
선불전자지급수단이란? 전자금융거래법안에서 이전 가능한 금전적 가치를 전자적 방법으로 저장하여 발행된 증표 또는 정보 - 토스머니: 토스에 가입한 유저에게 제공되는 송금 및 결제시 사용할 수 있는 선불전자지급수단
토스페이 결제 프로세스 중 계좌 출금되는 시점과 가맹점 결제가 이루어지는 시점은 아래와 같습니다.
- 토스APP 인증: 고객 계좌 출금 → 토스머니 충전
- 결제 승인: 토스머니 → 실제 결제 → 가맹점으로 응답
자동승인(autoExecute=true) 기능을 사용하는 가맹점은 인증과 동시에 승인이 자동으로 이루어져 이슈가 없으나, 자동승인 기능을 사용하지 않는 가맹점은 고객인증 ↔ 승인 구간에 단절이 있을 때 고객은 출금 상태이나, 가맹점은 결제내역이 없는 경우가 발생할 수 있습니다.
인증 후 결제토큰 만료시간 3분을 초과할 경우, 고객 계좌로 다시 환불 처리됩니다.
이때 결제 상태는 PAY_CANCEL로 저장되며 토스페이 파트너스에서 내역 조회가 가능합니다.
고객 인증완료 후 payToken 값이 응답되지 않아요 일반결제
인증 후 retUrl로 응답되는 데이터에는 payToken 값이 포함되어 있지 않습니다.
```
// 카드 예시
{retUrl}?status=PAY_COMPLETE&orderNo=test000&payMethod=CARD&cardCompany=10&cardBinNum=123456
// 토스머니/계좌 예시
{retUrl}?status=PAY_COMPLETE&orderNo=test111&payMethod=TOSS_MONEY&bankCode=004
```
자동 승인 옵션(autoExecute)을 사용하지 않는 경우, 승인API 요청을 위해 payToken 값이 필요합니다.
따라서 결제 생성 시 orderNo(주문번호)와 payToken을 함께 저장하셨다가 retUrl로 응답받은 orderNo값과 매핑된 payToken으로 승인 요청하시면 됩니다.
자동승인 옵션(autoExecute=true)을 사용하는 경우, 승인 API 호출 없이 자동으로 승인 처리되므로 retUrl로 응답받은 주문번호와 payToken을 매핑하는 과정이 필요치 않습니다. resultCallback 응답 값을 통해 payToken과 실제 결제 결과를 확인하시면 됩니다.
인증/승인 결제 유효 시간이 궁금해요 일반결제
결제 생성 후 checkoutPage 인증 유효시간
- 기본값: 15분
- 결제 생성 요청 시 expiredTime 필드에 만료시간 세팅 시 최대 60분까지 연장 가능
구매자 인증완료 후 승인 유효시간 (/api/v2/execute)
- 기본값: 3~5분
자동결제 서비스의 결제 프로세스가 궁금해요 자동결제
자동결제는 고객이 최초 1회 본인 인증을 통해 가맹점에 결제용 빌링키를 등록하면, 이후 가맹점이 해당 빌링키를 이용해 고객에게 반복적으로 과금을 처리할 수 있도록 하는 서비스입니다.
정기구독 모델을 운영하거나 자체 간편결제 기능을 제공하고자 하는 경우, 자동결제 방식을 활용하시면 됩니다.
1. 결제수단 등록(빌링키 생성)
고객이 최초 1회 인증 및 결제수단 등록을 완료하면 가맹점은 빌링키를 확보합니다.
2. 빌링 승인(실제 과금)
- 결제가 필요한 시점마다 가맹점에서 API를 호출해 과금 요청을 수행합니다.
- 금액 및 결제 주기는 상황에 따라 자유롭게 변경할 수 있습니다.
자동결제 빌링키는 1개만 등록이 가능한가요? 자동결제
하나의 가맹점 - 하나의 토스 유저 대상으로 하나의 빌링키만 사용 가능하나, 빌링키 생성 시, displayId 파라미터를 추가 세팅하면 여러 개의 빌링키를 등록할 수 있게 됩니다.
동일 유저의 빌링키를 추가 등록할 경우
displayId 없이:
- 최초 등록: 가맹점 apiKey - 유저(userId) - A빌링키(billingKey) → 등록 성공
- 추가 등록: 가맹점 apiKey - 유저(userId) - ERROR → 등록 실패
displayId 사용:
- 최초 등록: 가맹점 apiKey - 유저(userId) - displayId A(선택) - A빌링키(billingKey) → 등록 성공
- 추가 등록: 가맹점 apiKey - 유저(userId) - displayId B(필수) - B빌링키(billingKey) → 등록 성공
자동결제 금액이나 결제주기를 변경할 수 있나요? 자동결제
고객의 빌링키(billKey)로 자동결제를 발생시키는 주체는 가맹점입니다.
따라서 가맹점에서 원하는 시점에 원하는 금액으로 자동결제 승인 요청을 하시면 됩니다.
## 결제 환불
결제 후 환불 가능 기한은 언제까지인가요?
카드, 계좌, 토스(페이)머니 거래 모두 결제 승인일로부터 1년까지 환불이 가능하며, 유효 기간이 초과된 환불 요청 시, COMMON_REFUND_ERROR '환불이 불가능한 상태입니다.' 오류가 응답됩니다.
환불 처리 시 언제 고객에게 입금되나요?
결제수단별로 환불에 소요되는 시간은 아래와 같습니다.
계좌/토스(페이)머니 결제
- 머니: 수 분 이내
- 계좌: 수 분 이내 (은행 점검 시간일 경우 대기)
카드결제
전체환불
- 매입 전 취소(결제 당일 취소) 시 즉시 환불
- 매입 후 취소 시 D+1에 카드사로 취소 매입 전송 (카드사 → 고객 환불까지는 4~5일 소요될 수 있음)
부분환불
- 부분환불은 매입 후 취소로만 처리 가능하므로 승인 당일에 환불 요청해도 즉시 환불 X
- 승인매입 후, 취소 매입이 전송되어 고객 환불까지 5~6일 소요
결제 당일 부분환불 예시
| 일자 | 처리 단계 | 비고 |
| 11/6 (D) | 결제 승인, 부분 환불 요청 | |
| 11/7 (D+1) | 카드사로 승인매입 전송, 부분환불 처리 | |
| 11/8 (D+2) | 카드사로 취소매입 전송 | |
| 11/11~12 (D+5,6) | 카드사 내부 프로세스에 따라 고객 환불 처리 | 환불 완료까지 5~6일 소요될 수 있음 |
부분환불은 어떻게 하나요?
결제 환불 API로 전체환불과 부분환불 모두 처리가 가능합니다.
부분환불 요청 시 amount에 환불이 필요한 금액만큼 세팅해주시면 됩니다.
결제생성 당시 비과세금액(amountTaxFree)을 0 이외의 값으로 세팅한 경우, 부분환불 시 아래 과세, 부가세, 비과세 금액을 보내주셔야 합니다.
- amountTaxFree: 환불할 금액 중 비과세금액
- amountTaxable: 환불할 금액 중 과세금액
- amountVat: 환불할 금액 중 부가세
토스포인트 복합결제 부분환불 정책이 궁금해요
결제수단(카드, 토스페이머니) + 토스포인트 결제한 거래를 부분환불할 경우 원 결제수단을 우선적으로 환불한 후, 부족한 금액은 토스포인트로 환불됩니다.
예시: 10,000원 결제 = 계좌 5,000 + 토스포인트 5,000 일때, 부분취소 할 금액이 7,000원이면 계좌로 5,000원 환불 + 포인트로 2,000원 환불
프로모션 할인/적립 부분환불 정책이 궁금해요
프로모션 적립, 할인 거래의 경우 부분환불 후 남은 금액이 혜택 조건을 충족하는지 여부에 따라 적립/할인 회수율이 결정됩니다.
적립
| | 혜택조건 충족 (최소 결제금액 이상) | 혜택조건 미충족 (최소 결제금액 미만) |
| 정액 적립 | 적립금 유지 | 적립금 전체 회수 |
| 정률 적립 | 남은 결제금액을 기준으로 퍼센트 적용하여 적립금 재계산 | 적립금 전체 회수 |
할인
| | 혜택조건 충족 (최소 결제금액 이상) | 혜택조건 미충족 (최소 결제금액 미만) |
| 정액 할인 | 할인금액 유지 | 취소율을 계산하여 할인금액 부분취소 |
| 정률 할인 | 남은 결제금액을 기준으로 퍼센트 적용하여 재계산하여 할인 적용 | 남은 결제금액을 기준으로 퍼센트 적용하여 재계산하여 할인 적용 (최소결제금액 기준이 적용되지 않음) |
[정액할인] 5만원 이상 결제 시 5천원 할인 프로모션 - 부분환불 예시
부분환불 후 남은 결제금액이 최소결제금액을 미달할 경우, 미달한 금액의 비율을 계산하여 할인 취소금액 산정(소수점 반올림)
- 결제금액: 50,412
- 최소결제금액: 50,000
- 할인금액: 5,000
- 환불금액: 3,000
- 환불 후 남은 결제금액: 47,412
- 취소율: (50,000 - 47,412) / 50,000 = 0.05176
- 할인 취소금액: 5,000 * 0.05176 = 258.8 = 259
- 할인 취소금액을 제외한 환불금액: 3,000 - 259 = 2,741
결제수단 + 토스포인트 + 할인 거래일 경우 환불 우선순위
1순위 - 혜택조건 충족 여부에 따라 할인 취소금액을 제외하여 환불금액 산정 2순위 - 원 결제수단 환불 3순위 - 이후 남은 금액은 토스포인트 환불
## 현금영수증/매출전표
어떤 금액으로 현금영수증을 발행해야 하나요?
현금영수증은 현금성 거래인 계좌, 토스(페이)머니 결제를 대상으로 발행할 수 있으며, 토스 포인트, 즉시 할인 적용 금액은 제외해야 합니다.
따라서 현금영수증 자체 발행 시, 할인 금액을 제외한 순수 결제금액 필드인 paidAmount 값으로 처리해주시면 됩니다.
현금영수증 자동 발행 방법: 결제 생성 시, **cashReceipt = true**로 세팅하면 현금영수증이 자동으로 발행됩니다.
토스 포인트는 무상 지급 포인트 이므로 현금영수증 발행 대상이 아닙니다.
현금영수증이 자동 발행되지 않게 세팅하고 싶어요
하기 두 가지 방법을 통해 현금영수증 자동 발행을 제한할 수 있습니다.
1. 결제 생성 시 cashReceipt 필드 세팅
결제 생성 API 호출 시 cashReceipt = false로 세팅하면 해당 결제 건에 대해 현금영수증이 발행되지 않습니다.
2. MID 설정 변경 요청
가맹점 MID 전체에 대해 현금영수증 자동 발행을 비활성화하려면 토스페이 담당자에게 설정 변경을 요청해주세요.
결제 환불 시 현금영수증은 어떻게 되나요?
결제환불 시, 해당 거래건의 현금영수증도 자동으로 취소 처리되므로 가맹점에서 별도로 처리하실 사항은 없습니다.
전체환불
- 현금영수증 전체취소
부분환불
- 기존 현금영수증 전체취소
- 환불 후 남은금액 만큼 현금영수증 재발행
현금영수증을 취소하고 싶어요
현금영수증 취소에 대한 처리 유형에 따라 방법이 달라집니다.
결제와 현금영수증 모두 취소
결제 환불 API 요청 시 현금영수증도 함께 자동으로 취소됩니다.
만약 결제 부분환불을 했다면, 최초 발행된 현금영수증은 전체 취소한 후 환불 후 남은 금액으로 자동 재발행됩니다.
결제는 유지, 현금영수증만 취소
현금영수증 취소 API를 통해 현금영수증만 취소할 수 있습니다.
누락된 현금영수증을 발행 처리하고 싶어요
현금성 결제인 토스머니, 계좌 결제건 중 현금영수증이 발행되지 않은 경우, 현금영수증 API를 연동하거나 토스페이 파트너스(어드민)를 통해 발행 처리할 수 있습니다.
1. 현금영수증 API
API를 연동하여 가맹점 서버에서 현금영수증 발급/취소/상태조회 등을 처리할 수 있습니다. 현금영수증 API 연동가이드
2. 토스페이 파트너스
거래내역 [조회] > 주문번호 클릭 > 현금영수증 [발급하기]
현금영수증 발급 요청을 했는데 국세청에서 조회되지 않아요
현금영수증 발급 요청 후, 국세청 전송 및 승인 과정이 있어 실제 반영까지 통상 2~3일 정도 소요될 수 있습니다.
- 국세청으로 전송
- 국세청에서 확인 후 승인 또는 거절 등의 단계를 거쳐 처리
현금영수증 발행 정보를 변경하고 싶어요
유저가 앞으로 토스페이에서 발급되는 모든 현금영수증 정보를 변경하고자 하는 경우 토스 앱에서 설정할 수 있습니다. (Default: 토스 앱 가입 시 휴대폰번호로 설정)
토스 앱에 저장된 현금영수증 정보 변경하기
전체 메뉴 > 상단 돋보기 클릭하여 '현금영수증' 검색 > 현금영수증 정보
현금영수증 정보 변경 시, 변경 후 결제한 내역에만 반영되며 이전 결제 건에는 반영되지 않습니다.
이미 발행된 거래의 현금영수증 정보를 변경하기 위해서는 기존에 발행된 현금영수증을 취소하고 재발행해야 합니다.
1. 가맹점에서 현금영수증 재발행하기
현금영수증 API 재발행: 가맹점 서버에 현금영수증 API를 연동하여 기존 현금영수증을 취소하고 재발행할 수 있습니다. (결제는 유지, 현금영수증만 취소 처리)
토스페이 파트너스 재발행: 토스페이 파트너스 거래내역에서 현금영수증 취소 및 재발행 처리할 수 있습니다. 경로: 거래내역 [조회] > 주문번호 클릭 > 현금영수증 [발행하기] (이미 발행된 현금영수증이 있는 경우 - [취소] 후 [발행하기])
2. 결제고객이 현금영수증 재발행하기
토스 앱 內 토스페이 결제내역에서 현금영수증 재발행 처리가 가능합니다.
카드사 거래명세서나 결제 알림 SMS에 가맹점명이 아닌 '비바리퍼블리카'로 표시돼요
토스페이먼츠(PG)를 통해 카드사 서브몰 등록 시 결제 대행사의 대표 가맹점번호로 등록되기 때문에 카드사 거래명세서나 SMS에는 '비바리퍼블리카'로 노출되는 것이 정상입니다.
가맹점 고유 상호명으로 표시되길 원하는 경우, 토스페이 담당자를 통해 카드사로 간판명 변경 심사를 요청하셔야 합니다.
단, SMS에 표시되는 상호명(서브몰명)은 카드사 정책상 변경이 불가할 수 있습니다.
## 정산
정산금액 대사 방법이 궁금해요
정산대사는 아래 3가지 방법으로 진행하실 수 있습니다. 가맹점에서 희망하시는 방법으로 선택하여 확인하시면 됩니다.
1. 정산대사 API 연동
API를 통해 정산 데이터를 조회하여 대사를 진행할 수 있습니다.
2. 정산대사파일 SFTP 연동
IP등록, 계정 생성 등 세팅 절차가 필요한 서비스이므로, 정산 담당자와 협의가 필요합니다. 필요한 경우 토스페이 담당자에게 별도로 요청해주시기 바랍니다.
※ 응답 데이터는 정산대사 API와 동일합니다.
3. 토스페이 파트너스(어드민) 조회
토스페이 파트너스 > 정산 > 정산내역에서 엑셀 다운로드를 받아서 대사 진행
영중소 가맹점 카드결제 차액 정산 수수료를 조회할 수 있는 API가 있나요?
현재 제공되고 있는 정산 API는 일반 수수료로만 응답되며, 영중소 등급에 따른 수수료 확인은 불가합니다. (차액 정산 수수료용 API는 별도로 존재하지 않음)
따라서 토스페이 파트너스 메뉴를 통해 일별, 결제건별 차액정산 내역을 조회하셔야 합니다.
경로: 토스페이 파트너스 > 정산 > 차액정산내역 or 결제 건별 차액정산내역
## 기타
디자인 가이드는 어디서 받나요?
토스페이 디자인 가이드는 메인 페이지 하단에서 다운로드 받을 수 있습니다.
---
# 수수료 정책
URL: /policy/fee
토스 간편결제 결제대행 수수료 정책은 다음과 같습니다.
## 수수료 정책 (온라인)
| 결제수단 | 영중소 가맹점 구분 | 수수료율 (VAT 별도) |
| 토스머니, 카드, 후불결제 | 일반 | 3.00% |
| | 중소3 | 2.40% |
| | 중소2 | 2.15% |
| | 중소1 | 1.90% |
| | 영세 | 1.60% |
- 수수료는 가맹점 계약 내용에 따라 각 지불 수단별로 상이하게 적용됩니다.
- 수수료는 업종/판매 품목 별로 상이할 수 있으며, 당사와 협의 후 조정 가능합니다.
- 호스팅사, PG사(KG 이니시스 등)를 통해 진행하는 경우 해당 호스팅사, PG사 수수료 정책에 따라 적용됩니다.
- 모든 수수료는 부가세 별도입니다.
- 토스 부담 금액(토스 포인트, 즉시할인 사용 금액)은 원결제 수단의 수수료율이 적용됩니다.
### 영중소 가맹점 구분
- 반기 1회 여신금융협회(또는 국세청)에서 제공하는 가맹점 기준(연매출 규모)에 따라 수수료가 산정됩니다.
### 2024년 하반기부터 등급 반영 시점 변경:
- 24.5.21 「여신전문금융업 감독규정」 개정/시행에 따라 환급일자 변경
- 감독규정 제 25조의 6제4항 ‘우대수수료율 선정작업 기간 반기 종료 후 45일 이내’로 변경
- 기존: 상반기 1.31-7.30 / 하반기 7.31-1.30
- 변경: 상반기 2.14-8.13 / 하반기 8.14-2.13
- 2024년 상반기 등급은 1.31~8.13 기간 동안 적용됩니다.
- 토스머니는 원천사가 '토스페이'이기 때문에 즉시 적용됩니다. (단, 호스팅/PG사 연동 가맹점은 제외)
- 카드는 원천사가 '카드사'이기 때문에 카드사로부터 데이터 수신 및 정산받는 기간을 고려하여 차액 정산 형태로 적용됩니다.
## 수수료 정책 (오프라인)
| 결제수단 | 영중소 가맹점 구분 | 수수료율 (VAT 별도) |
| 토스머니 | 일반 | 1.8% |
| | 중소 | 1.2% |
| | 영세 | 0.8% |
- 카드 결제 수수료율은 가맹점과 카드사 간 체결된 신용카드 가맹 계약에 따르며, 토스는 토스페이 회원 인증 및 관련 업무만을 수행합니다.
- 일부 특수 업종 또는 일부 대형 프랜차이즈 자영점의 경우 위 수수료율 적용 대상에서 제외될 수 있습니다.
### 영중소 가맹점 구분
- 반기 1회 여신금융협회(또는 국세청)에서 제공하는 가맹점 기준(연매출 규모)에 따라 수수료가 산정됩니다.
## 수수료 적용 및 계산
- 거래 건별 승인 시점에 등록된 수수료율로 산출되며, 취소 거래 발생 시 승인 시점의 수수료를 따라갑니다. (취소 시 수수료는 가맹점 계약별로 상이할 수 있습니다.)
- 수수료는 정률(%)로 계산됩니다.
- 수수료: 결제 건별 거래 금액 * 수수료율 (소수점 버림, 예: 1100.7원 → 1100원)
- 부가세: 결제 건별 수수료 * 10% (소수점 반올림, 예: 110.7원 → 111원)
- 수수료는 선취되어 가맹점과 계약된 정산 주기에 따라 지급됩니다.
---
# 서비스 정책
URL: /policy/service
## 구매자 회원 가입 조건
만 14세 이상이면 누구나 회원 가입 후 토스페이를 이용할 수 있습니다. 토스머니는 자신의 은행 계좌를 통해 자동 충전할 수 있고, 카드 결제는 본인 명의의 카드를 등록해서 사용할 수 있습니다.
### 토스 머니
- 지원 은행: 우리 / KB국민 / IBK기업 / 부산 / 경남 / 우체국 / 광주 / 전북 / 새마을 / NH농협 / 신협 / SC제일 / 대구 / KDB산업 / 제주 / KEB하나 (구 외환은행 포함) / 수협 / 신한 / 카카오뱅크 / SBI 저축은행 / 케이뱅크 / 씨티 / 산림조합 / 저축은행 / 토스뱅크
- 지원 증권사: 키움 / 삼성 / NH투자 / 대신 / 신한금융투자 / 메리츠증권 / 유진투자 / 미래에셋대우 / 한국투자 / 한화투자 / 교보 / 이베스트 / SK / 동부(DB금융투자) / KB증권 / 하이투자 / HMC투자(현대차투자) / 하나금융 / 토스증권
### 카드
- 지원 카드사: 롯데 / 비씨 / 삼성 / 신한 / 하나 / 현대 / 국민 / 농협 / 우리 (매입 카드사 기준) 그 외 카드사는 현재 준비 중입니다.
## 구매자 결제 한도
### 일/월 한도
#### 성인 회원
- 회원당 1회 2,000,000원까지 결제 가능 (이를 초과하는 결제는 생성할 수 없습니다)
- 회원당 1일 누적 2,000,000원까지 결제 가능
#### 미성년자 회원 (만 19세 미만)
- 회원당 1회 500,000원까지 결제 가능
- 회원당 1일 누적 1,000,000원까지 결제 가능
- 회원당 1개월 누적 2,000,000원까지 결제 가능
### 주의 사항
- 위 한도는 토스 머니에 해당하는 표준 한도입니다. 카드 결제는 구매자 개인의 카드 한도에 따라 적용됩니다.
- 각 가맹점별/고객별 판매 품목이나 Risk 등급에 따라 결제 가능 한도를 제한할 수 있습니다.
- 구매 한도는 결제 금액과 더불어 토스 송금액도 함께 합산됩니다.
### 취소/환불 시 한도 회복
- 당일 취소/환불 시 일 한도 회복, 당월 취소/환불 시 월 한도 회복
예시
- 6/29 결제 500,000원 → 6/29 당일 환불 완료 시
- 6/29 일 결제 한도 +500,000
- 6월 월 결제 한도 +500,000
- 6/29 결제 500,000원 → 6/30 환불 완료 시
- 6/30 일 결제 한도 변함 없음
- 6월 월 결제 한도 +500,000
- 6/30 결제 500,000원 → 7/1 환불 완료 시
- 7/1 일 결제 한도 변함 없음
- 7월 월 결제 한도 변함 없음
## 결제 최소 금액
토스페이에서 지원하는 각 결제 수단별 최소 결제 금액은 다음과 같습니다. 즉시할인 등을 포함하는 경우 총 결제 완료 금액 기준이며, 복합 결제 시 포인트를 제외한 실결제 금액 기준입니다.
- 토스머니: 1원 이상부터 결제 가능
- 카드: 100원 이상부터 결제 가능 (전 카드사 동일)
## 결제 가맹점의 준수 사항
가맹점은 아래 사항을 준수해야 합니다.
- 가맹점은 전자화폐 등에 의한 거래를 이유로 재화 또는 용역의 제공을 거절하거나, 이용자를 불리하게 대우해서는 안됩니다.
- 가맹점은 이용자로 하여금 가맹점 수수료를 부담하게 해서는 안됩니다.
- 가맹점은 다음과 같은 행위를 해서는 안됩니다.
- 전자화폐 등을 이용하여 재화나 용역의 제공이 없이 거래를 가장하는 행위
- 실제 매출 금액을 초과하여 전자화폐 등에 의한 거래를 하는 행위
- 다른 가맹점 이름으로 전자화폐 등에 의한 거래를 하는 행위
- 가맹점의 이름을 타인에게 빌려주는 행위
- 전자화폐 등에 의한 거래를 대행하는 행위
- 가맹점이 아닌 자는 가맹점의 이름으로 전자화폐 등에 의한 거래를 해서는 안됩니다.
## 토스의 책임 사항
토스는 아래와 같은 거래에 따른 손실을 가맹점에 떠넘길 수 없습니다. 다만, 토스가 그 거래에 대해 가맹점의 고의 또는 중대한 과실을 증명하는 경우에는 그 손실의 전부 또는 일부를 가맹점의 부담으로 할 수 있다는 취지의 계약을 가맹점과 체결한 경우에는 예외로 합니다.
- 분실되거나 도난된 전자화폐 등에 의한 거래
- 위조되거나 변조된 전자화폐 등에 의한 거래
---
# 환불 정책
URL: /policy/refund
토스 간편결제 환불 정책은 다음과 같습니다.
## 정의
결제를 생성하고 완료된 이후에 지불한 금액을 다시 돌려받는 행위로, 환불 요청 시 환불 금액이 해당 가맹점의 환불 한도보다 작으면 환불 완료 처리하고, 크면 거부 처리합니다.
## 환불 과정
## 가맹점의 환불 한도
각 '가맹점'별로 '환불 한도'가 부여되며, 환불 한도 내의 환불 신청은 즉시 처리됩니다. ('환불 한도'만 확보하면 정산 여부나 결제 시기와 상관 없이 유연한 환불이 가능합니다.)
환불 한도 상세 정책
- 환불 한도는 "D+1 이후의 정산 예정 금액 + 가맹점 잔액 + 당일 승인 - 당일 환불 + 기본 환불 한도"로 산출됩니다.
- 환불 한도는 각 가맹점별로 부여됩니다.
- 환불 한도는 매일 01시에 환불 한도 산출 정책에 따라 새로 계산됩니다.
- 환불 한도는 매 3분마다 당일 승인과 환불액을 반영하여 갱신됩니다.
- 기본 환불 한도는 가맹점 매출액 기준에 따라 차등으로 부여하고 있습니다.
- 환불 한도 증액을 원하시면, 토스페이 계좌로 예치금 입금 혹은 정산 주기를 연장할 수 있습니다.
- 환불 한도 관련 문의사항은 토스페이팀으로 주세요.
## 전액/부분 환불 가능 여부
전액 환불과 부분 환불 모두 가능하며, 복합 결제의 경우 아래와 같이 환불됩니다.
- 복합 결제 전액 환불: 원 결제 수단으로 환불되며 포인트는 반환됩니다.
- 복합 결제 부분 환불: 원 결제 수단을 먼저 반영한 이후 포인트는 가장 나중에 환불 처리됩니다.
## 탈퇴 유저 환불 처리
- 토스 탈퇴 시, 환불 계좌가 등록되어 있는 경우 해당 계좌로 환불 처리하며, 토스에 가입된 사용자 휴대폰 번호로 입금 LMS를 발송합니다.
- 환불 계좌 등록 시, 별도의 개인정보 동의를 체크하여 탈퇴 후 1년간 해당 정보를 저장합니다.
- 토스를 통한 환불 거래가 발생하지 않으므로 수수료 보전이나 세금계산서 반영은 불가합니다.
## 환불 금액은 어디로 가는가?
- 카드 결제는 결제 시 사용한 카드에 연결된 계좌로, 계좌 결제는 해당 계좌로 환불됩니다.
- 토스머니 결제는 환불 금액이 토스머니로 반환되어 별도 환불 계좌를 수집하지 않아도 됩니다.
- 토스머니 결제 건 환불 시 해당 거래의 환불 후 잔액이 200만원 이상인 경우 결제 충전용 계좌로 환불됩니다.
## 환불 가능 기간
- 일반적인 결제는 결제 승인일로부터 1년까지 환불이 가능합니다.
- 유효 기간이 초과된 환불 요청 시, COMMON_REFUND_ERROR 오류 메시지 "환불이 불가능한 상태입니다."가 반환됩니다.
## 환불 시 발생하는 사용자 계좌정보 조회 실패 오류
토스머니 환불은 가맹점의 환불 요청과 동시에 즉시 사용자 토스 계정으로 환급 처리됩니다. 그러나 환불 요청 시 COMMON_ASSET_GET_ACCOUNT_ERROR "계좌 정보 조회에 실패했습니다." 오류가 발생한다면, 구매자의 토스 계정이 임시 차단된 상태일 수 있습니다. 이 경우, 구매자가 직접 토스 고객센터로 연락해 계정 활성화를 요청한 후, 가맹점은 재환불을 진행해주시면 됩니다.
---
# 정산 / 지급 정책
URL: /policy/settle
## 정산 및 지급 과정
가맹점에 지급할 총 금액을 언제 지급할지 계산하고 계산된 금액을 가맹점에 지급하는 과정입니다.
### 1. 정산 집계 (일마감)
- 매일 지정된 시간에 전일 발생한 거래 분에 대한 정산 금액을 산출합니다. (가맹점별)
- 집계 시간: 새벽 00시 ~ 01시 사이
- 집계 대상: 전일자 거래 건(승인 - 환불)
- 지급 금액:
### 2. 채권 관리
- 채권: 고객 환불로 인한 음수(-) 정산 대금을 의미하며, 지급보류 및 타잔액상계 기능으로 관리됩니다.
#### 지급보류
- 채권 발생 대비 지급보류: 정산 주기 내 발생한 채권(환불)로 인해 미수가 발생할 경우 당일 정산금액에서 지급 보류합니다.
- 채권이 확인되면 가까운 정산일에 차감됩니다.
- 당일 정산 예정 금액이 음수(-)인 경우 지급이 불가하여 그대로 지급 보류 후, 정산 예정 금액이 발생 시 자동 상계됩니다.
- 지급보류 이력: 아래 경로에서 확인할 수 있습니다.
- 토스페이 파트너스 > 정산내역조회 > 잔액 내역 및 별도가감 내역 > 잔액 내역 메뉴
- 토스페이 파트너스 > 정산내역조회 > 정산내역 > ‘지급일’ 기준으로 조회
#### 타잔액상계
- 정산일 기준으로 정산 예정 금액이 음수(-)인 경우 동일 회사의 하위 가맹점 중 가장 큰 정산 지급액이 있는 곳에서 자동 상계 처리됩니다. (상계 대상 가맹점 지정 불가)
- 타잔액상계 이력: 아래 경로에서 확인할 수 있습니다.
- 토스페이 파트너스 > 정산내역조회 > 잔액 내역 및 별도가감 내역 > 별도가감 메뉴
- 토스페이 파트너스 > 정산내역조회 > 정산내역 > ‘지급일’ 기준으로 조회
### 3. 금액 대사 및 보정/확정
- 매 영업일마다 비바리퍼블리카 정산 담당자가 각 가맹점에 지급할 금액을 확인하고, 필요 시 보정을 진행한 후 최종 확정합니다. (영업일 13시 전까지)
### 4. 정산금액 가맹점 지급
- 확정된 정산 금액을 각 가맹점의 정산 계좌로 입금합니다.
- 지급 시 조회된 정산 계좌의 예금주가 토스페이 시스템에 등록된 예금주와 상이할 경우 변경 전까지 지급이 보류됩니다.
- 입금 시 적요는 ‘Toss정산MMDD’로 표시됩니다.
## 정산 주기
- 일 지급(카드 사용 가맹점의 경우 D+4 이상) 및 월 지급 유형 중 선택할 수 있습니다.
- 결제 정산 주기와 별개로 영중소 가맹점 카드 결제 수수료 차액 정산은 통상 6일(D+6) 후 지급됩니다.
- 일 지급 가맹점이 아닌 경우 지정된 지급 일자가 길어질 수 있습니다.
- 정산 주기 변경을 원하시는 경우 토스페이 공식메일(support-pay@toss.im)로 문의해 주세요.
## 세금계산서 발행
- 정산 지급 시 ‘선취’된 수수료의 합계 금액에 대한 증빙으로 영수 세금계산서가 발행됩니다.
- 국세청 개정안에 따라 세금계산서는 아래 기준으로 발행됩니다.
- 공급가액 = (수수료 + 부가세) / 1.1
- 부가세 = (수수료 + 부가세) - 공급가액
## 현금영수증 및 신용카드 매출 전표
### 온라인
#### 신용카드 매출 전표
- 카드 결제건에 한해 자동 발행됩니다.
- 매출 전표 내 거래금액 및 할인/포인트 금액이 표시되며 공급가액/부가세는 표시되지 않습니다.
#### 현금영수증
- 계약 시 토스페이의 발행 대행 서비스에 동의한 가맹점에 한해 포인트/할인 제외한 현금 결제 금액이 자동 발행되어 국세청에 전송됩니다.
- 결제 시 가맹점에서 전달하는 과/면세 파라미터 값(API)에 따라 공급가액/부가세가 구분됩니다.
### 오프라인
#### 선불전자영수증
- 오프라인 토스머니(현금) 결제분은 ‘선불전자영수증’으로 발행됩니다.
- 선불전자영수증은 연 1회 연말정산 기간에 국세청에서 확인할 수 있으며, 현금매출이 아닌 직불카드-선불전자지급수단 매출로 분류됩니다.
---
# 토스페이 소개
URL: /offline/introduce/tosspay
AI 도구로 연동을 개발하고 있다면 오프라인 문서를 포함한 토스페이 가이드 전체를 LLM이 읽기 좋은 /llms.txt로 제공해요. 활용 방법은 AI 도구로 연동하기를 참고하세요.
## 오프라인 결제가 동작하는 방식
오프라인 결제는 POS → VAN → 토스페이 순서로 흐름이 이어져요.
- POS는 매장의 주문과 재고 관리가 중심이에요. 실제 결제를 처리하지 않고, 리더기에서 스캔된 결제 정보를 받아 VAN으로 전달하는 역할을 해요.
- VAN은 POS와 토스페이를 연결하는 중간 처리자예요. POS에서 발생한 결제 요청을 토스페이에 전달하고, 승인 결과를 다시 POS로 내려줘요.
- 토스페이는 결제수단에 따라 승인 또는 인증을 처리하고, 최종 결제 결과를 VAN으로 전달해요.
이 구조 덕분에 POS는 복잡한 결제 프로세스를 직접 구현할 필요가 없고, 대부분의 매장에서 사용 중인 VAN 모듈만으로 토스페이를 쉽게 연동할 수 있어요.
## POS에서 사용하는 리더기
매장에서는 고객의 QR 또는 얼굴 정보를 인식하기 위해 리더기를 사용해요. 리더기 구성은 매장 환경에 따라 달라질 수 있어요.
- 단일 리더기
- 바코드 리더기
- 페이스페이용 리더기(프론트캠, 프론트뷰)
- 멀티패드 리더기
- 프론트(Front) 리더기처럼 다양한 결제 방식을 한 기기에서 처리할 수 있는 형태예요.
POS와 리더기만 갖춰져 있다면, 언제든 VAN 모듈을 통해 토스페이 결제를 받을 수 있어요.
## 결제수단에 따라 달라지는 승인 방식
토스페이는 다양한 결제수단을 지원하고 있고, 각 수단은 최종 승인을 처리하는 방식이 달라요.
### 머니/계좌 결제
사용자가 토스머니나 계좌로 결제하면, 승인은 토스페이가 직접 처리해요.
승인 요청이 한 번만 오가면 되기 때문에 빠르고 구조가 단순해요.
### 카드 결제
카드 결제는 VAN과 카드사가 추가로 참여하는 구조예요.
- VAN이 카드사로 승인 요청을 보내요.
- 토스페이는 고객 인증을 담당해요.
- 최종 승인결과는 카드사에서 실시간 전문으로 전달돼요.
또한, 카드 결제는 매입 처리 이후 취소가 필요할 때 카드사에서 배치로 취소 전문을 보내기 때문에 실시간 흐름과는 조금 달라요.
## 결제수단 관리 방식
사용자는 토스앱 안에서 계좌·카드·머니를 손쉽게 등록하고 관리할 수 있어요.
등록된 결제수단은 온라인과 오프라인에서 모두 동일하게 사용할 수 있어요.
- 계좌는 마이데이터 기반 인증으로 등록돼요.
- 카드는 직접 입력하거나, 카드사 앱을 통해 인증을 거쳐 등록돼요.
- 등록된 결제수단은 QR결제, 페이스페이 등 모든 토스페이 결제에서 바로 사용할 수 있어요.
- 삭제하면 즉시 모든 토스페이 결제에서 사용되지 않아요.
토스페이는 결제수단을 통합 관리하기 때문에 사용자는 결제 환경에 상관없이 동일한 경험을 제공받을 수 있어요.
## 왜 도입하기 쉬울까요?
토스페이는 이미 국내 주요 VAN들과 연동을 완료하고 있어요.
매장이 사용하는 POS가 이 VAN 모듈을 사용하고 있다면, 대부분의 경우 별도 개발 없이 바로 토스페이를 추가할 수 있어요.
POS와 리더기가 준비되어 있고 해당 VAN에서 토스페이를 지원한다면 매장은 바로 토스페이 결제수단을 활성화할 수 있어요.
토스페이 결제 토큰 기반으로 빠르게 연동되는 구조라서 도입 과정도 간단해요.
---
# 페이스페이 소개
URL: /offline/introduce/facepay
페이스페이를 사용하면 지갑에서 카드나 꺼내거나 휴대폰이 없어도 1초 만에 얼굴 인증으로 토스페이 결제가 이루어져요
- 페이스페이 홈페이지
사용은 간편하게, 보안은 강력하게. 토스 보안 철학은 페이스페이에도 계속돼요. 간편한 사용과 철저한 보안을 위해 적용된 기술과 정책을 확인해보세요.
### 보안 정책
1. 99.99%의 정확도로 1초만에 얼굴 인증
토스가 자체 개발한 얼굴인식 기술로 높은 정확도와 빠른 인식 속도를 자랑해요.
2. 데이터 활용부터 관리까지 빈틈없는 보안 기술
토스에서는 사용자의 데이터를 모두 암호화하여 관리하고, 이런 암호화된 데이터는 사용자가 동의한 꼭 필요한 순간에만 활용하고 있어요. 개인정보보호위원회와 해당 서비스에 적합한 개인정보보호법 적용방안을 함께 마련하는 사전적정성 검토 또한 받았어요.
3. 개인정보의 주권은 개인에게
토스 페이스페이를 사용하고 싶지 않을 때 언제든지 이용 동의를 철회할 수 있고, 등록된 얼굴정보를 변경하고 싶을 때 손쉽게 다시 등록할 수 있어요.
4. 24시간 가동 중인 이상거래탐지시스템과 안심보장제
혹시 나도 모를 생길 수 있는 이상거래가 걱정되시나요? 이상거래탐지시스템(FDS)이 수상한 결제가 발견되면 바로 조치를 취하고 당신에게 알려드릴게요. 만약 부정 거래가 발생하면 안심보장제로 보상해드려요.
토스 안심보상제는 토스 페이스페이를 통한 부정 거래 발생 시에 토스가 피해금액 전체를 보상해드리는 제도예요.
### 우리 매장은 페이스페이를 사용할 수 있나요?
- 페이스페이는 토스페이의 결제수단이에요. 관리 대리점 또는 토스페이 고객센터(1644-4900)를 통해 우리 매장의 토스페이 입점 여부를 확인해 주세요.
- 별도의 가입 없이, 토스 프론트를 사용하고 있는 매장이라면 페이스페이를 사용하실 수 있어요. (토스 포스, 토스 터미널이 아니어도 가능해요!)
- 페이스페이 사용 가능한 매장은 매달 2,480만명이 방문하는 토스 앱 지도에서 '페이스페이 가능 매장'으로 보여요. 편리한 페이스페이를 이용하고자 하는 손님들께 0원으로 매장을 홍보해보세요.
### 사장님 한마디
손님들이 '와 여기서 얼굴로 결제돼요?' 하면서 되게 신기해 하시더라고요. 젊은 손님들도 좋아하고, 매장 이미지도 확 좋아졌어요.
---
# 대리점 계약
URL: /offline/prepare/subscription/agency
## 사전 확인 사항
### 1. VAN사 및 신청 플랫폼 확인
사용하는 VAN사, 밴대리점 여부에 따라 계약을 접수하는 플랫폼이 달라져요.
가맹점에서 사용하는 VAN사와 밴대리점 여부를 확인한 뒤 알맞는 플랫폼으로 접수해 주세요.
| 계약 플랫폼 | 밴대리점 여부 | 지원 VAN사 |
| QVAN | 필수 | KIS, SMARTRO, KFTC, KSNET, KOCES, KOVAN, KPN, KICC, NICEPAYMENTS, DAOU, 이외 밴사는 문의 필요 |
| NVAN | 필수 | NICE 밴 사용 가맹점 |
| SVAN | 필수 | SECTA9 밴 사용 가맹점 |
| 토스 전자계약 | 무관 | 위 연동 밴사 전체 이용 가능 |
### 2. 필수 서류
신청 플랫폼별 필수서류가 상이해요. 모든 서류는 원본 서류를 제출해야 해요. 단 법인 서류인 등기부등본, 주주명부, 인감증명서는 3개월 내 발급본을 제출해주세요.
#### 개인
| 플랫폼 | 제출 서류 목록 |
| QVAN, NVAN, SVAN | 사업자등록증, 대표자 신분증 사본, 점신계좌표 |
| 전자계약 | 사업자등록증 |
#### 법인
| 플랫폼 | 제출 서류 목록 |
| QVAN, NVAN, SVAN | 사업자등록증, 법인 등기부등본, 주주명부, 점신계좌 사본, 법인 등기부등본 |
| 전자계약 | 사업자등록증, 법인 등기부등본, 주주명부 |
법인 유형에 따라 정관 등 추가 서류를 요청할 수 있어요.
### 3. 사업자 유형
사업자 유형을 미리 전달해 주시면, 가맹점 생성이나 특이 케이스에 대해 더 정확하게 안내드릴 수 있어요.
| 항목 | 설명 |
| 외국인 대표자 여부 | 전자 계약이 불가해요. 지류 계약으로 안내해 주세요. |
| 미성년자 대표자 여부 | 전자 계약이 불가해요. 지류 계약으로 안내해 주세요. |
| 비영리 법인 여부 | 전자 계약이 불가해요. 지류 계약으로 안내해 주세요. |
## 계약 진행 타임라인
- 각 플랫폼에서 계약 접수를 진행해요.
- 심사 소요 시간은 다음과 같아요.
- 개인 사업자: 0~3 영업일
- 법인 사업자: 0~5 영업일
- 계약이 완료되면, 계약 담당자의 이메일로 아래 정보가 발송돼요.
- 가맹점 번호: MID(*전자계약의 경우 알림톡으로 발송)
- 토스페이 파트너스 계정 안내 메일
- 가맹점 번호는 VAN 전산에 자동 또는 수동으로 등록돼요. 등록이 완료되면 결제를 받을 수 있어요.
## 참고 자료
보다 자세한 계약 절차나 요건이 궁금하다면, 아래 가이드를 참고해 주세요.
- 오프라인 토스페이 청약 가이드
---
# 프랜차이즈 계약
URL: /offline/prepare/subscription/franchise
## 계약 진행 타임라인
- 사전 확인 사항을 보고 필요한 준비를 완료해요.
- 양측 협의를 통해 계약 세부 내용을 확정해요.
- 계약서를 발급하고, 필요한 경우 지류 계약을 진행해요.
- 가맹점용 전자계약 링크와 신청 가이드를 제작해 안내해요.
- 브랜드 전용 전자계약 링크를 오픈해요.
- 전체 계약이 완료되면, 대고객 서비스를 오픈할 수 있어요.
## 사전 확인 사항
### 1. 가맹점 구성
가맹점의 구성 방식에 따라 지류 계약서 제출 여부와 전자계약 진행 방식이 달라져요.
브랜드의 가맹점 구성을 미리 전달해 주시면, 상황에 맞는 가입 절차를 안내해 드릴 수 있어요.
계약서 항목을 별도로 검토하거나 수정해야 하는 경우에는 지류 계약이 필요해요.
| 구분 | 지류 계약 | 전자 계약 |
| 직영점 | 본사 기준 표준계약서 작성 및 원본 서류 제출 필요 (증빙서류 포함) | 본사 동일 사업자번호가 아닌 경우, 개별 전자계약 필요 |
| 가맹점 (자영점) | 제출 불필요 | 프랜차이즈용 전자계약 필요 |
### 2. 정산 구조
정산 방식에 따라 계약 내용이 달라지기 때문에, 계약 전 반드시 정산 구조를 먼저 협의해야 해요.
| 정산 구조 | 설명 | 예시 |
| 본사 일괄 정산 | 본사가 모든 가맹점의 매출을 모아서 한 번에 정산받는 구조예요. | 편의점, 패스트푸드 등 |
| 가맹점 개별 정산 | 각 가맹점이 개별적으로 정산을 받는 구조예요. | 대부분 프랜차이즈 매장 |
| 특이 정산 구조 | - 위 두 방식과 다른 정산 구조가 있다면, '토스페이 온보딩 팀'과 별도 논의가 필요해요.- 이 경우, 계약 절차와 타임라인에 영향이 있을 수 있으니 사전에 일정을 꼭 확인해 주세요. | 특별 계약 형태 등 |
### 3. 사용하는 VAN사 확인
프랜차이즈는 현재 이용 중인 VAN사로만 계약이 전송돼요.
따라서, 정확한 VAN사 정보를 미리 전달해 주세요.
현재 토스페이와 연동된 지원 VAN을 참고해 주세요. 지원 중인 VAN사 외에는 별도 문의가 필요해요.
### 4. 사업자 유형
사업자 유형을 미리 전달해 주시면, 가맹점 생성이나 특이 케이스에 대해 더 정확하게 안내드릴 수 있어요.
| 항목 | 설명 |
| 직영점/가맹점(자영점) 개수 | 현재 운영 중인 직영점과 가맹점(자영점) 각각의 개수를 전달해 주세요. |
| 개인/법인 사업자 비율 | 전체 가맹점 중 개인 사업자와 법인 사업자의 비율 또는 수량을 전달해 주세요. |
| 외국인 대표자 여부 | 전자 계약이 불가해요. 지류 계약으로 안내해 주세요. |
| 미성년자 대표자 여부 | 전자 계약이 불가해요. 지류 계약으로 안내해 주세요. |
| 비영리 법인 여부 | 전자 계약이 불가해요. 지류 계약으로 안내해 주세요. |
### 5. 추가로 확인이 필요한 사항
#### 특이사항
아래와 같은 특이사항이 있는 경우 반드시 계약 담당자에게 사전에 공유해 주세요.
- 매장별 점포코드 사용 여부
- 토스플레이스 가맹 여부
- 대리점 코드 삽입이 필요한 경우에 적용돼요.
- 멤버십 또는 인증서 사용 여부
- 토스페이 프로모션 일정 또는 대고객 오픈 일정
#### 토스페이 지도 노출
토스페이를 사용하는 매장은 지도에 노출돼요. 브랜드 로고를 별도로 사용하고 있다면 공식 로고(CI) 파일을 함께 전달해 주세요.
- PNG 또는 JPEG 형식
- 흰색 배경이 아닌 유색 배경 아이콘
## 전자계약에서 커스텀 가능 항목
### 1. 링크 첫 화면
전자계약 링크의 첫 화면에 회사명 또는 브랜드명을 노출할 수 있어요. 예를 들면 주식회사 OOO 전용 토스페이 가맹점 신청하기 같은 형식이에요.
### 2. 사업자 번호 사전 등록 여부
사업자 번호 사전 등록 여부를 어떻게 설정하느냐에 따라 전자계약에 진입할 수 있는 대상이 달라져요.
#### 사전 등록 방식
- 미리 전달받은 사업자 번호 리스트에 한해 전자계약 진입이 가능해요.
#### 오픈 방식
- 누구나 사업자번호만 입력하면 전자계약에 진입할 수 있어요.
두 방식 중에서 '사업자 사전 등록' 방식을 권장해요. 가맹점 이름 자동 입력(프리필), 오입력 방지, 수수료 노출 제한 등을 위해 사전 등록 방식을 사용하는 것이 더 안전해요.
### 3. 계약 조건 설정
전자계약에 아래 항목을 반영할 수 있어요.
#### 정산일 (일 정산 / 월 정산 중 택1)
- 일 정산: D+3 영업일
- 월 정산: 매월 8영업일
#### 수수료율 설정
- 기본 수수료율: 일반 1.8%, 중소 1.2%, 영세 0.8% (부가세 별도)
- 별도 협의 수수료율이 있는 경우, 해당 수수료가 계약서에 표시돼요.
### 4. 가맹점 정보 설정
#### 업종
- 사업자등록증에 기재된 업종 기준으로, 표준산업 분류코드를 기반으로 등록할 수 있어요.
#### 판매 품목
- 원하시는 단어로 품목명을 추가할 수 있어요.
- 단, 지나치게 포괄적인 표현은 피해주세요.
- 사용 가능 표현 예시: 충전소, 주유소, 제과점, 아이스크림
- 지양 표현 예시: 음식점업, 미용업 등
#### 홈페이지 주소 (선택 항목)
#### 가맹점 이름
관리에 편의를 위해 가맹점 이름이 실제 매장명과 일치하는 것이 좋아요. 예를 들어 토스제과 역삼점 같은 형식이에요.
---
# 단말기 설치
URL: /offline/prepare/device-onboarding
## 단말기 설치 절차
- 단말기 수령 후 박스를 개봉해요.
- 네트워크를 연결해요. (Wi-Fi 또는 유선 LAN 중 선택)
- 단말기에 다음 정보를 입력해서 온보딩을 진행해요.
- 사업자등록번호
- 매장 고유번호
- 매장 전화번호
- 사용 환경에 맞춰 연결하고, 테스트 결제를 진행해요.
- 토스포스
- 타사 포스
- 타사 단말기 조합
- 문제가 발생하면 고객센터나 대리점으로 문의해 주세요.
### 참고 자료
- 단말기 설치 메뉴얼 바로가기
## 대리점
단말기 유통 대리점이나 설치 대행자를 위한 설치 가이드예요.
가맹점에 단말기를 설치하고 설정을 마치는 데 필요한 절차를 정리했어요.
- 대상: 일반 유통 대리점, 단말기 설치를 대행하는 파트너
- 목표: 가맹점에 단말기를 설치하고, 설정까지 완료하는 것
### 단말기 설치 절차
- 배정된 단말기를 확인하고 포장을 개봉해요.
- 토스플레이스 파트너스에 가맹점 정보를 등록해요.
- 사업자등록번호
- 가맹점 고유번호
- 매장 전화번호
- 현장에서 단말기를 설치하고, 결제가 정상적으로 되는지 테스트해요.
### 참고 자료
- 토스플레이스 가이드 (대리점)
- 토스플레이스 서비스 이용 가이드 - 처음 설치해요
## 브랜드 본사
프랜차이즈 본사의 운영팀 또는 IT팀을 위한 온보딩 가이드예요.
가맹점에 단말기를 공급하기 전에 필요한 설정과 준비 절차를 정리했어요.
- 대상: 프랜차이즈 본사의 운영팀 또는 IT팀
- 목표: 가맹점에 단말기를 공급하기 전, 설정과 테스트를 완료하는 것
### 단말기 설치 절차
- 브랜드 계정으로 토스플레이스 파트너스에 로그인해요.
- 장비 공급 일정과 계획을 사전에 협의해요.
- 본사 차원에서 내부 테스트를 진행한 뒤, 필드 테스트까지 완료해요.
- 가맹점에 전달할 교육자료를 제작해서 배포해요.
### 참고 자료
- 토스플레이스 브랜드 파트너스 사용 가이드
## 고객센터
### 토스플레이스 대리점 전용 고객센터
- 전화 문의: 1644-2888
- 채팅 문의: http://pf.kakao.com/_Yxlgpb
- 운영 시간: 평일 오전 9시 ~ 오후 6시 (점심시간 12:00~13:00)
### 토스플레이스 가맹점 고객센터
- 전화 문의: 1644-2955
- 채팅 문의: http://pf.kakao.com/_Yxlgpb
- 운영 시간: 매일 오전 9시 ~ 오후 6시 (연중무휴 / 주말 및 공휴일은 12:00~13:20 점심 시간)
---
# 결제
URL: /offline/prepare/payment
## 업종별로 고려해야 할 특수한 결제 형태
가맹점 업종에 따라 특수한 결제 형태가 필요한 경우가 있어요. 예를 들면 다음과 같아요.
- 주유소에서는 먼저 일정 금액에 대해 가승인을 받고, 실제 발생한 금액에 대해 실제 승인 후 가승인한 금액을 취소하는 거래가 필요할 수 있어요.
- 교통, 여행 상품의 경우, 이용하지 않은 구간에 대해서 부분 취소하는 거래가 필요할 수 있어요.
- 지하철 같은 교통업종은 한 번의 탑승에 대해 여러 건의 승인이 발생하는 다중 승인 거래가 필요할 수 있어요.
- 제휴사 할인 카드로 결제 시 자동 할인이 적용되는 거래가 필요할 수 있어요.
이런 사례들은 업종별로 결제 흐름이 다를 수 있으니, 일반적인 결제 흐름을 벗어나는 구조가 필요하다면 사전 협의가 필요해요.
## 결제 수단과 정산 가능 여부
현재 사용할 수 있는 결제 수단은 아래와 같아요.
- 머니/토스페이머니
- 계좌
- 카드
BNPL은 지원하지 않아요.
지원하는 결제 방식은 아래와 같아요
- 페이스페이
- QR/바코드
- 테이블오더
단, 주의할 점이 있어요.
- 머니/계좌에 대해서만 토스페이에서 정산해요.
- 다중 승인이나 부분 취소는 현재 (25.12) 지원하지 않아요.
- 카드 결제는 인증만 진행하고 실제 승인은 VAN을 통해 카드사에서 처리해요.
- 토스는 카드 결제와 관련된 이슈를 해결할 수 없어요.
- 가맹점에서 관련 문의가 오면 VAN사를 통해 카드사로 문의하도록 안내해야 해요.
## 복합 결제
복합 결제는 여러 결제 수단을 함께 사용하는 방식이에요. 아래 내용을 참고해 주세요.
- 포인트는 전액 사용만 가능하고, 머니/계좌로 결제할 때만 이용할 수 있어요.
- 즉시 할인 역시 머니/계좌로 결제해야 적용돼요.
- 포인트 적립 프로모션은 카드 결제여도 가능해요.
## 멤버십 서비스 연동
제휴사나 가맹점에서 자체적인 멤버십 서비스를 운영 중이라면, 아래 사항을 고려해야 해요.
- 해당 멤버십이 존재하는지
- 존재한다면 자동 적립 기능이 필요한지
- 나중에라도 사후 적립 기능을 도입할 계획이 있는지
멤버십 연동은 사용자 경험에 영향을 주는 요소이기 때문에, 도입 여부와 방식에 대해 미리 정리해 두는 게 좋아요.
---
# 페이스페이
URL: /offline/prepare/facepay
## 1. 토스페이 연동 여부
토스페이를 연동한 뒤에 페이스페이를 사용할 수 있어요.
## 2. 페이스페이 연동 Agent(POS/KIOSK) 확인
POS
- 프론트뷰와 연동해요. 페이스페이용 추가 개발이 가능한지 확인해야 해요.
- Windows, 안드로이드 환경 모두 가능해요.
키오스크
- 프론트캠(전면 카메라)과 연동해요.
- Windows 환경 여부와 DLL 연동 개발 가능 여부를 확인해야 해요.
- 안드로이드 기반 키오스크의 경우, 별도의 AAR 파일을 통해 미러링이 지원돼요.
- 프론트캠 호출은 소켓 전문을 통한 연동이 필요해요.
결제 전용 단말기가 없다면, 토스플레이스의 프론트 디바이스를 통해 모든 결제를 처리할 수 있어요.
## 3. 네트워크 환경 확인
인터넷망, 전용선, VPN, 폐쇄망 등
- 사업장 내부 Agent가 폐쇄망 환경이라면, 토스 단말기에서 토스 서버로의 외부 통신이 가능하도록 네트워크 whitelist 설정이 필요해요.
- 키 다운로드, 단말기 App/OS 업데이트, 로그 전송 등 모두 인터넷 연결이 필요해요.
- 외부망 통신이 불가능한 경우에는 토스에서 제공하는 LTE 모듈을 사용해 외부와 통신할 수 있어요.
- 단, LTE 통신에는 별도의 요금이 발생할 수 있어요.
## 4. 개발환경(dev) 테스트
얼굴 인증만으로는 결제가 이뤄지지 않아요.
개발 환경에서는 실제 결제 흐름과 다르게 동작할 수 있기 때문에, 실제 운영 환경에서 테스트하는 것을 권장해요.
---
# 토스페이 연동
URL: /offline/develop/tosspay
## 연동 개요
- 토스페이 오프라인 결제서버와 VAN 서버간의 연동 구성이에요.
- 결제를 위한 실시간 전문 통신(TCP/IP) 방식과 정산을 위한 파일송수신(SFTP) 방식으로 구성돼있어요.
- 오프라인 토스페이 연동은 VAN 서버와 토스페이 서버간 전용선통신으로 이루어져요.
- 사용자 ↔ POS ↔ VAN 구간은 토스페이와 무관한 별도의 연동절차가 필요해요.
## 머니/계좌 거래
- 토스페이 결제수단 중, 머니/계좌 거래는 위와 같은 프로세스로 결제가 처리돼요.
- POS/단말기는 VAN으로 일반 거래처럼 승인요청을 전송하지만, 실제 머니/계좌수단의 승인을 내는 주체는 토스페이예요.
## 카드 거래
- 토스페이 결제수단 중, 카드 거래는 위와 같은 프로세스로 결제가 처리돼요.
- 페이스페이/QR/바코드 모두 "② 조회 요청" 단계 전까지는 토스페이 토큰만 가지고 있다가, 토스페이 내부 처리를 통해서 OTC(One Time Cardnumber)를 받아요.
- 이 OTC가 실물 IC카드번호를 대신할 일회성 카드번호예요.
- VAN사는 이제 OTC를 가지고 일반 IC거래처럼 카드사에 승인요청을 보내고 응답을 받아요.
- 카드사로부터 정상 응답을 받으면 그대로 POS/단말기까지 결과를 전송해주고 결제가 완료돼요.
## 실시간 전문 통신 방식
- 실시간 전문 통신 방식은 토스페이와 VAN사간 TCP/IP 프로토콜을 사용하여 실시간으로 메세지를 주고 받는 방식이에요.
- 전용선만 사용 가능하지만, VPN 구성이 필요하신 경우 상호 협의 하에 변경이 가능해요.
- '조회', '승인', '통지' 전문으로 이루어져 있어요.
## 인프라 정보
- 오프라인 결제 연동의 경우 전용회선으로 구성하고 있어요.
- VPN 환경도 제공해드릴 수 있지만, 가급적 지양하고 있어요.
- 회선은 총 3개로 구성되고, 결제 트래픽 정도에 따라 대역폭 협의 후 구성하고 있어요.
- IP 정보의 경우 다음과 같고, PORT 정보의 경우 연동 별 신규로 할당 및 안내해 드려요.
- 개발환경: 211.233.9.160
- 운영환경: 211.233.6.161
- VAN사 Inbound
- SFTP 통신방식의 경우 토스가 VAN사로 접속하여 파일을 전달드리는 형식이에요.
- VAN사 Inbound 방화벽 설정이 필요해요.
- 개발: 15.165.30.215 (포트는 VAN사별 상이)
- 운영 DC1: 117.52.3.80 ~ 87
- 운영 DC2: 211.115.96.80 ~ 87
## SFTP 통신 방식
- SFTP 통신 방식은 정산 등 배치성 대용량 파일을 주고 받는 용도로 사용돼요.
- 일정 시간 단위로 협의된 디렉토리 경로에 생성되는 파일을 SFTP 서버에 접속해서 가져가는 방식이에요.
- '정산내역', '가맹점 등록내역'으로 구성되어있어요.
## 데이터 포맷
- 송수신데이터는 ASCII 코드를 사용하며, 한글은 KSC-5601 2Bytes 완성형 코드를 사용해요.
- KSC-5601 코드 범위: 0xA1A1 ~ 0xFEFE
- 전문 및 일괄 전송 파일의 각 항목 별 표현(MODE)에 한글 수록 가능으로 표시된 경우('H'가 포함된 경우) 한글 이외에 문자도 모두 전각 처리(2Bytes Encoding)해요.
- 상호 협의 하에 UTF-8 등의 다른 Charset도 사용 가능해요.
---
# 토스페이 토큰
URL: /offline/develop/tosspay/token
## 토스페이 토큰
이 값은 각 거래를 고유하게 식별하는 값으로 중복 사용이 불가능해요.
총 24자리로 규칙은 다음과 같아요
| 구성 요소 | 설명 |
| BIN(8자리) | 결제수단 코드 (70550001~70550003) |
| 발행시점(2자리) | 반기 기준으로 증가 |
| 난수(14자리) | 고유 ID 역할 |
### 토스페이 BIN (결제수단 구분 값)
- 카드결제: 70550001
- 토스머니결제: 70550002
- 계좌결제: 70550003
### 유효기간
결제용 토스페이 토큰 유효기간은 2분, 취소용 토스페이 토큰 유효기간은 1년이에요.
## 테스트 정보
- 간단한 결제 테스트를 위한 고정형 토스페이 토큰도 제공해드리고 있어요.
- 토스머니: 705500020000000000000000
- 토스계좌: 705500030000000000000000
---
# 페이스페이
URL: /offline/develop/facepay
페이스페이는 토스페이를 사용할 때 얼굴 인증으로 토스페이 토큰 값을 발급받는 절차를 거쳐요. 페이스페이 기능을 사용하려면 먼저 토스페이 연동을 마쳐야 해요. 자세한 연동 프로세스는 facepay@toss.im으로 문의해 주세요.
페이스페이에 대한 상세한 소개는 페이스페이 소개 페이지를 방문해도 좋아요.
## 페이스페이용 단말기 소개
### POS와 연동이 용이한 ‘프론트’ 및 ‘프론트뷰’
#### 프론트(Front 2)
- 이 단말기는 신용카드와 간편결제를 포함해 모든 결제를 처리할 수 있어요. 도입하려면 별도로 협의해야 해요.
| | |
#### 프론트뷰(FrontView)
- 이 단말기는 토스 페이스페이만 지원해요. 기존에 사용하던 신용카드 단말기나 멀티패드와 함께 연동해서 사용할 수 있어요.
### KIOSK와 연동이 용이한 프론트캠
#### 프론트캠(FrontCam)
- 이 단말기는 키오스크와 연동하려고 출시한 제품이라, 자체 화면이 없어요. 그래서 키오스크(Agent)에서 단말기 화면을 미러링해야 해요.
---
# 가맹점 운영 가이드
URL: /offline/operation/store
바쁘신 사장님들, 페이스페이로 편리함을 더해보세요!
통합결제로 페이스페이뿐 아니라 카드결제, 간편결제도 모두 가능해요. 점주님은 버튼 하나만 누르세요! 손님분들이 원하시는 결제 방법을 선택해 결제해요. "카드로 결제하세요? 페이로 결제하세요?"라는 질문도 이젠 안녕이에요!
토스 앱에서 페이스페이를 등록한 고객이 이용할 수 있어요.
## 통합결제란?
복잡한 결제는 이제 끝! 점주님은 버튼 하나만 눌러주세요. 카드/간편결제/삼성(애플)페이 등 모두 가능해요. 고객이 직접 원하는 결제수단을 선택해요.
통합결제 화면은 기기에 따라 조금씩 다르게 보일 수 있어요. 다양한 결제 수단(카드/QR/삼성페이 등)이 한번에 보인다면 통합결제 화면이에요.
## 1. 결제 버튼 누르기
### 포스기를 사용하시나요?
#### 토스 포스(Toss POS)
아래 화면에서 기다리면, 고객들이 선택해요.
페이스페이 버튼을 눌러도 가능해요!
#### 오케이 포스(OK POS)
'신용카드' 버튼을 눌러주세요.
통합결제 화면이 안나온다면, 대리점에 연락해주세요.
#### 유니온 포스, 한울포스 (Union POS, Hanwool Pos)
'카드' 버튼을 눌러주세요.
결제가 안된다면 포스를 업데이트 해주세요. 메인 화면에서 '업데이트' 버튼을 눌러주세요.
#### 업포스(IMU POS, UPPOS)
'통합결제' 버튼을 눌러주세요.
통합결제가 아닌 (신용)카드 버튼이라면, 대리점에 연락해 포스를 업데이트 해주세요.
사용 중이신 포스기가 언급되지 않았나요? 그래도 페이스페이가 가능할 수 있어요!
- Air POS, POS MASTER: 페이스페이가 가능해요.
- 기타 포스: 관리 대리점을 통해 페이스페이가 가능한지 확인해주세요.
- 포스 무관: '(신용)카드' 결제로 먼저 페이스페이를 시도해주세요. (통합 결제 화면이 뜨는지 확인해주세요.)
- 포스 무관: '(신용)카드' 결제가 불가능하다면, '간편(QR, 모바일, 00페이…)결제' 버튼으로 시도해주세요.
### 단말기를 사용하시나요?
- 신용카드 결제와 똑같이 결제해 주세요.
- 신용카드 결제가 불가능할 경우, 간편결제 진입 경로로 결제를 시도해주세요.
#### KIS 밴사의 단말기를 사용하고 계신가요?
대리점에 "원터치 설정"을 요청해주세요. 원터치가 설정돼야 통합결제로 페이스페이가 가능해요.
## 2. 결제하기
프론트에 통합 결제 화면이 뜨면, 손님들이 '페이스페이' 버튼을 클릭해 얼굴을 인식해요.
통합결제 화면이 뜨지 않나요? 포스 업데이트가 필요할 수 있어요. 관리 대리점에 연락해주세요.
## 3. 결제완료
포스에서 결제가 완료되었는지 확인해주세요.
결제에 실패하나요? 결제 실패 시 확인 사항 부분을 확인해주세요.
---
# VAN 대리점 운영 가이드
URL: /offline/operation/agency
## 1. 내가 관리하는 가맹점에 페이스페이 활성화하기
### 1-1. 토스페이 청약
페이스페이를 사용하기 위해선 토스페이(간편결제) 청약이 완료되어야 해요.
### 1-2. VAN 전산에 토스페이 가맹점 번호 등록하기
청약이 완료된 이후, 카드사 가맹 등록과 동일하게 토스페이 가맹점 번호(MID)또한 꼭 VAN ASP에 등록해 주세요.
밴사 시스템에 토스페이 가맹점 번호 등록하기 가이드
### 1-3. 가맹점 활성화하기
토스플레이스 파트너스 홈페이지에서 '새 매장 만들기' 기능을 통해 매장을 생성하고 프론트 TID 번호까지 입력한 뒤 프론트를 온보딩해요.
- 새 매장 만들기 가이드
### 1-4. 매장에 토스 단말기 (프론트) 설치 및 세팅하기
매장에 연동된 포스(POS)/단말기(CAT) 별 필수 세팅값을 확인 후 프론트를 설치해 주세요.
- 포스 업데이트 가이드
- 단말기 업데이트 가이드
## 2. 점주님들은 페이스페이를 어떻게 사용하나요?
### 2-1. 결제 버튼 누르기
매장에서 손님이 ‘얼굴로 결제할게요’ 라고 점주님에게 요청하면 점주님은 ‘카드’ 또는 ‘통합결제’를 통해 결제해요.
#### 토스 포스(Toss POS)
결제 버튼만 눌러주세요.
결제 버튼만 눌러주시면 손님이 직접 프론트에서 결제방식을 선택할 수 있어요.
#### 오케이 포스(OK POS)
'신용카드' 버튼을 눌러주세요.
#### 유니온 포스, 한울포스 (Union POS, Hanwool Pos)
'카드' 버튼을 눌러주세요.
'통합결제' 버튼으로도 가능해요.
#### 업포스(IMU POS, UPPOS)
'통합결제' 버튼을 눌러주세요.
### 2-2. 결제하기
프론트에 통합 결제 화면이 뜨면, 손님들이 ‘페이스페이’ 버튼을 클릭해 얼굴을 인식해요.
### 2-3. 결제완료
그럼 점주분은 포스에서 결제가 완료되었는지 확인해 주시면 돼요.
## 3. 점주분이 결제에 실패했다는 알림을 받으셨나요?
매장에서 사용하는 POS나 CAT을 최신 버전으로 업데이트 해주세요.
매장에서 사용하는 POS, 혹은 CAT 단말기가 최신 버전이 아니거나, 혹은 다중결제지원이 ‘미사용’ 되어 있다면 아래와 같은 문구가 노출되며 점주분께 알림톡이 발송돼요.
- '간편결제'(모바일/QR결제) 버튼이나 결제 방식으로는 페이스페이 결제가 가능할 수 있어요. '간편결제' 방식으로 페이스페이를 시도할 수 있도록 점주님에게 알려주세요.
- POS사별 업데이트 방법을 확인 후, 최신버전으로 업데이트 해주세요.
- CAT 펌웨어 업데이트 방법을 확인 후, 최신버전으로 업데이트 해주세요.
## 문의처
- 결제 오류 관련 문의: 담당 밴대리점에 연락해 주세요.
- 토스페이 관련 문의(결제, 정산, 지도 정보): 토스페이 고객센터 1644-4900
- 토스프론트 (단말기) 관련 문의: 토스플레이스 고객센터 1644-2955
---
# 프로모션 가이드
URL: /offline/operation/promotion
## 토스페이 오프라인 프로모션 안내
토스페이 결제가 가능한 프랜차이즈 브랜드라면 오프라인 매장에서 사용할 수 있는 프로모션 운영이 가능해요.
프로모션은 세팅 주체에 따라 토스 세팅과 제휴사 세팅으로 나뉘며, 각 방식에 따라 적용 가능한 혜택과 지원되는 결제 수단이 달라져요.
카드 할인 프로모션은 추후 지원 예정이에요
## 프로모션이 시작되면 토스 앱 어디에서 확인할 수 있나요?
오프라인 혜택 프로모션이 승인되면 토스 앱 안의 여러 화면에 보여져요.
고객은 다음과 같은 위치에서 프로모션을 확인할 수 있어요.
### 기본 노출 위치
#### 모든 할인/적립 쿠폰 모아보기
- 확인 방법: 토스 홈 > 결제 홈 > 모든 할인 · 적립 쿠폰 > (하단) 오프라인
- 고객이 쿠폰을 한눈에 모아볼 수 있는 화면이에요. 오프라인 전용 쿠폰은 하단에서 확인할 수 있어요.
### 추가 노출 옵션 (사전 협의 필요)
#### 결제 가능한 매장 (지도보기)
- 확인 방법: 토스 홈 > 결제 > QR결제 > 결제가능 매장 지도보기
- 고객이 현재 위치 주변에서 사용할 수 있는 오프라인 매장을 지도로 확인할 수 있어요.
#### 토스 홈 상단 배너 (토스홈 인텔리전스)
- 특정 고객 그룹을 타겟으로, 토스 홈 최상단에 배너로 보여져요.
- 확인 방법: 토스 홈 > 상단에 나타나는 배너 클릭
- 필요한 정보: 언제 노출할지, 어떤 고객에게 보여줄지 (타겟팅)
#### 오프라인 결제 홈 배너
- QR결제 화면 상단에 배너로 보여져요.
- 확인 방법: 토스 홈 > 결제 > QR 결제 > 상단에 나타나는 배너 클릭
- 필요 정보: 언제 노출할지
#### 앱 푸시 알림 (App Push)
- 특정 고객 그룹에게 앱 푸시 알림으로 프로모션 소식을 전할 수 있어요.
- 협의를 통해 아래와 같은 형태로 맞춤 운영이 가능해요. (필요한 정보: 발송 날짜, 발송 횟수)
- 특정 제휴사의 푸시 템플릿을 N회 이상 발송
- 특정 제휴사의 푸시 템플릿을 부스팅하여 집중 노출
## 프로모션 스킴은 어떻게 전달하나요?
### 공통 사항
프로모션은 토스페이 청약을 완료한 가맹점만 적용돼요.
법적 효력을 보장하기 위해 프로모션 진행에 필요한 서류를 반드시 작성해 주셔야 해요. 서류에는 프로모션 스킴과 정산 방식(비용 분담율, 정산 일정 등)이 포함돼야 해요.
- 토스 세팅 프로모션: 프로모션 계약서 또는 신청서
- 제휴사 세팅 프로모션: 공문
원활한 운영을 위해 프로모션의 세부 운영 방식 (스킴) 정보를 꼭 전달해 주세요. 세팅 방식에 따라 운영 절차가 달라질 수 있으니, 아래 내용을 참고해 주세요.
### 토스 세팅 프로모션
- 전달받은 내용을 기준으로 토스 내부 어드민에서 운영팀이 직접 세팅해요.
- 오프라인 매장에서 토스페이 결제가 이뤄지면 자동으로 혜택이 적용돼요. (예: 즉시할인, 즉시적립)
### 제휴사 세팅 프로모션
- 제휴사에서 직접 POS에서 혜택을 세팅하고 운영해요.
- 토스는 혜택 정보를 노출하는 상세 페이지를 구성해드려요.
- 제휴사 세팅 프로모션의 경우 토스에서는 소진 금액을 확인할 수 없어요. 따라서, 프로모션 종료 후 정산을 위해 결제 데이터를 지정된 양식에 맞춰 전달해 주셔야 해요.
프로모션 운영을 위해 전달해야 하는 항목들은 다음과 같아요.
필요한 정보가 모두 준비되면 운영팀과 협의해서 빠르게 적용할 수 있어요.
| 항목 | 예시 |
| 결제 수단 | 페이스페이/QR |
| 혜택 유형 (할인 또는 적립) | 할인 |
| 진행 기간 | 2025.11.01 ~ 2025.11.30 |
| 정액/정률 여부 | 정액 |
| 최소 결제 금액 | 10,000원 |
| 최대 할인 금액 또는 할인율 | 3,000원 |
| 기간 내 N회 | 기간 내 1회 |
| 총 예산 | 500만원 |
| 유의사항 | 타 혜택과 중복 불가 |
## 정산 프로세스
정산 프로세스는 (1) 정산서 조회 => (2) 인보이스 발행 순으로 진행돼요.
### 1. 정산서 조회
- 매월 1일부터 말일까지 집행된 프로모션 내역에 대해, 익월 1일에 정산서를 발송해드려요. (아래 예시 참고)
- (예시) 2025년 6월 계약 완료 및 프로모션 진행 시
- 2025년 7월 1일: 정산서 메일 발송
- 2025년 7월 31일까지: 6월 프로모션 비용 입금 필요
- [정산서 승인하기] 버튼 클릭 시, 익일 이내 인보이스가 발행돼요.
- 정산서는 support-pay@business.toss.im 메일로 보내드리고 있어요.
- 수신 이메일 주소 변경을 원하시면 토스 운영팀 메일(support-pay@toss.im)로 변경 요청해 주세요.
- [정산서 승인하기]를 누르면 익일 이내에 인보이스가 발행돼요.
### 2. 인보이스(전자명세서) 발행
사업자등록번호 기준으로 매월 1일부터 말일까지 집행된 프로모션 내역에 대해, 월 1회 인보이스를 발행해드려요.
### 발행 기준 및 상세
- 발행 금액: 최종 할인/적립 금액 기준으로 발생한 금액에서 분담율을 적용하여 산출 (원단위 절사)
- 발행 기준: 프로모션 그룹 단위로 1장 발행
- 발행 주기: 익월 초 영업일 기준 3일 이내
- 빠른 발행 필요: 정산서 승인하기 버튼 클릭 시 승인 후 익일 내 발행
- 보류 선택: 사유 요청 후 검토 진행
- 발행 대상: 해당 월 프로모션 분담비가 발생한 프로모션 그룹
- 발행 일자: 해당 월의 말일
- 수신 이메일주소: 프로모션 그룹 대표 이메일
인보이스 재발송 및 이메일 주소 변경이 필요하면 support-pay@toss.im 으로 문의해주세요!
## 정산금 입금
- 집행일 기준 익월 초 정산 금액 확정 후 인보이스 발행이 진행돼요.
- 입금 안내 메일을 확인한 뒤 지정된 가상계좌로 입금 부탁드려요.
- 가상계좌 입금 시, 실시간 정산 확인이 가능하니 가급적 가상계좌를 이용해주세요.
주의: 인보이스 금액과 입금 금액이 일치하지 않으면 입금 처리에 실패해요.
- 가상계좌 확인서 발급이 필요할 경우, support-pay@toss.im으로 문의해주세요.
정산서, 인보이스 수신처
- 계정 생성 시 사용하는 이메일 주소로는 메일이 수신되고, 담당자 이메일 주소는 참조로 설정돼요.
- 담당자 변경시 정산서 누락 방지를 위해 토스페이 운영팀으로 수신처 변경을 요청주세요.
- 신규 고객사의 경우 정산을 위해 ① 사업자등록증 ② 통장 사본을 이메일로 요청드리고 있어요
보다 자세한 프로세스는 다음의 정산 가이드를 참고해 주세요. 정산 프로세스
---
# 정산 가이드
URL: /offline/operation/settlement
## 정산 흐름
## 1. 수수료 적용 및 계산 방식
### 적용 시점
- 수수료는 결제 승인 시점 기준으로 적용돼요.
- 취소 발생 시에도 결제 승인 시의 수수료율을 따라가요. (단, 일부 계약에 따라 상이할 수 있음)
### 계산 방식 (프랜차이즈 한정)
- 수수료 계산 방식은 아래 2가지 방식 중 하나를 선택할 수 있어요.
| 계산 방식 | 설명 |
| 결제 건별 (기본) | 결제 건마다 수수료를 개별 계산해요. |
| 점포별 일별 합산 | 하루치 거래를 모두 더한 뒤 수수료를 한 번 계산해요. |
- 수수료는 정률(%) 방식으로 계산돼요.
- 계산 시 소수점은 다음과 같이 처리돼요.
| 항목 | 계산 방식 | 예시 |
| 수수료 | 거래금액 × 수수료율, 소수점 절사 | 1,100.7원 → 1,100원 |
| 부가세 | 수수료 × 10%, 소수점 반올림 | 110.7원 → 111원 |
- 수수료는 선취된 뒤, 가맹점 정산 주기에 따라 지급돼요.
## 2. 정산 및 지급
### 정산 집계 (일마감)
매일 지정된 시간에 전날 발생한 거래 내역을 기준으로 정산 금액을 계산해요.
- 집계 시간: 매일 새벽 00시 ~ 01시 사이
- 집계 대상: 전일 거래 건 전체 (승인 건 - 환불 건)
- 정산 방식: 가맹점별로 정산 금액을 따로 계산해요.
- 지급 금액 = 거래금액 - 수수료 - 부가세
### 채권관리
환불 등으로 인해 정산 금액이 마이너스(-)가 될 경우, 채권으로 처리돼요.
이 경우 아래 두 가지 방식 중 하나로 관리해요.
#### 채권발생대비 지급 보류
정산주기 내 발생한 채권(환불)로 인한 미수 발생에 대비하여 당일 정산금액에서 지급보류해요. 채권 확인이 되면 가까운 정산일에 미리 차감해요.
| 구분 | 4/1(월) | 4/2(화) | 4/3(수) | 4/4(목) | 4/5(금) |
| 거래 | 10,000원 | -5,000원 | 0원 | 0원 | 0원 |
| 정산예정 | | | | 10,000원 | -5,000원 |
| 지급보류 | | | | 5,000원 | |
| 지급보류해제 | | | | | 5,000원 |
| 정산지급 | | | | 5,000원 | 0원 |
위 표는 D(거래일)+3 정산주기의 채권발생대비 지급 보류 및 해제 사례를 예시로 보여줘요.
#### 지급보류
당일 정산예정금액이 음수(-)인 경우 지급이 불가하여 (-)금액 그대로 지급보류 후 (+)정산예정금액 발생 시 자동 상계해요.
| 구분 | 4/1(월) | 4/2(화) | 4/3(수) | 4/4(목) | 4/5(금) |
| 거래 | -5,000원 | 10,000원 | 0원 | 0원 | 0원 |
| 정산예정 | | | | -5,000원 | 10,000원 |
| 지급보류 | | | | -5,000원 | |
| 지급보류해제 | | | | | -5,000원 |
| 정산지급 | 0원 | | | | 5,000원 |
위 표는 D(거래일)+3 정산주기의 지급보류 및 해제 사례를 예시로 보여줘요.
#### 타점포 상계 (타잔액상계)
같은 회사 소속 가맹점 중 정산금이 남는 다른 점포에서 상계 처리할 수도 있어요.
- 자동 상계되며, 상계 대상 가맹점은 따로 지정할 수 없어요.
#### 채권 이력 조회 방법
아래 경로에서 지급보류 또는 상계 이력을 확인할 수 있어요.
- 토스페이 파트너스 > 정산 > 잔액 내역 및 별도 가감 내역
- 잔액 내역 탭: 지급보류 확인
- 별도 가감 내역 탭: 상계 내역 확인
- 토스페이 파트너스 > 정산 > 정산 내역
- 지급일 기준으로 조회 가능
### 금액 대사 및 보정/확정
매 영업일마다 비바리퍼블리카 정산 담당자가 가맹점별 지급 금액을 검토해요.
- 필요 시 보정 작업을 거쳐 최종 확정 처리해요.
- 확정 마감 시간: 영업일 기준 13시 전까지
### 정산 금액 지급
- 확정된 정산 금액은 가맹점 등록 계좌로 자동 입금돼요.
- 입금 시 적요는 Toss정산MMDD 형식으로 표시돼요. 예: Toss정산0410
- 예금주 불일치 시 지급 보류 : 입금 대상 계좌의 예금주 이름이 시스템에 등록된 정보와 다르면, 지급이 보류돼요. 이 경우 예금주 정보가 수정될 때까지 입금이 이뤄지지 않아요.
### 정산 주기
정산 주기는 아래 두 가지 중에서 선택할 수 있어요.
| 정산 방식 | 설명 |
| 일 지급 (D+3) | 결제일 기준 3 영업일 뒤에 정산돼요. |
| 월 지급 (M+1) | 매월 말일 기준, 다음 달 8일에 정산돼요. (비영업일인 경우 다음 영업일에 지급) |
정산 주기를 변경하려면 계약서 재작성이 필요해요. 변경을 원하시면 공식 메일로 문의해 주세요.
## 3. 세금계산서 발행
정산 시 선취된 수수료에 대한 증빙으로 '영수' 세금계산서가 발행돼요.
| 정산 구분 | 기준일자 | 작성일자 | 발행일자 |
| 일반 정산 | 매출 승인일 기준 1일~말일 | 해당 월 말일 | 다음 달 첫 영업일 |
### 세금계산서 계산 방식
국세청 개정안 기준으로 아래 방식에 따라 계산돼요.
- 공급가액 = (수수료 + 부가세) ÷ 1.1
- 부가세 = (수수료 + 부가세) - 공급가액
예시 거래 내역
| 거래금액 | 수수료 | 부가세 | 지급액 |
| 10,000원 | 265원 | 27원 | 9,708원 |
| 10,000원 | 265원 | 27원 | 9,708원 |
| 10,000원 | 265원 | 27원 | 9,708원 |
| 합계 | 795원 | 81원 | - |
발행된 세금계산서
| 항목 | 공급가액 | 부가세 | 총액 |
| 발행 대상 금액 | 795원 | 81원 | 876원 |
| 실제 발행 금액 | 797원 | 79원 | 876원 |
소수점 처리 방식에 따라 실제 공급가액과 부가세는 일부 차이가 날 수 있어요.
### 세금계산서 발행 방식 (프랜차이즈 한정)
프랜차이즈의 경우, 아래 두 가지 방식 중에서 선택할 수 있어요.
| 방식 | 설명 |
| 건별 발행 | 해당 월 거래 수수료와 부가세를 단순 합산해서 발행해요. |
| 월별 발행 (기본) | 전체 수수료/부가세를 합산한 뒤, 총수수료 ÷ 1.1로 공급가액 재계산 후 발행해요. (소수점 반올림 포함) |
세금계산서 발행 방식은 계약 시점에 협의해서 설정해 주세요.
## 4. 현금영수증 및 신용카드 매출 전표
### 오프라인 토스머니 결제
오프라인에서 토스머니(현금)로 결제한 건은 '선불전자영수증'이 자동으로 발행돼요.
선불전자영수증은 일반 현금영수증과 다르게 아래와 같은 방식으로 처리돼요.
| 구분 | 내용 |
| 발급 시점 | 결제 시 자동 발급 |
| 확인 방법 | 연말정산 기간 중 국세청 홈택스에서 1회 확인 가능 |
| 매출 분류 | 일반 현금 매출이 아닌, 직불카드·선불전자지급수단 매출로 분류돼요. |
별도로 현금영수증을 발행하지 않아도 돼요. 국세청에서 자동 확인 가능해요.
## 5. 부가세 참고자료
토스페이를 통한 매출에 대한 부가가치세 신고용 자료는 아래 경로를 통해 확인할 수 있어요.
- 토스페이 파트너스
더 자세한 내용은 자주 묻는 질문에서 확인할 수 있어요.
부가세 신고용 정산 자료는 토스페이 파트너스 관리자 페이지에서 기간별로 다운로드할 수 있어요.
---
# 결제 정책
URL: /offline/policy/payment
## 연령에 따른 결제 수단 제한
사용자의 연령에 따라 이용할 수 있는 결제 수단에 제한이 있어요.
| 연령대 | 사용 가능 수단 |
| 만 7세 이상 ~ 19세 미만 | 토스머니, 본인 명의 카드 (유스카드 제외), 계좌 |
| 만 19세 이상 | 토스페이머니, 본인 명의 카드, 계좌 |
| 만 17세 이상 | 페이스페이(휴대폰/계좌/신분증 2+1 본인 인증 필수) |
## 최소 결제 금액
| 결제 수단 | 최소 결제 가능 금액 |
| 카드 | 10원 이상 |
| 머니 / 계좌 | 0원부터 가능 |
프로모션 쿠폰, 전액 할인 결제 등도 가능하게 설계되어 있어요.
## 결제 한도 정책
결제 한도는 사용자의 연령과 고환금성 여부에 따라 달라져요.
고환금성 여부는 가맹점 설정값과 거래 전문 필드의 T/F 값을 기준으로 판단해요.
| 구분 | 1회 한도 | 1일 한도 | 월 한도 | 무기명 한도 |
| 만 7세 이상 ~ 19세 미만 | 1,000,000원 | 1,000,000원 | 2,000,000원 | 500,000원 |
| 만 19세 이상 | 2,000,000원 | 2,000,000원 | 5,000,000원 | 500,000원 |
| 고환금성 | 300,000원 | 300,000원 | 300,000원 | 300,000원 |
고환금성이란 현금화 가능성이 높아 부정 사용 우려가 큰 거래 유형을 말해요.
- 성인 회원의 경우 1회 한도(200만원)를 초과하는 결제는 생성할 수 없어요.
- 위 한도는 토스 머니에 해당하는 표준 한도예요.
- 결제수단 상관없이 각 가맹점별/고객별 판매 품목이나 Risk 등급에 따라 결제 가능 한도를 제한할 수 있어요.
- 구매 한도는 결제 금액과 더불어 토스 송금액도 함께 합산돼요.
## 정산 및 수수료 기준
- 머니/계좌 결제: 승인 시점을 기준으로 정산되며, 익일에 정산 파일이 제공돼요.
- 카드 결제: 카드사 매입 기준으로 정산이 진행돼요.
- 정산 파일 전송: 매일 새벽, SFTP 방식으로 밴(VAN)사에 전달돼요.
수수료 정책 상세 내용은 수수료 정책 (오프라인)에서 확인할 수 있어요.
---
# 정산 정책
URL: /offline/policy/settlement
## 1. 수수료
### 기본 수수료
| 결제수단 | 영중소 가맹점 구분 | 수수료율(VAT 별도) |
| 토스 머니 / 토스페이머니 / 계좌 | 일반 | 1.8% |
| | 중소 | 1.2% |
| | 영세 | 0.8% |
- 카드 결제 수수료율은 토스가 아닌, 가맹점과 카드사 간 신용카드 계약에 따라요.
- 토스는 간편결제 인증 및 관련 처리 업무만 담당해요.
- 일부 특수 업종 또는 대형 프랜차이즈 가맹점은 위 수수료 정책 대상에서 제외될 수 있어요.
### 영중소 가맹점 구분
수수료율은 연 2회, 여신금융협회 또는 국세청에서 제공하는 연매출 기준에 따라 결정돼요.
## 2. 환불
토스 간편결제 환불 정책은 다음과 같아요.
### 정의
결제를 생성하고 완료된 이후에 지불한 금액을 다시 돌려받는 행위예요.
환불 요청 시 환불금액은 가맹점 정산에 마이너스(-)로 반영되며, 차기 정산 대금과 상계가 불가능한 경우 미수채권으로 전환되어 별도 입금 요청을 드릴 수 있어요.
### 전액/부분 환불 가능 여부
전액 환불과 부분 환불 모두 가능하며, 복합결제의 경우 아래와 같이 환불돼요.
- 복합결제 전액 환불: 원 결제수단으로 환불되며 포인트는 반환돼요.
- 복합결제 부분 환불: 원 결제수단을 먼저 반영한 이후 포인트는 가장 나중에 환불 처리돼요.
### 탈퇴 유저 환불 처리
- 토스 탈퇴 시, 환불계좌를 입력하여 정보가 기등록되어 있는 경우 환불 계좌로 환불 처리하며 토스에 가입된 사용자 휴대폰번호로 입금 LMS를 발송해요.
- 환불계좌 등록 시 별도의 개인정보 동의를 체크하여 탈퇴로부터 1년간 해당 정보를 저장해요.
- 토스를 통해 환불 거래가 발생하지 않았으므로 수수료 보전이나 세금계산서 반영은 불가한 점 양해 부탁 드려요.
### 환불 금액은 어디로 가나요?
- 계좌결제의 경우 결제를 진행한 계좌로 환불 처리돼요. 토스머니로 결제했다면 환불금액은 토스머니로 돌아가기 때문에 따로 '환불 계좌'를 수집하지 않아도 돼요.
- 토스머니 결제 건 환불 시, 해당 거래의 환불 후 토스머니 잔액이 200만원 이상인 경우 결제 충전용 계좌로 환불 처리돼요.
### 환불 가능 기간
- 일반적인 결제는 결제 승인일로부터 1년까지 가능해요.
- 유효기간 초과된 환불요청 시, COMMON_REFUND_ERROR "환불이 불가능한 상태입니다." 오류가 발생해요.
### 환불 시 발생하는 사용자 계좌정보 조회실패 오류
토스머니 환불은 가맹점의 환불요청과 동시에 즉시 사용자 토스 계정으로 환급 처리돼요.
그러나 환불요청 시 COMMON_ASSET_GET_ACCOUNT_ERROR "계좌정보 조회에 실패했습니다" 오류가 발생한다면 구매자의 토스 계정이 임시 차단된 상태일 수 있어요.
이 경우, 구매자가 직접 토스 고객센터로 연락주셔야 하며 계정 활성화 후 가맹점은 재 환불을 진행해 주시면 돼요.
## 3. 구매자 회원 가입 조건
만 14세 이상이면 누구나 회원 가입 후 토스페이를 이용할 수 있어요.
토스머니는 자신의 은행 계좌를 통해 자동 충전할 수 있어요.
### 토스 머니
지원 은행
우리 / KB국민 / IBK기업 / 부산 / 경남 / 우체국 / 광주 / 전북 / 새마을 / NH농협 / 신협 / SC제일 / 대구 / KDB산업 / 제주 / KEB하나 (구 외환은행 포함) / 수협 / 신한 / 카카오뱅크 / SBI 저축은행 / 케이뱅크 / 씨티 / 산림조합 / 저축은행 / 토스뱅크
지원 증권사
키움 / 삼성 / NH투자 / 대신 / 신한금융투자 / 메리츠증권 / 유진투자 / 미래에셋대우 / 한국투자 / 한화투자 / 교보 / 이베스트 / SK / 동부(DB금융투자) / KB증권 / 하이투자 / HMC투자(현대차투자) / 하나금융 / 토스증권
## 4. 취소/환불 시 한도 회복
당일 취소/환불 시 일 한도가 회복되며, 당월 취소/환불 시 월 한도가 회복돼요.
### 예시
- 6/29 결제 500,000원 → 6/29 당일 환불 완료 시
- 6/29 일 결제 한도 +500,000
- 6월 월 결제 한도 +500,000
- 6/29 결제 500,000원 → 6/30 환불 완료 시
- 6/30 일 결제 한도 변함 없음
- 6월 월 결제 한도 +500,000
- 6/30 결제 500,000원 → 7/1 환불 완료 시
- 7/1 일 결제 한도 변함 없음
- 7월 월 결제 한도 변함 없음
## 5. 결제 가맹점의 준수사항
가맹점은 아래 사항을 준수해야 해요.
- 가맹점은 직불전자지급수단이나 선불전자지급수단 또는 전자화폐(이하 "전자화폐등"이라 한다)에 의한 거래를 이유로 재화 또는 용역의 제공 등을 거절하거나 이용자를 불리하게 대우해서는 안 돼요.
- 가맹점은 이용자로 하여금 가맹점수수료를 부담하게 해서는 안 돼요.
- 가맹점은 다음 각 호의 어느 하나에 해당하는 행위를 해서는 안 돼요.
- 재화 또는 용역의 제공 등이 없이 전자화폐등에 의한 거래를 한 것으로 가장하는 행위
- 실제 매출금액을 초과하여 전자화폐등에 의한 거래를 하는 행위
- 다른 가맹점 이름으로 전자화폐등에 의한 거래를 하는 행위
- 가맹점의 이름을 타인에게 빌려주는 행위
- 전자화폐등에 의한 거래를 대행하는 행위
- 가맹점이 아닌 자는 가맹점의 이름으로 전자화폐등에 의한 거래를 해서는 안 돼요.
## 6. 토스의 책임사항
토스는 아래의 거래에 따른 손실을 가맹점에 떠넘길 수 없어요.
다만, 토스가 그 거래에 대하여 그 가맹점의 고의 또는 중대한 과실을 증명하는 경우에는 그 손실의 전부 또는 일부를 가맹점의 부담으로 할 수 있다는 취지의 계약을 가맹점과 체결한 경우에는 그러하지 않아요.
- 분실되거나 도난된 전자화폐등에 의한 거래
- 위조되거나 변조된 전자화폐등에 의한 거래
---
# 지원 VAN
URL: /offline/policy/van
토스페이에서는 다음과 같은 밴사를 지원해요.
- NICE
- KIS
- SMARTRO
- KOVAN
- KFTC
- KSNET
- DAOU DATA
- SECTA9
- KPN
- KICC
- KOCES
- NHVAN
- NICEPAY
- KCP
---
# 페이스페이
URL: /offline/faq/facepay
### 누구나 페이스페이로 결제할 수 있나요?
토스 앱에서 ‘토스 페이스페이’ 등록을 완료했다면 누구나 사용할 수 있어요.
### 외국인도 페이스페이로 결제할 수 있나요?
토스 앱에서 얼굴 등록 (페이스페이 신청)을 마친 분이라면 외국인도 누구나 페이스페이를 이용할 수 있어요.
### 똑같이 생긴 사람이 대신 결제하는 일은 없나요?
페이스페이는 고도화된 얼굴 인식 기술로 사람마다 고유한 얼굴 특징을 정밀하게 구별해요. 일란성 쌍둥이처럼 얼굴 특징이 흡사한 경우에는 2차 인증으로 더욱 안전하게 결제할 수 있도록 하고 있어요.
또한, 라이브니스(Liveness) 기술로 가짜 얼굴을 걸러내기 때문에 사진이나 영상을 통한 결제는 불가능해요.
부정 거래가 발생하더라도 토스 안심보상제를 통해 피해 금액을 전액 보상 받을 수 있어요. (1회 결제 한도 최대 200만 원)
### 개인정보는 안전하게 지켜지나요?
페이스페이로 등록된 사용자 정보는 암호화해 토스 서버에서만 안전하게 관리해요. 데이터를 안전하게 보호하기 위해 토스는 24시간 FDS(이상거래탐지시스템) 기술 등 최고 수준의 보안 기술을 적용하고 있어요. 또한 모든 개인정보는 고객님이 사용을 동의한 서비스 외 다른 목적으로 절대 사용되지 않아요.
### 결제 취소는 어떻게 하나요?
결제 취소 요청 후, 결제 내역 → 취소QR(토스 결제내역에서 확인 가능)을 프론트에 찍어주세요.
취소 QR 확인 경로: (고객 핸드폰) 토스 앱 → 우측 상단 결제 → 결제 내역 → 오프라인 → 해당 결제건 → 결제 취소하기
### 저도 페이스페이로 결제해보고 싶어요!
토스 유저라면 누구나 페이스페이를 사용하실 수 있어요.
토스 앱 메인 화면 → 우측 상단 [결제] → 페이스페이 → 얼굴등록 후 사용하실 수 있어요.
### 프론트를 키오스크 모드로 사용하고 싶어요
프론트와 연결된 포스가 토스 포스일 경우만 프론트를 키오스크로 사용하실 수 있어요.
### 문의처
- 결제 오류 관련 문의: 담당 밴대리점에 연락해 주세요.
- 토스페이 (결제, 정산, 지도정보) 관련 문의: 토스페이 고객센터 1644-4900
- 토스프론트 (기기) 관련 문의: 토스플레이스 고객센터 1644-2955
- 프랜차이즈 페이스페이 도입 문의: 도입을 위해 공식 이메일(facepay@toss.im)로 연락해 주세요.
---
# 페이스페이 결제 실패
URL: /offline/faq/facepay-fail
### 페이스페이가 정상적으로 작동하지 않아요
- 토스 프론트가 인터넷에 연결되어있는지, 블루투스가 켜져 있는지 확인해주세요. (화면 우측 상단 메뉴 → 설정)
- 토스 프론트가 최신 버전인지 확인해주세요. (화면 우측 상단 메뉴 → 설정 → 앱 버전)
- 최신 버전이 아닐 경우, 버전을 클릭하여 최신 버전으로 업데이트 해주세요.
- 프론트를 한번 껐다 켜 주세요. (재부팅)
- 옆면의 버튼을 꾹 눌러주세요 → '재시작' 버튼을 눌러주세요. (토스 재시작 버튼 X)
### 카메라 화면이 뿌옇거나 얼굴 인식이 잘 되지 않아요
- 카메라를 한 번 닦아주세요.
- 역광이 심하거나, 주변이 너무 어둡다면 얼굴 인식이 어려울 수 있어요. 프론트 위치를 재조정해 주세요.
- 높이가 너무 높거나 낮은 것은 아닌지, 카메라를 가리는 물체는 없는지 확인해주세요.
### 페이스페이 버튼을 눌렀을 때 더 이상 진행이 불가능한가요?
- 대리점에 연락하여 포스/단말기 업데이트 및 환경설정을 요청해 주세요.
- ‘간편결제’(모바일/QR결제) 버튼이나 결제 방식으로는 페이스페이 결제가 가능할 수 있어요. ‘간편결제’ 방식으로 페이스페이를 시도해주세요.
### (포스) 카드결제 버튼을 눌러도 통합결제 화면이 아닌 '카드를 끝까지 넣어주세요' 화면이 떠요
- '카드를 끝까지 넣어주세요' 문구와 함께 보이는 페이스페이버튼으로는 결제가 불가능해요.
- Union, IMU 포스: '통합결제' 버튼으로 결제를 시도해주세요.
- OK 포스: 대리점 조치가 필요한 상황이에요. 밴 대리점에 연락해 토스 페이스페이가 가능하게 결제 환경을 만들어 달라고 요청해주세요.
- 업데이트가 안되어있을 수 있어요. 대리점에 문의해주세요.
### (단말기) 카드결제 시 '카드를 끝까지 넣어주세요' 화면이 떠요
- 업데이트가 안되어있을 수 있어요. 대리점에 문의해주세요.
- KIS 단말기 사용중이신가요? 설정이 필요할 수 있어요. 대리점에 문의해주세요.
- 업데이트를 했는데도 안될 경우, '간편결제' 경로로 토스페이가 가능한지 시도해주세요.
### 얼굴 인식까지는 되었는데, 포스/단말기에서 오류 문구가 떠요
#### 오류문구가 '미등록 가맹점'을 포함하거나, 비슷한 오류 문구일 경우
- 토스페이 이용 계약이 안되어 있거나, 밴 대리점에서 토스페이 가맹점 번호를 등록하지 않아 발생한 오류예요.
- 사업자 번호로 토스페이 이용 계약이 안 되어있는 경우, 밴대리점을 통해 토스페이 입점 계약을 신청해주세요. (대리점을 통해 계약 완료 여부를 확인하실 수 있어요.)
- 계약이 되어 있는 경우, 밴 대리점에 전화하여 "밴 전산에 가맹점번호 등록" 을 요청해주세요.
#### 그 외
- 밴 대리점에 연락하여 문의해주세요. 업데이트가 필요할 수 있어요.
---
# 프로모션
URL: /offline/faq/promotion
### 프로모션은 수정할 수 있나요?
진행 중인 프로모션이라도 배너 이미지 교체는 가능해요.
### 프로모션 실적은 어디서 확인할 수 있나요?
토스 세팅 프로모션의 경우, 토스페이 파트너스에서 기간별 거래 내역을 조회할 수 있어요.
자세한 방법은 토스페이 파트너스 가이드를 참고해 주세요.
### 인보이스를 빨리 받고 싶어요
정산서는 프로모션 집행 익월 1일부터 발행 가능해요. 빠른 발행을 원하시면 [정산서 승인하기] 버튼을 눌러주세요. 승인하지 않으면 3영업일 이내 자동 발행되어요.
### 인보이스/정산서를 못 받았어요.
등록된 이메일 주소가 잘못되었을 가능성이 있어요. support-pay@toss.im으로 문의해주세요.
### 환불 적용이 궁금해요.
프로모션 집행월 말일까지 환불이 적용 가능해요. 정산 이후 환불은 지원하지 않는 점 양해 부탁드려요.
### 가상계좌번호는 일회성인가요?
가상계좌는 사업자 고유 계좌로 구성되어 영구적으로 사용할 수 있어요.
### 여러 프로모션을 운영 중인데, 합산 입금이 가능한가요?
인보이스상의 금액으로만 입금 가능하며, 합산 입금 시 계좌 오류로 처리되지 않아요.
### 정산서 내역을 이해하기 어려워요.
아래 항목을 참고해주세요.
| 항목 | 설명 |
| 프로모션 ID | 프로모션별 고유 번호 |
| 프로모션명 | 스킴 내용 |
| 프로모션 타입 | DISCOUNT(즉시 할인), CASHBACK(적립) |
| 프로모션 상태/결제 상태 | 환불이 발생하지 않은 경우:- COMPLETED/PAY전체 환불 발생:- REFUND_ALL/PAY (원 결제 내역)- COMPLETED/REFUND (전체 환불 내역)부분 환불 발생:- COMPLETED/PAY (원 결제 내역)- COMPLETED/REFUND (부분 환불 내역, 여러 건 가능) |
| 결제 토큰 | 고객 고유 토큰 |
| 결제/환불 금액 | GMV = 실결제금액 + 포인트 사용금액 + 할인금액 |
| 토스결제 할인금액 | 토스프라임 할인 금액 + 최종 할인/적립 금액 |
| 최종 할인/적립 금액 | 프로모션으로 인한 할인 금액 |
---
# AI 도구로 연동하기
URL: /ai-tools
Cursor, Claude Code 같은 AI 코딩 도구로 토스페이 연동을 개발한다면, 도구에게 토스페이 문서를 직접 읽혀서 더 정확한 코드를 얻을 수 있어요. 토스페이 가이드는 이를 위해 llms.txt 표준 문서를 제공해요.
## 제공하는 파일
| 파일 | 내용 | 용도 |
| /llms.txt | 전체 문서의 목차와 페이지별 요약 | AI 도구가 필요한 문서를 찾아가는 인덱스로 사용해요. |
| /llms-full.txt | 전체 문서의 본문을 담은 텍스트 파일 | 도구가 링크를 따라갈 수 없는 환경에서 통째로 제공할 때 사용해요. |
두 파일 모두 온라인 결제 튜토리얼, 가이드, API 레퍼런스, FAQ, 정책과 오프라인 결제 문서까지 포함해요. 문서가 업데이트되면 배포 시점에 자동으로 갱신돼요.
## AI 도구에서 사용하기
도구가 웹에 접근할 수 있다면 URL을 컨텍스트로 추가하는 방법이 가장 간단해요.
- Cursor 설정의 Docs에 https://docs-pay.toss.im/llms.txt를 추가하면, 채팅에서 @Docs로 토스페이 문서를 참조할 수 있어요.
- Claude Code 등 URL을 읽을 수 있는 도구라면 프롬프트에 https://docs-pay.toss.im/llms.txt를 참고하라고 알려주세요. 도구가 목차에서 필요한 문서를 찾아 읽어요.
도구가 외부 링크에 접근할 수 없는 환경이라면 /llms-full.txt를 내려받아 프로젝트에 포함하거나 프롬프트에 첨부하세요.
AI가 생성한 연동 코드는 반드시 검증하세요. API Key 보관, 결제 완료 확인 방식(콜백·상태 확인) 같은 보안·정합성 요구사항은 튜토리얼과 API 레퍼런스를 기준으로 확인해야 해요.