The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Visa Free Trial Mandate

Updated Visa Documentation

Visa has released updated documentation regarding the mandate. Please see our updated link below.

COVID-19 Update from Visa

Visa has announced updates regarding the free trial mandate's enforcement and deadline. Specifically:

1. Statement Descriptors

Visa will be delaying the requirements for statement descriptor updates until April 17, 2021. Recurly will continue working with our gateway partners to update our integrations as they become available. As a merchant, you will not need to make updates to your statement descriptors at this time.

2. Enhanced Notifications

Visa will be continuing with the original deadline for enhanced email notifications. More information on remaining compliant for this piece can be found here.

3. Express Consent

Similar with enhanced notifications, the deadline for the Express Consent requirements will remain set as the original date outlined by Visa. More information on remaining compliant for this piece can be seen here.

Update

Visa has released updated guidance regarding the enhanced statement descriptors for the Free Trial Mandate. Specifically, merchants may now update their existing statement descriptors to include a URL to their website / homepage instead of including specific “free trial” verbiage. For certain gateways, Recurly recommends utilizing this updated guidance to meet the enhanced statement descriptor requirements for the mandate while we finalize the requirements and update our integrations. The list of these gateways can be found below (updates are underway for gateways marked with an asterisk below):

  1. Authorize.Net
  2. SagePay
  3. Merchant e-Solutions
  4. Vantiv*
  5. WorldPay*
  6. TSYS*
  7. Chase Orbital*

The homepage URL should be added to one of the following locations. Please contact your gateway for specific details on how to do this.

  1. As part of the statement descriptor.
  2. As part of the URL field as long as this appears on your customers’ statements.
  3. As part of the Merchant City field as long as this appears on your customers’ statements.

Note: Recurly will continue updating the following gateways to add the “trial” verbiage statement descriptor functionality, which will automatically append appropriate free trial verbiage to necessary transactions. This functionality will still be added to additional gateways as we receive updated requirements from any additional gateway providers. For gateways marked with an asterisk, we recommend updating your statement descriptors temporarily as we continue to add the appropriate trial verbiage.

  1. Adyen
  2. Stripe
  3. Braintree
  4. Bambora
  5. Payeezy
  6. First Data
  7. CardConnect
  8. PayPal Payflow Pro
  9. PayPal Payments Pro
  10. Vantiv*
  11. WorldPay*
  12. TSYS*
  13. Chase Orbital*

Summary

Visa’s Free Trial Mandate is designed to provide clearer information on subscription related trial transactions to consumers. This should allow for easier identification and recognition of these types of charges to reduce the overall number of these transaction types that result in disputes. Visa’s regulation does this by enforcing guidelines surrounding the way a consumer signs up, is notified, and sees charges on their statements for trials that roll into a recurring subscription service. Keep in mind, while this mandate is recommended for all merchants who offer services billed on a recurring / subscription nature, it is only mandatory for those who also offer a free / introductory promotional period.

For more specific details, please review Visa’s documentation as linked below:

COVID-19 Update
Updated documentation
Summary Sheet

Configuration

Recurly is currently working with our gateway partners to update our integrations to meet the requirements of Visa’s Free Trial mandate. Most functionality is currently available with Recurly’s current offering and any outstanding requirements are being updated as we gather more information on how to implement the required changes from our gateway partners. A summary of the configuration needed for each piece of the mandate is called out below.

Express consent

This piece of the mandate relates to how consumers “sign-up” for a service. If the user is subscribing to a subscription plan that begins with a free trial, you’ll need to ensure that your checkout page has an “active” action that the user must take before subscribing agreeing to the recurring nature of your service. For instance, this can be a checkbox, button, etc.

Enhanced notifications

If you use Recurly’s current email templates, these can be customized to meet the requirements of the mandate. Specifically, you’ll want to adjust the following email templates, to meet the requirements called out in Visa’s documentation linked in the Summary section above.

New Subscription

This is the template that will be sent on initial sign-up.

Renewal Reminder

This template will be sent when the subscription is set to renew and can be configured to be sent 7 days prior to subscription renewal. This should be used to indicate when a customer’s trial is set to expire.

Subscription Change

This template will be set at the time a subscription change is made. Given this, you should ensure that subscription changes initiated by the merchant (rather than the customer) must be done 7 days prior to the changes taking effect.

Trial Ending

This template will be sent when the subscription is set to renew and a subscription is moving out of a trial period. You will need to adjust the following things on this template:

  1. Adjust the "days prior" value from 3 to 7.
  2. If you offer seasonal coupons (those that do not apply to all customers), enable the option "Send this email before the end of any discount on a subscription, including trials". This setting will allow this email to be sent if a subscription is moving out of a discounted state due to a coupon.

Statement descriptor and recurring indicators

The last pieces of the mandate state that certain information must be included in your transaction requests, which may appear on your customers’ statements. Since transactions processed through Recurly are submitted by Recurly on your behalf, we will be making the changes needed to support the mandate’s requirements. Specifically:

  • The first charge at the end of the trial period must include verbiage indicating that it is a trial related charge, which will appear on your customer’s statement, and
  • Every subsequent charge thereafter must include a recurring indicator flag when sent to your gateway.

The latter of the two points above is something that Recurly is already doing for any recurring charges sent to your gateway, so no additional updates will be needed to support this portion of the mandate. As for the former, Recurly is working with each gateway partner to identify the specific changes needed to support the mandate. In most cases, this is simply using a pre-existing field to pass “Trial” verbiage to your gateway when the first charge at the end of your trial period is processed.

Note for DBA Name

For certain gateways, you may need to configure your company's DBA (doing business as) name as this will be included in the transaction request. This will be configured under your Site Settings. Note, if this field is left blank, then Recurly will use the Company Name value that you've set under your Site Settings.

Here are the major changes you can expect:

If you use one of the following gateways, Recurly will pass the word “trial” with the first transaction processed at the end of the trial period, which will be appended to your DBA as it appears on your customers’ statements. Gateway names marked with an asterisk will require you to contact your gateway to enable support for "Dynamic / Soft Descriptor" fields:

  • Adyen
  • CardConnect*
  • Stripe
  • Wirecard*

If you use one of the following gateways, Recurly will pass the word “trial” along with the DBA Name value you currently have set under your Site Settings (Recurly will use the Company Name value if DBA Name is not set). Since this will appear on your customers’ statements with the first charge at the end of the trial period, please ensure this is updated according to your needs. Gateway names marked with an asterisk will require you to contact your gateway to enable support for "Dynamic / Soft Descriptor" field(s):

  • Braintree*
  • Bambora
  • First Data GGe4*
  • Payeezy Gateway*
  • TSYS*
  • Vantiv*
  • WorldPay*

Note: If your gateway is not listed above, then Recurly is still finalizing the necessary requirements with your gateway. We will actively update this page with new gateway partners as we receive final specifications from their teams.

Gateway Statuses

As we work with our partners to finalize the changes needed to our integration, we will continue to update this page. Please see the table below for the current status of the gateways we are tracking:

Gateway
Status

Adyen

Complete

Authorize.Net

In Progress

Bambora

Complete

Braintree

Complete

CardConnect

Complete

Chase Orbital

In Progress

Cybersource

In Progress

First Data

In Progress

Merchant e-Solutions

In Progress

Payeezy

Complete

PayPal (Payments / Payflow)

In Progress

SagePay

In Progress

Stripe

Complete

TSYS

In Progress

Wirecard

Complete

Updates for Braintree

Unique to Braintree, the statement descriptor formatting may differ depending on your Braintree merchant account's country location. Because of this, we've added a new configuration option to your Braintree gateway that will allow you to select your Braintree merchant account's country.

Steps:

  1. From the Recurly dashboard, go to your gateway configuration page via Configuration > Payment Gateways.
  2. For your Braintree gateway, select Options > Edit Gateway.
  3. Located the "Merchant Account Country" section and select the appropriate option.
Setting Description

None (Default): No free trial statement descriptors will be passed.

Australia: Free trial statement descriptor format if your merchant account is in AU.

Canada: Free trial statement descriptor format if your merchant account is in CA.

Other: Free trial statement descriptor format if your merchant account is anywhere outside of AU or CA.

FAQ

  • What happens if I offer a trial period with a duration of 7 days or less? How should I handle the required notifications? Your initial email notification (that is sent at sign-up) will serve as both the subscription sign-up confirmation and the trial ending notification. Please ensure that it includes all necessary information as outlined by Visa.
  • What happens if there’s a subscription modification that occurs within 7 days of a customer’s renewal? How should I handle the required notifications? The 7 day notification requirement for subscription modifications only applies to changes performed by the merchant (i.e. you’re raising the prices of a user’s subscription without an express request from the end customer). If the change is requested by the user, then you can notify as normal even if this notification is within 7 days or less of their upcoming renewal.
  • Can the “Trial” wording be customized? Currently, Recurly will use a standard “Trial” descriptor across all gateways. This will appear on the first charge at the end of the introductory promotional period and will not be seen on later, subsequent charges. At this time, this text cannot be customized.
  • What are the consequences of non-compliance? Are there any fines that will be assessed by Visa? Visa will be expanding the dispute conditions for "misrepresentation" as they relate to free trial / promo related transactions. These can be remedied by providing evidence to Visa that you've acted appropriately by (1) providing proof that customers expressly agreed to future transactions and (2) proof that you've notified consumers according to the guidelines of this mandate. Currently, Visa has not announced any fees due to non-compliance (March 2019).

Updated 9 months ago

Visa Free Trial Mandate


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.