Community

1. Create an account on Stripe.com

To start selling listing membership subscriptions using the integrated 'Stripe Subscription' gateway module you must first create a Stripe account at https://stripe.com. If you already have an account please skip this step. It is free to create a Stripe account and using the test mode is also free. Visit https://dashboard.stripe.com/register page to start. The initial registration process is simple. Enter your Email, Full name, Country, the desired Password and click the 'Create account' button. This will immediately bring you to your account Dashboard if no errors were found in your submission. You will also have to verify your email by visiting the link sent to the email address specified on the registration page. Your account now works in test mode. To verify your account and start accepting real (live) payments please click 'Add business details to activate your account' link on the Dashboard page and follow the instructions.

2. Getting API keys.

When on the Stripe Dashboard click the 'Get your API keys' link. This will open a window with your 'Publishable key' and your 'Secret key'. Note that the 'Secret key' is hidden by default and you have to click the 'Reveal test/live key' button to make the key visible. Now you have to create a 'Webhook Secret' key. Click the 'Developers' link that appears in the left menu block of your Stripe Dashboard and click the 'Webhooks' submenu to open the endpoints configuration page. Click the 'Add Endpoint' button that will open a new window with your new endpoint configuration settings. You have to specify your endpoint URL and activate several events to notify your phpListings installation about subscription activation or cancellation. The default endpoint URL for phpListings is

https://www.example.com/account/checkout/notify/stripe

where www.example.com is your phpListings installation domain name.

You will also have to enable the following events for this endpoint:

• customer.subscription.deleted
• customer.subscription.created

Now, click the 'Add endpoint' button to create the webhook. This will bring you to the endpoint summary page. In the 'Signing Secret' block click the 'Click to reveal' button to get the 'Webhook Secret' key.

3. Enabling and configuring your phpListings Stripe Subscriptions module.

Now when you have all three API keys available please enable the 'Stripe Subscription' module for your phpListings installation under 'Administrator - Settings - Payment Gateways'. Click the 'Edit' button for the 'Stripe Subscription' module and enter your Stripe 'Secret Key' into the 'API Key' field, your 'Publishable Key' and your 'Webhook Secret' into the module configuration form. Click the 'Update' button to save your settings.

The next step is to enable the 'Stripe Subscription' module for your pricing plans under 'Administrator - Content - Listing Type Name - Products - Product Name - Pricings - Edit - Supported Payment Gateways'.

4. Stripe Subscription payment flow.

On listing submission or listing membership plan change a new invoice is created and a payment request notification is emailed to the listing owner. They have to login to their phpListings customer panel, navigate to the desired listing type search results page in their account dashboard by clicking the listing type name in the left menu, then find the listing to upgrade and click the 'Summary' button for that listing. This will bring the user to the listing summary page where they can check their listing order status and click the 'Invoices' button to get the list of all invoices associated with the listing. They can also get to this page by clicking the 'Unpaid Invoices' card on the account dashboard or by clicking the direct link they have received in the payment request email.

Now they have to click the 'Pay' button for the listing invoice they want to pay for. On the next page they have to select the payment gateway to use for their payment ('Stripe Subscription') and click the 'Pay Now' button that will redirect them to the Stripe payment page where they have to provide their contact details and the credit or debit card details they want to use for the subscription payment. On successful payment they are redirected back to your phpListings installation with a 'Pending Payment' confirmation. At the same moment Stripe sends the subscription data to your endpoint ('customer.subscription.created' event) using the webhook settings you specified on step 2 of this tutorial. If the payment was successful the invoice is marked as Paid immediately and this activates the listing paid membership for the subscription period set for the listing membership pricing plan.

A new invoice is generated automatically for the listing 3 days (configurable setting) before the expiration and if no subscription cancellation request is received via the endpoint (customer.subscription.deleted event) the invoice is marked as Paid automatically that makes the listing membership plan to be prolonged for another period (no payment request email is sent to the customer).

If the subscription cancellation event is received via the webhook the last paid listing invoice is cancelled and the listing membership plan gets suspended immediately. A listing cancellation email notification is sent to the customer. Please note that customer may cancel their subscription via their customer portal with two options available - 'Cancel Immediately' or 'Cancel at the end of the period' It is important to mention that both options will cancel the listing subscription immediately so we recommend to use the 'Cancel Immediately' option only.

If the customer card has expired or has insufficient funds available to prolong the subscription payment, Stripe will attempt to notify the client and check the funds availability for 3 times. If all attempts fail, the 'customer.subscription.deleted' event is sent to your endpoint that cancels the listing membership immediately.