Hosted Fields Reference

Create Hosted Fields object

assembly.hostedFields(options?)

Initialises and manages a group of individual hosted fields.

Method parameters

NameDescriptionTypeDefault
optionsOptional configurationobject

Options properties

NameDescriptionTypeDefault
environmentThe Assembly Payments environment. Use 'pre-live' for testing in the sandbox.'pre-live' | 'production''production'

Create a Hosted Field

First, create a Hosted Fields object with assembly.hostedFields(options)

hostedFields.create(fieldType, options?)

Creates a hosted field.

Method Parameters

NameDescriptionTypeDefault
fieldTypeDefines the type of Hosted Field.'cardName' | 'cardNumber' | 'cardExpiry' | 'cardCvv' | 'bankAccountName' | 'bankRoutingNumber' | 'bankAccountNumber'Required
optionsHosted Field configuration options.object

Options properties

NameDescriptionTypeDefault
disabledDisable the input element.booleanfalse
hideIconHide the card icon in the card number field.booleanfalse
placeholderDefine the placeholder text for the field.string
stylesCustomise the appearance of the field.object

Destroy Hosted Fields

hostedFields.destroy()

A method to remove the elements set up during initialisation.

Mount a Hosted Field

First, create a field with hostedFields.create()

hostedField.mount(element)

Mounts the HostedField to the specified element in the DOM.

You need to specify the DOM element you would like to mount the Hosted Field to.

If this element has an associated <label> element. The Hosted Field input will be focused when the label is clicked.

To associate a label, create a <label> element and specify a for attribute that references your element's id, just like you would in a regular HTML form.

Method Parameters

NameDescriptionTypeDefault
elementThe element to mount the field within. Can be a CSS selector or a DOM element.string | HTMLElementRequired

Listen to Hosted Field events

An event is a signal that something happened. Listen to events to communicate with your Hosted Field.

hostedField.on(event, handler)

Events include: ready, change, focus, blur.

Method Parameters

NameDescriptionTypeDefault
eventThe name of the event to listen to.'ready' | 'change' | 'focus' | 'blur'Required
handlerA callback function that gets executed when the event happens. It is passed an event object that contains information about the event.(event) ⇒ voidRequired

Handler event properties

NameDescriptionType
fieldTypeA string that represents the field type.'cardName' | 'cardNumber' | 'cardExpiry' | 'cardCvv' | 'bankAccountName' | 'bankRoutingNumber' | 'bankAccountNumber'
errorAn object that contains error_name and error_message properties, when the Hosted Field has a validation error.object | undefined
validIt is true when the Hosted Field value is valid.boolean
emptyIt is true when the Hosted Field value is empty.boolean
cardBrandA string that identifies the card brand based on the card number.'amex' | 'mastercard' | 'visa' | 'unknown'

Other Hosted Field events

hostedField.focus()

Set focus on the specified Hosted Field.

Note: This does not open the keyboard in iOS Safari, due to system limitations.

hostedField.blur()

Remove keyboard focus from the specified Hosted Field.

hostedField.clear()

Clear the value of the specified Hosted Field.

hostedField.unmount()

Remove the Hosted Field from the DOM. It can be added again using the mount method.

hostedField.update(options)

Updates the configuration options the Hosted Field was initially created with.

Method Parameters

NameDescriptionTypeDefault
optionsHosted Field configuration options.objectRequired

Options properties

NameDescriptionTypeDefault
disabledDisables the input element.booleanfalse
hideIconHide the card icon in the card number field.booleanfalse
placeholderDefine the placeholder text for the field.string
stylesCustomise the appearance of the field.object

Style object

A Hosted Field's inner/text styles are defined in the JavaScript configuration. The syntax is similar to regular CSS but must be valid JavaScript. Pseudo-classes, pseudo-elements and media queries are all supported. Class names are utilised to allow you to style the input field differently based on validation:

  • '.valid': Applied when the input has been validated and has a valid value.
  • '.invalid': Applied when the input has been validated and has an invalid value.

Only a subset of CSS properties are supported via the style object. Any other CSS properties can be applied to the container element, via your preferred CSS authoring approach. Here is a complete list of the CSS properties supported: appearance, color, font-family, font-size-adjust, font-size, font-stretch, font-style, font-variant-alternates, font-variant-caps, font-variant-east-asian, font-variant-ligatures, font-variant-numeric, font-variant, font-weight, font, letter-spacing, line-height, text-align, text-shadow, text-transform, transition, moz-appearance, moz-osx-font-smoothing, moz-tap-highlight-color, moz-transition, webkit-appearance, webkit-font-smoothing, webkit-tap-highlight-color, webkit-transition.

Hosted Field Container

The Hosted Field container is the DOM element that the Hosted Field is mounted to. When styling your Hosted Field, the container element should be treated as if it were an <input> element. Whilst the text styles (such as font-size and color) must be defined via JavaScript, the input container styles can be defined however you usually author CSS.

The Hosted Fields library allows you to style the field container based on the field state, by dynamically applying CSS classes to the container element. The class names are as follows:

  • hosted-field-invalid
  • hosted-field-valid
  • hosted-field-focus

Create Card Account

Capture card details for a new or existing customer.

assembly.createCardAccount(additionalData)

This method will safely collect the values from your Hosted Fields. Then if the Hosted Fields data is well-formed it will send a request to our server to create the card account.

This method requires the following Hosted Field types to be initialised: cardName, cardNumber, cardExpiry and cardCvv.

You need to supply an auth token as part of the additionalData object.

Method Parameters

NameDescriptionTypeDefault
additionalDataProvide any additional data to be sent along with the API request.objectRequired

additionalData properties

NameDescriptionTypeDefault
tokenAssembly token authstringRequired
user_idAssembly Buyer or Seller ID (already created).string

Response object

A promise that eventually resolves to an object containing the result. If the creation is successful it will return an object including the id. Otherwise, it will return an object specifying the error/s.

NameDescriptionType
errorsAn object containing any errors.object | undefined
card_accountsAn object containing details on the successful account creation.object | undefined

Create Bank Account

assembly.createBankAccount(additionalData)

This method will safely collect the values from your Hosted Fields. Then if the Hosted Fields data is well-formed it will send a request to our server to create the card account.

This method requires the following Hosted Field types to be initialised: bankAccountName, bankRoutingNumber and bankAccountNumber.

There is additional required data that you need to supply as part of the additionalData object.

Method Parameters

NameDescriptionTypeDefault
additionalDataProvide any additional data to be sent along with the API request.objectRequired

additionalData properties

NameDescriptionTypeDefault
tokenAssembly token authstringRequired
user_idAssembly Buyer or Seller ID (already created).string
bank_nameBank namestringRequired
account_typeBank account type (savings or checking).stringRequired
holder_typeHolder type (personal or business).stringRequired
countryISO 3166-1 alpha-3 country code (3 char).stringRequired
payout_currencyISO 4217 alpha-3 currency code. This parameter determines the currency with which funds are paid out.string
currencyISO 4217 alpha-3 currency code. This is an optional field and if not provided, the item will be created with the default currency of the marketplace.string

Response object

A promise that eventually resolves to an object containing the result. If the creation is successful it will return an object including the id. Otherwise, it will return an object specifying the error/s.

NameDescriptionType
errorsAn object containing any errors.object | undefined
bank_accountsAn object containing details on the successful account creation.object | undefined

hostedFields.captureDeviceId()

Generating a device ID

A method to generate a Device ID that represents the user's device.

First, create a Hosted Fields object with assembly.hostedFields(options)

hostedFields.captureDeviceId()

Return type

A promise that eventually resolves to a string.

Capturing an IP address

A method to obtain the end-users IP address.

assembly.getIPAddress()

Return type

A promise that eventually resolves to a string.