Stripe APIs

Stripe APIs

These endpoints manage all payment and subscription-related interactions for decentralized storage services, including one-time purchases, subscription-based allocations, AI agents, operational fees, and blobber rental.

Get Stripe Configuration

Path: /v2/stripe/config Method: GET Access: Private API Description: Fetches the available Stripe pricing plans configured for different app types (e.g., blimp, vult, chalk, chimney). Each plan includes pricing and metadata like storage size and currency.

Query Parameters: (None)

Response:

[
  {
    "id": "price_1P0abc123xyz",
    "currency": "usd",
    "lookup_key": "blimp:: 100gb",
    "metadata": {
      "AppType": "blimp",
      "Size": "107374182400"
    },
    "unit_amount": 1500,
    "unit_amount_decimal": 1500.0,
    "active": true
  },
  {
    "id": "price_1P0def456uvw",
    "currency": "usd",
    "lookup_key": "blimp:: 200gb",
    "metadata": {
      "AppType": "blimp",
      "Size": "214748364800"
    },
    "unit_amount": 2500,
    "unit_amount_decimal": 2500.0,
    "active": true
  }
]

Logic:

  • Plans are retrieved using Stripe’s pricing list API.

  • Filters by AppType and ensures only active plans are returned.

  • Extracts and returns relevant metadata for each plan:

    • AppType

    • Size (in bytes)

    • lookup_key

    • unit_amount

    • currency

  • Used to populate pricing dropdowns or plan selectors in UI.

Get Stripe Customer

Path: /v2/stripe/customer Method: GET Access: Private API Description: Retrieves the Stripe customer profile associated with the currently authenticated user.

Query Parameters: (None)

Response:

{
  "customer_id": "cus_abc123xyz",
  "email": "[email protected]",
  "phone": "+1234567890",
  "name": "Alice"
}

Logic:

  • The backend maps the authenticated user’s ID to a stored Stripe customer ID.

  • If the customer does not exist:

    • Returns a 404 or triggers creation (implementation dependent).

  • Returns core details for UI prefill, account linking, and analytics.

Cancel Subscription

Path: /v2/stripe/cancel-subscription Method: POST Access: Private API Description: Cancels a user’s active Stripe subscription by subscription_id and updates both Stripe and local DB records.

Request Body:

{
  "subscription_id": "sub_1P0abc123xyz"
}

Response:

{
  "id": 123,
  "subscription_id": "sub_1P0abc123xyz",
  "customer_id": 456,
  "app_type": "blimp",
  "cancel_at": "2025-07-01T12:00:00Z",
  "subscription_start": "2025-06-01T12:00:00Z",
  "subscription_end": "2025-07-01T12:00:00Z",
  "discount": 0,
  "plan_id": "price_1P0abc123xyz",
  "plan_name": "blimp:: 100gb",
  "duration": "month",
  "status": "canceled",
  "stripe_allocation_details": {
    "allocation_id": "alloc_abc123",
    "allocation_size": 107374182400,
    "allocation_expiry": 1750000000
  },
  "stripe_ai_subscription": false
}

Logic:

  • Validates ownership of the subscription.

  • Calls Stripe’s subscription cancel API.

  • Marks subscription as canceled in the local DB.

  • Updates any associated allocations or resources to reflect termination.

Get Specific PaymentIntent

Path: /v2/stripe/payment-intent Method: GET Access: Private API Description: Returns full details about a specific PaymentIntent from Stripe, including allocation linkage and payment metadata.

Query Parameters:

  • payment_intent (string, required)

Example: GET /v2/stripe/payment-intent?payment_intent=pi_1P0abc123xyz

Response:

{
  "payment_intent": "pi_1P0abc123xyz",
  "amount": 1500,
  "date": "2025-07-01T12:00:00Z",
  "currency": "usd",
  "method": "card",
  "description": "Purchase 100GB storage",
  "status": "succeeded",
  "subscription_id": 12345,
  "checkout_session": "cs_test_12345",
  "app_type": "blimp",
  "stripe_allocation_details": {
    "allocation_id": "alloc_abc123",
    "allocation_size": 107374182400,
    "allocation_expiry": 1750000000
  }
}

Logic:

  • Validates the user owns the payment_intent.

  • Joins local database records with Stripe payment data.

  • Links back to the allocation or subscription triggered by this payment.

Create One-Time Allocation Checkout Session

Path: /v2/stripe/create-allocation

Method: POST

Access: Private API

Description: Creates a Stripe Checkout session for a one-time purchase of a storage allocation (currently supports blimp app type only). Returns a session URL for redirecting the user.

Request Body: (Required fields, full example)

{
  "price_id": "price_1P0abc123xyz",
  "amount": 1500,
  "success_url": "https://yourapp.com/payment-success",
  "cancel_url": "https://yourapp.com/payment-cancel",
  "description": "Purchase 100GB storage",
  "allocation_name": "My Storage",
  "allocation_type": "HotPlus",
  "owner_public_key": "abcdef1234567890",
  "data_shards": 2,
  "parity_shards": 2,
  "size": 107374182400,
  "read_price_min": 0,
  "read_price_max": 0,
  "write_price_min": 0,
  "write_price_max": 0,
  "blobber_ids": "blobber1,blobber2,blobber3,blobber4",
  "is_enterprise": false,
  "alloc_blobbers_type": "HotPlus",
  "round_expiry": 0,
  "owner_signing_public_key": "abcdef1234567890"
}

Response:

  • Status: 201 Created

  • Content-Type: application/json

{
  "id": "cs_test_12345",
  "amount_total": 1500,
  "currency": "usd",
  "url": "https://checkout.stripe.com/pay/cs_test_12345"
}

Logic:

  1. Validates all input fields.

  2. Ensures blobber_ids.length ≥ data_shards + parity_shards.

  3. Checks app type == "blimp".

  4. Filters blobbers by allocation type/enterprise.

  5. Verifies price on mainnet (match with blobber write price).

  6. Saves a StripeAllocationOptions task in DB.

  7. Builds checkout session with success/cancel URLs and metadata.Webhook: checkout.session.completed → case modelV2.CreateAllocation

  • Extracts TaskID from metadata.

  • Stores payment details in DB.

  • Marks the allocation as paid.

  • Triggers a worker to finalize allocation on-chain.

Update One-Time Allocation Checkout Session

Path: /v2/stripe/update-allocation

Method: POST Access: Private API

Description: Creates a Stripe Checkout session to upgrade or modify an existing allocation (increase size, replace blobbers). Applicable for blimp and vult.

Request Body:

{
  "price_id": "price_1P0abc123xyz",
  "amount": 1000,
  "success_url": "https://yourapp.com/payment-success",
  "cancel_url": "https://yourapp.com/payment-cancel",
  "allocation_id": "alloc_abc123",
  "size": 214748364800,
  "description": "Upgrade to 200GB",
  "add_blobber": "blobber5",
  "remove_blobber": "blobber2",
  "update_alloc_ticket": "",
  "round_expiry": 0
}

Response:

  • Status: 201 Created

  • Content-Type: application/json

{
  "id": "cs_test_67890",
  "amount_total": 1000,
  "currency": "usd",
  "url": "https://checkout.stripe.com/pay/cs_test_67890"
}

Logic:

  1. Validates allocation_id and presence of size or blobber changes.

  2. App type must be blimp or vult.

  3. If only remove_blobber is provided and amount == 0:

    • Skips Stripe session and performs free replacement in DB.

  4. Otherwise, creates StripeAllocationOptions task.

  5. Verifies mainnet cost matches amount.

Webhook: checkout.session.completed → case modelV2.UpdateAllocation

  • Processes payment.

  • Updates allocation task with PaymentIntent ID.

  • Triggers background update.

Create Allocation Subscription

Path: /v2/stripe/create-allocation-subscription

Method: POST

Access: Private API

Description: Creates a recurring subscription-based storage allocation (for vult or chalk). Validates the subscription plan and metadata.

Request Body:

{
  "price_id": "price_1P0abc123xyz",
  "amount": 1500,
  "success_url": "https://yourapp.com/payment-success",
  "cancel_url": "https://yourapp.com/payment-cancel",
  "description": "Purchase 100GB storage",
  "allocation_name": "My Storage",
  "allocation_type": "HotPlus",
  "owner_public_key": "abcdef1234567890",
  "data_shards": 2,
  "parity_shards": 2,
  "size": 107374182400,
  "read_price_min": 0,
  "read_price_max": 0,
  "write_price_min": 0,
  "write_price_max": 0,
  "blobber_ids": "blobber1,blobber2,blobber3,blobber4",
  "is_enterprise": false,
  "alloc_blobbers_type": "HotPlus",
  "round_expiry": 0,
  "owner_signing_public_key": "abcdef1234567890"
}

Response:

  • Status: 201 Created

  • Content-Type: application/json

{
  "id": "cs_test_12345",
  "amount_total": 1500,
  "currency": "usd",
  "url": "https://checkout.stripe.com/pay/cs_test_12345"
}

Logic:

  1. Ensures AppType == vult || chalk

  2. Validates plan metadata using checkSubscriptionPlanAllocation

  3. Stores allocation config as a StripeAllocationOptions task.

  4. Builds Stripe Checkout session:

    • Mode: subscription

    • Metadata includes: TaskID, ClientID, StripeOperation

    • Billing anchor set ~335 days later for yearly plans

    • Links to existing customer if exists

Webhook: checkout.session.completed → case modelV2.CreateAllocation

  • Extracts metadata

  • Creates allocation and subscription record

  • Processes referral discount (if any)

  • Marks allocation task as ready

Update Allocation Subscription

Path: /v2/stripe/update-allocation-subscription

Method: POST

Access: Private API

Description: Used to upgrade an existing subscription-based allocation. Cancels the old subscription and creates a new one.

Request Body:

{
  "price_id": "price_1P0abc123xyz",
  "success_url": "https://yourapp.com/payment-success",
  "cancel_url": "https://yourapp.com/payment-cancel",
  "allocation_id": "alloc_abc123",
  "size": 214748364800,
  "description": "Upgrade to 200GB"
}

Response:

  • Status: 201 Created

  • Content-Type: application/json

{
  "id": "cs_test_67890",
  "amount_total": 2500,
  "currency": "usd",
  "url": "https://checkout.stripe.com/pay/cs_test_67890"
}

Logic:

  1. Validates price_id, allocation_id, and size

  2. Matches app type and size with plan metadata

  3. Finds existing active subscriptions:

    • Generates upgrade coupons

    • Adds to metadata for Stripe

  4. Creates Stripe Checkout session:

    • Mode: subscription

    • Applies coupons/discounts

    • Adds ExistingSubscriptions metadata

    • Metadata: TaskID, PlanName, Duration, StripeOperation

Webhook: checkout.session.completed → case modelV2.UpdateAllocationSubscription

  • Fetches metadata

  • Cancels old subscriptions

  • Saves new subscription

  • Links task to updated allocation

Create Chimney Subscription

Path: /v2/stripe/chimney-subscription

Method: POST

Access: Private API

Description: Sets up a recurring operational fee between a blobber and validator using Stripe subscriptions.

Request Body:

{
  "price_id": "price_1P0abc123xyz",
  "blobber_client_id": "blobber123",
  "validator_client_id": "validator456",
  "success_url": "https://yourapp.com/payment-success",
  "cancel_url": "https://yourapp.com/payment-cancel",
  "description": "Operational fee for Chimney"
}

Response:

  • Status: 201 Created

  • Content-Type: application/json

{
  "id": "cs_test_12345",
  "amount_total": 500,
  "currency": "usd",
  "url": "https://checkout.stripe.com/pay/cs_test_12345"
}

Logic:

  1. Fetches customer by user ID.

  2. Validates price_id metadata.

  3. Builds metadata:

    • BlobberClientID, ValidatorClientID, StripeOperation=ChimneySubscription

  4. Creates checkout session in subscription mode.

Webhook: checkout.session.completed → case modelV2.ChimneySubscription

  • Parses metadata

  • Creates/updates StripeSubscriptionDetails with Chimney info

  • Triggers:

    • fundOperationalWallets()

    • Delegate wallet funding task

    • Link to subscription ID

Create Rent Blobber Subscription

Path: /v2/stripe/rent-blobber-subscription Method: POST Access: Private API Description: Creates a Stripe Checkout session for a recurring subscription to rent a blobber (dedicated storage provider). This allows a user to rent storage capacity directly from a specific blobber.

Request Body:

{
  "price_id": "price_1P0abc123xyz",
  "blobber_id": "blobber123",
  "success_url": "https://yourapp.com/payment-success",
  "cancel_url": "https://yourapp.com/payment-cancel",
  "description": "Rent blobber for 1 year"
}

Response:

  • Status: 201 Created

  • Content-Type: application/json

{
  "id": "cs_test_rent_blobber_001",
  "amount_total": 8000,
  "currency": "usd",
  "url": "https://checkout.stripe.com/pay/cs_test_rent_blobber_001"
}

Logic:

  1. Fetch Stripe customer for the authenticated user.

  2. Retrieve Stripe plan using price_id and extract metadata.

  3. Prepare metadata:

    • StripeOperation: "RentBlobberSubscription"

    • ClientID, AppType, BlobberID, DelegateWallet, PlanName, Duration, Description, PriceID, etc.

  4. Create Stripe Checkout session in subscription mode using metadata.

  5. Return Checkout session details to the client.

Webhook Handler: case modelV2.RentBlobberSubscription

  • On checkout.session.completed:

    • Extracts metadata (plan, blobber ID, delegate wallet, shift price ID, etc.)

    • Generates split key using ZVault

    • Fetches Portainer API endpoint for blobber host

    • Stops and renames old container, then deploys new one with split key

    • Deletes old container after successful migration

    • Updates rent_blobber record and saves delegate wallet and subscription metadata

    • Marks blobber as rented by the user in the database

Create AI Agent Subscription

Path: /v2/stripe/ai-agent-subscription

Method: POST

Access: Private API

Description: Creates a Stripe Checkout session for subscribing to an AI Agent service. This enables a recurring subscription to use AI inference APIs on the platform.

Request Body:

{
  "price_id": "price_1P0abc123xyz",
  "success_url": "https://yourapp.com/payment-success",
  "cancel_url": "https://yourapp.com/payment-cancel",
  "description": "AI Agent monthly subscription"
}

Response:

  • Status: 201 Created

  • Content-Type: application/json

{
  "id": "cs_test_ai_agent_001",
  "amount_total": 2500,
  "currency": "usd",
  "url": "https://checkout.stripe.com/pay/cs_test_ai_agent_001"
}

Logic:

  1. Fetch Stripe customer for the authenticated user.

  2. Validate price_id by fetching associated Stripe plan.

  3. Add metadata:

    • StripeOperation: "AiAgentSubscription"

    • ClientID, PlanName, Duration, PriceID, Description

  4. Create Stripe subscription checkout session with metadata

  5. Return session details to client

Webhook Handler: case modelV2.AiAgentSubscription

  • On checkout.session.completed:

    • Extract metadata (PriceID, PlanName, Duration, etc.)

    • Fetch subscription details from Stripe using subscription_id

    • Save new record in StripeSubscriptionDetails

    • Create new entry in AiSubscriptionEntity to link user ID and subscription

18. Get Stripe Subscription

Path: /v2/stripe/subscription

Method: GET

Access: Private API

Description: Returns the Stripe subscription details for a specific allocation or operational wallet (blobber and validator pair).

Query Parameters:

  • Use either of the following:

    • allocation_id=alloc_abc123

    • blobber_client_id=blobber123&validator_client_id=validator456

Response:

  • Status: 200 OK

  • Content-Type: application/json

{
  "subscription_id": "sub_1P0abc123xyz",
  "customer_id": "cus_abc123xyz",
  "stripe_allocation_details": {
    "allocation_id": "alloc_abc123",
    "allocation_size": 107374182400,
    "allocation_expiry": 1750000000
  },
  "stripe_chimney_details": {
    "blobber_client_id": "blobber123",
    "validator_client_id": "validator456"
  },
  "stripe_rent_blobber_details": {
    "blobber_id": "blobber123",
    "delegate_wallet": "wallet_xyz",
    "shift_price_id": "price_1P0def456uvw"
  },
  "app_type": "blimp",
  "cancel_at": "2025-07-01T12:00:00Z",
  "subscription_start": "2025-06-01T12:00:00Z",
  "subscription_end": "2025-07-01T12:00:00Z",
  "discount": 0,
  "plan_id": "price_1P0abc123xyz",
  "plan_meta_data": "blimp:: 100gb",
  "duration": "month",
  "status": "active"
}

Logic:

  • Uses provided allocation_id or (blobber_client_id, validator_client_id) to query internal DB

  • Fetches subscription metadata and links it to the Stripe customer and plan

Get All Stripe Subscriptions

Path: /v2/stripe/subscriptions

Method: GET

Access: Private API

Description: Returns all active Stripe subscriptions for the authenticated user.

Query Parameters (Optional):

  • ai_subscription=true → filters only AI agent subscriptions

Sample Requests:

GET /v2/stripe/subscriptions
GET /v2/stripe/subscriptions?ai_subscription=true

Response:

  • Status: 200 OK

  • Content-Type: application/json

[
  {
    "subscription_id": "sub_1P0abc123xyz",
    "customer_id": "cus_abc123xyz",
    "plan_id": "price_1P0abc123xyz",
    "app_type": "blimp",
    "plan_meta_data": "blimp:: 100gb",
    "duration": "month",
    "status": "active",
    "subscription_start": "2025-06-01T12:00:00Z",
    "subscription_end": "2025-07-01T12:00:00Z"
  },
  {
    "subscription_id": "sub_1P0ai789xyz",
    "customer_id": "cus_abc123xyz",
    "plan_id": "price_1P0ai789xyz",
    "app_type": "ai",
    "plan_meta_data": "ai:: pro",
    "duration": "month",
    "status": "active",
    "subscription_start": "2025-06-15T12:00:00Z",
    "subscription_end": "2025-07-15T12:00:00Z"
  }
]

Logic:

  • Fetches subscriptions tied to the user’s Stripe customer ID

  • Filters based on app_type if ai_subscription=true

20. Get Active Rent Blobber Subscriptions

Path: /v2/stripe/rent-blobber-subscriptions

Method: GET

Access: Private API

Description: Returns all active rent blobber subscriptions linked to the authenticated user.

Response:

  • Status: 200 OK

  • Content-Type: application/json

[
  {
    "subscription_id": "sub_1P0rent001xyz",
    "customer_id": "cus_abc123xyz",
    "blobber_id": "blobber123",
    "delegate_wallet": "wallet_xyz",
    "shift_price_id": "price_1P0rentxyz",
    "plan_id": "price_1P0rentxyz",
    "app_type": "blimp",
    "duration": "year",
    "status": "active",
    "subscription_start": "2025-01-01T00:00:00Z",
    "subscription_end": "2026-01-01T00:00:00Z"
  }
]

Logic:

  • Queries all subscriptions where stripe_blobber_id IS NOT NULL

  • Filters only active records tied to the authenticated user

Get Stripe Payment Intents

Path: /v2/stripe/payment-intents Method: GET Access: Private API

Description: Returns all Stripe payment intents (i.e., payment transaction records) for the currently authenticated user. This includes both one-time payments and subscription-related charges. The data is fetched using the user’s Stripe customer ID and includes relevant metadata for each payment.

Response: Status: 200 OK Content-Type: application/json

jsonCopyEdit[
  {
    "payment_intent": "pi_1P0abc123xyz",
    "amount": 1500,
    "currency": "usd",
    "status": "succeeded",
    "date": "2025-07-01T12:00:00Z",
    "description": "Purchase 100GB storage",
    "allocation_id": "alloc_abc123",
    "subscription_id": null
  },
  {
    "payment_intent": "pi_1P0def456uvw",
    "amount": 2500,
    "currency": "usd",
    "status": "pending",
    "date": "2025-07-10T10:00:00Z",
    "description": "Yearly subscription upgrade",
    "allocation_id": null,
    "subscription_id": "sub_1P0xyzsub456"
  }
]
    "date": "2025-07-10T12:00:00Z",
    "description": "Upgrade to 200GB",
    "allocation_id": "alloc_def456",
    "subscription_id": "sub_1P0def456uvw"
  }
]
PreviousDEX State APIs and User NotificationsNextAI APIs

Last updated