---
title: "Create Hosted Fields session"
method: POST
path: "/processing-terminals/{processingTerminalId}/hosted-fields-sessions"
tags: ["hostedFields"]
---

# Create Hosted Fields session

`POST /processing-terminals/{processingTerminalId}/hosted-fields-sessions`

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/take-payments/hosted-fields).

## Path parameters

- `processingTerminalId` string, required

## Headers

- `Authorization` string, required
- `Idempotency-Key` string, uuid, required

## Request body

- HostedFieldsCreateSessionRequest — Object that contains information about Hosted Fields initialization request.
  - `libVersion` string, required — Version of the Hosted Fields JavaScript library that you are using. The current production version is `1.7.0.261471`.
  - `scenario` 'payment' | 'tokenization', required — 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.
  - `secureTokenId` string — 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 `201`

Successful request. We created the session and returned a session token.

- HostedFieldsCreateSessionResponse
  - `processingTerminalId` string, required — Unique identifier that we assigned to the terminal.
  - `token` string, required — 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.
  - `expiresAt` string, date-time, required — 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.

## Other responses

- `400` — Validation error
- `401` — Identity could not be verified
- `403` — Do not have permissions to perform this action
- `406` — Not acceptable
- `409` — Conflict
- `415` — Unsupported media type
- `500` — An error has occured

---

[API](https://skmtc.dev/payroc/apis/schema.md) · [All operations](https://skmtc.dev/payroc/apis/schema/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/payroc/schema/revisions/1d9d3e305945/schema)