Guides > Embedded Fields

Embedded Fields


Embed payment fields in your web-based application or mobile application. Collect and process payment information on Qualpay servers. Your customer will remain on your website or in your application, so all of your branding and style will be maintained. Since your server is not processing customer payment data, your PCI DSS (Payment Card Industry Standard Data Security Standard) compliance scope is greatly reduced while taking advantage of Qualpay's PCI DSS Level 1 certified platform.

With Embedded Fields, you can include payment fields hosted by Qualpay directly in your payment form. Your customer can enter their credit card number or ACH account and routing number, expiration date, and Card Verification Value (CVV) into the Embedded Fields. You will implement the 'Pay' button on your site, then Embedded Fields will submit the form when the 'Pay' button is clicked. When the form is submitted, Qualpay will generate a single-use or permanent card_id depending on your configuration parameters. Using the success handler callback routine, you can use the card_id to invoke any transaction type you wish using our Payment Gateway API. If you're not ready to charge your customer, you can use the returned card_id to create a record in the Customer Vault with our Customer Vault API so that you can charge your customer at a later date.


Transaction Types

Both one-time and permanent tokens (card_id) can be used for any request that the Qualpay Payment Gateway API supports.

Card Types

A card_id can be created for Visa, MasterCard, Discover, American Express, International Diners and JCB cards. You may use both Google Pay and Qualpay's Embedded Fields in your checkout page. Either use Embedded Fields to collect payment information from your customer or integrate with Google Pay to request the payload from Google Server.


Maintain branding and complete control over the placement of Embedded Fields.


Sensitive cardholder data will travel from your customer's device directly to Qualpay, never touching your servers. PCI DSS (Payment Card Industry Standard) compliance scope is greatly reduced. Qualpay is a PCI DSS (Payment Card Industry Data Security Standard) certified Level 1 compliant Service Provider.


Sign up for an account to access the Qualpay Sandbox environment and retrieve your sandbox test keys in the Administration section. Be sure to enable access for Embedded Fields by setting the slider for Embedded Fields API to 'yes'. Integrate directly with our API or take advantage of one of our SDKs.

Possible Configuration Parameters

*Note if any of the required fields are not present, the Embedded fields frame will not load.

Variable length, required
The HTML 'id' of the form that will be submitted.
String, optional, default is test
Possible values are "test" for Sandbox environment or "prod" for Production environment.
Fixed length, 32 AN, required
Transient Key generated for use with Embedded fields. The key expires in 30 minutes.
Boolean, optional, default is false
By default embedded fields generates a single use card_id that can be used only once in Qualpay gateway requests. By setting tokenize to true, the card_id is stored in card vault and hence can be reused in future Qualpay gateway requests.
Javascript function, required
Success handler callback function to process the returned card_id. The function takes a JSON object argument that contains the card_id and number. Refer to the success handling section for more information on the success handler.
Javascript function, optional
Error handler callback function to process errors from the embedded fields. The function takes a JSON object that contains information about the error. Refer to Error Handling section for more information.
Javascript function, optional
A callback javascript function that will be invoked before Qualpay submits your form. If the function returns false, the form submission will be cancelled. The function can be used to disable elements in your form to prevent multiple submissions or can be used to run javascript validations before the form is submitted.
JSON, optional
If your account is enabled to process ACH payments, use this JSON to control the display of ACH tab on the embedded form. Refer to the ACH Configuration section for more information.
JSON, optional
By default all accounts can process card payments, use this JSON to hide card payment data on the embedded form. Refer to Card Configuration section for more information.
JSON, optional
By default the CVV is optional on the embedded fields. You can set it to be required using this field.
string, optional
Any font name listed on Google Fonts, can delimit with pipe (|) if more than one is needed.
string, optional
CSS rules can be passed to accomplish very general formatting such as the following:

Using a Captcha with Embedded Fields

To prevent your site from being used to test cards we strongly suggest that you use a Captcha. If you prefer to have Qualpay manage your reCaptcha inside the Embedded Fields frame you can edit settings by logging into Quapay Manager, then clicking on "Administration" then "Settings" and toggling Google V3 Recaptcha to "Off" or "On".

Success Handling

A success handler function is required to load the Qualpay Embedded fields. The success handler is called after the card is successfully tokenized and a card_id is generated. The card information is passed as a parameter to the callback function as a JSON object. You can include the logic here to make payment from your servers using the card_id. The structure of the JSON object is as follows:

Fixed length, 32 AN
A single use card_id that can be utilized in a Qualpay payment gateway request to make a payment, authorization, verification or tokenization. This id will be valid for 10 minutes after creation. The card_id will not be valid once it is used in a gateway request. If the tokenize flag is set to true in request, the card_id will be stored in vault.
Variable length up to 16 AN
Masked account number.
Fixed length, 4N
Expiration date of cardholder card number in MMYY format. Applicable only for credit cards.
Variable length up to 2 AN
Card type. Refer to card Type for a list of card types.
Fixed length, 1 AN
Bank account type. Applicable only for ACH payments. Possible values are: C = Personal checking account S = Personal savings account K = Business checking account V = Business savings account
Status code from the Hosted Field submission. Refer to 'Response Codes' section for possible values.
Variable length AN
Short description of status. Possible value is 'success'
JSON array
Detailed success message
Sample success object

Error Handling

An onError Callback function is optional. It can be used to handle errors. The error JSON object is passed as a parameter to the callback function. The structure of the JSON object is as follows:

Variable length, up to 6 AN
Error code from the Hosted Field submission.
Variable length AN
Error Message short description.
JSON array
Detail array of error messages.
Sample error object


Start transacting at

Have a question? Click the chat button in the bottom right or email us at

Go Live

Contact your sales representative or apply now for your production account.

Alternatively, sign up for our Partner Program, so you and your customers can take advantage of Qualpay's integrated payments and boarding process, designed to support all the different ways you onboard your customer.

Once you have received approval for your production account, log into Qualpay Manager and retrieve your production keys from the Administration section.

Start transacting at