> This is Payabli documentation. For a complete page index, fetch https://docs.payabli.com/llms.txt — append .md to any page URL for lightweight markdown. For section-level indexes, query parameters, and other AI-optimized access methods, see https://docs.payabli.com/ai-agents.md
# EmbeddedMethod UI
> Learn how to use the EmbeddedMethod UI embedded component to add the ability to securely store a payment profile or execute a sale
Use the EmbeddedMethod component to capture a payment method or make a sale using any payment method. This is the most flexible and customizable component Payabli offers to developers.
## Usage
This section shows how to use the EmbeddedMethod UI component in your project.
Use the interactive demo to see how the component works, then follow the configuration walkthrough to set it up in your project.
See [Library URLs](/guides/pay-in-components-overview#library-urls) for important information about embedded components library URLs.
### Interactive demo
This demo shows the component in action with transaction processing and visual feedback.
When the component processes a transaction, the demo displays the JSON response.
This demo shows the EmbeddedMethod UI component configured to process card, ACH, and RDC payments.
### Configuration walkthrough
/// Include the Payabli script
First, add the Payabli embedded component script to your HTML.
Make sure to include the `data-test` attribute for testing in the sandbox environment.
Including `` in the `` element prevents problems with special characters such as 'á' or 'ñ'.
/// Create the container and tab structure
Add a container element where the embedded component will render.
The `id` attribute becomes the `rootContainer` in your configuration.
Create tabs to switch between card, ACH, and RDC payment methods.
/// Add basic styling
Add CSS styles for the tabs to handle active and focus states.
/// Configure card payment method
Create the configuration object for card payments.
The `token` must be a **public API token**.
/// Configure ACH payment method
Create the configuration object for ACH payments.
The `token` must be a **public API token**.
/// Configure RDC payment method
Create the configuration object for RDC (Remote Deposit Capture) payments.
The `token` must be a **public API token**.
/// Add tab switching logic
Add JavaScript code for the tabs. The code handles reinitializing the component when users change payment methods.
/// Initialize and execute payment
Use the `payabliExec('pay')` function to perform payment processing logic.
This function processes a secure one-time payment with the embedded component.
```html
Payabli Integration
Payment Form
Enter your payment information below:
```
/// Include the Payabli script
First, add the Payabli embedded component script to your HTML.
Make sure to include the `data-test` attribute for testing in the sandbox environment.
This loads the core `PayabliComponent` class that powers all embedded components.
Including `` in the `` element prevents problems with special characters such as 'á' or 'ñ'.
```html
Payabli Integration - Temporary Token Flow
```
/// Create the container and tab structure
Add a container element where the embedded component will render.
The `id` attribute becomes the `rootContainer` in your configuration.
Create tabs to switch between card and ACH payment methods.
/// Add basic styling
Add CSS styles for the tabs to handle active and focus states.
/// Configure card payment method
Create the configuration object for card payments with `temporaryToken: true`.
This setting enables the temporary token flow. See [Temp token flow](/guides/platform-developer-tokenization-temp-flow) for more information about the temporary token flow.
The `token` must be a **public API token**.
/// Configure ACH payment method
Create the configuration object for ACH payments with `temporaryToken: true`.
The `token` must be a **public API token**.
/// Add tab switching logic
Add JavaScript code for the tabs. The code handles reinitializing the component when users change payment methods.
/// Initialize and execute token generation
Use the `payabliExec('method')` function to trigger temporary token generation.
This function generates a secure temporary token for the payment method entered into the embedded component.
For more information on using temporary tokens, see [Extend embedded components with the temporary token flow](/guides/platform-developer-tokenization-temp-flow).
```html focus=245-257
Payabli Integration
Payment Form
Enter your payment information to generate a temporary token:
```
### Configuration reference
These are the configuration parameters available for the EmbeddedMethod component.
If you need to pass more than data than what's supported, consider using the temporary token flow.
See [Temporary Token Flow](/guides/platform-developer-tokenization-temp-flow) for more information.
**`type`** `string` — required
This value determines the type of embedded component to render.\
Accepted values are: `methodEmbedded`, `methodLightbox`, `vterminal`, or `expressCheckout`.\
For the EmbeddedMethod UI, this value is `methodEmbedded`.
See the [Embedded Components Overview](/guides/pay-in-components-overview) for more information on other component types.
---
**`rootContainer`** `string` — required
Container ID used for the component.
---
**`defaultOpen`** `string`
Sets the default payment method that's shown. Accepted values are: `card` or `ach`.
---
**`hideComponent`** `boolean` — default: false
When true the component is hidden when it's instanced.
---
**`token`** `string` — required
API token for authentication. This should be a **public** API token, as described [here](/developers/api-tokens#api-token-types).
---
**`forceCustomerCreation`** `boolean` — default: true
When `true`, the component uses the `customerData` object to create a new customer record.
When `temporaryToken` is `true` and `forceCustomerCreation` is `false`, the component doesn't create a new customer record.
See [Temporary Token Flow](/guides/platform-developer-tokenization-temp-flow#disable-customer-creation) for more information.
---
**`customCssUrl`** `string`
Complete URL of a custom CSS stylesheet to use with the component.
---
**`clearFormAfterSubmit`** `boolean` — default: true
When `true`, the entered values on the form are cleared when submitted.
---
**`temporaryToken`** `boolean` — default: true
When `true`, the token created for the payment is temporary. Set this parameter to false to create a storedMethodId and save the payment profile.
---
**`showPopoverError`** `boolean` — default: true
When `false`, the validation error appears below the field instead of above it in a popover.
---
**`entryPoint`** `string`
When the API token belongs to an organization, the entrypoint name identifies the target paypoint (merchant).
---
**`card`** `object` — required
`cardService` object used to configure accepted card types.
#### properties
**`enabled`** `boolean`
Enable/disable card option.
---
**`amex`** `boolean`
Enable/disable acceptance of American Express cards.
---
**`discover`** `boolean`
Enable/disable acceptance of Discover cards.
---
**`visa`** `boolean`
Enable/disable acceptance of Visa cards.
---
**`mastercard`** `boolean`
Enable/disable acceptance of MasterCard cards.
---
**`diners`** `boolean`
Enable/disable acceptance of Diner's Club cards.
---
**`jcb`** `boolean`
Enable/disable acceptance of JCB cards.
---
**`inputs`** `object`
Card input fields descriptors. This object applies only to the EmbeddedMethod UI component.
#### properties
**`cardHolderName`** `object`
Optional, but *strongly recommended*. Descriptor object for input field.
---
**`cardNumber`** `object` — required
Descriptor object for input field.
---
**`cardExpirationDate`** `object` — required
Descriptor object for input field.
---
**`cardCvv`** `object` — required
Descriptor object for input field.
---
**`cardZipcode`** `object`
Optional, but *strongly recommended*. Descriptor object for input field.
---
---
---
**`ach`** `object` — required
`achService` object used to configure accepted ACH types.
#### properties
**`enabled`** `boolean`
Enable/disable ACH option.
---
**`checking`** `boolean`
Enable/disable acceptance of Checking account.
---
**`savings`** `boolean`
Enable/disable acceptance of Savings account.
---
**`achValidation`** `boolean` — default: false
When set to true, the embedded component will validate ACH account and routing numbers in real time.
This is an add-on feature. Contact the Payabli team for more information.
---
**`inputs`** `object`
ACH input field descriptors. This only applies to the EmbeddedMethod UI component.
#### properties
**`achAccountHolderName`** `object` — required
Required. Descriptor object for input field.
---
**`achAccountType`** `object` — required
Required. Descriptor object for input field.
---
**`achRouting`** `object` — required
Required. Descriptor object for input field. Use the
`confirm` input descriptor to add matching validation to this field. See [Style Individual Fields](/guides/pay-in-components-overview#style-individual-fields) for more.
---
**`achAccount`** `object` — required
Required. Descriptor object for input field. Use the
`confirm` input descriptor to add matching validation to this field. See [Style Individual Fields](/guides/pay-in-components-overview#style-individual-fields) for more.
---
---
---
**`rdc`** `object` — required
`rdcService` object used to configure accepted RDC types.
#### properties
**`enabled`** `boolean`
Enable/disable RDC option.
---
**`amount`** `number`
Amount to collect via RDC.
---
**`inputs`** `object`
RDC input field descriptors.
#### properties
**`rdcAccountHolderName`** `object`
Descriptor object for input field.
---
**`rdcAmount`** `object`
Descriptor object for input field.
---
---
---
**`paymentMethod`** `object` — required
`paymentMethod` object with data related to the payment method. **Required when saving a payment method or executing a payment**. Can be passed to the component via payabliExec method.
---
**`customerData`** `object` — required
Customer Object with data related to customer. Can be passed to the component as a parameter with the `payabliExec` method. **Required when saving a payment method**. Which fields are required depends on whether the paypoint has custom identifiers. If you aren't using custom identifiers, then you must include at least one of these values: `firstname` and `lastname`, `email`, or `customerId`.
---
**`paymentDetails`** `object` — required
`paymentDetails` object with data related to the payment. **Required to save a payment method**. Can be passed to the component via payabliExec method.
---
**`fallbackAuth`** `boolean | null` — default: false
When `true`, if tokenization fails, Payabli will attempt an authorization transaction to request a permanent token for the card. If the authorization is successful, the card will be tokenized and the authorization will be voided automatically.
---
**`fallbackAuthAmount`** `number | null` — default: 1.00
The amount for the `fallbackAuth` transaction. Defaults to one dollar.
---
**`functionCallBackSuccess`** `function`
The callback function called when the component executes successfully.
---
**`functionCallBackError`** `function`
The callback function called when the component receives an error. See [functionCallBackError response](/guides/pay-in-components-embeddedmethod-ui#functioncallbackerror-response) in the next section for a complete reference.
---
**`functionCallBackReady`** `function`
The callback function called when the component's status changes. Used to poll the form's completeness before showing the submit button.
---
## Response
The embedded component returns a response object to the callback functions defined in the configuration.
The response object contains the result of the transaction (success, declined, or error) and details about the transaction.
### Response examples
Click the tab to see an example response returned by the embedded component for each result.
```js Payment success
{
responseText: "Success",
responseData: {
authCode: "123456",
referenceId: "40-692c62895d1541d28c0bf77b275a26e4",
resultCode: 1,
resultText: "Approved",
avsResponseText: "",
cvvResponseText: "",
customerId: 706,
methodReferenceId: null
}
}
```
```js Payment decline
{
responseText: "Declined",
responseData: {
authCode: null,
referenceId: "40-2c437c3dcdc242bea96f52bdf42d2eeb",
resultCode: 2,
resultText: "200: Decline. Generally insufficient funds or incorrect card data supplied, for example, expiry date or security code.. DECLINE",
avsResponseText: "",
cvvResponseText: "",
customerId: 706,
methodReferenceId: null
}
}
```
```js Stored method success
{
responseText: "Success",
responseData: {
referenceId: "187-c5892026d9f345ffa63bf909d574fe92",
resultCode: 1,
resultText: "Added",
customerId: 1636,
methodReferenceId: "187-c5892026d9f345ffa63bf909d574fe92"
}
}
```
```js Stored method decline
{
responseText: "Declined",
responseData: {
referenceId: "187-d2a29970fa604edba5a6dbec67ace3ae",
resultCode: 2,
resultText: "200: Transaction was declined by processor.. DECLINE",
customerId: 1636,
methodReferenceId: "187-d2a29970fa604edba5a6dbec67ace3ae"
}
}
```
### Response reference
The response object passed to a callback function has the following structure:
**`responseText`** `string`
"Success" or "Declined"
---
**`responseData`** `object`
Container for response details.
#### properties
**`responseData.AuthCode`** `string`
Authorization code for payments. This field has a value of `null` for saved payment methods.
---
**`responseData.ReferenceId`** `string`
Identifier for the transaction (for payments) or the stored payment method (for save payment method).
---
**`responseData.ResultCode`** `integer`
Result of operation. 1 is success, 2 is declined, and 3 is error.
---
**`responseData.ResultText`** `string`
Message related the result. If the operation was successful, it returns "Added"/"Approved". If there was an error, it returns error details.
---
**`responseData.AvsResponseText`** `string`
Result of address validation for card transactions. This field is an empty string when processing ACH transactions. This field doesn't exist when saving payment methods.
---
**`responseData.CvvResponseText`** `string`
Result of CVV validation for card transactions. This field is an empty string when processing ACH transactions. This field doesn't exist when saving payment methods.
---
**`responseData.CustomerId`** `integer`
ID for the customer owner of payment or saved payment method.
---
**`responseData.methodReferenceId`** `string`
Identifier for stored payment method for saved payment methods.
This field has a value of `null` for payment transactions.
The `methodReferenceId` is used as the `storedMethodId` in other operations.
See [Handling responses and errors](/guides/pay-in-components-overview#handling-responses-and-errors) for more.
---
---
### `functionCallBackError` response
The `functionCallBackError` function is called when the component can't validate the payment information before submitting it to Payabli's API.
The response object passed to `functionCallBackError` contains an array with codes, keys, and descriptions of failed validations.
You can check the values in the array to offer your customized error message.
| Code | Key | Description |
| ---- | --------------------------------------- | --------------------------------- |
| 802 | paymentMethodsCardNumberError | Error in Card number field |
| 803 | paymentMethodsCardExpirationDateError | Error in Card Expiration field |
| 804 | paymentMethodsCardCvvError | Error in CardCVV field |
| 805 | paymentMethodsCardZipcodeError | Error in Card Zip code field |
| 901 | paymentMethodsAchAccountHolderNameError | Error in ACH Holder field |
| 902 | paymentMethodsAchAccountTypeError | Error in ACH Account type field |
| 903 | paymentMethodsAchRoutingError | Error in ACH Routing field |
| 904 | paymentMethodsAchAccountError | Error in ACH Account number field |
## Usage Flows
These flowcharts illustrate the path to making a payment or storing a payment method using an embedded component.
### Make a payment
To make a payment with an embedded component, your component configuration should contain `payabliExec(pay, parameters)`. In the `parameters` argument, include `customerData` and `paymentDetails` objects. When the payment is executed, the request returns response data.
*This flowchart explains the basic steps for the task. Hover over a step for more information.*
Run `payabliExec(pay, parameters)`
The action is set to `pay` here. Send the `paymentDetail` and `customerData` object in `parameters`.
→
Payment executed
The transaction is executed and includes the data sent as parameters
→
Response
### Save a payment method
To save a payment method with an embedded component, your component configuration should contain `payabliExec(method, parameters)`. In the `parameters` argument, include `customerData` and `paymentDetails` objects. When the payment method is saved, the request returns response data.
*This flowchart explains the basic steps for the task. Hover over a step for more information.*
Run `payabliExec(method, parameters)`
The action is set to `method` here. Send the `paymentDetail` and `customerData` object in `parameters`.
→
Payment method saved
The payment method is saved and includes the data sent as parameters
→
Response
### Save a payment method and make a payment
You can save a payment method and make a payment with the EmbeddedMethod UI component by writing a callback function to execute the payment after successfully saving the payment method.
To save a payment method and then execute a transaction with the saved payment method, your component configuration should contain `payabliExec(method, parameters)`. In the `parameters` argument, include the `customerData` and `paymentDetails` objects. When the payment method is saved, use a callback function to execute the transaction.
Remember to never make payment transactions via client-side API requests. Your callback function should make the payment transaction using a server-side function.
*This flowchart explains the basic steps for the task. Hover over a step for more information.*
Run `payabliExec(method, parameters)`
Here, the action is set to `method`. Send the `paymentDetail` and `customerData` object in `parameters`.
→
Payment method saved
The payment method is saved and includes the data sent as parameters. An ID for the payment method is returned, which is then used to make transactions.
→
Callback function
Use a callback function to send a transaction that uses the new payment method.
→
Response
## Related resources
See these related resources to help you get the most out of Payabli.
#### Advanced topics
* **[Embedded components framework integrations](/guides/pay-in-developer-components-frameworks)** - Learn how to use Payabli's embedded components with front-end frameworks like React and Vue
* **[Temporary token example app (for developers)](/guides/platform-tokenization-temp-token-app)** - Go through a guided checkout experience using the temporary token flow
* **[Extend embedded components with the temporary token flow (for developers)](/guides/platform-developer-tokenization-temp-flow)** - Use the temporary token flow with embedded components to have complete control over user transaction experience without expanding PCI scope
#### Related topics
* **[Embedded components overview](/guides/pay-in-components-overview)** - Learn how to use Payabli's embedded components to create customized checkout experiences without handling sensitive payment information yourself
* **[Pay In Payment Flow](/guides/mobile-components-payin)** - Mobile equivalent for native iOS apps