가맹점 연동 네트워크 요구사항

토스페이먼츠 API를 연동하는 가맹점 시스템이 갖춰야 할 네트워크/보안 구성을 정리했습니다.

토스페이먼츠는 여러 진입점으로 분산된 환경에서 서비스를 운영합니다. 같은 도메인이라도 조회 시점, 위치, 부하분산 비율에 따라 DNS 응답에 담기는 IP의 개수와 순서가 달라집니다. 아래 요구사항은 그 환경에서 결제가 실패하지 않으려면 지켜야 할 조건입니다.

표준 라이브러리와 기본 설정을 쓰고 있다면 대부분의 항목은 이미 충족돼 있습니다. 각 표의 비고 열에 조치가 필요한 경우와 그렇지 않은 경우를 적어 두었으니 그 부분만 확인해주세요.

이 문서는 가맹점과 토스페이먼츠 사이의 양방향 호출을 모두 다룹니다. 방향은 항상 아래와 같이 표기합니다.

"인바운드"와 "아웃바운드"는 주체에 따라 뜻이 반대가 되므로 이 문서에서는 쓰지 않습니다.

이 문서는 토스페이먼츠가 제공하는 대부분의 도메인에 적용됩니다.

가맹점 → 토스페이먼츠 방향에 적용합니다.

토스페이먼츠는 응답 IP의 개수, 순서, 고정성을 보장하지 않습니다. 다만 api.tosspayments.com처럼 허용 목록이 공개된 도메인에서는, 응답에 담기는 IP가 항상 그 목록에 있는 IP입니다.

안내된 IP가 [IP-1, IP-2, IP-3, IP-4]인 도메인에서 다음은 모두 정상 동작입니다.

가맹점 → 토스페이먼츠 방향에 적용합니다.

T6의 근거는 RFC 9525 「Service Identity in TLS」 §6.3입니다. 와일드카드는 가장 왼쪽 레이블 전체로만 쓸 수 있어서 *.tosspayments.com은 유효하고 w*.tosspayments.com이나 *.*.tosspayments.com은 무효입니다.

에러가 발생하면 증상별로 확인할 지점을 먼저 좁혀주세요.

양방향 모두에 적용합니다.

F3이 위험한 이유는 실패가 확률로만 드러나기 때문입니다. DNS 응답 비율은 균등하지 않아서 빠진 IP의 가중치에 따라 실패율이 0%에 가깝거나 반대로 대부분이 될 수 있습니다. 특히 DNS가 IP를 하나만 응답하면 D4로 다음 IP를 시도할 여지도 없어, 방화벽에 빠진 IP가 응답되는 동안 요청이 전부 실패합니다. 이런 간헐적인 실패는 연동 테스트에서는 잘 드러나지 않고 실제 트래픽에서야 드러납니다.

특정 IP에 장기간 트래픽이 없더라도 그 IP가 폐기된 것은 아닙니다. 부하분산 비율에 따라 언제든 다시 사용됩니다(F4).

아래 왼쪽 구성은 여러 진입점으로 분산된 환경에서 결제 실패를 일으킵니다. 이런 구성 때문에 발생한 결제 실패는 토스페이먼츠가 정상 동작을 보장하기 어렵습니다.

방화벽 제품이 DNS 기반 FQDN 객체만 지원해서 위 두 번째 행의 구성을 피할 수 없다면 애플리케이션 서버와 방화벽이 같은 resolver와 같은 TTL 정책을 쓰도록 맞춰주세요. 그래도 진입점 전환 중에는 두 시스템의 캐시가 어긋날 수 있으므로 안내된 IP 전체를 함께 등록해 두시는 편이 안전합니다(F1).

SNI는 클라이언트가 임의로 지정하는 값입니다. 방화벽이 SNI만 보고 외부로 나가는 연결을 허용하면, 내부의 악성 프로세스가 SNI를 api.tosspayments.com으로 설정한 채 다른 서버로 연결해 데이터를 반출할 수 있습니다(SNI spoofing). 그렇다고 HTTP Host 헤더를 기준으로 삼을 수도 없습니다. Host 헤더는 TLS로 암호화되어 있어 방화벽이 복호화하지 않고는 볼 수 없기 때문입니다. 그래서 IP 허용을 기본으로 하고, SNI는 보조 조건으로만 사용해주세요.

아래 세 가지를 확인해주세요. {IP} 자리에는 api.tosspayments.com에 안내된 진입점 IP를 하나씩 넣어주세요.

응답 IP의 개수와 순서는 전체 허용 IP 목록을 뜻하지 않습니다. 먼저 운영 서버가 실제로 쓰는 resolver로 조회하고, 외부 resolver를 쓸 수 있는 환경이라면 다른 resolver로도 반복 조회해 응답을 비교해주세요.

결과 예시

가맹점에서 확인할 것

• status: NOERROR: DNS 응답이 정상으로 돌아왔다는 뜻입니다.
• ANSWER SECTION의 TTL(예: 60): 이 값을 넘겨 캐시하지 않아야 합니다(D2). 무한 캐시하는 설정이 있는지 확인해주세요. TTL은 "최대"이므로 TTL보다 짧게 캐시하거나 아예 캐시하지 않는 것은 문제가 아닙니다(RFC 2181 §8). 공용 resolver에 물으면 남은 TTL이 보이므로 숫자 자체는 조회 시점에 따라 달라집니다.
• 응답에 담긴 IP가 전체 허용 IP 목록이 아닙니다. 조회 시점이나 resolver에 따라 다른 IP가 돌아올 수 있습니다. 방화벽에는 응답된 IP만이 아니라 방화벽 및 보안 프로토콜에 안내된 IP 전체가 등록돼 있어야 합니다(F1, F3).

--resolve 옵션으로 특정 IP를 강제 지정하고 도메인의 인증서와 TLS handshake가 정상인지 확인해주세요. IP 목록은 api.tosspayments.com용이므로 이 명령도 api.tosspayments.com을 호출해야 트래픽이 실제 진입점에 닿습니다. 또한 HTTPS_PROXY가 설정된 서버에서 curl은 프록시에 CONNECT를 보내고 이름 해석도 프록시가 하므로 --resolve가 무시됩니다. 그래서 아래 명령은 --proxy ""로 프록시를 거치지 않습니다. 운영 트래픽이 프록시를 거쳐 나가는 환경이라면 이 결과는 실제 경로를 반영하지 않고, 프록시를 우회하는 연결이 사내 보안 정책에 걸릴 수 있습니다. 이때는 보안팀과 협의해 프록시 장비에서 같은 항목을 확인해주세요.

결과 예시

진입점에 따라 발급 CA와 subject/issuer의 표기는 달라질 수 있습니다.

가맹점에서 확인할 것

• Connected to ... (IP) port 443: TCP 연결에 성공했습니다. 가맹점 방화벽이 이 IP로 나가는 연결을 허용했다는 뜻입니다(F1).
• subjectAltName: host "api.tosspayments.com" matched cert's "*.tosspayments.com": SAN 매치에 성공했습니다. 모든 진입점 IP에서 이 라인이 나와야 합니다(T5, T6).
• SSL certificate verify ok.: 클라이언트 신뢰 저장소에서 공인 루트까지 체인 검증을 통과했습니다(T7). 모든 IP에서 이 라인이 나와야 합니다.

응답 코드는 무시해도 됩니다. 이 진단은 TLS handshake와 인증서 검증만 확인하므로 뒤따르는 HTTP 응답(예: HTTP/2 404)과 server: 헤더는 판정 대상이 아닙니다.

실패 시 확인 지점

• Failed to connect to api.tosspayments.com port 443 → 가맹점 방화벽에 이 IP가 등록되지 않았습니다(F1, F3).
• SSL certificate problem: unable to get local issuer certificate → 신뢰 저장소에 루트 인증서가 없습니다(T7). Sectigo, Amazon 양쪽 루트가 모두 필요하고, 중간 인증서를 신뢰 저장소에 두는 방식은 피해주세요(T8).
• SSL: no alternative certificate subject name matches → --resolve에 넣은 IP가 엉뚱한 서버로 가고 있거나, 중간에 인증서를 바꿔치는 장비가 있는 경우입니다. curl은 URL이 호스트명이면 항상 SNI를 보내므로 SNI 미전송이 원인이 아닙니다.
• issuer에 공인 CA가 아닌 이름(사내 CA 등)이 보이면 가맹점 네트워크의 SSL inspection 장비가 TLS를 가로채고 있을 가능성이 큽니다. 가맹점 보안팀에 먼저 문의해주세요. 결제 API 요청에는 시크릿 키가 담긴 Authorization 헤더와 결제 정보가 들어 있으므로, 토스페이먼츠 API 트래픽은 SSL inspection 대상에서 제외하는 것을 권장합니다.

openssl s_client로 체인 검증과 hostname 검증을 함께 통과시키려면 아래 옵션을 모두 넣어주세요. -verify_hostname 없이는 hostname/SAN이 검사되지 않고, -verify_return_error 없이는 검증에 실패해도 handshake가 이어지며 verify return:1과 Verification: OK가 그대로 찍힙니다. 기준 버전은 OpenSSL 3.x이며, macOS 기본은 LibreSSL이라 옵션과 출력이 다를 수 있습니다.

결과 예시 (인증서 본문은 생략)

진입점에 따라 서버가 보내는 체인의 장수와 최상위 루트가 다를 수 있습니다.

가맹점에서 확인할 것

• Verification: OK 또는 Verify return code: 0 (ok): -verify_hostname과 -verify_return_error를 함께 넣었을 때 이 한 줄이 체인 검증과 hostname 검증을 모두 통과했다는 뜻입니다. 두 옵션을 넣지 않았다면 체인과 hostname 어느 쪽도 보장되지 않으므로 이 라인만 보고 통과로 판단하지 않도록 주의해주세요.
• depth= 줄은 서버가 보낸 장수가 아니라 가맹점 신뢰 저장소를 기준으로 재구성한 경로입니다. 신뢰 저장소에 어떤 루트/중간 인증서가 있는지에 따라 depth 수가 달라지므로 "0~2 모두 나와야 한다"는 식의 기준으로 삼지 않도록 해주세요.
• NotBefore / NotAfter: 인증서 유효 기간입니다. 만료일이 지나지 않았는지 확인해주세요.

진입점에 따라 발급 CA가 다르므로 모든 IP 사이에서 issuer/subject가 같은지는 대조하지 않아도 됩니다. 대신 같은 IP에 대해 실행한 2)와 3)의 결과가 서로 일치하는지, 그리고 모든 IP에서 아래 공통 항목이 성공했는지를 각각 확인합니다.

인증서 본문(PEM), serial number, 공개키 지문, subject의 세부 DN 표기, issuer의 중간 CA 이름, 체인의 최상위 루트는 진입점별로 달라도 정상입니다. 다만 위 공통 항목 중 하나라도 IP별로 실패하거나, 같은 IP의 2)와 3) 결과가 서로 어긋나거나, issuer에 사내 CA 등 공인 CA가 아닌 이름이 보인다면 아래 중 하나일 수 있습니다.

• 가맹점 네트워크의 SSL inspection 프록시가 TLS를 가로채고 있는 경우: 가맹점 보안팀에 먼저 문의해주세요.
• 방화벽 또는 TLS 설정이 안내된 요건(F1, T1)을 위반한 경우
• (드물게) 중간자 공격인 경우: 토스페이먼츠에 문의해주세요.

• IPv6를 도입할 때는 사전에 공지합니다. 가맹점 방화벽에 신규 IPv6 주소가 없으면 그 시점부터 실패할 수 있으니, 공지 시점에 함께 등록해주세요.
• DNSSEC을 도입할 때는 사전에 공지합니다.

토스페이먼츠는 같은 도메인을 여러 진입점으로 분산 운영합니다. 어느 진입점으로 들어가도 똑같이 통과하도록 DNS/TLS/방화벽 요건을 맞춰 두어야 결제가 실패하지 않습니다.

• DNS 부하분산(GSLB): 같은 도메인이라도 조회 시점, 위치, 부하분산 비율에 따라 응답 IP의 개수와 순서가 달라집니다.
• 다수 진입점 IP: 가맹점 방화벽에는 방화벽 및 보안 프로토콜에 안내된 IP 전체가 등록돼 있어야 합니다. 응답에 담긴 일부 IP만 등록하거나 "안 쓰는 IP"라고 삭제하면 부하분산 비율이 바뀌는 시점에 결제가 실패합니다.
• 동일한 통과 조건: 어느 진입점 IP로 들어가든 동일한 TLS 정책과 인증서 규칙을 통과해야 합니다. 진입점별로 발급 CA는 다르지만 표준 신뢰 저장소로 모두 검증됩니다. SNI 미전송이나 자체 hostname verifier가 있으면 특정 진입점으로 응답이 몰리는 시점에 실패합니다.