Take paymentsHosted Fields

Authenticate your session

View as Markdown

An AI skill is available for this guide, get it on the Skills Marketplace (GitHub).

To authenticate your access to the Payroc gateway, include a session token every time you run the Hosted Fields script on a webpage.

Before you begin

  • Make sure you have your API key for both the test environment and the production environment.
  • Make sure that your integration can handle errors. If a request is unsuccessful, we return an error that follows the RFC 7807 format. For more information about errors, go to Errors.

Integration steps

Step 1. Generate a Bearer token.
Step 2. Generate a session token from the Bearer token.

Step 1. Generate a Bearer token

Authenticate your requests to generate a Bearer token.

Step 2. Generate a session token from the Bearer token

You must use our Hosted Fields Sessions endpoint to generate a new session token each time you initialize Hosted Fields. A session token expires after 10 minutes.

When you generate a session token, you need to specify the version of the Hosted Fields JavaScript library that you are using. Include the version number in the libVersion parameter in the body of your request.

EnvironmentVersion
Test1.7.0.261457
Production1.7.0.261471

Request

To generate a session token, send a POST request to our Processing Terminals endpoint.

Include the following headers in your request:

  • Content-Type: Include application/json as the value for this parameter.
  • Authorization: Include your Bearer token in this parameter.
  • Idempotency-Key: Include a UUID v4 to make the request idempotent.

To create the body of your request, use the following parameters:

Request

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.7.0.261471`.
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.
secureTokenIdstringOptional1-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.

Example request

POST
/v1/processing-terminals/:processingTerminalId/hosted-fields-sessions
1curl -X POST https://api.payroc.com/v1/processing-terminals/1234001/hosted-fields-sessions \
2     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3     -H "Authorization: Bearer <token>" \
4     -H "Content-Type: application/json" \
5     -d '{
6  "libVersion": "1.1.0.123456",
7  "scenario": "payment"
8}'
Try it

Response fields

If your request is successful, our gateway generates a session token. The response contains the following fields:

Response

processingTerminalIdstringRequired
Unique identifier that we assigned to the terminal.
tokenstringRequired
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.
expiresAtdatetimeRequiredRead-only
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.

Example response

Response
1{
2  "processingTerminalId": "1234001",
3  "token": "abcdef1234567890abcdef1234567890",
4  "expiresAt": "2025-07-02T15:30:00.000+02:00"
5}