Mutual TLS
Use a Payvala-issued client certificate to identify your system when connecting to Payvala services.
On this page
Authentication Overview
Payvala API requests use multiple layers of authentication and security controls to protect access to Payvala services.
Depending on the API operation, authentication can include a Payvala-issued client certificate, an OAuth 2.0 access token, and HMAC request signing for transaction requests.
Authentication credentials must be securely managed and used only from trusted server-side systems.
OAuth 2.0
Use OAuth 2.0 Client Credentials to obtain a short-lived Bearer access token.
Request Signing
Transaction requests use HMAC-SHA256 signing to protect request integrity and verify the expected sender.
Authentication Credentials
Your Payvala integration uses the following credentials and security materials. Keep all private credentials protected and never expose them through client-side applications.
mTLS Client Certificate
A Payvala-issued certificate and private key used to identify your system. Access tokens are bound to the client certificate.
Master Key
MasterKeyId and MasterKeySecret are used when requesting OAuth access tokens using the client_credentials grant.
Access Key Pair
AccessKeyId and AccessKey are used for HMAC request signing. AccessKeyId is the public identifier while AccessKey is secret.
Authorization Code
AuthCode is generated through the Payvala portal or API and is used to classify and segment transactions.
Authentication Flow
A typical authenticated Payvala API request follows the steps below.
01
Connect over mTLS
Present your Payvala-issued client certificate when establishing the secure TLS connection.
02
Request an Access Token
Send the required credentials to the OAuth token endpoint using the client_credentials grant.
03
Call the API
Include the access token in the Authorization header. Transaction requests also include the required signing headers.
04
Reuse and Renew
Reuse the access token according to its returned expiry value and request a new token when it expires.
Access Token
Payvala uses OAuth 2.0 Client Credentials Grant to issue access tokens for authenticated API requests.
The access token is returned as a Bearer token and must be included in the Authorization header when calling secured APIs.
Authorization Header
Authorization: Bearer <access_token>Token Request
POST
/oauth/token| Field | Type | Required | Description |
|---|---|---|---|
AccessKeyId | String | Yes | Access key identifier issued by Payvala. |
AccessKey | String | Yes | Secret access key issued by Payvala. |
GrantType | String | Yes | Must be client_credentials. |
Token Response
| Field | Type | Description |
|---|---|---|
AccessToken | String | JWT access token used as a Bearer token. |
TokenType | String | Token type. Expected value is Bearer. |
ExpiresIn | Integer | Token lifetime returned by the API in seconds. |
Request Headers
Transaction requests require the access token and the request-signing headers described below.
Authorization
Bearer access token used to authenticate the API request. Never place the token in request payloads or logs.
x-access-key-id
The AccessKeyId associated with the secret key used to generate the request signature.
x-timestamp
The request timestamp represented using ISO 8601 format.
x-nonce
A unique UUID generated for each request.
x-signature
The HMAC-SHA256 signature generated from the required request values.
HMAC Signature
Transaction requests use HMAC-SHA256 signing to help verify the origin and integrity of the request.
01
Build the Signing Input
Concatenate the required values in the exact order defined by the signing rule.
02
Encode the Data
Encode the signing input using UTF-8.
03
Generate the Signature
Generate the HMAC-SHA256 digest using the AccessKey as the secret.
04
Send the Signature
Send the resulting lowercase hexadecimal signature in the x-signature header.
Signing Rule
HMAC_SHA256(accessKey, accessKeyId + requestId + txnId + timestamp + nonce + payload)Security Best Practices
Follow these practices when implementing and operating your Payvala integration.
Protect Private Keys
Store private keys and sensitive cryptographic material in an HSM or hardware-backed secrets manager.
Use Secure Configuration
Read credentials from environment variables or a dedicated secrets manager at application startup.
Never Hardcode Secrets
Never hardcode secrets or commit credentials to source control.
Protect Logs
Redact secrets, access tokens, private keys, and personal data from application and monitoring logs.
Rotate Credentials
Rotate credentials before expiry and maintain an overlap period to avoid integration downtime.
Synchronize System Time
Maintain accurate system time on systems that generate signed requests because timestamp validation can affect request acceptance.
Credentials Not to Expose
Authentication credentials must remain on trusted server-side systems and must never be exposed through client-side applications or public resources.
AccessKey
Never expose the secret AccessKey outside trusted server-side systems.
MasterKeySecret
Never expose the MasterKeySecret in source code, URLs, logs, or client-side applications.
Private Keys
Never expose private cryptographic keys, including the mTLS private key.
Access Tokens
Never expose OAuth access tokens in browser code, URLs, error messages, or logs.
Client-Side Applications
Do not place Payvala authentication credentials inside browser or mobile application code.
Public Repositories
Never commit authentication credentials or private keys to public or shared source repositories.