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


Methods


Note

To test your app in the SDK environment, your device's Palm Profile email address must be the same as the email address associated with your dev portal account.


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"
}