Third Party Checkout

Stripe Elements Overview

This guide is intended to help you understand how to connect your Stripe Elements integration correctly to Recurly via the V3 API.

For more information on the V3 API, see our Developer Hub.

Supported Payment Methods (Q4 Support)

Recurly will be supporting Dynamic Payment Methods. To add payment methods to your integration and have them show up dynamically, request these payment methods in your Stripe Dashboard individually.

• Cards: Visa, MasterCard, Discover, Diners, JCB/I, Union Pay, American Express, Cartes Bancaires

• Wallets: Link Pay, Cash App Pay, Revolut

Step 1: Build your Stripe Elements Integration

You will want to follow Stripe Documentation to build out an integration to the Stripe Payment Element. Documentation links are below:

• General Overview: Stripe Payment Element
• Quickstart Guide: Custom payment flow | Stripe Documentation

If you decide to use the Card Element instead of the Payment Element, you will be limited to accepting only Card payments and Link, and excluding Wallets such as Apple and Google Pay. Stripe’s Payment Element, however, will support cards and Link, plus the additional wallets and alternative payment method options supported by Recurly. For a simpler and more flexible setup, we recommend choosing the Payment Element.

Recommendations

• Payment Element: As noted above, the Payment Element option is best for simplicity and flexibility, but you can choose the Card Element option if you wish. Read more about the comparison at Stripe’s documentation below:

  • Compare the Payment Element and Card Element | Stripe Documentation

• Best Practices: Follow Stripe’s Best Practices guide, as well as Recurly-specific configuration requirements.

  • Payment Element integration best practices | Stripe Documentation

  • When using a payment method that requires mandates and legal terms, ensure you are choosing auto for payment options terms.

• Credentials: When using Elements with your Recurly Account, you must use your Stripe Account ID (acct_xxxx) when configuring Elements and Recurly’s top-level PK key. If you use your own publishable key, the integration will not work properly. This is due to Recurly using Stripe Connect.

  • To retrieve your Stripe Account ID, you have two options:

    • Option 1: Log into your Stripe Gateway account directly, click on the ‘Settings’ gear icon, choose ‘Settings’ > ‘Business’. The account ID will be present in the UI for copying.

    • Option 2: Log into your Recurly account and navigate to ‘Configuration’ > ‘Payment Gateways’ and run a ‘Test Configuration’ against a Stripe Gateway instance. The associated account ID will be visible in the UI.

    • Format: acct_xxxxxxxxxxxxx

Use the ‘development mode’ key while your Recurly site is in ‘development mode’. Use the ‘production mode’ key for production transactions.

• Recurly Development Mode Publishable Key: pk_test_40DpPkZhqK69boNdC3ygyBgsCMGIzMq9rbRmeqBbD7ELUduU6gW4NcmKhvinbztWdiNVFfUfknl2OsCRDkFfVe7s7003wu2I6Mq

• Recurly Production Mode Publishable Key: pk_live_40DpPkZhqK69boNdC3ygyqOhhvwU83GPZTzPmQfuOe3LRwtHJaMYLH9ID5s7DvAi2bNpOASqoZSX1OfQhILfHb5Wu00aHgiDD2z

• Choosing your Mode: Stripe’s Elements require a ‘mode’, and offers three options. Those options include payment, setup, and subscription. Recurly does not support the subscription mode.

It is important to understand your own checkout flow as you may use both setup and payment depending on your plan options or customer actions. First rule would be to always render the Stripe Element after you know if there is an amount to be charged or not.

Mode payment can be used any time a customer is signing up for a subscription where there is no trial, or is making a one-time purchase. This can also be used if they are updating their billing info and want to make a purchase at the same time. The best rule of thumb is to render the element after you know there will be a charge amount occurring (non-zero amount).

Mode setup should be used when a customer wishes to sign up for a free trial subscription, or is updating their billing information without making a purchase. This mode should also be used when creating a future-dated subscription, as we need to run a verification to retrieve reusable payment tokens for future usage. Again, the rule of thumb would be to use the setup mode when there is no expected amount for the immediate customer interaction.

Configuring Capture Method

Stripe’s captureMethod Elements configuration parameter allows you to create a confirmation token that allows separate Authorization and Capture, or an all-in-one Purchase whether or not the intent is a subscription signup or a one-time transaction.

If you choose to set your Elements configuration to captureMethod of manual, you must use the /authorize endpoint when sending your customer initiated transaction with a confirmation token.

If your captureMethod configuration is set to automatic, you must use the purchase endpoint.

Return URLs

Certain APMs require return URLs to be passed to Stripe within the confirmation token. To ensure customers who are choosing to checkout with a Return URL-dependent APM, ensure you are providing Stripe this detail before submitting the confirmation token to Recurly.

You can read more about Return URLs on Stripe’s Website on various pages. Recurly does not provide a return URL for usage with Stripe Elements.

Choosing Where to Confirm Payment or Setup Intents

Recurly will confirm payment and setup intent on your behalf. You do not need to do this on your own.

• Design an integration | Stripe Documentation

External Payment Methods

Recurly does not support Stripe’s External Payment Methods option – if you choose to support these methods in your Elements integration, these transactions and payment methods will not be accepted for payments or subscriptions on the Recurly platform.

• External payment methods | Stripe Documentation

If you would like to add external invoices from a self-hosted integration to Recurly, you may do so using the External Invoices feature.

• Recurly Docs | External Invoices

If you would like Recurly to support one of these External Payment Methods, please reach out to your Recurly Account manager and submit a feature request.

Custom Billing Info Collection

Recurly suggests allowing Stripe to determine billing information collection dynamically, but you can modify this by customizing which billing information details you collect. See documentation below:

• Control billing details collection | Stripe Documentation

By default, all fields are set to auto. This balances minimizing customer friction and maintaining optimal authorization rates. If you choose to set your Elements integration to never, you will need to collect and pass those details via the Recurly API fields instead.

Saving Payment Details

Since your checkout will be handling much of the buyer consent and recollection of information for known customers, it is imperative to follow Stripe’s and Recurly’s recommendations from both this page, and this guide.

When building your Payment Element, ensure you have also set setup_future_usage to off_session to ensure the payment method created can be used for future transactions.

• Save and retrieve customer payment methods | Stripe Documentation
• Setup Future Usage: Create an Elements object without an Intent

Key information from this guide includes:

• Consent for Future Purchases: Prompting buyers for consent before saving their payment details. Note, if customers do not check the box to store the payment method for future usage, the customer cannot use their payment method for additional purchases or subscriptions.

If this happens, allow_redisplay will appear in Confirmation Token retrievals as limited. - When the confirmation token returns as ‘limited’, this consumer will not be able to use their billing info on file for additional subscriptions or one-time purchases. Expect declines for attempts using a Stripe token in this state.

Migrating from Stripe Payment Methods to Confirmation Tokens

If your current integration with Stripe uses Payment Methods, see Stripe’s documentation for migrating to Confirmation Tokens here:

• Migrate to Confirmation Tokens | Stripe Documentation

Stripe Messaging

• Payment Method Messaging Element | Stripe Documentation

A consolidated list of parameters and our recommendations are below. We have not covered all Stripe documented Element options configuration available as, in those cases, they can be set based on your preferences.

Step 2: Retrieve the Confirmation Token Details (Optional)

If you need to calculate taxes or perform other pre-transaction activities, and require the customer details to do so, you can query the Confirmation Token ID you receive after a successful Elements interaction.

The confirmation Token contains information about the payment method selected during the checkout process, any billing and shipping information collected among other important details such as the setup_future_usage parameter. If this transaction is meant to offer recurring capabilities or if you need to reattempt a declined transaction, it should be set to off_session.

• Confirmation Token Documentation: The Confirmation Token object | Stripe API Reference
• Retrieve a ConfirmationToken | Stripe API Reference

For tax calculation purposes, relevant information will be provided in this object:

"billing_details": {
  "address": {
    "city": "Hyde Park",
    "country": "US",
    "line1": "50 Sprague St",
    "line2": "",
    "postal_code": "02136",
    "state": "MA"
  },
  "email": "jennyrosen@stripe.com",
  "name": "Jenny Rosen",
  "phone": null
},

Shipping details, if collected, are also in this response as below:

"shipping": {
  "address": {
    "city": "Hyde Park",
    "country": "US",
    "line1": "50 Sprague St",
    "line2": "",
    "postal_code": "02136",
    "state": "MA"
  },
  "name": "Jenny Rosen",
  "phone": null
}

Step 3: Create a Purchase Request

To make a purchase using the Stripe Confirmation Token, you will provide it in a Recurly V3 API purchase request. In the example below, one subscription is generated using the plan code created in our Quickstart Guide.

The following parameters are used specifically for this use-case.

An example request body to POST /purchases:

{
  "currency": "USD",
  "account": {
    "code": "my-new-account",
    "billing_info": {
      "payment_gateway_references": [
        {
          "token": "my_confirmation_token_id",
          "reference_type": "stripe_confirmation_token"
        }
      ]
    },
    "subscriptions": [
      {
        "plan_code": "coffee-monthly"
      }
    ]
  }
}

Many additional options are available to you. See the Create Purchase reference to learn more.

Redirect Method APMs

Certain APMs require displaying a QR code or other redirect to the consumer so they can authenticate in the Cash App application on their mobile device. Recurly utilizes our 3-D Secure exo-system to process Cash App transactions. When you provide a Stripe ctoken value in your API request, Recurly will respond with a three_d_secure_action_token

This token can be provided to Recurly.js to unpack and direct your consumer to complete their Cash App payment.

After your consumer processes their payment with Cash App, Recurly.js will produce a three_d_secure_action_result_token which you may provide in a retry of your initial purchase call. See Step 4 for more details on parsing the purchase response.

See Recurly.js Action Token documentation at our Developer Hub.

Step 4: Process the Purchase Response

If the purchase was not successful, you’ll receive an error response indicating the type of error that was encountered. Errors could occur due to a bad request (missing or invalid parameters), or other reasons such as payment gateway failures.

If the purchase is successful, an InvoiceCollection will be returned as the response type. This object consists of any charge or credit invoices created during the purchase.

Step 5: Verify and Finish

If the purchase was successful, you should now be able to access all associated objects that were created as a result. You can verify through the API or the admin console.

Next Steps

Now that you know how to create new accounts, subscriptions and one-time payments, take a look at the Subscription Management guide to learn more about how to manage the subscription changes after the initial purchase.

Using Recurly.js and Stripe Elements

In many cases, you may wish to retain your existing Recurly.js integration and supplement with Stripe Elements to allow users access to more alternative payment options. This is possible, though will be specific to your business needs and design of your unique checkout experience.

Card payments, often the leading payment method, can be accepted with Recurly.js to allow you to leverage several gateways, 3-D Secure solutions, and the multitude of fraud prevention products we offer.

If you have been or plan to use the Recurly.js pricing components, those may operate alongside Stripe Elements to provide real-time purchase price, tax estimates, discount calculations and more.

Alongside these Recurly.js capabilities, Stripe Elements may be used solely to implement payment methods not provided by Recurly.js for Stripe. We recommend this approach as a manner of minimally impacting any existing Recurly.js integration.\