Neon Commerce Checkout API
The Checkout API from Neon Commerce — 3 operation(s) for checkout.
OpenAPI Specification
openapi: 3.1.0
info:
title: Account Checkout API
description: The Account API is used for managing player accounts.
version: '1'
servers:
- url: https://api.neonpay.com
security:
- GlobalApiKey: []
tags:
- name: Checkout
paths:
/checkout:
post:
summary: Create a checkout
description: 'Create a checkout. Once the checkout is created, redirect the user to the `redirectUrl`. On success, we''ll send a `purchase.completed` event to your webhook listener. On payment failure, we''ll send a `payment.failed` event to your webhook listener.
Don''t use this API if you have a Neon storefront set up. Neon storefronts handle creating checkouts on your behalf.
'
operationId: createCheckout
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCheckoutRequest'
responses:
'201':
description: The response is used to move the user into the checkout flow and can be used to track the status of a checkout.
content:
application/json:
schema:
type: object
required:
- id
- redirectUrl
- externalProvider
- token
properties:
id:
description: ID of the created checkout
type: string
token:
description: Token used to access the checkout. Must be included alongside the checkout ID.
type: string
redirectUrl:
description: URL of the checkout; redirect to this URL in the browser
type: string
example: https://checkout.neonpay.com/checkout/ct_KbWxq3yU8jZpL0vN7sM1aR4tH6gQ2dE5
externalProvider:
description: The external provider used for this checkout, if applicable
type:
- object
- 'null'
properties:
name:
type: string
description: The name of the external provider, if applicable
example: xsolla
orderId:
type:
- number
- 'null'
description: The order ID of the external provider, if applicable
example: 1234567890
'400':
$ref: '#/components/responses/BadRequest'
tags:
- Checkout
/checkout/{checkoutId}/expire:
post:
summary: Expire a checkout
description: 'Expire a checkout. This will expire the checkout corresponding to the provided checkoutId regardless of the current status.
'
operationId: expireCheckout
parameters:
- name: checkoutId
in: path
description: A valid checkout ID.
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
reason:
type: string
enum:
- item_unavailable
- price_changed
- promotion_ended
- duplicate_checkout
description: The reason provided for expiring this checkout
responses:
'200':
description: Checkout successfully expired
content:
application/json:
schema:
type: object
properties:
checkoutId:
type: string
message:
type: string
example: Checkout expired successfully
'400':
$ref: '#/components/responses/BadRequest'
'404':
description: Checkout not found
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: CHECKOUT_NOT_FOUND
enum:
- CHECKOUT_NOT_FOUND
message:
type: string
example: Checkout not found.
tags:
- Checkout
/checkout/{checkoutId}:
get:
summary: Returns a checkout's details.
description: Can be used to get the status of a particular checkout.
operationId: getCheckout
parameters:
- name: checkoutId
in: path
description: A valid checkout ID.
required: true
schema:
type: string
responses:
'200':
description: Returns the checkout object associated with the passed in id.
content:
application/json:
schema:
$ref: '#/components/schemas/Checkout'
'400':
$ref: '#/components/responses/BadRequest'
'404':
description: Checkout not found
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: CHECKOUT_NOT_FOUND
enum:
- CHECKOUT_NOT_FOUND
message:
type: string
example: Checkout not found.
tags:
- Checkout
components:
schemas:
CreateCheckoutRequest:
oneOf:
- allOf:
- $ref: '#/components/schemas/BaseCreateCheckoutRequest'
- type: object
required:
- successUrl
properties:
successUrl:
type:
- string
- 'null'
description: URL to redirect to upon successful checkout
format: uri
cancelUrl:
type: string
description: URL to redirect to upon checkout cancellation
format: uri
- allOf:
- $ref: '#/components/schemas/BaseCreateCheckoutRequest'
- type: object
required:
- returnUrl
properties:
returnUrl:
type: string
description: Default URL to redirect to if set
format: uri
CheckoutItem:
allOf:
- $ref: '#/components/schemas/BaseCheckoutItem'
- type: object
required:
- price
- priceTierCode
properties:
price:
type: number
description: Item price, in 100x the base unit of the currency; read more about prices [here](https://docs.neonpay.com/docs/currencies#currencies-in-the-api)
priceTierCode:
type:
- string
- 'null'
description: Item price tier; read more about price tiers [here](https://neonpay.readme.io/docs/pricing)
CheckoutBundleItem:
type: object
properties:
sku:
type: string
description: External identifier
name:
type: string
description: Name of item, for display in checkout
quantity:
type: integer
description: Number of this item in purchase
imageUrl:
type:
- string
- 'null'
description: Item image URL
format: uri
subtitle:
type:
- string
- 'null'
description: Item subtitle description
highlightedSubtitle:
type:
- string
- 'null'
description: Highlighted item subtitle description
required:
- sku
- name
- quantity
ErrorDetail:
type: object
required:
- source
- message
properties:
source:
type: string
description: Specific entity that caused this error
example: items.0
message:
type: string
description: Human readable description of the error for this entity (defined in `source`)
example: Item missing both price tier and price.
context:
type: object
description: Additional context about the error
additionalProperties: true
Checkout:
type: object
properties:
id:
type: string
status:
type: string
description: The status of this checkout
storeUrl:
type: string
description: The originating store's URL
example: https://shop.knightfighter.com/
isSandbox:
type: boolean
description: Whether this checkout is in sandbox mode
cancelUrl:
type: string
description: The URL the user is returned to if they exit the checkout
currency:
type: string
description: The currency of this checkout, as an ISO 4217 code
initialCurrency:
type: string
description: 'The ISO 4217 currency code that was initially displayed to the user prior to initiating this checkout, if applicable.
'
itemsSubtotalAmount:
type:
- number
- 'null'
description: Sum of all items (price × quantity), expressed as 100x the currency's base unit; see [here](https://docs.neonpay.com/docs/currencies#currencies-in-the-api) for more on currencies
example: 1499
totalExcludingTaxAmount:
type:
- number
- 'null'
description: Total amount excluding tax (total - tax), expressed as 100x the currency's base unit; see [here](https://docs.neonpay.com/docs/currencies#currencies-in-the-api) for more on currencies
example: 1499
subtotalAmount:
type:
- number
- 'null'
description: '**Deprecated:** Use `itemsSubtotalAmount` or `totalExcludingTaxAmount` instead. This field represents the total excluding tax (total - tax), expressed as 100x the currency''s base unit; see [here](https://docs.neonpay.com/docs/currencies#currencies-in-the-api) for more on currencies'
deprecated: true
example: 1499
taxAmount:
type:
- number
- 'null'
description: Tax amount, expressed as 100x the currency's base unit; see [here](https://docs.neonpay.com/docs/currencies#currencies-in-the-api) for more on currencies
example: 150
taxRate:
type:
- number
- 'null'
description: The tax rate for this checkout, expressed as a decimal value
example: 0.1
totalAmount:
type:
- number
- 'null'
description: Total amount, expressed as 100x the currency's base unit; see [here](https://docs.neonpay.com/docs/currencies#currencies-in-the-api) for more on currencies
example: 1649
accountId:
description: 'A unique identifier for the player or account **in your system** who should receive the purchased items. Neon includes this value in fulfillment webhooks so you can credit the correct user.
'
type: string
example: player_987654
minLength: 1
accountDisplayName:
description: The display name of the user's account, if available
type: string
userId:
type: string
items:
type: array
items:
$ref: '#/components/schemas/CheckoutItem'
languageLocale:
type: string
description: The user's language, in IETF BCP 47 tag
example: en-US
playerCountry:
type: string
description: The physical location of the player as an ISO 3166-1 code
example: US
initialPlayerCountry:
type: string
description: The initial physical location of the player as an ISO 3166-1 code
example: US
required:
- id
- isSandbox
- cancelUrl
- currency
- status
- items
- languageLocale
- playerCountry
- userId
- initialCurrency
- initialPlayerCountry
BaseCreateCheckoutRequest:
type: object
required:
- languageLocale
- playerCountry
- items
- accountId
- currency
properties:
items:
description: Items being purchased
type: array
minItems: 1
items:
$ref: '#/components/schemas/CreateCheckoutItem'
externalReferenceId:
description: A reference to this transaction, like an internal purchase ID
type: string
externalMetadata:
description: Metadata associated with this transaction, like analytics or server data
type:
- object
- 'null'
additionalProperties: true
storeUrl:
type: string
example: https://shop.knightfighter.com/
description: The URL of the store. Used for attribution and backlinking
format: uri
accountId:
description: 'A unique identifier for the player or account **in your system** who should receive the purchased items. Neon includes this value in fulfillment webhooks so you can credit the correct user.
'
type: string
example: player_987654
minLength: 1
accountDisplayName:
description: The display name of the user's account, if available
type: string
languageLocale:
type: string
description: The user's language, in IETF BCP 47 tag
example: en-US
playerCountry:
type: string
pattern: ^[A-Z]{2}$
description: 'The physical location of the player as an ISO 3166-1 alpha-2 code; also used to derive currency. See [International Support & Currencies](https://docs.neonpay.com/docs/currencies) for a full list of supported countries.
'
example: US
currency:
type: string
description: 'The ISO 4217 currency code that you displayed to the user prior to initiating this checkout, if applicable. See [Initiating a Checkout](https://docs.neonpay.com/docs/creating-a-checkout#currencies-and-country-codes) for more details on this field.
'
defaultPaymentMethod:
type:
- string
- 'null'
description: 'The default payment method for this checkout, if applicable. This is used to pre-select the payment method in the checkout flow.
'
hidePromoCodeInput:
type:
- boolean
- 'null'
description: Whether to hide the promo code input in checkout; defaults to false
contact:
type: object
properties:
email:
type:
- string
- 'null'
fraudMetadata:
type: object
description: 'Metadata used to help prevent fraud.
'
properties:
customer:
type: object
description: 'Metadata about the customer making a checkout.
'
properties:
creationTime:
type:
- string
- 'null'
format: date-time
description: 'The time the customer was created.
'
socialSignOnType:
type: string
description: 'The social sign-in type of the customer in game.
'
enum:
- google
- apple
- facebook
- twitter
- yahoo
- microsoft
- wechat
- github
- linkedin
- amazon
- other
platform:
type: string
description: 'The platform the customer is using.
'
enum:
- web
- ios
- android
- macos
- windows
- linux
- other
sessionCount:
type:
- integer
- 'null'
description: 'The number of sessions the customer has had in the app.
'
levelInApp:
type:
- integer
- 'null'
description: 'The level of the customer in the app.
'
followersInApp:
type:
- integer
- 'null'
description: 'The number of followers the customer has in the app.
'
isOnLatestAppVersion:
type:
- boolean
- 'null'
description: 'Whether the customer is on the latest version of the app.
'
hasLinkedSocialAccount:
type:
- boolean
- 'null'
description: 'Whether the customer has linked a social account in the app.
'
finishedGameSetup:
type:
- boolean
- 'null'
description: 'Whether the customer has finished the game setup.
'
isKnownUser:
type:
- boolean
- 'null'
description: 'Whether the customer is a known user in the app.
'
latestLoginIp:
type: object
description: 'An object of IP information.
'
properties:
ipAddress:
type:
- string
- 'null'
description: The IP address the customer logged in from
country:
type:
- string
- 'null'
description: The country the IP address is located in, as an ISO 3166-1 code
city:
type:
- string
- 'null'
description: The city the IP address is located in
region:
type:
- string
- 'null'
description: The region the IP address is located in
pricingSheetName:
type:
- string
- 'null'
BaseCheckoutItem:
type: object
properties:
sku:
type: string
description: External identifier
name:
type: string
description: Name of item, for display in checkout
quantity:
type: integer
description: Number of this item in purchase
minimum: 1
imageUrl:
type:
- string
- 'null'
description: Image URL for this item
format: uri
bundleContents:
type: array
description: Items in this bundle, if applicable
default: []
items:
$ref: '#/components/schemas/CheckoutBundleItem'
subtitle:
type:
- string
- 'null'
description: A subtitle for this item, e.g. "Best Value"
highlightedSubtitle:
type:
- string
- 'null'
description: The highlighted portion of the item subtitle, e.g. "+40%!"
taxCode:
type: string
enum:
- digital_goods
description: The tax category of this item
shouldShowSingleQuantity:
type: boolean
description: Whether to show the quantity badge in checkout if the quantity equals 1; defaults to true
required:
- sku
- name
- quantity
- bundleContents
APIError:
type: object
required:
- code
- message
properties:
statusCode:
type: number
description: The HTTP response code
example: 400
code:
type: string
description: An error code that is static and can be used for programmatic error handling
example: INVALID_ITEM_ERROR
message:
type: string
description: A human readable description of the error
example: Item missing both price tier and price.
errors:
type: array
description: A list of more detailed errors about specific errors for specific entities
items:
$ref: '#/components/schemas/ErrorDetail'
CreateCheckoutItem:
allOf:
- $ref: '#/components/schemas/BaseCheckoutItem'
- oneOf:
- type: object
required:
- price
properties:
price:
type: integer
description: Item price, in 100x the base unit of the currency; read more about prices [here](https://docs.neonpay.com/docs/currencies#currencies-in-the-api)
- type: object
required:
- priceTierCode
properties:
priceTierCode:
type: string
description: Item price tier; read more about price tiers [here](https://neonpay.readme.io/docs/pricing)
responses:
BadRequest:
description: Response for bad requests. Should note what in the request was invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
securitySchemes:
GlobalApiKey:
type: apiKey
in: header
name: X-Api-Key
description: 'Your Global API key, which spans across environments. Sandbox keys are prefixed with `gk_sandbox_`;
production keys are prefixed with `gk_`. Find your keys in the Neon dashboard.
'