결제 프로바이더를 Paddle에서 Polar로 전면 교체한 과정

결제 프로바이더를 Paddle에서 Polar로 전면 교체했다.

단순한 SDK 스왑이 아니라, 결제 흐름 전체를 다시 손대야 하는 작업이었음. 마이그레이션 SQL까지 나온 걸 보면 DB 스키마 레벨까지 영향이 있었다는 뜻이고, 문서도 두 파일이나 함께 업데이트됐다. 팀 입장에서 이런 인프라 교체는 "그냥 라이브러리 바꾸는 일"이 아니라 연쇄 파급이 어디까지 튈지 모르는 작업이라 나름 조심스러웠다.

왜 Paddle에서 Polar로?

이 부분은 공개적으로 다 얘기하기 어렵지만, 결제 프로바이더를 바꾸는 이유는 보통 몇 가지로 수렴된다.

• 수수료 구조 차이
• 특정 지역/통화 지원 범위
• 개발자 경험(DX) — API 설계, 문서 품질, SDK 완성도
• 웹훅 신뢰성 및 이벤트 모델
• 세금 처리 방식 (Paddle은 MoR, Polar는 다른 구조)

이번 케이스도 이 범주 안 어딘가였다. 중요한 건 "바꾸기로 결정했으면 얼마나 깔끔하게 바꾸느냐"였고, 그게 이번 작업의 핵심 목표였음.

변경 파일별 역할 정리

SQL 파일이 포함된 게 이번 작업의 무게를 말해준다. 기존에 Paddle 기준으로 저장되던 subscription_id, customer_id, payment_status 같은 값들이 Polar 기준으로 매핑돼야 하기 때문. 이 부분은 한 번 잘못 건드리면 기존 결제 이력이 날아가거나 상태가 꼬이는 사고로 이어진다.

-- 이런 패턴의 마이그레이션이 일반적으로 수반됨
ALTER TABLE subscriptions
  ADD COLUMN polar_subscription_id TEXT,
  ADD COLUMN polar_customer_id TEXT;

UPDATE subscriptions
  SET polar_subscription_id = paddle_subscription_id
  WHERE ...;

-- 검증 후 기존 컬럼 DROP

실제 내용이 저렇다는 게 아니라, 프로바이더 교체 마이그레이션이 보통 이런 형태로 진행된다는 거. 컬럼 추가 → 데이터 이전 → 검증 → 구 컬럼 정리 순서를 지키는 게 롤백 포인트를 확보하는 기본이다.

이런 교체 작업에서 놓치기 쉬운 것들

프로바이더 교체는 겉으로 보이는 것보다 체크리스트가 훨씬 길다.

• 웹훅 시그니처 검증 로직 — 프로바이더마다 서명 방식이 다름. Paddle은 Paddle-Signature, Polar는 다른 헤더를 씀
• 이벤트 이름 매핑 — subscription.activated 같은 이벤트명이 프로바이더마다 달라서 핸들러를 1:1로 교체할 수 없는 경우가 많음
• 테스트 환경 분리 — Sandbox/Test 모드 설정이 완전히 다른 구조
• 기존 활성 구독 처리 — 이미 결제 중인 사용자의 상태를 어떻게 이관할지
• 에러 코드 차이 — 카드 거절, 잔액 부족 등의 에러 응답 구조가 다름

이 중에서 "기존 활성 구독 처리"가 항상 제일 골치 아프다. 새로운 프로바이더로 넘어가는 시점에 구 프로바이더의 웹훅이 여전히 들어올 수 있고, 그 기간 동안 양쪽을 동시에 처리해야 하는 구간이 생긴다. 이걸 feature flag나 프로바이더 타입 컬럼으로 분기하는 게 일반적인 접근.

문서부터 먼저 고쳤다는 것

C-D-INTEGRATION.md와 STATUS.md, CLAUDE.md가 같은 커밋에 묶인 게 사실 제일 마음에 드는 부분이다. 코드 바꾸고 문서는 나중에 — 이 패턴이 팀에서 제일 자주 나오는 기술 부채다. 결제 연동 같은 복잡한 흐름일수록 문서가 실제 코드와 일치하는 시점이 짧고, 나중에 합류한 사람이 구 문서 보고 잘못된 방향으로 작업하는 사고가 생긴다.

이번엔 마이그레이션 SQL, 의존성 변경, 문서 업데이트를 한 커밋에 묶었다. 작업 단위가 커서 커밋 쪼개는 게 맞지 않냐는 의견도 있을 수 있는데, 이런 교체 작업은 "절반만 바뀐 상태"가 더 위험하다고 판단했다. 원자적으로 묶는 게 낫다.

다음 단계는 Paddle 관련 잔존 코드 정리와 구 컬럼 cleanup이 될 것 같다. 끝.

🛒 이 글과 어울리는 추천 상품

• 기계식키보드 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →
• 모니터암 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.