IntegrateHosted Fields

Set up Hosted Fields

Use Hosted Fields to create a form on a webpage that customers can use to create a single-use token. You can then use the single use token to complete the following actions:

  • Make a payment with a card or a bank account.
  • Save their payment details.
  • Update their payment details.

Before you begin

To integrate with Hosted Fields, you need the merchant’s processing terminal ID, and you need to generate a Bearer token to initialize our JavaScript library.

Session tokens

To authenticate each instance of Hosted Fields, create a session token each time you load Hosted Fields on a webpage.

To create a session token, see our Authentication with Hosted Fields guide.

Integration steps

Step 1. Add HTML for each payment type.
Step 2. Add and configure JavaScript.
Step 3. Handle the single-use token.
Step 4. Handle error events.

Step 1. Add HTML for each payment type.

Important: You can add only one set of Hosted Fields to a webpage.

  • Insert HTML for the type of payment form you want to create.
1<div class="card-container payroc-form">
2  <label for="card-holder-name">Cardholder Name</label>
3  <div class="card-holder-name"></div>
4  <div class="card-holder-name-error error-message"></div>
5  <label for="card-number">Card Number</label>
6  <div class="card-number"></div>
7  <div class="card-number-error error-message"></div>
8  <div class="cols-2">
9    <div class="col">
10      <label for="card-expiry">Expires (MM/YY)</label>
11      <div class="card-expiry"></div>
12      <div class="card-expiry-error error-message"></div>
13    </div>
14    <div class="card-cvv-wrapper">
15      <div class="col">
16        <label for="card-cvv">CVV</label>
17        <div class="card-cvv"></div>
18        <div class="card-cvv-error error-message"></div>
19      </div>
20    </div>
21  </div>
22  <div class="card-submit submit-button"></div>
23</div>

Note: For the card HTML, we added the col and col-2 custom CSS attributes to create the structure for the example form.

Step 2. Add and configure JavaScript

We provide you with different JavaScript configurations depending on the payment type and transaction type. The value for the mode parameter depends on whether you want to take a payment, save payment details, or update saved payment details:

  • payment - You want to run a sale or to run a sale and tokenize the payment details within the same transaction.
  • tokenization - You want to save the customer’s payment details to run a sale later, or you want to update payment details that the customer previously saved.

To add and configure JavaScript for Hosted Fields, complete the following steps:

  1. Insert the JavaScript configuration for the action that you want to use the single-use token for:
  • Run a sale.
  • Save a customer’s payment details.
  • Update payment details.
  1. In the sessionToken field, include your session token.

To test your integration in our UAT environment, use the following details in the JavaScript configuration:

ParameterValue
srchttps://cdn.uat.payroc.com/js/hosted-fields/hosted-fields-1.6.0.172429.js
integritysha384-1DFjPXzSRRPT56FXz1ptVP4pwzXPxeNQynxQpU7+5v++p+EbWGprq5TZl8qizGKs
1<script
2  src="https://cdn.payroc.com/js/hosted-fields/hosted-fields-1.6.0.172441.js"
3  integrity="sha384-e1tK2exEUnMhHQYhH2erv/sY3w8jzY/XnnBevNbv20VtjuJpcwb0u9h8qblYjrBl"
4  crossorigin="anonymous"
5></script>
6
7<script>
8  const cardForm = new Payroc.hostedFields({
9    sessionToken: YOUR_SESSION_TOKEN,
10    mode: "payment",
11    fields: {
12      card: {
13        cardholderName: {
14          target: ".card-holder-name",
15          errorTarget: ".card-holder-name-error",
16          placeholder: "Cardholder Name",
17        },
18        cardNumber: {
19          target: ".card-number",
20          errorTarget: ".card-number-error",
21          placeholder: "1234 5678 1234 1211",
22        },
23        cvv: {
24          wrapperTarget: ".card-cvv-wrapper",
25          target: ".card-cvv",
26          errorTarget: ".card-cvv-error",
27          placeholder: "CVV",
28        },
29        expiryDate: {
30          target: ".card-expiry",
31          errorTarget: ".card-expiry-error",
32          placeholder: "MM/YY",
33        },
34        submit: {
35          target: ".submit-button",
36          value: "Pay Now",
37        },
38      },
39    },
40  });
41  cardForm.initialize();
42</script>
1<script
2  src="https://cdn.payroc.com/js/hosted-fields/hosted-fields-1.6.0.172441.js"
3  integrity="sha384-e1tK2exEUnMhHQYhH2erv/sY3w8jzY/XnnBevNbv20VtjuJpcwb0u9h8qblYjrBl"
4  crossorigin="anonymous"
5></script>
6
7<script>
8  const cardForm = new Payroc.hostedFields({
9    sessionToken: YOUR_SESSION_TOKEN,
10    mode: "tokenization",
11    fields: {
12      card: {
13        cardholderName: {
14          target: ".card-holder-name",
15          errorTarget: ".card-holder-name-error",
16          placeholder: "Cardholder Name",
17        },
18        cardNumber: {
19          target: ".card-number",
20          errorTarget: ".card-number-error",
21          placeholder: "1234 5678 1234 1211",
22        },
23        cvv: {
24          wrapperTarget: ".card-cvv-wrapper",
25          target: ".card-cvv",
26          errorTarget: ".card-cvv-error",
27          placeholder: "CVV",
28        },
29        expiryDate: {
30          target: ".card-expiry",
31          errorTarget: ".card-expiry-error",
32          placeholder: "MM/YY",
33        },
34        submit: {
35          target: ".submit-button",
36          value: "Submit",
37        },
38      },
39    },
40  });
41  padForm.initialize();
42</script>
1<script
2  src="https://cdn.payroc.com/js/hosted-fields/hosted-fields-1.6.0.172441.js"
3  integrity="sha384-e1tK2exEUnMhHQYhH2erv/sY3w8jzY/XnnBevNbv20VtjuJpcwb0u9h8qblYjrBl"
4  crossorigin="anonymous"
5></script>
6
7<script>
8  const cardForm = new Payroc.hostedFields({
9    sessionToken: YOUR_SESSION_TOKEN,
10    mode: "tokenization",
11    fields: {
12      card: {
13        cardholderName: {
14          target: ".card-holder-name",
15          errorTarget: ".card-holder-name-error",
16          placeholder: "Cardholder Name",
17        },
18        cardNumber: {
19          target: ".card-number",
20          errorTarget: ".card-number-error",
21          placeholder: "1234 5678 1234 1211",
22        },
23        cvv: {
24          wrapperTarget: ".card-cvv-wrapper",
25          target: ".card-cvv",
26          errorTarget: ".card-cvv-error",
27          placeholder: "CVV",
28        },
29        expiryDate: {
30          target: ".card-expiry",
31          errorTarget: ".card-expiry-error",
32          placeholder: "MM/YY",
33        },
34        submit: {
35          target: ".submit-button",
36          value: "Submit",
37        },
38      },
39    },
40  });
41</script>

Step 3. Handle the single-use token

After the customer submits their payment details, our gateway tokenizes them and returns a single-use token. To access the single-use token, you need to subscribe to the submissionSuccess event. You can then use the single-use token in follow-on actions.

To subscribe to the submissionSuccess event, add an event listener to the form. For example:

1cardForm.on("submissionSuccess", ({ token, expiresAt }) => {
2	 
3});

Response

The event response contains the following fields:

FieldDescription
tokenSingle-use token that represents the customer’s payment details.
expiresAtExpiry date and time of the single-use token.

Example response

1{
2  "token": "c96cb928e39c34bd05022cd821d2cbba2349f047ce0cef4f77cd2b5762be7608fb7c23e673bf014d58c64672928eb8256e38aa26911a22853143d22dd48ac9aa",
3  "expiresAt": "2024-05-18T23:17:34.844Z"
4}

Step 4. Handle error events

To help you identify and fix any errors that you might encounter when using Hosted Fields, subscribe to our error event. To subscribe to the error event, add an event listener to the form. For example:

1cardForm.on("error", ({ type, field, message }) => {
2  
3});

For more information about the error event, go to Error Event.