Hosted fields — payment.js

Hosted fields are a payment processing option provided by IXOPAY platform that allows merchants to embed a payment form within their own checkout page. With hosted fields, sensitive cardholder data is securely hosted and processed by the IXOPAY platform, while the merchant maintains control over the design and customization of their checkout page.

Guide

For a detailed, step-by-step guide on integrating payment.js, refer to the payment.js guide in our guides section.

Use cases

• Online retailers who want to provide a seamless and secure checkout experience for their customers.
• E-commerce platforms and marketplaces that require a consistent and branded checkout process across multiple sellers.
• Businesses that need flexibility in styling and design of their payment form while ensuring compliance with PCI standards.

Processing flow

The processing flow for hosted fields with payment.js can be divided into two distinct flows: the standard flow and the flow with 3-D Secure authentication. You can switch between the two flows using the tabs below to explore the specific steps and differences involved in each process.

Standard flow

1. The customer initiates a purchase on the merchant's website.
2. 
   Merchant
   The merchant sets up and initializes payment.js, see Guides: Hosted fields — payment.js for a step-by-step guide.
3. The customer enters their card number and CVV to payment form. The fields for card number and CVV are rendered within small <iframe>s served by IXOPAY's PCI-compliant infrastructure.
4. The customer submits the checkout form, and the submission is intercepted by the IXOPAY platform. The card number and CVV are submitted to the IXOPAY platform tokenized.
5. 
   Merchant
   The IXOPAY platform tokenizes the card number and CVV and returns the one-time token to the merchant in the tokenize callback. The merchant temporarily stores the token, for example in a hidden <form> field.
6. 
   Merchant
   The merchant website triggers the final submission of the checkout data to their backend, including the token.
7. 
   Merchant
   The merchant sends a debit or preauthorize request to the IXOPAY platform, including the token in the transactionToken field.
8. The IXOPAY platform processes the request and sends a transaction request to the PSP.
9. The PSP processes the transaction and sends the result back to IXOPAY.
10. 
    Merchant
    The IXOPAY platform processes the PSP's response and, using the callbackUrl field, notifies the merchant via a callback to the URL provided in the initial API call. This callback includes the payment status and any relevant details.
    info

    The callback is sent concurrently while the response to the debit or preauthorize request is still pending.

11. 
    Merchant
    The merchant handles the callback; additionally, it is recommended to store the transaction's uuid for future use.
12. 
    Merchant
    The merchant responds to the callback with:
    Callback response

    HTTP/1.1 200 OK
    Content-Type: text/plain
    
    OK
13. The IXOPAY platform responds to the merchant backend with a request containing the status of the transaction, usually FINISHED, PENDING or ERROR.
14. 
    Merchant
    The merchant decides what page to display to the customer depending on the transaction status.

Here's a visual representation of the processing flow using a sequence diagram:

3D-Secure flow

1. The customer initiates a purchase on the merchant's website.
2. 
   Merchant
   The merchant sets up and initializes payment.js, see Guides: Hosted fields — payment.js for a step-by-step guide.
3. The customer enters their card number and CVV to payment form. The fields for card number and CVV are rendered within small <iframe>s served by IXOPAY's PCI-compliant infrastructure.
4. The customer submits the checkout form, and the submission is intercepted by the IXOPAY platform. The card number and CVV are submitted to the IXOPAY platform tokenized.
5. 
   Merchant
   The IXOPAY platform tokenizes the card number and CVV and returns the token to the merchant in the tokenize callback. The merchant temporarily stores the token, for example in a hidden <form> field.
6. 
   Merchant
   The merchant website triggers the final submission of the checkout data to their backend, including the token.
7. 
   Merchant
   The merchant sends a debit or preauthorize request to the IXOPAY platform, including the token in the transactionToken field.
8. The IXOPAY platform sends a verification request to the 3-D Secure Merchant Plug-In (MPI). The verification request is transparently handled in the background and sent along to the 3-D Secure directory server and access control server.
9. The MPI responds with the 3-D secure status of the card and based on the connector settings the IXOPAY platform decides how to handle it.
10. 
    Merchant
    The IXOPAY platform sends the result with a 3-D Secure redirect URL to the merchant.

    {
      "success": true,
      // ...
      "returnType": "REDIRECT",
      "redirectUrl": "https://gateway.ixopay.com/redirect/d94c0d72f3a36e21f16e/ABCDEF01234567890ABCDEF01234567890",
      "redirectType": "fullpage"
    }
11. 
    Merchant
    The merchant redirects the customer's browser to the provided 3-D Secure redirect URL, switching temporarily to the bank's 3-D Secure verification page. This can be done on the backend by responding to the customer with an HTTP redirect using a Location HTTP header or on the frontend by setting the browser's window.location.
12. The customer's browser loads the banks 3-D secure verification page.
13. The bank delivers the 3-D secure verification page.
14. The customer follows the 3-D secure verification process. The exact method of verification and flow depends on the customer's bank. At the end of the flow the customer receives a payment authentication response.
15. The payment authentication response is sent to the IXOPAY platform
16. The IXOPAY platform processes the request and sends a transaction request along with the payment authentication response to the PSP.
17. The PSP processes the transaction and sends the result back to IXOPAY.
18. 
    Merchant
    The IXOPAY platform processes the PSP's response and notifies the merchant by a callback to the URL provided by the merchant in the initial API call via the callbackUrl field. This callback includes the payment status and any relevant details.
    info

    The callback is sent concurrently while the response to the debit or preauthorize request is still pending.

19. 
    Merchant
    The merchant handles the callback; additionally, it is recommended to store the transaction's uuid for future use.
20. 
    Merchant
    The merchant responds to the callback with:
    Callback response

    HTTP/1.1 200 OK
    Content-Type: text/plain
    
    OK
21. The IXOPAY platform redirects the customer to the merchants successUrl, cancelUrl or errorUrl, depending on the status of the transaction.
    info

    If the payment is in status PENDING the user will still be redirected to the success page in successUrl.

22. The customer's browser loads the merchants response URL.
23. 
    Merchant
    The merchant displays the appropriate thank-you or error page based on the payment status received in the callback.

Here's a visual representation of the processing flow using a sequence diagram:

See also

• Guides: Hosted fields — pamyment.js – a detailed walkthrough on how to integrate payment.js into your application, with code examples.