IntegrateHosted Fields

Authenticate your Hosted Fields session

To authenticate your access to our gateway, you must include a session token every time you run the Hosted Fields script on your webpage. The following constraints apply to session tokens:

  • A session token expires after 10 minutes.
  • You can use a session token only once for each instance of Hosted Fields.

Integration steps

Step 1. Generate a Bearer token.
Step 2. Generate a session token from the Bearer token.
Step 2a. (Optional) Generate a session token to update a secure token.

Before you begin

Headers

To create the header of each POST request, you must include the following parameters:

  • 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.
$curl
>-H "Content-Type: application/json"
>-H "Authorization: <Bearer token>"
>-H "Idempotency-Key: <UUID v4>"

Errors

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

Step 1. Generate a Bearer token

Use our Identity Service to generate a Bearer token to include in the header of your requests.

To generate your Bearer token, include your API key in the x-api-key parameter in the header of a POST request, and then send it to our Identity Service.

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

Note: 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.

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 for each instance of Hosted Fields.

When you generate a session token, you need to specify the version of the Hosted Fields JavaScript library that you are using.

VersionNotes
1.6.0.172441Current production version
1.6.0.172429Current test version

Note: The version number is in the script tag of the config object.

Version number diagram

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

Step 2a. (Optional) Generate a session token to update a secure token

If you want to update a secure token, you also need to include the secureTokenId of the secure token that you want to update.

Request parameters

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.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 take a payment immediately. - `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.

Example request

POST
/v1/processing-terminals/:processingTerminalId/hosted-fields-sessions
1curl -X POST https://api.payroc.com/v1/processing-terminals/ \
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.6.0.172441",
7  "scenario": "payment"
8}'

Response fields

If your request is successful, our gateway creates 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.
expiresAtstringRequiredformat: "date-time"
Date and time that the token expires. We return this value in the ISO 8601 format.

Example response

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