---
seo:
  title: Checkout form and token creation
  description: Learn how to create a checkout form and manage token creation.
  keywords: 'Developer docs'
  lang: en-US
redirects:
  '/docs/content/dev-docs/concept/checkout-form-and-token-creation/': {}
  '/docs/content/concepts-and-features/concept/checkout-form-and-token-creation/': {}
  '/docs/concepts-and-features/concept/checkout-form-and-token-creation/': {}
---

# Checkout form and token creation

If you have not used FramePay previously, see [Get started with FramePay](/docs/dev-docs/basic-setup.md).

FramePay processes your checkout form and injects UI elements that are rendered into secure, Rebilly hosted, iframes.

When a customer submits a valid FramePay form you use `Framepay.createToken(form, extraData)` to generate a payment token.

The values of `form` and `extraData` parameters depend on:

- the configured payment method/s.
- how you manage your customer information.

You use the form in 3 contexts:

- Specify the mounting points where FramePay injects UI elements.
- Specify `data-rebilly` attributes to indicate which customer data is collected.
- Create the payment token by passing the form to `Framepay.createToken(form, extraData)`.

## Mounting points

The instructions to specify mounting points are detailed in the [Get started with FramePay](/docs/dev-docs/basic-setup.md) topic.

## Checkout form attributes

There are only 2 payment methods (`payment card` and `bank account`) that require your customer information.

Use `data-rebilly` attributes to specify which customer data is collected by FramePay.

### Customer name

When you use the form to create a payment token, the only required customer data is the name of the customer.

There are 2 options to specify the name of the customer:

#### `fullName` in just one input

```javascript
...
<input data-rebilly="fullName">
...
```

#### `firstName` and `lastName` in two different inputs

```javascript
...
<input data-rebilly="firstName">
<input data-rebilly="lastName">
...
```

### Other customer data

You can optionally add the following `data-rebilly` attributes to your checkout form:

- `organization`
- `address`
- `address2`
- `city`
- `region`
- `country`
- `postalCode` <small>(optional: add a custom label using the `data-rebilly-label` attribute)</small>
- `phoneNumbers` <small>(optional: add a custom label using the `data-rebilly-label` attribute)</small>
- `emails` <small>(optional: add a custom label using the `data-rebilly-label` attribute)</small>
- `bic` <small>(exclusive to the [BBAN](framepay-global-reference.md#framepay.bban.mount) methods) </small>
- `bankName` <small>(exclusive to the [IBAN](framepay-global-reference.md#framepay.iban.mount) methods) </small>

## Create payment tokens

Use `Framepay.createToken(form, extraData)` to create a payment token with the customer data collected in the form.

The `form` parameter can be:

- a valid string `DOM` selector.
- a `jQuery` instance.
- a `Zepto` object that wraps an element within the page.
- `null` value, when the payment method does not require customer data (only `payment card` and `bank account` payment methods do require customer data).

### Inject token data

<!-- TODO --> Is this an alternative way to `createToken`?

FramePay can inject the newly created token into your payment form. This is useful for sending the token ID or payment instrument details directly to your own backend, as part of the payment form submission.

To automatically inject token data into your form, use `hidden input fields` with one of these specific `data-rebilly` attributes:

- `token` <small>The token ID.</small>
- `payment-instrument` <small>The [payment instrument](/docs/dev-docs/api/payment-tokens/posttoken/) details as a stringified object.</small>

This way, the token data is sent directly to your backend when the form is posted.

## Example

<!-- TODO IMPROVE EXAMPLE-->

This is an example of a checkout form with both visible customer inputs and hidden inputs:

```html
<form>
  <fieldset>
    <div class="field">
      <!-- FramePay will automatically gather this input field's value. -->
      <input data-rebilly="firstName" placeholder="First Name" />
    </div>
    <div class="field">
      <!-- FramePay will automatically gather this input field's value. -->
      <input data-rebilly="lastName" placeholder="Last Name" />
    </div>
    <div class="field">
      <!-- FramePay will automatically gather this input field's value. -->
      <input data-rebilly="emails" placeholder="Email" />
    </div>
    <div class="field">
      <!-- FramePay will automatically gather this input field's value. -->
      <input data-rebilly="phoneNumbers" data-rebilly-label="Custom label" placeholder="Phone" />
    </div>

    <!-- The following fields are not visible to the end user.
             Instead, FramePay will populate those fields with token data. -->
    <input type="hidden" data-rebilly="token" name="rebilly-token" />
    <input type="hidden" data-rebilly="payment-instrument" name="rebilly-payment-instrument" />
  </fieldset>
  <button>Pay</button>
</form>
```

---

---

---

---

---

---

---

## Framepay.errorCodes

The errorCodes namespace, uses for overriding default error messages see [configuration i18n](framepay-configuration-reference.md#i18n)

## Framepay.initialize()

Use this method to initialize FramePay with your publishable API key and customize the look and feel of elements.

It accepts a single [`configuration`](framepay-configuration-reference.md) object.

```JavaScript
// the basic configuration must contain your publishable API key
Framepay.initialize({
    publishableKey: 'pk_sandbox_1234567890',
    organizationId: 'your-organization-id', // no required property
});
```

<div className="warning">Use your own publishable key<br />
You must replace the key `pk_sandbox_1234567890` with your own. Start with a sandbox key. To create a publishable key, <a href="https://app.rebilly.com/api-keys/add">visit Rebilly</a>.
A key is specific to either the sandbox or live environment.
</div>

<br />

The `configuration` must contain at a [`publishableKey`](framepay-configuration-reference.md#publishablekey) otherwise an error will be thrown. It can optionally define CSS styles and className names to overwrite the style of FramePay.

For the `configuration` details please take a look at [configuration](framepay-configuration-reference.md#i18n).

```JavaScript
// first call
Framepay.initialize(config);

// where config is
const config = {
    icon: { // icon for combined field
        display: true // false to hide
    },
    classes: {}, // when needed,
    style: {
        base: { // shared `base` state
            color: '#fff', // generic JS property for DOM style
            '::placeholder': { // access to pseudo-element
                color: 'gray', // overwrite placeholder color only
            },
        },
        invalid: {
            color: 'red',
            '::placeholder': {
                color: 'firebrick',
            },
        },
    }
};
```

## Framepay.update()

Use this method has the same functionality as the `initialize` method, but this method will update actual configuration.

```javascript
Framepay.update({
  /* new configuration object */
});
```

The update priority.
Any properties which were established and not passed in the new configuration - will stay.

```javascript
Framepay.initialize({
  locale: Framepay.locale.es,
  icon: {
    display: true,
  },
  style: {
    base: {
      color: '#fff',
    },
  },
});

Framepay.update({ icon: { color: 'red', style: null } });
```

The actual Rebilly configuration will be:

```javascript
{
    locale: 'es',
    icon: {
        display: true,
        color: 'red'
    },
    style: {} // default value
}
```

## Framepay.createToken()

Use this method to create a token from the contents of a form. FramePay will automatically look for all elements that were mounted and any `input` fields with a `data-rebilly` attribute will be parsed automatically and sent alongside the elements' data.

Alternatively you can provide an `extraData` object containing properties supported by the Rebilly API instead of including additional field in your form.

```JavaScript
// create a token from the fields within a form
Framepay.createToken(form);

// optionally include extra data that is not found in the form
Framepay.createToken(form, extraData);
```

This method returns a `Promise` with a single argument representing the API result of the operation. Validation or network errors can be caught using a `catch()` handler and displayed to the customer.

```JavaScript
var form = document.querySelector('form');
form.addEventListener('submit', function (event) {
    event.preventDefault();
    Framepay.createToken(form)
        .then(function (token) {
            // if we have a token field in the form
            // we can submit directly
            form.submit();
        })
        .catch(function (error) {
            // see error.code and error.message
        });
});
```

If a `data-rebilly="token"` hidden input field is detected in your form the payment token will be automatically injected. However, the payment token ID is available as `token.id` if you prefer manual handling.

In order for the token creation to work you must mount fields before triggering `createToken`.

### Extra data

The `extraData` argument is optional and enables you to define specific values to include in your payment token request. The billing address values match the properties supported by `data-rebilly` input fields and can be provided as either form fields or as this object literal.

These options can be defined within:

<table>
    <thead>
        <tr>
            <th>Option</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td style={{verticalAlign: 'top'}}>
                <strong>method</strong><br />
                <code>string</code>
            </td>
            <td>
                <p>When provided FramePay will attempt to process the form data to generate a payment token for this <code>method</code>. Always define this property.</p>
                <h4>Multiple methods</h4>
                <p>This property is required when using multiple payment methods at the same time in a form or when using methods other than <code>payment-card</code> or <code>ach</code>.</p>
                <p>Accepts any of the [methods supported by Rebilly](/docs/dev-docs/api/payment-tokens/posttoken/).</p>
            </td>
        </tr>
        <tr>
            <td style={{verticalAlign: 'top'}}>
                <strong>billingAddress</strong><br />
                <code>object</code><sub>optional</sub>
            </td>
            <td>
                <p>This object defines the billing address of the customer.</p>
                These keys can be provided:
                <ul>
                    <li><code>firstName</code></li>
                    <li><code>lastName</code></li>
                    <li><code>organization</code></li>
                    <li><code>address</code></li>
                    <li><code>address2</code></li>
                    <li><code>city</code></li>
                    <li><code>region</code></li>
                    <li><code>country</code></li>
                    <li><code>postalCode</code></li>
                    <li><code>phoneNumbers</code>, an array of objects representing phone numbers. Each item must include a <code>label</code> and <code>value</code></li>
                    <li><code>emails</code>, an array of objects representing email addresses. Each item must include a <code>label</code> and <code>value</code></li>
                </ul>
                <h4>Required values</h4>
                <p>Please note that the <code>firstName</code> and <code>lastName</code> values are required to create a payment token. If they are not present
                within your form's fields you must define them as <code>extraData</code>.</p>
            </td>
        </tr>
        <tr>
            <td style={{verticalAlign: 'top'}}>
                <strong>leadSource</strong><br />
                <code>object</code><sub>optional</sub>
            </td>
            <td>
                <p>A lead source is Rebilly's term for the marketing campaign responsible for a customer interaction (typically a customer purchasing something).</p>
                <p>There are two ways to collect lead source information: either you provide it explicitly within the <code>extraData</code> option or use <a href="../lead-sources/">FramePay to collect Google UTM parameters</a> from the web address hosting it.</p>
                <p>If the lead source parameter is defined all UTM parameters from the web address will be ignored.</p>
                <h4>Lead source parameters</h4>
                <p>A lead source is just some additional metadata that attaches to the customer’s record, and contains attributes common from both <strong>Google analytics</strong> (UTM) and affiliate tracking applications:</p>
                <ul>
                    <li><code>source</code> a UTM parameter</li>
                    <li><code>medium</code> a UTM parameter</li>
                    <li><code>campaign</code> a UTM parameter</li>
                    <li><code>content</code> a UTM parameter</li>
                    <li><code>term</code> a UTM parameter</li>
                    <li><code>affiliate</code> an affiliate tracking parameter</li>
                    <li><code>subAffiliate</code> an affiliate tracking parameter</li>
                    <li><code>clickId</code> an affiliate tracking parameter</li>
                    <li><code>salesAgent</code> a sales tracking parameter</li>
                    <li><code>currency</code> and <code>amount</code>:  the cost of the lead</li>
                </ul>
                <p>These parameters are optional.</p>
                <h4>Prevent automatic attribution</h4>
                <p>If you want to prevent automatic lead source attribution from Google analytics UTM fields you can define this property as an empty object.</p>
                <pre><code>{`var extraData = {
   leadSource: {}
};`}</code></pre>
            </td>
        </tr>
          <tr>
            <td style={{verticalAlign: 'top'}}>
                <strong>BIC</strong><br />
                <code>string</code>
            </td>
            <td>
                <p>the SWIFT or BIC Code</p>
                <p>Only for the BBAN and IBAN methods, <br />allowed in the <code>data-rebilly</code> fields</p>
            </td>
        </tr>
        <tr>
            <td style={{verticalAlign: 'top'}}>
                <strong>bankName</strong><br />
                <code>string</code>
            </td>
            <td>
                <p>Bank name</p>
                <p>Only for the BBAN and IBAN methods, <br />allowed in the <code>data-rebilly</code> fields</p>
            </td>
        </tr>
    </tbody>
</table>

For example, if your form gathered the customer's name at a previous step and did not include the fields in the form used to create the token, then you would define it as extra data:

```JavaScript
// within the event listener for the form submit
var extraData = {
    billingAddress: {
        firstName: 'John',
        lastName: 'Doe'
    },
    leadSource: {
        campaign: 'facebook',
    }
};
// define extra data as the second argument
Framepay.createToken(form, extraData)
        .then(function (token) {
            // if we have a token field in the form
            // we can submit directly
            form.submit();
        })
        .catch(function (error) {
            // see error.code and error.message
        });
});
```

### `data-rebilly` Fields

See [data-rebilly fields](form-setup.md)