PayTR Enterprise SDK handles payment-provider integration logic. Security issues can affect payment state, order fulfillment, merchant credentials, refunds, transfers, customer data, and operational continuity.

This policy defines supported versions, vulnerability reporting, required security invariants, secret handling, callback trust, financial-mutation safety, card-data boundaries, deployment expectations, and incident response.

Critical vulnerabilities affecting older versions may be assessed case by case, but the normal remediation target is the current supported release line.

Do not disclose sensitive vulnerabilities through a public issue when the report contains:

• live merchant credentials;
• working secret values;
• cardholder data;
• customer personal data;
• production callback payloads;
• active exploit details that would materially increase risk;
• infrastructure credentials or private network details.

Use the repository owner's private security-reporting channel or GitHub private vulnerability reporting when enabled.

A useful report should include:

1. affected version/commit;
2. affected runtime (ASP.NET, Node.js, or both);
3. vulnerability class;
4. prerequisites;
5. sanitized reproduction steps;
6. expected vs actual behavior;
7. realistic impact;
8. suggested mitigation if known;
9. whether production secrets/data were exposed;
10. whether active exploitation is suspected.

Never include unnecessary real payment data in a proof of concept.

Security reports should be triaged by impact.

Examples:

• callback signature bypass enabling fraudulent fulfillment;
• merchant key/salt exposure;
• unauthenticated refund/transfer execution;
• PAN/CVV persistence or broad exposure;
• remote code execution;
• credential disclosure through logs/API responses.

Examples:

• authentication bypass on privileged wrapper routes;
• duplicate financial mutation due to retry/idempotency defect;
• TLS verification disabled in production;
• unsafe Direct API default;
• sensitive data included in routine logs.

Examples:

• insufficient request limits;
• exploitable information disclosure without direct credential compromise;
• missing authorization layer in a deployment pattern;
• weak operational auditability that materially delays fraud response.

Examples:

• hardening opportunities with limited exploitability;
• non-sensitive metadata exposure;
• documentation defects that do not change runtime behavior.

The following are non-negotiable project invariants.

Never expose:

• merchant_key;
• merchant_salt;
• production internal API keys;
• secret-store credentials;
• private signing/encryption keys.

Do not place them in browser or mobile bundles.

A callback must not change order/payment state until its PayTR signature/hash has been verified using the exact provider formula implemented for that callback type.

Provider callbacks must be treated as at-least-once delivery. The production database must enforce idempotent processing.

merchant_ok_url, success pages, browser redirects, and client-side callbacks are user-experience mechanisms. They are not a substitute for an authenticated server-to-server notification.

Refunds, transfers, and similar operations must not be automatically repeated merely because a timeout or connection failure occurred.

Direct API remains disabled until merchant authorization, security review, and compliance scope are understood.

CVV/CVC must never be persisted.

Provider communication and public production payment endpoints must use correctly validated HTTPS appropriate to the deployment.

If the internal API key is not configured, privileged API routes must not become anonymous.

Public API responses must not include merchant secrets, raw signing material, stack traces, or sensitive provider/card data.

Committed configuration must contain empty/placeholders only.

Production values should be injected using an approved secret channel such as:

• managed secret store;
• CI/CD protected secret;
• orchestrator secret;
• process environment injected by a secure deployment system;
• machine/service identity retrieving secrets at runtime.

Rotate a credential immediately when:

• it is committed to Git;
• it appears in logs;
• it is sent in an insecure support channel;
• a developer workstation is compromised;
• a CI secret is exposed;
• unauthorized access is suspected.

Deleting the value from the latest Git commit is not sufficient if it existed in repository history.

Apply least privilege:

• production secrets should not be available to frontend build jobs;
• test environments should use separate credentials;
• developers should not receive production merchant secrets by default;
• logging/monitoring systems must not receive secrets;
• support operators should have only the access required for their role.

The runnable applications protect /api/v1/paytr/* and /api/v1/system/* with:

X-Internal-Api-Key: <secret>

This control is suitable as a simple service integration boundary but is not a complete authorization system for a multi-user product.

Production deployments should add, where appropriate:

• private network exposure;
• API gateway policy;
• mTLS;
• workload identity;
• OAuth2/OIDC service authorization;
• tenant/user authorization;
• operation-level roles;
• stronger approval for refund/transfer operations.

Do not expose privileged provider operations directly to untrusted browsers.

Provider callback endpoints must be reachable by PayTR and therefore cannot rely on the internal API key.

Trust comes from PayTR callback hash/signature validation.

The project uses constant-time comparison helpers where applicable. Do not replace them with ordinary string equality for security-sensitive hash comparison.

Callback endpoints should:

• accept only the required HTTP method;
• enforce a bounded body size;
• parse only the expected content type/fields;
• reject missing fields;
• verify the hash before business state change;
• avoid reflecting payload values in unsafe responses.

Use durable storage and uniqueness constraints. In-memory stores are example behavior only.

A valid duplicate callback should result in the same accepted business outcome without duplicate fulfillment.

Return the exact provider acknowledgement required by PayTR only after the callback has been safely accepted/applied according to your transaction design.

The reusable integration code is designed to keep merchant signing on the server and to avoid normalizing raw card details into generic backend DTOs.

If an integrating product collects/processes card data through Direct API:

• determine PCI DSS scope with qualified expertise;
• use only provider-approved flows;
• never log PAN/CVV;
• never store CVV/CVC;
• minimize card-data exposure across services;
• isolate payment-form code;
• restrict staff/system access;
• implement secure browser headers/CSP appropriate to the architecture;
• perform application security testing before production.

A code repository cannot certify PCI compliance. Compliance depends on the complete people/process/technology environment.

• Use HMAC-SHA256 where required by the implemented PayTR formula.
• Preserve exact field order.
• Preserve exact string/amount encoding.
• Base64-encode only at the step defined by the formula.
• Compare signatures in constant time.
• Never include secret-bearing raw HMAC inputs in logs.
• Add deterministic test vectors when formulas change.
• Never weaken signature verification to accommodate malformed test data.

A timeout can produce an unknown outcome. Do not automatically issue the same refund again without confirming provider state.

Recommended pattern:

1. persist refund intent/reference;
2. submit once;
3. record the immediate outcome when known;
4. mark ambiguous outcomes for reconciliation;
5. verify using provider status/reporting/merchant operations;
6. resolve manually when necessary.

Use the same conservative model for platform/returned transfer operations.

Where the business requires it, add:

• operator roles;
• approval thresholds;
• four-eyes approval;
• daily limits;
• destination allowlists;
• alerts for unusual behavior.

Validate before provider calls:

• merchant order identifiers;
• amounts;
• currency values;
• installment values;
• email/phone formats as represented by the protocol;
• URLs;
• BIN length/format;
• date ranges;
• link/transfer identifiers;
• request body size.

Do not rely on PayTR to be the first validation layer for user-controlled input.

Production requirements:

• valid HTTPS;
• TLS certificate validation enabled;
• no insecure provider base URL;
• bounded provider timeout;
• bounded request headers/body;
• secure forwarded-header trust configuration;
• HSTS where appropriate;
• controlled CORS;
• no wildcard credentialed CORS;
• no automatic proxy retry for financial mutations.

When behind a reverse proxy, trust forwarding headers only from known proxy infrastructure.

The application middleware provides a baseline. Depending on deployment/client behavior, evaluate:

• X-Content-Type-Options: nosniff;
• frame restrictions compatible with the payment flow;
• referrer policy;
• content security policy;
• HSTS;
• permissions policy;
• cache-control for sensitive responses.

Do not add a frame policy that breaks a required PayTR iFrame flow without testing the actual integration.

Production CORS should use exact trusted origins.

Do not use broad wildcard origins for privileged payment APIs.

Remember: CORS is a browser control, not authentication. A non-browser client can call an exposed API regardless of CORS.

The current servers include request-rate controls.

For production, tune limits based on:

• expected traffic;
• callback burst behavior;
• NAT/shared client IPs;
• gateway limits;
• operational endpoints;
• provider retry behavior.

Do not configure a rate limiter that causes valid PayTR callbacks to be persistently rejected during provider retries.

Additional controls can include:

• gateway throttling;
• WAF rules;
• IP reputation;
• endpoint-specific limits;
• anomaly detection.

• merchant key/salt;
• production internal API key;
• CVV/CVC;
• PAN;
• raw authorization/card payloads;
• secret-containing HMAC source strings;
• full unnecessary callback bodies.

Useful fields:

• correlation ID;
• merchant order ID;
• internal payment ID;
• operation;
• sanitized error code;
• latency;
• result category;
• reconciliation state;
• deployment version.

• callback signature failures;
• repeated unauthorized privileged-route attempts;
• refund/transfer unknown states;
• reconciliation backlog;
• abnormal provider error rate;
• readiness degradation;
• unusual transfer volume;
• security-scanner critical findings.

Classify stored data before production.

Apply:

• minimization;
• encryption at rest where appropriate;
• encrypted backups;
• least-privilege database access;
• retention/deletion policy;
• audit access control;
• separation of production and non-production data;
• legal/privacy requirements applicable to your business.

Do not copy production payment/customer records into development systems without approved anonymization and business/legal authorization.

Recommended controls:

• dependency update automation;
• CodeQL/static analysis;
• secret scanning;
• dependency vulnerability scanning;
• SBOM generation;
• signed/provenanced release artifacts;
• pinned or reviewed build actions;
• branch protection and required reviews.

A security scan is evidence, not proof of absence of vulnerabilities.

Production pipelines should:

• use least-privilege tokens;
• separate build and deployment permissions;
• protect production environments with approvals;
• avoid printing secrets;
• produce immutable artifacts;
• deploy the exact reviewed artifact;
• retain build/test/security evidence;
• prevent untrusted pull requests from accessing production secrets.

For durable payment/callback storage:

• use unique constraints for idempotency;
• use transactions for state changes;
• avoid excessive database privileges;
• encrypt transport;
• protect backups;
• test restore;
• audit administrative changes;
• separate application and migration accounts where practical.

In-memory callback/reconciliation stores are not production persistence.

Before production release, test:

• missing/incorrect internal API key;
• callback with invalid hash;
• malformed callback hash;
• duplicate valid callback;
• oversized request body;
• rate-limit behavior;
• Direct API disabled behavior;
• BKM Express disabled behavior;
• missing merchant credentials;
• insecure provider URL rejection where implemented;
• error-response redaction;
• refund/transfer timeout/unknown-state handling;
• CORS behavior;
• reverse-proxy HTTPS behavior.

For high-risk deployments, add:

• threat modeling;
• SAST;
• dependency scanning;
• DAST;
• penetration testing;
• infrastructure configuration review.

If a payment/security incident is suspected:

1. preserve relevant sanitized logs and timestamps;
2. identify affected merchant/application environment;
3. rotate exposed credentials;
4. restrict compromised routes/services;
5. verify callback/order/payment state through authoritative records;
6. reconcile refunds/transfers/payments before repeating operations;
7. notify PayTR through the appropriate merchant support channel when provider/account action is required;
8. follow legal, privacy, financial, and customer-notification obligations;
9. document root cause and corrective actions;
10. add regression tests before closing the incident.

Do not delete evidence before retention/legal requirements are considered.

This repository cannot by itself guarantee:

• PCI DSS compliance;
• legal/regulatory compliance;
• fraud prevention;
• merchant-account approval;
• provider availability;
• secure infrastructure outside the repository;
• secure frontend implementation;
• secure organizational processes.

The integrating organization owns the complete production security posture.