:PROPERTIES:
:ID:       6af95849-8f78-4697-ab48-3712ff2f5ee1
:END:
#+title: Stripe payments tracking database
#+OPTIONS: ^:nil

Database for tracking payments and subscriptions managed by the [[id:9b3ed74d-41d4-4784-89e3-6a9183903b9e][Stripe Payments Service]].
* State Tracking
** Legacy purchase
- Client initiates purchase
- Backend coordinates with Stripe and returns a payment intent
  + Track new purchase and related incomplete payment
- Client completes purchase with Stripe
- Stripe notifies backend of payment intent status (update purchase)
  + Track event
  + Track payment as completed
  + Fulfill purchase
  + Track purchase as fulfilled

#+begin_src plantuml :file stripe-legacy-purchase-tracking.svg
  participant Stripe
  actor Client
  participant "stripe-payments" as Backend
  database Tracking

  Client -> Backend: Initiate purchase
  Backend -> Tracking : <font color="blue">Store incomplete purchase</font>
  Backend -> Stripe : Create payment intent
  Backend -> Tracking : <font color="blue">Store incomplete payment</font>
  Backend -> Client : Return payment intent
  Client -> Stripe : Complete purchase
  ...
  alt Success
    Stripe ---> Backend : payment_intent.succeeded
    Backend -> Tracking : <font color="green">Store event</font>
    alt Event not previously handled
      Backend -> Tracking : <font color="blue">Mark payment as succeeded</font>
      Backend -> Backend : Fulfill purchase
      Backend -> Tracking : <font color="blue">Mark purchase as fulfilled</font>
    end
  else Failure
    Stripe --> Backend : payment_intent.payment_failed
    Backend -> Tracking : <font color="green">Store event</font>
  end

#+end_src

#+RESULTS:
[[file:stripe-legacy-purchase-tracking.svg]]

#+caption: Legacy purchase flow with events
#+RESULTS:

** Product purchase
- Client prepares payment method with Stripe
- Client initiates purchase
- Backend coordinates with Stripe to complete the purchase
  + Attaches the payment method to the customer
  + For single products
    - Creates an invoice item
    - Creates an invoice
    - Pays the invoice
  + For subscriptions
    - Creates the subscription

#+begin_src plantuml :file stripe-purchase-tracking.svg
  participant Stripe
  actor Client
  participant "stripe-payments" as Backend
  database Tracking

  Client -> Stripe : Create payment method
  Client -> Backend: Initiate purchase
  Backend -> Tracking : <font color="blue">Store incomplete purchase</font>
  alt Non-recurring
          Backend -> Stripe : Create invoice item
          Backend -> Stripe : Create invoice
          Backend -> Stripe : Pay invoice
          Backend -> Tracking : <font color="blue">Store completed payment</font>
  else Recurring
          Backend -> Stripe : Create subscription
          Backend -> Tracking : <font color="blue">Store active subscription</font>
  end
  ...
  Stripe --> Backend : Subscription activated
  ...
  alt
          Stripe --> Backend : customer.subscription.updated (no longer active)
  else
          Stripe --> Backend : subscription_schedule.canceled
  end
  Backend -> Tracking : <font color="green">Store event</font>
  Backend -> Backend : Trigger unsubscribe actions
  Backend -> Tracking : <font color="blue">Mark subscription as terminated</font>
#+end_src

#+caption: Product purchase flow
#+RESULTS:
[[file:stripe-purchase-tracking.svg]]

#+begin_src plantuml :file stripe-purchase-tracking-payment-events.svg
  participant Stripe
  actor Client
  participant "stripe-payments" as Backend
  database Tracking

  == Payment succeeded ==
  Stripe --> Backend : payment_intent.succeeded
  Backend -> Tracking : <font color="green">Store event</font>
  alt Event not previously handled
          Backend -> Tracking : <font color="blue">Mark payment as succeeded</font>
          Backend -> Stripe : Look up invoice

          note over Backend
                  Recurring if an invoice exists
                  and has an associated subscription
          end note
          alt Non-recurring
                  Backend -> Backend : Fulfill purchase
                  Backend -> Tracking : <font color="blue">Mark purchase as fulfilled</font>
          else Recurring
          end
  end
  == Payment failed ==
  Stripe --> Backend : payment_intent.payment_failed
  Backend -> Tracking : <font color="green">Store event</font>
#+end_src

#+caption: Payment events
#+RESULTS:
[[file:stripe-purchase-tracking-payment-events.svg]]

#+begin_src plantuml :file stripe-purchase-subscription-events.svg
  participant Stripe
  actor Client
  participant "stripe-payments" as Backend
  database Tracking

  == Subscription activated ==
  alt
          Stripe --> Backend : customer.subscription.created (active)
  else
          Stripe --> Backend : customer.subscription.updated (active)
  end
  Backend -> Tracking : <font color="green">Store event</font>
  alt New subscription
          Backend -> Tracking : <font color="blue">Mark subscription as active</font>
          Backend -> Backend : Fulfill purchase
          Backend -> Tracking : <font color="blue">Mark purchase as fulfilled</font>
  else Subscription already processed
          note over Backend
                  One of the following is true:

                  <font color="green">- Already received an activation event for this subscription</font>
                  <font color="green">- Already receieved a termination event for this subscription</font>
                  <font color="blue">- Subscription already marked as active or terminated</font>
                  <font color="blue">- Purchase already marked as fulfilled</font>
          end note
  end
  == Subscription terminated ==
  alt
          Stripe --> Backend : customer.subscription.updated (no longer active)
  else
          Stripe --> Backend : subscription_schedule.canceled
  end
  Backend -> Tracking : <font color="green">Store event</font>
  alt Active subscription
          Backend -> Backend : Trigger unsubscribe actions
          Backend -> Tracking : <font color="blue">Mark subscription as terminated</font>
  else Subscription not yet processed
          note over Backend
                  One of the following is true:

                  <font color="green">- Did not receive an activation event for this subscription</font>
                  <font color="blue">- Subscription is not tracked</font>
          end note
  else Subscription already terminated
          note over Backend
                  One of the following is true:

                  <font color="green">- Already received a termination event for this subscription</font>
                  <font color="blue">- Subscription already marked as terminated</font>
          end note
  end
#+end_src

#+caption: Subscription events
#+RESULTS:
[[file:stripe-purchase-subscription-events.svg]]

* Tables
** Purchases
Purchases made via the [[id:9b3ed74d-41d4-4784-89e3-6a9183903b9e][Stripe Payments Service]].

#+begin_src plantuml :file stripe-purchase-states.svg
  [*] -> New
  New -> Fulfilled
#+end_src

#+caption: Purchase state diagram
#+RESULTS:
[[file:stripe-purchase-states.svg]]

#+caption: Purchases
| Field          | Type      | Nullable | Description                                |
|----------------+-----------+----------+--------------------------------------------|
| id             | UUID      | N        | Auto-generated purchase ID                 |
| created        | timestamp | N        | Time the purchase was initiated            |
| last_updated   | timestamp | N        | Time the purchase was last updated         |
| account        | UUID      | N        | The AWeber customer account purchased from |
| stripe_account | text      | N        | The Stripe account of the AWeber customer  |
| fulfilled      | boolean   | N        | Was this purchase fulfilled                |

- Store which automations were applied & when
** Subscriptions and Split Payments
Purchases made with recurring payments, managed using a Stripe Subscription.

#+begin_src plantuml :file stripe-subscription-states.svg
  [*] -> New
  New -> Active
  Active --> Terminated : Payment Failed
  Active --> Terminated : Unsubscribed
  New --> Terminated : Payment Failed
#+end_src

#+caption: Subscription state diagram
#+RESULTS:
[[file:stripe-subscription-states.svg]]

#+caption: Subscriptions
| Field          | Type                | Nullable | Description                                             |
|----------------+---------------------+----------+---------------------------------------------------------|
| id             | text                | N        | The Stripe subscription ID                              |
| created        | timestamp           | N        | Time the purchase was initiated                         |
| last_updated   | timestamp           | N        | Time the purchase was last updated                      |
| account        | UUID                | N        | The AWeber customer account the subscription belongs to |
| stripe_account | text                | N        | The Stripe account of the AWeber customer               |
| status         | [[subscription_status][subscription_status]] | N        | Status of the subscription                              |

<<subscription_status>>
#+caption: ENUM: Subscription Status
| new        |
| active     |
| terminated |
** Payments
Payments collected from buyers.

#+begin_src plantuml :file stripe-payment-states.svg
  [*] -> New
  New --> Paid : Payment succeeded
  New --> Failed : Payment failed
#+end_src

#+caption: Payment state diagram
#+RESULTS:
[[file:stripe-payment-states.svg]]

#+caption: Payments
| Field          | Type           | Nullable | Description                               |
|----------------+----------------+----------+-------------------------------------------|
| id             | text           | N        | The Stripe payment intent ID              |
| created        | timestamp      | N        | Time the purchase was initiated           |
| last_updated   | timestamp      | N        | Time the purchase was last updated        |
| account        | UUID           | N        | The AWeber customer account that was paid |
| stripe_account | text           | N        | The Stripe account of the AWeber customer |
| purchase       | UUID           | N        |                                           |
| status         | [[payment_status][payment_status]] | N        | Status of the payment intent              |

<<payment_status>>
#+caption: ENUM: Payment Status
| new    |
| paid   |
| failed |
** Events
#+caption: Events
| Field          | Type      | Nullable | Description                                             |
|----------------+-----------+----------+---------------------------------------------------------|
| id             | text      | N        | Stripe event id                                         |
| type           | text      | N        | Stripe event type                                       |
| account        | UUID      | N        | The AWeber customer account the subscription belongs to |
| stripe_account | text      | N        | The Stripe account of the AWeber customer               |
| timestamp      | timestamp | N        | Time event was published                                |
| subscription   | text      | Y        | Related Stripe subscription ID                          |

Events should expire out of the database over time. Stripe maintains events in
its database for up to 30 days.
*** Modeling in DynamoDB
**** Table
- Partition Key :: =id=

The table index provides for rapid lookup of individual events.
**** Attributes
| Field          | Type                    | Required | Description                                               |
|----------------+-------------------------+----------+-----------------------------------------------------------|
| id             | String                  | Y        | Stripe event id                                           |
| type           | String                  | Y        | Stripe event type                                         |
| stripe_account | String                  | Y        | The Stripe account of the AWeber customer                 |
| timestamp      | String (timestamp)      | Y        | Time event was published (e.g. "2020-01-01 01:02:34.567") |
| date           | String (date)           | Y        | Date portion of timestamp (e.g. "2020-01-01")             |
| time           | String (time)           | Y        | Time portion of timestamp (e.g. "01:02:34.567")           |
| expiration     | Number (Unix timestamp) | Y        | TTL expiration time of the event record                   |
| subscription   | String                  | N        | Related Stripe subscription ID                            |
**** TTL
The events table will automatically expire and remove rows for which
=expiration= has passed. We may set =expiration= to be the event creation time
plus thirty days to match Stripe's own expiration. This will prevent old items
from piling up in the table.
**** Time index (GSI)
- Partition Key :: =date=
- Sort Key :: =time=
- Projection :: Keys Only


The date and time portions of the event timestamp will be separated to allow for
scanning all events within a day, filterable by time. This should support our
polling job, which should run multiple times per day. We'll have to be careful
around date boundaries when looking up events (e.g. by including a query for
events from the previous day during the first run of the current day).
**** Stripe Account index (GSI)
- Partition Key :: =stripe_account=
- Sort Key :: =timestamp=
- Projection :: Include type, subscription

The account index provides for rapid lookup of events for a particular stripe
account, filterable by timestamp.
**** Subscription index (GSI)
- Partition Key :: =subscription=
- Sort Key :: =timestamp=
- Projection :: Include type, stripe_account

The account index provides for rapid lookup of events for a particular
subscription, filterable by timestamp.
**** IAM Policy
Put together by referencing [[id:ab2d34bf-97b1-4e50-8e9a-597d0f8fcf01][DynamoDB IAM Policies]].
#+caption: Stripe Payments DynamoDB IAM Policy
#+begin_src json
  {
      "Version": "2012-10-17",
      "Statement": [
          {
              "Effect": "Allow",
              "Action": "dynamodb:ListTables",
              "Resource": "*"
          },
          {
              "Effect": "Allow",
              "Action": [
                  "dynamodb:BatchGetItem",
                  "dynamodb:BatchWriteItem",
                  "dynamodb:ConditionCheckItem",
                  "dynamodb:PutItem",
                  "dynamodb:DeleteItem",
                  "dynamodb:Scan",
                  "dynamodb:Query",
                  "dynamodb:UpdateItem",
                  "dynamodb:DescribeTimeToLive",
                  "dynamodb:CreateTable",
                  "dynamodb:DescribeTable",
                  "dynamodb:GetItem",
                  "dynamodb:UpdateTable",
                  "dynamodb:UpdateTimeToLive"
              ],
              "Resource": [
                  "arn:aws:dynamodb:*:018154689201:table/*-stripe-payments-*/index/*",
                  "arn:aws:dynamodb:*:018154689201:table/*-stripe-payments-*"
              ]
          },
      ]
  }
#+end_src
* Notes
- How does the [[id:83d61eef-0781-46e0-b959-1a739cff5ea3][poller]] use these stored events?
  + /To identify events retrieved from Stripe which do not need to be replayed/
- How do we replay events?
  + Send it to the webhook endpoint? An internal webhook endpoint that shares
    code with the public one?
    - /The same webhook endpoint would be preferable, requires signing the
      payload/
- Do we expose the processed events as an internal endpoint in the
  stripe-payments service, or give the polling app a database connection?
  + /API seems preferable/

Following some discussion, the [[Events][Events]] table should be sufficient for now.