SchemaPaymentsHosted Fields

Create Hosted Fields session

Use this method to create a Hosted Fields session token. You need to generate a new session token each time you load Hosted Fields on a webpage. In your request, you need to indicate whether the merchant is using Hosted Fields to run a sale, save payment details, or update saved payment details. In the response, our gateway returns the session token and the time that it expires. You need the session token when you configure the JavaScript for Hosted Fields. For more information about adding Hosted Fields to a webpage, go to [Hosted Fields](https://docs.payroc.com/guides/integrate/hosted-fields).

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path Parameters

processingTerminalIdstringRequired>=4 characters<=50 characters
Unique identifier that we assigned to the terminal.

Headers

Idempotency-KeystringRequiredformat: "uuid"
Unique identifier that you generate for each request. You must use the [UUID v4 format](https://www.rfc-editor.org/rfc/rfc4122) for the identifier. For more information about the idempotency key, go to [Idempotency](https://docs.payroc.com/api/idempotency).

Request

This endpoint expects an object.
libVersionstringRequiredformat: "^\d{1,2}.\d{1,2}.\d{1,2}(?:-beta)?.\d+$"

Version of the Hosted Fields JavaScript library that you are using.

The current production version is 1.6.0.172441.

scenarioenumRequired
Indicates if a merchant wants to take a payment or tokenize a customer's payment details: - `payment` - The merchant wants to run a sale or run a sale and tokenize in the same transaction. - `tokenization` - The merchant wants to save the customer's payment details to take a payment later or to update a customer's payment details that they've already saved.
Allowed values:
secureTokenIdstringOptional>=1 character<=200 characters
Unique identifier that represents a customer's payment details. If a merchant wants to update a customer's payment details that are linked to a secure token, include the secureTokenId in your request.

Response

Successful request. We created the session and returned a session token.
processingTerminalIdstring
Unique identifier that we assigned to the terminal.
tokenstring
Token that our gateway assigned to the Hosted Fields session. Include this session token in the config file for Hosted Fields. The session token expires after 10 minutes.
expiresAtdatetime
Date and time that the token expires. We return this value in the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.

Errors