An API version is a stable contract between your integration and Payvala. It defines how requests must be structured, how responses are shaped, which validation rules are enforced, and how each resource behaves. As long as your integration stays on a given version, that contract does not change in ways that would break your code.

Versioning exists because payment integrations are long-lived and operationally sensitive. A change to a field type, a new required parameter, or a stricter validation rule can cause failed payments, broken reconciliation, or rejected webhooks in production. Versions let Payvala evolve the platform while you decide when to adopt changes that affect your integration.

Each version covers the following parts of the contract:

Every API request is evaluated against a specific API version. The version determines which request schema is validated, which response schema is returned, and which behavior rules are applied. Two integrations calling the same endpoint on different versions can receive differently shaped responses.

The version is selected by the client on each request. Common mechanisms in REST APIs include a request header, a URL path segment, or an account-level default. The exact mechanism for Payvala must be confirmed and documented here. The examples below use placeholders and do not represent a confirmed Payvala implementation.

In general, version selection follows this order: the version supplied on the request is used if present; otherwise, a configured default for the account applies, if one exists. Explicitly setting the version on every request is recommended so that behavior never depends on implicit defaults.

curl -X POST "<BASE_URL>/payments" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "<VERSION_HEADER_NAME>: <API_VERSION>" \
  -d '{
    "amount": 1000,
    "currency": "INR",
    "reference": "order_10045"
  }'

curl -X POST "<BASE_URL>/<API_VERSION>/payments" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "INR",
    "reference": "order_10045"
  }'

const PAYVALA_CONFIG = {
  baseUrl: "<BASE_URL>",
  apiVersion: "<API_VERSION>",
};

async function payvalaRequest(path: string, body: unknown) {
  const response = await fetch(PAYVALA_CONFIG.baseUrl + path, {
    method: "POST",
    headers: {
      "Authorization": "Bearer " + process.env.PAYVALA_API_KEY,
      "Content-Type": "application/json",
      "<VERSION_HEADER_NAME>": PAYVALA_CONFIG.apiVersion,
    },
    body: JSON.stringify(body),
  });
  return response.json();
}

A version identifier is the string your integration sends to select an API version. APIs typically use one of two formats. The format Payvala uses must be confirmed; both are shown here for explanation only.

With major-version identifiers (for example v1 or v2), a new identifier is issued only when breaking changes are introduced. Non-breaking changes are added to the existing version without changing the identifier.

With date-based identifiers (for example 2026-01 or 2026-07), each identifier marks the point in time at which the API contract was fixed. A new identifier is released when breaking changes are introduced, and the date indicates which contract applies.

{
  "payvala": {
    "baseUrl": "<BASE_URL>",
    "apiVersion": "<API_VERSION>",
    "environment": "sandbox"
  }
}

The version you should use depends on the state of your integration and the lifecycle status of the version. Use the table below to decide.

Backward compatibility means that an integration written against a version continues to work when Payvala releases changes within that same version. Payvala may add capabilities to a version without notice, provided existing requests and responses continue to behave as documented.

Compatibility depends on how your code consumes the API. A new optional response field is compatible only if your client ignores fields it does not recognize. Clients that use strict schema validation or fail on unknown properties may break on changes that are compatible by design.

The table below classifies common changes. 'Usually No' means migration is normally unnecessary but your client should be verified against the change.

A breaking change is any change that can cause a correctly written integration on a previous version to fail or behave incorrectly. Breaking changes are released only in a new API version and are never applied to a version you are already using.

The following categories are treated as breaking: removed fields, renamed fields, changed field types, new required parameters, changed validation rules, changed response structures, changed authentication requirements, and changed resource behavior.

{
  "id": "pay_123",
  "amount": 1000
}

{
  "id": "pay_123",
  "amount": {
    "value": 1000,
    "currency": "INR"
  }
}

// Before
{ "customer_ref": "cus_88" }

// After
{ "customer_id": "cus_88" }

// Before: valid request
{
  "amount": 1000,
  "currency": "INR"
}

// After: reference is now required
{
  "amount": 1000,
  "currency": "INR",
  "reference": "order_10045"
}

// Before: reference up to 255 characters accepted
// After:  reference limited to 40 characters

// Request that is now rejected
{
  "reference": "a-very-long-order-reference-that-exceeds-the-new-limit-0001"
}

Every API version moves through a defined lifecycle: Current, Supported, Deprecated, Sunset, and Retired. The status of each version is published in the Version Change History.

1. Current

   The latest released version and the one recommended for new integrations.

   What to do: Use for new integrations. Adopt new capabilities as needed.

2. Supported

   A previous version that remains fully maintained, with security and critical fixes.

   What to do: Continue using. Review the changelog and plan an upgrade at a convenient time.

3. Deprecated

   The version still works but is scheduled for removal on <SUNSET_DATE>. No new features are added.

   What to do: Begin migration planning immediately. Do not start new integrations on this version.

4. Sunset

   The version has reached its end-of-life date. Requests may be restricted or rejected.

   What to do: Complete migration. Production traffic on this version is at risk.

5. Retired

   The version is permanently removed and no longer served.

   What to do: No action possible on this version. Requests will fail.

Upgrading is a planned change, not a configuration toggle. Follow this workflow to reduce risk and keep production stable.

This guide walks through a migration from your current version to a target version. Migration follows this sequence: Current Version, Review Changelog, Compare API Contracts, Identify Breaking Changes, Update Code, Run Tests, Sandbox Validation, Production Migration.

// Request
POST <BASE_URL>/payments
<VERSION_HEADER_NAME>: <CURRENT_VERSION>

{
  "amount": 1000,
  "currency": "INR"
}

// Response
{
  "id": "pay_123",
  "status": "created",
  "amount": 1000
}

// Request
POST <BASE_URL>/payments
<VERSION_HEADER_NAME>: <API_VERSION>

{
  "amount": 1000,
  "currency": "INR",
  "reference": "order_10045"
}

// Response
{
  "id": "pay_123",
  "status": "created",
  "amount": {
    "value": 1000,
    "currency": "INR"
  }
}

// Before
const amount: number = payment.amount;

// After
const amount: number = payment.amount.value;
const currency: string = payment.amount.currency;

Deprecation and sunset communicate when a version will stop working. Understanding the difference helps you plan migration before production is affected.

Review the change history before upgrading. Each entry lists the release status, the date, a summary of changes, and whether migration is required.