Skip to main content

In-App Purchase Callbacks

This document describes the callback handling for iOS In-App Purchases (IAP) in our system. The system handles server-side notifications from App Store Server.

Server Notifications​

Endpoint: POST /api/v1/iap/callback

Request Parameters:

{
    "signedPayload": "xxx.yyy.zzz"
}

Notification Types and Processing​

1. New Subscription (SUBSCRIBED)​

Initial Buy​

  • Creates new VIP subscription record
  • Sets start date to current time
  • Sets expiration date based on package duration
  • Sets status to ONGOING
  • Handles free trial if applicable
    • Sets is_free = true
    • Uses trial duration
    • Sets type to FREE_TRIAL

Resubscribe​

  • Creates new subscription period
  • Reactivates expired subscription
  • Updates subscription status to ONGOING

2. Renewal (DID_RENEW)​

  • Updates existing subscription
  • Extends expiration date
  • Maintains ONGOING status
  • Records renewal timestamp
  • Updates subscription history

3. Expiration Scenarios​

Normal Expiration (EXPIRED)​

  • Updates subscription status to ENDED
  • Records expiration timestamp
  • Deactivates VIP features

Failed Renewal (DID_FAIL_TO_RENEW)​

  • Marks subscription for retry
  • Updates status after grace period
  • Notifies user if needed

4. Subscription Changes​

Upgrade (DID_CHANGE_RENEWAL_PREF + UPGRADE)​

  • Processes package upgrade
  • Updates price tier
  • Adjusts benefits immediately
  • Maintains original renewal date

Downgrade (DID_CHANGE_RENEWAL_PREF + DOWNGRADE)​

  • Records downgrade request
  • Applies changes on next renewal
  • Maintains current benefits until renewal

5. Refund (REFUND)​

  • Processes refund request
  • Updates subscription status
  • Handles access revocation
  • Updates transaction records

Example Implementation Flow​

Processing App Store Server Notifications​

  1. Receive and Validate Notification

    • Receive signed payload from App Store server
    • Validate JWT signature
    • Parse notification data and type
    • Log notification receipt

  2. Process Transaction Data

    • Extract signedTransactionInfo from payload
    • Verify transaction authenticity
    • Parse transaction details
    • Identify associated user and order

  3. Handle Notification Types

    • For new subscriptions (SUBSCRIBED):

      • Initial Buy (INITIAL_BUY):
        • Create new VIP subscription record
        • Set start/end dates
        • Set status to ONGOING
        • Handle free trial if applicable
      • Resubscribe (RESUBSCRIBE):
        • Reactivate expired subscription
        • Reset subscription dates
        • Update status to ONGOING

    • For renewals (DID_RENEW):

      • Update subscription expiry date
      • Record renewal in history
      • Maintain ONGOING status
      • Update transaction records

    • For expirations:

      • Normal Expiration (EXPIRED):
        • Update status to ENDED
        • Record expiration timestamp
        • Deactivate VIP features
      • Failed Renewal (DID_FAIL_TO_RENEW):
        • Mark for retry
        • Handle grace period
        • Send user notification

    • For subscription changes (DID_CHANGE_RENEWAL_PREF):

      • Upgrade (UPGRADE):
        • Process package upgrade
        • Update price tier
        • Apply immediate benefits
        • Keep renewal date
      • Downgrade (DOWNGRADE):
        • Record downgrade request
        • Apply at next renewal
        • Keep current benefits

    • For refunds (REFUND):

      • Voluntary Cancellation (VOLUNTARY):
        • Process refund
        • Update subscription status
        • Revoke access
        • Update transaction records

  4. Update User Access

    • Update VIP status
    • Modify feature access
    • Send notifications if needed

  5. Error Handling

    • Log processing errors
    • Handle missing subscriptions
    • Manage failed transactions
    • Maintain audit trail

Error Handling​

  • Invalid Payload: Returns 422 Unprocessable Entity
  • Missing Subscription: Returns 422 with error message
  • Server Errors: Returns 500 Internal Server Error

Security Considerations​

  1. Payload Verification

    • Validates JWT signature
    • Verifies transaction authenticity
    • Checks notification source

  2. Data Integrity

    • Uses database transactions
    • Maintains audit logs
    • Prevents duplicate processing

  3. Error Logging

    • Records all notification attempts
    • Logs validation failures
    • Tracks processing errors