Skip to main content
The billing system handles subscription management, payment processing, and plan upgrades for premium features.

​
Overview

The tangle.client.billing package provides functionality for requesting payment links and managing subscription lifecycles. To subscribe to a plan or upgrade, request a payment link that redirects users to a payment processor. Generate a payment link for subscribing to a plan.
​
redirect_url
string
required
URL to redirect the user to after completing or canceling payment
​
plan
string
required
Identifier of the subscription plan to purchase
​
billing_period
string
required
Billing cycle for the subscription. Valid values: “monthly” or “yearly”

​
Protocol Definition

// billing.requestPaymentLink -> billing.PaymentLink
message RequestPaymentLink {
  string redirect_url = 1;
  string plan = 2;
  string billing_period = 3; // monthly or yearly
}
The billing_period field should be set to either “monthly” for monthly billing or “yearly” for annual billing.
The server responds with a PaymentLink containing the URL to the payment processor.
​
url
string
required
The payment processor URL where the user should be redirected to complete payment

​
Protocol Definition

message PaymentLink {
  string url = 1;
}

​
Canceling Subscriptions

Cancel an active subscription.

​
CancelSubscription

This message cancels the user’s current subscription. 
// billing.cancelSubscription -> billing.CancelSubscription
message CancelSubscription {}
This message has no parameters. The server cancels the subscription for the authenticated user.
Canceling a subscription typically takes effect at the end of the current billing period. Users retain access to premium features until the subscription expires.

​
Usage Flow

​
Subscribing to a Plan

  1. Request Payment Link: Send RequestPaymentLink with the desired plan, billing period, and redirect URL
  2. Receive Payment URL: Server responds with PaymentLink containing the payment processor URL
  3. Redirect User: Navigate the user to the payment URL
  4. Complete Payment: User completes payment on the payment processor’s site
  5. Handle Redirect: User is redirected back to the specified redirect_url
  6. Verify Subscription: Check subscription status to confirm activation

​
Canceling a Subscription

  1. Request Cancellation: Send CancelSubscription message
  2. Confirmation: Server processes the cancellation request
  3. Access Period: User retains access until the end of the current billing cycle
  4. Subscription Ends: Premium features are disabled when the subscription expires

​
Example Workflow

// Example: Requesting a payment link for a yearly premium plan
const paymentRequest = {
  redirect_url: "https://app.example.com/billing/success",
  plan: "premium",
  billing_period: "yearly"
};

// Send RequestPaymentLink
// Receive PaymentLink response with URL
// Redirect user to payment URL

// After successful payment and redirect:
// User is returned to https://app.example.com/billing/success
// Subscription is now active

​
Best Practices

  • Always use HTTPS for redirect URLs to ensure secure payment processing
  • Validate the billing_period field to only accept “monthly” or “yearly”
  • Handle payment failures gracefully by checking subscription status after redirect
  • Provide clear confirmation UI when users cancel subscriptions
  • Display subscription status and expiration dates prominently
  • Allow users to resubscribe easily if they’ve previously canceled

​
Security Considerations

  • Payment processing is handled by external payment processors
  • Never store credit card information in client applications
  • Validate redirect URLs to prevent open redirect vulnerabilities
  • Use secure, authenticated sessions when requesting payment links
  • Implement proper error handling for failed payment attempts

Build docs developers (and LLMs) love

Get started for freeTalk to us