Integration

All IAP services like Google, Apple and Amazon basically encapsulate the actual subscription functionality, including order process, billing, payment and others. The billwerk system integrates as a monitor and data collector of these services. The control completely resides within the IAP services. However, especially when offering a product in several of these ecosystems and most probably even separately, the billwerk system is the tool to gather all information at a centralized point. With this approach product KPIs can be analyzed and reported as a whole.

The IAP integration is offered as a separate feature. Please contact our sales department for further information.

Product Definition

Neither Apple nor Amazon provide any pricing information via their APIs, so products, their prices and periods need to be defined redundantly also inside the billwerk product definition.

Make sure to create a separate PlanGroup for each IAP provider you want to provide to your customers. This ensures a separation of contracts.

IAP Order Process

Most of the order process is done outside the scope of billwerk. The app provider simply additionally processes an order on billwerk side by providing order information (receipt) as a replacement for the cart. The billwerk order process follows the same steps as usual (Create & Commit). billwerk will verify the receipt against the IAP provider. If the receipt is valid, billwerk will create a customer and a contract as usual.

Keep subscriptions of the different IAP platforms and billwerk in separate contracts at all time. Once a billwerk contract holds subscriptions of a specific platform do not up-/downgrade to subscriptions of another IAP platform.

Keeping in mind that billwerk takes the role of an observer for IAP the order process can be visualized as follows: IAP Signup Process

Samples

Differences to non-IAP orders

The following two snippets show the similarity of non IAP vs. IAP based orders:

IAP Order Data

{
    "Customer":{ 
        "FirstName":"Theo",
        "LastName":"Tester"
    },
    "ExternalCart":{
        "Type":"AmazonIap",
        "AmazonIapReceiptId":"...",
        "AmazonIapUserId":"..."
    },
    ...
}

Non-IAP Order Data

{
    "Customer":{ 
        "FirstName":"Theo",
        "LastName":"Tester"
    },
    "Cart":{
        "PlanVariantId": "599d51f881b1f00a28f7xxxx"
    },
    ...
}

Amazon IAP

Request

{
    "Customer":{ 
        "FirstName":"Theo",
        "LastName":"Tester"
    },
    "ExternalCart":{
        "Type":"AmazonIap",
        "AmazonIapReceiptId":"...",
        "AmazonIapUserId":"..."
    },
    ...
}

Apple IAP

DO NOT USE! Will be subject to breaking changes soon.

Request

{
    "Customer":{
        "FirstName":"Theo",
        "LastName":"Tester"
    },
    "ExternalCart":{
        "Type":"AppleIap",
        "AppleIapReceipt":"<long base64>",
        "AppleIapProductId":"<external id of planvariant>"
    },
    ...
}

Google IAP

Request

{
    "Customer": {
        "FirstName":"Theo",
        "LastName":"Tester"
    }
    "ExternalCart":{
        "Type":"GoogleIap",
        "GoogleIapPackageName" : "com.example.yourapp",
        "GoogleIapSubscriptionId" : "gold_monthly",
        "GoogleIapToken" :
        "WfdROFXfNAX8aT7fdEGeC1WapaUAzPI70qpxJoi1YV9ldHwexxxx_iwm5csf3lsqNWvbp7b_HSfaVKvpt
        aQceC1dBEbuydshi5v6XKXwitJMp6Wxxxx_Ve5DEzQUMgMZxbxfCrnC8WOoVYbxxxx_7KzGeVIlxxxx
        O7Y4A"
    }
    ...
}

IAP Billing & Cancellation Process

billwerk will periodically check for updated versions of the stored receipts. If a cancelation of a subscription is notified, the contract within billwerk is updated accordingly. This diagram applies to all of our IAP methods. IAP Subscription Cancellation Process

KPIs & Reporting

With the integrations we can keep track of the IAP subscriptions. This will allow including IAP in a lot of report types. However, the IAP services don’t offer APIs to get information on receivables and payments. Therefore IAP subscriptions won't be included in reports that are based on receivables or payments. It is also not possible to integrate IAP into our payment escalation process.