[Documentation] Provide an intro tutorial

[danieljaouen]

After browsing both Stripe's API and the Stripity Stripe documentation, I am still unclear on how to:

1. Charge a card given its information (number, CVV, etc.), and
2. Store that card on Stripe's servers for PCI compliance

Would it be possible to give an introductory tutorial on how to use the library either in the GitHub readme or in the official documentation?

Thanks.

[tmstieff]

I can provide a more advanced write up in a bit, but it is suggested to use the setup / payment intents now instead of the simple token flow. Unfortunately it is a little more involved, especially on the frontend side, and I have some open questions regarding that myself. For the token flow, which can still be used for North American payments, see below.

# When the user registers, go ahead and create a new Stripe user for them, and then 
# link the two in your system for further reference
def create_stripe_customer(%User{} = user) do
    customer = %{
      email: user.email,
    }

    {:ok, customer} = Stripe.Customer.create(customer)

    # You will need a field on your user table to update the "stripe_customer_id"
    {:ok, _user} = Auth.update_user(user, %{stripe_customer_id: customer.id})
end

# With a customer created, you can now associate cards to them, but you will need to get 
# a token from the frontend using https://stripe.com/docs/stripe-js if you want to avoid 
# PCI issues. The user will enter CC details, and Stripe will respond with a token 
# and the sanitized CC details through an iframe. Pass this token and sanitized CC 
# data to your backend, then you can do the following.
def associate_card(token_id, user) do
    {:ok, card} = Stripe.Card.create(%{customer: user.strip_customer_id, source: token_id})

    # Also, if you want, you can set this as the customer's default card
    {:ok, _} -> Stripe.Customer.update(customer_id, %{default_source: card.id})

    # Here, you can also store the sanitized card details in your database, 
    # or just proxy back to Stripe to get the customer's cards with Stripe.Card.list(%{customer: user.stripe_customer_id}
end

# Now you can charge the customer and card combination by creating a new charge
def submit_order(user, amount, card) do
    # Requires order to be submitted in cents
    cents = Decimal.mult(amount, 100)
    cents_int =
      cents
      |> Decimal.round()
      |> Decimal.to_integer()
    
    # Use the card.id from when you created the credit card in Stripe, or, 
    # get the customer's default card by call getting the customer from Stripe
    card_id = card.id

    case Stripe.Charge.create(%{
      amount: cents_int,
      currency: "USD",
      customer: user.stripe_customer_id,
      source: card_id,
      receipt_email: user.email,
      description: "A description to appear on the Stripe invoice"
    }) do
      {:ok, order} -> {:ok, order}
    end
end

This excludes any error handling, but explains the general flow for token based charges. If you are planning on doing any business in Europe, you'll need to use the newer https://stripe.com/docs/payments/setup-intents API.

[jmpressman]

I second that this would be a great resource to have, particularly documentation/examples surrounding the Setup Intents API seeing as that is the new standard to aim for.

[github-actions]

This issue has been automatically marked as "stale:discard". If this issue still relevant, please leave any comment (for example, "bump"), and we'll keep it open. We are sorry that we haven't been able to prioritize it yet. If you have any new additional information, please include it with your comment.

[github-actions]

Closing this issue after a prolonged period of inactivity. If this issue is still relevant, feel free to re-open the issue. Thank you!