Skip to content
Process Payments/
/
Field Collection
Last updated

Field Collection

Overview

This guide provides an overview of how to collect payment fields using the embedded SDK. It covers the setup and integration of payment fields into your web application, allowing you to securely capture payment information from your customers.

By default, the embedded SDK only collects card details. However, you can customize the fields to collect additional information such as billing address and Name on Card.

Collect Billing Address

To collect the billing address, you can use the fieldCollection.billingAddress configuration option when initializing the embedded SDK. This option allows you to specify which billing address fields to include in the payment form.

We currently support the following billing address configuration options:

  • full: Collects the full billing address, including firstName, lastName, lineOne, lineTwo (optional), country, postal/zipCode and region (optional unless country is CA or US)
  • minimal: Collects only the country, postal/zipCode and region (optional unless country is CA or US)

Here's an example of how to configure the embedded SDK to collect the full billing address:

Collect Full Billing Address Example
Ryft.init({
    publicKey,
    clientSecret,
    fieldCollection: {
        billingAddress: {
            display: "full" // Change to "minimum" to collect the minimum billing address
        }
    }
});

When customers fill out their billing details, a billingAddressValidationChanged event will be triggered, which you can listen for to validate the billing address fields as described in the Handling SDK Events section.

Supply Billing Address Manually

In some cases, you may already have the customer's billing address information from a previous step in your checkout process. In such scenarios, you can supply the billing address directly to the embedded SDK as described below.

Additionally, you can make use of the fieldCollection.billingAddress.display field as follows:

  • full: Render the full billing address fields, but pre-fill them with the provided values to allow the customer to review and edit if necessary.
  • hidden: Do not render the billing address fields, but use the provided values for the transaction.

Here's an example of how to supply the billing address manually:

Supply Billing Address Manually Example
Ryft.init({
    publicKey,
    clientSecret,
    fieldCollection: {
        billingAddress: {
            display: "hidden", // or "full" to render the fields
            value: {
                firstName: "Fox",
                lastName: "Mulder",
                lineOne: "Stonehenge",
                postalCode: "SP4 7DE",
                city: "Salisbury",
                country: "GB",
                region: "<required for US/CA>"
            }
        }
    }
});

When supplying the billing address manually, ensure that the provided values are valid against our API validation rules. Invalid values may lead to transaction failures.

Collect Name on Card

The embedded SDK can also collect the Name on Card as part of the payment form. To enable this feature, you can use the fieldCollection.nameOnCard configuration option when initializing the SDK as follows:

Collect Name on Card Example
Ryft.init({
    publicKey,
    clientSecret,
    fieldCollection: {
        nameOnCard: true  // Set to 'false' to disable Name on Card collection
    }
});

When customers fill out their Name on Card, a cardValidationChanged event will be triggered, which you can listen for to validate the Name on Card field as described in the Handling SDK Events section.

Previous page
Next page