VibeFox Datatrans for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

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.

Reachable shop: Datatrans sends webhooks from its own servers, so your shop must be reachable from the internet.

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

Installation

1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox Datatrans Gateway in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).

4. Enter the sandbox credentials from the Datatrans sandbox Web Admin (see Configuration).

5. Turn on Enable/Disable and click Save. Make a test payment in sandbox mode. When everything works, enter the production credentials and turn off Sandbox mode.

On install the module creates the order status Datatrans payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences; Datatrans is shown only for the currencies allowed there.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Datatrans Gateway > Configure. Each section has its own Save button, which saves the whole page. When the payment method is enabled but the current environment has no merchant ID or API password, the page shows Datatrans is hidden at checkout until these settings are filled in: with the missing fields. While sandbox mode is on, the page shows Sandbox mode is on: payments go to the Datatrans sandbox, no real money is charged.

Datatrans

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

Title: the payment method name customers see at checkout. It is also the payment method name stored in the order. Default: Datatrans. Required.

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

Sandbox mode: uses the Datatrans sandbox: test payments, no real money. It switches both the Datatrans servers and the credentials used for new payments. Default: on. Turn it off to take real payments. While it is on, customers see Sandbox mode: no real payment is taken. under the payment method. Refunds and captures always use the environment the payment was made in, whatever this switch says.

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 the 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 the 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.

Saved passwords and sign keys are never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it. 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, the other settings are saved.

Clear saved secrets: tick a password or sign key and click Save to remove it. An empty field keeps the saved value.

Webhook URL

The section shows the webhook URL of your shop. With friendly URLs it looks like https://your-shop/module/wcp_datatrans_gateway/webhook, possibly with a language code such as /en/. The module 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; copy it exactly as the settings show it. Refunds made in the Datatrans Web Admin are not reflected in the order.

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

settled / transmitted: the payment was captured. The order is created as paid (or an authorized order becomes paid).

authorized: the payment was only authorized (Auto settle off). The order is created in Datatrans payment on hold.

canceled: the customer left the payment page (no order), or the authorization was released (the order is cancelled).

failed: the payment failed. No order is created; the cart stays payable.

With an HMAC sign key, each webhook is checked by its Datatrans-Signature header with the sign key of the environment the payment was made in. Webhooks without a valid signature are rejected. Without a sign key, the module does not trust the webhook content and checks every webhook against the Datatrans status API. Without the webhook, an order is created only when the customer comes back to the shop after paying.

Payment processing

Auto settle: captures (settles) payments immediately. If disabled, payments are only authorized: the order is put in Datatrans payment on hold and you capture it later with Capture Datatrans payment in the Datatrans block of the order, or release it with Cancel Datatrans authorization. Default: on.

Order status after payment: the order status once the payment is settled.

Payment accepted (Processing): the standard PrestaShop status for paid orders. Default.

Delivered (Completed): every paid order becomes Delivered.

Datatrans payment on hold (On Hold): every paid order waits for your manual review. The payment is still recorded on the order.

Authorized-only payments and amount or currency mismatches always go to Datatrans payment on hold.

Advanced

Logging: writes payment events and API calls to logs/datatrans_p_debug.log.php in the module folder. The file cannot be opened from the web. Errors are always logged, even when this switch is off. No keys, card data or customer data are written. Default: off.

Log: shows the size and the latest entries of the log, with a button to clear it.

Delete data on uninstall: when on, uninstalling the module removes the module settings and the log. The Datatrans payment records of the orders (transactions, refunds) and the order status always stay. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default Datatrans) and sees the note You will be redirected to the Datatrans payment page to complete the payment securely. After confirming, the module creates a Datatrans transaction for the cart total in the cart currency and sends the customer to the Datatrans payment page. The page opens in German, English, French or Italian when the shop language is one of them. There the customer pays with any method enabled in your Datatrans account. No order exists yet at this point.

After paying, the customer returns to your shop. 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 comes back. The return address carries the cart's secure key, and the return itself never creates an order. The order is then created and the customer sees the standard order confirmation page with Your payment with Datatrans has been received. For an authorized-only payment the page shows Your payment with Datatrans has been authorized. The amount will be charged when your order is processed. If Datatrans has not confirmed the payment yet, a Payment confirmation page shows Your payment is being confirmed by Datatrans. You will receive an e-mail as soon as it is confirmed. Please do not pay again. with a Check again button; the webhook creates the order as soon as it arrives.

If the customer cancels on the Datatrans page, they are back at checkout with The payment was canceled. You can try again or choose another payment method. If the payment failed, the message is The payment was not completed. Please try again or choose another payment method. The cart is kept. A new attempt creates a new Datatrans transaction; a late payment of an earlier attempt is still recognised.

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

The webhook works while the shop is in maintenance mode and is not blocked by the country restriction of your shop.

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

Orders and refunds

Order statuses

No order yet: the customer was sent to Datatrans and has not paid, the payment failed or was canceled, or Datatrans has not confirmed it yet. Only the cart exists.

Payment accepted, Delivered or Datatrans payment on hold: the payment was settled. The status follows Order status after payment. The payment is recorded with the Datatrans transaction ID, and a note shows the amount, the payment method, the environment and how it was confirmed (webhook or return).

Datatrans payment on hold after an authorization: Auto settle is off and the payment is only authorized. Capture or cancel it in the order block.

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

Canceled: the authorization was released, in the order block or in the Datatrans Web Admin.

Refunded: the payment was fully refunded through the module.

If a second payment arrives for a cart that is already paid or authorized, the order is not changed. A note asks you to check it and refund the duplicate in Datatrans. A failed or canceled transaction never downgrades a paid order.

Datatrans payment block

The order page shows a Datatrans payment block with the transaction ID, the Datatrans status, the payment method, the amount, the amounts paid and refunded, a Sandbox badge for sandbox payments, the refund history and the Datatrans notes of the order. The actions of the block need the right to edit orders; access to the Modules pages is not needed.

Capture and cancel

For an authorized-only payment the block shows Capture Datatrans payment and Cancel Datatrans authorization. Capture settles the payment for the current order total, which must not be higher than the authorized amount; the order then moves to the status of Order status after payment. Cancel releases the authorization and sets the order to Canceled. Both go to the environment of the payment. If Datatrans refuses, the block shows the error and a note is added.

Refunds

In the Datatrans payment block enter the amount (the amount not refunded yet is filled in), optionally a reason, and click Refund via Datatrans. Confirm the question Refund this amount through Datatrans? This cannot be undone. Full and partial refunds are supported, up to the amount Datatrans actually charged minus earlier refunds. The refund is sent to the environment of the payment, so that environment's merchant ID and API password must be set. A retried refund is not credited twice. If Datatrans does not accept the refund, the block shows the error and no refund is recorded. A successful refund is added to the history and the notes with the Datatrans refund transaction ID. A full refund sets the order to Refunded; a partial refund does not change the status.

For an authorized-only payment nothing was charged yet: only the full amount can be "refunded", which cancels the authorization. Refunds are available once Datatrans has settled the payment; an authorization with a mismatched amount cannot be refunded until it is settled.

The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through Datatrans. Refunds made in the Datatrans Web Admin are not recorded in PrestaShop.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Datatrans Gateway is the first block on Modules > Module Manager > VibeFox Datatrans Gateway > Configure, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this shop. Below them are the line Product: presta-payment-datatrans and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the shop address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the main shop, also in a multistore setup. Removing the key from the shop 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. The PrestaShop storefront does not know that you are logged in to the back office, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in Modules > Module Manager on the Alerts tab. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.

Troubleshooting

Datatrans does not appear at checkout: check that the license is active, Enable/Disable is on and the current environment has its merchant ID and API password: the sandbox fields in sandbox mode, the production fields otherwise. The settings page lists the missing fields. In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group.

The payment went through, but no order was created: Datatrans could not reach the webhook URL and the customer did not return to the shop. Check that the shop is reachable from the internet and that no firewall blocks requests to the webhook URL. Check that the sign key in the settings belongs to the environment of the payment. Look at the Log field on the module page.

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.

Webhook answers Busy, retry: the order was being confirmed by another request at the same moment, or the order could not be created (for example, the module is disabled). Datatrans retries the webhook. The log shows the reason.

The webhook URL shows Method not allowed in the browser: this is normal. The URL accepts only requests from Datatrans.

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 Datatrans payments are not configured yet: the merchant ID or API password of the current environment is missing.

The customer sees The payment could not be started: look at the Log field. A wrong merchant ID or API password, or credentials of the wrong environment, are the usual reasons.

Order is Datatrans payment on hold after payment: read the Datatrans notes in the order block (see Order statuses), then fulfil the order or refund the payment.

Capture is refused: the order total is higher than the authorized amount. Datatrans cannot settle more than was authorized.

Refund or capture fails with a message about missing credentials: the payment was made in the other environment, and its merchant ID or API password is not set. Enter them and try again.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Datatrans Gateway and choose Uninstall. The license key and license status of this module are always removed. If Delete data on uninstall is on, the module settings and the log are removed. If it is off, all settings are kept for a later re-install. The Datatrans transactions and refunds and the order status Datatrans payment on hold are always kept, so orders paid before can still be refunded or captured after a re-install. Existing orders keep their payment notes and transaction IDs.

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