Testing & Implementing 3D Secure

Testing your workflows with 3D Secure

The following document will walk you through how test the experience of 3D Secure (3DS). More information about PSD2 and SCA can be found here

We currently support 3DS on the following gateways: Stripe, Braintree, CyberSource, Windcave (Payment Express)

PSD2 Flows: Pre Authentication and Post Authentication

Chargify offers two ways to authenticate your customers PSD2 transactions, via a Pre Authentication or Post Authentication flow. There are several differences with how each of these authentications handle transactions that are flagged for SCA.

The authentication path controls when the customer is authenticated through 3D Secure.

Pre Authentication occurs at the same time the user enters in their card details. This makes it easy for you, the merchant, as no further action is required on your end. Using this method will surface a pop-up that authenticates the customer for $0, which will not match up with the final purchase of the product.

Pre Authentication is applicable for:

  • Public Signup Pages (PSPs)
  • Self-Service Pages (SSPs)
  • Chargify.js for Cybersource, Braintree and Windcave

To enable Pre Authentication for supported gateways on Chargify.js, add the flag threeDSecure: true to your load.js form.

With Post Authentication, Chargify waits until the token is used to check the need for SCA. In other words, a Chargify.js token is not authenticated until it is used. For API subscription creation requests that fail due to SCA, we will return an action_link URL that you can share with the user. This URL leads to a page where authentication can be completed. See a more detailed guide on this workflow here.

Post Authentication is applicable for:

  • Chargify.js + API for Stripe

Step 1: Gateway configuration, Chargify test site, test credentials and cards

Enabling 3DS at your gateway

Most gateways require you to take some action on their side to enable 3D Secure. Below we will outline what is needed for each gateway.

Stripe

3DS is already enabled in Stripe by default.

Braintree

Please contact Braintree to ensure 3DS is enabled on your account. More info can be found here.

CyberSource

Contact CyberSource to enable 3D Secure on your account and retrieve Cardinal Commerce credentials.

Windcave (Payment Express)

Contact Windcave support and request a set of REST API credentials (REST API Username and REST API Key) that are linked to your existing PxPost credentials under the same “Group Account”. Note: ensuring that this linkage is under the same Group Account is important for correct functionality with Chargify. In addition have them enable “AJAX_POST” for your account.

The Windcave credential types will differ depending on whether the Chargify site is used for testing or production. Test sites should use UAT credentials, whereas live sites will use SEC. Windcave itself will also have separate usernames and passwords for its “test” and “live” environments.

Configuring a Chargify test site with test gateway credentials

If you haven’t created a Chargify test site yet, it is recommended to create one in order to test the 3DS flow. When configuring your gateway on the test site, you may have to provide additional information to enable 3DS support.

Stripe

No additional steps are needed for Stripe.

Braintree

Visit Config > Settings > Payment Gateway and edit your Braintree credentials. At the bottom of the popup, there will be an checkbox that will enable SCA requests.

Enable SCA requests for Braintree inside Chargify.

CyberSource

Cybersource requires two additional steps, both of which are completed on the same page in Chargify. From Config > Settings > Payment Gateway, choose to edit your existing credentials and perform the following:

  • Add your Cardinal Cruise API Identifier, Cardinal Cruise API Key, and Cardinal Cruise Unit ID
  • Click the checkbox for “Strong Customer Authentication (SCA) Enabled”
Enable SCA requests for Cybersource inside Chargify.

Windcave (Payment Express)

Windcave requires two additional steps, both of which are completed on the same page in Chargify. From Config > Settings > Payment Gateway, choose to edit your existing credentials and perform the following:

  • Fill in your Windcave REST credentials, which consist of the API username and key
  • Click the checkbox for “Strong Customer Authentication (SCA) Enabled”
Enable SCA requests for Windcave inside Chargify.

Gateway test cards

Most gateways provide unique test card numbers you can use to simulate successful and unsuccessful 3DS flows.

Stripe

  • 4000000000003063

For more information, refer to Stripe’s documentation.

Braintree

Please refer to Braintree’s documentation.

CyberSource

Successful cards:

  • 4000000000001091 (Visa)
  • 5200000000001096 (MasterCard)
  • 340000000001098 (American Express)

Unsuccessful cards:

  • 4000000000001109 (Visa)
  • 5200000000001104 (MasterCard)
  • 340000000001106 (American Express)

For more information, refer to Cybersource’s documentation.

Windcave (Payment Express)

Windcave’s documentation may be found here.

Use any future card expiration date and any 3 digit CSC/CVC value for successful and/or unsuccessful payments.

Successful cards:

  • 5453010000095323 (Mastercard)

Unsuccessful cards:

  • 5431111111111111 (Mastercard)
  • 6011111111111117 (Discover)

Step 2: Determine your access points

For the purpose of this testing guide, an access point is anywhere your end-customer may enter a credit card that is used by Chargify.

If you are unsure which method is being used, please feel free to contact the Chargify support team and they can assist in finding how your customers are signing up or updating their cards. That being said, the development or IT team that worked on your integration will have the most knowledge on which access points your company uses.

Chargify.js

Chargify.js allows you to collect card information using embedded iframes on your own site. One way of helping you determine if this is being used is by seeing if you have a “Public Key” generated under Config > Integrations > Chargify.js.

Additionally, if your signup or card update page on your own customer-facing site embeds the Chargify.js file, this could indicate that this access point is being used.

API

The API can be used to create and manage subscriptions. Do you have an API key generated under Config > Integrations > API Keys/Chargify Direct?

Bear in mind that API keys generated here may be used not to directly interact with our API, but rather to communicate with a third-party application, such as Salesforce. If you are directly integrated with our API to process signups, there will be code on your server that references this API key, and it is likely that you are not using our Public Signup Pages.

Public Signup Pages / Offer Signup Pages

These are Chargify-hosted pages that are used to create subscriptions. Public Signup Pages allow the customer to fully configure their subscription with products, components, and coupons; Offer Signup Pages are a static signup form that can be sent as an already-configured deal for a particular customer. You can determine if you have any enabled Public Signup or Offer Signup Pages by going to Billing > Public Signup Pages or Billing > Offer Signup Pages. That said, the existence of these pages does not necessarily mean they are being used to signup your end customers; the only way to know for certain would be to determine if these links are embeded in your website.

Another way of determining if they are being used is if your customers are directed to a chargifypay.com domain name as part of the signup process. The URL will resemble the following: https://subdomain.chargifypay.com/subscribe/w3k4sc2jqydk

Self-Service Pages

Self-Service Pages are Chargify-hosted pages used to update credit card information. If you have emails enabled in Chargify, such as signup or renewal emails, they reference an update_url variable, which pulls in each subscriber’s unique service link. Additionally, if your team manually sends payment update request emails from the subscription > Payment Details > Email Customer to Request Payment Update, these emails reference Self-Service Pages by default.

Self-Service Page URLs will be hosted on the chargifypay domain and will contain the subscription ID and your Chargify site’s subdomain. Here is how an example URL would be formatted: https://<subdomain>.chargifypay.com/update_payment/<subscription_id>/f1078bae2f

Billing Portal

The Billing Portal allows customers to self-manage their subscriptions; in particular, if the feature is enabled, they can be used to update the credit card on file.

You can determine if your Billing Portal workflow will be affected by PSD2 by first seeing if the portal is enabled under Config > Settings > Billing Portal. If Billing Portal is enabled, next check to see “Allow Card Updates” is enabled under the ‘Features’ section.

Invoices

This refers to the public views that customers can use to pay off their open or past due invoices. Steps for verifying whether these URLs are used will vary based on the site’s architecture. See below for more information on which impacts you.

Legacy Statement-based

Click on the “Billing” navigation in your site – if it lists “Transactions” and not “Payments”, your site may be using statement-based invoices. This is referred to as invoice billing, and is not enabled by default.

Visit Config > Settings > Invoice Billing to 1) determine if the feature is turned on, and 2) if “Enable Pay by Credit Card Link In Invoice” turned on.

Relationship Invoicing:

Click on the “Billing” navigation in your site – if it lists “Payments” and not “Transactions”, your site is on Relationship Invoicing.

Do you have invoice emails turned on, particularly for remittance payments, with invoice.url defined in the email template? If you export subscriptions, do any have a payment_collection_method of “remittance”? It’s possible that a member of your team may be manually sending the public URL to customers as needed.

Step 3: Test and implement the applicable access points

As mentioned before, we strongly recommend testing each of these access points on a separate Chargify test site, after your team has determined which acccess points are used by your particular Chargify integration.

Testing Chargify.js

To handle SCA requests with Chargify.js, add the flag threeDSecure: true to your load function. Here is a minimal example that passes credit cards:

<script>
    var chargify = new Chargify();

    chargify.load({
        // selector, where the iframe will be included on your page
        // optional, if you have a `selector` for every field ('fields' option)
        selector: '#chargify1',

        // (i.e. '1a2cdsdn3lkn54lnlkn')
        publicKey: 'your-public-api-key',

        // form type (possible values: 'card', 'bank' or 'gocardless')
        type: 'card',

        // points to your Chargify site
        serverHost: 'https://acme.chargify.com'
        
        //enables support for 3D Secure
        threeDSecure: true
    });
</script>

Exactly when the SCA popup is displayed to your customer will depend on whether the gateway requires a pre-auth or post-auth integration. See the section above for more information.

Stripe

READY FOR TESTING

Stripe is a post-auth integration, where creating a Chargify.js token won’t prompt SCA.

Braintree

READY FOR TESTING

Please be aware Braintree has the following requirements:

  • A billing address is required on the credit card

If your signup workflow immediately creates a subscription and you know the amount of the first charge (including taxes, discounts, etc), you can pass this amount to be used for SCA verification. This can be done via a config option or text field.

3DS verification amount provided via config:

<script>
    var chargify = new Chargify();

    chargify.load({
        // ...
        threeDSecure: true,
        threeDSVerificationAmount: '99.00',
    });
</script>

3DS verification amount provided via text field:

<div id='chargify-form'>
  <input
    data-chargify='threeDSVerificationAmount'
    value='99.00'
    readOnly
    hidden
  />
</div>

If an SCA challenge is necessary, the modal will present the threeDSVerificationAmount provided to Chargify.js. If no amount is provided, $1 will be displayed.

Braintree is a pre-auth integration.

CyberSource

READY FOR TESTING

Cybersource is a pre-auth integration, meaning the SCA prompt will be given to the customer when their token is created. Optionally, you may pass in a second callbacks argument with a onThreeDsConfigError callback.

const chargify = new Chargify();

const options = {
  threeDSecure = true, // Enable 3D Secure
  // (...)
}

const callbacks = {
  onThreeDsConfigError: function(error) {
    console.error(error);
  }
}

chargify.load(options, callbacks);

Please be aware Cybersource has the following requirements:

  • A billing address is required on the credit card
  • The product must have an exact cost of $6102.01

Windcave (Payment Express)

READY FOR TESTING

Windcave is a pre-auth integration.

Testing API

It’s possible to use the API for creating subscriptions as well as updating payment methods. Unless you are PCI compliant, raw card data should not be passed through Chargify’s API; instead, use Chargify.js to tokenize the information first.

When creating a subscription with Chargify.js, simply pass a chargify_token under the credit_card_attributes or bank_account_attributes objects.

Stripe

READY FOR TESTING

Stripe is a post-auth gateway, meaning that the API call to create a subscription will prompt for SCA if the bank requires it.

For an in-depth overview of workflows using Stripe, please review our API documentation.

Braintree

READY FOR TESTING

Braintree is a pre-auth gateway.

CyberSource

READY FOR TESTING

Cybersource is a pre-auth gateway.

If you are PCI compliant and are creating subscriptions with raw card data, it’s required to embed a special 3DS library called Songbird.Js from Cardinal Commerce on your checkout page. When you create the subscription via API, it’s required to pass a three_ds_token attribute, which will be the ProcessorTransactionId returned from a successful 3D Secure authorization.

Please be aware Cybersource has the following requirements:

  • A billing address is required on the credit card
  • The product must have an exact cost of $6102.01

Windcave (Payment Express)

READY FOR TESTING

Additional information can be found here.

Windcave is a pre-auth gateway.

Testing Public Signup Pages / Offer Signup Pages

  • On the side bar under Catalog, click Public Signup Pages.
  • If you haven’t created a Public Signup Page, you may do so by clicking “+ Create Public Signup Page”. If this has already been completed, click “View URL” and copy the link that pops up in the Signup Page URL modal.
  • Paste the link in a new tab in your browser to view your Public Signup Page.
  • Enter in any First Name, Last Name, and Email Address for the Customer Information.
  • For the Billing Information, input any First Name, Last Name.
  • Enter the test card information unique to your payment gateway and follow the instructions on the 3D Secure popup.

Stripe

READY FOR TESTING

No additional steps are required for Stripe.

Braintree:

READY FOR TESTING

No additional steps are required for Braintree.

CyberSource

READY FOR TESTING

Please be aware Cybersource has the following requirements:

  • A billing address is required on the credit card
  • The product must have an exact cost of $6102.01

Windcave (Payment Express)

READY FOR TESTING

No additional steps are required for Windcave.

Testing Self-Service Pages

  • Click on any subscription to arrive on its Summary page
  • Click Subscription Actions > View self-service page; you will be redirected to their form to update card information
  • Enter the test card information unique to your payment gateway and follow the instructions on the 3D Secure popup.

Stripe

READY FOR TESTING

No additional steps are required for Stripe.

Braintree

READY FOR TESTING

CyberSource

READY FOR TESTING

Please be aware Cybersource has the following requirements:

  • A billing address is required on the credit card
  • The product must have an exact cost of $6102.01

Windcave (Payment Express)

READY FOR TESTING

No additional steps are required for Windcave.

Testing Billing Portal

  • Click Config > Settings > Billing Portal and verify the following:
    • the Billing Portal is enabled on the site
    • the feature “Allow Card Updates” is enabled
    • “Bypass email verification for logins” is enabled on management URLs; this isn’t required, but makes testing easier
  • Visit any subscription and scroll down to the bottom of the Summary page. Click “View Billing Portal Management Link” and visit the URL in a new tab
  • In the Billing Portal, click “Update Payment Information”
  • Enter the test card information unique to your payment gateway and follow the instructions on the 3D Secure popup.

Stripe

NOT READY FOR TESTING

Braintree

READY FOR TESTING

CyberSource

READY FOR TESTING

Please be aware Cybersource has the following requirements:

  • A billing address is required on the credit card
  • The product must have an exact cost of $6102.01

Windcave (Payment Express)

READY FOR TESTING

Testing Legacy invoices

  • Go to Config > Settings > Invoice Billing and confirm the following:
    • Invoice billing is an option for subscribers
    • Invoice emails are enabled
    • “Enable Pay by Credit Card Link In Invoice” is enabled
  • Visit any subscription and click “Change” on the Payment Method line to change it to invoice billing.
  • Change the next billing date to 5 minutes from now and wait for 20 - 30 minutes for the subscription to renew.
  • Once the subscription has renewed, view the email to grab the public invoice URL to pay the open invoice.
    • If your email is entered on the customer record, it will be sent to you
    • Alternatively, check Tools > Email Insights > Archives to find the email from there
  • Visit the link. It will resemble the following: Pay Invoice Online: https://subdomain.chargifypay.com/invoices/pay/2j993s65f4n4jn75c92mgjst
  • Choose to add a new card, input the test card information unique to your payment gateway, and follow the instructions on the 3D Secure popup.

Stripe

READY FOR TESTING

No additional steps are required for Stripe.

Braintree

READY FOR TESTING

CyberSource

READY FOR TESTING

Please be aware Cybersource has the following requirements:

  • A billing address is required on the credit card
  • The product must have an exact cost of $6102.01

Windcave (Payment Express)

READY FOR TESTING

No additional steps are required for Windcave.

Testing Relationship Invoicing invoices

  • Visit any subscription and view the Summary page.
  • Click “change” on the Payment Method line to move them to remittance billing.
  • Change the next billing date to 5 minutes from now and wait for 20 - 30 minutes for the subscription to renew.
  • Once the subscription has renewed, visit the “Invoices” tab and click on the new, open invoice.
  • Click More Options > View Invoice Public URL and visit the provided link.
  • Choose to add a new card, input the test card information unique to your payment gateway, and follow the instructions on the 3D Secure popup.

Stripe

READY FOR TESTING

No additional steps are required for Stripe.

Braintree

READY FOR TESTING

CyberSource

READY FOR TESTING

Please be aware Cybersource has the following requirements:

  • A billing address is required on the credit card
  • The product must have an exact cost of $6102.01

Windcave (Payment Express)

NOT READY FOR TESTING

Step 4: Implementing 3DS on live Chargify Sites

After you have successfully tested all the access points using a Chargify test site, you can enable 3DS on your live Chargify sites by following the same steps as above for enabling 3DS in Charigfy, but using your gateway production credentials instead of any test credentials. Your end-customers will then be presented with the 3DS prompts when appropriate.

If you have any card collection flows using Chargify.js or the API, you will want to sure the code you used when testing is also implemented in your production environment.