让没有银行卡的用户，
用话费完成每一次付费。

1 · Installation & Setup

The SDK is distributed manually as a compiled .aar archive. Add it to your project and declare its open-source dependencies in your app module build script.

Step 1: Add the .aar File

1. Locate the downloaded subscription.aar.
2. In your app module (usually app), create app/libs/ if missing.
3. Paste subscription.aar into libs.

Step 2: Configure build.gradle.kts (App Module)

dependencies {
    // 1. Reference the local SDK binary
    implementation(files("libs/subscription.aar"))

    // 2. Declare transient dependencies
    implementation("com.squareup.okhttp3:okhttp:4.9.0")
    implementation("com.google.code.gson:gson:2.10")
    implementation("androidx.work:work-runtime:2.9.0")
    implementation("androidx.core:core:1.12.0")
    implementation("androidx.appcompat:appcompat:1.6.1")
}

Step 3: Set Android Target Platform

In defaultConfig, minimum supported platform is Android 7 (API 24) or higher.

Step 4: Configure App Permissions

Declare required permissions outside <application> in AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.SEND_SMS" />
    <application>
    </application>
</manifest>

2 · Authentication & Initialization

The SDK requires a secure Merchant API Bearer Key. Pass it at instantiation; the SDK persists it in an internal encrypted SharedPreferences container.

import com.relario.subscription.SubscriptionManager;

public class MainActivity extends AppCompatActivity {
    private SubscriptionManager subscriptionManager;
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        String key = "your_relario_production_or_test_api_key_here";
        subscriptionManager = new SubscriptionManager(this, key);
    }
}

3 · Public API Methods

3.1 One-Time Purchases (purchaseOneTime)

Initializes a standalone SMS microtransaction for a single digital item.

// Overload A: Asynchronous Callback Model
public void purchaseOneTime(int smsCount, String productId,
    String productName, String customerId, PurchaseCallback callback)

// Overload B: Fire-and-Forget Mode
public void purchaseOneTime(int smsCount, String productId,
    String productName, String customerId)

• smsCount (int): Quantized premium message count to reach the payment target.
• productId (String): Unique SKU token of the asset.
• productName (String): Visible display title.
• customerId (String): Your app's unique user reference.
• callback: Handles success payloads or network exceptions.

subscriptionManager.purchaseOneTime(1, "gold_pack_01",
    "100 Gold Coins", "user_id_777", new PurchaseCallback() {
  public void onSuccess(Transaction t) {
    // SDK auto-dispatches the verification SMS next
  }
  public void onError(Exception e) { }
});

3.2 Schedule Recurring Subscriptions (subscribe)

Enqueues a persistent WorkManager task that wakes the app on a recurring schedule and executes billing across app close and device restart.

public void subscribe(int interval, String timeUnit,
    int smsCount, String productId, String productName, String customerId)

• interval (int): Numeric spacing, e.g. 15 / 24 / 1.
• timeUnit (String): Matches java.util.concurrent.TimeUnit values.

// Trigger every 24 Hours
subscriptionManager.subscribe(24, "HOURS", 1,
    "premium_sub_month", "Monthly Vip Pass", "user_id_777");

3.3 Terminate Recurring Subscriptions (cancelSubscription)

public void cancelSubscription(String productId)
subscriptionManager.cancelSubscription("premium_sub_month");

3.4 Query Single Transaction (checkTransactionStatus)

public void checkTransactionStatus(String transactionId, TransactionDetailsCallback callback)
// transaction.getStatus() returns "ok"
// transaction.getPayments().size() = confirmed receipts

3.5 Fetch Transaction History (retrieveTransactions)

public void retrieveTransactions(TransactionHistoryCallback callback)
// Parses local DB, polls server, returns JSON array

4 · Understanding Data Models

The core Transaction object:

• getTransactionId(): Unique operation reference.
• getStatus(): Server state (e.g. "ok").
• getSmsBody(): Verification text payload sent.
• getPhoneNumbersList(): Shortcode endpoints list.
• getPayments(): Confirmed operator webhook receipts.

5 · Webhook Notifications

When a carrier payment hits, the platform can asynchronously inform your backend. Configure a Webhook URL in your merchant panel; the platform POSTs:

{
  "paymentType": "sms",
  "transactionId": "120058355",
  "paymentId": 10072190,
  "productId": "prod_999",
  "productName": "Premium Access",
  "customerId": "user_11",
  "smsBody": "120058355:1e3a1a9830",
  "sourcePhoneNumber": "40723456789",
  "destinationPhoneNumber": "41766013299",
  "initiatedAt": 1781173691517
}

Testing Webhooks via Development Mode

1. Enable Development Mode in the merchant panel.
2. Save your server route in the Webhook URL field.
3. Select Transactions > Simulate transaction.
4. Click confirm to force a simulated POST and verify capture.