# 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.