The Catappult Developer Hub

Welcome to the Catappult developer hub. You'll find comprehensive guides and documentation to help you start working with Catappult as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Other integration methods

In case your app is not automatically migrated and it has in-app purchases, integrate our billing using one of the below solutions.

Unity UDP

Prerequisites

Setting up your game
Open your game and check the version of Unity IAP package.

If you already integrated Unity IAP
Go to Package Manager (Window->Package Manager) or open the AssetStore and search for Unity IAP.

If you went through package manager the version should be at least 2.0.8.
If you went through the Asset Store the version should be 1.22.

OR

Just import this package to have everything setup for you.

Now please go to Integrating UDP with existing Unity IAP.

If you didn't integrate Unity IAP yet
If you don't have IAP setup at all first download the Unity IAP package from here, then set up the in-apps and the UDP part. This is the easiest and cleanest way to get the best results.
You can check more in-depth details about this process here.
Once you're done implementing Unity's IAP you can go to Integrating UDP with existing Unity IAP.

If you already have IAP integrated but using other solution rather than Unity IAP (like Google Play SDK directly) it's better for you to integrate the standalone SDK.

You can check more in-depth details about this process here.

Integrating UDP with existing Unity IAP implementation

If you didn't download the package yet, start by going here and downloading the Unity IAP package with UDP.

Integrate it on Unity and then follow this guide and then for easiness and speed this guide but first take a careful look at the following list of notes that might help you out dodging some possible errors you may encounter during the process:

  • Make sure the product ids for products you create on the catalog are lowercase. This is mandatory for Android but not iOS for example, so Unity doesn't warn you if you have capital letters by mistake. Don't use fullTrajectory use full_trajectory instead.

  • Make sure at the end of Unity IAP's IAP Catalog you have the Automatically initialize UnityPurhcasing checkbox enabled. This is crucial for the process to work with Codeless IAP for instance and sometimes it does not start enabled by default.

  • Don't forget to set up a price in USD on the Unity Distribution Portal section

After you're done creating and setting up your products you're ready for Submitting your game.

Submitting your game

First you need to build an APK of your game.

Before building the APK you need to make sure that the IAP system is targetting UDP. To verify this please go to Window -> Unity IAP -> Android and make sure that Target Unity Distribution Portal is checked.

Now you can build. Click File -> Build Settings. Make sure Android is the platform selected. click build and chose the APK filename.

You’ll have to manually upload it to Unity servers. To do so, on the Services tab, click “Go to dashboard” button.

On the website, after making sure you’re on the Develop tab, click Cloud Build -> Build History -> Upload Build.

On the upload window pick the APK, add a label and select the Android platform. Then click “Upload”.

After the upload is done, pick the latest build, tap the 3 dots button and select “Push to Unity Distribution Platform” option.

Press “Push” on the next popup and wait for the upload to finish.

You'll be taken to the Deployments section showing your latest deploy.

Click "Visit the UDP console" to see your game there.

You'll be taken to a page where you can edit your game's info. After your done, hit the Save Button.

The Save Button turns into a Release button and you can create a new Revision for submission.

Fill in the details and click Create.

On the top tabs press Publish to be taken to the stores listing.

This screen will show all available stores to publish your game. Find Catappult and click to sign up.
If you already have a Catappult account it will be linked to your Unity account. If you don't, one will be created for you with the details fetched from your Unity account.

After registration/merging of your account is done you'll be taken back to UDP portal and you can now register your game on the Catappult portal. Click the "Register your game on Catappult" and make sure the package name is correct.

Click Register.

You'll have to fill in some info about your company details. All fields are mandatory. Click create when done.

With company info filled in you can now click the register button again (this process might take a little bit).
Now you're ready to pick the target step to publish to the stores. On Catappult there are two target steps available:

  • Repack Game - this just applies the store SDK on your game and let's download a preview APK
  • Submit To Store - this step implicitly runs the previous step and then submits the game to the store

Since we don't support a sandbox environment, the APK resulting from the Repack Game won't be of any good by itself. Until the game is registered and uploaded to our portal the services won't work.

Go ahead and pick Submit to Store, tick the Catappult store and on the top right corner click Publish.

After clicking Publish and confirming, you'll be taken to the tab "Status" where you can see that your submission operation is "In Process". As this is a composite operation, you'll get 2 notifications. One when the game is successfully packed, and another when the game was successfully published. This process shouldn't last more than 5 minutes.

That's it!

If you login to Catappult you can now see your game is published and ready to be downloaded by our huge userbase!

Unity plugin

This is the official Unity plugin for the AppCoins Protocol that allows you to integrate AppCoins In-App Billing into your Unity Android game.

About AppCoins Unity Plugin

This plugin is developed to support the AppCoins protocol. Integrating this plugin allows developers to use the AppCoins In-App Billing and the AppCoins Reward campaigns into their games.

Warning!

We fixed the requirement to use the Custom Builld Window so on Unity 2018 you can go back to just using the default build window again! Previous Unity versions still need to build using the Custom Build Window.

Pre requisites to run the project

To successfully run the project you need to do couple of things.

Setup a Wallet

Register on Catappult

  1. Go to the Catappult website and press the Sign Up button. Press the Developer button.
  2. Fill in all the required details.
  3. After this you'll have to read through and accept the Terms of service.
  4. After this you'll have to read through and accept the Certified Developer Distribution Agreement.
  5. Wait a few moments and you should've received a confirmation e-mail on the e-mail account you supplied. Open it and click the Confirm Email link.
  6. You'll be redirected to the Catappult portal and have your account confirmed. You can now login by pressing the Login button, filling in your details and pressing the Login button again.
  7. Congratulations! You're now inside the Catappult portal, ready to upload your first app. To do that press the Add App button.
  8. Now you're asked if you have in-apps in your app. If you do select My app has in-app purchases. and jump to step 12. If you don't, select No in-app purchases and keep going.
  9. Now enter the app's package name and hit Next.
  10. You'll be presented with an accordion with relevant data and info for your app
    10.1 On the Certification tab you can check the status of the certification process (it usually lasts X days)
    10.2 On the In-App Billing tab you can grab the Public Key and the Wallet Address that you will need to integrate our billing in your game
    10.3 On the In-App Products tab you can create your app's products
    10.4 On the Upload App tab you can add your APK (and OBB files if you have them) and press the Upload button.
  11. Only after uploading an APK will the Next button light up and then you can press it. Jump to step 16.
  12. Now enter the app's package name and click the Next button.
  13. Now you're asked to submit an APK and the OBB files of your app if you have any. Press Upload when all relevant data is added.
  14. After the app is uploaded to our servers you need to pick a category, the tittle and the description. Click Finish when done.
  15. The app was successfully created and uploaded! Click Next to go to the app's main page
  16. TODO explain how to certify and create IAPS
    Now you're in your App's home page. There are 3 tabs:
    • Certification - Here you'll be asked to certify the app after you upload it
    • In-App Billing - Here you can create in-app products and get your Public Key
    • Upload App Release - Here you can upload new releases of your app

Integrating the plugin into your game (Testing the sample)

  1. Make sure you carefully went through all the pre requisites.
  2. Download the plugin package corresponding to your Unity version (The supported Unity versions are 2018, 2017 and 5.6). You can find them on the latest release here. Open the package in your Unity project (double click the file or in Unity go to Assets -> Import Package -> Custom Package.... and find the file you just downloaded). Make sure to import the example folder.
  3. Open the example scene.
  4. Make sure you are on the Android platform. Go to File -> Build Settings, select Android and then switch platform.
  1. Go to the AppCoins Menu and Open "Android Custom Build Build".
  2. In AndroidCustomBuildWindow click "Player Settings...".
    7.The PlayerSettings Window will open in the inspector. Go to Other Settings and change the package name to: "com.appcoins.sample", like the image bellow.
  1. Now go back to the AndroidCustomBuildWindow and confirm your gradle path.
  2. After that choose the option "Install build when is done?", and press the confirm Button.
  3. Choose where the APK of the application is stored and Confirm it.
  4. If everything goes well you should see the message: "OnInitialized: PASS" on the top of the phone screen. This means that you have everything correctly setup. You can try the consumable and non-consumable purchases to also see that they work.

NOTE: this will only work on the main network (Ethereum)

Integrating the plugin into your game (Making it work for your game)

  1. Add these imports into your logic class
using Appcoins.Purchasing;
  1. If you have In-app Purchases, define the product ids you created
public static string kYourProductID = "yourSkuID";
public static string kOtherProductID = "otherSkuID";
  1. Define outlet for Purchaser class
private Purchaser _purchaser;
  1. Define OnPurchaseSuccess to process the purchase result
private void OnPurchaseSuccess(AppcoinsProduct product)
{
  Debug.Log("On purchase success called with product: \n skuID: " + product.skuID + " \n type: " + product.productType);

  if (product.skuID == kYourProductID) {
    GiveYourProduct();
  } else if(product.skuID == kOtherProductID) {
    GiveOtherProduct();
  }
}
  1. Setup purchaser with defined product ids and correct product types
void SetupPurchaser() {          
  _purchaser = Purchaser.Create();

  //NOTE: If you want to easily debug the interactions with the Catappult Purchasing system, you can pass an UI.Text label to the Purchaser class
  _purchaser.SetStatusLabel(_statusTxt);

  _purchaser.onInitializeSuccess.AddListener(OnInitializeSuccess);
  _purchaser.onPurchaseSuccess.AddListener(OnPurchaseSuccess);

  _purchaser.AddProduct(kYourProductID, AppcoinsProductType.Consumable);
  _purchaser.AddProduct(kOtherProductID, AppcoinsProductType.NonConsumable);

  //Only call initialize after adding all products!
  _purchaser.InitializePurchasing();
}
  1. Call the function you just created when you want to initialize the Purchasing system. We want it as soon as possible so we add it to the Start method of our logic class.
void Start () {
  //... your code ...
  SetupPurchaser();
}
  1. On the AppCoins top menu, click "AppCoins Plugin Settings"
  2. Fill it in with the appropriate values for Developer Wallet Address and Public Key that you previously stored during the pre-requisites steps. (The default ones are working for the sample app)

NOTE: If you want to get an IAP value in APPC you can easily do that by calling GetAPPCPriceStringForSKU(string skuID) from AppcoinsPurchasing object.

string priceStr = appcoinsPurchasing.GetAPPCPriceStringForSKU(someSkuID);

To build the project

WARNING!

We fixed the requirement to use the Custom Builld Window so on Unity 2018 you can go back to just using the default build window again! Previous Unity versions still need to build using the Custom Build Window.

Go to the build menu (File -> Build Settings)

  1. Check that the build system is set to "Gradle" (if the import was done correctly this should've changed automatically).

Now click Player Settings.
On the Player Settings window:

  1. Click the other settings panel
  2. Make sure you change the package name to your liking (the one defined during app creation on Catappult).
  3. Make sure that you have min sdk version set to 21 (if the import was done correctly this should've changed automatically).

Unity 2018.X

  1. Go to the build menu (File -> Build Settings)
  2. Click Build and Run

Unity 2017.X and below (till Unity 5.6)

  1. Close the Player Settings window
  2. On the top bar click AppCoins
  3. Click Android Custom Build
  4. This popup will show up
  1. The gradle path should be picked from the path to your Android Studio installation. Please check that the version matches your own.
  2. Gradle and Dex heap size are just to be changed if you have issues building.
  3. The adb path will be picked by you (assuming you have Android SDK installed)
  4. Pick the scenes you want to include. The ones added to the build settings, as well as the scene you're currently working on, will automatically be selected for you
  5. When you click Confirm a pop up will show up asking you to pick a folder to generate the Android project to. Pick a folder of your liking preferably inside the project root (it can't be the project root itself).

NOTE: The final build will be located here: FolderYouChoseToBuildTo/ProjectName/build/outputs/apk/ in a subfolder called debug or release, depending on build settings)

  1. When you pick the folder the build process will start. The normal build process will happen and then the custom build process will kick in opening a terminal window. Unity might seem to be not responding but worry not! This is normal because it's waiting for the terminal processes to finish.
  2. If you ticked Install build when done? make sure you have your phone connected to the computer and that you unlock it to allow ADB to install
  3. If you ticked Run build when done? make sure you have your phone connected to the computer and that you unlock it to allow ADB to run
  4. The build process completed. You can run the app on your phone!

To make a signed build

Please check this page Using Unity

First App upload

Time to upload an APK of your app. For the upload to get through there are some mandatory steps that you need to follow.

  • Mandatory: It's mandatory that the APK does NOT feature the Google billing permission. To do this you need to edit the AndroidManifest.xml and remove the line:
<uses-permission android:name="com.android.vending.BILLING" />

If the plugin was correctly integrated this step should be already done for you.

  • Mandatory: The uploaded APK has to be signed (ideally with the same key used for Google Play). Please check this page Using Unity

  • Mandatory: If your app has IAP you have to add the Catappult billing permission to the manifest. If the plugin was correctly integrated this step should be already done for you. To manually add the permission you need to edit the AndroidManifest.xml and add the line uses-permission like so:

=Example AndroidManifest.xml=
<?xml version="1.0" encoding="utf-8"?>
<manifest
  xmlns:android="http://schemas.android.com/apk/res/android"
  package="com.your.app"
  xmlns:tools="http://schemas.android.com/tools"
  android:installLocation="preferExternal">

  ...

  <uses-permission android:name="com.appcoins.BILLING" />

  ...

</manifest>

This app submission will enable the next step: Certification. Your app needs to be certified for the integration to work. You can't even test it before the certification process is done, as the service will act like if your app does not exist.

To certify the app you have two options.

  • If you’re distributing this app on Google Play, with the same package name, we can send you a link to the contact e-mail associated to that app. Simply open the link on that e-mail and your app will be certified. With this method your app is ready to be distributed on Aptoide with no action from the Catappult team.
  • If this package isn’t on Google Play, you can download a blank APK, sign it (with the same key you signed the app you uploaded) and upload it to Catappult. This method will require the Catappult team to review your request to assure the app is indeed yours and is not infringing any Intelectual Property. This process should last no longer than 5 working days.

After this process is done you're finally ready to test the game.

You're DONE! Congrats! :tada+:

Custom Payload Validation

The SDK allows you to have your own payload validation mechanism for extra safety. You can check a working sample of this mechanism on the provided sample. The Logic class acts as our custom validator and simply returns true.

NOTE: If you're reusing the Logic class from the sample and don't want custom payload validation you just have to:

  • remove the IPayloadValidator from the class definition
  • remove the call to SetupCustomValidator on SetupPurchaser function
  • remove the IsValidPayload method from the Logic class.
  • you can skip the rest of this section

If you want to implement custom validation for your purchases' payload you have to follow these steps:

  1. Make sure your validator class implements our inteface IPayloadValidator. (You can reuse the class you created to handle the purchase logic)
public class Logic : MonoBehaviour, IPayloadValidator {

}
  1. Implement the mandatory method that handles the validation.
public bool IsValidPayload(string payload) {
  Debug.Log("Custom payload validation in place! Payload is " + payload);
  //Add your custom code here

  return true; //validates the purchase by default
}
  1. In your purchase logic class, make sure you setup your validation class as a custom validator (in this example they're the same so we pass this as a reference). You can do this in the end of the SetupPurchaser method:
        void SetupPurchaser() {
          ...
          previous code
          ...

          //Setup custom validator with a reference to your class
          _purchaser.SetupCustomValidator(this);
        }

Good practices you should follow

Disable purchase buttons if purchasing is not initialized yet.

Disable purchase buttons for already owned non-consumable buttons.

Versioning

The priority of Catappult and partners is to provide a good user experience to the user of Android apps and games.

Catappult strongly recommends to use:

  • Package ID: the same as in Google Play (e.g. “com.example.myapp”)
  • Developer's signature: the same as in Google Play
  • Vercode: higher than Google Play, by adding an extra digit - different than 0- in the left (e.g.: vercode Play=“573”, vercode Catappult=“1573”)

To know more about this please check the Catappult FAQ

Native Android SDK

Architecture

This guide assumes that you have already Google Play billing integrated in your app. It will help you migrating from the Google Play to Catappult Billing service. Catappult billing service is implemented in a Wallet called "AppCoins Wallet". AppCoins wallet is widely available in different app stores. AppCoins Wallet exposes a Android Service which your app should bind with. Once bound to AppCoinsWallet service, your app can start communicating over IPC using an AIDL interface.

Google Play IAB to AppCoins IAB Migration Guide

Requirements

1. Catappult Public Key
Just like Google Play IAB, AppCoins IAB also exposes a public key. You should use AppCoins IAB public key to verify your purchases. It works exactly like Google Play IAB key, so you just need to replace one for the other.To find your Catappult public key, you should be registered in Catappult Back Office. You should head to Add App section of the BO and add the package name of your app (e.g. com.appcoins.wallet). Please make sure it's the same package name of the APK you'll upload later. Once you insert the package name and click "Next", you should already see your public key.

And change in your code:

        String base64EncodedPublicKey = "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzZZoGzIM+TlYDyGWl78g37ChRtrUWCOTnF8Sy4zwC2vqQhI/QETkYM/jMruY3pLvdDOcdWm9xoZLJq5exxqQyhrZbSoziXQ9bIOJwNSjA/WIJnAewAk8QGPhvjNFy0wflCqLDWflrt04vbvvNsdh9UpgceIdinzqE0MhF94HJr1Ovb5JEMktDgU89SarCsx90a4Psk6cdapulGjdpL35dBRkRkM74sfNmSy8Oan9FaI36+z4h88MgTrELHnQ0XTlS32flvCK7nhICV+bzcY89wPRPN4rkqjS4F5nngwAnaz5VMV0Zy5SZBZntLS1QIA641FxJJHAikM8ZYz3hkTn0QIDAQAB";

2. Wallet Support
In order to use AppCoins, you will need a compliant wallet installed. The following snippets shows how you can prompt the user to install the AppCoins BDS Wallet when not present, otherwise the user will not be able to do the payment.We recommend you to do this validation when the user intends to do a purchase. By doing so, you avoid misleading the user on stating a purchase without the wallet installed. To do that, first validate if an EIP-681 compatible wallet is installed.

if (!hasWalletInstalled(this)) {
    showWalletInstallDialog(this,
    this.getString(R.string.install_wallet_from_iab));
}

Please note that other EIP-681 compatible wallets can be available on the users device and in that case no dialog is prompted and the bind with billing service fails. In this case the installed wallet is not compatible with the Catappult billing system and also in that case the dialog should be prompted suggesting to the user to install the compatible wallet.To check if the wallet is installed, build the EIP-681 compatible URI and validate if there is an application that can handle the intent. It can be done with the following.

public static boolean hasWalletInstalled(Context context) {
    Intent intent = new Intent(Intent.ACTION_VIEW);
    Uri uri = Uri.parse("ethereum:");
    intent.setData(uri);

    return hasHandlerAvailable(intent, context);
  }

The list of applications that can listen to the intent with the EIP-681 compatible URI is checked to be empty. If it is empty, it means that no application to handle the purchase flow is available.

public static boolean hasHandlerAvailable(Intent intent, Context context) {
    PackageManager manager = context.getPackageManager();
    List<ResolveInfo> infos = manager.queryIntentActivities(intent, 0);
    return !infos.isEmpty();
  }

Showing a basic dialog that informs the user of the need to install a compatible wallet can be done with following method. Notice that the dialog generated by this method is basic and provides the minimum required information. The creation of a new dialog is advised, to be compatible with the layout of your application.

private static void showWalletInstallDialog(Context context, String message) {
    AlertDialog.Builder builder;
    builder = new AlertDialog.Builder(context);
    builder.setTitle(R.string.wallet_missing)
        .setMessage(message)
        .setPositiveButton(R.string.install, (dialog, which) -> gotoStore(context))
        .setNegativeButton(R.string.skip, (DialogInterface dialog, int which) -> dialog.dismiss())
        .setIcon(android.R.drawable.ic_dialog_alert)
        .show();
}

If you follow with the use of the code above the resources below are required.

  <string name="install">INSTALL</string>
  <string name="skip">SKIP</string>
  <string name="install_wallet_from_iab">To pay for in-app items, you need to install the AppCoins BDS Wallet.</string>
  <string name="wallet_missing">AppCoins Wallet Missing</string>

The following method is the one used to redirect the user to AppCoins BDS Wallet store page.

@NonNull private static void gotoStore(Context activity) {
    String appPackageName = "com.appcoins.wallet";
    try {
      activity.startActivity(
          new Intent(Intent.ACTION_VIEW, Uri.parse("market://details?id=" + appPackageName)));
    } catch (android.content.ActivityNotFoundException anfe) {
      activity.startActivity(new Intent(Intent.ACTION_VIEW,
          Uri.parse("https://play.google.com/store/apps/details?id=" + appPackageName)));
    }
  }

Integration

1. AIDL
Like Google Play IAB, AppCoins IAB uses an AIDL file in order to communicate with AppCoins service. The AppCoins IAB file is here.
In Android Studio, follow the steps:

  • rename InAppBillingService.aidl (Google AIDL) file to AppcoinsBilling.aidl: in Android Studio, select the file InAppBillingService.aidl, right click and choose the option Refactor -> Rename.) and change it to AppcoinsBilling.aidl.
  • Open AppcoinsBilling.aidl (InAppBillingService.aidl ), erase all the lines and replace by the content of AppCoins AIDL file.
  • the path to the AppcoinsBilling.aidl file needs to follow the package name structure (e.g. aidl/com/appcoins/billing). In the root of yourAndroid studio project, move the file to a new directory:
$ find . -name "*aidl" 
./app/src/main/aidl/com/android/vending/billing/AppcoinsBilling.aidl
$ mkdir -p ./app/src/main/aidl/com/appcoins/billing/
$ mv ./app/src/main/aidl/com/android/vending/billing/AppcoinsBilling.aidl ./app/src/main/aidl/com/appcoins/billing/
  • Change all occurrences of "IInAppBillingService" to "AppcoinsBilling" and also all occurrences of "com.android.vending" to "com.appcoins.billing". Right click on the root of your Java files and choose "Replace in path" option works.

There are some methods of Google Billing (like getBuyIntentToReplaceSkus) that may not be supported yet. In those cases, change the code to use the existent ones.

2. Permissions
Your app needs a permission to allow it to perform billing actions with AppCoins IAB. The permission is declared in the AndroidManifest.xml file of your app. Since Google Play IAB already declares a permission with name com.android.vending.BILLING, you should rename it to com.appcoins.BILLING.### Google Play IAB

<uses-permission android:name="com.android.vending.BILLING" />

AppCoins IAB

<uses-permission android:name="com.appcoins.BILLING" />

3. Service Connection
In order to communicate with AppCoins IAB, your app must bind to a service in the same way as in Google Play IAB. Google Play IAB Intent action and package must be updated from com.android.vending.billing.InAppBillingService.BIND and com.android.vending to com.appcoins.wallet.iab.action.BIND and com.appcoins.wallet, respectively.

Intent serviceIntent = new Intent("com.android.vending.billing.InAppBillingService.BIND");
serviceIntent.setPackage("com.android.vending");

AppCoins IAB Service Intent

Intent serviceIntent = new Intent("com.appcoins.wallet.iab.action.BIND");
serviceIntent.setPackage("com.appcoins.wallet");

You can find & replace in the Android Studio for the above strings. Depending on the approach taken for Google Billing integration, it can be in different files (e.g. IabHelper.java).

Payment Intent

When calling getPaymentIntent method, you must send your developer's Ethereum wallet address. This can be done by using the helper provided here.

...
String payload = PayloadHelper.buildIntentPayload("developer_ethereum_address","developer_payload");
Bundle buyIntentBundle = mService.getBuyIntent(3, mContext.getPackageName(), sku, itemType, payload);

In order to get your developer's Ethereum wallet address, go to Catappult Back Office -> Wallet -> Deposit APPC and click on "copy to clipboard button".

4. Purchase Broadcast
Google Play IAB broadcasts and Intent with action com.android.vending.billing.PURCHASES_UPDATED. Since AppCoins IAB does not implement this, any code related with listening to that Intent can be removed.

Testing

For testing purposes you can use the following data to test the billing of you application. *applicationId: com.appcoins.sample

  • IAB_KEY: MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyEt94j9rt0UvpkZ2jPMZZ16yUrBOtjpIQCWi/F3HN0+iwSAeEJyDw7xIKfNTEc0msm+m6ud1kJpLK3oCsK61syZ8bYQlNZkUxTaWNof1nMnbw3Xu5nuYMuowmzDqNMWg5jNooy6oxwIgVcdvbyGi5RIlxqbo2vSAwpbAAZE2HbUrysKhLME7IOrdRR8MQbSbKEy/9MtfKz0uZCJGi9h+dQb0b69H7Yo+/BN/ayBSJzOPlaqmiHK5lZsnZhK+ixpB883fr+PgSczU7qGoktqoe6Fs+nhk9bLElljCs5ZIl9/NmOSteipkbplhqLY7KwapDmhrtBgrTetmnW9PU/eCWQIDAQAB

Known issues

  • AppCoins IAB is not compliant with Google Play IAB v5. Calls to getBuyIntentToReplaceSkus method will always fail.

One Step Payment

Quickstart

The basic payment interface with AppCoins Wallet is done using an URI (interface) that any Android App can call. That URI defines the basic information needed for a payment: amount, app package, developer wallet,...

That URI follows the EIP-681, with small changes. To differentiate those changes from the original standard, it's called EIP-681A, where the "A" stands for AppCoins changes.

The Android developer can build the URI manually or can use a SDK to make it easier.

HTTPS URI (preferential)

The one-step IAP payment can be triggered in two different ways: an internal Android intent that is only captured by AppCoins EIP-681A wallets and by a Web URL that can be captured for browsers as well. The advantage to use the Web URL is that if the wallet is not installed, the user will be redirected for an app store (Google Play, Aptoide). This method is then suggested.

Technical Steps

Request Parameters

HTTP (web) intent
The gateway URL:

https://apichain.catappult.io/transaction/inapp?value=XXX&currency=XXX&to=XXX&product=XXX&domain=XXX&data=XXX&callback_url=XXX

Request parameters

Parameter
Type
Description_of_field
Static
Optional
Example

value

Double

The value in APPC (AppCoins by default) of the transaction.

N

Y

2.5

currency

String

The currency in which the value is sent, if no currency is sent it is considered APPC (AppCoins).

N

Y

USD or EUR

to

String

The wallet address of the receiver of the transaction. Attention: if your domain is registered on bds, this argument is ignored.

Y

Y

0xda99070eb09ab6ab7e49866c390b01d3bca9d516

product

String

The id of the item being bought.

Y

Y

sword.001

domain

String

The application id, also known as package name.

Y

Y

com.mygamestudio.game

data

String

Additional information to be sent if needed.

N

Y

100 Gems

callback_url

String

The developer's URL to be called after the transaction is completed.

N

Y

https://mygamestudio.co/appcoins?out_trade_no=1234

order_reference

String

Unique identifier of the transaction created by the developer.

N

Y

Callback URL

The composition of the callback URL can contain as query string any parameter relevant to the transaction so that it can be handled on the developer's side. As an example, the following url beside the endpoint contains also a transaction id relevant to the developer.

https://www.mygamestudio.com/v1/appcoins_ipn.php?out_trade_no=2082389608326064

Parameters restriction
There are some ground rules that need to be taken in consideration regarding the parameter combination, when building the URL to call the wallet.

A transaction without product management requires at least the value for the transaction and the package name of the application as below:
https://apichain.catappult.io/transaction/inapp?value=1.50&domain=com.developers.mygame

  • Parameters possible combinations
value
product
domain
callback_url

Note: The currency, to and data parameters are optional. In the case of the value set in the to parameter, if does not match the value defined as the wallet address for the given domain, the value is replaced with the later.

Sync Response

Response Handling
The result of the transaction can be listened by the application with the method:

@Override protected void onActivityResult(int requestCode, int resultCode, Intent data) { ... }

The resultCode indicates if the transaction went successfully (Activity.RESULT_OK) or not (Activity.RESULT_CANCELED)

When the transaction is successful, the data intent also contains the id of the finished transaction and it can be obtained by using the following:

data.getExtras().get("transaction_hash");

Also in the response intent it's possible to get the response code of the transaction with the following:

data.getExtras().getInt(RESPONSE_CODE)

Check in the following table the returned response codes.

Response codes:

Response Code
Description

0

Success

1

User pressed back or canceled a dialog

2

The network connection is down

3

This billing API version is not supported for the type requested

4

Requested product (aka SKU) is not available for purchase

5

Invalid arguments provided to the API

6

Fatal error during the API action

7

Failure to purchase since item is already owned

8

Failure to consume since item is not owned

Samples

HTTP intent example

  • The URL data sample:
Parameter
Value
Description

value

2.5

The value in APPC (AppCoins) of the transaction.

currency

APPC

The currency in which the value is sent. By default is APPC if not set on the URL.

to

0xab949343e6c369c6b17
c7ae302c1debd4b7b61c3

The wallet address of the receiver of the transaction. It can be overridden if does not match with the address defined for the given domain.

product

gems.001

The id of the item being bought.

domain

com.mygamestudio.game

The application id, also known as package name.

data

100 gems

Additional information to be sent if needed.

callback_url

https://www.mygamestudio.com/appcoins?out_trade_no=1234

The URL to be called after the transaction is completed. The URL is afterwards completed with additional parameters for purchase validation.

  • The URL sample:
https://apichain.catappult.io/transaction/inapp?value=2.50&currency=APPC&to=0xab949343e6c369c6b17c7ae302c1debd4b7b61c3&product=gems.001&domain=com.mygamestudio.game&data=100+gems&callback_url=https://www.mygamestudio.com/appcoins?out_trade_no=1234

Async Notification

On top of the synchronous response, EIP-681A payments provides an asynchronous notification service allow you to sync AppCoins transactions with your own servers. The EIP-681A notification service triggers a notification when a completed, canceled or failed event occurs. In order to use this service you must set the callback_url parameter at the EIP-681A URI and prepare your server to receive a sign transaction resource as described below.

Method
POST

  • HTTP request example
https://www.mygamestudio.com/v1/appcoins_ipn.php?out_trade_no=2082389608326064
  • Parameters
Type
Name
Description
Schema
Example

Body

signature

Notification signature based on transaction parameter

string

"0x7b87a3c4dd63bee43d4c88"

Body

transaction

Transaction resource in json

string

  • Transaction parameter fields
    This parameter represents a transaction resource under a json string schema. This data is used to generate the signature parameter that we recommend to be validated as described on the 'Validate transaction resource' section.
{"uid":"ApGuj5aRILeWka8P","domain":"com.mygamestudio.game","product":"sword.001","status":"COMPLETED","added":"2018-11-0211:24:31.815136","modified":"2018-11-0211:26:46.043137","price":{"appc":"1","currency":"USD","value":"0.1"}}
Name
Description
Schema
Example

uid

Unique ID for transaction resource

string

"ApGuj5aRILeWka8P"

domain

Package name

string

"com.mygamestudio.game"

product

Product name (aka SKU)

string

"sword.001"

status

Transaction status

string

"COMPLETED" or "CANCELED" or "FAILED"

added

Transaction added timestmap

string

"2018-11-02 11:24:31.815136"

modified

Transaction modified timestmap

string

"2018-11-02 11:26:46.043137"

price.appc

Transaction price in AppCoins

string

"1"

price.currency

Transaction price currency

string

"USD"

price.value

Transaction price value

string

"0.1"

  • Validate transaction resource
    The transaction resource is signed with your wallet private key. In order to validate if the signature parameter match to the transaction parameter, one of the following examples can be used:
  • (PHP) PHP validation
  • (JS / Node) Javascript validation

PHP Validation

Validate signature belongs to the signing address
To validate the signature belongs to the signing address, we can create a class Signature that will call the method personalEcRecover from Ethereum\EcRecover:

<?php

namespace Signature;

use Ethereum\EcRecover;
use Ethereum\DataType\EthD;
 
 /**
 * Class that validates sender signature
 *
 */
class Signature
{ 

  /**
   * @dataProvider ecRecover
   *
   * @param $address
   * @param $transaction
   * @param $signature
   *
   * @returns bool
   *
   * @throws \Exception
   */
    public function checkMatch($address, $transaction, $signature)
    {
      $recoveredAddr = Ethereum::personalEcRecover($transaction, new EthD($signature) );
      $isEqual = $address ==  $recoveredAddr;
      return $isEqual;
    }

}

?>

Javascript Validation

Validate signature belongs to the signing address
To validate the signature belongs to the signing address, we can use the method recover from web3.eth.account.recover:

function checkSignatureMatch(signingAddress, transaction, signature) {
  var expectedSigningAddress = web3.eth.accounts.recover(transaction, signature);
  var isEqual = expectedSigningAddress === signingAddress;
  return isEqual;
}

Error Codes

Response Codes of Sync request
As stated in Sync response page, there are the following error codes in the return of the sync request:

Response Code
Description

0

Success

1

User pressed back or canceled a dialog

2

The network connection is down

3

This billing API version is not supported for the type requested

4

Requested SKU is not available for purchase

5

Invalid arguments provided to the API

6

Fatal error during the API action

7

Failure to purchase since item is already owned

8

Failure to consume since item is not owned

Transaction Validation

After a transaction occurs, you can validate the transaction from your servers.
For that, use the following endpoint:

https://api.blockchainds.com/broker/8.20180518/transactions?reference=87b3984e01a7497389b0ecfdd9164703

The "reference" field (e.g. 87b3984e01a7497389b0ecfdd9164703 above) is called order_reference in the One-step payment URL (https://docs.catappult.io/docs/app-not-available-on-google-play#section--request-parameters-).

Other integration methods


In case your app is not automatically migrated and it has in-app purchases, integrate our billing using one of the below solutions.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.