framepay-vue

Vue components for FramePay.js

Supported: Vue 2.4+

This is the repo for the official Vue.js wrapper for Rebilly's FramePay. This package provides a flexible set of methods and components to allow drop-in support of FramePay in any Vue 2.4+ project.

Table of Contents

• Table of Contents
• FramePay Documentation
• Demos
• Installation
• Getting Started
  • Initialization
    • At startup
    • On a component (rebilly-form, rebilly-card etc)
  • Usage
    • With rebilly-form
    • With rebilly-form and custom submit logic
    • With rebilly-token
    • Handle token manually
• Advanced Options
  • Multiple Payment Methods
    • v-if
    • v-show
  • Styling
    • Built in Styling
    • Custom Styling
  • Events
    • rebilly-form
    • on payment method components
  • Validation
  • Element IDs
• Available Components and Methods
  • Methods
    • createToken Proxy Method
    • The Rebilly Object
  • Components
    • RebillyForm
    • RebillyToken
    • Payment Method Components
      • Separate Credit Card fields
      • Separate Bank Account fields
      • Props
• Further Reading

FramePay Documentation

For more information on FramePay see its official documentation or repository.

Demos

Codesandbox demos coming soon

Installation

Step 1:

Install using Yarn:

yarn add @rebilly/framepay-vue

Or using NPM:

npm install @rebilly/framepay-vue --save

Step 2: Add the plugin to Vue:

// main.js
import FramePay from '@rebilly/framepay-vue';

Vue.use(FramePay);

Vue.use() also accepts an optional argument for initialization options. See Initialization below.

Getting Started

Initialization

Initialization can be done at startup, or directly on a payment component. To initialize FramePay you will need a publishable key from Rebilly. We recommend starting with a sandbox key.

See here for all initialization options: https://rebilly.github.io/framepay-docs/reference/rebilly.html#rebilly-initialize

At startup

//main.js
import FramePay from '@rebilly/framepay-vue';

const configuration = {
    publishableKey: 'pk_sandbox_1234567890',
    injectStyle: true,
};
Vue.use(FramePay, configuration);

See Built in Styling for more information about the injectStyle option.

On a component (rebilly-form, rebilly-card etc)

<rebilly-form :configuration="{ publishableKey: 'pk_sandbox_1234567890' }">
    <input data-rebilly="firstName">
    <input data-rebilly="lastName">
    <rebilly-card></rebilly-card>
<rebilly-form> 

If initialization options are attached to multiple components, only the first will be used.

Usage

framepay-vue offers three sets of payment method components:

• RebillyCard automatically mounts the combined credit card payment method
• RebillyCardCvv, RebillyCardExpiry, and RebillyCardNumber mount three separate components for collecting credit info
• RebillyBankAccountNumber, RebillyBankAccountType, and RebillyBankRoutingNumber mount the ach (bank account) payment method

Two more components are also offered for convenience:

• RebillyForm wraps a regular HTML form. It automatically detects payment method components and performs token creation/injection when the form is submitted. It is the simplest way to get started with framepay-vue.
• RebillyToken can be added to any standard form, and when present will automatically receive the token created by createToken(). You do not need to use RebillyToken if you are using RebillyForm already.

With rebilly-form

The default behavior of RebillyForm is to intercept the regular submit event, execute Rebilly.createToken(), and then submit the form with the newly created token attached. Any inputs that include data-rebilly attribute with the appropriate value will be sent to Rebilly.createToken().

<rebilly-form @error="" :extraData="{}">
    <input data-rebilly="firstName">
    <input data-rebilly="lastName">
    <rebilly-card></rebilly-card>
<rebilly-form>

<script>
import { RebillyForm, RebillyCard } from '@rebilly/framepay-vue';

export default {
    components: {
        RebillyCard,
        RebillyForm,
    },
};
</script>

Any DOM attributes you attach to RebillyForm will automatically be passed to the base form element.

@error will expose the error message returned if the Rebilly.createToken() request failed. You can inspect error.message and error.code.

See here for all arguments to extraData: https://rebilly.github.io/framepay-docs/reference/rebilly.html#extra-data.

See here for list of data-rebilly types: https://rebilly.github.io/framepay-docs/reference/rebilly.html#data-rebilly-fields.

With rebilly-form and custom submit logic

If you want to perform your own logic after token creation but before form submission, attach a listener to @submit on RebillyForm. If RebillyForm detects the listener on @submit, it will not submit the form automatically but instead emit it alongside the newly created token.

<rebilly-form @submit="submitHandler" @error="" :extraData="{}">
    <input data-rebilly="firstName">
    <input data-rebilly="lastName">
    <rebilly-card></rebilly-card>
<rebilly-form>
<script>
import { RebillyForm, RebillyCard } from '@rebilly/framepay-vue';

export default {
    components: {
        RebillyCard,
        RebillyForm,
    },
    methods: {
        submitHandler(token, form) {
             // do something with token
             form.submit()
        },
    },
};
</script>

With rebilly-token

If you prefer to call createToken() manually, use the example below. Note that you don't want to use the Rebilly object directly, but rather the proxied createToken method provided by framepay-vue. This method returns a promise that waits for the FramePay script to be loaded before calling Rebilly.createToken(). Using the pattern below will help eliminate errors due to race conditions.

<form @submit="submitHandler">
    <input data-rebilly="firstName">
    <input data-rebilly="lastName">
    <rebilly-card></rebilly-card>
    <rebilly-token></rebilly-token>
</form>

<script>
import { createToken, RebillyCard, RebillyToken } from '@rebilly/framepay-vue';

export default {
    methods: {
        submitHandler(event) {
            event.preventDefault();
            const form = event.target;
            const extraData = { } // some stuff
            createToken(form, extraData))
                .then((token) => {
                    // the token is already added to the form via RebillyToken
                       form.submit();
                })
                .catch((error) => {
                    // see error.code and error.message
                    console.log(error);
                });
        },
    },
};
</script>

Handle token manually

The token can also be handled entirely manually. As above, be sure to call the imported createToken() method instead of the global Rebilly object. This approach offers the most flexibility, but still removes the need for you to handle initialization, mounting and destruction of payment method elements.

<form @submit="submitHandler">
    <input data-rebilly="firstName">
    <input data-rebilly="lastName">
    <rebilly-card></rebilly-card>
</form>

<script>
    import { createToken, RebillyCard } from '@rebilly/framepay-vue';

    export default {
      methods: {
        submitHandler(event) {
            event.preventDefault();
            const form = event.target;
            const extraData = { } // some stuff
            createToken(form, extraData))
                .then((token) => {
                    // you must dynamically add the token id to the form
            	    form.submit();
                })
                .catch((error) => {
                    // see error.code and error.message
                    console.log(error);
                });
        },
      },
    };
</script>

Advanced Options

Multiple Payment Methods

v-if

Framepay will automatically use the first payment method it detects in the form. Multiple payment methods can be handled like this:

<rebilly-form @error="" :extraData="{}">
    <input data-rebilly="firstName">
    <input data-rebilly="lastName">
    <rebilly-card v-if="paymentMethod === 'payment-card'"></rebilly-card>
    <div v-if="paymentMethod=== 'ach'">
        <rebilly-bank-account-type></rebilly-bank-account-type>
        <rebilly-bank-account-number></rebilly-bank-account-number>
        <rebilly-bank-routing-number></rebilly-bank-routing-number>
    </div>
<rebilly-form>

<button @click="paymentMethod = 'payment-card'">PaymentCard</button>
<button @click="paymentMethod = 'ach'">Bank</button>

v-show

v-if causes the elements to be destroyed and recycled, meaning payment method fields will be re-mounted each time method changes in the above example.

It is possible to use v-show instead, which will allow you to preserve the user's input when they switch payment methods in your UI. However, you must specify which method FramePay should use to create the token, by passing it to extraData.

<rebilly-form @error="" :extraData="{ method: paymentMethod }">
    <input data-rebilly="firstName">
    <input data-rebilly="lastName">
    <rebilly-card v-if="paymentMethod === 'payment-card'"></rebilly-card>
    <div v-if="paymentMethod=== 'ach'">
        <rebilly-bank-account-type></rebilly-bank-account-type>
        <rebilly-bank-account-number></rebilly-bank-account-number>
        <rebilly-bank-routing-number></rebilly-bank-routing-number>
    </div>
<rebilly-form>

<button @click="paymentMethod = 'payment-card'">PaymentCard</button>
<button @click="paymentMethod = 'ach'">Bank</button>

Styling

Styling can be managed using Rebilly's built in styles for Framepay, or by setting some custom options.

Built in Styling

To use the built in styling, add injectStyle: true to your configuration object.

//main.js
import FramePay from '@rebilly/framepay-vue';

const configuration = {
    publishableKey: 'pk_sandbox_1234567890',
    injectStyle: true,
};
Vue.use(FramePay, configuration);

OR

<rebilly-form :configuration="{ publishableKey: 'pk_sandbox_1234567890', injectStyle: true }">
    <input data-rebilly="firstName">
    <input data-rebilly="lastName">
    <rebilly-card></rebilly-card>
<rebilly-form> 

Custom Styling

Custom styling can also be added to your configuration object. While the built-in styling affects the iframes containing Framepay fields, custom styling allows you to tweak the Framepay fields themselves. The full list of style options can be found in the table here: https://rebilly.github.io/framepay-docs/reference/rebilly.html#rebilly-initialize

Events

rebilly-form

As covered above, rebilly-form emits error and submit events.

on payment method components

Payment method components emit the following events: on, ready, focus and change.

See details: https://rebilly.github.io/framepay-docs/reference/element.html#element-on

Validation

Validation errors on payment method components can be detected by attaching a listener to change.

<rebilly-form @error="" :extraData="{}">
    <input data-rebilly="firstName">
    <input data-rebilly="lastName">
    <rebilly-card @change="changeHandler"></rebilly-card>
<rebilly-form>

<script>
    export default {
        methods: {
            changeHandler(e) {
        	    // e.valid, e.source, e.error
            },
        },
    };
</script>

See details: https://rebilly.github.io/framepay-docs/reference/element.html#element-on

Element IDs

By default, each payment method component's ID is the component name with -mount appended, eg: rebilly-card-mount

This can be changed by simply passing id as a prop to <rebilly-card>, <rebilly-bank-account-number> etc.

Because this will only change the ID of the element you are mounting Framepay to, it will not interfere any of the default or custom Framepay styling.

Available Components and Methods

Methods

createToken Proxy Method

framepay-vue exports a single method: createToken(). This method simply wraps the Framepay method Rebilly.createToken() in a promise to ensure that the Framepay script has loaded and the object is available. Be sure to import createToken from @rebilly/framepay-vue instead of using Rebilly.createToken(), otherwise you may run into errors due to race conditions.

Again, you don't need to use createToken at all if you choose to use the RebillyForm component.

The Rebilly Object

As mentioned above, Framepay will expose the Rebilly object in the global namespace after it has loaded. We recommend that you never call the Rebilly object directly, as framepay-vue is designed to either expose or abstract away all the methods you need to use Framepay.

For more information about the Rebilly object, see: https://rebilly.github.io/framepay-docs/reference/rebilly.html

Components

RebillyForm

RebillyForm accepts the following props:

• @submit
• @error
• the configuration object for initialization
• extraData for passing additional information to createToken()
• any attributes from a standard HTML form will be passed properly

See: Usage example

RebillyToken

RebillyToken accepts no arguments. It simply adds a hidden <input> element to the form, with the property data-rebilly="token" set.

See: Source code and Usage example

Payment Method Components

These components handle the mount/unmount lifecycle of a Framepay field, and can optionally be used for initialization. The available components are listed below.

• RebillyCard - mounts a combined payment field for card number, CVV and expiry

Separate Credit Card fields

These elements must all be mounted in the same form in order to successfully create a token.

• RebillyCardCvv - mounts a CVV field
• RebillyCardExpiry - mounts a credit card expiry field
• RebillyCardNumber - mounts a credit card number field

Separate Bank Account fields

These elements must all be mounted in the same form in order to successfully create a token.

• RebillyBankAccountNumber - mounts a bank account number field
• RebillyBankAccountType - mounts a set of inline buttons to select bank account type
• RebillyBankRoutingNumber - mounts a bank routing number field

Props

Payment method components all accept the same props:

• id for changing the ID of the element containing the mounted field
• @ready, @change, @focus, @blur
• the configuration object for initialization

Further Reading

Rebilly API for Payment Tokens https://rebilly.github.io/RebillyAPI/#tag/Payment-Tokens