Authorization

Every request to our systems must be properly authorized.

Authorization is handled via OAuth 2.0.

OAuth 2.0 is a system that allows applications to securely access actions on our server without needing to share passwords. Your system logs in using an access key (access token).

Generate an access token

To obtain an access token, send a POST request with content type application/x-www-form-urlencoded to the endpoint:

https://api.tpay.com/oauth/auth

Check the details in the API Reference documentation: POST /oauth/auth

In the request, specify the following parameters:

client_id *	Client identifier.
client_secret *	Client secret.

* Fields required.

You can generate these parameters in the Merchant Panel.

Go to the Merchant Panel and select Integration > API.
In the Open API Keys section, click Add new key.
Copy the generated key and secret, then save them in a secure place — the password for the newly created key is only visible when first generated.

Store authorization data securely

Securely storing the access key (token) is crucial for protecting your systems and payments. Here are a few best practices to follow:

Avoid storing in code::

Never store keys directly in application code, especially in files that might be publicly accessible (e.g., code repositories).

Use environment variables::

Store keys in environment variables that can be read by the application at runtime but are not stored in the source code.

Encrypt keys::

Store keys in encrypted form.

Limit access::

Ensure that only authorized individuals and services have access to the keys. Configure appropriate access policies (IAM policies) in your infrastructure.

Rotate keys regularly:

Change the key regularly to minimize the risk of leaks. Ensure that the rotation process does not disrupt the application’s operation.

Monitor usage:

Monitor the use of access keys to detect and respond to suspicious activity.

Use secure libraries and tools:

Use well-regarded libraries and tools for managing and storing keys, which are regularly updated and reviewed for security.

Request an OAuth token

To create an authorization token, send a POST request to the endpoint:

https://api.tpay.com/oauth/auth

Check the details in the API Reference documentation: POST /oauth/auth

In the request, specify the following parameters:

client_id *	Client identifier.
client_secret *	Client secret.

* Fields required.

Example:

curl -X POST https://api.tpay.com/oauth/auth -d 'client_id=testclient&client_secret=testpass'

Example response:

{
  "issued_at": 1718215429,
  "scope": "read",
  "token_type": "Bearer",
  "expires_in": 7200,
  "client_id": "01HH1N1V033B5FMB6TXPWZVATY-01J06SX1HPPFG0D8907TWBG871",
  "access_token": "3a06d08eb804f8bb4a8b2c82bf14c15cbae79ef6"
}

Response parameters:

issued_at *	The timestamp (in Unix format) indicating when the token was generated. This value represents the number of seconds since January 1, 1970 (UTC).
scope *	The scope of permissions granted to the token. In this case, the token allows for data reading (read).
token_type *	The type of token used for authorization. A Bearer token means that the application can access resources by passing this token in the HTTP Authorization header.
expires_in *	The token's validity period in seconds. In this case, the token will expire after 7200 seconds (2 hours) from its generation.
access_token *	The access token used for authorization. This token must be passed in the HTTP Authorization header in the format: Bearer <access_token>.

* Fields that always appear in the response body.

Note

The access token should be stored in the application and used to authorize requests until it expires.
The token is valid for the period specified in the expires_in parameter (by default, 2 hours).
After the token expires, the application should obtain a new token. It is important not to attempt to obtain a new token with every request but to rely on the already generated token until it expires.
The token’s validity period may change, so it is important to manage its storage and renewal appropriately.