Documentation

In-App Payment

The webOS In-App Payment framework allows you to embed a store directly in your app and sell additional app content and functionality.

The In-App Payment framework consists of one component accessible to device apps:

 com.palm.service.payment

All in-app purchase functionality is implemented via API calls to this JavaScript service accessible on the device bus.

See Also

In-App Payment Overview

Methods

getAvailableItems - Returns item information according to specified criteria.
getItemInfo - Returns details about a specific item.
getPendingPurchaseInfo - Checks if a pending purchase is complete.
purchaseItem - Purchases an app item.

getAvailableItems

Returns the list of application's available items filtered according to specified criteria. All arguments are optional, and default to true if omitted.

To limit transmitted data size, no receipts are returned.

Syntax

{ 
    "includePerishable"    : boolean, 
    "includeNonPerishable" : boolean, 
    "includePurchased"     : boolean, 
    "includeNotPurchased"  : boolean 
}

Parameters

Parameter	Required	Type	Description
includePerishable	No	boolean	Should available perishable items be returned flag. Default is `true`.
includeNonPerishable	No	boolean	Should available non-perishable items be returned flag. Default is `true`.
includePurchased	No	boolean	Should already purchased items be returned flag. Default is `true`.
includeNonPurchased	No	boolean	Should non-purchased items be returned flag. Default is `true`.

Returns

{
   "returnValue" : boolean,
   "itemCount"   : int,
   "itemInfos" : [
      {
         "type"     : string,
         "title"    : string,
         "summary"  : string,
         "currency" : string,
         "itemId"   : string,
         "price"    : string,
         "itemStatus" :
         {
            "timesPurchased" : string
         }
      }
    ]
    "errorCode" : string
}

Parameter	Required	Type	Description
returnValue	Yes	boolean	`true` (success) or `false` (failure).
itemCount	Yes	int	Number of items returned.
itemInfos	Yes	object array	If no item is found, object array is empty.
type	No	string	"P" (perishable) or "N" (non-perishable).
title	No	string	Item title.
summary	No	string	Item description.
currency	No	string	3-digit currency code, i.e., "USD". Conforms to ISO 4217.
itemId	No	string	Item ID. 64 characters maximum.
price	No	string	Item price, i.e., "0.99".
itemStatus	No	object	Inline object, see field below.
timesPurchased	No	string	Number of times item purchased.
errorCode	No	string	Error code returned on failure. Possible values: NotAllowed -- Authentication failure Internal Error -- General error

Examples

{ 
    "includePerishable"    : false, 
    "includeNonPerishable" : true, 
    "includePurchased"     : false, 
    "includeNotPurchased"  : false 
}

Example Outputs

Non-perishable items returned

{
   "returnValue" : true,
   "itemCount" : 2,
   "itemInfos" : [
      {
         "type" : "N"
         "title" : "Challenging game level 1",
         "summary" : "This level 1 is the basic level of the game.",
         "currency" : "USD",
         "itemId" : "gamelevel01",
         "price" : "0.99",
         "itemStatus" :
         {
            "timesPurchased" : "1"
         }
      },
      {
         "type" : "N"
         "title" : "Challenging game level 2",
         "summary" : "This level 2 is the basic level of the game.",
         "currency" : "USD",
         "itemId" : "gamelevel02",
         "price" : "0.99",
         "itemStatus" :
         {
            "timesPurchased" : "1"
         }
      }
   ]
}

No items found

{
   "returnValue" : true,
   "itemCount" : 0,
   "itemInfos" : [{}]
}

getItemInfo

Returns item details. If an item is not found, "itemInfo" is an empty object.

Syntax

{ 
   "itemId"          : string,
   "includeReceipts" : boolean,
   "maxReceipts"     : int
}

Parameters

Parameter	Required	Type	Description
itemId	Yes	string	Item ID, i.e. "gamelevel101". 64 characters maximum.
includeReceipts	Yes	boolean	Include receipts with items flag.
maxReceipts	No	int	Maximum number of receipts to return. Limit of 16.

Returns

{
   "returnValue"   : boolean,
   "itemInfo"      :
   {
       "type"       : string,
       "title"      : string,
       "summary"    : string,
       "currency"   : string,
       "itemId"     : string,
       "price"      : string,
       "itemStatus" : inline object (below) | string
       {
          "timesPurchased" : string,
          "receipts" : [ {
               "receiptInfo"   : receipt object,
               "signedReceipt" : string BLOB
            }]
        }
   },
   errorCode : string
}

Parameter	Required	Type	Description
returnValue	Yes	boolean	`true` (success) or `false` (failure).
itemInfo	Yes	object	Inline object. If no item is found, object is empty.
type	No	string	"P" (perishable) or "N" (non-perishable). Subscriptions are not currently supported.
title	No	string	Item title.
summary	No	string	Item description.
currency	No	string	3-digit currency code, i.e., "USD". Conforms to ISO 4217.
itemId	No	string	Item ID , i.e., "gamelevel3". 64 characters maximum.
price	No	string	Item price, i.e., "0.99"
itemStatus	No	object or string	Inline object, see fields below. If item is not found, this is set to "ItemNotFound".
timesPurchased	No	string	Number of times item purchased.
receipts	No	object array	Array of receipt objects.
receiptInfo	No	receipt object	Receipt object.
signedReceipt	No	string BLOB	Signed receipt. Can be used for verification. Base64 encoded.
errorCode	No	string	Error code returned on failure. Possible values: NotAllowed -- Authentication failure InternalError -- General error

Example

{ 
   "itemId"          : "gameLevel2",
   "includeReceipts" : true,
   "maxReceipts"     : 5
}

Example Output

{
   "returnValue" : true,
   "itemInfo" :
   {
      "type" : "N"
      "title" : "Challenging game level 1",
      "summary" : "This level 1 is the basic level of the game.",
      "currency" : "USD",
      "itemId" : "gamelevel01",
      "price" : "0.99",
      "itemStatus" :
      {
         "timesPurchased" : "1",
         "receipts" : [ 
             {
                "receiptInfo" : receipt object,
                "signedReceipt" : <BLOB>
             } ]
      }
   }
}

getPendingPurchaseInfo

Checks if a pending purchase is complete.

Syntax

{ 
   "orderNo" : int
}

Parameters

Parameter	Required	Type	Description
orderNo	Yes	int	Order number.

Returns

{ 
    "returnValue"   : boolean, 
    "receipts" : {
         "receiptInfo"   : receipt object,
         "signedReceipt" : string BLOB
     },
    "orderNo"       : int,
    "receiptStatus" : string, 
    "sku"           : string,
    "errorCode"     : string,
    "errorText"     : string    
}

Parameter	Required	Type	Description
returnValue	Yes	boolean	`true` (success) or `false` (failure).
receipts	No	object	Returned on successful purchase. Returned as a base64 encoded string of the receipt and sku denoting the item purchased in the form <App>-<App Name>-<App version Item Id>.
receiptInfo	No	object	Receipt object
signedReceipt	No	string BLOB	Signed receipt. Can be used for verification. Base64 encoded.
orderNo	No	int	Order number
receiptStatus	No	string	"Charged", "Pending", "Failed", or "OrderNotPresent". If "Pending", the app should use the "orderNo" and poll on getPendingPurchaseInfo. If no "orderNo" is returned, then you will need to query on getItemInfo and look for receipts/times purchased changes. If order cannot be found, "OrderNotPresent" is returned.
sku	No	string	Stock Keeping Unit/product number. I.e., "App-com.mycompany.myappid-1.0.3-mygamelevel01"
errorCode	No	string	Numeric code returned on failure.
errorText	No	string	Error text message returned on failure.

Example

{
    "orderNo" : 12345
}

Example Output

{ 
   "returnValue" : true,
   "receipts" : {      
      "receiptInfo" : {
         "version" : "1.0",
         "receiptId" : 1234,
         "orderId" : 123456,
         "purchaseTime" : 77778889999,
         "type" : "N",
         "appId" : "com.mycompany.myapp",
         "itemId" : "myitemid",
         "quantity" : 1,
         "vendorData" : <BLOB>,
         "accountUniqueId" : <BLOB>,
         "deviceUniqueId" : <BLOB>
      },
      "signedReceipt" : <BLOB>
   },
   "orderNo" : 12345,
   "receiptStatus" : "Charged",
   "sku" : "App-com.mycompany.myappid-1.0.3-mygamelevel01" 
}

purchaseItem

Purchases an in-app item. Requires the item's ID.

A successful purchase returns a "Charged" status and a receipt. If a payment takes time, a "Pending" status is returned. If this happens, your app can later call getPendingPurchaseInfo to check if the payment experienced further user action. Note that a pending status can also transit to failure.

For perishable items, 3rd-party apps should not charge the user twice. Your UI should diplay the item as "pending" and not allow the user to re-purchase it. Users should be able to check if it is done (via user tap) or, alternatively, your app can poll state periodically.

Note

Currently, there is a noticeable lag between the time this API is called (the user clicks "purchase") and when the confirm dialog or Payment Setup UI first appears. You may want to give your users some type of feedback on this such as a "loading" icon.

Syntax

{ 
   "itemId"     : string,
   "quantity"   : int,
   "vendorData" : string
}

Parameters

Parameter	Required	Type	Description
itemId	Yes	string	Item ID, i.e. "gamelevel101". 64 characters maximum.
quantity	Yes	int	Number of items to purchase. Right now, just 1 for perishable items, ignored for non-perishable items. In the future, multiple item purchase will be supported.
vendorData	Yes	string	This string appears signed in the receipt. Developers can use this field to add their own security features. 256 bytes maximum. Note that this field cannot be null. It must be set to some value, i.e. item ID.

Returns

{ 
    "returnValue"   : boolean, 
    "receipt" : {
         "receiptInfo"   : receipt object,
         "signedReceipt" : string BLOB
     }
    "orderNo"       : int,
    "receiptStatus" : string, 
    "sku"           : string,
    "errorCode"     : string,
    "errorText"     : string    
}

NOTE

The receipt field is returned as a JSON string, not a JSON object. To reference its fields using dot notation, you need to convert it to a JSON object. For example:

var receipt = enyo.json.parse(inResponse.receipt);
var receiptInfo = receipt.receiptInfo;
var purchaseTime = receiptInfo.purchaseTime;

Parameter	Required	Type	Description
returnValue	Yes	boolean	true (success) or false (failure)
receipt	No	JSON string	Returned on successful purchase. Note that this field is a JSON string and not a JSON object. You need to convert it to a JSON object before referencing its fields using standard dot notation.
receiptInfo	No	object	Receipt object.
signedReceipt	No	string BLOB	Signed receipt. Can be used for verification. Base64 encoded.
orderNo	No	int	Order number.
receiptStatus	Yes	string	One of the following: Charged -- Successful purchase Pending -- Purchase pending; the app should use the "orderNo" to poll on getPendingPurchaseInfo. PaymentNotSetup -- If payment is not set up, a UI is launched to do this. If the user cancels this, then "PaymentNotSetup" is returned. ItemAlreadyPurchased -- This non-perishable has already been purchased. PurchaseInProgress -- The purchase process was started, but the modal dialog was dismissed before completion. PurchaseFailed -- The purchase process failed to complete successfully. Cancelled -- The user cancelled the action before the purchase process started or the user pressed the "home" button on the modal dialog.
sku	No	string	Stock Keeping Unit/product number. I.e., "App-com.mycompany.myappid-1.0.3-mygamelevel01".
errorCode	No	string	Numeric code returned on failure.
errorText	No	string	Error text message returned on failure.

Examples

{
   "itemId": "gameLevel2",
   "quantity" : 1,
   "vendorData" : "%^&#;@22##"
}

Example Outputs

Successfully charged to credit card

{
   "returnValue" : true,
   "receipt" : {
      "receiptInfo" : {
         "version" : "1.0",
         "receiptId" : 12340,
         "orderId" : 12345,
         "purchaseTime" : 77778889999,
         "type" : "N",
         "appId" : "com.mycompany.myapp",
         "itemId" : "myitemid",
         "quantity" : 1,
         "vendorData" : <BLOB>,
         "accountUniqueId" : <BLOB>,
         "deviceUniqueId" : <BLOB>
      },
      "signedReceipt" : <BLOB>
    },
   "orderNo" : 1234,
   "receiptStatus" : "Charged",
   "sku" : "App-com.mycompany.myappid-1.0.3-gameleve2"
}

Pending

If a pending status is returned, your app should use the order number to poll on getPendingPurchaseInfo.

{ 
   "returnValue"    : true,  
   "orderNo"       : 12346, 
   "receiptStatus" : "Pending"
}

Failed

If the server cannot make the payment, for example, because of an invalid credit card, a failed status is returned.

{ 
   "returnValue"    : true,  
   "receiptStatus" : "Failed"
}

No Payment Setup

If a payment option is not configured, then the user sees a UI to do this. If the user cancels during this process, the "PaymentNotSetup" status is returned.

{ 
   "returnValue"    : true,  
   "receiptStatus" : "PaymentNotSetup"
}

Documentation

In-App Payment

Methods

getAvailableItems

Syntax

Parameters

Returns

Examples

getItemInfo

Syntax

Parameters

Returns

Example

getPendingPurchaseInfo

Syntax

Parameters

Returns

Example

purchaseItem

Syntax

Parameters

Returns

Examples

Why webOS

Getting Started

Videos

Stay up to date