Hosted Fields Reference

Create Hosted Fields object

assembly.hostedFields(options?)

Initialises and manages a group of individual hosted fields.

Method parameters

Name

Description

Type

Default

options

Optional configuration

object

Options properties

Name

Description

Type

Default

environment

The 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

Name

Description

Type

Default

fieldType

Defines the type of Hosted Field.

'cardName' | 'cardNumber' | 'cardExpiry' | 'cardCvv' | 'bankAccountName' | 'bankRoutingNumber' | 'bankAccountNumber'

Required

options

Hosted Field configuration options.

object

Options properties

Name

Description

Type

Default

disabled

Disable the input element.

boolean

false

hideIcon

Hide the card icon in the card number field.

boolean

false

placeholder

Define the placeholder text for the field.

string

styles

Customise 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

Name

Description

Type

Default

element

The element to mount the field within. Can be a CSS selector or a DOM element.

string | HTMLElement

Required

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

Name

Description

Type

Default

event

The name of the event to listen to.

'ready' | 'change' | 'focus' | 'blur'

Required

handler

A callback function that gets executed when the event happens. It is passed an event object that contains information about the event.

(event) ⇒ void

Required

Handler event properties

Name

Description

Type

fieldType

A string that represents the field type.

'cardName' | 'cardNumber' | 'cardExpiry' | 'cardCvv' | 'bankAccountName' | 'bankRoutingNumber' | 'bankAccountNumber'

error

An object that contains error_name and error_message properties, when the Hosted Field has a validation error.

object | undefined

valid

It is true when the Hosted Field value is valid.

boolean

empty

It is true when the Hosted Field value is empty.

boolean

cardBrand

A 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

Name

Description

Type

Default

options

Hosted Field configuration options.

object

Required

Options properties

Name

Description

Type

Default

disabled

Disables the input element.

boolean

false

hideIcon

Hide the card icon in the card number field.

boolean

false

placeholder

Define the placeholder text for the field.

string

styles

Customise 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

Name

Description

Type

Default

additionalData

Provide any additional data to be sent along with the API request.

object

Required

additionalData properties

Name

Description

Type

Default

token

Assembly token auth

string

Required

user_id

Assembly 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.

Name

Description

Type

errors

An object containing any errors.

object | undefined

card_accounts

An 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

Name

Description

Type

Default

additionalData

Provide any additional data to be sent along with the API request.

object

Required

additionalData properties

Name

Description

Type

Default

token

Assembly token auth

string

Required

user_id

Assembly Buyer or Seller ID (already created).

string

bank_name

Bank name

string

Required

account_type

Bank account type (savings or checking).

string

Required

holder_type

Holder type (personal or business).

string

Required

country

ISO 3166-1 alpha-3 country code (3 char).

string

Required

payout_currency

ISO 4217 alpha-3 currency code. This parameter determines the currency with which funds are paid out.

string

currency

ISO 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.

Name

Description

Type

errors

An object containing any errors.

object | undefined

bank_accounts

An 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.


Did this page help you?