readdle/app-store-server-api

Pure-PHP library that allows managing customer transactions using the App Store Server API and handling server-to-server notifications using the App Store Server Notifications V2

3.10.2 2024-10-22 10:45 UTC

Requires

• ext-json: *
• ext-openssl: *

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.23
• phpstan/phpstan: ^1.10
• phpunit/phpunit: ^10.5

MIT

• Pavlo Kotets

• php
• parser
• apple
• itunes
• purchase
• in app
• app store
• server-to-server
• server api
• server notifications

README

This is a zero-dependencies* pure PHP library that allows managing customer transactions using the App Store Server API and handling server-to-server notifications by providing everything you need to implement the App Store Server Notifications V2 endpoint.

_{* Zero-dependencies means this library doesn't rely on any third-party library. At the same time, this library relies on such essential PHP extensions as json and openssl}

NOTE

If you need to deal with receipts instead of (or additionally to) API, check out this library.

Installation

Nothing special here, just use composer to install the package:

composer require readdle/app-store-server-api

Usage

App Store Server API

API initialization:

try {
    $api = new \Readdle\AppStoreServerAPI\AppStoreServerAPI(
        \Readdle\AppStoreServerAPI\Environment::PRODUCTION,
        '1a2b3c4d-1234-4321-1111-1a2b3c4d5e6f',
        'com.readdle.MyBundle',
        'ABC1234DEF',
        "-----BEGIN PRIVATE KEY-----\n<base64-encoded private key goes here>\n-----END PRIVATE KEY-----"
    );
} catch (\Readdle\AppStoreServerAPI\Exception\WrongEnvironmentException $e) {
    exit($e->getMessage());
}

Performing API call:

try {
    $transactionHistory = $api->getTransactionHistory($transactionId, ['sort' => GetTransactionHistoryQueryParams::SORT__DESCENDING]);
    $transactions = $transactionHistory->getTransactions();
} catch (\Readdle\AppStoreServerAPI\Exception\AppStoreServerAPIException $e) {
    exit($e->getMessage());
}

App Store Server Notifications

try {
    $responseBodyV2 = \Readdle\AppStoreServerAPI\ResponseBodyV2::createFromRawNotification(
        '{"signedPayload":"..."}',
        \Readdle\AppStoreServerAPI\Util\Helper::toPEM(file_get_contents('https://www.apple.com/certificateauthority/AppleRootCA-G3.cer'))
    );
} catch (\Readdle\AppStoreServerAPI\Exception\AppStoreServerNotificationException $e) {
    exit('Server notification could not be processed: ' . $e->getMessage());
}

Examples

In examples/ directory you can find examples for all implemented endpoints. Initialization of the API client is separated into client.php and used in all examples.

In order to run examples you have to create credentials.json and/or notifications.json inside examples/ directory.

credentials.json structure should be as follows:

{
  "env": "Production",
  "issuerId": "1a2b3c4d-1234-4321-1111-1a2b3c4d5e6f",
  "bundleId": "com.readdle.MyBundle",
  "keyId": "ABC1234DEF",
  "key": "-----BEGIN PRIVATE KEY-----\n<base64-encoded private key goes here>\n-----END PRIVATE KEY-----",
  "orderId": "ABC1234DEF",
  "transactionId": "123456789012345"
}

In most examples transactionId is used. Please, consider that transactionId is related to environment, so if you put transactionId from the sandbox the environment property should be Sandbox as well, otherwise you'll get {"errorCode":4040010,"errorMessage":"Transaction id not found."} error.

For Order ID lookup you have to specify orderId. This endpoint (and, consequently, the example) is not available in the sandbox environment.

notification.json structure is the same as you receive it in your server-to-server notification endpoint:

{"signedPayload":"<JWT token goes here>"}

What is covered

In-app purchase history V1 (Deprecated, but left for backwards compatibility)

Get Transaction History

AppStoreServerAPI::getTransactionHistory(string $transactionId, array $queryParams)

Get a customer’s in-app purchase transaction history for your app.

In-app purchase history V2

Get Transaction History

AppStoreServerAPI::getTransactionHistoryV2(string $transactionId, array $queryParams)

Get a customer’s in-app purchase transaction history for your app.

Transaction Info

Get Transaction Info

AppStoreServerAPI::getTransactionInfo(string $transactionId)

Get information about a single transaction for your app.

Subscription status

Get All Subscription Statuses

AppStoreServerAPI::getAllSubscriptionStatuses(string $transactionId, array $queryParams = [])

Get the statuses for all of a customer’s auto-renewable subscriptions in your app.

Consumption information

Send Consumption Information

AppStoreServerAPI::sendConsumptionInformation(string $transactionId, array $requestBody)

Send consumption information about a consumable in-app purchase to the App Store after your server receives a consumption request notification.

Order ID lookup

Look Up Order ID

AppStoreServerAPI::lookUpOrderId(string $orderId)

Get a customer’s in-app purchases from a receipt using the order ID.

Refund lookup

Get Refund History

AppStoreServerAPI::getRefundHistory(string $transactionId)

Get a list of all of a customer’s refunded in-app purchases for your app.

Subscription-renewal-date extension

Extend a Subscription Renewal Date

AppStoreServerAPI::extendSubscriptionRenewalDate(string $originalTransactionId, array $requestBody)

Extends the renewal date of a customer’s active subscription using the original transaction identifier.

Extend Subscription Renewal Dates for All Active Subscribers

AppStoreServerAPI::massExtendSubscriptionRenewalDate(array $requestBody)

Uses a subscription’s product identifier to extend the renewal date for all of its eligible active subscribers.

Get Status of Subscription Renewal Date Extensions

AppStoreServerAPI::getStatusOfSubscriptionRenewalDateExtensionsRequest(string $productId, string $requestIdentifier)

Checks whether a renewal date extension request completed, and provides the final count of successful or failed extensions.

App Store Server Notifications history

Get Notification History

AppStoreServerAPI::getNotificationHistory(array $requestBody)

Get a list of notifications that the App Store server attempted to send to your server.

App Store Server Notifications testing

Request a Test Notification

AppStoreServerAPI::requestTestNotification()

Ask App Store Server Notifications to send a test notification to your server.

Get Test Notification Status

AppStoreServerAPI::getTestNotificationStatus(string $testNotificationToken)

Check the status of the test App Store server notification sent to your server.