Initiating a Checkout

🚧

If you use Neon to power your storefront:

Your storefront will automatically handle the initiation and launch of checkout experiences. Please skip to Updating Your Game.

🚧

If you use Neon to power your server:

You should use the serverless version to handle the initiation and launch of checkout. Please go to Serverless Integration -> Creating your checkout .

Once your user knows the items they'd like to purchase (e.g. by creating a cart), you can redirect them to Neon checkout. You'll do so by creating a Checkout object with the data needed to start the checkout process. You'll receive a redirect URL in response, which will take the user to Neon's checkout form. Once the user completes the purchase, they'll be redirected back to the successUrl you specified when creating the checkout.

Create a checkout

You can start a Neon checkout by creating a Checkout object via POST /checkout:

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": "100-gems",
      "name": "100 Gems",
      "quantity": 1,
      "imageUrl": "https://cdn.my-game.com/images/100-gems.png",
      "price": 199
    }
  ],
  "successUrl": "https://app.my-game.com/success",
  "cancelUrl": "https://app.my-game.com/cancel",
  "storeUrl": "https://shop.my-game.com",
  "languageLocale": "en",
  "playerCountry": "US",
  "currency": "USD",
  "accountId": "player_987654",
  "contact": {
    "email": "[email protected]"
  },
}
'

• items contains the list of Item objects the user wants to purchase:
  • sku is a unique code you can use to fulfill the purchase to the user's account. See Updating Your Game for more on the fulfillment process.
  • name is the display name of the item, localized to the player's preferred language.
  • quantity is the number of this item they want to purchase.
  • price is the price of the checkout, set to 100x the base unit of the currency. See Currencies for more details.
  • Optionally, you can set imageUrl to a link to an image that we can use to display the item during checkout.
  • Optionally, you can set subtitle and highlightedSubtitle to display additional information about the item.
• successUrl, cancelUrl, and storeUrl are links to your storefront that the user can be redirected to.
  • successUrl is the URL the user is sent to once they successfully complete the checkout.
  • cancelUrl is the URL the user is sent to if they decide to cancel the checkout at any point.
  • storeUrl is the URL the user is directed to after signing up for a Neon Pay account.
• languageLocale and playerCountry are used to geo-locate the user and offer the appropriate translations and payment methods.
  • languageLocale is an IETF BCP 47 tag, e.g. en-US, that's used to show the correct language for all text in the checkout form.
  • playerCountry is an ISO 3166-1 country code, e.g. US, that's used to show the correct payment methods for the user, and also to ensure that the user's input payment method originates from the same country they are physically in.
• currency is the ISO 4217 currency code of this checkout. It must match the currency of the country (see list here).
• accountId is unique identifier for the player or account within your own game or platform (e.g. player-1234). Neon uses this to know which of your players should receive the purchased item after checkout. This is not your Neon account ID. See Updating Your Game for more on the fulfillment process.
• Some fields are optional:
  • You can set externalReferenceId and externalMetadata for use in the fulfillment process. Neon includes them in the purchase completion and in analytics events, but otherwise doesn't make use of them.
  • You can set contact to prefill the customer’s email address at checkout.

Redirect the user to checkout

On success, the API returns a redirectUrl, which you can redirect the user to:

const response = await fetch("https://api.neonpay.com/checkout", { method: "POST", body: ... });

if (!response.ok) {
  // handle errors
}

const data = await response.json();

window.location.href = data.redirectUrl;

Currencies and country codes

You must pass in a valid ISO 3166-1 country code as playerCountry to create a checkout. You should also pass in a valid ISO 4217 currency code as currency. These two fields serve different purposes:

• In addition to the purposes described above, playerCountry is used as the player's billing country. We currently only support one currency per country, and the user must be shown, and charged in, that currency. You can see each supported country's expected currency here.
• You can use currency to validate that the currency you show to the user before starting a checkout is the same currency Neon uses. In case of a mismatch, Neon returns an error with the expected currency.

See International Support for a list of the countries Neon supports, and which currencies we support in each.