Java

Official billing.io SDK for Java

The official billing.io SDK for Java 11+.

Maven Central

io.billing:billingio-java

GitHub

billingio/billingio-java

Installation

Maven

<dependency>
  <groupId>io.billing</groupId>
  <artifactId>billingio-java</artifactId>
  <version>1.0.0</version>
</dependency>

Gradle

implementation "io.billing:billingio-java:1.0.0"

Quick Start

import io.billing.BillingIO;
import io.billing.model.Checkout;

BillingIO billing = BillingIO.builder()
    .apiKey("sk_live_...")
    .build();

Checkout checkout = billing.checkouts().create(
    Checkout.CreateParams.builder()
        .amountUsd(49.99)
        .chain("tron")
        .token("USDT")
        .putMetadata("order_id", "ord_12345")
        .build()
);

System.out.println(checkout.getCheckoutId());
System.out.println(checkout.getDepositAddress());

List Checkouts with Pagination

import io.billing.model.CheckoutList;

CheckoutList page = billing.checkouts().list(
    Checkout.ListParams.builder()
        .limit(10)
        .build()
);

for (Checkout checkout : page.getData()) {
    System.out.println(checkout.getCheckoutId() + " - " + checkout.getStatus());
}

// Fetch next page
if (page.getCursor() != null) {
    CheckoutList nextPage = billing.checkouts().list(
        Checkout.ListParams.builder()
            .cursor(page.getCursor())
            .limit(10)
            .build()
    );
}

Get Checkout Status

import io.billing.model.CheckoutStatus;

CheckoutStatus status = billing.checkouts().getStatus("chk_abc123");

System.out.println(status.getStatus());                // "confirming"
System.out.println(status.getConfirmations());          // 8
System.out.println(status.getRequiredConfirmations());  // 19

Webhook Signature Verification (Spring Boot)

import io.billing.webhook.WebhookSignature;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
public class WebhookController {

    @PostMapping("/webhooks/billing")
    public ResponseEntity<String> handleWebhook(
            @RequestBody String body,
            @RequestHeader("X-Billing-Signature") String signature) {

        boolean isValid = WebhookSignature.verify(
            body, signature, "whsec_..."
        );

        if (!isValid) {
            return ResponseEntity.status(401).body("Invalid signature");
        }

        // process event...
        return ResponseEntity.ok("OK");
    }
}

Customers

import io.billing.model.Customer;

Customer customer = billing.customers().create(
    Customer.CreateParams.builder()
        .email("[e-mail]")
        .name("Alice Johnson")
        .putMetadata("plan", "pro")
        .build()
);

Customer fetched = billing.customers().get("cus_abc123");

Customer updated = billing.customers().update("cus_abc123",
    Customer.UpdateParams.builder()
        .name("Alice Smith")
        .build()
);

Payment Methods

import io.billing.model.PaymentMethod;

PaymentMethod pm = billing.paymentMethods().create(
    PaymentMethod.CreateParams.builder()
        .chain("tron")
        .token("USDT")
        .displayName("Primary USDT")
        .build()
);

billing.paymentMethods().setDefault("pm_abc123");

Subscriptions

import io.billing.model.SubscriptionPlan;
import io.billing.model.Subscription;

SubscriptionPlan plan = billing.subscriptionPlans().create(
    SubscriptionPlan.CreateParams.builder()
        .name("Pro Monthly")
        .amountUsd(29.99)
        .interval("monthly")
        .token("USDT")
        .chain("tron")
        .build()
);

Subscription sub = billing.subscriptions().create(
    Subscription.CreateParams.builder()
        .customerId("cus_abc123")
        .planId(plan.getId())
        .paymentMethodId("pm_abc123")
        .build()
);

// Cancel
billing.subscriptions().update("sub_abc123",
    Subscription.UpdateParams.builder()
        .status("canceled")
        .build()
);

Entitlements

import io.billing.model.Entitlement;

Entitlement ent = billing.entitlements().create(
    Entitlement.CreateParams.builder()
        .planId("plan_abc123")
        .featureKey("api_calls")
        .valueType("numeric")
        .valueNumeric(10000)
        .build()
);

EntitlementCheck check = billing.entitlements().check(
    Entitlement.CheckParams.builder()
        .customerId("cus_abc123")
        .featureKey("api_calls")
        .build()
);
System.out.println(check.getHasAccess() + " " + check.getValue());

Payouts

import io.billing.model.PayoutIntent;

PayoutIntent payout = billing.payoutIntents().create(
    PayoutIntent.CreateParams.builder()
        .recipientAddress("TXyz...")
        .chain("tron")
        .token("USDT")
        .amount(500.00)
        .currency("USD")
        .build()
);

// Submit tx hash after executing externally
billing.payoutIntents().execute("po_abc123",
    PayoutIntent.ExecuteParams.builder()
        .txHash("0xabc...")
        .build()
);

Revenue

import io.billing.model.Adjustment;

Adjustment adj = billing.adjustments().create(
    Adjustment.CreateParams.builder()
        .type("credit")
        .amountUsd(10.00)
        .description("Loyalty discount")
        .customerId("cus_abc123")
        .build()
);

Error Handling

import io.billing.exception.BillingIOException;

try {
    billing.checkouts().create(params);
} catch (BillingIOException e) {
    System.out.println(e.getStatus());  // 422
    System.out.println(e.getCode());    // "validation_error"
    System.out.println(e.getMessage()); // "amount_usd must be positive"
}