Apple CONSUMPTION_REQUEST 완벽 정리: 앱 개발자가 알아야 할 것

고객이 Apple에 환불을 요청합니다. 12시간 뒤, 여러분의 서버에서 하나의 기회가 닫힙니다. 그리고 대부분의 팀은 그 기회가 열렸다는 사실조차 모릅니다.

그 기회가 바로 Apple CONSUMPTION_REQUEST입니다. App Store가 환불 요청을 검토하는 동안 여러분에게 정보를 요청할 때 보내는 알림이죠. 환불이 아닙니다. 결정도 아닙니다. 최종 환불 결정은 어느 쪽이든 Apple이 내립니다. 이 알림이 주는 것은 해당 구매에서 실제로 무슨 일이 있었는지 설명할 수 있는 제한된 기회입니다.

이를 제대로 처리하는 것은 고객 지원 문제가 아니라 백엔드 문제입니다. 알림이 도착해야 하고, 트랜잭션을 식별할 수 있어야 하며, 동의 상태를 알고 있어야 하고, 응답이 기한 안에 나가야 합니다.

이 글에서는 이 알림의 의미, Apple이 현재 요구하는 항목(필드 목록이 예전보다 훨씬 짧아졌습니다), 그리고 이를 중심으로 워크플로를 구축하는 방법을 다룹니다. 더 넓은 프로세스에 대해서는 저희 App Store 환불 관리 가이드가 전체 맥락을 잡아줍니다.

핵심 요약

• CONSUMPTION_REQUEST는 환불 검토 중에 Apple이 정보를 요청하는 것입니다. 환불 알림이 아닙니다.

• 최종 환불 결정은 Apple이 내립니다. 여러분의 응답은 여러 입력값 중 하나일 뿐입니다.

• 현재 엔드포인트는 5개 필드를 받으며 그중 3개가 필수입니다. 이전 버전의 12개에서 줄었습니다.

• 동의는 필수입니다. customerConsented가 true가 아닌 요청은 Apple이 거부합니다.

• Apple은 알림 후 12시간 이내 응답을 요구합니다.

• 기한이 짧고 알림이 아무 때나 도착하기 때문에, 이 단계는 사람이 처리하는 것보다 자동화에 더 적합합니다.

Apple CONSUMPTION_REQUEST란 무엇인가?

CONSUMPTION_REQUEST는 고객이 Apple에 환불을 요청했으며, App Store가 해당 구매에 대한 소비 정보(consumption information)를 보내달라고 요청한다는 것을 알리는 App Store Server Notification입니다.

개발자를 위한 Apple 소비 정보 요청이 존재하는 이유는 정보 격차 때문입니다. Apple은 트랜잭션, 계정, 구매 이력을 볼 수 있습니다. 하지만 앱 안에서 무슨 일이 있었는지는 볼 수 없습니다. 콘텐츠가 전달됐는지, 제대로 작동했는지, 고객이 실제로 얼마나 사용했는지 말이죠. 여러분은 볼 수 있습니다.

분명히 아닌 것 하나: 거부권이 아닙니다. 응답이 환불을 막지는 않으며, Apple은 여러 요소를 종합적으로 고려한다고 명시하고 있습니다.

Apple CONSUMPTION_REQUEST는 어떻게 작동하는가?

순서는 다음과 같습니다:

고객이 환불을 요청

↓

Apple이 요청 검토를 시작

↓

CONSUMPTION_REQUEST가 알림 엔드포인트에 도착

↓

알림을 검증하고 트랜잭션을 식별

↓

동의 여부를 확인하고 실제 사용 데이터를 수집

↓

요건이 충족되면 소비 정보를 전송

↓

Apple이 환불 결정을 내림

↓

REFUND 또는 REFUND_DECLINED가 도착하고, 상태를 업데이트

참고할 점: Apple의 현재 엔드포인트에서는 모든 상품 유형의 환불 요청이 이를 트리거할 수 있습니다. 소모품, 비소모품, 비갱신 구독, 자동 갱신 구독 모두 해당됩니다. 이전 문서와 대부분의 서드파티 글은 여전히 소모품과 자동 갱신 구독만 해당된다고 설명합니다. 핸들러가 그 기준으로 상품 유형을 필터링하고 있다면, 요청을 놓치고 있는 것입니다.

Apple은 개발자에게 어떤 정보를 요구하는가?

예전보다 적습니다. 기존 가이드 대부분이 틀리는 부분이 바로 여기이므로 정확히 짚어볼 필요가 있습니다. Apple의 현재 Send Consumption Information 엔드포인트는 5개 필드를 받습니다 — 필수 3개, 선택 2개.

두 가지 제약에서 많은 사람이 걸려 넘어집니다. deliveryStatus가 delivered가 아니면 consumptionPercentage는 0이어야 하며, 그렇지 않으면 요청이 실패합니다. 그리고 milliunits는 퍼센트가 아닙니다. 절반 소비는 50이 아니라 50000입니다.

선택 항목인 환불 선호도(refund preference)는 비교적 새로 추가된 것으로, 이해해 둘 가치가 있습니다. 전액 환불, 거절, 일할 계산 환불 중 어느 쪽을 선호하는지 표시할 수 있습니다. 이는 지시가 아니라 선호일 뿐입니다. Apple은 다른 모든 요소와 함께 이를 고려하며, 결과는 요청한 것과 다를 수 있습니다.

Apple이 일할 계산 환불을 승인하면 취소된 부분이 트랜잭션 페이로드에 담겨 돌아오므로, 권한(entitlement) 로직에서 모든 환불을 전부 아니면 전무로 처리하는 대신 부분 취소를 처리해야 할 수도 있습니다.

Apple은 왜 소비 정보가 필요한가?

Apple이 일부만 볼 수 있는 사안을 결정해야 하기 때문입니다.

Apple은 무엇을, 언제, 어떤 계정으로 구매했는지, 그 계정의 이력이 어떤지 알고 있습니다. 하지만 여러분의 서버가 코인을 전달했는지, 잠금 해제된 기능이 작동했는지, 고객이 환불을 요청하기 전에 상품을 많이 사용했는지는 알지 못합니다. 그 맥락은 여러분의 시스템에 있습니다.

CONSUMPTION_REQUEST Apple 환불 흐름은 Apple이 결정 전에 그 맥락을 끌어오는 방식입니다. 그래서 설득보다 정확성이 더 중요합니다. 이 데이터는 실제로 일어난 일을 설명하는 것이지, 여러분이 펼치는 변론이 아닙니다. 변론처럼 다루면 확실한 이득 없이 실질적인 리스크만 떠안게 됩니다.

개발자가 CONSUMPTION_REQUEST에 응답하는 방법

8단계입니다. 대부분의 작업은 요청이 도착하기 전에 이루어집니다.

1. 알림 수신

App Store CONSUMPTION_REQUEST 알림은 App Store Server Notifications V2용으로 설정한 서버 URL로 도착합니다. 그 엔드포인트가 없거나, 검증되지 않았거나, 조용히 실패하고 있다면 요청은 여러분에게 도달하지 않습니다. Apple의 App Store Server Notifications 문서에서 설정과 페이로드 형식을 다룹니다.

2. 알림 검증

알림은 서명된 JWS 페이로드로 도착합니다. 내용에 따라 어떤 조치를 취하기 전에 Apple의 인증서 체인으로 서명을 검증하고, bundle ID가 여러분의 앱과 일치하는지 확인하세요. 받은 것을 무엇이든 수락하는 검증되지 않은 엔드포인트는 다른 누군가가 여러분의 환불 로직을 조종할 수 있는 통로가 됩니다.

3. 트랜잭션 식별

디코딩된 페이로드에는 트랜잭션 식별자가 담겨 있습니다. 이를 대조할 저장된 구매 기록이 필요합니다. 기록이 없으면 조회도 불가능하고, 소비에 대해 유용한 말을 할 방법도 없습니다.

4. 트랜잭션을 올바른 사용자와 매칭

어떤 고객인지 알기 전에는 그 고객의 사용량을 설명할 수 없습니다. 그 매핑을 위해 존재하는 것이 appAccountToken입니다. 앱이 구매 시점에 첨부하는 UUID로, 알림 페이로드에 다시 담겨 돌아옵니다. 이것이 없으면 팀은 결국 타이밍과 추측에 의존해 매칭하게 되는데, 속도가 가장 중요한 바로 그 순간에 느리고 불안정한 방법입니다.

5. 적용되는 동의 요건 확인

이 부분에서 Apple은 명확합니다. 고객 데이터를 공유하기 전에 유효한 동의를 받아야 하며, 동의를 받는 것은 Apple이 아니라 여러분의 책임입니다. 알림에는 동의 플래그가 없으므로 자체 기록으로 파악해야 합니다.

고객이 동의하지 않았다면 Apple의 가이드는 아예 응답하지 않는 것입니다. 동의를 false로 설정해 요청을 보내는 것은 통하지 않습니다. App Store가 거부합니다. 또한 Apple은 App Tracking Transparency 프롬프트가 이 용도의 메커니즘이 아니라고 분명히 밝히고 있습니다. 이는 앱 안에서 별도로 수집해야 하는 동의입니다.

6. 실제 사용 정보 수집

전달 상태와 소비량을 실제 기록에서 가져오세요. 서버가 소모품 잔액을 추적하고 있다면 얼마나 사용됐는지 이미 알고 있습니다. 기능 잠금 해제가 실패했다면 로그에도 남아 있습니다. 추정하지 마세요 — 지어낸 소비 수치는 정확한 데이터를 전제로 받은 동의 하에 Apple에 부정확한 데이터를 보내는 것입니다.

7. 적절한 정보 전송

알림에 담긴 원래 트랜잭션 식별자를 사용해 소비 정보 엔드포인트로 PUT 요청을 보내 응답하세요. 보내고 잊어버리지 말고 오류 응답을 처리하세요. 유효성 검사 실패는 구체적인 오류 유형과 함께 HTTP 400을 반환하며, 아무도 확인하지 않으면 조용히 실패한 호출은 성공한 호출과 똑같아 보입니다.

8. 결과 기록

요청, 트랜잭션, 전송한 내용, 전송 시각, 그리고 Apple이 최종적으로 내린 결정을 로그로 남기세요. 이 기록이 있어야 몇 주 뒤 지원 문의에 답하고, 환불 전반의 패턴을 발견하고, 권한 상태가 올바른지 확인할 수 있습니다. 환불이 확정되면 환불 후 접근 권한을 회수하고, Apple이 나중에 결정을 번복할 경우 복원할 준비를 해두세요.

개발자가 CONSUMPTION_REQUEST를 놓치면 어떻게 되는가?

극적인 일은 아무것도 일어나지 않습니다. 그게 문제의 일부입니다.

응답을 놓친다는 것은 그 워크플로에서 Apple이 제출을 허용한 추가 정보를 제공하지 않는다는 뜻입니다. Apple은 여전히 결정을 내립니다. Apple이 이미 가진 정보만으로 환불이 승인될 수도, 거절될 수도 있습니다. 오류도, 경고도, 무언가를 건너뛰었다는 뚜렷한 신호도 없습니다.

놓치게 되는 경위는 평범합니다. 알림이 새벽 2시에 도착합니다. 핸들러를 담당하는 엔지니어가 자리에 없습니다. 식별자는 한 시스템에, 사용 데이터는 다른 시스템에 있어 트랜잭션 조회가 지연됩니다. 누군가 월요일에 그것을 발견하지만, 기한은 한참 전에 지났습니다.

수동 CONSUMPTION_REQUEST 처리가 어려운 이유

이 워크플로의 모든 제약은 수동 처리와 반대 방향을 가리킵니다.

알림은 24시간 내내 도착합니다. 기한은 12시간입니다. 각 요청마다 트랜잭션 조회, 사용자 매칭, 동의 확인, 사용량 계산, 서명된 API 호출, 결과 로깅이 필요합니다. 일곱 단계, 어느 하나 흥미롭지 않고, 모두 시간 제한이 있습니다.

주 1건이면 성가신 일입니다. 하루 30건이면 누군가의 업무가 됩니다. 잘 해내도 아무것도 만들어내지 못하고, 늦으면 조용한 손실만 남기는 업무 말이죠.

자동화가 환불 워크플로를 어떻게 바꾸는가

자동화가 Apple에 대한 영향력을 주지는 않습니다. 많은 마케팅이 그 반대를 암시하기 때문에 다시 한번 강조할 가치가 있습니다. Apple의 결정은 여전히 Apple의 것입니다.

자동화가 하는 일은 여러분 쪽을 일관되게 만드는 것입니다. 알림이 모니터링되고 검증됩니다. 관련 요청이 나머지 스트림에서 분리됩니다. 트랜잭션이 계정과 매칭됩니다. 응답 데이터가 실제 기록에서 조합되고, 기한이 추적되고, 응답이 제출되고 로깅되며, 결과가 권한 업데이트로 이어집니다.

이 단계 중 어느 것도 판단을 필요로 하지 않습니다. 모두 적절한 순간에 주의를 기울이는 것이 필요할 뿐이며, 그건 사람보다 소프트웨어가 더 잘합니다.

App Store 환불 관리 소프트웨어는 무엇을 처리해야 하는가?

App Store 환불 관리 소프트웨어를 평가하고 있다면, 유용한 질문은 위에서 언급한 구체적인 공백을 메워주는지 여부입니다.

App Store Server Notifications를 모니터링하고 검증해서 이벤트가 실패하는 엔드포인트 속으로 사라지지 않게 해야 합니다. CONSUMPTION_REQUEST 이벤트는 환불 결과와 다른 처리가 필요하므로 별도로 추적해야 합니다. 수동 작업 시간이 가장 많이 들어가는 부분이므로 트랜잭션을 계정과 매칭해야 합니다. 사람들이 놓치는 기한이므로 응답 기한을 추적해야 합니다.

그 외에도: 동의 상태를 존중하는 소비 데이터 워크플로, 검색 가능한 환불 이력, 결과 추적, 부분 취소를 포함한 권한 동기화, 그리고 패턴을 보여줄 만큼 명확한 리포팅. 중요한 것은 기능 목록의 길이가 아니라 워크플로를 얼마나 빠짐없이 커버하는지입니다.

이 규칙들이 문서화된 곳

위 내용은 모두 세 가지 Apple 자료에서 다룹니다. 직접 읽어보세요. 이 영역은 최근에 변경됐고, 많은 2차 콘텐츠가 이전 버전의 API를 설명하고 있습니다.

Send Consumption Information — 현재 엔드포인트입니다. 동의 요건, 12시간 기한, 5개 필드 요청 본문, 그리고 소비 정보가 모든 상품 유형에 적용된다는 사실을 다룹니다. 표준 In-App Purchase라면 이것을 기준으로 구축해야 합니다.

App Store Server Notifications — 알림이 백엔드에 도달하는 방식, 서명된 페이로드 형식, 그리고 CONSUMPTION_REQUEST, REFUND, REFUND_DECLINED를 포함한 알림 유형을 다룹니다.

Send Consumption Information V1 — 이전 엔드포인트로, 일부 팀이 여전히 연결해 둔 12개 필드 요청 본문을 사용합니다. 해당 페이지의 Apple 자체 안내는 표준 In-App Purchase를 현재 엔드포인트로 안내하고, V1은 Advanced Commerce API를 사용하는 구매로 범위를 한정합니다. 여러분의 연동이 어느 쪽에 있는지 파악하는 데 유용할 뿐, 구축 대상은 아닙니다.

마치며

CONSUMPTION_REQUEST는 Apple의 환불 결정이 아닙니다. 여러분의 시스템은 알고 Apple은 모르는 것을 Apple에 알려줄 수 있는, 짧고 시간이 정해진 기회입니다.

이를 안정적으로 처리하는 워크플로에는 검증된 알림 엔드포인트, 식별 가능한 트랜잭션, 매핑 가능한 고객, 실제로 수집한 동의, 실제 사용 데이터, 기한 내 응답, 그리고 이후 권한을 업데이트할 수 있을 만큼 잘 기록된 결과가 필요합니다.

이 글을 읽고 한 가지만 한다면, 여러분의 연동이 어떤 엔드포인트를 호출하는지 확인하세요. 표준 In-App Purchase에 대해 여전히 V1 경로로 12개 필드를 보내고 있다면, 그것이 가장 먼저 메워야 할 공백입니다.

환불 볼륨이 수동 처리 범위를 넘어섰다면

환불 활동이 잦아져서 알림을 손으로 지켜보는 것이 더 이상 현실적이지 않다면, 전용 시스템이 이벤트를 모니터링하고, 기한 내에 응답을 준비해 제출하고, 결과를 추적하고, 권한을 동기화된 상태로 유지할 수 있습니다. RefundSensor는 그 워크플로에서 개발자 쪽을 자동화합니다. Apple의 결정이 아니라, 여러분이 책임지는 부분만요.