Stripe Payment Gateway

Overview

Stripe is a versatile payment gateway that supports credit card payments and PayTo (Australian New Payments Platform) bank payments. It provides a modern, secure payment processing experience with real-time webhook notifications.

Key Features

• Credit Card Payments - Accept Visa, Mastercard and American Express via Stripe Elements

• PayTo Bank Payments - Australian real-time bank payments via the NPP (New Payments Platform)

• PayTo Mandates - Set up recurring direct debit mandates approved through the customer's mobile banking app

• One-Off Bank Payments - Accept single payments using BSB/account number or PayID

• Webhook Integration - Automatic payment status updates and mandate lifecycle management

• Tokenised Storage - Secure card and bank account tokenisation (no sensitive data stored locally)

• Surcharge Support - Configurable surcharges per card type

How Stripe Works

1. Gateway is configured - Add your Stripe API keys and webhook secret in Pracbill

2. Customer makes a payment - Via credit card or PayTo bank payment

3. Stripe processes the payment - Securely handles all sensitive data

4. Webhook confirms the result - Pracbill is notified when payment succeeds or fails

Setting Up Stripe

Prerequisites

Before you begin, you'll need:

• A Stripe account (stripe.com)

• Your Stripe Publishable Key (public key)

• Your Stripe Secret Key (private key)

• Your Webhook Signing Secret

Step 1: Create a Stripe Account

1. Go to stripe.com and sign up for an account

2. Complete the identity verification and business details

3. For testing, use Stripe's Test Mode first (toggle in the dashboard)

Step 2: Get Your API Keys

1. Log in to your Stripe Dashboard

2. Navigate to Developers → API Keys

3. Copy your Publishable key (starts with pk_test_ or pk_live_)

4. Copy your Secret key (starts with sk_test_ or sk_live_)

Step 3: Set Up Webhooks

1. In the Stripe Dashboard, navigate to Developers → Webhooks

2. Click Add endpoint

3. Set the endpoint URL to: https://billing.pracbill.com.au/api/stripe/webhook

4. Select the following events to listen to:

   • payment_intent.succeeded

   • payment_intent.payment_failed

   • setup_intent.succeeded

   • setup_intent.setup_failed

   • mandate.updated

5. Click Add endpoint

6. Copy the Signing secret (starts with whsec_)

Step 4: Configure Stripe in Pracbill

1. Navigate to Admin → Payment Options

2. Click Add New Payment Gateway

3. Select Stripe from the gateway list

4. Enter your configuration:

5. Click Save

Step 5: Enable Payment Types

In the Payment Options configuration:

1. Check the payment types you want to accept:

   • Visa - Visa credit/debit cards

   • Mastercard - Mastercard credit/debit cards

   • Amex - American Express cards

   • PayTo - Australian bank payments (see PayTo section below)

   • Direct Debit - Bank direct debit

2. Set any surcharges if applicable (see Surcharges section)

3. Save your changes

Credit Card Payments

Taking a Card Payment

1. Navigate to the customer or invoice

2. Click Take Payment

3. Enter card details in the Stripe Elements form

4. Click Process Payment

Card payments are processed in real-time and the result is displayed immediately.

Saving a Card

When taking a payment, the card is automatically tokenised and saved as a payment method for future use. No card numbers are stored in Pracbill - only a secure Stripe token.

PayTo (Australian Bank Payments)

PayTo is an Australian real-time payment system built on the New Payments Platform (NPP). It enables customers to pay directly from their bank account using either their BSB/account number or PayID.

What is PayTo?

PayTo allows two types of bank payments:

• One-Off Payments - Customer enters their bank details for a single payment

• Mandate-Based Recurring Payments - Customer approves a recurring payment agreement through their mobile banking app, allowing you to collect payments automatically

Enabling PayTo

1. Navigate to Settings → Payments → Payment Methods

2. Edit your Stripe gateway configuration

3. Check the PayTo option under Payment Types

4. Save your changes

Once enabled, customers will see a PayTo (Bank Payment) tab alongside the credit card option when making payments.

One-Off Bank Payments

Customers can make a single bank payment using one of two input methods:

Method 1: BSB and Account Number

1. Select the PayTo (Bank Payment) tab on the payment screen

2. Choose BSB and Account Number

3. Enter:

   • BSB - 6-digit Bank State Branch number (e.g., 012-345)

   • Account Number - 5 to 9 digit account number

   • Account Holder Name - Name on the bank account

4. Click Process Payment

Method 2: PayID

1. Select the PayTo (Bank Payment) tab

2. Choose PayID

3. Select the PayID type:

   • Email - An email address registered as a PayID

   • Phone - An Australian phone number registered as a PayID

   • ABN - An Australian Business Number registered as a PayID

4. Enter the PayID value

5. Click Process Payment

Setting Up a PayTo Mandate (Recurring Payments)

PayTo mandates allow you to set up an ongoing payment agreement that the customer approves through their banking app. Once approved, you can collect payments automatically.

Step 1: Create the Mandate

1. Navigate to the customer record

2. Go to Payment Methods tab

3. Click Add Payment Method

4. Select Stripe as the gateway

5. Choose Set Up PayTo Mandate

6. Enter the mandate details:

7. Enter the customer's bank details (BSB/account or PayID)

8. Click Create Mandate

Step 2: Customer Approves the Mandate

1. The customer receives a notification in their mobile banking app

2. They review the mandate details (your business name, amount, schedule)

3. They approve the mandate in their banking app

4. Pracbill receives a webhook notification confirming the mandate is active

Step 3: Collecting Payments

Once the mandate is approved:

• Automatic Payments - If the customer has the PayTo method set as Primary, invoices are automatically charged on the due date

• Manual Payments - Navigate to the invoice, click Take Payment, and select the PayTo payment method

PayTo Payment Lifecycle

Note: PayTo payments via the NPP are typically faster than traditional direct debits, often settling within the same business day.

Webhooks

Stripe sends webhook events to notify Pracbill of payment and mandate status changes. The webhook endpoint verifies the signature of every event to ensure authenticity.

Webhook URL

Configure this URL in your Stripe Dashboard:

Events Handled

Webhook Security

Stripe webhooks are secured with:

• Signature verification - Every webhook is verified using HMAC-SHA256 with your webhook secret

• Timestamp validation - Events older than 5 minutes are rejected to prevent replay attacks

• Idempotency - Duplicate events are detected and ignored

• Audit logging - All webhook events are logged for troubleshooting

Surcharges

You can configure surcharges per card type in the Payment Options settings. See the Payment Options page for details on surcharge configuration including custom surcharge keys for Visa, Mastercard and American Express.

Troubleshooting

Payment Shows as Failed

Common reasons for failed payments:

• Insufficient funds - Customer's account doesn't have enough funds

• Card declined - The card issuer declined the transaction

• Mandate revoked - Customer cancelled the PayTo mandate in their banking app

• Invalid bank details - BSB or account number was incorrect

PayTo Mandate Not Appearing

• The customer must approve the mandate in their mobile banking app

• Check that webhooks are correctly configured and the endpoint is accessible

• Verify the Webhook Secret in Pracbill matches the one in Stripe Dashboard

Webhook Signature Verification Failing

• Ensure the Webhook Secret in Pracbill matches your Stripe Dashboard

• Check that no proxy or firewall is modifying the request body

• Verify the webhook secret hasn't been regenerated in Stripe

Customer Can't See PayTo Option

• Verify PayTo is enabled in your Stripe Payment Options configuration

• PayTo is only available for Australian bank accounts (AUD transactions)

• Ensure the customer is on the payment screen (not a saved card selection)

Supported Features

Further Resources

• Stripe Documentation

• Stripe PayTo Documentation

• Understanding Payment Methods

• Adding a Credit Card as a Payment Method

• Adding a Bank Account as a Payment Method

• Automated Payments Setup