Authentication guide

This guide describes how you can obtain an access token with the Oauth API. You need the access token to call the PagoNxt APIs.

PagoNxt APIs uses access tokens to make sure that only applications authorized and approved can access API operations.

Although every API call requires an access token, the type of the token depends on the API: When the API handles protected resources on behalf of the resource owner, a “JWT profile” access token is used. This means that the app needs to generate a JWT Bearer token to retrieve the access token. The JWT Bearer token is used to identify the resource owner.

To obtain the access token to call API endpoints, which are protected with OAuth 2.0 JWT Bearer grant, you must first create a JWT Bearer token and then use it to request the JWT profile access token.

📘 The PagoNxt APIs are in constant development. As such, an API may only have certain environments available.

Introduction to authentication

Introduction to authentication Access tokens are requested from a separate authentication API and are obtained by authorization and authentication:

Authorization is the process of verifying that you have access to the resource that you are requesting, in this case, the PagoNxt API. Authentication is the process of verifying your identity.

These steps are needed to ensure that only approved applications can access an API, and that they can only access the resources they are permitted to access.

When requesting an access token for the PagoNxt APIs, you send a JWT Bearer token as part of a request to the Oauth API.

The JWT Bearer token is used by the Oauth API to verify your identity and, based on this information, the API confirms whether you are allowed to access the API. If the authorization and authentication steps are successful, the Oauth API provides you with an access token to use in API requests.

The following figure shows the authentication process for the One Trade APIs, where a client application requests an access token from the Oauth API and uses it in a request to the API.

Create a JWT Bearer token

A JWT Bearer token is included in the request body of an access token request. It allows One Trade to confirm the identity of the request sender and to check that they are permitted to access the API.

In the Sandbox Lite environment, you do not need to create or sign your own tokens for authentication. Instead, you must use the following predefined JWT Bearer token in your access token request:

eyJhbGciOiJSUzI1NiIsImtpZCI6InByb0d0c1RyYWRlSW50ZXJuZXQiLCJ0eXAiOiJKV1QifQ.eyJpYXQiOjE2Nzk5OTYwNTMsImV4cCI6MTY5Mjk1NjA1MywibmJmIjoxNjc5OTk2MDUzLCJpc3MiOiI3Yzg2MGM1Zi02YTAyLTQ4OTUtYjNlMi1hZWQzYzJlOWU2ZDEiLCJzdWIiOiI3Yzg2MGM1Zi02YTAyLTQ4OTUtYjNlMi1hZWQzYzJlOWU2ZDEiLCJhdWQiOiJwYWdvbnh0IiwianRpIjoiODllNzI2NGEtYWE1OC00YmUwLTk4OGUtMWRhYTkyZWRhYTg0In0.OxsRwXYGGrur8Q-9Ink_qCP3aHRYEqt7akaR8TPmpG2wXoYTucYldjS21be3Pg-QqYN8OKeR-9x1x4Sxn2N1xoNUpQ8IBGgFlAxmf2wSsw9YAvzsWNWERR2SgFw7DiXZbPIJZV0RArzNY1o8dI053izzO3A0iy_EfbMkU-6Ix0l26jd8w0OfImOttRwv7GpHROqYQg3Eq3yjSzPbWYKb9n68EITQQODoIeYYuJ_UGTkZo5MlH9qP92wVGheRHlFfbtDKrULJ5ta3IbXIR9nr73wJ1uGoYqdp5yotcUeD4ZT5W0RhHZ4OWoQIKCRGxuR4dndGPUNKu9CariZc_dVUlw

Obtaining an access token

This section describes how to obtain the access token via an HTTP authentication request to the Oauth API. It also illustrates a successful response.

POST https://sandbox.onetrade.api.pagonxt.com/oauth/token

The request must contain the following headers:

Header Name	Description	Required / Optional	Values
Content-Type	Format of the request body	Required	application/x-www-form-urlencoded
Accept	Format of the response body	Required	application/json

📘

📘 The access token request does not use the Authorization header

The body must include the key-value pairs as shown in the following code:

The request must include the x-www-form-urlencoded key-value pairs shown in the following table:

Key	Description	Data type	Required / Optional
grant_type	Access token grant type (Client credentials)	String	Required
scope	Scope of the access token. To provide multiple scopes, the values must be separated by a space. For a list of possible values, please refer to the specific APIS.	String	Required
client_assertion_type	Authorization token grant type (JWT Bearer token)	String	Required
client_assertion	Predefined JWT bearer token from the previous step.	String	Required

An example body can be seen:

{
  "grant_type": "string",
  "scope": "",
  "client_assertion_type": "...",
  "client_assertion": "..."
}

If the request is valid, you receive an HTTP 200 OK response, which means that an access token was successfully issued.

For further details of HTTP response codes and instructions on how to handle errors, see HTTP codes and request error handling.

In addition to the response code, the response body returns an access token.

{
  "access_token": "ebd5a47a-c792-4a70-881d-ae94973cac47-IE",
  "token_type": "bearer",
  "expires_in": 3599,
  "scope": "accounts.create accounts.read accounts.update accounts.close transactions.read paymentcamt056.create paymentcamt029.read paymentpacs002.read paymentpacs002-id.read paymentpacs008.create paymentpacs008.simulate"
}

You’ll need access_token key for calling following APIs