Neon Commerce Purchases API

openapi: 3.2.0
info:
  title: Purchases API
  description: 'The Purchase API can be used to get details about a purchase, refund purchases, and subscribe to purchase-related webhooks. Purchases are created when the user successfully completes a checkout. Once finalized, a checkout can no longer be accessed or modified; instead, use the purchase API to find the associated checkout.

    '
  version: 1.0.0
servers:
- url: https://api.neonpay.com
security:
- EnvironmentApiKey: []
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:
    PurchaseBundleItem:
      type: object
      required:
      - sku
      - name
      - quantity
      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
    CartAbandonedWebhook:
      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
          example: invoice.paid
        data:
          type: object
          properties:
            redirectUrl:
              type: string
              description: The URL to redirect the user to
            cart:
              type: object
              properties:
                id:
                  type: string
                  description: The ID of the cart
            playerId:
              type: string
              description: The ID of the player
    PurchaseNotFoundError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: PURCHASE_NOT_FOUND
              enum:
              - PURCHASE_NOT_FOUND
            message:
              type: string
              example: Purchase not found.
    PurchaseWebhookV1:
      type: object
      description: Request body for event version 1
      deprecated: true
      properties:
        purchase:
          type: object
        isSandbox:
          type: boolean
    Purchase:
      allOf:
      - $ref: '#/components/schemas/BasePurchase'
      - type: object
        required:
        - events
        properties:
          events:
            type: array
            items:
              $ref: '#/components/schemas/PurchaseEvent'
    PurchaseEvent:
      type: object
      required:
      - id
      - type
      - amount
      - currency
      properties:
        id:
          type: string
          description: The ID of this event
        date:
          type: string
          description: The ISO timestamp of this event
          format: date-time
        type:
          type: string
          enum:
          - sale
          - refund
          - chargeback
        amount:
          type: number
          description: The total amount of this event (either the purchase or refund total), 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
    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'
    CheckoutAbandonedWebhook:
      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
          example: invoice.paid
        data:
          type: object
          properties:
            redirectUrl:
              type: string
              description: The URL to redirect the user to
            checkout:
              type: object
              properties:
                id:
                  type: string
                  description: The ID of the checkout
                date:
                  type: string
                  format: date-time
                  description: The ISO timestamp of this purchase
    Dispute:
      type: object
      required:
      - id
      - date
      - status
      - comments
      - amount
      - purchaseId
      - currency
      - isSandbox
      - reason
      properties:
        id:
          description: The dispute ID
          type: string
        date:
          description: The date of the dispute
          type: string
          format: date-time
        status:
          type: string
          description: The status of this dispute. Disputes are initialized in the `open` status; when we receive a decision from the customer's bank, the status is updated to `won`, `lost`, or `closed`.
          enum:
          - open
          - closed
          - won
          - lost
        comments:
          type:
          - string
          - 'null'
          description: Optional comments; defaults to null
        amount:
          type: number
          description: Total disputed amount
        purchaseId:
          type: string
          description: The ID of the purchase being disputed
        isSandbox:
          type: boolean
          description: Whether this event is in sandbox mode
        currency:
          type: string
          description: The ISO 4217 currency code of the purchase under dispute
        reason:
          type:
          - string
          - 'null'
          description: The reason for the dispute
          enum:
          - null
          - cancel_subscription
          - product_not_received
          - product_unacceptable
          - friendly_fraud
          - ach_return
          - ach_reversal
          - duplicate
          - fraud
          - authorization
          - processing_errors
          - consumer_disputes
          - other
    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'
    InvoiceRefund:
      type: object
      required:
      - id
      - date
      - subtotalAmount
      - taxAmount
      - totalAmount
      - currency
      - settlementCurrency
      - invoiceId
      properties:
        id:
          type: string
        date:
          type: string
          format: date-time
        subtotalAmount:
          type: integer
          deprecated: true
        taxAmount:
          type: integer
        subtotalAmountInSettlementCurrency:
          type: integer
        totalAmountInSettlementCurrency:
          type: integer
        totalAmount:
          type: integer
        currency:
          $ref: '#/components/schemas/Currency'
        settlementCurrency:
          $ref: '#/components/schemas/Currency'
        invoiceId:
          type: string
    RefundItem:
      type: object
      required:
      - id
      - quantity
      - item
      - sku
      - name
      - price
      - referencePrice
      - referenceCurrency
      properties:
        id:
          type: string
          description: The unique ID of this item
          deprecated: true
        quantity:
          type: number
          description: The number of units of this item refunded
        item:
          type: object
          description: The original purchased item
          required:
          - id
          - sku
          properties:
            id:
              type: string
              description: The unique ID of this item
            sku:
              type: string
              description: The SKU of this item
        sku:
          type: string
          description: The SKU of this item
          deprecated: true
        name:
          type: string
          description: The localized name of this item
          deprecated: true
        price:
          type: number
          description: The price of this item, expressed as 100x the smallest unit of the purchase currency
          deprecated: true
        refundableQuantity:
          type: number
          description: The purchased quantity of this item, excluding refunded units
          deprecated: true
        referencePrice:
          type: number
          description: The price of this item in the settlement currency
          deprecated: true
        referenceCurrency:
          type: string
          description: The settlement currency of this item
          deprecated: true
    RefundWebhookV1:
      type: object
      description: Request body for event version 1
      deprecated: true
      properties:
        refund:
          type: object
        isSandbox:
          type: boolean
    RefundWebhookV2:
      type: object
      description: Request body for event version 2
      properties:
        id:
          type: string
          description: The ID of this event
        version:
          type: integer
          description: The version of this event
          enum:
          - 2
        isSandbox:
          type: boolean
          description: Whether this event is in sandbox mode
        type:
          type: string
          description: The type of this event (refund.processed)
          example: refund.processed
        data:
          type: object
          properties:
            refund:
              $ref: '#/components/schemas/Refund'
    PaymentFailedWebhook:
      type: object
      description: Request body for event version 1
      required:
      - id
    

# --- 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