samsung in-app purchase programming guide eng
TRANSCRIPT
Samsung In App Purchase v2.0
Programming Guide
Revision History
Version Description Author Date
1.0 Created 13.04.15
2.0.1 Security-related content added 13.06.04
2.0.2 Mode parameter added to getItemList method 13.06.12
Table of Contents 1. Samsung In App Purchase v2.0 ..................................................................................................................................... 4
1.1 Product Purchase ............................................................................................................................................................. 4
1.2 Product Type .................................................................................................................................................................... 5
2. Creating an IAP Link ....................................................................................................................................................... 6
2.1 Adding the IAP Library ................................................................................................................................................. 6
2.2 Adding Permissions ........................................................................................................................................................ 6
2.3 Installing IAP and Authorizing Samsung Account ................................................................................................. 7
2.4 Creating ServiceConnection and Binding IAPConnector ..................................................................................... 9
2.5 Processing the IAP Request and Response with IAPConnector....................................................................... 10
① init() method ...................................................................................................................................................... 10
② getItemList() method ....................................................................................................................... 11
③ getItemsInbox() method ................................................................................................................. 11
④ Payment ........................................................................................................................................................... 12
3. IAP Reference ................................................................................................................................................................. 20
3.1 API Reference ............................................................................................................................................................... 20
① init method ................................................................................................................................................ 20
② getItemList method ............................................................................................................................ 21
③ getItemsInbox method ....................................................................................................................... 22
④ PaymentMethodListActivity ......................................................................................................... 22
3.2. Response Code ............................................................................................................................................................ 23
1. Samsung In App Purchase v2.0
IAP (In-App Purchase) v2.0 lets you use Samsung’s payment services inside apps. While v1.0 linked to the
library jar file, v2.0 uses the AIDL (Android Interface Definition Language) to help the IAP process and
applications communicate with each other. The latter makes it easier to link than the former.
1.1 Product Purchase
The below figure shows the process where an application uses IAP to request the purchase of a product.
① Proceed with the Samsung account authorization process.
② Bind IAPConnector to enable the IAP API.
③ Call the init() method start resetting IAP and receive the results as a bundle.
④ Call the getItemList() method to receive a list of purchasable products as a bundle.
⑤ Select a product to purchase and call the startActivityForResult() method to call an activity
(PaymentMethodListActivity) for selecting a payment method. Then, receive the results as a bundle in
the onActivityResult() method.
⑥ Call the getItemsInbox() method to receive a list of purchased products as a bundle.
⑦ When the entire process ends, unbind IAPConnector to finish using IAP.
1.2 Product Type IAP supports the following product types.
Type Description
Consumable Product
If you purchase and use this type of product, it is consumed. You need to repurchase
it to use it again. e.g. Consumable products such as bullets in games.
Non-Consumable Product
If you purchase this type of product, you can keep using it permanently. You cannot
repurchase it. e.g. Non-consumable products such as a book that you do not have to purchase
again.
Subscription (short-term product)
Products that you can repurchase after a certain period of time. e.g. Products such as monthly magazines and short-term passes that can be
repurchased after a certain time. All All of the three types above are included.
2. Creating an IAP Link In order to use the IAP payment service in an application, you must follow the steps below.
① Add the IAP library.
② Add permissions.
③ Install IAP and authorize your Samsung account.
④ Create a ServiceConnection and bind it to IAPConnector.
⑤ In the application, request IAP with IAPConnector and process the response.
2.1 Adding the IAP Library The 'IAPConnector.aidl' and 'IAPServiceCallback.aidl' files are AIDL (Android Interface Definition
Language) files with the IAP interfaces defined. They use the IPC (Inter-Process Communication) method to
provide interfaces for linking with the IAP process. In order to link with IAP, add these files to your application
projects as below.
If you use Eclipse:
Step 1) Create a package with the name 'com.sec.android.iap' under the src folder of the application
project that will use IAP.
Step 2) Copy the 'IAPConnector.aidl' and 'IAPServiceCallBack.aidl' files under the
'com.sec.android.iap' package.
If you do not use Eclipse:
Step 1) Create a folder with the structure 'src/com/sec/android/iap'.
Step 2) Copy the files 'IAPConnector.aidl' and 'IAPServiceCallBack.aidl' in the new folder.
Step 3) Use the Ant tool to build a project and create the 'IAPConnector.java' and
'IAPServiceCallback.java' files.
Through the process above, create the 'IAPConnector.java' and 'IAPServiceCallback.java' files that were
created in the application project '/gen' folder.
2.2 Adding Permissions In order to use IAP, you must register the "com.sec.android.iap.permission.BILLING" permission in the
AndroidManifest.xml file.
Add the permission to AndroidManifest.xml as below.
<uses-permission android:name="com.sec.android.iap.permission.BILLING"/>
! If you do not register the permission, it will always fail in the next step, the Samsung account authorization
process
2.3 Installing IAP and Authorizing Samsung Account
Checking IAP installation
Intent serviceIntent = new Intent( "com.sec.android.iap.service.iapService"
);
Boolean flag = getPackageManager().queryIntentServices( serviceIntent, 0 ).i
sEmpty()
If the flag value in the above code is false, it means that IAP is already installed. If it is true, it means IAP is not
installed.
If IAP is installed: Test the validity of the installed IAP by comparing the signature hash codes of the IAP package.
public class IAPUtils
{
private static final int IAP_SIGNATURE_HASHCODE = 0x7a7eaf4b;
public static boolean isValidIAPPackage( Context _context )
{
boolean result = true;
try
{
Signature[] sigs = _context.getPackageManager().getPackageInfo(
SamsungIAPHelper.IAP_PACKAGE_NAME,
PackageManager.GET_SIGNATURES ).signatures;
if( sigs[0].hashCode() != IAP_SIGNATURE_HASHCODE )
{
result = false;
}
}
catch( Exception e )
{
e.printStackTrace();
result = false;
}
return result;
}
}
If the validity test of the installed IAP reveals that the IAP is not valid, a message dialog must be
displayed as shown below, and the payment process must not proceed any further.
// If the installed IAP package is not valid:
// ================================================================
if( false == IAPUtils.isValidIAPPackage( _activity ) )
{
new AlertDialog.Builder( _activity )
.setTitle( R.string.in_app_purchase )
.setMessage( R.string.invalid_iap_package )
.setPositiveButton( android.R.string.ok,
new DialogInterface.OnClickListener()
{
@Override
public void onClick( DialogInterface dialog, int which )
{
dialog.dismiss();
_activity.finish();
}
} ).show();
}
// ================================================================
If the installed IAP is valid, proceed with the Samsung account authorization process as below. You can move
on to the next step if the account is successfully authorized. // If the installed package is valid:
// ================================================================
else
{
ComponentName com = new ComponentName( "com.sec.android.iap",
"com.sec.android.iap.activity.AccountActivity" );
Intent intent = new Intent();
intent.setComponent( com );
_activity.startActivityForResult( intent, 1001 );
}
// ================================================================
Call the IAP AccountActivity to authorize the Samsung account. AccountActivity is used to authorize your
Samsung account and reconfirm your password when you make a payment.
When you call AccountActivity, the application uses the startActivityForResult method to call it, and IAP
returns the ‘Samsung account authorization’ results to the onActivityResult method in the application.
onActivityResult method
@Override
protected void onActivityResult( int _requestCode, int _resultCode, Intent _
intent )
{
if( _requestCode == 1001 )
{
if( _resultCode == RESULT_OK )
{
/* Login successful */
}
}
}
If IAP is not installed: To install IAP, go to the IAP details page at Samsung Apps.
static final int FLAG_INCLUDE_STOPPED_PACKAGES = 32;
Intent intent = new Intent();
intent.setData( Uri.parse( "samsungapps:// ProductDetail/com.sec.android.ia
p" ) );
// For Honeycomb MR1 or higher, add the FLAG_INCLUDE_STOPPED_PACKAGES flag.
if( Build.VERSION.SDK_INT >= 12 )
{
intent.addFlags( Intent.FLAG_ACTIVITY_NEW_TASK |
Intent.FLAG_ACTIVITY_CLEAR_TOP |
FLAG_INCLUDE_STOPPED_PACKAGES );
}
else
{
intent.addFlags( Intent.FLAG_ACTIVITY_NEW_TASK |
Intent.FLAG_ACTIVITY_CLEAR_TOP );
}
startActivity( intent );
2.4 Creating ServiceConnection and Binding IAPConnector To communicate with IAP in applications, you must create a ServiceConnection. Please follow the steps below.
① Binding IAPConnector
② Unbinding When Closing an Application
① Binding IAPConnector To connect to IAP in applications, implement ServiceConnection in an Activity and bind IAPConnector. After
creating ServiceConnection, use the overridden methods onServiceDisconnected and onServiceConnected to
refer to IAPConnector instances.
IAPConnector mIAPConnector;
ServiceConnection mServiceConn = new ServiceConnection()
{
@Override
public void onServiceDisconnected( ComponentName name )
{
mIAPConnector = null;
}
@Override
public void onServiceConnected( ComponentName name, IBinder service )
{
mIAPConnector = IAPConnector.Stub.asInterface( service );
}
};
Bind using the bindService method that has the intent that is referred to for IAP service names and created
ServiceConnection objects as parameters.
Intent serviceIntent = new Intent( "com.sec.android.iap.service.iapService"
);
bindService( serviceIntent, mServiceConn, Context.BIND_AUTO_CREATE );
When you complete the process above, you can use mIAPConnector to communicate with IAP.
② Unbinding When Closing an Application You must unbind IAP when closing applications. If IAP is no longer needed, you must unbind the Service Connection object that was created above under the
name mServiceConn.
unbindService( mServiceConn );
2.5 Processing the IAP Request and Response with IAPConnector IAP provides the interfaces below.
Type Name Description Method init Setting and resetting of information for using payment services. Method getItemList List of products. Method getItemsInbox List of purchased products. Activit
y
PaymentMethodListAct
ivity
Activity for selecting a payment method and requesting payment.
Each interface is described in detail below.
① init() method This must be called before you use any IAP services, including 'List of products', 'List of purchased products',
and 'Payment'. After the Samsung account is successfully authorized, call the init() method to set basic required payment
information. The init() method sets up the following basic information to use in IAP: IAP upgrade check, server URL,
country code, shop ID, currency (currency unit) information, user ID, and email.
※ Note: If you call the init() method on the main thread, an ANR (Application Not Responding) might
occur. Create a separate thread to avoid the error.
Bundle result = mIAPConnector.init( mMode );
if ( null != bundle )
{
int statusCode = bundle.getInt( "STATUS_CODE" );
String errorString = bundle.getString( "ERROR_STRING" );
if ( statusCode == 0 )
{
/* Successful */
}
}
If 'STATUS_CODE' is '0', the initial setup has successfully completed and you can use the services, including
'List of products', 'List of purchased products', and 'Payment'.
② getItemList() method
This returns the ‘List of purchasable products’ as a bundle.
※ Note: If you call the getItemList() method on the main thread, an ANR (Application Not
Responding) might occur. Create a separate thread to avoid the error.
Bundle itemList = mIAPConnector.getItemList( mMode,
getPackageName(),
_itemGroupId,
_startNum,
_endNum,
_itemType );
Information about whether the request was successful or not is saved in 'STATUS_CODE', the key value of the
returned bundle. (If successful, '0'.)
Using RESULT_LIST inside a Bundle
int statusCode = bundle.getInt( "STATUS_CODE" );
if ( statusCode == 0 )
{
ArrayList<String> arrayList = bundle.getStringArrayList( "RESULT_LIST"
);
for ( String itemString : arrayList)
{
JSONObject jObject = new JSONObject( itemString );
String itemId = jObject.getString( "mItemId" );
String itemName = jObject.getString( "mItemName" );
String itemPrice = jObject.getString( "mItemPrice" );
String currencyUnit = jObject.getString( "mCurrencyUnit" );
String itemDesc = jObject.getString( " mItemDesc" );
String itemImageUrl = jObject.getString( "mItemImageUrl" );
String itemDownloadUrl = jObject.getString( "mItemDownloadUrl" );
String reserved1 = jObject.getString( "mReserved1" );
String reserved2 = jObject.getString( "mReserved2" );
String type = jObject.getString( "mType" );
}
}
③ getItemsInbox() method
This returns the ‘List of purchased products’ as a bundle.
※ Note: If you call the getItemsInbox() method on the main thread, an ANR (Application Not
Responding) might occur. Create a separate thread to avoid the error.
Bundle itemsInboxList = mIAPConnector.getItemsInbox( mContext.getPackageNam
e(),
_itemGroupId,
_startNum,
_endNum,
_startDate,
_endDate );
Information about whether the request was successful or not is saved in 'STATUS_CODE', the key value of the
returned bundle. (If successful, '0'.)
Using RESULT_LIST inside a Bundle
int statusCode = bundle.getInt( "STATUS_CODE" );
if ( statusCode == 0 )
{
ArrayList<String> arrayList = bundle.getStringArrayList( " RESULT_LIST"
);
for ( String itemString : arrayList)
{
JSONObject jObject = new JSONObject( itemString );
String itemId = jObject.getString( "mItemId" );
String itemName = jObject.getString( "mItemName" );
String itemDesc = jObject.getString( " mItemDesc " );
String itemPrice = jObject.getString( "mItemPrice" );
String currencyUnit = jObject.getString( " mCurrencyUnit " );
String itemImageUrl = jObject.getString( " mItemImageUrl " );
String itemDownloadUrl = jObject.getString( " mItemDownloadUrl " );
String purchaseDate = jObject.getString( " mPurchaseDate " );
long timeInMillis = Long.parseLong( jObject.getString( "mPurchaseDate
" ) );
String paymentId = jObject.getString( "mPaymentId" );
String reserved1 = jObject.getString( "mReserved1" );
String reserved2 = jObject.getString( "mReserved2" );
String type = jObject.getString( "mType" );
String itemPriceString = jObject.getString( "mItemPriceString" );
}
}
④ Payment
Make the process so that you can go to the IAP ‘Payment’ Activity where you can pay for a
product.
Bundle bundle = new Bundle();
bundle.putString( "THIRD_PARTY_NAME", getPackageName() );
bundle.putString( "ITEM_GROUP_ID", _itemGroupId );
bundle.putString( "ITEM_ID", _itemId );
ComponentName com = new ComponentName( "com.sec.android.iap",
"com.sec.android.iap.activity.PaymentMethodListActivity"
);
Intent intent = new Intent( Intent.ACTION_MAIN );
intent.addCategory( Intent.CATEGORY_LAUNCHER );
intent.setComponent( com );
intent.putExtras( bundle );
startActivityForResult( intent, 1000 );
When you call the IAP ‘Payment Details’ Activity, the application uses the startActivityForResult
method to call it, and IAP returns the payment results in the application’s onActivityResult method.
onActivityResult method
Data for the payment intent’s 'RESULT_OBJECT' key is returned as a JSON string as illustrated below.
{
"mItemDesc":"Learn about the books of the Bible##46;",
"mCurrencyUnit":"¡Ì",
"mItemImageUrl":"http:\/\/img.samsungapps.com\/product\/2013\/0510\/000
000524646\/IconImage_20130510095823098_NEW_WEB_ICON.png",
"mItemDownloadUrl":"",
"mPaymentId":"ZPMTID20130603GBI0000376",
"mItemPrice":1,
"mVerifyUrl":"https:\/\/iap.samsungapps.com\/iap\/appsItemVerifyIAPRece
ipt.as?protocolVersion=2.0",
"mItemName":"Books",
"mPurchaseDate":1370253642115,
"mPurchaseId":"524822074a3a8671102cbe35bf033f59bcb6f9ec79a950ab5d83de67
b3ff92f8",
"mReserved1":"",
"mReserved2":"",
"mItemId":"000000057508",
"mItemPriceString":"¡Ì1.00"
}
You can get a desired value by creating a JSON object as below. Additional values such as STATUS_CODE,
THIRD_PARTY_NAME, ERROR_STRING and ITEM_ID are included in the bundle.
// 1. Processing IAP payment results:
// treat result of IAPService
// ========================================================================
====
if( _requestCode == 1 )
{
if( null == _intent )
{
return;
}
Bundle extras = _intent.getExtras();
String itemId = "";
String thirdPartyName = "";
// payment success : 0
// payment cancelled : 1
// =====================================================================
===
int statusCode = 1;
// =====================================================================
===
String errorString = "";
String purchaseData = "";
// 1) If there is bundle information transferred from IAP:
// ---------------------------------------------------------------------
---
if( null != extras )
{
thirdPartyName = extras.getString( "THIRD_PARTY_NAME" );
statusCode = extras.getInt( "STATUS_CODE" );
errorString = extras.getString( "ERROR_STRING" );
itemId = extras.getString( "ITEM_ID" );
purchaseData = extras.getString( "RESULT_OBJECT" );
}
// ---------------------------------------------------------------------
---
// 2) If there is no bundle information transferred from the IAP:
// ---------------------------------------------------------------------
---
else
{
showResultDialog(
getString( R.string.dlg_title_payment_error ),
getString( R.string.msg_payment_was_not_processed_successfully )
);
}
// ---------------------------------------------------------------------
---
// 3) If payment is not cancelled:
// If payment was not cancelled
// ---------------------------------------------------------------------
---
if( RESULT_OK == _resultCode )
{
try
{
JSONObject jObject = new JSONObject( purchaseData );
String paymentId = jObject.getString( "mPaymentId" );
String itemDesc = jObject.getString( "mItemDesc" );
String itemPrice = jObject.getString( "mItemPrice" );
String currencyUnit = jObject.getString( "mCurrencyUnit" );
String itemImageUrl = jObject.getString( "mItemImageUrl" );
String itemName = jObject.getString( "mItemName" );
String purchaseDate = jObject.getString( "mPurchaseDate" );
long timeInMillis = Long.parseLong( jObject.getString("mPurchaseD
ate") );
String purchaseId = jObject.getString( "mPurchaseId" );
String reserved1 = jObject.getString( "mReserved1" );
String reserved2 = jObject.getString( "mReserved2" );
String itemDownloadUrl = jObject.getString( "mItemDownloadUrl" );
itemId = jObject.getString( "mItemId" );
String itemPriceString = jObject.getString( "mItemPriceString" );
String verifyUrl = jObject.getString( "mVerifyUrl" );
// a. If the payment result is success:
// --------------------------------------------------------------
--
if( statusCode == 0 )
{
String serverUrl = verifyUrl + "&purchaseID=" + purchaseId;
new VerifyClientToServer( serverUrl,
purchaseId,
paymentId ).execute();
}
// --------------------------------------------------------------
--
b. If the payment result is failure:
// --------------------------------------------------------------
--
else
{
showResultDialog(
getString( R.string.dlg_title_payment_error ),
"-itemId : " + itemId +
"\n-thirdPartyName : " + thirdPartyName +
"\n-statusCode : " + statusCode +
"\n-errorString : " + errorString );
}
// --------------------------------------------------------------
--
}
catch( JSONException e )
{
e.printStackTrace();
}
}
// ---------------------------------------------------------------------
---
// 4) If payment is canceled:
// If payment was cancelled
// ---------------------------------------------------------------------
---
else if( RESULT_CANCELED == _resultCode )
{
showResultDialog(
getString( R.string.dlg_title_payment_cancelled ),
"-itemId : " + itemId +
"\n-thirdPartyName : " + thirdPartyName +
"\n-statusCode : " + statusCode );
}
// ---------------------------------------------------------------------
---
}
// ========================================================================
====
In order to prevent problems caused by sniffing apps during payment result processing, use the mVerifyUrl and
mPurchaseID values in the bundle that came as a result, to check if the payment is valid for the IAP server. For
that purpose, VerifyClientToServer AsyncTask is run in the above example. Below is source code for
VerifyClientToServer AsyncTask.
private class VerifyClientToServer extends AsyncTask<Void, Void, Boolean>
{
String mServerUrl = null;
String mPurchaseId = null;
String mPaymentId = null;
VerificationVO mVerificationVO = null;
public VerifyClientToServer
(
String _strUrl,
String _purchaseId,
String _paymentId
)
{
mServerUrl = _strUrl;
mPurchaseId = _purchaseId;
mPaymentId = _paymentId;
}
@Override
protected void onPreExecute()
{
super.onPreExecute();
// Cancel the task if the server URL, mPurchasedId and mPaymentId are empty.
// ================================================================
if( true == TextUtils.isEmpty( mServerUrl ) ||
true == TextUtils.isEmpty( mPurchaseId ) ||
true == TextUtils.isEmpty( mPaymentId) )
{
this.cancel( true );
}
// ================================================================
mProgressDialog = showProgressDialog( ItemList.this );
}
@Override
protected void onCancelled()
{
dismissProgressDialog( mProgressDialog );
super.onCancelled();
}
@Override
protected Boolean doInBackground( Void... params )
{
try
{
int retryCount = 0;
String strResponse = null;
// For reliability, if an error occurs, retry up to 3 times.
// =============================================================
do
{
strResponse = getHttpGetData( mServerUrl,
10000,
10000 );
retryCount++;
}
while( retryCount < 3 &&
true == TextUtils.isEmpty( strResponse ) );
// =============================================================
if( strResponse == null || TextUtils.isEmpty( strResponse ) )
{
return false;
}
else
{
mVerificationVO = new VerificationVO( strResponse );
// Only if Status Code is "true", and if PaymentId and
// mPaymentId of mVerificationVO match, determine as success.
// ==========================================================
if( mVerificationVO != null &&
true == "true".equals( mVerificationVO.getmStatus() ) &&
true == mPaymentId.equals(
mVerificationVO.getmPaymentId() ) )
{
return true;
}
// ==========================================================
else
{
return false;
}
}
}
catch( Exception e )
{
e.printStackTrace();
return false;
}
}
@Override
protected void onPostExecute( Boolean result )
{
dismissProgressDialog( mProgressDialog );
if( true == result )
{
showResultDialog(
getString( R.string.dlg_title_payment_success ),
"-itemId : " + mVerificationVO.getmItemId() +
"\n-paymentId : " + mVerificationVO.getmPaymentId() );
}
else
{
showResultDialog(
getString( R.string.dlg_title_payment_error ),
getString( R.string.msg_invalid_purchase ) );
}
}
private String getHttpGetData
(
final String _strUrl,
final int _connTimeout,
final int _readTimeout
)
{
String strResult = null;
URLConnection con = null;
HttpURLConnection httpConnection = null;
BufferedInputStream bis = null;
ByteArrayOutputStream buffer = null;
try
{
URL url = new URL( _strUrl );
con = url.openConnection();
con.setConnectTimeout(10000);
con.setReadTimeout(10000);
httpConnection = (HttpURLConnection)con;
httpConnection.setRequestMethod("GET");
httpConnection.connect();
int responseCode = httpConnection.getResponseCode();
if( responseCode == 200 )
{
bis = new BufferedInputStream(
httpConnection.getInputStream(),
4096 );
buffer = new ByteArrayOutputStream( 4096 );
byte [] bData = new byte[ 4096 ];
int nRead;
while( ( nRead = bis.read( bData, 0, 4096 ) ) != -1 )
{
buffer.write( bData, 0, nRead );
}
buffer.flush();
strResult = buffer.toString();
}
}
catch( Exception e )
{
e.printStackTrace();
}
finally
{
if( bis != null )
{
try { bis.close(); } catch (Exception e) {}
}
if( buffer != null )
{
try { buffer.close(); } catch (IOException e) {}
}
con = null;
httpConnection = null;
}
return strResult;
}
}
In the VerifyClientToServer example above, strResponse is JSON formatted as shown below.
{
"itemId":"000000057507",
"itemName":"Additional Game Modes",
"itemDesc":"Unlock all game modes. Best value!",
"purchaseDate":"2013-06-03 21:04:50",
"paymentId":"ZPMTID20130603GBI0000384",
"paymentAmount":"1.500",
"status":"true"
}
You can receive strResponse from the server and extract a desired value, such as the creator of the verification
class below. The example below is part of the VerificationVO source used as an object for saving task results in
VerifyClientToServer AsyncTask.
public class VerificationVO
{
private String mItemId;
private String mItemName;
private String mItemDesc;
private String mPurchaseDate;
private String mPaymentId;
private String mPaymentAmount;
private String mStatus;
public VerificationVO( String strJson )
{
try
{
JSONObject jObject = new JSONObject( strJson );
mItemId = jObject.getString( "itemId" );
mItemName = jObject.getString( "itemName" );
mItemDesc = jObject.getString( "itemDesc" );
mPurchaseDate = jObject.getString( "purchaseDate" );
mPaymentId = jObject.getString( "paymentId" );
mPaymentAmount = jObject.getString( "paymentAmount" );
mStatus = jObject.getString( "status" );
}
catch( JSONException e )
{
e.printStackTrace();
}
}
Omitted…
}
For safer transactions, you can process tasks such as VerifyClientToServer in the above sample
code through a 3rd-party server. If you deliver mVerifyUrl, mPurchaseId and mPaymentId from the client to
the 3rd
-party server, processing is possible on the server in the form shown in the above example.
3. IAP Reference This chapter provides reference information to use IAP.
3.1 API Reference This is the API defined in the 'IAPConnector.java' and 'IAPServiceCallback.java' files.
① init method
init( int mode )
This method must be called before you use IAP services, including 'List of products', 'List of purchased
products', and 'Payment Details'. It returns results as a bundle.
- Parameter details Parameter Type Description
mode int
Value for IAP mode
0: Live (production) mode
1: Development mode (returned results are true every time)
-1: Development mode (returned results are false every time)
- Key descriptions for returned bundle Parameter Description
STATUS_CODE Result code (If not 0, error or failure)
ERROR_STRING Message in case of an error or failure
- STATUS_CODE types for result bundle Response code Code value Description
IAP_ERROR_NONE 0 Successful
IAP_ERROR_INITIALIZATION -1000 Failure while resetting IAP
IAP_ERROR_NEED_APP_UPGRADE -1001 IAP upgrade required
IAP_ERROR_COMMON -1002 Error while running IAP
② getItemList method
getItemList( String packageName, String itemGroupId, int startNum, int
endNum, String itemType )
This method returns the ‘List of purchasable products’ as a bundle.
- Parameter details Parameter Type Description
mode int
Value for IAP mode
0: Live (production) mode
1: Development mode (returned results are true every time)
-1: Development mode (returned results are false every time)
packageName String Package name of the application
itemGroupId String Group ID of the product
startNum int Starting number of the list to be shown
endNum int Ending number of the list to be shown
itemType String
Item type
Consumable: 00
Non-consumable: 01
Subscription (short-term): 02
All: 10
- Key descriptions for returned bundle Parameter Description
STATUS_CODE Result code (If not 0, error or failure)
ERROR_STRING Message in case of an error or failure
RESULT_LIST Product list as a JSON string
- STATUS_CODE types for result bundle Response code Code value Description
IAP_ERROR_NONE 0 Successful
IAP_ERROR_COMMON -1002 Error while running IAP
IAP_ERROR_PRODUCT_DOES_NOT_EXI
ST -1005 No product list requested
- JSON field description for Bundle 'RESULT_LIST' Parameter Description
mItemId Product ID
mItemName Product name
mItemPrice Product price
mCurrencyUnit Currency
mItemDesc Product description
mItemImageUrl Product image URL
mItemDownloadUrl Product download URL
mReserved1 Reserved 1
mReserved2 Reserved 2
mType Product type
③ getItemsInbox method
getItemsInbox( String packageName, String itemGroupId, int startNum, int
endNum, String startDate, String endDate ) method
This method returns the ‘List of purchased products’ as a bundle.
- Parameter details Parameter Type Description
packageName String Package name of the application
itemGroupId String Group ID of the product
startNum int Starting number of the list to be shown
endNum int Ending number of the list to be shown
startDate String Start date of the purchase period (e.g. 20130422)
endDate String End date of the purchase period (e.g. 20130430)
- Key descriptions for returned bundle Parameter Description
STATUS_CODE Result code (If not 0, error or failure)
ERROR_STRING Message in case of an error or failure
RESULT_LIST Purchased product list as a JSON string
- STATUS_CODE types for result bundle Response code Code value Description
IAP_ERROR_NONE 0 Successful
IAP_ERROR_COMMON -1002 Error while running IAP
- JSON field description for Bundle 'RESULT_LIST' Parameter Description
mItemId Product ID
mItemName Product name
mItemPrice Product price
mItemPriceString Currency + product price mItemDesc Product description
mCurrencyUnit Currency
mPurchaseDate Purchase date (in milliseconds)
mPaymentId Payment ID
mPurchaseId Purchase ID
mItemImageUrl Product image URL
mItemDownloadUrl Product download URL
mReserved1 Reserved 1
mReserved2 Reserved 2
mType Product type
④ PaymentMethodListActivity
This section explains the required bundle information and results that are delivered when the IAP payment
feature is used.
- Required bundle information at the time of request Parameter Type Description
packageName String Package name of the application
itemGroupId String Group ID of the product
itemId String Product ID
- Key descriptions for returned bundle Parameter Description
STATUS_CODE Result code (If not 0, error or failure)
ERROR_STRING Message in case of an error or failure
RESULT_OBJECT Payment result as a JSON string
ITEM_ID ID of the product to purchase
- STATUS_CODE types for result bundle Response code Code value Description
IAP_ERROR_NONE 0 Successful
IAP_PAYMENT_IS_CANCELED 1 Payment canceled
IAP_ERROR_COMMON -1002 Error while running IAP
IAP_ERROR_ALREADY_PURCHASED -1003 The product is a non-consumable product and cannot
be repurchased
IAP_ERROR_WHILE_RUNNING -1004 Called payment details without bundle information
IAP_ERROR_CONFIRM_INBOX -1006
The payment results were not successful, but the list
of purchased products needs to be checked because
the product could have been purchased
- JSON field description for Bundle 'RESULT_OBJECT'
Parameter Description
mItemId Product ID
mItemName Product name
mItemDesc Product description
mItemPrice Product price
mItemPriceString Product price with currency
mCurrencyUnit Currency
mPaymentId Payment ID
mPurchaseDate Purchase date (in milliseconds)
mPurchaseId Purchase ID
mReserved1 Reserved 1
mReserved2 Reserved 2
mItemImageUrl Product image URL
mItemDownloadUrl Product download URL
3.2. Response Code The below is a list of codes for 'STATUS_CODE', the key value of the bundle returned from IAP.
Response code Code value Description
IAP_ERROR_NONE 0 Successful
IAP_PAYMENT_IS_CANCELED 1 Payment canceled
IAP_ERROR_INITIALIZATION -1000 Failure while resetting IAP
IAP_ERROR_NEED_APP_UPGRADE -1001 IAP upgrade required
IAP_ERROR_COMMON -1002 Error while running IAP
IAP_ERROR_ALREADY_PURCHASED -1003 The product is a non-consumable product and cannot
be repurchased IAP_ERROR_WHILE_RUNNING -1004 Called payment details without bundle information
IAP_ERROR_PRODUCT_DOES_NOT_EXI
ST -1005 No product list requested
IAP_ERROR_CONFIRM_INBOX -1006 The payment results were not successful, but the list
of purchased products needs to be checked because
the product could have been purchased