How Stripe Generates Subscription Payments for Agency Handy

Since Agency Handy integrates with Stripe for subscription payments, here's a detailed breakdown of the backend process—from subscription creation to transaction recording and processing.


1. Subscription Setup (Initial Creation)

When a user subscribes to Agency Handy through Stripe, the backend follows these steps:

a. Creating a Customer in Stripe

  • When a new user subscribes, Agency Handy sends a request to Stripe to create a customer.

  • Stripe generates a Customer ID (cus_xxx) and stores user payment details (card/bank info).

  • Customer data is securely stored in Stripe, while only the Customer ID is saved in Agency Handy’s database.

b. Creating a Subscription

  • Agency Handy sends a request to Stripe to create a subscription plan (monthly/yearly).

  • Stripe assigns a Subscription ID (sub_xxx) to track the user’s plan.

  • Payment methods are linked to this subscription.

  • Stripe sets up recurring billing based on the selected plan.


2. Payment Processing for Subscriptions

Once the subscription is set up, Stripe follows these steps to process payments:

a. Charging the Customer

  • On the billing cycle date, Stripe automatically attempts to charge the saved payment method.

  • If successful, Stripe marks the subscription as active and generates an invoice.

  • If payment fails, Stripe retries according to its Smart Retries logic (e.g., after 1 day, 3 days, 7 days).

b. Generating an Invoice

  • After a successful charge, Stripe creates an invoice (in_xxx) that records:

    • Amount Charged

    • Payment Status

    • Subscription Details

    • Breakdown of Taxes & Discounts (if any)

c. Webhook Notification to Agency Handy

  • Stripe sends a webhook event (invoice.payment_succeeded) to Agency Handy.

  • Agency Handy updates the user’s subscription status to active.

d. Handling Failed Payments

  • If payment fails, Stripe triggers an event (invoice.payment_failed).

  • Agency Handy is notified and can:

    • Pause access to services.

    • Send a reminder email to update payment.

    • Retry the charge before canceling the subscription.


3. Transaction Recording & Processing

Every transaction in Stripe follows a structured process:

a. Creating a Charge Record

  • Each successful charge generates a Charge ID (ch_xxx) in Stripe.

  • The charge is linked to the invoice (in_xxx) and subscription (sub_xxx).

b. Recording Payments

  • Stripe logs the payment method (e.g., Visa ending in 1234).

  • The transaction is recorded in Stripe’s dashboard under Payments.

  • Agency Handy receives webhook data and updates its internal database.

c. Payouts to Agency Handy

  • Stripe collects payments from users but holds the funds in a Stripe balance.

  • Payouts to your bank account occur on a set schedule (daily or weekly).

  • Each payout generates a Payout ID (po_xxx) and is recorded.

d. Refunds & Disputes

  • Agency Handy doesn't allow user requests for refunds through Stripe.

  • If there’s a charge dispute, Stripe handles it by reviewing evidence.

  • Disputed amounts are temporarily held until resolved.


4. Summary of Stripe’s Key IDs & Data Flow

Step

Stripe Object

ID Format

Purpose

Customer Creation

customer

cus_xxx

Stores user details securely.

Subscription

subscription

sub_xxx

Tracks recurring billing.

Invoice

invoice

in_xxx

Records payment details.

Payment Charge

charge

ch_xxx

Represents the transaction.

Payout

payout

po_xxx

Transfers funds to Agency Handy’s bank.

Webhook Events

event

evt_xxx

Notifies Agency Handy of changes.


Final Flow of Subscription Payments

  1. User subscribes → Agency Handy creates a Customer and Subscription in Stripe.

  2. Stripe charges the user on renewal date.

  3. Stripe generates an invoice and marks it paid.

  4. Webhook updates Agency Handy → Subscription is confirmed active.

  5. Payments accumulate in Stripe balance.

  6. Stripe sends payout to Agency Handy's bank.

  7. Agency Handy updates its database with the transaction.

Last updated

Was this helpful?