VibeFox DPO for Adobe Commerce — Aide

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, JSON and SimpleXML extensions.

DPO Pay account: you need the Company Token and the Service Type ID of your DPO merchant account. DPO issues them when your account is opened; get them from your DPO account manager. DPO can also provide a test account with its own token and service type. There is no separate test server: DPO uses the same API address for test and live accounts, and the account is chosen by the Company Token.

Currency: the order currency must be supported by your DPO account. DPO accepts at most 2 decimal places, so order totals with 3 decimals (for example KWD 12.345) cannot be paid, and DPO Pay is not offered for them.

Magento cron: the standard Magento cron must run on your server. It performs the scheduled payment checks (see Configuration).

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-dpo-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/DpoPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_DpoPayment 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 DPO Pay 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 test and/or live Company Token and Service Type (see Configuration). Send the push notification URL shown on the page to DPO support and ask them to set it for your account. Set Enable to Yes and click Save Config. Place a test order in test mode, then set Test mode to No to accept real payments.

The module adds the DPO Pay 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 one table for the DPO payment attempts.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox DPO Pay 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. Amounts are entered with a dot, for example "9.99".

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 (Enter a title for the payment method (1 to 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 (Order total must be a number, 0 or greater.).

When Enable is Yes, saving also checks the selected mode. If its Company Token or Service Type is empty, Magento shows DPO Pay: enter the Company Token and Service Type of the selected mode; the payment method is hidden until then. While test mode is on, it shows DPO Pay: test mode is on; payments use the test account credentials.

General

Enable: shows or hides DPO Pay at checkout. It is shown only when the Company Token and the Service Type of the current mode are set. Default: No.

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

Description: shown in the payment method list at checkout when the customer selects DPO Pay. Default: Pay securely by card or mobile money on the DPO Pay payment page.

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

API credentials

DPO issues a Company Token and a Service Type ID for your merchant account, and separate ones for a test account. Get them from your DPO account manager.

Test mode: when Yes, new payments are created with the test Company Token and Service Type. Default: Yes. Set it to No to accept real payments with the live credentials. While it is on, customers see TEST MODE: no real money is charged. under the payment method. Status checks and cancellations of existing payments always use the account the payment was created with.

Test Company Token: the Company Token of your DPO test account.

Test Service Type: the numeric Service Type ID of your DPO test account.

Live Company Token: the Company Token of your live DPO merchant account.

Live Service Type: the numeric Service Type ID of your live DPO merchant account.

Magento stores the Company Tokens 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 token, clear the field and click Save Config. A Service Type must be a number. Any other value is not saved: Magento shows DPO Pay: Service Type must be numeric. The previous value was kept. and saves the other fields.

Orders

Successful payment status: the order status after a verified successful payment.

Authorized-only payments and payments with a different amount or currency always go to review (see Orders and refunds). Capture and refunds are performed in the DPO merchant portal.

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

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

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

Maximum Order Total: offer DPO Pay only up to this order total, in the base currency. 0 or empty means no maximum. Default: 0.

Advanced

Debug log: writes DPO requests, push notifications and checks to var/log/dpo_p_debug.log.php in the Magento folder. The file cannot be opened from the web. Errors are always logged. Company Tokens, e-mail addresses and payment tokens are masked. Default: No.

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the gateway settings and the log (see Uninstall). The license key is always removed. The DPO payment history always stays. Default: No.

Push notifications and scheduled checks

This row, below the sections, shows the push notification URL. The push notification tells your store at once that a payment has been made, even if the customer closes the browser after paying. The URL is not set in a dashboard: Give this push notification URL to DPO support. 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/wcpdpopay/notify/index. Copy the URL exactly as the settings show it. It must be reachable from the internet, without a firewall or basic authentication in front of it.

DPO push notifications carry no signature, so their content is never trusted. The module only uses them to find the payment by its token and then checks the result with DPO itself, with the Company Token of the mode the payment was made in. A token your store did not create is rejected without any request to DPO.

The standard Magento cron checks unconfirmed payments with DPO 15 minutes after the redirect and again 15 minutes after the payment time limit (5 hours). No public cron URL is used. Without the push URL and the cron, an order is confirmed only when the customer returns 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 DPO Pay) and sees the description and the note You will be redirected to DPO Pay 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 DPO payment token for the order total in the order currency, with Order # and the order number as description, and sends the customer to the DPO payment page. The customer's name, e-mail, phone and billing address are passed to pre-fill the page. There the customer pays with any method enabled on your DPO account. The payment link is valid for 5 hours. In the DPO portal the payment has the company reference MG2- and the cart number.

After paying, the customer returns to your store. The order is marked paid only after DPO confirms it: the module asks DPO for the result of the payment when the customer returns, when a push notification arrives and at the scheduled checks. Magento then creates the invoice with the DPO transaction token, sets the status from Successful payment status and sends the order e-mail. The customer sees the standard order success page. A customer who comes back in another browser lands on the home page.

If DPO has not confirmed the payment yet, the customer sees a simple page with We have not received a payment confirmation from DPO Pay. Please do not pay again. and a Check again link. If DPO reports an authorized-only or overpaid or underpaid payment, the customer sees the success page with Your DPO payment requires review by the store.

If the payment was declined, or the customer leaves the DPO page with its back button, the payment is checked first. If it was not paid, an open DPO token is cancelled at DPO, the order is cancelled (the stock goes back), the cart is restored and the customer sees Your DPO payment was declined or cancelled. Please try again or choose another method. A payment that DPO is still processing is not cancelled.

When the customer pays again for the same cart, the previous DPO token is checked first. If it was paid, no new payment is created. If it is still being processed, the customer sees Your previous payment is still being processed by DPO. Please wait before trying again. Otherwise the old token is cancelled at DPO and a new one is created.

If DPO cannot start the payment, the order is cancelled, the cart is restored and the customer sees a short message in the cart chosen by the DPO error code, for example DPO Pay does not support the currency of this order. Please choose another payment method., The amount exceeds the limit allowed by DPO Pay. Please choose another payment method or contact us. or This order has already been paid with DPO Pay. Please contact us if the order status is not updated. Other errors show DPO Pay is temporarily unavailable. Please try again or choose another payment method.

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), the payment is checked with DPO and its open token is cancelled at DPO. If the payment was already made, the order gets its invoice instead of being cancelled.

The module works with the standard Magento checkout. It takes one-time payments on the DPO page only. It has no refunds from Magento, no saved cards, no subscriptions or recurring payments, no card fields on your site and no capture of authorized-only payments. DPO Pay 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 DPO, but DPO has not confirmed the payment yet. There is no invoice.

Processing, Complete or On Hold: the payment was verified. The status follows Successful payment status. The invoice is created with the DPO transaction token as the transaction ID, and a note shows the amount, the currency, the approval code and how the payment was confirmed (return, push or scheduled check).

On Hold for review: DPO reports a payment that is only authorized and not captured, or an overpaid or underpaid transaction. No invoice is created. Capture or void the payment in the DPO portal, then update the order.

On Hold after a mismatch: DPO confirmed a payment, but the amount or currency differs from the order, or the order had been changed manually. No invoice is created. The note shows the actual payment. Reconcile it in the DPO portal. A payment that arrives for an order that was already cancelled leaves the order cancelled and adds the same note.

Canceled: the payment was declined, expired or cancelled at DPO, the customer left the DPO page, the payment could not be started, or the order was cancelled in Magento.

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

If DPO confirms a second successful payment for a cart that is already paid, the order is not changed and gets a note about a possible double payment, so you can refund it in the DPO portal. A later declined result never changes a paid order, and a paid or refunded order is never reopened. The notes are order comments that the customer does not see.

Cancelling an order: when you cancel an unpaid DPO order, the module checks the payment with DPO first. If DPO cannot be reached, Magento shows DPO Pay could not verify this payment. Please try again. and the order is not cancelled. If DPO already confirmed money for the cart, Magento shows DPO Pay already confirmed money for this cart. Review the order before cancelling it. If DPO does not confirm the cancellation of the token (for example for an authorized-only payment), the order is cancelled with a note asking you to void the payment in the DPO portal.

Cancelling by the Magento cron: if DPO cannot be reached or the Company Token of the payment's mode has been removed, the cron leaves the order in Pending Payment and adds the note DPO Pay could not verify the payment of this order (DPO unavailable or the Company Token of its mode is missing). The order was not cancelled automatically: check the DPO portal, then cancel or invoice the order. once. If DPO already confirmed money for the cart, the order stays as it is with the note DPO Pay already confirmed money for this cart. The order was not cancelled automatically: review it before cancelling. The cron goes on with the other expired orders and tries this order again on a later run.

DPO payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, once DPO has answered, DPO transaction token, DPO transaction reference, DPO company reference, DPO result, DPO approval, DPO verified amount and DPO mode. The customer sees only the payment method title.

Refunds

Refunds from Magento are not sent to DPO. Refund the payment in the DPO merchant portal, then create a credit memo for the invoice with Refund Offline to record the refund in Magento. A full refund closes the order (Closed).

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox DPO Pay Gateway is the first row of the VibeFox DPO Pay 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-dpo 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, DPO Pay 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 This payment method is not available. Please choose another one. 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 by the return, the push notification and the scheduled checks.

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

DPO Pay 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 mode has its Company Token and Service Type: the test fields in test mode, the live fields otherwise. Saving the settings shows a warning when they are missing. 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 with 3 decimals cannot be paid with DPO.

The payment went through, but the order stays Pending Payment: the push notification URL is probably not set for your DPO account, and the customer did not return to the store. Ask DPO support to set the URL shown in Push notifications and scheduled checks, and check that the Magento cron runs. Set Debug log to Yes and look at the log at the bottom of the group.

Push notification answers Unknown transaction: the payment token does not belong to a DPO Pay payment of this store, for example the push came from another store on the same DPO account.

Push notification answers Forbidden: the push carries a Company Token that is not set in the store of the payment.

Push notification answers Verification failed: DPO could not be reached to check the payment, the cart was being processed by another request at the same moment, or the order could not be updated. The scheduled check confirms the order later, and so does the customer's return. The reason is in the log.

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

Push notifications fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the push URL too. The order is confirmed when the customer returns or at a later scheduled check.

The Service Type is not saved: it must be the numeric Service Type ID from DPO.

The customer sees DPO Pay is temporarily unavailable: DPO refused to create the payment, for example because of a wrong Company Token or Service Type, or a token of the other mode. The DPO result code is in the log. The order of that attempt is cancelled.

The customer sees This order has already been paid with DPO Pay: DPO refused a second payment for the same cart. Check the payment in the DPO portal and the order in Magento.

Order is On Hold after payment: read the order notes (see Order statuses), then review the transaction in the DPO portal.

There is no Refund button on the credit memo: this is normal. The module has no online refunds. Refund the payment in the DPO merchant portal, then use Refund Offline.

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.

Developers can change the customer data sent to DPO with the Magento event dpo_p_customer_data and the payment time limit with dpo_p_payment_time_limit.

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_DpoPayment. It removes the data and the code.

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

The license key and license status are always removed. If Remove data on uninstall is Yes, the gateway settings and the log are removed too. If it is No, the settings are kept for a re-install. The DPO payment history is always kept, so late notifications and checks for old payments still work after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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