인증 및 기타 헤더 설정

토스페이먼츠 API를 사용하기 위해 필요한 인증과 헤더 설정 방법입니다.

토스페이먼츠 API는 일반적으로 Basic 인증에 시크릿 키를 사용합니다. 시크릿 키는 개발자센터에서 확인할 수 있습니다.

1. 개발자센터에서 내 시크릿 키를 확인하세요.

• 로그인했다면, 아래 키값도 내 테스트 시크릿 키로 바뀌어요.
• 로그인하지 않고 문서에 있는 테스트 시크릿 키도 결제 연동에 사용할 수 있지만, 결제 내역을 확인할 수 없어요.

2. 시크릿 키 뒤에 :을 추가하고 base64로 인코딩하세요. 콜론을 빠트리지 않도록 주의하세요.

아래 명령어를 터미널에서 실행하면 인코딩된 값을 얻을 수 있습니다.

3. 인코딩된 값을 API의 Basic 인증헤더에 사용하세요.

HTTP Basic 인증 방식은 클라이언트에서 base64로 인코딩된 사용자 ID, 비밀번호 쌍을 인증 정보(credentials) 값으로 사용합니다. 사용자 ID와 비밀번호는 위와 같이 콜론으로 구분합니다. Base64로 인코딩한 정보는 쉽게 디코딩이 가능해서 Basic 인증은 반드시 HTTPS 및 TLS와 함께 사용해야 합니다.

토스페이먼츠 API는 시크릿 키를 사용자 ID로 사용하고, 비밀번호는 사용하지 않습니다. 비밀번호가 없다는 것을 알리기 위해 시크릿 키 뒤에 콜론을 추가합니다.

시크릿 키는 상점의 결제를 승인·취소·조회할 수 있는 자격증명입니다. 비밀번호와 같은 수준으로 다뤄야 합니다. 시크릿 키가 유출되면 제3자가 상점 명의로 결제를 승인하거나 취소할 수 있습니다.

• 소스 코드에 하드코딩: 비공개 저장소라도 안 됩니다. 클론·포크되면 추적할 수 없고, 한 번 커밋되면 히스토리에 남습니다.
• 클라이언트·앱에 포함: 디컴파일(역분석)을 통해 쉽게 탈취될 수 있습니다.
• URL 쿼리스트링에 포함: 액세스 로그·리퍼러·브라우저 히스토리에 그대로 남습니다.
• 로그에 출력: 디버그 로그에 요청 헤더를 통째로 출력하는 코드가 흔한 유출 경로입니다.
• 메신저·이메일로 공유: 평문 전송입니다. 개발자센터의 사용자 추가 기능으로 권한을 부여하고 각자 직접 조회하도록 하세요.
• 테스트·라이브 키 혼용: 테스트 환경에서는 테스트 키만 사용하세요. 라이브 키의 노출 위험을 줄일 수 있습니다.

키는 애플리케이션 코드·설정 파일과 분리된 전용 시크릿 저장소(vault) 에 두고, 실행 시점에 불러오는 방식을 권장합니다. 아래는 대표적인 저장소별 연동 예시입니다.

API 문서: AWS Secrets Manager API Reference

IAM 정책으로 결제 서버 역할만 읽도록 제한하세요.

API 문서: AWS KMS API Reference

설정 파일에 암호문으로 보관하고 실행 시점에 복호화하는 방식입니다.

API 문서: Google Cloud Secret Manager API

API 문서: Azure Key Vault REST API

API 문서: HashiCorp Vault API Docs

환경변수로 주입하고, 값이 담긴 파일은 반드시 .gitignore에 추가하세요. 이 방식은 차선책입니다. 환경변수는 프로세스 목록·크래시 덤프·에러 리포팅 도구에 노출될 수 있습니다.

키를 읽을 수 있는 주체를 필요한 범위로 제한하세요.

• 결제를 담당하는 팀·서비스에만 권한을 부여하세요.
• 외주사를 통해 연동한다면 개발 종료 시점에 조회 권한을 회수하세요. 개발자센터 왼쪽 하단 사용자 추가하기에서 권한을 관리합니다.
• 운영 서버 역할과 개발자 개인 계정의 권한을 분리하세요. 라이브 키를 직접 확인할 일은 거의 없습니다.
• 퇴사·조직 이동 시 권한 회수를 정기 점검 항목에 포함하세요.

키 자체에 IP 제한을 걸어 호출 주체(호출 서버)를 제한하는 방법도 함께 사용하세요. API 키 접근 정책을 참고하세요.

사람이 조심하는 것만으로는 유출을 막기 어렵습니다. 자동 탐지 도구를 도입하도록 권고합니다.

토스페이먼츠 키 패턴을 커스텀 룰로 추가하면 탐지율이 올라갑니다.

API 로그를 주기적으로 확인해 직접 보내지 않은 요청이 있는지 점검하세요.

수상한 호출을 발견했다면 아래 순서로 조치하세요.

1. 키 재발급 후 기존 키를 즉시 폐기합니다.
2. API 키 접근 정책에 IP 제한을 등록합니다.
3. 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com) 또는 실시간 문의 채널로 연락합니다.

토스페이먼츠에서도 유출된 키를 발견하면 조치 요청 메일을 발송합니다. 다만 모든 유출을 발견할 수는 없으므로 상점에서 직접 관리하는 것이 기본입니다.

결제 연동을 중개사·연동 솔루션을 통해 하고, 중개사 콘솔에 시크릿 키를 등록하는 구조라면 아래 보관 기준을 지켜주세요.

• 중개사 담당자에게 메신저·이메일로 키를 전달하지 마세요.
• 중개사와의 계약이 종료되면 키를 재발급해 회수하세요. 계약 종료는 키 회수 사유입니다.
• 중개사 서버 IP를 API 키 접근 정책에 등록해 호출 주체를 제한하세요.

• 시크릿 키가 소스 코드·클라이언트·앱에 들어 있지 않습니다.
• 전용 시크릿 저장소(vault)에 분리 보관합니다.
• 평문으로 저장·전송하지 않습니다.
• 키 접근 권한이 필요한 주체로 제한되어 있습니다.
• 외주사·중개사 권한을 개발 종료 후 회수했습니다.
• 시크릿 스캐닝이 커밋 또는 CI 단계에 붙어 있습니다.
• 테스트·라이브 키를 분리해 사용합니다.
• API 로그를 주기적으로 확인합니다.
• API 키 접근 정책(IP 제한)을 등록합니다.

• 시크릿 키 베스트 프랙티스

멱등성은 연산을 여러 번 하더라도 결과가 달라지지 않는 성질을 뜻합니다. API 요청에서 멱등성을 보장하면 같은 요청이 여러 번 일어나도 항상 첫 번째 요청과 같은 결과가 돌아옵니다.

멱등키를 사용하면 민감한 API 요청이 반복적으로 일어나는 문제를 막을 수 있고, 네트워크 이슈나 타임아웃 문제로 응답을 받지 못했을 때도 안전하게 같은 요청을 다시 보낼 수 있습니다. 멱등성의 개념과 구현 방법은 토스페이먼츠 블로그 포스트에서 더 자세히 살펴보세요.

요청 헤더에 Idempotency-Key를 추가하면 멱등한 요청을 보낼 수 있습니다.

• 멱등키는 UUID와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 최대 길이는 300자입니다.

• 멱등키는 처음 요청에 사용한 날부터 15일간 유효합니다. 처음 요청한 날부터 15일이 지났다면 새로운 멱등키로 요청하세요.

아래와 같이 API 요청에 멱등키 헤더를 사용하면 같은 요청이 두 번 일어나도 실제로 요청이 이루어지지 않고 첫 번째 요청 응답과 같은 응답을 보내줍니다.

• 토스페이먼츠 서버는 상점에서 API 요청 헤더로 보낸 멱등키와 API 키, API 주소, HTTP 메서드 조합이 같은 요청이 있는지 확인해서 멱등성을 보장합니다. 따라서 API 키, API 주소, HTTP 메서드가 다르다면 같은 멱등키를 사용해도 괜찮습니다.
• 멱등키 관리를 위한 별도의 데이터베이스나 테이블을 사용하면 서버 성능 및 보안 및 유지보수 측면에서 장점이 있습니다. 단순한 데이터 구조라면 Redis와 같은 키-값(K-V) 저장소를 사용해도 괜찮습니다. 멱등키와 관련된 데이터의 복잡도, 유효 기간 관리, 확장성, 성능 등을 고려해서 적절한 데이터베이스 유형을 선택하세요.
• 멱등한 요청에서 에러가 반환되었을 때 멱등키를 변경해서 동일한 요청을 재시도하는 것은 위험이 있습니다. 정확한 오류 원인을 토스페이먼츠로부터 확인한 다음에 다시 요청을 보내주세요.

멱등키 헤더를 사용할 때 발생할 수 있는 에러는 두 가지가 있습니다. 멱등키 길이가 300자보다 길면 HTTP 400 - INVALID_IDEMPOTENCY_KEY가 돌아옵니다. 300자 이하로 멱등키를 다시 만들어주세요. 첫 번째 요청이 처리 중일 때 같은 요청을 다시 보내면 HTTP 409 - IDEMPOTENT_REQUEST_PROCESSING 에러가 돌아옵니다. 이 에러가 돌아오면 다시 한번 요청해서 응답을 확인하세요.

API 요청에 추가할 수 있는 선택 헤더 목록입니다.

모든 필드와 오류 메시지는 기본적으로 한글로 제공됩니다. 영문으로 에러 메시지 및 응답 본문을 받고 싶다면 API 요청 헤더에 Accept-Language를 포함하세요. 사용자가 입력한 값을 제외한 모든 필드가 영어로 변환됩니다.

결제 과정에서 팝업 차단 에러가 나는 것을 방지하기 위해 아래와 같이 HTTP 헤더를 설정해주세요. COOP(Cross-Origin-Opener-Policy)은 웹 사이트에서 팝업 창이나 새 탭을 열 수 있는지 정하는 보안 정책입니다.

테스트 환경에서 에러를 재현하고 싶다면 토스페이먼츠 API 테스트 헤더를 사용하세요.

• {TEST_CODE} 자리에 재현하고 싶은 에러 코드를 넣고 API를 실행하세요.
• test_ 로 시작하는 테스트 API 키를 사용해주세요. 라이브 환경에서는 테스트 코드 헤더가 무시됩니다.

예를 들어, 카드 번호 결제 API에 잘못된 유효기간을 넣었을 때 돌아오는 응답을 보고 싶다면 아래와 같이 INVALID_CARD_EXPIRATION를 테스트 헤더에 추가하세요.