결제 API 키는 비밀번호 없는 현금카드처럼 작동합니다. 키를 보낸 사람은 인보이스를 만들고, 결제 데이터를 읽을 수 있으며, 지급 기능을 사용하는 경우 잔액에서 자금을 빼낼 수도 있습니다. 따라서 결제 API 보안은 세 가지 습관으로 귀결됩니다. 키를 자사 서버에만 보관하고, API가 해당 서버의 주소에서 온 요청만 받도록 하며, 조치하기 전에 결제 내역을 다시 조회하여 모든 웹훅을 확인하는 것입니다.
이 가이드는 유로화로 정산되는 암호화폐 결제 API를 연동하고 있는 PSP, EMI, 은행 및 가맹점의 엔지니어링 책임자와 결제 책임자를 위한 것입니다. IP 주소와 CIDR 범위로 키를 제한하는 방법, 키를 어디에 보관해야 하는지, 웹훅을 확인하는 방법, 지급 기능 주변에 어떤 통제 장치가 필요한지 보여줍니다. 예시는 ItisPay API와 대시보드(데모 데이터)를 사용합니다.
주요 장면
요약
- API 키는 베어러 자격 증명입니다. GitGuardian은 2025년 공개 GitHub 커밋에서 새로 추가된 하드코딩된 시크릿을 2,865만 개로 집계했으므로, 키를 안전하게 보관하는 것뿐 아니라 키가 유출되는 상황에도 대비해야 합니다.
- IP 허용 목록은 유출된 키를 귀사 네트워크 외부에서 쓸모없게 만듭니다. 실제 아웃바운드 주소를 모두 포괄하는 가장 작은 IPv4 또는 IPv6 범위를 나열하세요. 목록이 비어 있으면 모든 주소를 허용합니다.
- 웹훅은 통지일 뿐 증명이 아닙니다. 상품을 발송하거나 계정에 입금하기 전에 키로 ID를 통해 인보이스를 다시 조회하세요.
- 지급에는 귀사 측의 사람에 의한 통제가 필요합니다. 2단계 로그인, 저장된 수취인 IBAN 및 지갑, 설정 금액을 초과하는 경우 두 번째 승인자가 여기에 해당합니다.
유출된 결제 API 키가 왜 그토록 위험한가요?#
유출된 결제 API 키가 위험한 이유는 키가 귀사 연동의 신원 그 자체이기 때문입니다. 대부분의 결제 API와 마찬가지로 ItisPay API는 Api-key라는 헤더 하나로 각 요청을 인증하며, 같은 인증이 인보이스, IBAN 또는 지갑으로의 지급, 외부 주소로의 암호화폐 출금을 모두 다룹니다. 그래서 문서에서는 키가 “클라이언트 측 코드나 공개 저장소에 노출되지 않아야 한다”고 요구합니다.
실제로 키는 코드, 로그, 채팅처럼 평범한 곳을 통해 유출됩니다. GitGuardian의 State of Secrets Sprawl 2026(2026년 3월)에 따르면, 2025년 공개 GitHub 커밋에 새로 추가된 하드코딩된 시크릿은 2,865만 개로, 1년 전보다 34% 늘었습니다. GitGuardian이 2022년에 유출된 시크릿을 다시 테스트했을 때, 그중 64% 이상이 2026년 1월에도 여전히 유효했습니다. 팀들은 키를 공개한 뒤 교체하는 것을 잊습니다.
OWASP API Security Top 10(2023)은 “Broken Authentication”을 2위로 꼽으며, “인증 메커니즘은 모든 사람에게 노출되어 있기 때문에 공격자가 쉽게 노리는 대상”이라고 경고합니다. Verizon의 2025 Data Breach Investigations Report는 자격 증명 악용을 22%로 가장 흔한 초기 공격 벡터로 꼽습니다. 비밀 문자열 하나만으로는 취약한 방어이므로, 이 가이드의 나머지 부분은 문자열이 유출된 뒤에도 유지되는 계층을 추가합니다.
IP 허용 목록은 API 키를 어떻게 보호하나요?#
IP 허용 목록(IP 화이트리스트라고도 함)은 키를 문자열뿐 아니라 장소에도 묶어 보호합니다. API는 귀사가 등록한 주소에서 온 요청일 때만 키를 받아들입니다. 개발자 노트북, CI 로그, 붙여넣기 사이트에 있는 키 사본은 작동하지 않습니다.
ItisPay 대시보드에서 이 설정은 Projects, Settings, Security 아래의 API Allowed IPs 필드에 있습니다. 이 필드는 쉼표로 구분된 단일 주소와 CIDR 블록 목록을 받습니다. 도움말 문구는 “모든 IP를 허용하려면 비워 두세요. IPv4와 IPv6를 모두 지원합니다.”라고 말합니다. 같은 목록은 API로 프로젝트를 생성할 때 api_allowed_ips 필드에서도 설정할 수 있으며, 256.256.256.256과 같은 잘못된 항목은 저장되지 않고 유효성 검사 오류로 거부됩니다.
기본값이 비어 있다는 점이 중요합니다. 새 프로젝트는 누군가 필드를 채우기 전까지 어디서든 키를 받아들이므로, 이 단계를 나중에 정리할 항목이 아니라 운영 개시 체크리스트에 넣으세요. 스크린샷의 데모 값 203.0.113.10과 198.51.100.0/24는 RFC 5737이 문서용으로 예약한 범위에서 온 것이며, 실제 목록에는 귀사의 공인 주소가 들어갑니다. 각 프로젝트는 고유한 64자리 키와 고유한 목록을 가지므로, 운영 환경은 서버 두세 대로 잠가 두고 테스트 프로젝트는 더 넓은 범위를 허용할 수 있습니다.
IPv4와 IPv6의 CIDR 범위는 어떻게 작성하나요?#
서버가 API에 접근하는 데 실제로 사용하는 모든 주소를 포괄하는 가장 작은 범위를 작성하세요. 대부분의 허용 목록 문제는 지나치게 넓은 범위나 누군가 잊어버린 아웃바운드 경로에서 발생합니다.
프리픽스 읽기#
CIDR 블록은 주소 뒤에 슬래시와 프리픽스 길이가 붙은 형태입니다. RFC 4632는 프리픽스 길이를 유효 비트 수로 정의합니다. 192.168.99.0/24는 처음 24비트를 고정하고 8비트를 자유롭게 두므로 256개 주소가 됩니다. 프리픽스에서 비트를 하나 줄일 때마다 블록 크기는 두 배가 됩니다. /32는 IPv4 주소 1개, /29는 8개, /24는 256개, /16은 65,536개입니다.
IPv6도 128비트로 같은 방식으로 작동합니다. /128은 주소 1개입니다. RFC 4291은 대부분의 IPv6 주소에서 인터페이스 부분을 64비트로 정하므로, 서버의 네트워크는 보통 /64이며 호스트는 그 안에서 주소를 바꿀 수 있습니다(예: 운영체제가 임시 주소를 생성하는 경우). 호스트의 IPv6 주소가 바뀌고 그 /64가 귀사 전용이라면, 단일 /128 대신 /64를 등록하세요. IPv6 예시용 문서 범위는 2001:db8::/32(RFC 3849)이므로, 실제 허용 목록에 절대 복사하지 마세요.
실제 아웃바운드 주소 찾기#
중요한 주소는 서버가 자신에 대해 보고하는 주소가 아니라 API가 보는 주소입니다. 클라우드 NAT 게이트웨이나 기업 방화벽 뒤에서는 많은 머신이 공인 주소 한두 개를 공유합니다. 서버리스 함수는 고정 이그레스(egress)로 라우팅하지 않는 한 공유 풀에서 나가는 경우가 많습니다. 각 환경에서 “내 IP 확인” 서비스를 호출하거나 방화벽 로그에서 출발지 주소를 읽어 확인한 다음, 정확히 그 주소를 등록하세요.
| 구성 | 등록할 항목 | 판정 |
|---|---|---|
| 고정 공인 IPv4 주소를 가진 서버 한 대 | 해당 주소를 /32 형식 또는 일반 주소로 입력 | 가능 |
| 클라우드 NAT 게이트웨이 뒤의 여러 서버 | NAT 게이트웨이의 공인 주소 | 가능 |
| 주소가 바뀌는 IPv6 호스트 | 다른 곳에서 사용하지 않는 경우에 한해 해당 호스트의 /64 | 상황에 따라 |
| 수동 테스트용 사무실 네트워크 | 제공업체가 보장하는 경우에 한해 사무실의 고정 주소 | 상황에 따라 |
| 고정 송신 주소가 없는 서버리스 함수 | 먼저 고정 주소를 가진 NAT를 거치도록 라우팅 | 불가 |
| 클라우드 제공업체의 리전 전체 대역 | 없음; 다른 고객도 포함되므로 | 불가 |
변경 사항을 저장하기 전에 새 주소를 먼저 추가하고, 배포한 뒤 트래픽이 정상적으로 흐르는지 확인한 다음에야 기존 주소를 삭제하십시오. 실제 운영 서버를 빠뜨린 목록을 저장하면 자사 결제 과정이 차단됩니다.
API 키는 어디에 보관해야 하며, 누가 볼 수 있습니까?#
키는 서버 내부의 시크릿 저장소에만 보관해야 하며, 다른 곳에 두어서는 안 됩니다. 브라우저 페이지나 모바일 앱에 포함하지 마십시오. 누구든 그 안에서 키를 읽을 수 있기 때문입니다. URL에도 넣지 마십시오. OWASP REST Security Cheat Sheet는 URL에 담긴 키가 웹 서버 로그에서 탈취될 수 있다고 경고합니다. 결제 페이지는 자사 백엔드와 통신하고, 백엔드가 결제 API와 통신해야 합니다.
키는 시작 시점에 시크릿 매니저나 환경 변수에서 불러오고, 저장소의 설정 파일에서 읽지 마십시오. GitHub에서 코드를 호스팅한다면 푸시 보호 기능을 켜십시오. GitHub 문서에 따르면 이 기능은 “푸시 시도 중 잠재적인 시크릿을 감지하면 푸시를 차단합니다.”
환경마다 키를 하나씩 사용하십시오. ItisPay의 각 프로젝트는 고유한 키와 허용 목록을 갖기 때문에, 운영용과 스테이징용 프로젝트를 분리하면 유출된 스테이징 키가 실제 결제에 영향을 줄 수 없습니다. 운영 키를 볼 수 있는 사람은 제한하십시오. EBA의 2019년 ICT 보안 가이드라인은 기술 사용자를 포함해 “need-to-know”(업무상 필요한 경우에만 접근) 원칙과 “최소 접근 권한”을 규정합니다. 2025년부터는 DORA가 대부분의 결제 업체에 이 의무를 적용하고 있습니다.
키를 교체하는 방법도 필요해지기 전에 미리 정해 두십시오. OWASP Cryptographic Storage Cheat Sheet는 일정 기간마다, 그리고 유출이 의심될 때마다 키를 교체하라고 권장하며, “키를 교체하는 데 필요한 코드와 절차가 필요해지기 전에 갖춰져 있어야 한다”고 강조합니다.
결제 API의 웹훅은 어떻게 검증해야 합니까?#
웹훅은 무언가 바뀌었다는 알림으로만 취급해야 하며, 결제를 받았다는 증거로 간주해서는 안 됩니다. 콜백 URL을 알아낸 누구든 가짜 “완료” 메시지를 보낼 수 있습니다. 안전한 방법은 자사 키로 API에서 인보이스를 다시 조회하고, API가 반환한 내용을 기준으로 처리하는 것입니다.
ItisPay 인보이스를 생성할 때 callback_url 필드가 상태 업데이트를 받을 주소를 지정합니다. 웹훅이 도착하면 그 안의 인보이스 ID를 가져와 ID로 해당 인보이스에 GET 요청을 보냅니다. 응답의 상태가 예상한 상태이고 금액이 청구한 금액과 일치할 때에만 상품을 발송하거나 계정에 입금하십시오. 문서에 따르면 이 엔드포인트는 “사용자 표시 또는 검증용”으로 결제 상태와 블록체인 세부 정보를 반환합니다.
핸들러를 깔끔하게 유지하기 위한 몇 가지 규칙은 다음과 같습니다:
- 웹훅은 HTTPS로만 수신하고, 일반 HTTP 요청은 거부하십시오.
- 핸들러를 멱등하게 만드십시오. 처리한 인보이스 ID와 상태를 저장하고, 제공업체가 알림을 다시 보내므로 중복 요청은 건너뛰십시오.
- 빠르게 응답하고 실제 작업은 큐에서 처리하여, 느린 데이터베이스 때문에 재시도가 발생하지 않도록 하십시오.
- 제공업체가 웹훅을 HMAC(RFC 2104에 정의된 키 기반 해시)으로 서명하는 경우, 서명을 다시 계산하고 상수 시간 함수로 비교하십시오. OWASP Webhook Security Cheat Sheet는 단호하게 말합니다: “==은 절대 사용하지 마십시오. 타이밍 정보가 새어 나가고 엔드포인트가 서명 오라클로 전락할 수 있습니다.” 서명된 타임스탬프가 너무 오래된 메시지는 거부하십시오.
운영 전에 테스트하십시오. ItisPay에는 실제 테스트 인보이스의 상태 변경을 시뮬레이션하는 엔드포인트와, 인보이스 또는 주문 ID에 대한 최신 웹훅을 다시 보내는 엔드포인트가 있습니다. 실제 자금 없이 재시도와 중복 처리를 확인할 수 있습니다.
지급과 대시보드 접근은 어떻게 잠가야 합니까?#
지급은 탈취된 키가 실제 금전 손실로 이어지는 지점이므로, 그 주변에 사람이 확인하는 통제 장치를 추가하십시오. ItisPay 지급 엔드포인트를 통해 법정화폐 지급은 수취인 IBAN으로, 암호화폐 지급은 지갑 주소로 전송되며, 두 경우 모두 사용 가능한 잔액에서 집행됩니다. API는 요청한 대로 실행합니다. 요청의 정당성을 판단하는 일은 사용자의 몫입니다.
자사 측에서 효과적인 통제 방법은 다음과 같습니다:
- 대시보드 또는 지급 권한이 있는 모든 사용자에게 2단계 로그인 적용. EU 결제 규정은 이미 결제 이용자에게 이 원칙을 적용하고 있습니다. 강력한 고객 인증에 관한 PSD2 규칙은 지식, 소유, 내재성(inherence) 중 최소 두 개의 독립적인 요소를 요구합니다. 같은 기준을 자사 직원에게도 적용하십시오.
- 등록된 수취인 목록. 승인된 IBAN과 지갑 주소의 목록을 직접 관리하고, 지급 서비스가 이 목록에 있는 대상으로만 전송하도록 하십시오. 새 수취인은 별도의 승인 절차를 거치며, 가능하면 냉각 기간(cooling-off period)을 두십시오.
- 기준 금액 이상에는 2차 승인자. 한 사람이 준비하고 다른 사람이 승인합니다. 금액 기준은 자사의 위험 감수 수준에 맞게 정하십시오.
- 별도의 지급 서비스. 인보이스를 생성하는 결제 서버와 분리하여, 자체 고정 주소를 허용 목록에 등록한 단일 서비스에서 지급을 실행하십시오.
| 통제 수단 | 차단하는 위협 | 판정 |
|---|---|---|
| 키에 대한 IP 허용 목록 | 유출된 키를 귀사 네트워크 외부에서 사용하는 행위 | 효과 있음 |
| 키는 서버에만 보관 | 브라우저, 앱, 저장소에서의 키 탈취 | 효과 있음 |
| 웹훅 수신 후 인보이스 재조회 | 위조된 “결제 완료” 알림 | 효과 있음 |
| 저장된 수취인 및 2차 승인자 | 공격자의 IBAN 또는 지갑으로의 지급 | 효과 있음 |
| 허용 목록 내 해킹된 서버를 상대로 위 수단 중 어느 하나만 적용하는 경우 | 이미 내부에 침투한 자에 의한 탈취 | 아니오 |
API 접근에 대해 DORA와 PCI DSS는 무엇을 요구하나요?#
EU 규제 금융사라면 이러한 통제는 선택 사항이 아닙니다. 디지털 운영 복원력법(DORA, 규정 (EU) 2022/2554)은 EBA에 따르면 2025년 1월 17일부터 적용되고 있습니다. 제9조는 기업이 “물리적 또는 논리적 접근을 제한하는 정책을 시행할 것”을 요구하며, “강력한 인증 메커니즘에 대한 정책과 프로토콜을 시행할 것”을 요구합니다. 허용 목록에 등록되고 서버에서만 사용되며 교체 계획이 있는 키는 감사인이 검토를 요청하는 종류의 증빙입니다.
PCI DSS는 암호화폐 인보이스가 아닌 카드 데이터를 다룹니다. 같은 팀이 카드 결제도 운영한다면, 요구사항 8.4.2는 카드소지자 데이터 환경에 대한 모든 접근에 다중 요소 인증(MFA)을 요구하며, 시행 시점이 정해진 버전 4.0의 향후 요구사항은 2025년 3월 31일부터 의무가 되었습니다.
결제 API 보안 통제는 어디에서 효과가 멈추나요?#
이러한 통제는 접근 경로를 좁힐 뿐입니다. 그것만으로 연동이 안전해지지는 않습니다. 웹훅 발신자의 경우에도 OWASP 웹훅 시트는 IP 허용 목록을 “추가 계층일 뿐”이라고 부르며, 그 이유는 “공유 출구 IP는 신원의 증거가 아니기 때문”입니다.
효과가 없는 경우
- 허용 목록에 있는 해킹된 서버. 공격자는 실제 키로 신뢰된 주소에서 요청을 보냅니다.
- 공유 출구 주소. 다른 테넌트가 같은 NAT 주소로 클라우드를 빠져나가면, 허용 목록으로는 그들과 귀사를 구분할 수 없습니다.
- 2단계 로그인 없이 탈취된 대시보드 비밀번호. 공격자는 API를 전혀 거치지 않습니다.
- 인보이스 필드의 개인정보. ItisPay의 공개 인보이스 엔드포인트는 키 없이도 미결제 인보이스의 전체 세부 정보를 반환하므로, 고객 이름과 이메일은 주문명에 넣지 마세요.
보안 연동을 하루 오후에 어떻게 시작하나요?#
고정된 순서를 따르면 보안 연동의 기술적 부분은 하루 오후에 마칠 수 있습니다. 아래 단계는 ItisPay를 사용하지만, 같은 순서는 어떤 제공업체에도 적용됩니다.
- 테스트 프로젝트와 별도의 운영 프로젝트를 각각 자체 키와 함께 생성하세요.
- 두 키를 모두 시크릿 매니저에 저장하고 서버에서만 불러오세요.
- 각 환경의 공개 아웃바운드 주소를 찾아 API 허용 IP에 입력하세요.
- 백엔드에서 인보이스를 생성하세요: Api-key 헤더, 고유한 order_id, EUR의 fiat_currency와 함께 fiat_amount, currency에 코인, 그리고 callback_url을 포함해 https://api.itispay.com/api/v1/invoices로 POST 요청합니다.
- 웹훅 핸들러를 구축하세요: HTTPS만 사용, 멱등성 보장, 조치 전에 ID로 인보이스를 다시 조회합니다.
- 처리하는 각 상태에 대해 웹훅 시뮬레이션을 실행한 뒤, 중복 테스트를 위해 재전송 엔드포인트를 실행하세요.
- 지급 기능은 마지막에 켜며, 저장된 수취인과 2차 승인자를 갖추세요.
빠른 시작을 원하시면, 대시보드의 Ask AI 어시스턴트가 요청 시 샘플 코드를 작성해 줍니다. 예를 들어 Api-key 헤더가 이미 포함된 Node.js 인보이스 호출 코드입니다. 이를 초안으로 취급하고, 배포 전에 필드 이름을 API 레퍼런스와 대조하세요. 계약의 기준은 생성된 예제가 아니라 레퍼런스이기 때문입니다. ItisPay는 또한 npm에 공식 TypeScript 클라이언트 @itispay/typescript-client를 게시합니다.
이를 더 넓은 결제 오케스트레이션 구성에 연결하는 경우, 각 제공업체마다 고유한 키, 허용 목록, 웹훅 핸들러를 두세요. ID로 다시 조회하는 동일한 레코드는 재무팀의 암호화폐 결제 대사에도 활용됩니다.
스테이블코인 결제를 수락하고 기술 스택을 직접 구축하지 않고 유로를 받고 싶다면, ItisPay가 API, 인보이스 발행, 웹훅, 대사를 제공하며, 결제 API 보안의 첫 번째 계층인 귀사의 IP 주소로 제한할 수 있는 키도 제공합니다. 라이선스 발급, KYC, 귀사 IBAN으로의 정산은 EU 라이선스를 보유한 CASP + 지급결제기관 파트너를 통해 진행되며, 대부분의 팀은 KYB 단계에서 첫 거래까지 일주일 미만이 걸립니다.
이 글은 정보 제공 목적으로만 작성되었으며, 법률 또는 규제 자문을 구성하지 않습니다.
