Neon Commerce Purchases API
The Purchases API from Neon Commerce — 6 operation(s) for purchases.
OpenAPI Specification
openapi: 3.1.0
info:
title: Account Purchases API
description: The Account API is used for managing player accounts.
version: '1'
servers:
- url: https://api.neonpay.com
security:
- GlobalApiKey: []
tags:
- name: Purchases
paths:
/purchases/search:
get:
summary: Search for a purchase by checkout ID or order number
operationId: findPurchase
parameters:
- in: query
allowReserved: true
name: orderNumber
schema:
type: string
description: The order number supplied to the user on checkout completion
example: ABCD-1234-EFGH
- in: query
allowReserved: true
name: checkoutId
schema:
type: string
description: A finalized checkout ID. Use this parameter to find the associated purchase
example: 97937797-8675-496f-a219-198b3b3b7f63
responses:
'200':
description: The purchase associated with the given unique ID
content:
application/json:
schema:
$ref: '#/components/schemas/Purchase'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/PurchaseNotFoundError'
tags:
- Purchases
/purchases/{purchaseId}:
get:
summary: Get a purchase
description: Get a purchase by its ID
operationId: getPurchase
parameters:
- in: path
name: purchaseId
required: true
description: The purchase ID
schema:
type: string
responses:
'201':
description: The purchase object
content:
application/json:
schema:
$ref: '#/components/schemas/Purchase'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/PurchaseNotFoundError'
tags:
- Purchases
/purchases/refunds:
get:
summary: Get all available refunds for a specific environment
operationId: getPurchaseRefunds
parameters:
- in: query
allowReserved: true
name: limit
schema:
type: number
maximum: 100
description: A limit on the number of refunds to be returned.
- in: query
allowReserved: true
name: startDate
schema:
type: string
format: date-time
description: Filter refunds created on or after this date (inclusive)
- in: query
allowReserved: true
name: endDate
schema:
type: string
format: date-time
description: Filter refunds created before this date (exclusive)
- in: query
allowReserved: true
name: startingAfter
schema:
type: string
description: 'A cursor for use in pagination. An object ID that defines your place in the list of refunds. It''ll fetch the next page of the list.
'
- in: query
allowReserved: true
name: endingBefore
schema:
type: string
description: 'A cursor for use in pagination. An object ID that defines your place in the list of refunds. It''ll fetch the previous page of the list.
'
responses:
'200':
description: List of refunds
content:
application/json:
schema:
type: object
required:
- data
- links
properties:
data:
type: array
items:
$ref: '#/components/schemas/Refund'
links:
type: object
required:
- previous
- next
properties:
previous:
type:
- string
- 'null'
description: Link to the previous page of refunds
next:
type:
- string
- 'null'
description: Link to the next page of refunds
'400':
$ref: '#/components/responses/BadRequest'
tags:
- Purchases
/purchases:
get:
summary: Get all available purchases for a specific environment
operationId: getPurchases
parameters:
- in: query
allowReserved: true
name: limit
schema:
type: number
maximum: 100
description: A limit on the number of purchases to be returned.
- in: query
allowReserved: true
name: startDate
schema:
type: string
format: date-time
description: Only returns purchases that were created after the given starting date (inclusive).
- in: query
allowReserved: true
name: endDate
schema:
type: string
format: date-time
description: Only returns purchases that were created before the given ending date (exclusive).
- in: query
allowReserved: true
name: startingAfter
schema:
type: string
description: 'A cursor for use in pagination. An object ID that defines your place in the list of purchases. It''ll fetch the next page of the list.
'
- in: query
allowReserved: true
name: endingBefore
schema:
type: string
description: 'A cursor for use in pagination. An object ID that defines your place in the list of purchases. It''ll fetch the previous page of the list.
'
responses:
'200':
description: The list of purchases corresponding to the chosen filters (if any).
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: array
items:
allOf:
- $ref: '#/components/schemas/BasePurchase'
- type: object
required:
- refunds
properties:
refunds:
type: array
items:
$ref: '#/components/schemas/Refund'
links:
type: object
required:
- previous
- next
properties:
previous:
type:
- string
- 'null'
description: 'The link associated with the query of the same service if you were to paginate to the previous page of the list. If null, then there''s no more previous data. This URL will include any date filters, if applicable.
'
next:
type:
- string
- 'null'
description: 'The link associated with the query of the same service if you were to paginate to the next page of the list. If null, then there''s no more data. This URL will include any date filters, if applicable.
'
'400':
$ref: '#/components/responses/BadRequest'
tags:
- Purchases
/purchases/{purchaseId}/refund:
post:
summary: 'Refunds a purchase.
'
description: 'Refunds are typically handled by Neon. Please reach out to Neon to determine if you qualify for access to this API.
'
operationId: refundPurchase
parameters:
- in: path
name: purchaseId
description: A valid purchase ID
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
anyOf:
- type: object
properties:
fee:
type: number
description: The amount to be removed from the fee (treated as 0 if not provided), expressed as 100x the currency's base unit; see [here](https://docs.neonpay.com/docs/currencies#currencies-in-the-api) for more on currencies
- type: object
required:
- items
properties:
items:
type: array
items:
type: object
required:
- itemId
- quantity
properties:
itemId:
type: string
description: The ID of the purchased item to be refunded
quantity:
type: number
description: The number of units of this item to be refunded; units are refunded in order of most to least discounted
responses:
'200':
description: Refund Success
content:
application/json:
schema:
$ref: '#/components/schemas/Refund'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/PurchaseNotFoundError'
tags:
- Purchases
/purchases/webhooks:
post:
summary: Subscribe to purchase lifecycle events
description: Learn more about webhooks [here](https://neonpay.readme.io/docs/webhooks-and-callbacks).
operationId: subscribeToWebhooks
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- url
properties:
url:
description: The destination URL for these webhooks
type: string
format: uri
example: https://gameUrl.com/purchase.completed
secret:
description: A shared secret used to sign every webhook
type: string
enabledEvents:
description: The set of events to which this URL will be subscribed, or `*` to subscribe to all events
type: array
default:
- '*'
items:
type: string
enum:
- '*'
- payment.failed
- purchase.completed
- refund.processed
- dispute.closed
- dispute.opened
- invoice.paid
- subscription.activated
- subscription.canceled
- subscription.expired
- checkout.abandoned
- cart.abandoned
eventVersion:
description: The version of schema to be used for calls to this URL
default: 2
type: number
responses:
'201':
description: Webhook added successfully
content:
application/json:
schema:
type: object
required:
- secret
- ids
properties:
secret:
type: string
description: The secret used to sign this callback's data, either passed in or generated by Neon
ids:
type: array
description: The created callback IDs
items:
type: string
description: The UUID of the created callback
'400':
$ref: '#/components/responses/BadRequest'
callbacks:
payment.failed:
'{$request.body#/url}':
post:
security: []
parameters:
- $ref: '#/components/parameters/NeonSignature'
- in: header
name: X-Neon-Webhook-Type
required: true
schema:
type: string
description: The type of this request (`payment.failed`).
requestBody:
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/PaymentFailedWebhook'
responses:
'200':
description: Return a 200 status to indicate the request was handled successfully
purchase.completed:
'{$request.body#/url}':
post:
security: []
parameters:
- $ref: '#/components/parameters/NeonSignature'
- in: header
name: X-Neon-Webhook-Type
required: true
schema:
type: string
description: The type of this request (`purchase.completed`).
requestBody:
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/PurchaseWebhookV2'
- $ref: '#/components/schemas/PurchaseWebhookV1'
responses:
'200':
description: Return a 200 status to indicate the request was handled successfully
refund.processed:
'{$request.body#/url}':
post:
security: []
parameters:
- $ref: '#/components/parameters/NeonSignature'
- in: header
name: X-Neon-Webhook-Type
required: true
schema:
type: string
description: The type of this request (`refund.processed`).
requestBody:
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/RefundWebhookV2'
- $ref: '#/components/schemas/RefundWebhookV1'
responses:
'200':
description: Return a 200 status to indicate the request was handled successfully
dispute.opened:
'{$request.body#/url}':
post:
security: []
parameters:
- $ref: '#/components/parameters/NeonSignature'
- in: header
name: X-Neon-Webhook-Type
required: true
schema:
type: string
description: The type of this request (`dispute.opened`).
requestBody:
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/DisputeWebhook'
responses:
'200':
description: Return a 200 status to indicate the request was handled successfully
dispute.closed:
'{$request.body#/url}':
post:
security: []
parameters:
- $ref: '#/components/parameters/NeonSignature'
- in: header
name: X-Neon-Webhook-Type
required: true
schema:
type: string
description: The type of this request (`dispute.closed`).
requestBody:
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/DisputeWebhook'
responses:
'200':
description: Return a 200 status to indicate the request was handled successfully
invoice.paid:
'{$request.body#/url}':
post:
security: []
parameters:
- $ref: '#/components/parameters/NeonSignature'
- in: header
name: X-Neon-Webhook-Type
required: true
schema:
type: string
description: The type of this request (`invoice.paid`).
requestBody:
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/InvoiceWebhook'
responses:
'200':
description: Return a 200 status to indicate the request was handled successfully
invoice.refunded:
'{$request.body#/url}':
post:
security: []
parameters:
- $ref: '#/components/parameters/NeonSignature'
- in: header
name: X-Neon-Webhook-Type
required: true
schema:
type: string
description: The type of this request (`invoice.refunded`).
requestBody:
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/InvoiceRefundWebhook'
responses:
'200':
description: Return a 200 status to indicate the request was handled successfully
subscription.activated:
'{$request.body#/url}':
post:
security: []
parameters:
- $ref: '#/components/parameters/NeonSignature'
- in: header
name: X-Neon-Webhook-Type
required: true
schema:
type: string
description: The type of this request (`invoice.paid`).
requestBody:
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/SubscriptionWebhook'
responses:
'200':
description: Return a 200 status to indicate the request was handled successfully
subscription.canceled:
'{$request.body#/url}':
post:
security: []
parameters:
- $ref: '#/components/parameters/NeonSignature'
- in: header
name: X-Neon-Webhook-Type
required: true
schema:
type: string
description: The type of this request (`invoice.paid`).
requestBody:
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/SubscriptionWebhook'
responses:
'200':
description: Return a 200 status to indicate the request was handled successfully
subscription.expired:
'{$request.body#/url}':
post:
security: []
parameters:
- $ref: '#/components/parameters/NeonSignature'
- in: header
name: X-Neon-Webhook-Type
required: true
schema:
type: string
description: The type of this request (`subscription.expired`).
requestBody:
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/SubscriptionWebhook'
responses:
'200':
description: Return a 200 status to indicate the request was handled successfully
checkout.abandoned:
'{$request.body#/url}':
post:
security: []
parameters:
- $ref: '#/components/parameters/NeonSignature'
- in: header
name: X-Neon-Webhook-Type
required: true
schema:
type: string
description: The type of this request (`invoice.paid`).
requestBody:
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/CheckoutAbandonedWebhook'
responses:
'200':
description: Return a 200 status to indicate the request was handled successfully
cart.abandoned:
'{$request.body#/url}':
post:
security: []
parameters:
- $ref: '#/components/parameters/NeonSignature'
- in: header
name: X-Neon-Webhook-Type
required: true
schema:
type: string
description: The type of this request (`invoice.paid`).
requestBody:
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/CartAbandonedWebhook'
responses:
'200':
description: Return a 200 status to indicate the request was handled successfully
tags:
- Purchases
components:
schemas:
PaymentFailedWebhook:
type: object
description: Request body for event version 1
required:
- id
- version
- isSandbox
- type
- data
properties:
id:
type: string
description: The ID of this event
version:
type: integer
description: The version of this event
enum:
- 1
isSandbox:
type: boolean
description: Whether this event is in sandbox mode
type:
type: string
description: The type of this event (payment.failed)
example: payment.failed
data:
allOf:
- type: object
required:
- payment
properties:
payment:
type: object
description: The payment that failed
required:
- id
- date
- status
- method
- code
- message
- amount
- currency
properties:
id:
type: string
description: The ID of the payment
date:
type: string
format: date-time
description: The date of this payment failure
status:
type: string
description: The status of the payment
method:
type: string
description: The payment method associated with this payment
code:
type: string
description: The error code associated with the payment failure
message:
type: string
description: Additional information to describe the payment failure
amount:
type: integer
description: The amount of this payment, expressed as 100x the currency's base unit; see [here](https://docs.neonpay.com/docs/currencies#currencies-in-the-api) for more on currencies
currency:
type: string
description: The ISO 4217 currency code of the payment
- anyOf:
- type: object
required:
- checkout
properties:
checkout:
type: object
required:
- id
- accountId
properties:
id:
type: string
description: The checkout ID associated with this payment
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
- 'null'
example: player_987654
minLength: 1
- type: object
required:
- invoice
properties:
invoice:
type: object
required:
- id
- accountId
properties:
id:
type: string
description: The invoice ID associated with this payment
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
- 'null'
example: player_987654
minLength: 1
SubscriptionWebhook:
type: object
description: Request body for event version 1
properties:
id:
type: string
description: The ID of this event
version:
type: integer
description: The version of this event
enum:
- 1
isSandbox:
type: boolean
description: Whether this event is in sandbox mode
type:
type: string
description: The type of this event (invoice.paid or dispute.closed)
example: invoice.paid
data:
type: object
properties:
subscription:
$ref: '#/components/schemas/SubscriptionExternal'
ErrorDetail:
type: object
required:
- source
- message
properties:
source:
type: string
description: Specific entity that caused this error
example: purchaseId
message:
type: string
description: Human readable description of the error for this entity (defined in `source`)
example: Purchase not found
InvoiceRefundWebhook:
type: object
description: Request body for event version 1
properties:
id:
type: string
description: The ID of this event
version:
type: integer
description: The version of this event
enum:
- 1
isSandbox:
type: boolean
description: Whether this event is in sandbox mode
type:
type: string
description: The type of this event (invoice.refunded)
example: invoice.paid
data:
type: object
required:
- refund
properties:
refund:
$ref: '#/components/schemas/InvoiceRefund'
BasePurchase:
type: object
required:
- id
- date
- checkoutId
- orderNumber
- itemsSubtotalAmount
- totalExcludingTaxAmount
- subtotalAmount
- taxAmount
- taxRate
- totalAmount
- currency
- initialCurrency
- status
- playerCountry
- initialPlayerCountry
- pricingSheetName
- locale
- items
- payment
properties:
id:
type: string
date:
type: string
format: date-time
description: The ISO timestamp of this purchase
orderNumber:
type: string
description: The user-facing short ID associated with this purchase
checkoutId:
allOf:
- description: The ID of the checkout this purchase originated from
- type: string
itemsSubtotalAmount:
type: number
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
totalExcludingTaxAmount:
type: number
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
subtotalAmount:
type: number
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
taxAmount:
type: number
description: The purchase 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
taxRate:
type: number
description: The tax rate used for this checkout as a percentage
totalAmount:
type: number
description: The total amount of this checkout (subtotal + 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
discountAmount:
type:
- number
- 'null'
description: The amount this checkout was discounted, if applicable, expressed as 100x the currency's base unit; see [here](https://docs.neonpay.com/docs/currencies#currencies-in-the-api) for more on currencies
promoCode:
type:
- string
- 'null'
description: The promo code applied to this checkout, if applicable
fee:
type: object
required:
- fxRate
- feeAmount
- netProceedsAmount
- settlementCurrency
properties:
fxRate:
type: number
description: The foreign-exchange rate used to convert this purchase from the purchase currency to your settlement currency
feeAmount:
type: number
description: The fee amount we charged, expressed as 100x your settlement currency's base unit; see [here](https://docs.neonpay.com/docs/currencies#currencies-in-the-api) for more on currencies
netProceedsAmount:
type: number
description: The net proceeds you're credited, expressed as 100x your settlement currency's base unit; see [here](https://docs.neonpay.com/docs/currencies#currencies-in-the-api) for more on currencies
settlementCurrency:
type: string
description: Your settlement currency
currency:
type: string
initialCurrency:
type: string
description: The initial currency of the purchase before any currency changes
initialPlayerCountry:
type: string
description: The initial player country of the purchase before any country changes
pricingSheetName:
type:
- string
- 'null'
description: The name of the pricing sheet used for this purchase
status:
type: string
externalReferenceId:
type:
- string
- 'null'
example: e7ec4707-75ee-4fa8-aeb9-57370098ddc5
description: User-supplied reference ID
externalMetadata: {}
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
- 'null'
example: player_987654
minLength: 1
email:
type:
# --- truncated at 32 KB (58 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/neon-commerce/refs/heads/main/openapi/neon-commerce-purchases-api-openapi.yml