Customizing Beanie

Learn how you can customize your Beanie integration.

BEANIE IS SCA-READY

In a few words: it’s a new European regulation that aims to better protect consumers when they pay online. European businesses accepting debit and credit card payments will be impacted by the new Strong Customer Authentication (SCA) rule as of September 14, 2019. By using Beanie, you can rely on Octobat to ensure your business is SCA compliant.

Learn more about SCA and how it might impact your business.

Branding

You can customize the look and feel of Beanie on a Configuration basis, or on a Session-basis depending on your needs. This option is available for both Serverless and Client/Server modes.

Directly from your Octobat dashboard, you can create a new, or edit an existing Beanie Configuration with the "Primary Color" parameter entering a color Hex Code as follows:

Billing address collection

You can specify whether Beanie should collect the full billing address of your customer, or only its billing country - and, possibly, the zip code if required by the payment processor -.

You can set the billingAddressCollection property in the redirectToBeanie call. If set to required, Beanie will ask for a full billing address filling. If not set, or set to auto then Beanie will only collect the required components of the billing address.

beanie.redirectToBeanie({
  items: [
    { price: 'price_123', quantity: 1 } // For one-off charges only
    // { plan: 'price_456/plan_456', quantity: 7 } => Subscriptions-only
  ],
  successUrl: 'https://example.com/success',
  cancelUrl: 'https://example.com/cancel',
  billingAddressCollection: 'required'
})
.then(function (result) {
  if (result.error) {
    // If `redirectToBeanie` fails due to a browser or network
    // error, display the localized error message to your customer.
    var displayError = document.getElementById('error-message');
    displayError.textContent = result.error.message;
  }
}).catch(function(error) {
  // If `redirectToBeanie` can't be triggered because of invalid parameters
  // or implementation, error, display a generic error message to your customer,
  // and report the error to the console for debugging purposes, or send it to Sentry
  // Sentry.log(error)
  console.log(error)
  var displayError = document.getElementById('error-message');
  displayError.textContent = "Implementation error, please contact website administrator"
})

Shipping address collection

You can specify whether Beanie should prompt for and collect the shipping address of your customer. This is particularly useful when you sell physical goods, and need to send the order to the customer, and track the shipping in your operations. Beanie requires you to input a list of countries where you are allow shipping to, configuring the allowed_countries property with an array of alpha2 ISO country codes, that will appear in the Shipping Country dropdown in the Beanie interface.

When selling physical goods, if shipping details are filled, they take precedence over the billing details to calculate taxes.

This option will be only available through BeanieConfigurations, and soon available in the Octobat interface.

Prefilling customer data

You may already have collected information about your customer that you want to prefill in the Beanie page to avoid your customers needing to enter information twice. Currently, you can prefill the customer email and the customer name on the Beanie page by filling the prefillData field in the redirectToBeanie call. We plan to expand this feature to allow you to prefill more fields in the future.

beanie.redirectToBeanie({
  items: [
    { price: 'price_123', quantity: 1 }
  ],
  successUrl: 'https://example.com/success',
  cancelUrl: 'https://example.com/cancel',
  prefillData: {
    customer_name: "John Doe",
    customer_email: "foo@bar.tld"
  }
})
.then(function (result) {
  if (result.error) {
    // If `redirectToBeanie` fails due to a browser or network
    // error, display the localized error message to your customer.
    var displayError = document.getElementById('error-message');
    displayError.textContent = result.error.message;
  }
}).catch(function(error) {
  // If `redirectToBeanie` can't be triggered because of invalid parameters
  // or implementation, error, display a generic error message to your customer,
  // and report the error to the console for debugging purposes, or send it to Sentry
  // Sentry.log(error)
  console.log(error)
  var displayError = document.getElementById('error-message');
  displayError.textContent = "Implementation error, please contact website administrator"
})

Saving customers and their payment methods

For subscriptions, customers are automatically saved, and their payment methods set up for off session future usage if they are reusable, thanks to Stripe SCA APIs. This section only concerns one-off purchases.

It's common to give your customers the possibility to save their payment methods - such as credit cards - in order to charge them automatically if they decide to purchase another products from your store.

Beanie gives you flexibility and efficiency in this process, allowing you to:

  • Always save the customer's credit card for future reuse

  • Ask your customer if they want to save their credit card for future usage or not.

  • Never save the customer's credit card.

For the first two options, Beanie also comes with an option to optimize future payments success through Stripe, whether you'd like to charge them on session only (when they're on your website), or also off session. The goal of this is to optimize the payment method setup.

To enable this feature, please follow these steps:

Create a BeanieConfiguration object with the following options: Save payment method to be reused:

  • Never => The payment method will never be saved.

  • Optional => The customer will have a checkbox to chose whether they want to save their payment method or not.

  • Always => The payment methods will always be saved.

Payment method future usage:

  • Empty / Off Session => Optimize the set up for both on session and off session usage

  • On Session => Optimize the set up for on session usage only

When you let the choice to your customer to save or not their payment method, they'll get a checkbox to confirm their choice:

Please note that on the Stripe side, a customer object is only created when the payment method is saved.

Usage with existing customers (client/server only)

Associating to a Reference Id

You can provide a unique string to reference the Beanie Session, in order to reconcile it with your internal system's IDs or data. It can be a customer email, or a customer ID or a cart ID.

TheclientReferenceIdfield is included in the JWT generated by Beanie and transmitted as a GET parameter to thesuccessUrlpage. You can rely on it for reconciliation of the underlying Beanie session with your internal data.

Learn more about it in the After the payment section.

beanie.redirectToBeanie({
  items: [
    { price: 'price_123', quantity: 1 }
  ],
  successUrl: 'https://example.com/success',
  cancelUrl: 'https://example.com/cancel',
  clientReferenceId: 'user-4242-foo-bar'
})
.then(function (result) {
  if (result.error) {
    // If `redirectToBeanie` fails due to a browser or network
    // error, display the localized error message to your customer.
    var displayError = document.getElementById('error-message');
    displayError.textContent = result.error.message;
  }
}).catch(function(error) {
  // If `redirectToBeanie` can't be triggered because of invalid parameters
  // or implementation, error, display a generic error message to your customer,
  // and report the error to the console for debugging purposes, or send it to Sentry
  // Sentry.log(error)
  console.log(error)
  var displayError = document.getElementById('error-message');
  displayError.textContent = "Implementation error, please contact website administrator"
})

Associating metadata

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. The metadata attached to aBeanie Session are replicated to the payment provider underlying objects: respectively for Stripe:

  • Subscription for subscriptions

  • PaymentIntent for one-off payments

beanie.redirectToBeanie({
  items: [
    { price: 'price_123', quantity: 1 }
  ],
  successUrl: 'https://example.com/success',
  cancelUrl: 'https://example.com/cancel',
  metadata: {
    "key": "value"
  }
})
.then(function (result) {
  if (result.error) {
    // If `redirectToBeanie` fails due to a browser or network
    // error, display the localized error message to your customer.
    var displayError = document.getElementById('error-message');
    displayError.textContent = result.error.message;
  }
}).catch(function(error) {
  // If `redirectToBeanie` can't be triggered because of invalid parameters
  // or implementation, error, display a generic error message to your customer,
  // and report the error to the console for debugging purposes, or send it to Sentry
  // Sentry.log(error)
  console.log(error)
  var displayError = document.getElementById('error-message');
  displayError.textContent = "Implementation error, please contact website administrator"
})

Prefill a coupon

For one-off payments, you need to define your coupons on Octobat, while subscriptions rely on your PSP-defined coupons. Beware that for Stripe, we rely on the coupon ID, and not the coupon code.

beanie.redirectToBeanie({
  items: [
    { price: 'price_123', quantity: 1 }
  ],
  successUrl: 'https://example.com/success',
  cancelUrl: 'https://example.com/cancel',
  coupon: '{{COUPON_ID}}'
})
.then(function (result) { })

Handling trials (client / server) only

We rely on Stripe's trial_from_plan and trial_end parameters as follows:

curl -X POST https://apiv2.octobat.com/beanie/sessions \
        -u {{SECRET_KEY}}: \
        -d ( ... configuration options ... ) \
        -d subscription_data[trial_end]={{TRIAL_END}}
curl -X POST https://apiv2.octobat.com/beanie/sessions \
        -u {{SECRET_KEY}}: \
        -d ( ... configuration options ... ) \
        -d subscription_data[trial_period_days]={{TRIAL_PERIOD_DAYS}}

For security concerns, trial handling is only available through the client/server integration.

Last updated