Hosted fields — payment.js
payment.js is a flexible way to accept payments that requires programming knowledge. With payment.js, you have full control over the look and feel of your payment form, and the customer remains on your website during the payment process, rather than being redirected.
For more details on payment.js, check out the in-depth article on payment.js in the reference.
How to use payment.js
Step 1: Include payment.js
The first step is to prepare the checkout page on your website to use payment.js. Start by opening the checkout page’s source (where your customer enters their credit card number).
The following section guides you through the process of integrating payment.js step-by-step. To access the full sample code, see Appendix: Full code sample.
Load payment.js
To use payment.js, you have to load the provided JavaScript file. Include the script in <head> to optimize the browser’s resource loading. Load the file from https://gateway.ixopay.com/js/integrated/payment.1.3.min.js and make sure the attribute data-main="payment-js" is included in the <script>-tag.
- HTML
Define your payment fields
Add payment.js to your credit card <form>. payment.js handles the card number and CVV fields and will replace them with secure iframes.
Build the form with the following elements:
<input>elements for- Card holder name (or separate fields for first name and last name)
- Expiration year
- Expiration month
<div>or<span>elements for- Card number
- CVV
Make sure you have a way to easily access these fields in JavaScript, for example by assigning unique id-attributes.
Add an onsubmit handler to handle a user clicking submit. This intercept handler is responsible for tokenization of the credit card data.
- HTML
Initialize payment.js
After you have created your payment form, create a PaymentJs object and call init() to initialize payment.js. Add this code to the end of your page, so payment.js is already loaded and page rendering is not blocked.
The init() method requires these arguments:
- The
$INTEGRATION_KEYfrom Setting up your account — Create a connector.
To find the integration key for an existing connector.
- Navigate to the edit view of your connector.
- In the Base Data section on the left, find the entry called Public Integration Key (e.g. for payment.js).
- Click the button to reveal the key.
-
The
idof the card number element -
The
idof the CVV element -
Optional: A callback function to customize payment.js, see Style your hosted fields and Advanced form styling.
-
Javascript
Intercept form submit
Finally, when the user clicks on submit, we need to intercept the event and call tokenize(). We extract the required data from the <form> and pass it to payment.js. Then we register two callbacks to handle the success and error cases.
If tokenization is successful, we store the received token in the <form> and submit it to our backend. In the case of an error, add error handling to the error callback and display it to the customer.
- Javascript
Error handling
You need to inform the customer if any data they entered was invalid. To do that, add an implementation for the error hook of the tokenize() method.
The errors are described in detail in Error handling.
- Javascript
Step 2: Perform transaction
Now that we have successfully obtained the cc-token for the tokenized credit card, we can accept payment from the customer.
We refer to the transaction token received via the <form> submit cc-token as $CC_TOKEN in the following sample code.
To perform the transaction in your backend system, we need to create a transaction by sending a POST request to gateway.ixopay.com.
Here we choose a Debit transaction, which when successful, will immediately transfer funds. Depending on your business model a Preauthorize transaction - followed by a Capture transaction - might be more appropriate.
For details on how to authenticate API calls to the IXOPAY platform, see Authentication.
This is a minimal example. Include as much information as possible in the customer field. This reduces friction and provides the most benefit for risk checks, 3D-secure authentication and other validations.
- curl
- Python
- PHP
- Java
Step 3: Payment complete
Your backend system receives the response to the transaction call. For a successful transaction, display your checkout complete page to the customer.
Additionally, if you specify a callbackUrl in the Debit transaction request, the IXOPAY platform will send a callback with the status of the payment. For more information on how to set up and use callbacks, please see the callbacks page.
For details on how to handle unsuccessful transaction results, see Handling errors.
Sometimes 3D Secure authentication is required for credit card payments. For details on how to handle 3D Secure transaction results, see 3-D Secure.
Optional: Style your hosted fields
One of the benefits of payment.js is that it can be seamlessly integrated into your checkout process. This includes styling the payment form. Below is a sample of how to style the form created in this guide.
For more details on styling, see Form styling.
Code sample
- Javascript
Next steps
Now that you’ve integrated IXOPAY platform via hosted fields, you can look into …
- … testing your setup to make sure you’ve set up everything correctly.
- … handling changes to the payments status with callbacks.
- … recurring payments to generate recurring revenue.
- … making your code production-ready by handling errors.
- … getting more in-depth details about the payment.js features from the “Hosted fields — payment.js” reference.
Appendix: Full code sample
Code sample
- Javascript