VibeFox Midtrans for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

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

Currency: Indonesian Rupiah (IDR). Midtrans charges in IDR only, so the payment method is offered only when the cart currency is IDR. There is no currency conversion. Add the IDR currency in International > Localization if your shop does not have it.

Midtrans account: you need the Server Key from Midtrans Dashboard > Settings > Access Keys, in the sandbox dashboard and in the production dashboard. Only the Server Key is used. The Client Key is not needed for Snap Redirect. The payment methods themselves (GoPay, QRIS, virtual accounts and others) are enabled in your Midtrans account.

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 Midtrans Payment 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 Server Keys and copy the payment notification URL into the Midtrans dashboard (see Configuration).

5. Turn on Enable/Disable and click Save. Test in Sandbox, then switch Environment to Production.

On install the module creates two order statuses, Awaiting Midtrans payment and Midtrans payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences. The module must stay allowed for the IDR currency.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Midtrans Payment Gateway > Configure. Each section has its own Save button, which saves the whole page. Above the fields the page warns you when the Server Key of the selected environment is missing (the payment method is then hidden at checkout) and when the default shop currency is not IDR, and shows Sandbox mode: payments are simulated, no real money is charged. while Sandbox is selected.

Midtrans

Enable/Disable: Enable Midtrans payments turns the payment method on or off. Default: off.

Title: the payment method title shown to customers at checkout. It is also the payment method name stored in the order. Default: Midtrans. Required.

Description: the text shown under the payment method at checkout. Default: Pay securely via Midtrans — GoPay, QRIS, ShopeePay, cards, bank transfer and more. In Sandbox the line SANDBOX MODE: no real money is charged. is added.

API credentials

Copy the Server Key from Midtrans Dashboard > Settings > Access Keys. The section has links to the production and the sandbox dashboard.

Environment: which Midtrans environment new payments use. Switching uses the key and the API of the selected environment. Payments keep the environment they were made in, for refunds and notifications. Default: Sandbox.

Sandbox: for testing, no real money.

Production: live payments.

Production Server Key: starts with Mid-server-. Keep it secret.

Sandbox Server Key: starts with SB-Mid-server-.

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

Clear saved keys: tick a key and click Save to remove it. An empty field keeps the saved value.

Payment notification URL

The notification tells your shop that a payment has been made. The Notification URL field shows the URL to use. With friendly URLs it looks like https://your-shop/module/wcp_midtrans_payment_gateway/webhook, possibly with a language code such as /en/. Copy the URL exactly as the settings show it and paste it into Midtrans Dashboard > Settings > Payment > Notification URL, in the sandbox dashboard and in the production dashboard you use. If you open the URL in a browser, it shows a short explanation, so you can check that it is reachable. The Test notification URL button in the Midtrans dashboard is answered as well.

Each notification must carry a valid signature made with one of your Server Keys, and the environment of the key must match the environment of the payment. Notifications without a valid signature are rejected. The status is then read again from the Midtrans status API. The module handles these Midtrans transaction statuses:

settlement, capture (accepted): the payment was made. The order is created as paid when the amount (whole rupiah) and currency match the cart.

capture (challenge): a card payment flagged by Midtrans fraud detection. The order is put in Midtrans payment on hold until you approve or deny it in the Midtrans dashboard.

pending: the customer chose a delayed method (virtual account, convenience store) and has not paid yet. The order is created in Awaiting Midtrans payment.

expire, cancel: the unpaid transaction expired or was cancelled. A waiting order becomes Canceled, for every payment method. Without an order, only the attempt is closed and the customer can pay the cart again.

deny: the payment was denied. A waiting order becomes Payment error.

failure: the payment failed. A waiting order becomes Payment error.

refund, partial_refund: a refund made in the Midtrans dashboard is recorded on the order.

Without the notification URL, an order is created only when the customer returns to the shop after paying, and a delayed payment made later is not seen until the customer comes back.

Payment settings

Midtrans charges in IDR only, and amounts are sent in whole rupiah. If the order lines do not add up to the rounded total, a Rounding adjustment line is sent to Midtrans.

Status after payment: the order status after a confirmed payment.

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

Completed: every paid order becomes Delivered.

On hold: every paid order goes to Midtrans payment on hold for your manual review. The payment is still recorded on the order.

Payment page expiry (minutes): how long the customer can pay (Snap page, virtual account and so on). Leave empty or 0 for the Midtrans default. A value that is not a whole number of minutes is refused with an error when you save.

Order ID prefix: added to the number sent to Midtrans, so several shops can share one Midtrans account. The number is the cart ID with a time stamp, for example WC-123-1700000000. Letters, digits and - _ . ~ only, up to 20 characters; other characters are removed on save. Notifications of other shops are ignored. Default: WC-.

Advanced

Debug log: writes API calls and notifications to logs/midtrans_p_debug.log.php in the module folder. The file cannot be opened from the web. Errors are always logged. Keys and customer data are never logged. 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 module removes the module settings and the log. Orders, their Midtrans payment references and refunds and the module's order statuses always stay, so old orders can still be refunded after a re-install. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default Midtrans) and confirms. The module creates a Midtrans Snap transaction for the cart total in whole rupiah, with the order lines, shipping, discounts, gift wrapping, tax and the customer's billing and shipping details, and sends the customer to the Midtrans payment page. There the customer chooses any method enabled in your Midtrans account. No order exists yet at this point.

After paying, the customer returns to your shop. The return link itself never marks an order paid: the order is marked paid only after Midtrans confirms it, by the signed notification or by a request to the Midtrans status API when the customer comes back. The order is then created and the customer sees the standard order confirmation page with the payment method used. For a delayed payment the page shows We are waiting for Midtrans to confirm your payment. If you chose a bank transfer, virtual account or convenience store, please complete the payment using the instructions from Midtrans. You will receive an e-mail once the payment is confirmed. For an order closed without payment it shows Your Midtrans payment was not completed. Please contact us about this order. If Midtrans cannot be reached when the customer comes back, a Payment confirmation page shows We are confirming your payment with Midtrans. The order will be updated automatically — please do not pay again. with a Check again button.

If the customer left the Snap page without paying, the customer is back at checkout with The Midtrans payment was not completed. You can try again below. If the payment was declined or has expired, the message is Your Midtrans payment was declined or has expired. Please try again or choose another payment method. The cart is kept. When the customer pays again, an unused or pending Snap of the same amount is reused. If the amount changed, the pending transaction is expired at Midtrans first. If the previous Snap was paid meanwhile, the order is created and no new transaction is made. If the order already exists and was closed without payment, the message is Your Midtrans payment was declined or has expired. Please place a new order or contact us.

If Midtrans cannot start the payment, the customer stays at checkout with a short message: Could not connect to Midtrans. Please try again in a moment., Midtrans payments are temporarily unavailable. Please choose another payment method or contact us. (for example with a wrong Server Key) or the reason from Midtrans. The technical reason is written to the log. A non-IDR cart gives Midtrans only supports payments in IDR (Indonesian Rupiah). Please choose another payment method.

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

The module uses Snap Redirect only. It has no Snap pop-up, no card form on your site, no saved cards or one-click payments, no installment or promo settings (configure payment methods in the Midtrans dashboard) and no subscriptions. Card payments are captured immediately, with no separate authorize and capture.

Orders and refunds

Order statuses

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

Awaiting Midtrans payment: the customer chose a delayed method (virtual account, convenience store) or started a card payment that is not finished. The order becomes paid when Midtrans reports the payment.

Payment accepted, Delivered or Midtrans payment on hold: the payment was confirmed. The status follows Status after payment. The payment is recorded with the Midtrans transaction ID, and a note shows the payment method and the Midtrans order ID.

Midtrans payment on hold: also set when a card payment is under fraud review (challenge, no payment recorded yet), when the paid amount or currency did not match the order (the order is not marked paid), or when a payment arrives for a cancelled order (the order is not re-opened automatically). The note explains it. Check the order, then fulfil it or refund the payment.

Canceled: the unpaid transaction expired or was cancelled. When you cancel an unpaid Midtrans order yourself, its pending Midtrans transaction, for example an issued virtual account, is expired so it can no longer be paid.

Payment error: the payment failed, or a challenged card payment was denied.

Refunded: the payment was fully refunded.

If a second payment arrives for an order that is already paid, the order is not changed. A note asks you to refund the second payment in the Midtrans dashboard. A payment for a refunded order adds a note only.

Midtrans payment block

The order page shows a Midtrans payment block with the Midtrans order ID, the transaction ID (linked to the transaction in the Midtrans dashboard of the payment's environment), the payment method, the status, the amount paid and refunded, a Sandbox badge for sandbox payments, the refund history and the Midtrans notes of the order.

Refunds

In the Midtrans payment block enter the amount (the amount not refunded yet is filled in), optionally a reason, and click Refund via Midtrans. Confirm the question Refund this amount through Midtrans? This cannot be undone. Full and partial refunds are supported in whole rupiah; an amount with decimals is refused. You need the right to edit orders. You can refund up to the amount Midtrans actually charged, even if the order was edited later. The refund is sent in the environment the payment was made in, so that environment's Server Key must be set. Midtrans allows API refunds only for some payment methods and transaction states (for example settled card, GoPay, QRIS or ShopeePay payments). If Midtrans does not accept the refund, the block shows the error and no refund is recorded; then refund in the Midtrans dashboard. A successful refund is added to the refund history and the notes. A full refund sets the order to Refunded. A partial refund does not change the status. Refunds are available once Midtrans has reported the payment settled.

The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through Midtrans.

Refunds made in the Midtrans dashboard arrive by the notification and are added to the refund history automatically, with the reason Refunded in the Midtrans dashboard. When the whole payment is refunded there, the order becomes Refunded.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Midtrans Payment Gateway is the first block on Modules > Module Manager > VibeFox Midtrans Payment 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-midtrans 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, Midtrans 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

Midtrans does not appear at checkout: check that the license is active, Enable/Disable is on and the selected Environment has its Server Key. Check that the cart currency is IDR. In Payment > Preferences check that the module is allowed for IDR, the customer's country and the customer's group. The settings page shows a warning when the key is missing or the shop currency is not IDR.

The payment went through, but no order was created: the notification is not working. Check that the payment notification URL is set in the Midtrans dashboard of the environment you use (sandbox or production), that it is exactly the URL shown in Notification URL and that it is reachable: open it in a browser, it shows a short explanation. Turn on Debug log to see the notifications. The order is also created when the customer returns to the shop after paying.

Notification answers Invalid signature: the notification was not signed with your Sandbox or Production Server Key. Check that the keys in the settings belong to the same Midtrans account as the dashboard that sends the notifications.

Notification answers Server key not configured: no Server Key is set. Enter it in the settings; Midtrans retries the notification.

Notification answers Order not found — ignored: the Midtrans order ID was not issued by this shop, for example by another shop on the same Midtrans account. Give each shop a different Order ID prefix.

Notification answers Environment mismatch — ignored: the notification was signed with the key of the other environment than the payment was made in.

Notification answers Verification failed, please retry: the Midtrans status API could not be reached. Midtrans retries the notification.

Notification answers Busy, please retry: the cart was being updated by another request at the same moment, or the order could not be created (for example, the module is disabled). Midtrans retries the notification. Look at the log for the reason.

The order is Midtrans payment on hold: read the Midtrans notes in the block. The card payment is under fraud review, the paid amount or currency did not match the order, or the payment arrived after the order was cancelled.

The customer sees an error when choosing Midtrans: look at the Log field on the module page; errors are always logged. A wrong Server Key gives the message that Midtrans payments are temporarily unavailable.

Refund fails: the payment method or transaction state does not allow API refunds; refund in the Midtrans dashboard, and the refund is recorded on the order automatically. If the message says that no Server Key is configured for the environment the order was paid in, enter that key and try again.

Developers can change the data sent to Midtrans with the hook actionWcpMidtransSnapPayload; the order ID and the amount cannot be changed.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Midtrans Payment 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 Midtrans payment references and refunds of orders and the order statuses Awaiting Midtrans payment and Midtrans payment on hold are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes and transaction IDs.

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