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 Stripe balance.

• Payouts to Agency Handy’s bank account happen on a set schedule (daily/weekly).

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

d. Refunds & Disputes

• Agency Handy doesn't allow user requests refund 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.