Configuration

Standardize client configuration for production-quality integration.

Recommended config structure

import { HsrcPay } from "@hsrcpay/sdk";

type Environment = "sandbox" | "production";

export function createHsrcPayClient(env: Environment) {
  return new HsrcPay({
    apiKey: env === "production" ? process.env.HSRCPAY_LIVE_KEY! : process.env.HSRCPAY_TEST_KEY!,
    environment: env,
    timeoutMs: 10_000,
    maxRetries: 2,
  });
}

Idempotency strategy

For retried write operations (such as create), use an idempotency key to prevent the same request from running twice. Even if confirm has no separate requirement, after a timeout check the existing record with payments.get instead of opening a new payment.

const payment = await hsrcpay.payments.create(
  { amount: 8900, currency: "TRY" },
  { idempotencyKey: "order_2026_04_03_00042" },
);

Request-level safeguards

• Generate a deterministic idempotencyKey for every write operation.
• Set timeouts by endpoint criticality instead of a single global timeout.
• Apply retry policy only for transient network/5xx errors.

Logging and observability

• Write fields such as request id (requestId) and paymentId into structured logs.
• On failed calls, store HTTP status, error code, and correlation id.
• Do not log personal data (PII) or card data.