Zephr User Guide

Chargify

9 views 0

Chargify is a payment provider and subscription management platform.

The Zephr Chargify integration allows you to take payments and manage subscriptions to content. You can map Zephr Products to Chargify Price Points allowing a multitude of options for customers to pay for your content.

Pre-requisites

  • A Chargify account, configured with products and price point IDs
  • Zephr user attributes configured for users’ first names and last names (Chargify requires all customer records to have email, first name and last name, therefore these are also required in Zephr when using this extension)

Behaviour

The extension allows you to associate Chargify price points with Zephr Products as Payment Options.

Zephr Products that have been configured with Payment Options can be added to Zephr Payment Forms.

When a Zephr Chargify payment form is reached by an end-user, a payment form is rendered by Chargify JS. Payment details are submitted straight to Chargify, and do not pass through Zephr servers, nor are they stored by Zephr.

When a customer follows a successful payment flow, a corresponding customer record will be created in Chargify if one does not exist already. The customer will then be issued a temporary Zephr product grant allowing immediate access to relevant content.

From this moment, Zephr will listen for incoming webhook notifications denoting when a payment method has been successfully charged: when this notification is received, a Zephr product grant will be issued for the duration of the billing period (plus 24 hours as a grace period).

Following this pattern, the Zephr product grant will be renewed on each successful billing period until such time notifications cease.

Configuration

To enable the Chargify Extension within Zephr, navigate to Settings > Extensions > Chargify. If you cannot see this option in your list of Extensions, email support@zephr.com.

Once on the configuration screen, you’ll see a number of sections – API Configuration, Payment Form Configuration, Notification Configuration, Customer Configuration and Activate Plugin.

API Configuration

In this section, you’ll need to enter your Chargify API key and the subdomain for your Chargify tenant.

You’ll be able to find your API key in the Config > Integrations section of your Chargify account, and your subdomain from the URL on which you access your account.

Payment Form Configuration

You should be able to find your Public Key in the Config > Integrations section.

Chargify - Payment Form Config

In this section, you can also choose which elements you want to be displayed on the payment form.

With no options checked, you will get a simple payment form with only fields for the card number, expiry month and expiry date. Depending on your use case, you can also activate:

  • First & Last Name fields
  • A CVV field
  • Billing address fields

Notification Configuration

Chargify signs webhook notifications with a shared secret. You can find this in your Chargify account by navigating to the ‘Edit Current Site’ section.

NOTE: Depending on your Chargify user permissions, you may need to request this from your Chargify administrator.

Customer Configuration

Whilst Zephr does not handle billing details (these are handled directly by Chargify), the extension does have capabilities to sync Zephr user attributes to Chargify Customer data fields.

Chargify - Customer Configuration

Common use cases for this would be to sync data relating to delivery (shipping) addresses.

More details on the available Customer fields at the Chargify end are available here.

To map values to Chargify Customer records, create a corresponding Zephr User Attribute and add the attribute slug (pictured) to the relevant field in this section.

Chargify - User Attributes

The First Name and Last Name attributes are required in Chargify, so must be mapped from Zephr.

Webhook Configuration

For Chargify to notify Zephr when subscription payment methods are charged successfully, you will need to give Chargify a URL to which it can issue webhooks.

To do this:

  1. Navigate to Config > Settings > Webhooks in your Chargify account
  2. Click the ‘Add new endpoint’ button and add the URL to which you would like webhooks to be sent.
    • If you are using the Zephr CDN, this address will be https://<your_domain>/plugins/advanced/public/chargify/subscriptionChargedCallback
    • If you are not using the Zephr CDN, there will still be a public endpoint provided by Zephr to which you can have the webhooks sent – to find this, navigate to Delivery > Sites > <your_site> > Site Domains: you will then be able to instruct Chargify to dispatch notifications to https://<your_zephr_cdn_domain>/plugins/advanced/public/chargify/subscriptionChargedCallback
  3. Once you have added the URL, check the box for the ‘Payment Success’ event.
  4. OPTIONAL: the ‘Actions’ menu for the webhook you have just added will have an option to run a test to check Zephr can receive the webhook at the URL you have entered.

Chargify offers a number of useful tools for working with webhooks – you should be able to inspect the status of webhooks issued to Zephr.

NOTE: Chargify has facilities to resend webhooks: using this functionality may result in duplicate product grants visible in the Zephr Admin Console. Whilst these duplicate grants will not have an effect on the level of access a customer enjoys it may affect any reporting in which you are using Zephr data.

Activate Plugin

Once you’ve input the relevant details, confirm which of your Sites the extension should be active on. To do this, use the toggles for each site under the Activate Plugin section, or choose Select All Sites.

Mailchimp - Plugin Activation

Once completed, click Save. Your extension is now enabled and you will be able to use Chargify payment forms in your rules.

Usage

NOTE: you’ll need to configure your Chargify products and price points before you can associate them with Zephr products, or build Zephr payment forms.

A simple flow for creating a payment form powered by Chargify and Zephr would be as follows:

  1. Create any relevant products and price points in Chargify.
  2. Configure and activate the Zephr Chargify extension.
  3. Create a Zephr Product (navigate to Products > Catalogue)
  4. On the product creation page, add and relevant features, then click the ‘Add a Payment Option’ button. This will trigger a dialogue where you can select the relevant Chargify price points.

Chargify - Payment Plans

Note: the dialogue will currently only allow browsing of price points that begin with a letter. Price points that begin with a number are still searchable via the search box.

  1. Create a feature rule: this is where you can create a payment form UI element as the outcome of a rule. From the rules canvas, click the Outcomes > Add Outcome button.
  2. On the create outcome page, click the ‘Add a New Form or Custom Component Block’ button, then ‘Add Payment Form’.
  3. On the payment form creation page select the Zephr product you configured with Chargify price point IDs. Then click ‘Add a Payment Option’ for as many price points as you wish to add.
  4. Once you’ve saved your payment form and outcome, it can be deployed as an outcome in your feature rules.

Notes

As part of normal operation, this extension will create a corresponding user record in Chargify the first time a user completes a successful payment flow.

Depending on extension configuration, the corresponding user record may then be kept up to date with information from Zephr. It is your responsibility to ensure that you have secured the relevant permissions from your end-users in order to conduct this processing.

Zephr does not take responsibility for any payment processing and cannot undertake actions such as dunning.

The extension does not currently support Promotional Codes or Coupons.

The extension currently only responds to ‘Payment Success’ events when receiving notifications from Chargify.