시작하기
앱인토스를 연동하기 위해 필요한 API를 소개드려요.
앱인토스 개발을 처음 시작한다면, 좀 더 친절한 안내를 먼저 확인해보세요! '시작하기' 문서로 바로가기
주의해주세요
iframe은 사용할 수 없어요.
iframe을 사용할 경우 앱인토스 기능이 정상 동작하지 않고, 내부 보안 심사에서도 반려돼요.
단, YouTube 영상 콘텐츠를 삽입하는 용도는 예외적으로 iframe 사용이 가능해요.
서버 mTLS 인증서 발급받기
앱인토스 API를 사용하려면 반드시 mTLS(mutable Transport Layer Security, 양방향 전송 계층 보안) 인증서를 설정해야 해요.
mTLS는 클라이언트와 서버가 서로의 신원을 확인하는 방식이에요.
일반 HTTPS는 서버만 인증하지만, mTLS는 파트너사 서버와 앱인토스 서버가 서로를 인증해요.
이 인증서를 설정해야 다음을 보장할 수 있어요.
- 통신 구간 암호화
- 허용된 서버만 API 호출 가능
- 위·변조 방지
아직 인증서를 준비하지 않았다면 서버 mTLS 인증서 발급받기 문서의 mTLS 인증서 발급 방법을 먼저 확인하세요.
통신 방화벽 확인하기
서버에서 Inbound, Outbound 방화벽을 관리하고 있다면 아래 IP와 포트를 반드시 허용해야 해요.
허용하지 않으면 API 호출이 실패하거나 콜백을 받지 못해요.
가맹점이 허용해야 하는 Inbound IP
앱인토스 → 가맹점
| 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예요.
예를 들어 결제 결과 콜백을 받을 때 필요해요.
가맹점이 허용해야 하는 Outbound IP
가맹점 → 앱인토스
| 기능 | 도메인 | 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 포트를 열어야 정상적으로 통신할 수 있어요.
API 공통 규격
도메인 정보
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보다 많은 요청이 필요한 경우 채널톡으로 상향을 요청할 수 있어요.
요청할 때는 다음 정보를 함께 전달하세요.
- 사용 목적
- 예상 트래픽 규모
- 피크 시간대 요청량
비즈니스 목적과 트래픽 규모를 검토한 뒤 한도를 조정해요.
대량 트래픽이 예상된다면 서비스 오픈 전에 미리 협의하는 것이 좋아요.