VibeFox Datatrans for Adobe Commerce — Help

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the cURL and JSON extensions.

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 store: Datatrans sends webhooks from its own servers, so your store must be reachable from the internet.

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

Installation

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-datatrans-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/DatatransPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_DatatransPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox Datatrans Gateway. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Enter the sandbox credentials from the Datatrans sandbox Web Admin (see Configuration). Set Enable to Yes and click Save Config. Make a test payment in sandbox mode. When everything works, enter the production credentials and set Sandbox mode to No.

The module adds the Datatrans payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates two tables for the Datatrans transactions and refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Datatrans Gateway, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page.

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters; a Sort order that is not a whole number; a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater (use a point as the decimal separator, for example 9.99).

After Save Config, while Enable is Yes, Magento shows Datatrans: enter the merchant ID and API password of the active mode, otherwise the payment method is hidden at checkout. when the current environment has no merchant ID or API password, and, while sandbox mode is on, Datatrans: test mode is on; no real money is charged.

General

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

Enable: shows or hides Datatrans at checkout. It is shown only when the merchant ID and API password of the current environment are set. Default: No.

Sort order: the position among the payment methods at checkout. A whole number.

Description: shown in the payment method list at checkout, under the payment method when the customer selects it. Default: Pay securely via Datatrans.

Connection

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: Yes. Set it to No to take real payments. While it is on, customers see TEST MODE: no real money is charged. under the payment method. Refunds, captures and status checks always use the environment the payment was made in, whatever this switch says.

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

Test Merchant Id: the merchant ID of your sandbox account.

Test Password: the server-to-server API password of the sandbox account.

Test Hmac Key: the hex key used to verify the Datatrans-Signature header of sandbox webhooks. Without it every webhook is re-checked against the Datatrans status API.

Merchant Id: the merchant ID of your production account.

Password: the server-to-server API password of the production account.

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

Magento stores the passwords and sign keys encrypted and shows only a mask (******) after saving. Leave the mask as it is to keep the saved value, type a new value to change it. To delete a saved password or sign key, clear the field and click Save Config. A sign key must be a hexadecimal string as issued by Datatrans. Any other value is not saved: Magento shows Datatrans: the HMAC sign key must be a hexadecimal string. The previous value was kept. and the other settings are saved.

Orders

Auto settle: captures (settles) payments immediately. If set to No, payments are only authorized: the order is put On Hold without an invoice, and you capture it later with Capture Datatrans payment on the order page, or release it with Cancel Datatrans authorization (see Orders and refunds). Default: Yes.

Order status after payment: the order status set after a settled payment.

Authorized-only payments and amount or currency mismatches always go to On Hold.

Payment from Applicable Countries: All Allowed Countries offers Datatrans for every country your store allows, Specific Countries only for the countries below.

Payment from Specific Countries: offer Datatrans only for billing addresses in these countries.

Minimum Order Total: offer Datatrans only from this order total, in the base currency of your store. Empty or 0 means no minimum.

Maximum Order Total: offer Datatrans only up to this order total, in the base currency. Empty or 0 means no maximum.

Advanced

Debug log: writes payment events and API calls to var/log/datatrans_p_debug.log.php in the Magento folder. The file cannot be opened from the web. Errors are always logged, even when this switch is No. Keys, card data, return tokens and e-mail addresses are not written. Default: No.

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the module settings and the log (see Uninstall). The license key is always removed. The Datatrans transactions and refunds always stay, so old orders can still be refunded. Default: No.

Datatrans portal URLs

This row shows the webhook URL of your store. It is the storefront address of the store selected in Scope (the default store view in the Default Config) and looks like https://your-store/wcpdatatransgateway/webhook/index. The module sends the webhook URL of the order's store 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; copy it exactly as the settings show it.

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

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, read from the settings of the order's store. 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 confirmed only when the customer comes back to the store after paying.

Debug log

The last row shows the size and the latest entries of the log. Click Clear log to empty it.

Checkout

At the payment step the customer chooses the payment method (by default Datatrans) and sees the description and the note You will be redirected to Datatrans to complete the payment securely. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module then creates a Datatrans transaction for the order total in the order currency, with the order ID as the reference, and sends the customer to the Datatrans payment page. The page opens in German, English, French or Italian when the locale of the store view is one of them. There the customer pays with any method enabled in your Datatrans account.

After paying, the customer returns to 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 comes back. The return address carries a secret token of the payment attempt, and the return itself never marks an order paid. Magento then creates the invoice, sets the status from Order status after payment and sends the order e-mail. The customer sees the standard order success page. For an authorized-only payment, or a payment that needs your review, the success page shows Your payment is being reviewed by the store. If Datatrans has not confirmed the payment yet, the customer sees a short page with Datatrans has not confirmed your payment yet. Please do not pay again. and a Check again link. The webhook confirms the order as soon as it arrives. A customer who comes back in another browser lands on the home page.

If the customer cancels on the Datatrans page, or the payment failed or expired, the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart with Your payment was cancelled, declined or expired. Please try again. A new attempt places a new order with a new Datatrans transaction. If the return address cannot be verified, the customer sees We could not verify the Datatrans payment. in the cart.

If Datatrans cannot start the payment, the order is cancelled, the cart is restored and the customer sees We could not start the Datatrans payment. Please try again or choose another payment method. The technical reason is written to the log.

When an order in Pending Payment is cancelled in Magento, by you or by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings), a payment that arrives later does not reopen it: the order stays Canceled with a note asking you to review the payment.

The module works with the standard Magento checkout. It 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. Datatrans is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to Datatrans, but Datatrans has not confirmed the payment yet. There is no invoice.

Processing, Complete or On Hold: the payment was settled. The status follows Order status after payment. The invoice is created with the Datatrans transaction ID (followed by -capture) as the transaction ID, and a note shows the transaction, the environment and how it was confirmed (webhook or return).

On Hold after an authorization: Auto settle is No and the payment is only authorized. There is no invoice yet. Capture or cancel it (see Capture and cancel).

On Hold after a mismatch: Datatrans reported a different amount or currency than the order total, or the order had been changed manually. No invoice is created. Check the transaction in the Datatrans Web Admin, then fulfil the order or refund the payment there.

Canceled: the customer cancelled or did not complete the payment, the payment could not be started, the authorization was released, or the order was cancelled in Magento. A payment that arrives after the cancellation leaves the order Canceled with a note.

Closed: the payment was fully refunded with a credit memo.

If a second payment arrives for a cart that is already paid, the paid order is not changed. A note asks you to check it and refund the duplicate in the Datatrans Web Admin. A failed or canceled transaction never downgrades a paid order. The notes are order comments that the customer does not see.

Datatrans payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and Datatrans transaction, Datatrans status, Datatrans amount and Datatrans mode (test or live). The customer sees only the payment method title.

Capture and cancel

For an authorized-only payment the Information tab of the order shows a Datatrans authorization block with the buttons Capture Datatrans payment and Cancel Datatrans authorization. They need the Admin permission to edit orders. Capture creates the invoice online and settles the full current order total, which must not be higher than the authorized amount; the order then moves to Processing. Cancel releases the authorization and sets the order to Canceled. Cancelling the order in Magento (after Unhold) also releases the authorization. Both go to the environment of the payment. If Datatrans refuses, Magento shows the error, for example Datatrans captures the full order total, up to the authorized amount. A capture or cancellation made in the Datatrans Web Admin is applied to the order when its webhook arrives.

Refunds

Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The money is sent back through Datatrans. Full and partial refunds are supported. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Datatrans.

The refund is made in the order currency, up to the amount Datatrans charged minus the amounts already refunded. It 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, Magento shows Datatrans refund failed. Check Datatrans Web Admin before retrying. and the credit memo is not created. If the outcome of a refund is unknown (for example, Datatrans did not answer), further online refunds of the order are blocked with Datatrans refund outcome is uncertain. Check Datatrans Web Admin before retrying. A full refund closes the order.

Refunds are available once Datatrans has settled the payment and the order has an invoice. For an authorized-only payment, cancel the authorization instead. Refunds made in the Datatrans Web Admin are not recorded in Magento; create a credit memo with Refund Offline if needed.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Datatrans Gateway is the first row of the VibeFox Datatrans Gateway group in Stores > Configuration > Sales > Payment Methods, 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 store. Below them are the line Product: magento-payment-datatrans and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 store 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 default store view, also when the installation has several websites or stores. Removing the key from the store 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 order is cancelled, the cart is restored and the customer sees We could not start the Datatrans payment. Please try again or choose another payment method. The Magento storefront does not know that you are logged in to the Admin, 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. Existing orders are not affected: payments already started are still confirmed, and captures and refunds work.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

Datatrans does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the current environment has its merchant ID and API password: Test Merchant Id and Test Password in sandbox mode, Merchant Id and Password otherwise. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total. An order total of 0 cannot be paid with Datatrans.

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 store is reachable from the internet and that no firewall blocks requests to the webhook URL. Check that the sign key in the settings of the order's website belongs to the environment of the payment. Turn on Debug log and look at the log in the Advanced section. The order is also confirmed when the customer returns to the store after paying.

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 merchant ID or API password of that environment are missing, or Datatrans did not answer. Datatrans retries the webhook.

Webhook answers Busy retry or Retry later: the order was being confirmed by another request at the same moment, or an error occurred while the order was being updated. Datatrans retries the webhook. The log shows the reason.

Webhook answers Reference mismatch or Merchant mismatch: the transaction does not belong to this order or to the merchant ID of its environment. The order is not changed.

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

Webhooks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the webhook URL too. Datatrans retries the webhook later, and the order is also confirmed when the customer returns.

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

The customer is back in the cart with We could not start the Datatrans payment: turn on Debug log and look at the log. A wrong merchant ID or API password, credentials of the wrong environment or an inactive license are the usual reasons. The order of that attempt is cancelled.

Order is On Hold after payment: read the order notes (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.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice (an authorization, or On Hold after a mismatch) cannot be refunded online.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_DatatransPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_DatatransPayment to remove the data, then bin/magento module:disable Vibefox_DatatransPayment, delete the folder app/code/Vibefox/DatatransPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Remove data on uninstall is Yes, the module settings and the log are removed too. If it is No, the settings are kept for a re-install. The Datatrans transactions and refunds are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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