Tutorial 2.3: iOS and tvOS Payments

Prerequisites

Before iOS application and middleware can be connected to Apple Pay, following steps must be completed:

  1. Setting up App Store account and creating application - see tutorial.
  2. Adding test products - see tutorial.

    Important notes for setting up products compatible with Cleeng:

    • The product references have to be the same as Cleeng's offer IDs.
    • Product price must be set manually in iTunes Connect. Make sure to align prices between Apple's product and Cleeng offer.
      You can only select price tiers in the iTunes connect, make sure the video’s in the Cleeng database have the same price.
    • Use non-renewing-subscription products for subscriptions for a specific period of time. The subscriptions are removed from the receipt after the App has retrieved access to the product automatically. It means that application must rely on Cleeng when checking entitlement.
    • Use non-consumable for subscriptions that are forever. They will remain on the receipt forever.
    • To test, logout of iTunes Connect on you phone and login with on of the sandbox account created in the iTunes Connect -> Users and Roles -> Sandbox Testers (see tutorial).

In following paragraphs we make an assumption that customer is already authenticated and application has his Customer Token.

Authentication is described in this section.

Purchase Flow

iOS Application is responsible for displaying a Pay Button that will initiate the payment (see Apple documentation). Once payment is completed, App Store will return a receipt object that needs to be passed through the middleware to Cleeng's Receipt Endpoint.

Pay Button Logic

After purchase is completed, application and middleware should enter polling mode. They should make a request to getAccessStatus API every 5 seconds until transaction is completed. If access is not granted within 60 seconds, application should assume it faild and inform user accordingly. If transaction is confirmed, video content can be revealed.

Polling getAccessStatus

Communication with Receipt Endpoint

> Receipt Endpoint has following URL: https://cleeng.com/checkout/apple_inapp.php

In order to register transaction in Cleeng, receipt data returned from Apple Pay must be passed to secure endpoint for validation. Endpoint accepts POST request with JSON payload, an object containing following fields:

  • customerToken - token identyfing customer account on Cleeng (eg. ZAP8dgKPIEgBulSZZBdyv1O0wzg1pucyHf8gUGg2X6ZhdRaH)
  • offerId - identifier for Cleeng offer (eg E123123123_US).
  • receiptData - complete receipt data returned from Apple Pay.
  • transactionId - transaction identifier returned from Apple Pay.

Endpoint is secured using HTTP Authentication - Authorization header must be present in each request. Username and password will be provided by Cleeng Tech support during project setup. Example header may look like this:

Authorization: Basic aYLR0cHdRGNoomJ=

Receipt processing is an asynchronous process that may take up to 30 seconds, therefore application needs to poll Cleeng API (getAccessStatus method) until transaction is completed and access is granted.