[공유] Google Play/Apple Store one-time purchase/consumable 상품 결제 flow

[hyoseok0]

개괄

• Google Play/Apple Store 인앱 결제 상품 종류
• 구매
  • Google Play/Apple Store 인앱 결제 flow
• 구매 후 처리
  • 환불
  • Google Play/Apple Store 스토어 결제 내역과 Cake DB 간 불일치 시 데이터 보정
• 테스트
  • sandbox 환경에서 테스트

[hyoseok0]

Google Play/Apple Store 인앱 결제 상품 정보

구분

• 상품 구분

  • 상품 접근 가능 기간 여부
  • 있음
    • subscription
  • 없음
    • one-time purchase

• subscription 구분

  • auto-renewable subscription
  • non-renewable subscription

• one-time purchase 구분

  • consumable
  • non-consumable

접근 가능 기간이 있고, 해당 기간 중 재구매가 가능한 상품은 어떤 유형에 매핑될까?

• one-time purchase 의 consumable

• 왜 one-time purchase 의 consumable?

  • 접근 가능 기간 중 재구매가 가능해야 하기 때문
  • 접근 가능 기간이 있고, renewable 되지 않으므로 non-renewable subscription 이 적합하지 않을까 생각해볼 수 있지만, 해당 유형은 접근 가능 종료 후 재구매 가능하므로 클래스 묶음 특성에 맞지 않음

• 어떻게 consumable 로 클래스 묶음 구매내역 설정?

  • consumable 은 Google Play/Apple Store 에서 접근 가능 기간 설정이 불가하므로, 해당 값을 service DB 에서 관리
  • consumable 은 consume 해야 재구매가 가능하므로, 접근 가능 기간 중 재구매가 가능하게 구매 직후 앱에서 상품 consume 처리
  • Apple 정책

• 상품 PK

  • android
  • purchaseToken
  • iOS
  • originalTransactionId
    • 참고) 1회성 구매는 구매 이후 추가 transaction 이 없어, transactionId 와 originalTransactionId 가 같아, 현재 클래스 묶음에서는 transactionId 를 PK 로 사용했습니다.

• android 상품 특성

  • 3일 이내, Google Play 에 acknowledge (service backend 에 결제정보가 반영됐다고 api 호출을 통해 Google Play backend 에 알려주기) 하지 않으면, Google 에서 환불 처리

  • one-time purchase 와 subscription 모두 동일하게 적용

  • android 의 one-time purchase 는 구매 이후 일정 기간 이후에 결제 완료되는 pending purchase 라는 상품이 있지만, 클래스 묶음 결제 정책과 상관없습니다.

  • 참고로 아래 flow 입니다.

    1. 결제 방식 중 현금 결제와 실제 구매할 오프라인 상점 선택
    2. code 를 메일과 알림으로 받음
    3. 오프라인 상점에 가서 code 와 현금 지급 후 구매 완료

• 참고

  • https://developer.android.com/google/play/billing/lifecycle
  • https://developer.apple.com/in-app-purchase/
  • https://developers.google.com/assistant/transactions/digital/dev-guide-digital-consumables#6

[hyoseok0]

구매

Google Play/Apple Store 인앱 결제

• 기본

  • Google Play/Apple Store 에 사용자가 결제 하고, App backend 의 Cake DB 에 결제 내역 동기화
  • Google Play/Apple Store 과 App backend 은 서로 상대방이 자신의 상태를 알게됐다는 걸 알아야 함

• 아키텍쳐

  • https://developer.android.com/google/play/billing/lifecycle

• 기본 결제 동기화 flow

  • https://react-native-iap.dooboolab.com/docs/guides/purchases#new-purchase-flow 상품 결제 flow.pptx

• app 에서 Cake service backend 서버로 호출하는 api

  • (1) [POST] /curriculum/bundle/{curriculumBundleId}/purchase
  • (2) [POST] /curriculum/bundle/{curriculumBundleId}/finishPurchase

• api 호출 시나리오 상세

  • 위 flow 가 정상 동작 시, 각각 1회 호출
  • api 실패 시 앱에서 처리
  • 실패 직후
    • 특정 간격으로 특정 횟수만큼 api 호출
  • 앱 상태가 background (다른 앱 구동 또는 홈 스크린)에서 foreground 로 변경 시, 저장했던 기존 event 내역으로 purchaseUpdateListener 재수행
  • billing server 에서 'request purchase' 가 정상 처리됐지만, billing server 로 'finish / consume / acknowledge' 요청이 안 오거나 정상 처리되지 않았을 때, Google Play/Apple Store 에서의 처리
  • 앱이 재기동될 때마다 purchase 성공 이벤트 발행
  • app 의 purchaseUpdateListener 수행되어 (1), (2) api 호출

• api 구현 시 유의 사항

  • DB timeout 이나 network 오류 등 일시적인 환경 문제로 api 처리 실패 시, 위와 같은 FE 나 스토어의 여러 보완 로직으로 대부분 재처리됨

  • cake service backend api 가 Google Play/Apple Store 반영 없이 부정하게 호출될 수 있어, 각 api 에서 Google Play/Apple Store 반영 여부 확인 로직 필요

  • (1) api

    • Google Play
    • FE 가 전달한 구매 정보로 Google Play 에서 구매내역 정보를 조회 하고, 해당 구매내역 여부, 상태 등으로 구매내역 검증
    • Apple Store
    • FE 가 전달한 영수증 정보(receipt) 로 Apple Store 에서 구매내역 정보를 조회하고, FE 전달 값과 비교해서 구매내역 검증
    • 참고) 사용한 Apple Store api 는 deprecated. 그러나 현재 케이크 정기권(auto-renewable subscription) 에서 동일하게 사용해서, 기존 코드를 재활용해 구현. 향후 App Store Server API 로 변경 필요

  • (2) api

    • Goole Play
    • FE 가 전달한 구매 정보로 Google Play 에서 구매내역 정보를 조회하고, Goole Play billing server 에서 처리 완료 여부 검증
    • Apple Store
    • FE 가 전달한 영수증 정보(receipt) 로 Apple Store 에서 구매내역 정보를 조회하고, Apple Store billing server 에서 처리 완료 여부 검증

  • api 가 동일 parameter으로 여러번 호출될 수 있어, 여러번 호출되더라도 중복결제를 막고 동일 response 를 return 하도록 설정

  • 동일 parameter 로 기처리됐는지 여부를 validation 체크하고, 기처리된 경우 추가 처리를 하지 않고 정상 처리됐다고 return

[hyoseok0]

구매 후 처리

환불

• 기본

  • 사용자 또는 Google Play/Apple Store 또는 개발자(Google Play 에 한정) 가 Google Play/Apple Store 에 환불 처리를 하고, App backend 는 환불 내역을 동기화

• Google Play/Apple Store 별 처리 방법

  • Google Play

  • 아래 flow 로 처리

    1. 배치에서 Google Play 에 환불 대상 조회 api 호출을 주기적으로 해서, android 구매 환불 대상 조회
       • 배치 수행 일자 기준 이전 30일(default 값)동안 발생한 환불 대상 구매내역 중 환불 처리되지 않은 내역 조회
    2. 서비스 api 로 android 구매 환불 요청
       • 잘못된 api 호출 방지를 위해 아래와 같은 보완 로직이 있습니다.
         1. 배치는 api 호출 전 MongoDB 의 log collection 에 데이터 insert 하고, _id 값을 api 로 전달
         2. api 는 전달 받은 _id 로 log 내역이 있고, 처리되지 않았을 때 환불 처리
         3. 배치는 api 응답 받은 후, log collection 에 처리 완료로 update

  • 참고)

    • 개발자가 Google Play 에 환불 처리 api 호출로 환불 처리가 가능합니다.
    • sandbox 환경에서 테스트 데이터 생성 가능
    • Google Play 에서 환불 처리 시, Google Play 에서 Google Play에 등록한 cake service api 를 호출
    • Google Play 에서 환불 요청이 거의 없고, 환불 처리 이후 바로 반영될 필요는 없어 기존 배치로도 충분할 거 같음. 향후 필요 시, cake service api 에서 환불 처리 개발 가능

  • Apple Store

  • 아래 flow 로 처리

    1. 사용자가 환불 처리 시, Apple Store 에서 스토어에 등록한 cake service api 호출
    2. cake service api 에서 환불 처리
    3. 참고)
       1. cake service api 에서 환경 이슈로 일시적으로 환불 처리가 실패할 수 있어, Apple Store 는 200 응답을 받지 않았을 때 1,12,24,48,72 시간 후에 재시도
       2. 환불 케이스가 많지 않고, 재시도를 하므로 별도의 보정 배치는 없습니다. api 로직 상 버그로 추후 재처리가 필요하면, 아래 PR 들을 참고해서 배치와 api 추가 후 재처리 가능
       3. 개발자의 환불 처리가 불가
       4. auto-renewable subscription 도 동일 flow

환불 취소

• Google Play
  • 환불 취소 없음
• Apple Store
  • 환불과 flow 가 동일하며, Apple Store api 응답 결과의 알림 유형(notificationType) 만 REFUND_REVERSED 로 다름

Google Play/Apple Store 스토어 결제 내역과 Cake DB 간 불일치 시 데이터 보정

• 기본

  • 기본 결제 동기화 flow 에서 (2) api 처리 실패 시, 배치에서 실패 내역 조회 후 임의로 (2) api 호출

• 기본 결제 동기화 flow

  • https://react-native-iap.dooboolab.com/docs/guides/purchases#new-purchase-flow 상품 결제 flow.pptx

• 언제 스토어 결제 내역과 Cake DB 간 불일치가 있을까?

  • 기본적인 동기화 flow 의 (2) api 처리가 일시적으로 실패했고, 앱과 스토어의 보완 로직으로도 api 처리가 실패하거나, 아직 보완 로직이 수행되지 않았을 때
  • 기본적인 동기화 flow 의 (2) api 로직에 버그가 있을 때
  • 버그 수정 후, 배치로 보정

• 일시적인 (2) api 처리 실패 시, 대부분 앱과 스토어 보완로직으로 해결될텐데, 추가 데이터 보정이 필요할까?

  • 결제 내역을 정확하고 빠르게 동기화하는 것은 사용자 경험과 신뢰에 있어 매우 중요하므로, backend 에서도 추가 데이터 보정

• 어떻게 해결할까?

  • 아래 flow 로 처리
    1. 배치에서 DB 조회로 (1) api 는 수행됐지만, (2) api 가 수행되지 않은 구매내역 조회
       • 기본 flow 와의 중복 처리를 막기 위해 수정일시 기준 10분 전부터 3일전까지의 불일치 데이터 조회
  2. service api 로 구매 확정 요청
     • 잘못된 api 호출 방지를 위해 아래와 같은 validation 로직 있음
       1. 배치는 api 호출 전 MongoDB 의 log collection 에 데이터 insert 하고, _id 값을 api 로 전달
       2. api 는 전달 받은 _id 로 log 내역이 있고, 처리되지 않았을 때 환불 처리
       3. 배치는 api 응답 받은 후, log collection 에 처리 완료로 update
  • 참고) Google Play/Apple Store 은 결제 관련 이벤트 발생 시, 스토어에 등록한 cake service api 를 호출. 구매 이벤트 발생 시, 스토어에서 cake service api 를 호출하면, 해당 api 를 통해 추가 보완 가능. 그러나 one-time purchase 는 subscription 과 달리 구매 이벤트 발생 시, 스토어에 등록한 service api 를 호출하지 않음
    • 스토어에서 service api 를 호출하는 이벤트 내역
      • Google 알림 api 호출 이벤트 내역
      • SubscriptionNotification
      • OneTimeProductNotification 은 구매 이후 일정 기간 이후에 결제 완료되는 pending purchase 에서 지불 또는 취소가 발생했을 때만 이벤트 발생
      • Apple 알림 api 호출 이벤트 내역

[hyoseok0]

테스트

sandbox 환경에서 테스트

• Google Play
  • 아래 조건이 맞을 때 테스트 결제
  • development-signed 앱에서
    • Google Play 로부터가 아닌 직접 다운로드 받은 앱
  • license tester ID 로 결제
  • 참고) 가이드
• Apple Store
  • 아래 조건이 맞을 때 테스트 결제
  • Apple Store 에 등록한 기기
    • 등록 가능한 UDID 개수가 제한
    • UDID 조회 방법
  • development-signed 앱에서
    • Apple Store 로부터가 아닌 직접 다운로드 받은 앱
  • sandbox Apple ID 로 결제
  • 참고) 가이드