Payvala SDKs

• Available Released and documented.
• Coming soon Planned; not yet released.
• Unsupported No Payvala SDK. Use the REST API directly.

• Node.js

  Available

  Integrate Payvala APIs into Node.js server applications.

  Language

  JavaScript / TypeScript

  Package manager

  npm

  Package

  To be confirmed

  Version

  To be confirmed

  Minimum runtime

  To be confirmed

  Capabilities

  To be confirmed

  SelectedNode.js docs

• Java

  Available

  Integrate Payvala services into Java server applications.

  Language

  Java

  Package manager

  Maven

  Package

  To be confirmed

  Version

  To be confirmed

  Minimum runtime

  To be confirmed

  Capabilities

  To be confirmed

  Use JavaJava docs

• Python

  Coming soon

  The Payvala Python SDK is not released yet.

  Language

  Python

  Package manager

  pip

  Package

  To be confirmed

  Version

  To be confirmed

  Minimum runtime

  To be confirmed

  Capabilities

  To be confirmed

  Use PythonPython docs

• Go

  Coming soon

  The Payvala Go SDK is not released yet.

  Language

  Go

  Package manager

  Go Modules

  Package

  To be confirmed

  Version

  To be confirmed

  Minimum runtime

  To be confirmed

  Capabilities

  To be confirmed

  Use GoGo docs

npm install @payvala/<actual-package-name>

const <SdkModule> = require('@payvala/<actual-package-name>');

Before you begin

• Onboarded organization

  Your organization is registered in the Payvala portal (POEMS) and you have admin access.

• Payvala-issued mTLS client certificate

  Presented on every API call, including the OAuth token endpoint. Keep the private key in an HSM or hardware-backed secrets manager.

• Registered egress IPs

  Register your outbound IP addresses or CIDR ranges in POEMS, separately for Staging and Production.

• Credentials

  Master key credentials for tokens, an access key pair for request signing, and at least one authorization code.

• TLS 1.3 and network access

  Enforce TLS 1.3 with strict server certificate validation, and allow the payvala.com domain through your firewalls.

• Synchronized clock

  Enable NTP on every system that signs requests. Clock drift beyond the allowed tolerance causes requests to be rejected.

Replace placeholder package information with the details published for your selected SDK. Minimum language runtime versions are shown once confirmed.

How a request is authenticated

1. Step 1

   Connect over mTLS

   Present your client certificate on a TLS 1.3 connection.

2. Step 2

   Request an access token

   POST the master key credentials to /oauth/token. The token is a short-lived Bearer JWT.

3. Step 3

   Call the API

   Send the token in the Authorization header. Transaction requests also carry the signature headers below.

4. Step 4

   Reuse, then renew

   Cache the token for its 15-minute lifetime (ExpiresIn: 900), then request a new one.

HMAC_SHA256(accessKey, accessKeyId + requestId + txnId + timestamp + nonce + payload)

Environment variable names are suggestions used in these examples. They are not defined by Payvala or the SDK.

const client = new <ClientClass>({

  <environmentOption>: '<staging | production>',

  <masterKeyIdOption>: process.env.PAYVALA_MASTER_KEY_ID,

  <masterKeySecretOption>: process.env.PAYVALA_MASTER_KEY_SECRET,

  <accessKeyIdOption>: process.env.PAYVALA_ACCESS_KEY_ID,

  <accessKeyOption>: process.env.PAYVALA_ACCESS_KEY,

  // mTLS client certificate + private key: option names to be confirmed

});

Class and option names in angle brackets are placeholders until the official SDK API is published here.

1. 01

   Install

   Add the SDK for your language.

2. 02

   Configure credentials

   Load the credentials for one environment from your secrets store.

3. 03

   Initialize the client

   Create the client with your environment and credentials.

4. 04

   Call the API

   Request a token, then call an operation such as Send transaction notification.

5. 05

   Handle the response

   Check status and code. Handle errors as described below.

response = client.<sdkMethod>({

  <parameter>: <value>

})



// Check response.status and response.code before continuing.

The same call over plain HTTP

Until SDK method names are published, this shows the underlying token request using the documented endpoint and fields.

curl --request POST "https://stage-partner-service.payvala.com/oauth/token" \\

  --cert <CLIENT_CERT_FILE> --key <CLIENT_KEY_FILE> \\

  --header "Content-Type: application/json" \\

  --data '{

    "MasterKeyId": "<MASTER_KEY_ID>",

    "MasterKeySecret": "<MASTER_KEY_SECRET>",

    "GrantType": "client_credentials"

  }'

Only operations documented in the Payvala API are listed. SDK coverage per language is confirmed separately.

1. SDK method
2. HTTP method
3. API endpoint
4. Request
5. Payvala API
6. Response

{

  "MasterKeyId": "<MASTER_KEY_ID>",

  "MasterKeySecret": "<MASTER_KEY_SECRET>",

  "GrantType": "client_credentials"

}

{

  "code": <integer>,

  "status": true,

  "message": "<message>",

  "data": {

    "AccessToken": "<JWT>",

    "TokenType": "Bearer",

    "ExpiresIn": 900

  }

}

Values in angle brackets are placeholders. Field names and types come from the Payvala API specification.

1. Development
2. Staging
3. Production

• Development

  Your own machines and test infrastructure. Payvala does not publish a separate development host.

• Staging (also called Sandbox)

  Payvala-hosted environment for integration testing and certification.

  partner-service

  stage-partner-service.payvala.com

  api

  stage-api.payvala.com

• Production

  Live transaction processing, for approved integrations.

  partner-service

  partner-service.payvala.com

  api

  api.payvala.com

• Credentials, tokens, keys and certificates issued for Staging do not work in Production.
• Register egress IPs in POEMS separately for each environment.
• Keep configuration for each environment in separate secrets and deployment settings.
• Complete testing in Staging before enabling Production.