서버 API 이용하기

앱인토스 API를 이용하기 전에 필요한 서버 통신 설정을 안내해요.

서버 mTLS 인증서 발급받기

앱인토스 API를 사용하려면 반드시 mTLS(mutable Transport Layer Security, 양방향 전송 계층 보안) 인증서를 설정해야 해요.

mTLS는 클라이언트와 서버가 서로의 신원을 확인하는 방식이에요. 일반 HTTPS는 서버만 인증하지만, mTLS는 파트너사 서버와 앱인토스 서버가 서로를 인증해요.

이 인증서를 설정해야 다음을 보장할 수 있어요.

통신 구간 암호화
허용된 서버만 API 호출 가능
위·변조 방지

발급받은 인증서는 다음과 같이 관리하세요.

인증서와 키 파일은 유출되지 않도록 안전하게 보관하세요.
인증서가 만료되기 전에 재발급하세요.
무중단 교체가 필요하면 인증서를 두 개 이상 등록해 둘 수 있어요.

아직 인증서를 준비하지 않았다면 서버 mTLS 인증서 발급받기 문서의 mTLS 인증서 발급 방법을 먼저 확인하세요.

통신 방화벽 확인하기

서버에서 Inbound, Outbound 방화벽을 관리하고 있다면 아래 IP와 포트를 반드시 허용해야 해요. 허용하지 않으면 API 호출이 실패하거나 콜백을 받지 못해요.

가맹점이 허용해야 하는 Inbound IP

앱인토스 → 가맹점

Port

117.52.3.11

443

211.115.96.11

443

106.249.5.11

443

117.52.3.80~87

443

211.115.96.80~87

443

106.249.5.80~87

443

앱인토스가 가맹점 서버로 요청을 보낼 때 사용하는 IP예요. 예를 들어 콘솔에 등록한 콜백 URL로 구독 상태 변경 콜백이나 데이터 제공 동의 회수 콜백을 받을 때 필요해요.

가맹점이 허용해야 하는 Outbound IP

가맹점 → 앱인토스

기능

도메인

Port

간편 로그인, 메시지 발송, 토스 포인트 지급

apps-in-toss-api.toss.im

117.52.3.192, 211.115.96.192, 106.249.5.192

443

간편 결제

pay-apps-in-toss-api.toss.im

117.52.3.195, 211.115.96.195, 106.249.5.195

443

가맹점 서버에서 앱인토스 API를 호출할 때 필요한 설정이에요. HTTPS 443 포트를 열어야 정상적으로 통신할 수 있어요.

CORS 허용하기

미니앱에서 서버와 통신하려면, 서버의 CORS 허용 Origin에 미니앱 Origin을 추가해야 해요. 허용해야 하는 Origin은 SDK 버전과 적용일에 따라 달라요.

SDK 3.x

SDK 3.x Origin 변경 안내

2026년 8월 25일(화) 이후 업로드되는 SDK 3.x 번들부터, SDK 2.x에서 사용하던 Origin으로 서비스돼요. 외부 서버와 통신하는 경우, 서버의 CORS 허용 Origin에 아래 Origin을 추가해 주세요.

https://<appName>.apps.tossmini.com : 실제 서비스 환경
https://<appName>.private-apps.tossmini.com : 콘솔 QR 테스트 환경

https://<appName>.web.tossmini.com : 실제 서비스 환경
https://<appName>.private-web.tossmini.com : 콘솔 QR 테스트 환경

SDK 1.x ~ 2.x

https://<appName>.apps.tossmini.com : 실제 서비스 환경
https://<appName>.private-apps.tossmini.com : 콘솔 QR 테스트 환경

API 공통 규격

도메인 정보

https://apps-in-toss-api.toss.im
https://pay-apps-in-toss-api.toss.im

API 공통 응답 형식

모든 API는 공통된 응답 구조를 사용해요. resultType 값으로 성공 여부를 먼저 확인하세요.

성공 응답

{
  "resultType": "SUCCESS",
  "success": {
    "sample": "data"
  }
}

resultType이 "SUCCESS"이면 요청이 정상 처리된 상태예요.
실제 응답 데이터는 success 객체 안에 들어 있어요.
각 API마다 success 내부 구조는 달라요.

실패 응답

{
  "resultType": "FAIL",
  "error": {
    "errorCode": "INVALID_PARAMETER",
    "reason": "요청에 실패했습니다."
  }
}

resultType이 "FAIL"이면 요청 처리에 실패한 상태예요.
errorCode는 오류 유형을 나타내는 코드예요.
reason에는 사람이 읽을 수 있는 오류 설명이 들어 있어요.
잘못된 파라미터를 보내면 INVALID_PARAMETER와 같은 코드로 에러를 발생시켜요.

응답을 처리할 때는 반드시 resultType을 먼저 검사한 뒤, 성공과 실패 로직을 나눠 구현하세요.

요청 제한 정책

앱인토스 API는 안정적인 서비스 운영을 위해 요청 수를 제한해요.

기본 제한

분당 3,000 QPM
QPM은 Queries Per Minute의 약자로, 1분 동안 호출할 수 있는 API 요청 수를 의미해요.
미니앱 기준으로 분당 최대 3,000건까지 요청할 수 있어요.

이 한도를 초과하면 일정 시간 동안 추가 요청이 차단될 수 있어요.

QPM 상향이 필요한 경우

기본 3,000 QPM보다 많은 요청이 필요한 경우 채널톡으로 상향을 요청할 수 있어요.

요청할 때는 다음 정보를 함께 전달하세요.

사용 목적
예상 트래픽 규모
피크 시간대 요청량

비즈니스 목적과 트래픽 규모를 검토한 뒤 한도를 조정해요. 대량 트래픽이 예상된다면 서비스 오픈 전에 미리 협의하는 것이 좋아요.

이전시작하기

다음WebView의 속성 제어하기

마지막 업데이트 14일 전

도움이 되었나요?