Zephr User Guide

Chargify

24 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.

The extension supports multiple currencies and automatically synchronises with the currencies configured in your Chargify account.

Promo codes (called coupons within Chargify) and payments through PayPal are also supported.

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

Here, you’ll need to add your Chargify Public Key, which can be found in the Config > Integrations section of your Chargify Account.

Paypal

Next, you can choose if you wish to accept PayPal payments. Tick the “Accept Paypal Payments” box to enable adding a pay with PayPal option on your payment form. Note that to see these changes reflected in existing forms you must recreate the payment form in the Zephr feature builder.

Braintree is the only payment gateway within Chargify that can accept Paypal payments. You must ensure you have linked a Braintree account in your Chargify console and configured it as the default gateway for PayPal payments.

If you are using Zephr to manually route product families to specific payment gateways you can add further configuration to specify separate gateways for PayPal & card payments in the Product Family – Payment GatewayHandle Mapping area below. For example:

{
    “My_product_family_id”: {
        “card”: “gateway_handle_for_card_payments”,
        “pay_pal”: “gateway_handle_for_paypal_payments”
    },
    ...
}

Other Payment Form Configuration

Following this, 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

NOTE: Chargify billing name/address fields are distinct from Zephr user attributes for name and address. In this context, the Chargify fields correspond to billing information whereas the Zephr attributes are analogous to customer/shipping details.

Chargify - Payment Form Configuration

If you require country/state customer details for tax reasons but do not want to explicitly ask for this information try out the Zephr Geosync Plugin (link) to estimate customer location based on IP address.

Product Family – Payment Gateway Handle Mapping

If you have Multiple Payment Gateways enabled in Chargify you can route payments for all products in nominated Product Families to a specific Payment Gateway. For this you will need:

  • the IDs of Product Families you want to map
    • Navigate to Catalog > Products within the Chargify Console
    • On this page products are grouped by Product Family. The Product Family IDs are displayed next to the headers.
  • the Gateway Handles for your Payment Gateways
    • Chargify Console > Config > Payment Gateways
    • click on a gateway to display its handle.

Once you have this information, you can configure the routing with a JSON object in the form:

{
    "“MY_CHARGIFY_PRODUCT_FAMILY_ID"”: "“MY_PAYMENT_GATEWAY_HANDLE"”,
    ...
}

In this example, any products purchased from the family with ID `MY_CHARGIFY_PRODUCT_FAMILY_ID` will be routed to the payment gateway that has the handle `MY_PAYMENT_GATEWAY_HANDLE`.

Once you’ve completed the Payment Form Configuration section, click Done.

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.

Once added, click Done.

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.

Once completed, click Done.

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 in Zephr. To complete the integration, you will need to add a Webhook within Chargify. Details on how to do this are below.

Configuring a Webhook in Chargify

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.

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.

Enabling Promo Codes for Chargify

To enable promo codes, tick the relevant box when creating a Payment Form outcome in the Zephr Rule Builder.

For a promo code to take effect, it must be created in Chargify and enabled for the Products displayed on the payment form. See the Chargify Coupons documentation for more information.

List Subscriptions Endpoint

The extension creates a new API endpoint at mydomain.com//plugins/public/chargify/subscriptions which lists the Chargify subscriptions for the signed-in user.

This endpoint can be called like so:

curl --location --request GET
'https://MYDOMAIN.com/plugins/public/chargify/subscriptions' \
--header 'Cookie: blaize_session=df45a301-23a7-465a-b838-61d81d6e1bd5'

Here is an example response from this endpoint:

{
    "subscriptions": [
        {
            "token": null,
            "managed-by": "Chargify",
            "external-id": 1234567,
            "next-billing-time": "2021-08-14T17:02:30-04:00",
            "ends": null,
            "blaize-product": {
                id": "product-1",
                "label": "Product 1",
                "description": ""
            },
            "transaction-history": [
                {
                    "human-readable-amount": "$3.74 CAD",
                    "time": "2021-07-14T17:02:30-04:00",
                    "currency": "CAD",
                    "cents": 374,
                    "cycle": null,
                    "period_start": "2021-07-14",
                    "period_end": "2021-08-14",
                    "cycleCount": 1,
                    "taxRate": {}
                }
            ],
            "subscription-state": "active",
            "paid_through_date": "2021-08-14T17:02:30-04:00",
            "plan_id": 234567,
            "plan_name": "Monthly magazine"
        }
    ]
}

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 currently only responds to ‘Payment Success’ events when receiving notifications from Chargify.