Sync Web Transactions to IAPHUB

If your mobile app is also available on the web, you can easily sell subscriptions or any other digital goods through a browser using any web payment processors like Stripe, PayPal, Adyen, and others.

IAPHUB streamlines the integration of web-based transactions into your native iOS and Android applications, ensuring a seamless user experience across platforms. By leveraging our API, you can effortlessly synchronize web purchases with your mobile app, requiring minimal development effort. This enables you to efficiently manage subscriptions and digital goods across multiple platforms, while maintaining complete control over your preferred payment processors. You have the flexibility to implement a single or multiple payment systems as needed, ensuring a tailored approach to your business requirements.

The guide below walks you through each step to properly synchronize a web subscription with IAPHUB.

Prerequisites

Before you begin, make sure your app meets the following requirements:

1. IAPHUB SDK Installation and Configuration
   Ensure that your native mobile app has the latest version of the IAPHUB SDK installed and correctly configured. This is crucial for a smooth integration between your app and IAPHUB's services.

2. User Authentication
   The user must be authenticated using the login method of the SDK. Without an authentication system in place, it will not be possible to associate the subscription with a specific user.

3. Payment Processor Integration
   Ensure your web payment processor is set up to handle subscription transactions. These transactions will need to be synchronized with IAPHUB for them to be accessible within your mobile app.

4. Backend Setup
   Ensure that your backend system can make API calls to IAPHUB's endpoints to create and update transaction data based on the user's web subscription.

Create a Subscription

Once a subscription is purchased through your web payment processor, call the Create transaction API route to create the subscription on IAPHUB.

For testing purposes, it is recommended to start by creating a sandbox subscription with a short expiration period, such as a few minutes.

When creating a transaction, you must provide the order ID of the transaction prefixed with API..
Additionally, if you are utilizing multiple payment systems, it is advisable to append a supplementary 3-letter prefix (for instance, STP. for Stripe) to the order ID. This ensures that there are no conflicts between payment systems.

Example Request

curl -X POST "https://api.iaphub.com/v1/app/APP_ID/user/USER_ID/transaction" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey SERVER_API_KEY" \
  -d '{
    "orderId": "API.STP.de65c2e0-a2af-43fb-aaac-b71f78d56f9f",
    "product": "monthly_subscription_tier1",
    "purchaseDate": "2025-03-26T21:27:47.467Z",
    "price": 29,
    "currency": "USD",
    "country": "US",
    "isSandbox": true,
    "expirationDate": "2025-03-26T21:32:47.467Z"
  }'

info

The APP_ID parameter can be located on the settings page of the IAPHUB dashboard.
The USER_ID parameter corresponds to the user ID used for authenticating the user through the IAPHUB SDK's login method.
The SERVER_API_KEY parameter can be located on the settings page of the IAPHUB dashboard.

Once the transaction is successfully created, the next time the user opens the app or brings it to the foreground:

• The onUserUpdate event of the SDK will be triggered.
• The getActiveProducts and getProducts methods will return the newly created subscription.

info

After creating a web subscription for the first time, if your app is already open, please restart it to ensure the IAPHUB SDK is notified of the web transactions being enabled. For existing users with the app already open, web transactions will function as expected, but it may take up to 24 hours for the new configuration to be fully propagated.

At this point, the subscription will be fully synchronized with the user's account, and they will be able to access their purchased content on the mobile app.

Subscription Auto-Renewal Disabled

Upon cancellation of a user's subscription auto-renewal, it is essential to inform IAPHUB by invoking the Update transaction API endpoint.

To accomplish this, you must include the subscriptionCancelReason parameter in your request, specifying the reason behind the cancellation.

Example Request

curl -X POST "https://api.iaphub.com/v1/app/APP_ID/transaction/API.STP.de65c2e0-a2af-43fb-aaac-b71f78d56f9f" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey SERVER_API_KEY" \
  -d '{
    "subscriptionCancelReason": "customer_cancelled"
  }'

Subscription Auto-Renewal Enabled

When a user reenables the auto-renewal of their subscription, you should notify IAPHUB by calling the Update transaction API route.

To accomplish this, you must include the subscriptionCancelReason parameter in your request, with a null value, indicating that the subscription auto-renewal has been reenabled.

Example Request

curl -X POST "https://api.iaphub.com/v1/app/APP_ID/transaction/API.STP.de65c2e0-a2af-43fb-aaac-b71f78d56f9f" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey SERVER_API_KEY" \
  -d '{
    "subscriptionCancelReason": null
  }'

Subscription Expiration Date Update

If needed, you can update the subscription expiration date by calling the Update transaction API endpoint.

To update the subscription expiration date, you must include the expirationDate parameter in your request.
Please note that the expiration date can only be modified when the subscription is in an active state. This update is not applicable when the subscription is in either the grace or retry period states.

Example Request

curl -X POST "https://api.iaphub.com/v1/app/APP_ID/transaction/API.STP.de65c2e0-a2af-43fb-aaac-b71f78d56f9f" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey SERVER_API_KEY" \
  -d '{
    "expirationDate": "2025-03-26T21:42:47.467Z"
  }'

Subscription Renewal

To renew a subscription, you need to call the Create transaction API endpoint.

The parameters required for renewing a subscription are the same as those required for creating a subscription, with one additional requirement: the linkedPurchase parameter must be provided with the orderId of previous transaction. This ensures that the new transaction is linked to the original subscription.

You have a 24-hour window (5 minutes in sandbox) after the expiration to renew the subscription. If not renewed within this timeframe, the subscription will automatically transition into the retry period state.

Example Request

curl -X POST "https://api.iaphub.com/v1/app/APP_ID/user/USER_ID/transaction" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey SERVER_API_KEY" \
  -d '{
    "orderId": "API.STP.7a89f6b5-9404-4109-afff-7bda20cff665",
    "product": "monthly_subscription_tier1",
    "purchaseDate": "2025-03-26T21:42:47.467Z",
    "price": 29,
    "currency": "USD",
    "country": "US",
    "isSandbox": true,
    "expirationDate": "2025-03-26T21:47:47.467Z",
    "linkedPurchase": "API.STP.de65c2e0-a2af-43fb-aaac-b71f78d56f9f"
  }'

Subscription Expiration

When the subscription auto-renewal is cancelled, the subscription will automatically expire after the expiration date.
Once the subscription expires, the next time the user opens the app or brings it to the foreground:

• The onUserUpdate event of the SDK will be triggered.
• The getActiveProducts and getProducts methods will no longer return the expired subscription.

If the auto-renewal is maintained beyond the expiration date, it indicates an ongoing attempt to renew the subscription.
In this case, you have a 24-hour window (5 minutes in sandbox) after the expiration to either:

• Renew the subscription
• Update the subscription to the grace period state.
• Update the subscription to the retry period state.
• Make the subscription expire by disabling the auto-renewal.

After no action is taken after the 24 hours window (5 minutes in sandbox), the subscription will automatically transition to the retry period state.

Subscription Grace Period

The grace period state is particularly useful when you want to ensure uninterrupted access to the subscription for users while attempting to renew their subscription.

During the grace period, the subscription remains accessible to users through the SDK's getActiveProducts and getProducts methods.

This grace period can last up to 30 days (10 minutes in sandbox) after the expiration date. If the subscription is not updated within this timeframe, it will automatically transition to the retry period state. You can end the grace period at any time by either making the subscription expire by disabling the auto-renewal or by updating the subscription state to the retry period.

Example Request

curl -X POST "https://api.iaphub.com/v1/app/APP_ID/transaction/API.STP.de65c2e0-a2af-43fb-aaac-b71f78d56f9f" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey SERVER_API_KEY" \
  -d '{
    "subscriptionState": "grace_period"
  }'

Subscription Retry Period

The retry period state allows you to restrict access to the subscription while attempting to renew it.

During the retry period, the subscription is not returned by the SDK's getActiveProducts and getProducts methods, unless the includeSubscriptionStates parameter is provided with the "retry_period" option.

This retry period can last up to 60 days (20 minutes in sandbox) after the expiration date. If the subscription is not updated within this timeframe, it will automatically expire. You can end the retry period at any time by making the subscription expire by disabling the auto-renewal.

Example Request

curl -X POST "https://api.iaphub.com/v1/app/APP_ID/transaction/API.STP.de65c2e0-a2af-43fb-aaac-b71f78d56f9f" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey SERVER_API_KEY" \
  -d '{
    "subscriptionState": "retry_period"
  }'