View on GitHub

@nativescript/payments ​

In-app purchases and subscriptions for NativeScript apps, backed by StoreKit 2 on iOS and the Google Play Billing Library 8 on Android.

Payments on iOS

Item list	Confirmation	Done	Success

Payments on Android

Item list	Confirmation	Success

Contents ​

• Installation
• Prerequisites
  • iOS prerequisites
  • Android prerequisites
• Usage
  • Quick start
  • How a purchase flows
  • Finishing transactions
  • Subscriptions
  • Restoring purchases
  • Purchase options
  • Handling errors
  • Promoted in-app purchases (iOS)
  • Connection lifecycle
• Migrating from 3.x
• API
  • Payment
  • Product
  • Transaction
  • PaymentError
  • PurchaseOptions
• License

Installation ​

ns plugin add @nativescript/payments

On iOS the plugin uses StoreKit 2 on iOS 15 and later and falls back to StoreKit 1 on older versions. On Android it uses the Google Play Billing Library 8.0 (minSdk 21).

Prerequisites ​

iOS prerequisites ​

To offer in-app purchases in your iOS app, create the products for the app on App Store Connect.

The Product ID you enter on the form is the value you pass to fetchProducts().

Once created, the products are listed for the app in App Store Connect.

To test iOS purchases fully you need a real device and a sandbox test user on your App Store Connect account.

Android prerequisites ​

1. Upload at least one APK or AAB to the Google Play Console.
2. Create your in-app products or subscriptions in the console.

The Product ID you enter on the form is the value you pass to fetchProducts().

Important notes about Google products ​

• Avoid numeric-only values in the product ID. Play appears to ignore such IDs when querying and returns a single product instead of every product requested.

• Products cannot be purchased until Google has reviewed the app. They still appear in the result of fetchProducts(), with a title suffixed by "(in review)" or similar, but the purchase flow errors until the review completes.

To test Android purchases you need a real device with Google Play set up and signed in. Add license testers to the app so test purchases are not charged. See also Google's test purchases guide.

Usage ​

Quick start ​

Create one Payment instance, assign its two callbacks right after construction, and keep the instance alive for the life of the app. Everything else returns a promise.

import {
  Payment,
  PaymentError,
  Product,
  Transaction,
} from '@nativescript/payments'

const CONSUMABLE_IDS = ['io.myapp.coins.five', 'io.myapp.coins.fifty']
const NON_CONSUMABLE_IDS = ['io.myapp.remove_ads']

export class Store {
  products: Array<Product> = []
  private payment: Payment

  constructor() {
    if (!Payment.isSupported()) {
      console.log('In-app purchases are not available on this device')
      return
    }

    this.payment = new Payment()

    // Fires once the store connection is ready. Query products here.
    this.payment.onReady = async () => {
      try {
        this.products = await this.payment.fetchProducts(
          [...CONSUMABLE_IDS, ...NON_CONSUMABLE_IDS],
          'inapp',
        )
      } catch (error) {
        console.error('Could not fetch products', error)
      }
    }

    // Fires for every transaction the store reports: purchases started from your app,
    // purchases completed later (Ask to Buy, pending payments), renewals, and refunds.
    this.payment.onPurchaseUpdate = (transactions, error) => {
      if (error) {
        const paymentError = error as PaymentError
        if (paymentError.code !== 'USER_CANCELLED') {
          console.error(`Purchase failed: ${paymentError.message}`)
        }
        return
      }
      transactions.forEach((transaction) => this.handleTransaction(transaction))
    }
  }

  async buy(product: Product) {
    try {
      await this.payment.purchaseProduct(product)
    } catch (error) {
      // See "How a purchase flows" for what rejects on each platform.
      console.error(`Could not start purchase: ${error.message}`)
    }
  }

  private async handleTransaction(transaction: Transaction) {
    switch (transaction.state) {
      case 'purchased':
        if (transaction.isRevoked) {
          // Refunded. Revoke whatever the purchase unlocked.
          return
        }
        // 1. Verify the transaction on your backend (see Transaction.receiptToken).
        // 2. Grant the entitlement.
        // 3. Finish the transaction. Consume it if the user may buy it again.
        await transaction.finish({
          consume: CONSUMABLE_IDS.includes(transaction.productId),
        })
        break
      case 'pending':
        // Waiting on an external action such as Ask to Buy approval or a deferred payment.
        // Do not grant anything or finish it. Another update arrives when it completes.
        break
    }
  }
}

How a purchase flows ​

1. new Payment() opens the store connection. On Android this starts the Play Billing connection; on iOS it starts listening for StoreKit transaction updates.
2. onReady fires. Call fetchProducts() to load the products the user can buy.
3. purchaseProduct(product) presents the platform purchase sheet.
4. The result arrives in onPurchaseUpdate. Verify it, grant the entitlement, then call transaction.finish().

The promise returned by purchaseProduct() settles at a different point on each platform, so put your success handling in onPurchaseUpdate, which behaves the same on both:

onPurchaseUpdate receives (transactions, error). When error is set, transactions is an empty array. On Android a cancelled purchase arrives here as an error with code USER_CANCELLED.

Finishing transactions ​

Every transaction in the purchased state must be finished after you grant the entitlement, or the store treats it as incomplete:

• On Android, Google refunds any purchase that is not acknowledged within three days. finish() acknowledges it.
• On iOS, an unfinished transaction is delivered to onPurchaseUpdate again on every launch until you finish it.

// Non-consumables and subscriptions: acknowledge and keep.
await transaction.finish()

// Consumables (coins, lives): consume so the user can buy the same product again.
await transaction.finish({ consume: true })

consume only has an effect on Android. iOS decides consumability from the product type configured in App Store Connect. On Android, auto-renewing subscriptions are acknowledged regardless of consume, and finishing an already-acknowledged transaction is a no-op.

To catch purchases that completed while your app was not running, call fetchPurchases() at startup on Android and finish anything whose isAcknowledged is false. iOS delivers those through onPurchaseUpdate on its own.

this.payment.onReady = async () => {
  const owned = await this.payment.fetchPurchases()
  for (const transaction of owned) {
    if (transaction.state === 'purchased' && !transaction.isAcknowledged) {
      await this.handleTransaction(transaction)
    }
  }
}

Subscriptions ​

Subscriptions use the same calls as one-time products. Fetch them with the 'subs' type and buy them with purchaseProduct().

const plans = await this.payment.fetchProducts(
  ['io.myapp.pro.monthly', 'io.myapp.pro.yearly'],
  'subs',
)

await this.payment.purchaseProduct(plans[0])

On Android the purchase uses the first offer listed in the product's subscription offer details, which is the base plan unless you have configured a promotional offer first. For other offers, work with the native ProductDetails through product.native.

Check the state of a subscription from a Transaction:

For reliable entitlement checks, verify subscriptions on your backend with the App Store Server API and the Google Play Developer API.

Let users manage or cancel subscriptions with the system UI:

await this.payment.showSubscriptionsManagement()

// Optionally deep-link to one subscription.
await this.payment.showSubscriptionsManagement({
  ios: { subscriptionGroupID: '21345678' }, // iOS 17+
  android: { productId: 'io.myapp.pro.monthly' },
})

On iOS 15 and later this presents the manage subscriptions sheet; older versions open the App Store subscriptions page. On Android it opens the Google Play subscriptions page.

Restoring purchases ​

fetchPurchases() returns the transactions the user currently owns, including active subscriptions. On Android this is a local query of the Play cache for one-time products and subscriptions. On iOS 15 and later it calls AppStore.sync() before reading the current entitlements, which can prompt the user to sign in to the App Store, so Apple recommends triggering it from an explicit "Restore Purchases" action.

async restorePurchases() {
  const transactions = await this.payment.fetchPurchases();
  for (const transaction of transactions) {
    if (transaction.state === 'purchased' && !transaction.isExpired && !transaction.isRevoked) {
      // Grant the entitlement for transaction.productId
    }
  }
}

Purchase options ​

purchaseProduct() accepts an optional PurchaseOptions object:

await this.payment.purchaseProduct(product, {
  accountId: '4c2a9d84-2b6e-4f0a-9c1e-8a5f7b3d2e10',
  ios: {
    quantity: 1,
    simulatesAskToBuyInSandbox: true,
  },
  android: {
    profileId: 'profile-42',
    isOfferPersonalized: false,
  },
})

Handling errors ​

Rejected promises and the error argument of onPurchaseUpdate are PaymentError instances:

try {
  await this.payment.purchaseProduct(product)
} catch (error) {
  const paymentError = error as PaymentError
  console.log(paymentError.code) // e.g. 'USER_CANCELLED'
  console.log(paymentError.message) // human-readable description
  console.log(paymentError.resolution) // suggested fix, when the store provides one
  console.log(paymentError.native) // the platform response object
}

code is one of the FailureTypes values: USER_CANCELLED, DEFERRED_PAYMENT, PURCHASE_NOT_ALLOWED, PRODUCT_UNAVAILABLE, PRODUCT_ALREADY_OWNED, PRODUCT_NOT_OWNED, DEVELOPER_USAGE, NETWORK_AVAILABILITY, BILLING_AVAILABILITY, SERVICE_DISCONNECTED, SERVICE_TIMEOUT, SERVICE_UNAVAILABLE, FEATURE_NOT_SUPPORTED, USER_INELIGIBLE, INSUFFICIENT_FUNDS, ERROR, or UNSPECIFIED.

Promoted in-app purchases (iOS) ​

When a user taps a product promoted on your App Store page, iOS launches your app and the plugin calls onIncomingPromotion with the product. Continue the purchase when your app is ready, for example after the user has signed in:

this.payment.onIncomingPromotion = (product) => {
  this.payment.purchaseProduct(product)
}

This callback is never called on Android.

Connection lifecycle ​

• Create a single Payment instance and keep it for the life of the app. On Android it owns the Play Billing connection; on iOS it owns the StoreKit transaction listener. Creating a new instance per page means missing transaction updates.
• The store connection starts in the constructor. You do not need to call connect() after new Payment().
• disconnect() closes the Play Billing connection on Android, and connect() reopens it. Both are no-ops on iOS.
• canMakePayments() returns true on Android once the Play Billing connection is ready, and on iOS when the device allows purchases (for example, not blocked by Screen Time restrictions).
• Payment.isSupported() is a static check you can run before constructing: on iOS it reports whether the device can make payments; on Android it reports whether the Google Play Store app is installed.

Migrating from 3.x ​

Version 4 removed RxJS. Every paymentEvents context maps to a promise or callback on a Payment instance:

Before:

import {
  buyItem,
  fetchItems,
  finalizeOrder,
  init,
  PaymentEvent,
  paymentEvents,
  toMainThread,
} from '@nativescript/payments'

paymentEvents.connect()
paymentEvents.pipe(toMainThread()).subscribe((event: PaymentEvent.Type) => {
  switch (event.context) {
    case PaymentEvent.Context.CONNECTING_STORE:
      if (event.result === PaymentEvent.Result.SUCCESS) {
        fetchItems(['io.myapp.coins.five'])
      }
      break
    case PaymentEvent.Context.RETRIEVING_ITEMS:
      if (event.result === PaymentEvent.Result.SUCCESS) {
        this.items = event.payload
      }
      break
    case PaymentEvent.Context.PROCESSING_ORDER:
      if (event.result === PaymentEvent.Result.SUCCESS) {
        finalizeOrder(event.payload, true)
      }
      break
  }
})
init()

buyItem(this.items[0])

After:

import { Payment } from '@nativescript/payments'

const payment = new Payment()
payment.onReady = async () => {
  this.items = await payment.fetchProducts(['io.myapp.coins.five'], 'inapp')
}
payment.onPurchaseUpdate = (transactions, error) => {
  if (error) {
    return
  }
  transactions.forEach((transaction) => {
    if (transaction.state === 'purchased') {
      transaction.finish({ consume: true })
    }
  })
}

payment.purchaseProduct(this.items[0])

API ​

Payment ​

Product ​

Transaction ​

PaymentError ​

Extends Error.

PurchaseOptions ​

interface PurchaseOptions {
  accountId?: string
  ios?: {
    quantity?: number
    simulatesAskToBuyInSandbox?: boolean
    accountId?: NSUUID
  }
  android?: {
    accountId?: string
    profileId?: string
    isOfferPersonalized?: boolean
  }
}

See Purchase options for what each field does.

License ​

Apache License Version 2.0