Download the PHP package kkxdev/laravel-apple-iap without Composer

Laravel Apple In-App Purchase

A Laravel package for Apple In-App Purchase — receipt validation, App Store Server API (StoreKit 2), JWS transaction verification, and App Store Server Notifications v2.

Core IAP functionality lives in the package. Subscription state management (active/expired/grace period tracking, database records) is left to your application via Laravel events.

Requirements

Installation

Install via Composer:

The service provider and AppleIap facade are auto-discovered via Laravel's package discovery.

Publish the config file:

This creates config/apple-iap.php in your application.

Configuration

Add the following variables to your .env file:

Webhook URL

Register your notification URL in App Store Connect → Your App → App Information → App Store Server Notifications:

The default path can be changed in config:

Circuit Breaker

The circuit breaker is enabled by default and wraps all HTTP calls to Apple's APIs. It opens after 5 consecutive network failures and probes recovery after 60 seconds:

Usage

Facade

All functionality is available through the AppleIap facade:

App Store Server Notifications v2 (Recommended)

Register a webhook route and process incoming notifications:

The apple-iap.verify-notification middleware verifies the cryptographic signature of every incoming notification before your controller runs. Requests with invalid signatures receive a 400 response automatically.

processServerNotification() fires:

1. ServerNotificationReceived — always (catch-all)
2. A specific typed event matching the notification type (e.g. SubscriptionRenewed)

Listening to Events

Register listeners in your EventServiceProvider:

Example Listener

All Available Events

Every event exposes the raw decoded DTOs — your listener has everything it needs without making additional API calls.

App Store Server API (StoreKit 2)

Get Transaction History

Get Subscription Statuses

Look Up by Order ID

Get Refund History

Extend a Subscription Renewal Date

Send a Test Notification

Verifying JWS Transactions Directly

When your app sends a StoreKit 2 transaction to your server, verify it directly:

Decode renewal info:

Promotional Offer Signatures

Promotional offers let you give discounted (or free) subscription periods to existing or lapsed subscribers. Because generating the signature requires your private key, it must always be done on a secure server — never on the device.

How it works

1. Your iOS app determines the user is eligible for a promotional offer.
2. The app calls your backend to obtain a signed payload.
3. The backend calls AppleIap::generatePromotionalOfferSignature() and returns the result.
4. The iOS app passes the four values to StoreKit when initiating the purchase.
5. Apple verifies the signature; on success the promotional price applies.

Basic usage

The toArray() response contains exactly the four fields StoreKit requires:

Note: A new nonce is generated automatically on every call. Each nonce is single-use — Apple rejects duplicate nonces. Signatures expire after 24 hours.

iOS integration (StoreKit 2)

iOS integration (StoreKit 1 / SKPaymentDiscount)

Example controller

Using a dedicated Subscription Key

By default the package reuses the App Store Server API key (APPLE_IAP_KEY_ID / APPLE_IAP_PRIVATE_KEY_PATH). If you want a separate key downloaded from App Store Connect → Users and Access → Keys → In-App Purchase:

applicationUsername rules

Legacy Receipt Validation

Apple has deprecated verifyReceipt. Use the App Store Server API for new integrations.

The package automatically retries against the sandbox endpoint when Apple returns status 21007 (sandbox receipt sent to production), so you do not need to handle this case yourself.

Dependency Injection

All components are bound in the container. You can inject them directly:

Artisan Command

Verify a receipt from the command line (useful for debugging customer issues):

Error Handling

All exceptions extend Kkxdev\AppleIap\Exceptions\AppleIapException:

Circuit Breaker

The circuit breaker prevents cascading failures when Apple's APIs are experiencing issues.

States:

• Closed — normal operation; failures are counted
• Open — fail-fast; all requests throw CircuitBreakerOpenException immediately
• Half-open — one probe request is allowed through to test recovery

What counts as a failure: NetworkException only (5xx responses, connection timeouts). ApiException with 4xx status does not trip the circuit — those are caller errors.

Two independent circuit breakers run in parallel:

• receipt_validation — wraps calls to verifyReceipt
• server_api — wraps calls to the App Store Server API

To disable entirely:

Testing

The package binds all components through contracts, making them easy to swap in tests.

Faking HTTP calls

Faking events

Mocking the verifier

DTO Reference

JwsTransaction

Helper methods:

JwsRenewalInfo

Helper methods: willAutoRenew(), isInGracePeriod(), gracePeriodExpiresDateAsDateTime()

ProductType constants

Security

JWS verification uses the Apple Root CA G3 certificate embedded in the package. No certificate is fetched at runtime. The package walks the full x5c certificate chain in every JWS token and verifies:

1. Each certificate in the chain is signed by the next.
2. The chain root matches the embedded Apple Root CA G3.
3. The JWS signature is valid using the leaf certificate's public key (ES256).

This means no Apple notification or transaction token can be forged, even if an attacker controls the network.

License

MIT