One-Step Payment
Overview
The One-Step Payment (OSP) is the simplest method for purchases using AppCoins. To implement it, the developer must create a URL with the payment information (see picture below).
Visit the easy integrations page for more information.

One Step Payment flow
Process
- Create the URL to start the purchase flow. The URL should follow this structure;
- Use the URL to make a system call;
- AppCoins wallet will communicate with our services to process the payment;
- Once the purchase is concluded, if you're taking the backend route, our server will notify the app’s services with the details. To see more about the server's notification, click here.
- The app’s server should deliver the purchased item, for the backend route, or the app should validate and give the item locally, for the no-backend route.
Implementing OSP in a native Android application
There are 2 ways to implement OSP in your app:
Implementation with server-side validation is safer since, in this way, every validation is performed server-side and if the URL is changed/damaged, our services will reject it.
Implementation without server-side validation is simpler but not as safe. The process is similar to Google Billing without server-side check, since the entire validation is in the APK, meaning that the value of the purchases can be manipulated by people with reverse engineering skills.
If you opt to implement OSP without server-side validation, you undertake a maximum limit of 500 completed transactions every 30 days to prevent any type of fraud.
Implementing OSP in Unity
The advised way to implement OSP in unity is to create a C# MonoBehavior script that will have the OSP flow logic and can be associated with the IAP buttons.
Just like in regular Android there are two ways of implementing OSP:
OSP URL Structure
Scheme: https
Host: apichain.catappult.io
Path: /transaction/inapp
Query string arguments: value, currency, to, product, domain, data, callback_url, reference, signature
Example:
https://apichain.catappult.io/transaction/inapp?value=11¤cy=USD&domain=com.appcoins.trivialdrivesample&product=sword.001
Warning!
Previously there was a "to" argument where the destination wallet address would be specified. This argument is no longer needed and was removed from this example.
Query String Arguments details
Parameter | Type | Description_of_field | Static | Optional | Example |
---|---|---|---|---|---|
value* | Double | The value of the chosen product (if no currency is set it is considered APPC) | N | N | 11.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 |
product* | String | The id of the item being bought. It can only have lowercase letters, numbers, underscores (_) and periods (.) | Y | N | sword.001 |
domain* | String | The application id, also known as package name. | Y | N | com.appcoins.trivialdrivesample |
data | String | Additional information to be sent if needed. | N | Y | Awesome Sword |
callback_url | String | The developer's URL to be called after the transaction is completed. It must be URL encoded. | N | Y | https://mygamestudio.co/appcoins?out_trade_no=1234 must be encoded to https%3A%2F%2Fmygamestudio.co%2Fappcoins%3Fout_trade_no%3D1234 |
order_reference | String | Unique identifier of the transaction created by the developer. (Cannot be used for different purchases) | N | Y | XYZ98880032 |
signature | String | The Hexadecimal string of the signed URL in order to be validated. For more details see section Create URL (backend). The signature must be lowercase. | N | Y | 49bc6dac9780acfe5419eb16e862cf096994c15f807313b04f5a6ccd7717e78e |
* mandatory fields
Payment Notification
If the developer provides a callback URL, our purchase service triggers a notification whenever there is a valid purchase. In order to use this service you must:
- Set the callback_url parameter when creating the URL to start the purchase;
- Prepare your server to receive a sign transaction resource as described below;
- Verify data integrity and check if the request did really come from Catappult.
After the URL is called and the payment is processed our services make a request to the callback URL that follows the structure specified in Request to callback URL (to see more about this, click here). For this reason, the developer needs to prepare the server to handle this request and finally validate if the request did come from Catappult.
For a fully working sample, you can check the following link: https://github.com/Catappult/appcoins-server-validator
Request to callback URL
Method: Post
URL: The provided URL
Body: signature, transaction
Content type: Json
Response code: 200
Response code
It is important that your service return 200 as status code so we acknowledge you did receive the notification successfully.
Body example
{
"signature": "62747e2bd871b38794edf8e7e27fc525f523be4955beeb2467ba8617d10ef1ff3c39eac5c75a52c8ebc0badefec32a84616f26ebc0213fa86604567c218b74931b",
"transaction": "{\"uid\":\"2DtyvTOSShc1xT9C\",\"domain\":\"com.appcoins.trivialdrivesample\",\"product\":\"gas\",\"reference\":\"XYZ98880032\",\"status\":\"COMPLETED\",\"added\":\"2020-05-04T10:19:44+00:00\",\"modified\":\"2020-05-04T10:19:44+00:00\",\"price\":{\"currency\":\"APPC\",\"value\":\"1\",\"appc\":\"1\"}}"
}
Body structure
Details about parameters present at the root of the json object sent when calling callback_url:
Type | Name | Description | Schema | Example |
---|---|---|---|---|
Body | signature | (Deprecated) Notification signature based on transaction parameter | string | 0x7b87a3c4dd63bee43d4c88 |
Body | transaction | Transaction resource in json | string |
Signature
Deprecated: This argument is no longer used.
Transaction parameter fields
This parameter is a json structured string that should be parsed to get the information about the purchase itself.
Name | Description | Schema | Example |
---|---|---|---|
uid | Unique ID for transaction resource | string | 2DtyvTOSShc1xT9C |
domain | Package name | string | com.appcoins.trivialdrivesample |
product | Product name (aka SKU) | string | sword.001 |
reference | Unique identifier of the transaction created by the developer. | string | XYZ98880032 |
status | Transaction status | string | COMPLETED or CANCELED or FAILED |
added | Transaction added timestmap | string | 2020-04-18T06:15:18+00:00 |
modified | Transaction modified timestmap | string | 2020-04-18T07:17:19+00:00 |
type | Type of transaction | string | INAPP_UNMANAGED |
price.appc | Transaction price in AppCoins | string | 115 |
price.currency | Transaction price currency (used by user to perform the purchase) | string | USD, APPC, EUR, etc |
price.value | Transaction price value | string | 11.5 |
price.usd | Transaction price in USD | string | 4.99 |
Transaction API
UID
Method: GET
Scheme: https
HOST: api.blockchainds.com
Path: /broker/8.20200101/transactions/{uid}
Ex:
https://api.blockchainds.com/broker/8.20200101/transactions/2DtyvTOSShc1xT9C
Response:
{
"uid": "2DtyvTOSShc1xT9C",
"domain": "com.appcoins.trivialdrivesample",
"product": "gas",
"wallet_from": "0xa43748bf498d7070d05d4fde042c51c780ce71b9",
"country": "PT",
"type": "INAPP_UNMANAGED",
"method": "appcoins_credits",
"reference": null,
"hash": "0x234e3c2407680ffe07d4f1bb7bc5c773085cd4ca723669a0473777ceeaabab95",
"origin": "BDS",
"status": "COMPLETED",
"added": "2020-05-04T10:19:45+00:00",
"modified": "2020-05-04T10:19:45+00:00",
"gateway": {
"name": "appcoins_credits"
},
"metadata": null,
"price": {
"currency": "APPC",
"value": "1",
"appc": "1",
"usd": null
}
}
Hash
Method: GET
Scheme: https
HOST: api.blockchainds.com
Path: /broker/8.20200101/transactions
Query parameters: hash
Ex:
https://api.catappult.io/broker/8.20200101/transactions?hash=0x234e3c2407680ffe07d4f1bb7bc5c773085cd4ca723669a0473777ceeaabab95
Response:
{
"next": null,
"items": [
{
"uid": "2DtyvTOSShc1xT9C",
"domain": "com.appcoins.trivialdrivesample",
"product": "gas",
"wallet_from": "0xa43748bf498d7070d05d4fde042c51c780ce71b9",
"country": "PT",
"type": "INAPP_UNMANAGED",
"method": "appcoins_credits",
"reference": null,
"hash": "0x234e3c2407680ffe07d4f1bb7bc5c773085cd4ca723669a0473777ceeaabab95",
"origin": "BDS",
"status": "COMPLETED",
"added": "2020-05-04T10:19:45+00:00",
"modified": "2020-05-04T10:19:45+00:00",
"gateway": {
"name": "appcoins_credits"
},
"metadata": null,
"price": {
"currency": "APPC",
"value": "1",
"appc": "1",
"usd": null
}
}
]
}
Updated 9 months ago