Tutorial: Android In-App Purchases

Prerequisites

For Android in-app purchases to be connected to Cleeng's system, the following steps must be completed:

  1. In order to validate receipt Cleeng require Android oAuth Client Id in JSON format. Client ID should be created with permission to use google API’s on behalf end user, with privileges to view finance reports.

  2. Product ID (SKU) should be the reference of Cleeng Offer ID but must be composed of only lowercase letters (a-z). For example: Product ID => s123123123_us, Cleeng Offer ID => S123123123_US.

    Cleeng Offer ID |  Product ID (SKU)
    ----------------|------------------
    S123123123_US   |  s123123123_us
    
  3. To process receipt validation App or Middleware has to send POST request in JSON format with authorization credentials to Cleeng after successful purchase on Google Play service. Request has to contain Customer Token, Offer ID and Receipt object that should be taken from Google Play Purchase object that is passed back to the listener after purchase.

  4. Contact Cleeng to finalize Android in-app purchase setup.

This tutorial assumes that the user is already authenticated and has a customerToken stored in the app. For reference see our authentication tutorial.

Purchase Flow

The Android app is responsible for displaying the “buy" button to initiate the payment. Once successful payment is completed through Android Billing, the Cleeng receipt endpoint must be notified.

Receipt Endpoint

Endpoints:

  • Production URL: https://cleeng.com/android/payment
  • Sandbox URL: http://sandbox.cleeng.com/android/payment

Request:

  1. Request method: POST
  2. Required headers:
    • Content-Type: application/json
    • X-Publisher-Token: publisher_token
    • Authorization: Basic auth_token - token provided by Cleeng
  3. Json payload example

    {
      "customerToken": "I_WJQk99Ur5an9lGZjAWtRNhc986_6yWCHz5igXoWuMzUR3g",
      "offerId": "S598742062_US",
      "receipt": {
        "productId": "s598742062_us",
        "purchaseToken": "rojeslcdyyiapnqcynkjyyjh",
        "packageName": "com.cleeng.iap.android.demo",
        "orderId": "n9lGZjAWtRNhc98",
        "purchaseState": "0",
        "purchaseTime": "1495672338713",
        "developerPayload": "39772f248878a8ff130c0b167caa45e7"
      },
      ipAddress: "192.168.1.1"
    }
    
  4. Parameters describe

    • customerToken - token identyfing customer account on Cleeng (eg. ZAP8dgKPIEgBulSZZBdyv1O0wzg1pucyHf8gUGg2X6ZhdRaH)
    • offerId - identifier for Cleeng offer (eg E123123123_US)
    • productId - Product ID from Purchase object from Google Play response after successful purchase
    • purchaseToken - Purchase Token from Purchase object from Google Play response after successful purchase
    • packageName - Package Name from Purchase object from Google Play response after successful purchase
    • orderId - Order ID from Purchase object from Google Play response after successful purchase
    • purchaseState - Purchase State from Purchase object from Google Play response after successful purchase
    • purchaseTime - Purchase Time from Purchase object from Google Play response after successful purchase
    • ipAddress - viewer ip address, optional parameter
  5. Example json response:

    {
      "message": "OK"
    }
    
  6. Response describe

    • message - processing result
  7. Error codes

    • 400 - Invalid parameters
    • 401 - Invalid authentication // broadcaster and viewer
    • 422 - Unprocessable entity
    • 200 - OK
    • 500 - Internal Server Error

In order to register a transaction in Cleeng, the receipt data returned from Android Billing must be passed to the secure Cleeng endpoint for validation. The endpoint accepts a POST request of a JSON payload containing following fields:

Validate Access

Payment processing is asynchronous and may take up to 1-2 minutes between purchase and validation in Cleeng. Because of this, the app should grant temporary access to the user while the transaction is processed. However, every time after the inital purchase, the middleware will be the source of truth to check the user's access status.

Note: If this is not completed within 1-2 minutes, the app should assume that the payment failed and notify the user.

Android purchase flow