VibeFox Datatrans for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

PHP: 8.0 or later.

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 download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package wcp_datatrans_gateway-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_datatrans_gateway.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_datatrans_gateway-oc3-(version).ocmod.zip. The extension has no OCMOD modifications, so Extensions > Modifications does not need a refresh. Instead of the installer you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Datatrans Gateway and click Install (the green + button). Your admin user needs the right to modify the payment extensions list.

3. Click Edit (the pencil button) to open the settings page. Paste your VibeFox license key into License key in the license block at the top of the 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.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_datatrans_gateway.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Datatrans Gateway, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key and the Datatrans credentials and test the payment as in steps 3 to 5 for OpenCart 3. The settings page and its fields are the same in both versions. Only the webhook URL is different (see Configuration).

A new install starts with the payment method turned off and sandbox mode on. The webhook URL is sent to Datatrans with every transaction, so you do not have to set it up.

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox Datatrans Gateway > Edit. The sections are listed on the left; the Save button under the list 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. Without the right to modify the extension the page shows the settings but cannot save them.

When you save, Title must not be empty or longer than 128 characters, Sort Order must be a whole number, Total a number of 0 or more, and the geo zone and order statuses must exist. Otherwise nothing is saved and the page shows the error. A sign key that is not a hexadecimal string is not saved: the previous value is kept, the other settings are saved, and the page shows a warning that names the field.

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, up to 128 characters.

Description: the text shown to the customer at the Confirm Order step, above the confirm button. 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. at the Confirm Order step. Refunds and captures always use the environment the payment was made in, whatever this switch says.

Sort Order: the position of Datatrans among the payment methods at checkout. Leave it empty or enter a whole number.

Geo Zone: offer Datatrans only for payment addresses in the selected geo zone. Default: All zones. Geo zones are set up in System > Localisation > Geo Zones.

Total: the checkout total, in the default currency of the store, that an order must reach before Datatrans is offered. Leave it empty to offer Datatrans for any total.

Sandbox credentials

Copy them from the Datatrans sandbox Web Admin (admin.sandbox.datatrans.com, the page links there). 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. To remove a saved value, tick Clear the saved value on save under the field and click Save.

Webhook URL

The section shows the webhook URL of your store. On OpenCart 3 it looks like https://your-store/index.php?route=extension/payment/wcp_datatrans_gateway/webhook, on OpenCart 4 like https://your-store/index.php?route=extension/wcp_datatrans_gateway/payment/wcp_datatrans_gateway.webhook. It is built from the storefront address of your OpenCart installation. The extension 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 extension 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. Webhooks without a valid signature are rejected. Without a sign key, the extension does not trust the webhook content and checks every webhook against the Datatrans status API. Without the webhook, an order gets its status only when the customer comes back to the store after paying.

Payment processing

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

OpenCart creates the order at the Confirm Order step without a status (a missing order). The order gets a status only after Datatrans has confirmed the payment. A failed or cancelled payment leaves it without a status, and the cart is kept. Each field below lists your OpenCart order statuses.

Order status after payment: the status of the order once the payment is settled and its amount and currency match. Default: Processing.

Datatrans payment on hold: authorized-only payments (Auto settle off), amount or currency mismatches and payments that arrive after the order was cancelled. A note explains the reason. Default: Pending, because OpenCart has no On hold status. You can create your own status in System > Localisation > Order Statuses and select it here.

Authorization canceled: set when the authorization is released with Cancel Datatrans authorization or in the Datatrans Web Admin. Default: Canceled.

Refunded: set after the payment is fully refunded from the order page. Default: Refunded.

Advanced

Logging: writes payment events and API calls to datatrans_p_debug.log.php in the OpenCart logs folder (storage/logs). The file cannot be opened from the web, and at 5 MB it is moved to datatrans_p_debug.old.log.php. 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. Click Clear log to empty it.

Delete data on uninstall: when on, uninstalling the extension removes the module settings and the log. The Datatrans payment records of the orders (transactions, refunds) are kept. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file. Passwords and sign keys are not exported.

Import: paste previously exported JSON and click Import to restore the settings. Saved passwords and sign keys are kept.

Checkout

At the Payment Method step the customer chooses the payment method (by default Datatrans). At the Confirm Order step the customer sees your description and the note You will be redirected to the Datatrans payment page to complete the payment securely. OpenCart creates the order at this step, still without a status. When the customer clicks Confirm Order, the extension creates a Datatrans transaction for the order total in the order currency, with the OpenCart order number as the reference, and sends the customer to the Datatrans payment page. The page opens in German, English, French or Italian when the store language is one of them. There the customer pays with any method enabled in your Datatrans account. On OpenCart 4 the customer picks the payment method with the Choose button of the payment method block, in the window Payment method options, and clicks Confirm Order at the bottom of the checkout page.

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 random token of the payment attempt, and the address itself is never trusted. The order then gets its status the standard OpenCart way, with the usual order e-mails and stock update, and the customer sees the OpenCart order success 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 the buttons Check again and Back to checkout; the webhook sets the order status as soon as it arrives. On OpenCart 4 the browser does not send the store session when Datatrans sends the customer back, so the extension first shows a short page that opens the same return address again from your store: the customer keeps the cart and the login.

If the customer cancels on the Datatrans page, the customer is 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. On OpenCart 4 these messages are shown above the checkout page. The cart is kept. OpenCart 3 creates a new order every time the Confirm Order step is shown; OpenCart 4 keeps one order for the checkout and updates it, and a new attempt is a new Datatrans transaction of the same order. Before a new payment starts, the open Datatrans transactions of the earlier orders of the same cart are checked: a paid or authorized one is confirmed instead of a new payment, an open one is cancelled at Datatrans. A cart is paid only once: when another order of the same cart is already paid or authorized, no new payment is started and the customer goes to the success page. If a payment for another order of a paid cart still arrives, that order stays without a status and the paid order gets a note to check and refund the duplicate in Datatrans.

OpenCart 4 keeps the order in the checkout until the success page is shown. If that order was closed without a payment meanwhile (for example cancelled, also after you cancelled an authorization, or refunded), Confirm Order or the return from Datatrans sends the customer back to the checkout with Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., and the next Confirm Order pays a new order of the cart. If the order is already paid and the cart has changed since (other products or quantities), the customer is sent back to the checkout, and the changed cart gets a new order and its own payment; the same cart goes to the success page without a new payment.

If Datatrans cannot start the payment, the customer stays at the Confirm Order step 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 also works while the store is in maintenance mode: OpenCart 3 lets payment extension requests through, and on OpenCart 4 the extension adds a startup action that lets the webhook and the customer's return through.

The extension 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 status (missing order): the customer was sent to Datatrans and has not paid, the payment failed or was canceled, or Datatrans has not confirmed it yet. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders.

Order status after payment (default Processing): the payment was settled. A note shows the amount, the payment method, the Datatrans transaction ID, the environment and how it was confirmed (webhook or return).

Datatrans payment on hold after an authorization (default Pending): Auto settle is off and the payment is only authorized. Capture or cancel it in the order tab.

Datatrans payment on hold after payment: Datatrans reported a different amount or currency than the order total, 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.

Authorization canceled (default Canceled): the authorization was released, in the order tab or in the Datatrans Web Admin.

Refunded (default Refunded): the payment was fully refunded through the extension.

If a second payment arrives for an order 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. A payment for an order that is already refunded only adds a note.

Notes are entries in the order History that the customer does not see.

VibeFox Datatrans Gateway tab

In Sales > Orders open an order paid with Datatrans. At the bottom of the order page, next to History and Additional, the VibeFox Datatrans Gateway tab shows the Transaction ID with a Sandbox label for sandbox payments, the Datatrans Status, the Payment method, the Amount, the amounts Paid / refunded, the capture and cancel buttons or the refund form, the refund history and the Datatrans notes of the order. The tab is shown to users who have access to the extension. Its actions need the right to modify the extension (set in System > Users > User Groups).

Capture and cancel

For an authorized-only payment the tab 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 Order status after payment. Cancel releases the authorization and sets the order to Authorization canceled. Both go to the environment of the payment. If Datatrans refuses, the tab shows the error and a note is added.

Refunds

In the tab enter the Amount (the amount not refunded yet is filled in), optionally a Reason (optional), 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 tab shows the error and no refund is recorded. A successful refund is added to the refund history and the notes with the Datatrans refund transaction ID. A full refund sets the order to Refunded without notifying the customer and without returning products to stock, like a manual status change. A partial refund does not change the status.

Refunds are available once Datatrans has settled the payment. An authorized-only payment is captured or cancelled instead, and an authorization with a mismatched amount cannot be refunded until it is settled.

Product returns in Sales > Returns do not send money back through Datatrans. Refunds made in the Datatrans Web Admin are not recorded in OpenCart.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Datatrans Gateway is the first block on Extensions > Extensions > Payments > VibeFox Datatrans Gateway > Edit, 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: opencart-payment-datatrans and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin 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 store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. 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 customer sees This payment method is not available. Please choose another one. An admin user who is logged in to the admin in the same browser still sees the payment method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the payment method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension 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. Also check that the payment address is in the selected Geo Zone and that the order reaches the Total set in the settings.

The payment went through, but the order stays without a status: 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 belongs to the environment of the payment. Look at the Log field on the extension 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 status could not be set. 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.

The customer sees We could not verify the payment: the return address did not match a payment attempt of the order. If money was charged, the webhook still sets the order status.

Order is in the on hold status after payment: read the Datatrans notes in the order tab (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.

No capture buttons or refund form in the tab: the tab says why: the payment is not settled yet, it is fully refunded, your user group has no right to modify the extension, or the credentials of the payment environment are missing.

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.

For developers: before the Datatrans transaction is created, the extension triggers the OpenCart event datatrans_p_init_request with the request body and the order.

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox Datatrans Gateway. The license key and license status of this extension are always removed. OpenCart always removes its own settings of the extension: Enable/Disable, Sort Order, Geo Zone, Total and the four order statuses of the Payment processing section, which return to their defaults on a re-install. The OpenCart event of the extension is removed too (on OpenCart 4 its events and its startup action, which lets Datatrans through in maintenance mode). If Delete data on uninstall is on, the other module settings (title, description, sandbox mode, credentials, auto settle, logging) and the log are removed. If it is off, they are kept for a later re-install. The Datatrans transactions and refunds are always kept, so orders paid before can still be refunded or captured after a re-install. Existing orders keep their payment notes.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox Datatrans Gateway in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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