자주 묻는 질문

토스페이 계약을 통해 MID가 발급되면, 테스트용, 실거래용 apiKey가 한쌍으로 부여됩니다.

가맹점에 발급되는 MID의 key는 모두 운영 환경에서 사용 가능한 테스트용, 실거래용 apiKey이며, 개발 환경에서 테스트를 희망하는 경우 별도로 요청주시어 개발환경 apiKey를 전달받아 사용하셔야 합니다.

토스페이 운영환경에서 테스트용 apiKey를 사용하여 테스트할 경우 실제 금원 이동없이 승인 응답까지 확인하실 수 있습니다. 테스트 완료 시, apiKey를 실거래용으로 변경한 후 실제 사용자에게 서비스를 오픈하시면 됩니다.

토스페이 가이드는 LLM이 읽기 좋은 형태의 문서를 llms.txt 표준으로 제공합니다. 목차 버전인 /llms.txt와 전체 본문 버전인 /llms-full.txt가 있습니다.

Cursor, Claude Code 같은 도구에서 활용하는 방법은 AI 도구로 연동하기에서 안내합니다.

토스페이 운영 환경(pay.toss.im)은 방화벽은 오픈되어 있어 별도의 IP 등록이 필요치 않습니다.

가맹점 자체적으로 방화벽을 사용하는 경우, 하기 가이드에 안내된 토스페이의 IP 를 등록해주시기 바랍니다.

방화벽 설정하기

카드와 토스페이머니는 모두 독립적인 기본 결제수단이므로 복합결제가 불가하며, 기본 결제수단 + 토스포인트일 경우에만 복합결제가 가능합니다.

복합결제 가능한 경우: 기본 결제수단 + 토스포인트

• 카드 + 토스포인트 ⇒ 가능
• 계좌 + 토스포인트 ⇒ 가능
• 토스머니 + 토스포인트 ⇒ 가능
• 카드 + 토스머니 ⇒ 불가능
• 카드 + 계좌 ⇒ 불가능

계좌결제 선택 후 토스포인트를 사용하는 경우, 토스포인트 100%로 결제할 수 있습니다.

토스포인트는 독립적인 지불수단이 아니므로 카드/계좌 선택 후 토스포인트 결제가 가능합니다.

카드 선택 시 최소결제금액 100원 조건이 존재하여 카드 100원 + 나머지 토스포인트 결제로 처리되며, 계좌 선택 시 전액 토스포인트 결제가 가능합니다.

카드 결제의 경우 고객 카드 한도에 따라 적용됩니다.

아래 한도는 표준 한도이며, 가맹점의 판매 품목이나 Risk 등급에 따라 달라질 수 있습니다.

계좌결제, 토스(페이)머니 모두 payMethod(결제수단) 값이 동일하게 TOSS_MONEY로 응답되므로 두 결제수단의 구분을 위해서는 accountBankCode(은행코드) 값을 확인해주셔야 합니다.

토스머니/토스페이머니 결제 시 888 코드 응답

accountBankName: 토스머니
accountBankCode: 888
accountNumber: 0000000000

계좌 결제 시 결제계좌의 은행코드 응답

accountBankName: 우리은행          // 결제계좌 은행
accountBankCode: 020                    // 결제계좌 은행코드
accountNumber: 100*******792      // 결제계좌번호

1. 토스머니: 미성년자(만7세~19세미만) 대상 선불전자지급수단으로, 토스머니 충전 후 결제하는 방식 (성인은 fade out 처리됨)
2. 토스페이머니: 성인 대상 선불전자지급수단으로, 토스페이머니 충전 후 결제하는 방식
3. 계좌결제: 계좌에서 직접 출금되는 것이 아닌 계좌를 통해 토스머니를 충전한 후, 그 충전된 금액으로 결제하는 방식 (backend 로직: 고객 계좌 → 토스머니통으로 충전 → 결제)

승인결과 응답 시, 결제 요청금액에서 토스포인트, 즉시할인 사용 금액을 합산하여 discountedAmount 값으로 전달하고 있습니다.

retUrl의 이동은 토스 web page에서 처리되는 로직으로 일반적인 경우 처리를 보장하지만 특별한 상황에서 실패할 수 있습니다.

특별한 상황이란, 구매자가 결제 중에 앱을 종료하거나 백그라운드 처리를 하는 등의 이탈로 JavaScript 로직이 처리될 수 없는 경우입니다.

이 경우 구매자가 다시 결제 화면으로 돌아와서 '결제완료' 버튼을 클릭한다면 retUrl로의 이동을 재시도하게 됩니다. 다만, 구매자가 재시도를 하지 않는 경우에는 retUrl로 이동하지 못하는 상황이 발생할 수 있습니다.

ResultCallback은 토스 서버에서 가맹점 서버로 결제 결과를 안전하게 전달하는 서버 간 통신 방식입니다.

• retUrl은 단순히 사용자 브라우저를 리다이렉트하는 용도로, 결제 성공 여부를 토스에서 보장할 수 없습니다.
• 사용자가 중간에 이탈하거나 네트워크 문제가 발생하면, 결제 상태를 알 수 없는 경우가 생깁니다.
• ResultCallback은 서버 to 서버로 결과를 전달하므로 데이터 유실이 없고 안전한 통신 방식으로 결제 상태를 정확히 확인할 수 있습니다.

• 자동 승인 설정(autoExecute=true)인 경우, 반드시 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 값을 확인하실 수 있습니다.

구매자는 인증을 완료했지만 가맹점 retUrl로 결제 결과가 오지 않거나, 토스 서버로부터 resultCallback 결과를 받지 못할 경우, 먼저 방화벽 설정을 확인해야 합니다.

구조: 가맹점 ➔ 가맹점 방화벽 ➔ 토스페이

가맹점 방화벽의 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

구조: 토스페이 ➔ 가맹점 방화벽 ➔ 가맹점

가맹점 방화벽의 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

• 토스페이 방화벽은 제한 없이 모두 오픈되어 있습니다.
• 각 케이스 별 구분이 어려울 경우, Outbound와 Inbound 정책에 맞게 모든 토스 IP를 추가할 수 있습니다.
• 가맹점이 설정한 resultCallback URL에 443 이외의 포트가 포함되어 있다면 접근이 어려울 수 있습니다.
• 토스 서버의 IP가 추가되는 경우, 사전에 공지 메일을 발송해 드립니다.

1. 고객 결제 요청
2. 가맹점 서버 → 토스페이로 결제URL 생성 요청
3. 토스페이 → 가맹점으로 결제URL(checkoutPage) 응답
4. 고객 화면에 checkoutPage를 호출하여 '토스 페이프론트'로 이동

1. 토스 페이프론트에서 [다음] 클릭 시, 토스 APP 호출
2. 결제수단 선택 → [결제하기] 클릭 → 생체/비밀번호 인증
3. 계좌 결제로 진행한 경우 인증완료 시점에 계좌 출금 → 토스머니 충전

1. 토스 APP 인증 완료 후 이전 브라우저 or 앱으로 이동
2. 가맹점 결과페이지 retUrl로 이동 (retUrl은 가맹점에서 구현하는 결제 결과 페이지)

1. 결제생성 시 autoExecute 값을 세팅하지 않거나 'false'로 세팅한 경우, 승인요청 API를 호출해야 실제 결제가 이루어집니다.
2. 승인 요청을 위해 결제토큰 값이 필요하나, retUrl 인증결과 데이터에 결제토큰이 포함되어 있지 않습니다. 따라서 결제 생성 단계에서 주문번호와 결제토큰을 함께 저장해두었다가 승인 요청 시 결제토큰을 매핑해서 요청하도록 구현해야 합니다.

1. 최종적인 승인 결과를 판단할 수 있는 단계입니다.
2. 결제생성 시 resultCallback 필드에 세팅한 URL로 콜백이 전송되며, 자동승인 옵션(autoExecute=true)을 사용하는 경우에는 필수로 사용해야 합니다.

autoExecute 옵션은 자동 승인 여부를 제어하는 역할을 합니다.

고객 인증과 동시에 자동으로 승인할 것인지, 가맹점에서 승인 시점을 제어할 것인지에 따라 알맞게 autoExecute 필드 값을 세팅해주시면 됩니다.

• 고객이 토스 앱에서 인증 완료 시, 승인이 자동으로 처리됩니다.
• 승인에 대한 결과는 토스페이 → 가맹점 resultCallback으로 전송합니다.
• retUrl 전환 여부와 무관하게 자동으로 결제 승인까지 이루어지므로 편리합니다.

• value 값이 없거나, 오세팅된 경우에도 false와 동일하게 동작합니다.
• 가맹점에서 승인요청 API를 호출해야 승인 처리됩니다.
• 가맹점에서 고객인증 ↔ 승인 사이에 내부 처리(재고확인 등) 프로세스 구현할 수 있습니다.
• 인증 후 결제만료시간 3분 내로 승인 요청이 없을 경우, 결제 만료 처리되어 승인 실패됩니다.

토스페이 계좌 결제는 선불전자지급수단으로, 고객 계좌 → 토스머니 충전 → 결제 단계를 거치게 됩니다.

토스페이 결제 프로세스 중 계좌 출금되는 시점과 가맹점 결제가 이루어지는 시점은 아래와 같습니다.

• 토스APP 인증: 고객 계좌 출금 → 토스머니 충전
• 결제 승인: 토스머니 → 실제 결제 → 가맹점으로 응답

자동승인(autoExecute=true) 기능을 사용하는 가맹점은 인증과 동시에 승인이 자동으로 이루어져 이슈가 없으나, 자동승인 기능을 사용하지 않는 가맹점은 고객인증 ↔ 승인 구간에 단절이 있을 때 고객은 출금 상태이나, 가맹점은 결제내역이 없는 경우가 발생할 수 있습니다.

인증 후 결제토큰 만료시간 3분을 초과할 경우, 고객 계좌로 다시 환불 처리됩니다.

이때 결제 상태는 PAY_CANCEL로 저장되며 토스페이 파트너스에서 내역 조회가 가능합니다.

인증 후 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회 인증 및 결제수단 등록을 완료하면 가맹점은 빌링키를 확보합니다.

• 결제가 필요한 시점마다 가맹점에서 API를 호출해 과금 요청을 수행합니다.
• 금액 및 결제 주기는 상황에 따라 자유롭게 변경할 수 있습니다.

하나의 가맹점 - 하나의 토스 유저 대상으로 하나의 빌링키만 사용 가능하나, 빌링키 생성 시, 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일 소요

결제 환불 API로 전체환불과 부분환불 모두 처리가 가능합니다.

부분환불 요청 시 amount에 환불이 필요한 금액만큼 세팅해주시면 됩니다.

결제생성 당시 비과세금액(amountTaxFree)을 0 이외의 값으로 세팅한 경우, 부분환불 시 아래 과세, 부가세, 비과세 금액을 보내주셔야 합니다.

• amountTaxFree: 환불할 금액 중 비과세금액
• amountTaxable: 환불할 금액 중 과세금액
• amountVat: 환불할 금액 중 부가세

결제수단(카드, 토스페이머니) + 토스포인트 결제한 거래를 부분환불할 경우 원 결제수단을 우선적으로 환불한 후, 부족한 금액은 토스포인트로 환불됩니다.

프로모션 적립, 할인 거래의 경우 부분환불 후 남은 금액이 혜택 조건을 충족하는지 여부에 따라 적립/할인 회수율이 결정됩니다.

결제수단 + 토스포인트 + 할인 거래일 경우 환불 우선순위

1순위 - 혜택조건 충족 여부에 따라 할인 취소금액을 제외하여 환불금액 산정 2순위 - 원 결제수단 환불 3순위 - 이후 남은 금액은 토스포인트 환불

현금영수증은 현금성 거래인 계좌, 토스(페이)머니 결제를 대상으로 발행할 수 있으며, 토스 포인트, 즉시 할인 적용 금액은 제외해야 합니다.

따라서 현금영수증 자체 발행 시, 할인 금액을 제외한 순수 결제금액 필드인 paidAmount 값으로 처리해주시면 됩니다.

하기 두 가지 방법을 통해 현금영수증 자동 발행을 제한할 수 있습니다.

결제 생성 API 호출 시 cashReceipt = false로 세팅하면 해당 결제 건에 대해 현금영수증이 발행되지 않습니다.

가맹점 MID 전체에 대해 현금영수증 자동 발행을 비활성화하려면 토스페이 담당자에게 설정 변경을 요청해주세요.

결제환불 시, 해당 거래건의 현금영수증도 자동으로 취소 처리되므로 가맹점에서 별도로 처리하실 사항은 없습니다.

전체환불

• 현금영수증 전체취소

부분환불

• 기존 현금영수증 전체취소
• 환불 후 남은금액 만큼 현금영수증 재발행

현금영수증 취소에 대한 처리 유형에 따라 방법이 달라집니다.

현금성 결제인 토스머니, 계좌 결제건 중 현금영수증이 발행되지 않은 경우, 현금영수증 API를 연동하거나 토스페이 파트너스(어드민)를 통해 발행 처리할 수 있습니다.

API를 연동하여 가맹점 서버에서 현금영수증 발급/취소/상태조회 등을 처리할 수 있습니다. 현금영수증 API 연동가이드

거래내역 [조회] > 주문번호 클릭 > 현금영수증 [발급하기]

유저가 앞으로 토스페이에서 발급되는 모든 현금영수증 정보를 변경하고자 하는 경우 토스 앱에서 설정할 수 있습니다. (Default: 토스 앱 가입 시 휴대폰번호로 설정)

토스 앱에 저장된 현금영수증 정보 변경하기

전체 메뉴 > 상단 돋보기 클릭하여 '현금영수증' 검색 > 현금영수증 정보

이미 발행된 거래의 현금영수증 정보를 변경하기 위해서는 기존에 발행된 현금영수증을 취소하고 재발행해야 합니다.

현금영수증 API 재발행: 가맹점 서버에 현금영수증 API를 연동하여 기존 현금영수증을 취소하고 재발행할 수 있습니다. (결제는 유지, 현금영수증만 취소 처리)

토스페이 파트너스 재발행: 토스페이 파트너스 거래내역에서 현금영수증 취소 및 재발행 처리할 수 있습니다. 경로: 거래내역 [조회] > 주문번호 클릭 > 현금영수증 [발행하기] (이미 발행된 현금영수증이 있는 경우 - [취소] 후 [발행하기])

토스 앱 內 토스페이 결제내역에서 현금영수증 재발행 처리가 가능합니다.

토스페이먼츠(PG)를 통해 카드사 서브몰 등록 시 결제 대행사의 대표 가맹점번호로 등록되기 때문에 카드사 거래명세서나 SMS에는 '비바리퍼블리카'로 노출되는 것이 정상입니다.

가맹점 고유 상호명으로 표시되길 원하는 경우, 토스페이 담당자를 통해 카드사로 간판명 변경 심사를 요청하셔야 합니다.

단, SMS에 표시되는 상호명(서브몰명)은 카드사 정책상 변경이 불가할 수 있습니다.

정산대사는 아래 3가지 방법으로 진행하실 수 있습니다. 가맹점에서 희망하시는 방법으로 선택하여 확인하시면 됩니다.

API를 통해 정산 데이터를 조회하여 대사를 진행할 수 있습니다.

IP등록, 계정 생성 등 세팅 절차가 필요한 서비스이므로, 정산 담당자와 협의가 필요합니다. 필요한 경우 토스페이 담당자에게 별도로 요청해주시기 바랍니다.

※ 응답 데이터는 정산대사 API와 동일합니다.

토스페이 파트너스 > 정산 > 정산내역에서 엑셀 다운로드를 받아서 대사 진행

현재 제공되고 있는 정산 API는 일반 수수료로만 응답되며, 영중소 등급에 따른 수수료 확인은 불가합니다. (차액 정산 수수료용 API는 별도로 존재하지 않음)

따라서 토스페이 파트너스 메뉴를 통해 일별, 결제건별 차액정산 내역을 조회하셔야 합니다.

경로: 토스페이 파트너스 > 정산 > 차액정산내역 or 결제 건별 차액정산내역

토스페이 디자인 가이드는 메인 페이지 하단에서 다운로드 받을 수 있습니다.