읽기 전용 Paddle API 키를 붙여넣어 소프트웨어 및 SaaS 판매, 환불, 세금을 제품별·국가별로 가져옵니다.

Paddle은 앱 스토어 밖에서 판매하는 소프트웨어(데스크톱 앱, 웹 앱, SaaS 요금제, 라이선스)의 merchant of record입니다. OAuth 대신 읽기 전용 API 키 하나로 연결합니다. Paddle 대시보드에서 키를 만들고 Revenue Sensor에 붙여넣은 뒤, 동기화할 Paddle 제품을 선택하면 됩니다. 키는 암호화되어 저장되며 저희 서버 밖으로 나가지 않습니다. Paddle 로그인 정보는 전혀 사용되지 않습니다.

시작하기 전에

판매를 추적하려는 판매자 계정의 Paddle 대시보드 접근 권한과 Developer tools에서 API 키를 만들 수 있는 권한.
라이브 계정과 샌드박스 중 무엇을 원하는지 정해 두세요. Paddle은 각각 별도의 키를 발급하며, 어느 쪽을 읽을지는 키가 결정합니다. 그 외에 선택할 것은 없습니다.

읽기 전용 API 키 만들기

1
Developer tools 열기
Paddle 대시보드에서 Developer tools → Authentication으로 이동해 새 API 키를 만듭니다. "Revenue Sensor"처럼 나중에 알아볼 수 있는 이름을 붙이세요.
2
읽기 권한만 부여
Transactions, Adjustments, Products, Addresses의 읽기 권한을 체크합니다. Addresses는 Customers 아래에 있으며 구매자의 국가를 알려주므로, 관련 없어 보여도 그대로 두세요. 쓰기 권한은 필요 없습니다.
3
키를 한 번만 복사
Paddle은 키를 생성할 때 단 한 번만 보여줍니다. 바로 복사하세요. 잃어버렸다면 폐기하고 새로 만드세요.

계정 연결

1
키 붙여넣기
Revenue Sensor 콘솔에서 Integrations → Paddle → Connect로 이동해 API 키를 붙여넣습니다. Revenue Sensor는 키의 접두사로 라이브 키와 샌드박스 키를 구분하고, 계속 진행하기 전에 어느 쪽을 사용할지 확인해 줍니다.
2
제품 선택
동기화 단위는 스토어 앱이 아니라 Paddle 제품입니다. 장부에 넣을 제품을 고르세요. 각 제품은 수익에서 별도의 행으로 표시되며, 앱에 속한 제품이라면 해당 앱에 매핑할 수 있습니다. 선택한 것만 가져오고, 선택한 것만 요금제에 집계됩니다.
3
첫 동기화 완료 기다리기
Paddle은 전체 기록을 보관하므로 첫 동기화에서 최대 1년 치의 결제 완료 거래와 환불을 소급해 가져옵니다. 보통 몇 분이면 끝나며, 진행 중에 페이지를 떠나도 됩니다.

가져오는 데이터

항목	비고
수익	결제 완료된 거래이며, 인보이스 발행일이 아니라 대금이 회수된 날에 기록됩니다. 제품별·일별·구매자 국가별로 세금을 제외하고 표시됩니다. Google Play가 Google 수수료를 빼기 전 총액으로 표시되는 것과 마찬가지로 Paddle 수수료도 차감되지 않습니다.
세금	Paddle은 merchant of record로서 판매세와 VAT를 징수하고 모든 품목에 이를 명시하므로, 세금은 별도로 가져오며 이 소스에서는 세금 포함 보기를 사용할 수 있습니다.
환불 및 지불 거절	승인된 환불과 지불 거절(chargeback)은 승인된 날에 수익을 줄이며, 참고용으로 환불 금액으로도 함께 기록됩니다. 취소된 지불 거절은 금액을 되돌립니다. 크레딧과 지불 거절 경고는 환불로 취급하지 않습니다.
국가	고객의 청구지 주소에서 가져옵니다. 국가 코드만 사용합니다.

Paddle의 모든 통화 지원

거래는 청구된 통화 그대로 가져와 다른 소스와 같은 방식으로 환산됩니다. JPY, KRW처럼 소수점이 없는 통화도 올바르게 읽히므로, 일본 판매가 실제 가치의 100분의 1로 보고되는 일은 없습니다.

실시간 업데이트(선택 사항)

Revenue Sensor는 Paddle을 30분마다 동기화합니다. 새 판매나 환불을 1~2분 안에 확인하고 싶다면 Paddle의 알림 대상(notification destination)을 저희 쪽으로 지정하세요. 숫자는 여전히 Paddle API에서 가져오며, 웹훅은 더 빨리 동기화하라는 신호일 뿐입니다.

1
웹훅 URL 복사
Revenue Sensor 콘솔에서 Paddle 연결을 엽니다. "Real-time updates" 패널에 이 연결 전용 URL이 표시되니 복사하세요.
2
알림 대상 만들기
Paddle에서 Developer tools → Notifications → New destination으로 이동합니다. URL을 붙여넣고 유형으로 Webhook을 선택한 뒤 transaction, adjustment, subscription 이벤트를 구독합니다.
3
시크릿 저장
알림 대상을 만들면 Paddle이 서명 시크릿을 보여줍니다. 이를 "Real-time updates" 패널에 붙여넣고 저장하세요. 저희는 이 값으로 모든 전송을 검증하고 서명되지 않은 것은 버립니다. 시크릿은 암호화되어 저장되며 다시 표시되지 않습니다.

문제 해결

키가 거부됨: Transactions, Adjustments, Products, Addresses 네 가지 모두에 읽기 권한이 있는지 확인하세요. Addresses가 없는 키는 기본 검사는 통과하지만 동기화에서 실패합니다.
제품이 표시되지 않음: 키가 다른 계정의 것이거나, 라이브를 기대했는데 샌드박스 키인 경우(또는 그 반대)입니다. 키의 접두사로 어느 쪽인지 알 수 있습니다.
판매가 누락됨: 결제가 완료된 거래만 가져옵니다. 초안, 미결제 인보이스, 취소된 거래는 아직 수익이 아닙니다.
수익이 정산액보다 높아 보임: 정상입니다. 세금은 별도로 관리되고 Paddle 수수료는 차감되지 않으므로, 이 수치는 Paddle 몫을 빼기 전의 총수익입니다.
환불이 판매와 다른 날에 표시됨: 환불은 승인된 날에 기록되며 원래 구매일로 소급되지 않습니다.

Paddle 연결