Defold In-app purchase extension API documentation

This extension provides functions for making in-app purchases. Supported on iOS, Android (Google Play and Amazon) and Facebook Canvas.

Usage

To use this library in your Defold project, add the following URL to your game.project dependencies:

https://github.com/defold/extension-iap/archive/master.zip

We recommend using a link to a zip file of a specific release.

Source code

The source code is available on GitHub

API reference

Modules

iap

Functions and constants for doing in-app purchases. Supported on iOS, Android (Google Play and Amazon) and Facebook Canvas platforms. [icon:ios] [icon:googleplay] [icon:amazon] [icon:facebook]

Enums

iap.PROVIDER_ID_AMAZON

provider id for Amazon

iap.PROVIDER_ID_APPLE

provider id for Apple

iap.PROVIDER_ID_FACEBOOK

provider id for Facebook

iap.PROVIDER_ID_GOOGLE

iap provider id for Google

iap.REASON_UNSPECIFIED

unspecified error reason

iap.REASON_USER_CANCELED

user canceled reason

iap.TRANS_STATE_FAILED

transaction failed state

iap.TRANS_STATE_PURCHASED

transaction purchased state

iap.TRANS_STATE_PURCHASING

transaction purchasing state This is an intermediate mode followed by TRANS_STATE_PURCHASED. Store provider support dependent.

iap.TRANS_STATE_RESTORED

transaction restored state This is only available on store providers supporting restoring purchases.

iap.TRANS_STATE_UNVERIFIED

transaction unverified state, requires verification of purchase


Functions

iap.buy() Sets the listener function for In-app purchase events.
iap.finish() Explicitly finish a product transaction. [icon:attention] Calling iap.finish ...
iap.get_provider_id() Get current iap provider
iap.list() Get a list of all avaliable iap products.
iap.restore() Restore previously purchased products.
iap.set_listener() Set the callback function to receive purchase transaction events.

iap.buy(id, options)

Parameter Type Description
id string

product to buy

options table

optional parameters as properties. The following parameters can be set

  • request_id string -

    Facebook only. [icon:facebook] Optional custom unique request id to set for this transaction. The id becomes attached to the payment within the Graph API.

Sets the listener function for In-app purchase events.

Examples

  local function iap_listener(self, transaction, error)
    if error == nil then
      -- purchase is successful.
      print(transaction.date)
      -- required if auto finish transactions is disabled in project settings
      if (transaction.state == iap.TRANS_STATE_PURCHASED) then
        -- do server-side verification of purchase here..
        iap.finish(transaction)
      end
    else
      print(error.error, error.reason)
    end
  end

  function init(self)
      iap.set_listener(iap_listener)
      iap.buy("my_iap")
  end

iap.finish(transaction)

Parameter Type Description
transaction table

transaction table parameter as supplied in listener callback

Explicitly finish a product transaction.

⚠️ Calling iap.finish is required on a successful transaction if auto_finish_transactions is disabled in project settings. Calling this function with auto_finish_transactions set will be ignored and a warning is printed. The transaction.state field must equal iap.TRANS_STATE_PURCHASED.

iap.get_provider_id()

Returns

Return value Type Description
provider_id constant

one of the following values

  • iap.PROVIDER_ID_GOOGLE
  • iap.PROVIDER_ID_AMAZON
  • iap.PROVIDER_ID_APPLE
  • iap.PROVIDER_ID_FACEBOOK

Get current iap provider

iap.list(ids, callback)

Parameter Type Description
ids table

table (array) of identifiers to get products from

callback function

result callback taking the following parameters

Parameter Type Description
self object

The current object.

products table

a table describing the available iap products.

  • ident string -

    The product identifier.

  • title string -

    The product title.

  • description string -

    The product description.

  • price number -

    The price of the product.

  • price_string string -

    The price of the product, as a formatted string (amount and currency symbol).

  • currency_code string -

    The currency code. On Google Play, this reflects the merchant’s locale, instead of the user’s. [icon:ios] [icon:googleplay] [icon:facebook]

error table

a table containing error information. nil if there is no error. - error (the error message)

Get a list of all avaliable iap products.

Examples

  local function iap_callback(self, products, error)
    if error == nil then
      for k,p in pairs(products) do
        -- present the product
        print(p.title)
        print(p.description)
      end
    else
      print(error.error)
    end
  end

  function init(self)
      iap.list({"my_iap"}, iap_callback)
  end

iap.restore()

Returns

Return value Type Description
success boolean

value is true if current store supports handling restored transactions, otherwise false.

Restore previously purchased products.

iap.set_listener(listener)

Parameter Type Description
listener function

listener callback function. Pass an empty function if you no longer wish to receive callbacks.

Parameter Type Description
self object

The current object.

transaction table

a table describing the transaction.

  • ident string -

    The product identifier.

  • state string -

    The transaction state. One of the following

    • iap.TRANS_STATE_FAILED
    • iap.TRANS_STATE_PURCHASED
    • iap.TRANS_STATE_PURCHASING
    • iap.TRANS_STATE_RESTORED
    • iap.TRANS_STATE_UNVERIFIED
  • date string -

    The date and time for the transaction.

  • trans_ident string -

    The transaction identifier. This field is only set when state is TRANS_STATE_RESTORED, TRANS_STATE_UNVERIFIED or TRANS_STATE_PURCHASED.

  • receipt string -

    The transaction receipt. This field is only set when state is TRANS_STATE_PURCHASED or TRANS_STATE_UNVERIFIED.

  • original_trans string -

    Apple only[icon:apple]. The original transaction. This field is only set when state is TRANS_STATE_RESTORED.

  • signature string -

    Google Play only[icon:googleplay]. A string containing the signature of the purchase data that was signed with the private key of the developer.

  • request_id string -

    Facebook only[icon:facebook]. This field is set to the optional custom unique request id request_id if set in the iap.buy() call parameters.

  • user_id string -

    Amazon Pay only[icon:amazon]. The user ID.

  • is_sandbox_mode boolean -

    Amazon Pay only[icon:amazon]. If true, the SDK is running in Sandbox mode. This only allows interactions with the Amazon AppTester. Use this mode only for testing locally.

  • cancel_date string -

    Amazon Pay only[icon:amazon]. The cancel date for the purchase. This field is only set if the purchase is canceled.

  • canceled string -

    Amazon Pay only[icon:amazon]. Is set to true if the receipt was canceled or has expired; otherwise false.

error table

a table containing error information. nil if there is no error. error - the error message. reason - the reason for the error, value can be one of the following constants

  • iap.REASON_UNSPECIFIED
  • iap.REASON_USER_CANCELED

Set the callback function to receive purchase transaction events.