Widgets
Getting started with widgets for Number
Widgets are our legacy option to collecting cardholder data and payments. If you are just getting started with Number, we recommend using the PayForm instead.
A Number widget is a pre-made web form which can be used to collect cardholder data. They can be used to make instant payments and collect consent.
After the widget has been submitted, we will pass relevant data to you as a webhook.
Designing your widget
You can control the design of the form, the size, and the way data is populated and consumed. If you wish, you can also use the widget with standard options to make it as simple as possible.
Considerations and options
Is the widget going to be public-facing or practice-facing?
Do you need to collect cardholder information, make instant sales, or both?
What fields do you need to show to the user? (cardholder info...?)
What information do you want to pass in the background as a hidden field? (
ReferenceID, ...?)What fields should be pre-populated? (
Firstname,Lastname, ...?)What fields can be altered by the user, and what should be read-only? (
Address,Amount, ...?)How do you wish to POST the real-time values from the widget?
Redirect to the integrator site with encrypted values attached?
Have the widget contained in an iFrame and have it do a POST message to the parent page?
POST values to the integrator site without redirection, in the background?
Do you need to redirect to Number receipt page, or consent agreement page?
What should the widget be styled like? You can modify the size, colors, frame, etc.
You'll also need to know how you plan to use the widget in your workflow:
Embed the widget directly within your desktop or web application;
Direct your users to a dedicated top-level payment page;
Send the generated payment link directly to cardholders.
Using an IFrame vs full page
IFrame
An IFrame is a web container which can contain content from any domain. This has been an ideal method for our integrators to include a payment widget since it has become an integral part of their website. It creates an environment where the payment window becomes a part of the client site.
Loading an IFrame with Number's widget or PayForm gives you 100% isolation from Cardholder data. This provides excellent security and eliminates more costly PCI compliance programs.
Do note that our widget requires a session cookie. Extra steps are required to utilize the IFrame approach. For example, Safari will block cookies from an IFrame if the parent page does not share the same domain. To resolve this, a subdomain can be created and served on our web farm.
PayForms do not utilize session cookies, there are no issues loading them as IFrames. This makes them preferable to using the widget.
Full page
If you do not want to use an IFrame to host our payment widget, we can also develop a full-page payment display for you. You will open this page exactly the same as any widget (you may pre-populate some values as the page is opened).
Once the user submits the payment, we can POST real-time data to your site in a number of ways. Usually, we will simply redirect back to your site with some ECHO values which allow your application to pick up where it left off prior to payment.
We encourage integrators to design their own payment page if they so desire. You can supply HTML / CSS / JavaScript / jQuery for us to include and modify in our secure PCI Level One environment.
Creating your widget
To open your widget, first you need to create a string manifest that will eventually become an encrypted URL. There are two ways to create this manifest:
Using our widget builder tool.
Creating it yourself using your programming language of choice.
If you want to use advanced options such as dynamically pre-populating form data, you will need to program the widget manifest without the tool!
Widget builder tool
Use our widget builder tool to select various settings, options, and styles. The widget manifest and encrypted URL will be generated for you.
Programming the widget
If you need to open the widget with dynamic content, you will have to do some programming. This is also true if you need to consume real-time data after the widget is submitted.
If you only need a widget for users to submit payments and need no dynamic content or real-time postings, we can provide you with an encrypted URL to place in your product.
In order to open a widget for collecting credit card information, first you must create a widget manifest. This is a string which is has two components: Key and Inputs.
Key parameter
For Key, you need to enter your Number credentials. You can either use your account code and token or a session key. You can read more about those parameters in Authentication.
Examples:
Inputs parameter
For Inputs, you add parameters which can configure the widget, pre-populating the widget with values, directing us where to post the results, etc. Each parameter should be separated from its value and the following arguments by a pipe "|" symbol.
Example:
Here is a list of arguments you can use for Inputs:
MERCHID: An integer which represents one of your merchant records. You will get this information when you board new accounts.REFID: Any custom unique identifier to describe this particular cardholder or transaction. You can then query our database at a later time to find records based on this reference ID.FIRSTNAME: (optional)LASTNAME: (optional)ADDRESS1: (optional)ADDRESS2: (optional)CITY: (optional)STATE: (optional)ZIP: (optional)AMOUNT: For a one-time payment widget, the $ amount for the transaction.WTYPE: The type of widget to use. Use "P" for testing and contact Number for more details.REDIRECT: URL where we can POST the results of the widget submission.
When we POST the results of the widget to the redirect URL of your choice, if you are storing a card-on-file, we will provide information such as a ConsentID which will allow you to charge this card at a later time, and if you are collecting a payment, we will provide the TransactionID so that you may do operations such as voiding, etc.
Manifest encryption
Once you have developed your string manifest, you will now need to encrypt it using AES 256. You will be issued a unique encryption key when you begin to process live transactions. Until then, you are encouraged to use the Number development sandbox key.
Whenever you use this key, you will append the following to your encrypted URL, so that we know which encryption key you are using:
Make sure to swap the sandbox encryption key and EINDEX value when you switch to running a production environment!
In all cases, encrypt the above manifest and create two components:
an initialization vector (
I)an encrypted message (
M)
Gather the widget manifest and encrypt it. The final step is to create the URL using the template.
See examples below:
If you want to quickly test your encryption, you can use our encryption utility.
Getting real-time data
There are a few methods you can use to POST data to your product when the widget is submitted:
Provide a redirect URL in the string manifest to receive an encrypted message;
Provide a URL where we can POST values;
If you display the widget using an IFrame, you can choose a POST message to the parent page.
If you provided a redirect URL, we will POST data to your site as follows:
You will read the m and i values and decrypt using the same encryption scheme, and the same key you used to open the widget.
Replace any space ' ' characters with plus '+' characters prior to decrypting the base64 string. These can be altered during URL encoding.
Here is some typical decrypted data:
Additional processing with APIs
Having integrated the widget into your application, now that the cardholder data is in our system, you can use our APIs for additional processing. This includes charging consents, crediting payments, voiding transactions, and running reports.
To learn more, see our REST API guide.
Last updated
Was this helpful?
