> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://ixopay.ferndocs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://ixopay.ferndocs.com/_mcp/server. # 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](https://documentation.ixopay.com/docs/guides/getting-started/accept-payments/payment.js "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](https://documentation.ixopay.com/docs/reference/features/3d-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 * 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](https://documentation.ixopay.com/docs/guides/getting-started/accept-payments/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`](https://documentation.ixopay.com/docs/reference/integration/payment.js/methods#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](https://documentation.ixopay.com/api/transaction/debit) or [preauthorize](https://documentation.ixopay.com/api/transaction/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 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: ```mermaid %%{ init: { "sequence": {"mirrorActors": false} } }%% sequenceDiagram accTitle: Sequence diagram for payment.js processing without 3-D Secure accDescr: A visual representation of the steps listed above. autonumber actor C as Customer participant M as Merchant participant G as IXOPAY platform participant PSP Note over C,PSP: Start transaction C-->>M: Purchase activate C M->>M: Setup & initialize payment.js C-->>C: Enter card number and CVV C-->>+G: payment.js tokenize() call G->>-C: Tokenize callback deactivate C Note over C,PSP: Submit form and show final page C->>+M: Purchase including token M->>+G: Debit including token G-->>+PSP: Transaction PSP-->>-G: Result par G-)+M: Callback to callback URL M->>M: Store result M->>-G: OK end G-->>-M: Result M->>-C: Thank-you or error page ``` 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](https://documentation.ixopay.com/docs/guides/getting-started/accept-payments/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`](https://documentation.ixopay.com/docs/reference/integration/payment.js/methods#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](https://documentation.ixopay.com/api/transaction/debit) or [preauthorize](https://documentation.ixopay.com/api/transaction/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. ```json { "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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Redirections) 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 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: ```mermaid %%{ init: { "sequence": {"mirrorActors": false} } }%% sequenceDiagram accTitle: Sequence diagram for payment.js processing with 3-D Secure accDescr: A visual representation of the steps listed above. autonumber actor C as Customer participant M as Merchant participant G as IXOPAY platform participant PSP Note over C,PSP: Start transaction C-->>M: Purchase activate C M->>M: Setup & initialize payment.js C-->>C: Enter card number and CVV C-->>+G: payment.js tokenize() call G->>-C: Tokenize callback deactivate C Note over C,PSP: Submit form C->>+M: Purchase including token M->>+G: Debit including token G-->>+PSP: 3-D Secure VeReq PSP-->>-G: 3-D Secure VeRes G->>-M: Result M-->-C: 3-D Secure redirect URL Note over C,PSP: 3-D Secure verification C-->>+PSP: GET 3-D Secure page PSP-->>-C: 3-D Secure page C-->PSP: 3-D Secure verification process Note over C,PSP: Process transaction C-->>+G: Submit 3-D Secure verification G-->>+PSP: Transaction PSP-->>-G: Result par G-)+M: Callback to callback URL M->>M: Store result M->>-G: OK end G-->>-C: Redirects back to successUrl, errorUrl or cancelUrl Note over C,PSP: Show final page C-->>+M: Get response URL M->>-C: Thank-you or error page ``` ## See also * [Guides: Hosted fields — payment.js](https://documentation.ixopay.com/docs/guides/getting-started/accept-payments/payment.js) – a detailed walkthrough on how to integrate payment.js into your application, with code examples.