Payment Integration

Introduction

Show me the money! ZapStart uses Stripe for payment processing, which makes it easy to handle one-time payments and subscriptions.

Setting Up Stripe

Let's get your Stripe account ready:

1. Go to Stripe and create an account
2. Complete the account creation and verification process (you may need to provide some business information along with your bank account details), this is covered in details in the ZapStart Company-Setup Guide.
3. By default, you'll be in Test Mode, which is for development purposes.
4. Configure your account settings for a professional appearance:
   • In Settings > Public Details, add your website URL
   • In Settings > Branding, upload your logo and set your brand colors
   • In Settings > Customer Emails, enable notifications for successful payments and refunds
   • In Settings > Customer Portal, activate the customer portal link (this is for subscription management)
5. Set up fraud prevention measures:
   • Search for "rules" in the dashboard search box
   • Navigate to Fraud Prevention > Rules
   • Ensure the first 3D Secure rule is enabled (required in many regions)
   • Consider enabling the second rule as well (recommended for additional security)
   • Configure settings to block payments if CVC verification fails

Getting Your API Keys

Now, let's get the API keys needed for ZapStart:

1. In the Stripe dashboard, ensure you're in the correct mode:
   • Test Mode: For development (fake payments)
   • Live Mode: For production (real payments)
2. Go to Developers > API keys (note we're in the Test Mode)
3. You'll see your:
   • Publishable key (safe to use in frontend), we won't use this key in the frontend, but copy it to the .env file in the backend directory
   • Secret key (must only be used in backend).

STRIPE_PUBLIC_KEY=your_publishable_key
STRIPE_SECRET_KEY=your_secret_key

Creating Products and Plans

Let's create a recurring subscription payment product in Stripe and configure your ZapStart application to use it:

Creating a Recurring Subscription Product

1. In your Stripe Dashboard, go to Products (in the left sidebar)
2. Click + Add product
3. Configure your product:
   • Name: Enter a descriptive name (e.g., "Pro Package")
   • Description: Describe what customers get with this product
   • Optionally add an image to represent your product
4. In the Pricing section:
   • Make sure Recurring is selected (not one-time)
   • Enter the price amount (e.g., $20.00)
   • Choose your currency (e.g., USD)
5. Click Save product
6. After saving, you'll be taken to the product detail page. click on the three dots on the right of the pricing table and click on the Copy Price ID

Updating Your Configuration Files

Now that you have your Price ID, you need to update your configuration files:

1. Update Backend Configuration

Open backend/configBack.js and make these changes:

• Set oneTime: false at the top of the file (if you want to use the one-time payment product, set it to true)
• Find the plans object
• Locate the Pro plan entry
• Replace the PRICE_ID value with your Stripe Price ID

2. Update Frontend Configuration

Open frontend/configFront.js and make these changes:

• Set oneTime: false at the top of the file (if you want to use the one-time payment product, set it to true)
• Find the stripe.plans array
• Locate the second object in the array (the paid plan, where free: false)
• Update the priceId of the conditional values:
  • For development: Your test mode Price ID
  • For production: Your live mode Price ID (you'll get this later when ready for production)

Setting Up Stripe Webhooks

Webhooks let Stripe notify your app about events like successful payments, it will communicate with our backend webhook endpoint which is /api/subscription/webhook:

For Local Development

1. Install the Stripe CLI from here, go and follow the instructions for your specific platform:
   https://docs.stripe.com/stripe-cli?install-method=homebrew
2. After you have installed the Stripe CLI, login to your Stripe account via the CLI:
   stripe login

   This will open your browser and ask you to authorize the CLI to access your account.

3. Start listening for webhooks:
   stripe listen --forward-to http://localhost:8000/api/webhooks/stripe

   The CLI will display a webhook signing secret, copy it to the STRIPE_WEBHOOK_SECRET= in the .env file in the backend directory.

.env

STRIPE_WEBHOOK_SECRET=your_webhook_signing_secret

Testing Payments Locally

Now that your Stripe keys are set up, it's time to test the payment flow:

1. Make sure your backend server is running with the Stripe environment variables set, you may require to restart the server.
2. Use Stripe's test card numbers for the checkout page:
   • 4242 4242 4242 4242 - Successful payment
   • 4000 0000 0000 0002 - Card declined
   • 4000 0025 0000 3155 - Requires authentication (3D Secure)

Production Setup

When you're ready to go live with real payments, you'll need to set up production webhooks:

1. Turn OFF Test Mode in your Stripe Dashboard to switch to live mode
2. In the Stripe dashboard, go to Developers > Webhooks
3. Click Add endpoint
4. Enter your webhook URL (e.g., https://api.yourdomain.com/api/webhooks/stripe)
5. Select the events you want to receive:
   • checkout.session.completed
   • customer.subscription.deleted
   • invoice.paid
   • You can add more events if you want to, but these are the most important ones.
6. Click Add endpoint
7. Retrieve the signing secret and update your production environment variables (you can find the secret and public keys in Developers > API keys):
   Stripe Dashboard

   STRIPE_PUBLIC_KEY=your_publishable_key
   STRIPE_SECRET_KEY=your_secret_key
   STRIPE_WEBHOOK_SECRET=your_webhook_signing_secret
   

8. Create a product in production mode and copy the Price ID to the config files (backend/configBack.js and frontend/configFront.js)
9. Optional: Configure your payout schedule:
   • Go to Balance > Manage Payouts
   • Set a specific monthly payout date if you prefer consolidated payments (e.g., the 10th of each month)
10. Create products in production mode and copy the Price ID to the config files and update the pricing value in the frontend config file