SILVERCLOUD / 기술 아티클
믿을 수 있는 결제 확인: 앱과 웹사이트를 위한 서버 측 체크리스트
고객이 ‘결제’를 누르고, 초록색 체크 표시를 본 뒤 앱을 닫습니다. 이 주문은 결제됐을까요? 아마도요. 하지만 돈이 걸린 일에 ‘아마도’로는 부족합니다. 체크 표시는 기기 한 대가 화면 흐름의 끝까지 갔다는 사실만 알려 줍니다. 돈이 실제로 움직였는지는 결제 사업자가 알고 있으며, 서버는 그 사실을 다른 누구도 위조할 수 없는 경로로 결제 사업자에게서 직접 확인해야 합니다.
이 체크리스트는 결제 상태, 서버 측 확인, 안전한 재시도, 환불, 대사, 테스트를 다루며 카드, 간편결제, QR 계좌이체에 모두 적용됩니다.
성공 화면은 확인이 아니다
결제를 마친 고객은 보통 ?status=success&order=1042 같은 파라미터가 붙은 채로 웹사이트나 앱으로 돌아옵니다. 이것을 증거로 삼으면 세 가지 면에서 무너집니다.
- 누구나 고칠 수 있다. 브라우저에서
failed를success로 바꾸는 데는 몇 초면 충분합니다. - 아예 로드되지 않을 수 있다. 탭을 닫거나, 신호가 끊기거나, 은행 앱이 돌아오지 않으면 결제는 성공했는데 서버는 전혀 모릅니다.
- 돈보다 먼저 도착할 수 있다. 계좌이체를 비롯한 일부 결제 수단은 고객이 할 일을 마친 뒤에도 한동안 대기 상태로 남습니다.
돌아오는 페이지에는 ‘결제를 확인하고 있습니다’를 표시하고 자체 서버에 상태를 물어야 합니다. 서버는 검증된 출처만 신뢰합니다. 주문이 결제됐는지를 클라이언트가 결정하는 일은 절대 없어야 합니다.
결제의 상태
paid 플래그 하나로 처리하지 말고 결제 상태를 명시적으로 모델링하세요.
- 생성됨: 결제 사업자에 등록됐고, 아직 결제되지 않음.
- 대기 중: 고객이 조작했거나 이체가 진행 중이며, 결과가 확정되지 않음.
- 성공: 결제 사업자가 대금을 확인함.
- 실패: 거절, 취소 또는 차단됨.
- 만료: 결제 기한이 결과 없이 지남.
- 부분 환불과 전액 환불: 성공 후 일부 또는 전부가 반환됨.
카드에는 ‘승인됐지만 매입 전’ 상태와, 이후의 분쟁(차지백)이 더해질 수 있습니다. 허용되는 상태 전이는 코드로 적어 두세요. 생성됨은 대기 중으로 갈 수 있고, 생성됨이나 대기 중은 성공, 실패, 만료로 갈 수 있으며, 성공은 부분 환불이나 전액 환불로 갈 수 있습니다. 부분 환불된 결제는 추가로 환불할 수 있지만, 생성됨이나 대기 중으로 되돌아가는 일은 없습니다. 그 밖의 변화는 버그이거나 사람이 검토해야 할 사례입니다.
검증 가능한 출처로, 서버에서 확인하라
믿을 수 있는 출처는 두 가지이며, 탄탄한 연동은 둘 다 씁니다.
서명된 웹훅. 무언가 일어나면 결제 사업자가 엔드포인트를 호출합니다. 대부분은 공유 비밀 키로 요청마다 서명하는데, 보통 원본 요청 본문(raw body)에 대한 HMAC-SHA256이며 타임스탬프를 함께 쓰는 경우가 많습니다. 핸들러는 다음을 해야 합니다.
- 받은 그대로의 원본 본문을 읽습니다. JSON을 파싱했다가 다시 직렬화하면 공백, 이스케이프, 키 순서가 바뀔 수 있고, 그러면 서명이 맞지 않습니다.
- HMAC을 계산해 헤더 값과 상수 시간(constant-time)으로 비교합니다. 일반 문자열 비교는 처음 다른 문자에서 멈추기 때문에, 그 시간 차이로 올바른 서명에 대한 정보가 새어 나갈 수 있습니다.
- 짧은 허용 범위(흔히 5분)를 벗어난 타임스탬프는 거부해, 가로챈 요청을 나중에 재전송(리플레이)할 수 없게 합니다. 허용 범위 안에서의 재전송은 이벤트 ID 중복 제거로 막습니다.
- 금액, 통화, 주문 참조를 직접 생성한 주문과 대조합니다. 유효한 서명은 누가 보냈는지를 증명할 뿐, 올바른 주문에 올바른 금액이 결제됐다는 증명은 아닙니다. 금액은 통화의 최소 단위 정수로 저장하고, 부동소수점은 쓰지 마세요.
결제 사업자의 API. 서버가 비밀 키를 사용해 결제 ID로 조회합니다. 늦거나 유실된 웹훅을 이것으로 보완할 수 있으며, 웹훅을 단순한 신호로만 보고 받을 때마다 현재 상태를 조회하는 팀도 있습니다.
API 키와 웹훅 시크릿은 서버에만 두고 앱이나 저장소에는 넣지 않으며, 서비스 중단 없이 교체할 수 있어야 합니다.
멱등성: 같은 이벤트가 두 번 와도 아무것도 바뀌지 않는다
대부분의 결제 사업자는 웹훅을 ‘최소 한 번’ 전달합니다. 엔드포인트가 타임아웃되거나 오류를 반환하면 이벤트가 다시 오고, 여러 번 오기도 합니다. 중복은 정상적인 일이므로 처리는 멱등해야 합니다.
- 이벤트 ID로 중복을 제거합니다. 처리한 이벤트 ID를 유니크 제약 아래 저장하면 재전달돼도 아무것도 바뀌지 않습니다.
- 트랜잭션 하나, 업데이트 한 번. 이벤트 ID 기록과 주문 상태 변경을 같은 데이터베이스 트랜잭션에서 처리합니다. 실패하면 둘 다 롤백되고 재시도는 깨끗한 상태에서 시작합니다. 업데이트에는 조건(
WHERE status = 'pending')을 걸어, 동시에 도착한 웹훅과 API 조회가 같은 주문을 두 번 처리하지 못하게 합니다. - 결제와 환불을 생성할 때는 멱등 키를 씁니다. 결제 사업자가 지원한다면 자체 결제 시도 ID로 키를 만드세요. 타임아웃 뒤 재시도해도 이중 청구 대신 원래 결과가 돌아옵니다. 지원하지 않는다면 고유한 참조 번호로 자체 레코드를 먼저 저장하고, 재시도 전에 그 번호로 조회하세요.
- 이벤트 순서는 뒤바뀝니다. 전달 순서는 일반적으로 보장되지 않으며, 성공 이벤트가 환불 이벤트보다 늦게 올 수 있습니다. 마지막에 온 이벤트로 덮어쓰지 말고 상태 전이 규칙을 적용하며, 확신이 없으면 현재 상태를 조회하세요.
- 백오프를 두고 재시도합니다. 타임아웃, 연결 오류, 429와 5xx 응답은 지수 백오프와 지터를 적용하고 횟수 상한을 둬서 재시도합니다. 유효성 검사 오류는 재시도하지 않습니다.
- 타임아웃은 실패가 아니라 ‘알 수 없음’입니다. 청구가 이미 됐을 수 있으니 조회로 확정하세요.
- 만료는 스케줄로 처리합니다. 작업(job)이 기한이 지나도록 대기 중인 결제를 찾아 결제 사업자에게 확인한 뒤에야 만료로 표시합니다. 만료 뒤에 도착한 성공은(계좌이체에서 실제로 일어납니다) 미리 합의한 규칙에 따라 검토 대기열로 보내거나 환불합니다.
웹훅에는 빠르게 응답하세요. 저장하고, 커밋하고, 2xx를 반환한 뒤 이메일 발송이나 출고 같은 느린 작업은 큐로 넘깁니다. 느린 핸들러는 타임아웃을 부르고, 타임아웃은 더 많은 중복을 부릅니다.
코드로 옮기면
Node.js와 PostgreSQL에서 동작하는 TypeScript 최소 핸들러입니다. 헤더 이름, 서명 인코딩, 서명 대상 문자열은 결제 사업자마다 다르지만 구조는 같습니다.
import { createHmac, timingSafeEqual } from "node:crypto";
import { Pool } from "pg";
const pool = new Pool(); // reads the PG* environment variables
const SECRET = process.env.PAYMENT_WEBHOOK_SECRET!; // server-side only, never in the app
export async function handlePaymentWebhook(req: Request): Promise<Response> {
const raw = Buffer.from(await req.arrayBuffer()); // the exact bytes, before any JSON parsing
const timestamp = req.headers.get("x-signature-timestamp") ?? "";
const received = Buffer.from(req.headers.get("x-signature") ?? "", "hex");
const expected = createHmac("sha256", SECRET).update(`${timestamp}.`).update(raw).digest();
const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300; // Unix seconds, 5 minutes
if (!fresh || received.length !== expected.length || !timingSafeEqual(received, expected)) {
return new Response("invalid signature", { status: 400 });
}
const event = JSON.parse(raw.toString("utf8"));
const db = await pool.connect();
try {
await db.query("BEGIN");
// event_id is the primary key: a repeated delivery inserts nothing.
const inserted = await db.query(
"INSERT INTO processed_events (event_id) VALUES ($1) ON CONFLICT DO NOTHING", [event.id]);
if (inserted.rowCount === 1 && event.type === "payment.succeeded") {
// Only pending -> paid, and only if amount and currency match the order.
const paid = await db.query(
`UPDATE orders SET status = 'paid', paid_at = now()
WHERE id = $1 AND status = 'pending' AND amount = $2 AND currency = $3`,
[event.data.order_id, event.data.amount, event.data.currency]);
if (paid.rowCount === 0) await db.query("INSERT INTO payment_review (event_id) VALUES ($1)", [event.id]);
}
await db.query("COMMIT");
return new Response("ok");
} catch {
await db.query("ROLLBACK");
return new Response("retry later", { status: 500 }); // the provider retries
} finally {
db.release();
}
}일치하는 대기 중 주문이 없으면(이미 결제됨, 만료됨, 금액 불일치) 이벤트는 사라지지 않고 검토 테이블로 들어갑니다.
환불, 대사, 감사 추적
환불은 결제에 연결된 별도 레코드이며 자체 상태를 가집니다. 환불도 대기 중이거나 실패할 수 있기 때문입니다. 부분 환불의 합계는 매입 금액을 절대 넘으면 안 됩니다. 환불 요청에는 멱등 키를 붙이고, 주문 상태는 결제 사업자가 확인한 뒤에만 바꾸세요.
일일 대사는 다른 모든 장치가 놓친 것을 잡아냅니다. 매일 전날의 거래 리포트나 정산 리포트를 결제 사업자에게서 받아, 각 행을 결제 사업자의 거래 ID로 자체 레코드와 맞춘 뒤 금액, 통화, 상태를 비교합니다. 흔한 불일치는 다음과 같습니다.
- 결제 사업자에는 결제됨, 우리 시스템에는 대기 중: 웹훅이 유실됐고, 돈을 낸 고객이 아직 기다리고 있습니다.
- 우리 시스템에는 결제됨, 결제 사업자에는 기록 없음: 버그나 악용이며 가장 시급합니다.
- 금액이나 상태가 다름: 기록되지 않은 부분 환불, 또는 총액·수수료·순정산액의 혼동.
불일치는 담당자와 처리 메모가 있는 불일치 대기열로 보내고, 아무도 모르게 고치는 일은 없어야 합니다. 리포트의 마감 시각도 주의하세요. 자정 무렵의 결제는 양쪽에서 서로 다른 날짜로 잡힐 수 있습니다.
감사 추적. 받은 웹훅은 헤더와 서명 검증 결과까지 원본 그대로 모두 보관해 다시 보낼 수 있게 하고, 상태 변경 이력은 추가만 가능한(append-only) 형태로 남깁니다. 어떤 상태에서 어떤 상태로, 언제, 어떤 이벤트·작업·사람 때문에 바뀌었는지를 기록합니다. 시크릿이나 전체 카드 번호는 절대 로그에 남기지 마세요. 결제 사업자가 호스팅하는 결제 페이지나 임베드형 입력 필드를 쓰면 카드 번호는 아예 서버에 닿지 않습니다.
알림은 서명 검증 실패 급증, 처리 오류, 대기 중에 멈춘 결제, 환불 실패, 대사 불일치, 성공률 급락에 울리도록 설정합니다.
정상 경로만이 아니라 실패를 테스트하라
결제 사업자의 샌드박스나 테스트 모드에서 테스트 키를 쓰고, 다음을 해 보세요.
- 웹훅을 리플레이합니다. 실제 샌드박스 이벤트를 픽스처로 저장한 뒤, 같은 이벤트를 두 번 보내고, 순서를 뒤집고, 본문 1바이트를 바꾸고, 오래된 타임스탬프를 씁니다.
- 장애를 주입합니다. 커밋한 뒤 2xx를 반환하기 전에 프로세스를 멈춥니다. 결제 사업자가 다시 보내더라도 무엇도 두 번 일어나서는 안 됩니다. 데이터베이스를 1분간 끊어 봅니다. 결제 사업자 호출에 지연을 넣어 타임아웃이 발생하게 합니다.
- 클라이언트를 엉뚱하게 씁니다. ‘결제’를 연속으로 두 번 누르고, 리디렉션 전에 브라우저를 닫고, 위조한 파라미터로 리턴 URL을 엽니다.
출시 전 체크리스트
- 주문은 검증된 웹훅이나 서버 측 API 조회를 통해서만 결제 완료가 된다.
- 서명은 원본 본문으로 상수 시간 비교를 해 검증하고, 오래된 타임스탬프는 거부한다.
- 금액, 통화, 주문 참조를 주문과 대조한다.
- 이벤트 ID는 유일하며, 중복은 부작용 없이 2xx를 반환한다.
- 이벤트 기록과 상태 변경은 한 트랜잭션에서 커밋하고, 업데이트에는 조건을 건다.
- 결제와 환불 생성에는 멱등 키 또는 자체 참조 번호 조회를 쓴다.
- 상태 전이는 코드에 정의돼 있고, 늦게 온 이벤트가 주문을 되돌리지 못한다.
- 웹훅 엔드포인트는 결제 사업자의 타임아웃 안에 응답하고, 느린 작업은 큐로 보낸다.
- 외부 호출에는 타임아웃이 있고, 재시도에는 상한과 백오프, 지터가 있다.
- 대기 중 결제는 상태 조회 후 스케줄에 따라 만료되며, 늦게 온 성공에는 정해진 처리 경로가 있다.
- 부분 환불은 매입 금액을 넘을 수 없다.
- 대사는 매일 실행되고, 모든 불일치에 담당자가 있다.
- 원본 웹훅과 상태 이력을 보관하고, 로그에는 시크릿이나 전체 카드 번호가 없다.
- 알림이 서명 실패, 처리 오류, 멈춘 결제, 대사 불일치를 모두 다룬다.
silvercloud는 외주 개발팀입니다. 파트너 기업의 앱과 웹사이트에 체크아웃과 웹훅부터 환불과 대사까지 이 계층을 구축하고, 각 파트너의 요구사항에 맞춰 결제 게이트웨이 시스템도 개발한 뒤, 파트너 팀이 운영할 수 있도록 인계합니다. 결제 연동을 계획 중이시라면 silvercloud.city에서 브리프를 보내 주세요.