Use Hosted Fields to create a form on a webpage that customers can use 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.

Bearer tokens

We also refer to a Bearer token as an authToken or an access token.

To use our Identity Service to generate a Bearer token, complete the following steps:

Include your API key in the x-api-key parameter in the header of a POST request.
Send your request to https://identity.payroc.com/authorize.

You need to generate a new Bearer token before the previous Bearer token expires.

Example request

curl --location --request POST  'https://identity.payroc.com/authorize' --header 'x-api-key: <api key>'

Example response

If your request is successful, we return a response that contains your Bearer token, information about its scope, and when it expires.

{
"access_token": "eyJhbGc....adQssw5c",
"expires_in": 3600,
"scope": "service_a service_b",
"token_type": "Bearer"
}

If your request is unsuccessful, we return an error. For more information about errors, see Errors.

Integration steps

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

Step 1. Add and configure JavaScript

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

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:

Insert the JavaScript configuration for the action that you want to complete:

Run a sale.
Save a customer's payment details.
Update payment details.

In the processingTerminalId field, include your processingTerminalId.
In the authToken field, include your Bearer token.
(Optional) If you are updating the payment details represented by a secure token, include the secureTokenId that you want to update in the secureToken field.

Step 2. Add HTML for each payment type.

Insert HTML for the type of payment form you want to create.

Card

ACH

PAD

<div class="card-container payroc-form">
<label for="card-holder-name">Cardholder Name</label>
<div class="card-holder-name"></div>
<div class="card-holder-name-error error-message"></div>
<label for="card-number">Card Number</label>
<div class="card-number"></div>
<div class="card-number-error error-message"></div>
<div class="card-issue-number-wrapper">
<label for="card-issue-number" class="card-issue-number-label">Issue Number</label>
<div class="card-issue-number"></div>
<div class="card-issue-number-error error-message"></div>
</div>
<div class="cols-2">
<div class="col">
  <label for="card-expiry">Expires (MM/YY)</label>
  <div class="card-expiry"></div>
  <div class="card-expiry-error error-message"></div>
</div>
<div class="cvv-wrapper">
  <div class="col">
    <label for="card-cvv">CVV</label>
    <div class="card-cvv"></div>
    <div class="card-cvv-error error-message"></div>
  </div>
</div>
</div>
<div class="card-submit submit-button"></div>
</div>

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:

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

Response

The event response contains the following fields:

Field	Description
token	Single-use token that represents the customer's payment details.
expiresAt	Expiry date and time of the single-use token.

Example response

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

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:

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

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

Set up Hosted Fields

Example request

Example response

Run a sale

Save a customer's payment details

Update payment details