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.
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:
You can set the primaryColor property in the redirectToBeanie call. It must be a color hexadecimal code - for example: #212CA7 -
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', primaryColor:'#4cd6bd'}).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"})
You can specify whether Beanie should collect the customer’s billing address by setting the primary_color parameter as an hex color code when creating a Beanie Session.
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"})
You can specify whether Beanie should collect the customer’s billing address by setting billing_address_collection when creating a Beanie Session. 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.
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.
You can specify whether Beanie should prompt for and collect the shipping address of your customer using the shipping_address_collection field while creating the session as follows:
Do not fill the field or leave blank in order to not collect the shipping address from the customer.
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"})
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 creating the BeanieSession on the server side, make sure you fill the following options:
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.
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"})
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"})
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.