Setup, testing & payment operations

1. Install

Upload the plugin ZIP under Plugins → Add New → Upload Plugin, activate it, then open WooCommerce → Settings → Payments → Sanval Payments - Payten/NestPay. The gateway supports WooCommerce HPOS and both classic and block-based checkout.

2. Configure the acquiring bank

Use a ready bank preset where available, or choose a custom configuration and enter the values supplied by the bank's virtual-POS team:

• Client ID - merchant identifier.
• Store Key - secret used to create and verify signed messages.
• Hosted payment URL - normally the bank's est3Dgate endpoint.
• Currency - for example 941 for RSD, 949 for TRY or 978 for EUR.
• Hash algorithm and store type - keep the documented defaults unless the bank contract specifies different values.

Keep Test Mode enabled until a complete card flow returns an approved result and the WooCommerce order is updated correctly.

3. Choose the payment action

Capture immediately (sale)

The request uses the bank's immediate-authorization flow. An approved payment is captured and the order moves into its normal paid WooCommerce status.

Authorize only (capture later)

The request uses pre-authorization. Funds are reserved but not captured. An administrator can later Capture the full amount, capture an allowed smaller amount when partial capture is enabled, or Void the authorization. Your acquiring contract must permit these operations.

4. Single payments and installments

No installments (single payment) means a normal one-time card payment. A maximum above one exposes the available installment choices at checkout. Installments are a Premium workflow and are only valid when the bank and the merchant contract permit them.

5. Refunds

Open a paid order and use WooCommerce's Refund action. The plugin supports full and partial bank refunds where the bank contract allows them. The bank-refund button is disabled when no refundable balance remains, and invalid or excessive amounts are rejected before a bank request or WooCommerce refund is created.

6. Same-order retry

A shopper can retry a failed or interrupted payment from the WooCommerce customer payment page for the same order. The gateway creates a new payment attempt and bank order ID while preserving the order's history, avoiding duplicate WooCommerce orders.

7. Lost-callback recovery

A bank may approve a payment even when the shopper's browser or the return callback fails before the store records it. Premium provides two recovery paths where the bank supports Query:

• Check status at bank on the WooCommerce order for a manual, immediate check.
• Automatic reconciliation for recent pending orders after the configured delay and within the configured recovery window.

When an approved payment is recovered, the order is marked paid and an order note records the bank transaction ID and bank order ID. Repeating the status check is idempotent: it confirms state without charging the customer again or duplicating payment records.

8. Production readiness

Open the gateway's Diagnostics section and run Refresh readiness checks. The safe check does not send a payment request or modify an order. It verifies:

• the payment callback is externally reachable;
• the background recovery runner has executed;
• the hosted and server-to-server bank settings are configured;
• the latest operational-alert test was accepted by WordPress.

9. Password-protected staging

Basic Authentication or a staging-protection layer can block both the bank callback and wp-cron.php. Enable Protected-staging compatibility to keep the rest of the site protected while exposing only the payment callback and background runner required for end-to-end testing. Disable the compatibility mode when it is no longer needed.

10. Scheduler health and repair

Diagnostics displays the Action Scheduler and recovery-watchdog state, last successful run and overdue conditions. Use the admin-side repair control when available. This is designed for normal store administrators; server cron can still be used by advanced hosting teams, but it is not the primary customer workflow.

11. Operational alerts

Configure an alert recipient and send a test message from Diagnostics. Critical alerts use a modern HTML template and include the site, time, order, bank result and other redacted context needed to act on the incident. Card data and secret credentials are never included.

12. Transactions and support reports

WooCommerce → Sanval Transactions provides an operational view of orders, transaction IDs, bank order IDs, payment action/state, installments, latest Query and warnings. Each order also includes a Bank / support report and, where relevant, an outbound request audit.

The diagnostic export is encoded, capped and redacted. It can include field names, request profile, callback schema and bank response values, but excludes cardholder data and the Store Key.

13. Payment integrity and security controls

The bank-hosted checkout flow is surrounded by server-side controls designed to fail closed when payment data is ambiguous or an administrative request is not authorized:

• Callback verification - signed bank responses are verified before they can change an order.
• Strict callback parsing - duplicate field names, nested values, malformed structures and oversized callback payloads are rejected rather than silently normalized.
• Replay/idempotency protection - a repeated valid Approved callback does not create a second payment completion or duplicate transaction record.
• Per-order authorization - privileged financial actions require the appropriate WooCommerce capability and a request token bound to the intended order.
• Shared financial-operation lock - Capture, Void, Refund and bank-status operations cannot race each other across concurrent requests.
• Endpoint safety policy - server-to-server endpoints must use HTTPS and unsafe local, private or credential-bearing targets are rejected.
• Safe diagnostics - bank messages are normalized for display and support exports redact secrets, cardholder data and sensitive URLs.

14. Licence, grace and expiry

While Premium is active, all Premium workflows, updates and support are available. If the subscription becomes inactive, the plugin shows the remaining grace period. After expiry:

• core hosted single payments continue to work;
• new Premium workflows such as installments, reconciliation, reports and alerts are disabled;
• existing pre-authorized orders remain eligible for Capture or Void so already-reserved funds are not stranded.

15. Go-live checklist

1. Complete one approved sandbox single payment.
2. Test installments if enabled by the bank.
3. Test pre-authorization, capture and void if included in the merchant contract.
4. Test a full or partial refund.
5. Confirm same-order retry after an interrupted or failed attempt.
6. Run a positive lost-callback recovery test.
7. Confirm all readiness cards are green and the alert email is received.
8. Confirm the configured server-to-server bank endpoint is the expected HTTPS endpoint for the target environment.
9. Switch to production credentials and make one low-value live order.

Troubleshooting

Callback rejected because the signature did not validate

Confirm that the Store Key belongs to the same Client ID and bank environment that created the transaction. Test and production keys are not interchangeable. A callback can also fail if an intermediary modifies fields before they reach WordPress.

3-D Secure succeeded but the gateway returned code 99

mdStatus=1 confirms authentication only; it does not guarantee financial approval. Preserve the bank order ID, attempt transaction ID, request profile and bank message from the support report. The bank can use those values to identify a sandbox or merchant-configuration issue.

The callback or background runner returns 401/403

A password-protection layer, WAF or security plugin is blocking the route. Enable Protected-staging compatibility or allow the callback and background runner explicitly.

An old admin tab can still click a bank operation

The server validates every operation at execution time. A stale browser page cannot bypass a Query pause, licence restriction, order state or refund limit even when its button was rendered earlier.