Apple App Store

PickLayer accepts signed StoreKit 2 transactions from your iOS app and uses them to fund a billing plan. There is no separate payment processor in the loop: your app makes the purchase through StoreKit, posts the resulting JWS to PickLayer, and PickLayer activates the user’s plan after verifying the signature against Apple Root CA G3 and confirming the transaction with App Store Server API.

For Stripe-based subscriptions on web and Android, see Stripe. For the cross-cutting usage and quota model, see the billing overview.

Prerequisites

• An App Store Connect account with the app set up and at least one build on TestFlight or the App Store.
• One or more in-app purchase products configured in App Store Connect — non-consumables, auto-renewing subscriptions, or non-renewing subscriptions, depending on what your billing plan represents.
• An App Store Server API key, generated under Users and Access → Integrations → App Store Server API → Keys. You will need three values from this key:
  • issuerId — UUID shown at the top of the Keys page.
  • keyId — the 10-character ID shown next to the key after download.
  • privateKey — the PEM contents of the .p8 file you downloaded (the file is single-download; store it carefully).

Setup in the PickLayer admin UI

1. Open the Billing page in the PickLayer console.

2. Scroll to External Integrations and click Add integration.

3. Set Provider to Apple App Store. Give it a Display name (free-text label, e.g. iOS production).

4. Paste the credential JSON into the Credentials JSON / token field. Use these field names:

   {
     "issuerId": "xxxx-xxxx",
     "keyId": "ABC123",
     "privateKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
     "environment": "production"
   }

   • environment is optional; valid values are production (default) and sandbox. Use sandbox for TestFlight and Xcode StoreKit testing.
   • The verifier also accepts the snake_case aliases issuer_id, key_id, private_key, and env.
   • Embed \n in the PEM string; do not paste raw line breaks inside the JSON value.

5. (Optional) Set a Webhook secret. If you provide one, every request to /external-checkout/apple must include an X-Apple-Signature header containing HMAC-SHA256(secret, JSON.stringify(body)) in hex. Requests without a valid header are rejected with 401. If you leave the field blank, only the JWS-level Apple signature is checked.

6. Set Status to Active and click Create. Credentials are stored encrypted at rest and used only to validate billing events.

7. On a Billing Plan, attach the integration by adding a funding mode of type BUILDER_CUSTOM_CHECKOUT (or USER) that references this integration. The plan’s funding mode is what links an Apple transaction to a specific plan.

iOS-side flow

1. The user taps the purchase button in your iOS app.

2. Your app calls StoreKit 2 (Product.purchase()) and unwraps the resulting Transaction. Each transaction carries a jwsRepresentation — a signed JWS string.

3. Before kicking off the StoreKit purchase, your app should have created a plan funding intent through the standard PickLayer billing API and obtained an intentId (UUID). Pass that intentId as the StoreKit appAccountToken so it ends up inside the signed payload.

4. Your app POSTs the JWS to PickLayer:

   POST https://<your-picklayer-host>/external-checkout/apple
   Content-Type: application/json
   
   { "signedPayload": "<jwsRepresentation>" }

5. PickLayer:

   • Verifies the ES256 signature on the JWS and walks the x5c certificate chain to the pinned Apple Root CA G3.
   • Extracts appAccountToken (intent ID) and transactionId from the payload.
   • Calls Apple’s App Store Server API with a JWT signed by your integration credentials to fetch the authoritative transaction record.
   • Looks up the matching PlanFundingIntent, marks it verified, credits the user’s plan wallet, and flips the user-plan assignment to funding_status = 'funded'.

6. Your app polls GET /v1/billing/readiness (or watches your usual entitlement state) to confirm activation. Expect funded: true once verification completes.

Endpoint reference

POST /external-checkout/apple

Public endpoint — no Authorization header. The Apple JWS signature is the auth: it cannot be forged without Apple’s signing key.

Headers

Request body

In production you should always send signedPayload — the intentId / transactionId-only path exists for debugging and bypasses JWS verification.

Successful response (200)

{
  "code": 200,
  "type": "success",
  "message": "Apple checkout verified",
  "data": {}
}

Error responses

Sandbox vs production

The environment field on the integration determines which App Store Server API base URL the verifier hits:

If your iOS build can target both (e.g. you need the same backend to serve TestFlight production and sandbox testers), create two separate integrations and attach them to separate funding modes.

Troubleshooting