Skip to content

Latest commit

 

History

History
151 lines (102 loc) · 6.28 KB

payments-service-scenario.md

File metadata and controls

151 lines (102 loc) · 6.28 KB
Raw

Scenario 4: Payments integration with Stripe

This document will guide you through the prerequisites and commands necessary to setup and preview the portal project with complete Stripe integration, locally on your computer.

Project Structure

Within the packages folder, you will find the three projects that make up this scenario:

  • portal - The web app portal
  • api - The web app backend
  • stripe - The Stripe backend

Running this scenario

Note: This scenario has been optimised for use with GitHub Codespaces, a development environment hosted in the GitHub cloud, as we prepared predefined environment with everything installed.

Install the required Node.js packages

The repo is a monorepo, and thus contains all the components from all the scenarios. To support this npm workspaces has been configured, and as a result, all scenarios packages will be installed.

To install all packages required run the following command:

npm install --workspaces

Note: The devcontainer will automatically execute this command on creation, but you can execute it manually if you wish to see the installation happen.

Configuring Stripe

This scenario uses Stripe to handle payments. To use Stripe, you will need to create an account and obtain a set of API keys.

Note: it's possible to run the app without configuring Stripe at all: in that case, the payments will be mocked and accepted directly, so you can still test the flow.

  1. Create a free Stripe account here: https://dashboard.stripe.com/register
  2. Once you have created your account, you will be redirected to the Stripe dashboard. Click on the Developers menu item, and then click on the API keys tab on the left.
  3. Copy the Public key and Secret key and paste them into a new .stripe.env file in the root folder, like this:
STRIPE_PUBLIC_KEY=<your public key>
STRIPE_SECRET_KEY=<your secret key>

  1. Click on the Webhooks tab on the left, and then select the Add endpoint button. For the endpoint URL, enter http://dummy.com and choose the Select events option. Search for checkout, and enable the events checkout.session.completed and checkout.session.expired. Then click on the Add endpoint button. Note that the endpoint URL will need to be updated later on.

  2. Copy the Signing secret key from your webhook and paste it into the .stripe.env file, like this:

STRIPE_WEBHOOK_SECRET=<your webhook key>

Provisioning the Azure resources

Once your Stripe keys have been configured, you can provision the Azure resources required for this scenario. To do this, run the following command:

# Export the environment variables from the .stripe.env file
export $(cat .stripe.env | xargs)

# Login to azd (only required once the first time)
azd auth login

# Provision infrastructure and the azd development environment
azd provision

# Package the app using the environment variables in .azure/env + deploy the code on Azure
azd deploy

Except for the first command, the deployment commands are the same as the ones used in the Deploy to Azure guide.

After the deployment is complete, you will need to update the Stripe webhook endpoint URL with the one generated by the deployment.

  1. First, run the following command to get the endpoint URL:

    # Create a .env file with the environment variables from the azd environment
azd env get-values > .env

# Get the endpoint URL
source .env && echo "Your Stripe webhook endpoint URL is:\n$SERVICE_STRIPE_URI/stripe-api/stripe/webhook"

  2. Copy the resulting URL, and then go back to the Stripe dashboard, and select on the Webhooks tab on the left.

  3. Pick on the webhook you created earlier, click on the ... button then select Update details.

  4. Replace the http://dummy.com value with the URL you copied earlier, and then click on the Update endpoint button.

You should now have a fully working Stripe test integration.

Note: if you want to test the Stripe integration, you can use the Stripe test cards.

Running locally

By default, the project is configured to skip the Stripe integration with a warning, to make it easier to run locally without having to configure Stripe. If you want to run the Stripe integration locally, you need to edit the docker-compose.yml file to add this line to the stripe service definition:

services:
  stripe:
    build:
      context: .
      dockerfile: ./packages/stripe/Dockerfile
    environment:
      API_URL: http://host.docker.internal:7071
    ports:
      - "4242:4242"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    # Add this line to enable the Stripe integration
    env_file:
      - .stripe.env

This will enable the Stripe integration, and use the .stripe.env file you created to configure the Stripe keys.

If you want to debug the Stripe integration, you can use the Stripe CLI to forward the Stripe webhooks to your local machine. To do this, run the following command:

# Login to stripe (only required once the first time)
stripe login

# Forward the Stripe webhooks to your local machine
stripe listen --forward-to http://localhost:4242/stripe/webhook

At this point, the Stripe CLI will print a webhook secret key that's only valid for local testing. Copy this key, and paste it into the .stripe.env file, like this:

STRIPE_WEBHOOK_SECRET=<your local webhook key>

You can now run the project locally using the following command:

npm start

It will start the web app portal, the API, and the Stripe backend, and you can access the portal at http://localhost:4280.

You can now simulate Stripe events by using the Stripe CLI to send test events to your local machine. For example, to simulate a successful payment, you can run the following command:

stripe trigger checkout.session.completed

You should see the event being processed by your Stripe backend, and you can use it to debug your integration.

Payment service scenario diagram

This scenario is represented by the following diagram Contoso Real Estate Payment Service - Scenario 4