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:

  1. Create a Beanie Session with setup mode on your server

  2. Add Beanie to your website

  3. Retrieve the attached Payment Method on your server

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 themodeparameter, with a value ofsetupwhen 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 thecustomerparameter, 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 BeanieSessionidfield from the API response to redirect to the right hosted session, so make sure it's available to the HTML/JS file you call theredirectToBeaniefrom.

Step 2: Add Beanie to your website

To add Beanie on your website, you must add a Javascript snippet including theidfield 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 themredirectToBeanieusing the BeanieSessionidparameter 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,redirectToBeanieshould 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 thesuccess_urlparameter while creating the session.
TheGETparameter:setup_detailsis transmitted, and contains a SECRET_KEY-encoded JWT with the following payload:

{
  beanie: {
    payment_method_registration_id: 'oc_cs_test_xxxxxxxx', // The Beanie Session ID
    livemode: false,
    customer_id: 'oc_cu_xxxxxxxxxx' // The Octobat Customer ID
  },
  transaction: {
    gateway: 'stripe', // Your payment gateway identifier
    type: "setup_intent", // The payment gateway transaction type
    id: 'seti_xxxxxxxxx', // The payment gateway transaction identifier
    payment_method_id: 'pm_xxxxxxxxx', // The payment method identifier
    customer_id: 'cus_xxxxxxxx' // The payment gateway customer identifier
  }
}

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 support@octobat.com