Hosted Fields

Authenticate your session

View as MarkdownOpen in Claude

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

To authenticate your integration, you need to use a Bearer token. To generate a Bearer token, send your API key in a request to our Identity Service.

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

Request

To generate a Bearer token, Include your API key in a x-api-key header in a POST request to our Identity endpoint.

EndpointPrefixURL
Testidentity.uat.https://identity.uat.payroc.com/authorize
Productionidentity.https://identity.payroc.com/authorize

Example request

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

Response

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

FieldDescription
access_tokenValue for the Bearer token. Use this value in the Authorization header of your requests.
expires_inNumber of seconds that the token expires in.
scopeIndicates which services that the token covers.
token_typeType of access token.

Example response

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

1{
2  "access_token": "eyJhbGc....adQssw5c",
3  "expires_in": 3600,
4  "scope": "service_a service_b",
5  "token_type": "Bearer"
6}

Step 2. Generate a session token from the Bearer token

You must 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.
Allowed values:
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}