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    

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

The URL example

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

Intent call

The intent with the URL can be opened either with the browser, useful when the AppCoins Wallet is not installed, or by the AppCoins Wallet. In some cases the user chooses to open the URL with the browser when the AppCoins is already installed or even choosing the option to always open the URL with the browser.
So in order to avoid this problem we suggested the use of the bellow sample to generate the intent to trigger the One Step billing flow.

Intent intent = buildTargetIntent(url);
try {
	startActivityForResult(intent, RC_ONE_STEP);
} catch (Exception e) {
	e.printStackTrace();
}
 
/**
* This method generates the intent with the provided One Steo URL to target the
* AppCoins Wallet.
* @param url The url that generated by following the One Step payment rules
* 
* @return The intent used to call the wallet 
*/
private Intent buildTargetIntent(String url) {
  Intent intent = new Intent(Intent.ACTION_VIEW);
  intent.setData(Uri.parse(url));

  // Check if there is an application that can process the AppCoins Billing
  // flow
  PackageManager packageManager = getApplicationContext().getPackageManager();
  List<ResolveInfo> appsList = packageManager
            .queryIntentActivities(intent, PackageManager.MATCH_DEFAULT_ONLY);
  for (ResolveInfo app : appsList) {
    if (app.activityInfo.packageName.equals("cm.aptoide.pt")) {
      // If there's aptoide installed always choose Aptoide as default to open 
      // url
      intent.setPackage(app.activityInfo.packageName);
      break;
    } else if (app.activityInfo.packageName.equals("com.appcoins.wallet")) {
      // If Aptoide is not installed and wallet is installed then choose Wallet
      // as default to open url
      intent.setPackage(app.activityInfo.packageName);
    }
  }
  return intent;
}

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

XYZ98880032

signature

String

The Hexadecimal string of the signed URL in order to be validated. For more details see section Content Validation

N

Y

49bc6dac9780acfe5419eb16e862cf096994c15f807313b04f5a6ccd7717e78e

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.

signature

49bc6dac9780acfe5419eb16e8
62cf096994c15f807313b04f5a6
ccd7717e78e

The Hexadecimal string of the signed URL in order to be validated. For more details see section Content 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-).

URL Content Validation

For additional security of the URL's, in order to be validated its content the developer can include the signature parameter in the URL. The signature parameter is built as shown bellow, were the URL
is signed using a HMAC function with the use of SHA256 algorithm.
The required secret key should be only available at a server level and should be shared between the developer and provider.
This field is not mandatory for the URL to work.

Note: Avoid having the secret key in the APK. Having the secret key in the APK compromises the security delivered with this step of the URL building, since it can be easily obtained by anyone that has access to APK.

<?php
 
function generate_url(): string
{
    $secret = 'foobar';
   
    $url = '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%3A%2F%2Fwww.mygamestudio.com%2Fappcoins%3Fout_trade_no%3D1234';
   
    $signature = hash_hmac('sha256', $url, $secret, false);
   
    return $url . '&signature=' . $signature;
}
 
echo generate_url();
 
?>

One Step Payment


Suggested Edits are limited on API Reference Pages

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