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-invalidhosted-field-validhosted-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.
Updated about 3 years ago