Collecting payment details with Beanie

Learn how Beanie can help you to collect payment details for a given customer, without collecting a payment. Beanie's setup mode is useful for adding a payment method for future payments, or updating a subscription payment method.

Follow these steps to create a hosted-Beanie page that collects payment details and automatically attach it to a given customer.

Step 1: Create a Beanie Session with setup mode on your server

For security reasons, to create a setup mode Beanie Session, you must use the Beanie client/server implementation. Use the mode parameter, with a value of setup when creating the BeanieSession or your server.

If you want to update the default payment method of a given customer, who already has payments, you must specify the customer parameter, with a value of either:

• Your gateway customer's unique identifier

• The Octobat customer's unique identifier

Octobat.api_key = 'YOUR_API_KEY'

Octobat::Beanie::Session.create(
  gateway: 'stripe',
  mode: 'setup',
  customer: 'oc_cu_xxxxxxxxxx',
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel'
)

You can refer to the API Reference for a full list of parameters you can use to create your BeanieSession.

Your OctobatBeanie.js needs the BeanieSession id field from the API response to redirect to the right hosted session, so make sure it's available to the HTML/JS file you call the redirectToBeanie from.

Step 2: Add Beanie to your website

To add Beanie on your website, you must add a Javascript snippet including the id field from the session you created in step 1.

Firstly, include OctobatBeanie.js on your website:

<script src="https://cdn.jsdelivr.net/gh/0ctobat/octobat-beanie.js@latest/dist/octobat-beanie.min.js">
</script>

Then, create an instance of a Beanie object using your publishable API key from Octobat:

var beanie = OctobatBeanie('oc_pkey_xxxxxxxxxxxxxxxxxx')

When your customer is ready to update their payment method, call them redirectToBeanie using the BeanieSession id parameter directly fetched from the session creation API call.

beanie.redirectToBeanie({
  sessionId: 'BEANIE_SESSION_ID'
}).then(function(result) {
  if (result.error) {
    // If `redirectToBeanie` fails due to a browser or network
    // error, display the 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 an error logger like Sentry
  // Sentry.log(error)
  console.log(error)
  var displayError = document.getElementById('error-message');
  displayError.textContent = "Implementation error, please contact website administrator"
})

Typically,redirectToBeanie should be called as a result of an event handler, such as the click on a link or a button. It can be a good idea to disable clicks or events on the targetted button or link to avoid double redirects.

Step 3: Retrieve the attached Payment Method on your server

After a customer successfully completes their Beanie Session, Octobat has updated its default payment method on the payment gateway, and has properly setup the payment method for future charges, such as recurring ones.

Octobat redirects the customer to the URL you specified in the success_url parameter while creating the session. TheGETparameter:setup_details is transmitted, and contains a SECRET_KEY-encoded JWT with the following payload:

{
  beanie: {
    payment_method_registration_id: 'oc_cs_test_xxxxxxxx', 
    livemode: false,
    customer_id: 'oc_cu_xxxxxxxxxx' 
  },
  transaction: {
    gateway: 'stripe', 
    type: "setup_intent", 
    id: 'seti_xxxxxxxxx', 
    payment_method_id: 'pm_xxxxxxxxx', 
    customer_id: 'cus_xxxxxxxx' 
  }
}

You can use this dataset to reconcile data from the callback to your database.

You can get more information on how to decode a JWT-encoded token here: Learn more about JWTs.

Need help?

We’re always happy to help out with code or any other questions you might have. Please drop us a line to [e-mail]