Apple In-App Purchases

How it works

Apple takes the player's money before INVO sees the purchase. Two rules follow from that:

• • Before every purchase, ask INVO which products are available and offer only those. This is where INVO says no, before the player pays.
• • After payment, a genuine purchase is never refused for your billing. If your billing account cannot cover a purchase that Apple has already charged, the purchase is held, not lost (503 APPLE_CREDIT_PENDING). Keep it unfinished; it credits once your account is funded.

Setting it up

1. In App Store Connect: create a consumable In-App Purchase product for each currency pack, for example com.example.game.coins.100. Only consumables can buy currency.
2. In the INVO console: make sure billing is set up (see Billing).
3. In the INVO console: open the title's Apple settings and enter:
   • • the bundle id (for example com.example.game) and the app's Apple ID (the number App Store Connect shows for the app)
   • • whether you are in Apple's Small Business Program (it changes Apple's commission, which INVO uses for the proceeds estimate)
   • • each product id and the coins it gives, with a label and its US App Store price (optional, recommended)
   • • up to 10 App Review accounts: the player emails Apple's reviewers will use (see App Review)
4. Turn the Apple config on. Saving it with Apple enabled moves your title's iOS key to the Apple rail. Your iOS key then buys only through Apple; turning it off moves the key back. Other keys (web, Android, Steam) are not affected.
5. In App Store Connect: under App Store Server Notifications (Version 2), paste the notification URLs the console shows: the production console's URL as the Production Server URL, and the sandbox console's URL as the Sandbox Server URL. Refunds depend on these. Do this before adding the key in the next step: INVO refuses a key for an app with no notification URL (APPLE_NOTIFICATION_URL_MISSING).
6. In App Store Connect and the INVO console: create an In-App Purchase API key and add it to the title. It is required to sell on the live App Store, and saving it verifies your app at once (see In-App Purchase API key).

In-App Purchase API key

What it is and why INVO asks for it

The key lets INVO call Apple's App Store Server API for your app. INVO uses it to:

• • Check transactions independently. INVO can ask Apple directly about a purchase, instead of relying only on what reaches it.
• • Reconcile refunds. Every 6 hours INVO asks Apple about purchases from the last 120 days that are not yet refunded, and takes back the coins for any refund whose notification never arrived. It goes through the same refund handling as a notification, so a refund is never applied twice.
• • Verify your app self-serve. Apple accepts a key only from the App Store Connect account that owns the app, so saving the key proves ownership and verifies the app immediately, with no support ticket.

Create the key in App Store Connect

1. Sign in to App Store Connect as the Account Holder or an Admin.
2. Open Users and Access, then the Integrations tab.
3. Under Keys, choose In-App Purchase.
4. Choose Generate In-App Purchase Key (or the + button), give the key a name, and click Generate.
5. Note the Issuer ID shown above the key list and the new key's Key ID, then Download the key. App Store Connect lets you download the .p8 file only once; keep it safe until you have pasted it into INVO.

Add it in the INVO console

First save the title's Apple settings (bundle id and products), and paste INVO's notification URLs into App Store Connect (see Setting it up). Then open the In-App Purchase API key panel in the same settings and paste:

• • Issuer ID: the UUID shown above the key list, for example 57246542-96fe-1a63-e053-0824d011072a.
• • Key ID: the key's 10-character id, for example 2X9R4HXF34.
• • Private key: the full contents of the .p8 file, including the -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- lines.

Only the account owner can add, rotate or remove the key. The key belongs to one INVO title. The production console checks it against Apple's production environment and the sandbox console against Apple's sandbox, so add it to your sandbox title too if you want to try the flow there first.

What happens when you save

1. INVO checks the key with Apple before storing anything, by asking Apple to send a test notification for your bundle id. A key Apple refuses is never stored.
2. Apple accepts only a key from the App Store Connect account that owns the app, so its acceptance is the proof of ownership. The key is saved and your app is verified at once. There is nothing to wait for. The console shows APPLE_KEY_ACCEPTED: "Key accepted. Apple confirmed it belongs to this app, and the app is verified."

If another INVO title has already verified the same bundle id, the key is saved but does not verify this title; contact INVO support.

The private key is stored encrypted and is never shown again, not in the console and not in any API response. The console shows only the Issuer ID, the Key ID and when the key was last checked.

Rotate or remove the key

• • Rotate: generate a new key in App Store Connect and save it in the console. It is checked the same way and replaces the old key only once Apple accepts it. Then revoke the old key in App Store Connect.
• • Remove: remove the key in the console and INVO stops using it at once. Purchases keep verifying and crediting, and refund notifications keep working; INVO stops asking Apple directly about your transactions. If you revoke a key in App Store Connect, remove it from the console too. Selling on the live App Store requires a key, so add a new one promptly.
• • Changing the bundle id clears the key (and verification). Upload the key again for the new bundle id.

Errors when saving the key

Step 1: Get the products (backend)

Call this before every purchase, not once at launch. All Apple routes take your iOS key in X-Game-Secret-Key.

GET https://invo.network/api/currency-purchases/apple/products
Headers:
  X-Game-Secret-Key: ivsdk_<your_ios_key>

Response 200:
{
  "status":             "success",
  "bundle_id":          "com.example.game",
  "can_sell":           true,
  "unavailable_reason": null,
  "products": [
    {
      "product_id":         "com.example.game.coins.100",
      "coins":              100,
      "label":              "Pouch of Coins",
      "price_usd":          "9.99",
      "active":             true,
      "available":          true,
      "unavailable_reason": null
    }
  ]
}

• • Ask StoreKit for exactly the product_ids listed, and hide or disable any with available: false.
• • unavailable_reason is one of:
  • APPLE_NOT_VERIFIED: production has not verified your app yet (see Verification).
  • PARTNER_BILLING_NOT_SET_UP: your billing account is not set up.
  • PARTNER_RAIL_SUSPENDED: your billing account is suspended.
  • PARTNER_CREDIT_UNAVAILABLE: your prepaid balance cannot cover this product right now.
• • All four are fixed by you in the console, never by the player. Show a plain "not available right now".

Step 2: Buy with StoreKit (app)

Buy the product with StoreKit 2. Optionally set an appAccountToken (a UUID you choose for the player) and send the same value to INVO; INVO then refuses the transaction for any other player. Listen to Transaction.updates from app launch: that is where StoreKit redelivers transactions you left unfinished.

Swift (StoreKit 2)

import StoreKit

final class CoinStore {
    private var updates: Task<Void, Never>?

    // Start at app launch. StoreKit redelivers unfinished transactions here.
    func start() {
        updates = Task {
            for await result in Transaction.updates {
                if case .verified(let tx) = result { await deliver(tx) }
            }
        }
    }

    // productIds come from YOUR backend, which called GET /apple/products
    // and kept only products with available: true.
    func buy(productId: String, playerToken: UUID) async throws {
        guard let product = try await Product.products(for: [productId]).first
        else { return }

        let result = try await product.purchase(options: [.appAccountToken(playerToken)])
        if case .success(.verified(let tx)) = result {
            await deliver(tx)
        }
        // .pending, .userCancelled: nothing to do yet.
    }

    private func deliver(_ tx: Transaction) async {
        // YOUR backend forwards this to INVO's /apple/verify-purchase.
        // Your backend passes INVO's "finish" flag back to the app.
        let answer = try? await MyGameBackend.verifyApplePurchase(
            signedTransaction: tx.jwsRepresentation)

        if answer?.finish == true {
            await tx.finish()
        }
        // finish false, or no answer at all: do NOT finish. StoreKit
        // redelivers it and your backend retries. INVO credits it once.
    }
}

Purchases made with Xcode's local StoreKit testing are not signed by Apple and are never accepted. Test with an App Store sandbox account against INVO sandbox.

Step 3: Verify the purchase (backend)

Your backend sends Apple's signed transaction (Transaction.jwsRepresentation) to INVO. Call it from your server, never from the device.

POST https://invo.network/api/currency-purchases/apple/verify-purchase
Headers:
  X-Game-Secret-Key: ivsdk_<your_ios_key>
  Content-Type: application/json

Body:
{
  "player_email":       "player@example.com",
  "signed_transaction": "<Transaction.jwsRepresentation>",
  "app_account_token":  "8f14e45f-ceea-467a-9575-6b2f5f2d4c1e",   // optional
  "metadata":           { "my_player_id": "p_123" }              // optional, echoed on webhooks
}

Response 200:
{
  "status":         "credited",          // or "already_credited"
  "order_id":       "ORD_...",
  "transaction_id": "2000000123456789",
  "product_id":     "com.example.game.coins.100",
  "coins":          100,
  "balance":        "1250.00",
  "environment":    "Production",
  "test_mode":      false,
  "finish":         true
}

• player_email (required): the INVO player who receives the coins.
• signed_transaction (required): the transaction exactly as StoreKit gave it. You never send a price or a coin amount; the product mapping in the console decides the coins.
• app_account_token (optional): when sent, it must match the transaction's appAccountToken.
• metadata (optional, JSON object): echoed on purchase.completed and purchase.refunded.
• status (response): credited, or already_credited for a repeat of a transaction INVO has already credited. On a repeat, balance is null unless the call names the same player.
• test_mode (response): true for an Apple Sandbox transaction.
• finish (response): true means call Transaction.finish(). It is on every answer, including errors.

The call is idempotent on the Apple transaction. Send the same transaction as often as you like; it credits once.

Error codes

Every error has the same shape:

{
  "status":     "error",
  "error_code": "APPLE_PRODUCT_UNKNOWN",
  "message":    "...",
  "finish":     false
}

Read finish, not the code, to decide. Where finish is false, fix what the code names and the next redelivery credits.

A card purchase (/purchase-currency) sent with a key on the Apple rail answers 400 WRONG_RAIL_ENDPOINT with status: "use_apple_endpoint".

Webhooks

purchase.completed and purchase.refunded fire for Apple purchases like any other. They carry rail: "apple", channel: "ios", your metadata, and an apple block:

"rail":     "apple",
"channel":  "ios",
"metadata": { "my_player_id": "p_123" },
"apple": {
  "transaction_id":          "2000000123456789",
  "original_transaction_id": "2000000123456789",
  "product_id":              "com.example.game.coins.100",
  "environment":             "Production",
  "storefront":              "USA",
  "price":                   "9.99",
  "currency":                "USD",
  "charged_usd_estimated":   false,
  "test_mode":               false
}

• • usd_amount / charge_total_usd is what the player paid in USD. It is exact on the US storefront. On other storefronts it is the product's US price from the console, and charged_usd_estimated is true.
• • price is the per-unit price in the storefront's currency (currency).

Refunds

Verification

Sandbox testing and App Review

Billing

SDK usage (server)

TypeScript (@invonetwork/web-sdk)

// Before every purchase: offer only available products.
const { products } = await invo.appleProducts();
const offer = products.filter((p) => p.available).map((p) => p.productId);

// After StoreKit returns a verified transaction:
const result = await invo.verifyApplePurchase({
  playerEmail: "player@example.com",
  signedTransaction: jwsFromApp,        // Transaction.jwsRepresentation
  appAccountToken: playerUuid,          // optional
  metadata: { myPlayerId: "p_123" },    // optional, echoed on webhooks
});
// Pass result.finish back to the app. Errors carry finish too:
// finish true -> the app calls Transaction.finish(); false -> leave it and retry.

Python (invonetwork)

products = invo.apple_products()
offer = [p["product_id"] for p in products["products"] if p["available"]]

result = invo.verify_apple_purchase(
    player_email="player@example.com",
    signed_transaction=jws_from_app,     # Transaction.jwsRepresentation
    app_account_token=player_uuid,       # optional
    metadata={"my_player_id": "p_123"},  # optional
)
# Pass result["finish"] back to the app. Errors carry finish too:
# True -> the app calls Transaction.finish(); False -> leave it unfinished.

Good to know