Accept Payments with Neon in iOS Games

Neon makes it easy for mobile game developers to offer real-money purchases through a secure, localized, and flexible checkout experience, which can now be called from inside your game app. This guide walks you through how to initiate a Neon checkout flow from your iOS game using the Neon API.

There are two entry points to Neon from your game. You can either link to your storefront to let users browse your full suite of product offers (including web exclusives), or you can create a checkout for a specific offer or set of offers via our API.

Link to your storefront from your game

You can always link directly to your storefront in the user's browser via your production storefront URL. This will open the logged-out storefront experience, and the user will need to log in via your configured authentication scheme.

Alternatively, you can use our authentication API to generate a pre-authenticated storefront URL. Linking to this URL will open the logged-in storefront experience.

You can do so by calling the POST /auth/token endpoint as follows:

curl --request POST \
     --url https://api.neonpay.com/auth/token \
     --header 'X-API-KEY: <your API key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "accountId": "<account ID>",
  "accountDisplayName": "<account display name>",
  "metadata": "<metadata>"
}

Key fields:

• accountId: This is the player's account ID (a.k.a. user ID, player ID) used to identify the player in your system. This is used to fulfill the items the player purchased in the game.
• accountDisplayName: This is a display name for the player's account. This can be something like a player defined gamer tag or just their name
• metadata: This is arbitrary metadata added to the player's session. It is included in analytics events and purchase related webhooks (e.g. the externalMetadata field in purchase.completed)

See the full API reference for more details.

Start a checkout from your game

Prerequisites

Ensure that you have:

• A Neon account and access to your API key.
• A server backend to securely create Neon Checkout sessions.
• [optional] A dedicated page in your app to which the user can return after making payment. This could be the user's inventory page, the shop page, or any other acceptable landing page.

Step 1: Let Players Select Items

Your game should allow users to select which items they want to purchase. We recommend listing some items as special offers and having the buy buttons route to Neon's checkout creation. Once the user is ready to pay, you’ll initiate the checkout.

Step 2: Create a Neon Checkout Session

To start a Neon checkout, you'll need to create a Checkout object by calling POST /checkout with information about the items in the order, the player's locale and country, and the URLs to redirect them to after checkout.

Here’s a sample request:

curl --request POST \
     --url https://api.neonpay.com/checkout \
     --header 'X-API-KEY: <your API key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "items": [
    {
      "sku": "<sku>",
      "name": "<name>",
      "quantity": <quantity>,
      "imageUrl": "<url>",
      "price": <price>
    }
  ],
  "successUrl": "<success URL>",
  "cancelUrl": "<failure URL>",
  "storeUrl": "<store URL>",
  "languageLocale": "<locale>",
  "playerCountry": "<country>",
  "accountId": "<account ID>"
}

Key fields:

• items: List of item(s) being purchased.
  • sku: Unique identifier for fulfillment.
  • name: Localized name of the item.
  • quantity: Number of units.
  • price: Price in cents (100x base unit of currency).
  • Optional: imageUrl, subtitle, highlightedSubtitle.
• successUrl: Redirect after successful purchase. For the smoothest experience, set this to a deeplink to your game.
• cancelUrl: Redirect if the user cancels checkout.
• storeUrl: Redirect after Neon Pay signup.
• languageLocale: IETF BCP 47 format (e.g. en-US).
• playerCountry: ISO 3166-1 country code (e.g. US).
• accountId: Identifier used for fulfillment.
• Optional fields for fulfillment and analytics: externalReferenceId, externalMetadata.

See the API reference for more details on each field.

Step 3: Redirect to Neon Checkout

Use the redirectUrl in the checkout creation response to send the user to the Neon-hosted checkout page. From here, the user can choose their preferred payment method, securely enter their payment credentials, and complete their payment.

After checkout is completed, the user will be redirected to the successUrl you provided.

Note: current App Store guidance is to open the redirectUrl in the user's native browser, as opposed to using an in-game web view.

Step 4: Update Your Game

Once the user successfully makes payment, we'll fire a purchase.completed event with details about their purchase. You can configure a listener URL in your dashboard (note that you'll need to register listeners for both production-mode and sandbox-mode events; these can be the same).

Use the event body to fulfill the user's purchase to their in-game account. In particular, the data.purchase.accountId field matches the accountId, and the data.purchase.items matches the items, including quantity and SKU, you passed in during checkout creation.

Note: due to the asynchronous nature of webhooks, it's possible that the user will be redirected to successUrl before the webhook is fired. We recommend that your client poll your server periodically for updates, or wait for a server-originated push, before updating the user in-game.

Here's an example purchase.completed webhook:

{
  "id": "d20f0f08-694d-4798-9faf-fccd5b61ed39",
  "type": "purchase.completed",
  "version": 2,
  "isSandbox": true,
  "data": {
    "purchase": {
      "id": "1bfb9321-0013-4196-ac9c-a864ecce522f",
      "orderNumber": "KJ7Z-KJNW-BMDB",
      "checkoutId": "a50adc04-a5c7-487e-a684-4f0d539bc3d8",
      "subtotalAmount": 199,
      "taxAmount": 18,
      "taxRate": 0.08875,
      "totalAmount": 217,
      "discountAmount": null,
      "currency": "USD",
      "status": "complete",
      "externalReferenceId": null,
      "externalMetadata": null,
      "accountId": "simple_user",
      "email": "[email protected]",
      "locale": "en-US",
      "date": "2024-02-05T22:42:02.552Z",
      "fee": {
        "settlementCurrency": "USD",
        "fxRate": 1.0000,
        "feeAmount": 60,
        "netProceeds": 139
      },
      "items": [
        {
          "sku": "qty2-sku",
          "name": "Iron Shield",
          "price": 199,
          "referencePrice": 199,
          "referenceCurrency": "USD",
          "quantity": 1
        }
      ],
      "events": [
        {
          "id": "902c342b-2d1b-434b-9f38-efd1a564a666",
          "date": "2024-02-05T22:42:02.552Z",
          "type": "sale",
          "amount": 217,
          "currency": "USD"
        }
      ]
    }
  }
}