Embedded Fields
Overview
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.
Features
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.
Customization
Maintain branding and complete control over the placement of Embedded Fields.
Security
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.
Integrate
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.
- Generate a transient key using Embedded Fields API. Refer to the API specification for help.
- Include the Qualpay javascript and css libraries in your html. The styling in the css library can be overridden to match your user interface or for responsiveness.
- Define a div container with id="qp-embedded-container" in your HTML. The embedded fields Iframe will be loaded within this div:
- Define success handler to process the card_id on form submission:
- Define the optional error handler routine to handle errors:
- Use the function qpEmbeddedForm.loadFrame() from the Qualpay SDK library to load the Iframe into your page, where merchantId is the Qualpay merchant id and configurationParam is a JSON object containing the configuration parameters required to set up the Embedded Fields.
- You can also use the qpEmbeddedForm.unloadFrame() helper function to clear the embedded iframe from your page after a successful payment.
Possible Configuration Parameters
*Note if any of the required fields are not present, the Embedded fields frame will not load.
formID
Variable length, required
The HTML 'id' of the form that will be submitted.
mode
String, optional, default is test
Possible values are "test" for Sandbox environment or "prod" for Production environment.
transientKey
Fixed length, 32 AN, required
Transient Key generated for use with Embedded fields. The key expires in 30 minutes.
tokenize
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.
onSuccess
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.
onError
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.
preSubmit
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.
achConfig
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.
cardConfig
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.
formFields
JSON, optional
By default the CVV is optional on the embedded fields. You can set it to be required using this field.
font
string, optional
Any font name listed on Google Fonts, can delimit with pipe (|) if more than one is needed.
style
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:
card_id
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.
card_number
Variable length up to 16 AN
Masked account number.
exp_date
Fixed length, 4N
Expiration date of cardholder card number in MMYY format. Applicable only for credit cards.
card_type
Variable length up to 2 AN
Card type. Refer to
card Type for a list of card types.
type_id
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
code
Numeric
Status code from the Hosted Field submission. Refer to 'Response Codes' section for possible values.
msg
Variable length AN
Short description of status. Possible value is 'success'
detail
JSON array
Detailed success message
JSON
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:
code
Variable length, up to 6 AN
Error code from the Hosted Field submission.
msg
Variable length AN
Error Message short description.
detail
JSON array
Detail array of error messages.
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 https://api-test.qualpay.com
