VibeFox Datatrans for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

WooCommerce: 7.0 or later, installed and active.

PHP: 8.0 or later.

HTTPS: your site must be reachable from the internet over HTTPS, so that Datatrans can deliver webhooks.

Datatrans account: you need the merchant ID, the server-to-server API password and, recommended, the HMAC-SHA256 sign key for webhooks. Sandbox credentials come from the Datatrans sandbox Web Admin (admin.sandbox.datatrans.com), production credentials from the production Web Admin (admin.datatrans.com). Sandbox and production are separate Datatrans accounts with different merchant IDs and keys.

Currency: the store currency (or the order currency of your multi-currency plugin) must be enabled for your Datatrans merchant account.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_datatrans_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate. WooCommerce must be active.

3. Open the settings: WooCommerce > Settings > Payments > Datatrans > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Enter the sandbox credentials and, for real payments, the production credentials (see Configuration).

6. Turn on Enable/Disable. Keep Sandbox mode on while you test, then untick it to take real payments.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Datatrans. When the gateway is enabled but the merchant ID or the API password of the current environment is missing, the page shows Datatrans is hidden at checkout until these settings are filled in: with the list of missing fields. While sandbox mode is on, it shows Sandbox mode is on: payments go to the Datatrans sandbox, no real money is charged.

Webhook

The Webhook URL is shown at the top of the settings. It looks like https://your-site/wc-api/datatrans_payment_callback/. The plugin sends this URL to Datatrans with every transaction, so you do not have to enter it anywhere. You may also enter it in the webhook settings of the Datatrans Web Admin to receive updates for captures and cancellations made there.

The webhook reports the state of the transaction. The plugin acts on these states:

settled / transmitted: the payment was captured. The order is marked paid.

authorized: the payment was authorized but not captured (only when Auto settle is off). The order is put On hold.

failed: the payment failed or was declined. The order becomes Failed and can be paid again.

canceled: the customer cancelled on the payment page (the order stays Pending payment), or the authorization was released (the order is cancelled).

With an HMAC sign key, each webhook is checked by its Datatrans-Signature header. Webhooks without a valid signature are rejected. Without a sign key, the plugin does not trust the webhook content and checks every webhook against the Datatrans status API. Without the webhook, an order is confirmed only when the customer comes back to the store after paying.

General

Enable/Disable: Enable Datatrans Payment turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. Default: Datatrans.

Description: the text shown under the payment method at checkout. Default: Pay securely via Datatrans.

Sandbox mode: Use the Datatrans sandbox (test payments, no real money). It switches both the API and payment page hosts and the credentials below. Refunds and captures always use the environment the payment was made in. Default: on. Untick it to take real payments.

Sandbox credentials

Copy them from the Datatrans sandbox Web Admin (admin.sandbox.datatrans.com). The sign key is in the security settings there.

Sandbox merchant ID: the merchant ID of your sandbox account.

Sandbox API password: the server-to-server API password of your sandbox account.

Sandbox HMAC sign key: the hex key used to verify the Datatrans-Signature header of webhooks. Without it every webhook is re-checked against the Datatrans status API.

Production credentials

Copy them from the Datatrans production Web Admin (admin.datatrans.com).

Production merchant ID: the merchant ID of your production account.

Production API password: the server-to-server API password of your production account.

Production HMAC sign key: the hex key used to verify the Datatrans-Signature header of production webhooks. Without it every webhook is re-checked against the Datatrans status API.

A sign key must be a hexadecimal string as issued by Datatrans. Any other value is not saved: the page shows an error and keeps the previous value. If you update from version 1.0, the single set of credentials of that version is moved to the sandbox fields when sandbox mode was on, otherwise it stays in the production fields.

Payment processing

Auto settle: Capture (settle) payments immediately. Default: on. If you turn it off, payments are only authorized: the order is put On hold and you capture it later with the order action Capture Datatrans payment, or release it with Cancel Datatrans authorization.

Order status after payment: the order status set once the payment is settled. The status is set at once, without a second status change.

Processing: the WooCommerce default (default). Orders with only virtual downloadable products become Completed.

Completed: every paid order becomes Completed.

On Hold: every paid order waits for your manual review.

Advanced

Logging: Log payment events and API calls writes details to WooCommerce > Status > Logs, source wcp_datatrans_gateway. Errors are always logged. No keys, card data or customer data are written. Default: off.

Delete data on uninstall: Remove the plugin settings when the plugin is deleted. Default: off.

Checkout

The customer chooses the payment method (by default Datatrans) and places the order. The plugin creates a Datatrans transaction for the order total in the order currency, with the order ID as reference, and sends the customer to the Datatrans payment page. There the customer pays with any method enabled in your Datatrans account, for example a card, TWINT or PostFinance. The payment page opens in German, English, French or Italian when your site uses one of these languages; otherwise Datatrans chooses the language.

After paying, the customer returns to the order received page of your store. The order is marked paid only after Datatrans confirms it: by the webhook or by a server-side request to the Datatrans status API when the customer returns. The return address carries the order key, and the return itself never marks an order paid.

If the customer cancels on the payment page, the customer goes to the Pay for order page with the message The payment was canceled. You can try again or choose another payment method. After a failed payment the message is The payment was not completed. Please try again or choose another payment method. The order stays payable, and the customer can try again.

If Datatrans cannot start the payment, the customer sees The payment could not be started. Please try again or choose another payment method. The reason is written to the log.

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin takes one-time payments on the Datatrans payment page only. It has no saved cards or aliases, subscriptions, Lightbox or Secure Fields integration, choice of payment methods in the settings and no partial capture of an authorization.

Orders and refunds

Order statuses

Pending payment: the customer was sent to Datatrans and has not paid yet, cancelled on the payment page, or Datatrans has not confirmed the payment yet. Each new transaction is noted on the order with its ID and environment.

Processing, Completed or On Hold: the payment was settled. The status follows Order status after payment. The order note shows the amount, the payment method, the Datatrans transaction ID and the environment (sandbox or production). The transaction ID is saved on the order.

On hold, authorized: with Auto settle off, the payment was authorized but not captured. Open the order and choose Capture Datatrans payment or Cancel Datatrans authorization in the order actions. The capture uses the current order total, which must not be higher than the authorized amount. If it is, or if Datatrans rejects the capture or cancellation, the reason is added to the order notes.

On hold after payment: Datatrans reported a different amount or currency than the order total (for example, the order was edited after the payment started), or the payment arrived after the order had been cancelled. The order note explains it. Check the transaction in the Datatrans Web Admin and fulfil the order or refund the payment.

Failed: the payment failed or was declined. The customer can try again.

Cancelled: the authorization was released, by the order action or in the Datatrans Web Admin.

A late failed or cancelled notice never changes a paid order. If a second successful payment arrives for an order that is already paid, the order is not changed. A note warns about a possible double charge and asks you to refund it in Datatrans if needed.

Refunds

Open the order, click Refund, enter the amount and click Refund via Datatrans. Full and partial refunds are supported. The refund is sent in the environment the payment was made in, so that environment's credentials must be set. A retried refund is not credited twice. If Datatrans does not accept the refund, WooCommerce shows the error and no refund is recorded. A successful refund is added to the order notes with the amount and the Datatrans refund transaction ID.

For a payment that is only authorized, a refund of the full amount cancels the authorization. A partial refund is not possible until the payment is captured.

Refunds made in the Datatrans Web Admin are not recorded in WooCommerce. If needed, create a manual refund in WooCommerce without Refund via Datatrans.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Datatrans. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Datatrans is not shown to customers at checkout. If a payment is started anyway, the customer sees This payment method is not available. Please choose another one. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed, and refunds and captures work.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

Datatrans does not appear at checkout: check that the license is active, Enable/Disable is on and the merchant ID and API password of the current environment are set: the sandbox fields in sandbox mode, the production fields otherwise. The settings page lists the missing fields.

The payment went through, but the order stays Pending payment: Datatrans could not reach the webhook URL and the customer did not return to the store. Check that the site is reachable from the internet over HTTPS and that no security plugin or firewall blocks requests to /wc-api/datatrans_payment_callback/. Check that the sign key in the settings belongs to the environment of the payment. Turn on Logging and look at WooCommerce > Status > Logs, source wcp_datatrans_gateway.

Webhook answers Invalid signature: the HMAC sign key in the settings does not match the one in the Datatrans Web Admin, or belongs to the other environment. Copy the key again.

Webhook answers Not configured or Verification failed: the webhook had to be checked with the Datatrans status API, but the credentials of that environment are missing, or Datatrans did not answer. Datatrans retries the webhook.

The HMAC sign key is not saved: the key must be a hexadecimal string. Copy it again from the Datatrans Web Admin.

The customer sees The payment could not be started: the merchant ID or API password is wrong, belongs to the other environment, or the currency is not enabled for your Datatrans account. Turn on Logging to see the reason.

Order is On hold after payment: read the order note. The paid amount or currency differed from the order, the payment came after the order was cancelled, or the payment is only authorized and waits for capture.

Capture is not possible: the order total is higher than the authorized amount. Capture uses the current order total, so reduce it to the authorized amount or less.

Refund fails with a message about credentials: the payment was made in the other environment, and its credentials are not set. Enter them and try again. For an authorized payment, refund the full amount or capture it first.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

For developers, the readme mentions the filter wcp_datatrans_gateway_init_request, for example to limit the payment methods shown on the Datatrans page.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes and transaction IDs.

Datatrans is a trademark of its respective owner. This plugin is not affiliated with or endorsed by Datatrans.