EN
EUR
Back

VibeFox Midtrans for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

WooCommerce: 8.0 or later, installed and active. Without WooCommerce the plugin refuses to activate.

PHP: 8.0 or later.

Store currency: Indonesian Rupiah (IDR). For other currencies the payment method is hidden at checkout. There is no currency conversion.

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 WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_midtrans_payment_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Set the store currency to Indonesian Rupiah (IDR).

4. Open the settings: WooCommerce > Settings > Payments > Midtrans > Manage, or click Settings under the plugin name on the Plugins page.

5. Enter your VibeFox license key in the license block at the top of the page and click Activate.

6. Enter the Server Keys and copy the payment notification URL into the Midtrans dashboard (see Configuration).

7. Turn on Enable/Disable. Test in Sandbox, then switch Environment to Production.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Midtrans. 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 store currency is not IDR, and shows Sandbox mode: payments are simulated, no real money is charged. while Sandbox is selected. In the list of payment methods, Midtrans is marked as needing setup until a Server Key is entered and shows Test mode in Sandbox.

General

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

Title: the payment method title shown to customers at checkout. Default: Midtrans.

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. Orders keep the environment they were paid 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-.

Payment notification URL

The notification tells your store that a payment has been made. The section shows the URL to use. It looks like https://your-site/wc-api/midtrans_p_callback/. 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 order. Notifications without a valid signature are rejected. The status is then re-read from the Midtrans status API. The plugin handles these Midtrans transaction statuses:

settlement, capture (accepted): the payment was made. The order is marked paid when the amount (whole rupiah) and currency match.
capture (challenge): a card payment flagged by Midtrans fraud detection. The order is put 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 put on hold.
expire: the unpaid transaction expired. The order is cancelled and the stock returned. An abandoned card payment does not change the order.
cancel: the transaction was cancelled. The order is cancelled.
deny: the payment was denied. A challenged order on hold becomes Failed; otherwise a note is added and the customer can try again.
failure: the payment failed. The order becomes Failed.
refund, partial_refund: a refund made in the Midtrans dashboard is recorded as a WooCommerce refund.

Without the notification URL, an order is confirmed only when the customer returns to the store after paying.

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. The status is set in one step, without double customer e-mails.

Processing: follows the WooCommerce defaults; virtual downloadable-only orders become Completed (default).
Completed: every paid order becomes Completed.
On hold: every paid order waits for your manual review.

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.

Order ID prefix: added to the order number sent to Midtrans, so several stores can share one Midtrans account. Letters, digits and - _ . ~ only, up to 20 characters; other characters are removed on save. Notifications of other stores are ignored. Default: WC-.

Advanced

Debug log: Log API calls and notifications writes to WooCommerce > Status > Logs, source wcp_midtrans_payment_gateway. Errors are always logged. Keys and customer data are never logged. Default: off.

Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted (deactivation keeps everything). Order data is kept. Default: off.

Checkout

The customer chooses the payment method (by default Midtrans) and places the order. The plugin creates a Midtrans Snap transaction for the order total in whole rupiah, with the order lines, shipping, 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.

After paying, the customer returns to the order received page of your store. The return link itself never marks an order paid: the plugin asks the Midtrans status API, and the order is marked paid only after Midtrans confirms it. While the payment is not confirmed, 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. The page also shows the payment method used.

If the payment was not completed, the customer is sent to the Pay for order page with The Midtrans payment was not completed. You can try again below. If it was declined or has expired, the message is Your Midtrans payment was declined or has expired. Please try again or choose another payment method. 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 confirmed and no new transaction is created.

If Midtrans cannot start the payment, the customer sees 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 added to the order notes.

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin 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 WooCommerce Subscriptions. Card payments are captured immediately, with no separate authorize and capture.

Orders and refunds

Order statuses

Pending payment: the customer was sent to Midtrans and has not chosen a payment method yet.

On hold: the customer chose a delayed method and has not paid yet, the card payment is under fraud review (challenge), or the paid amount or currency did not match the order. On hold is also set when a payment arrives for a cancelled order; the order is not re-opened automatically. The order note explains it.

Processing, Completed or On hold after payment: the payment was confirmed. The status follows Status after payment. The order note shows the payment method and the Midtrans IDs. The transaction ID is the Midtrans transaction ID, and on the order screen it links to the transaction in the Midtrans dashboard of the order's environment.

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

Cancelled: the unpaid transaction expired or was cancelled. The stock is returned. When you cancel an unpaid Midtrans order in WooCommerce (or the unpaid-order timer does), its pending Midtrans transaction, for example an issued virtual account, is expired so it can no longer be paid.

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

Refunds

Open the order, click Refund, enter the amount and click Refund via Midtrans (the button shows your Title). Full and partial refunds are supported in whole rupiah; an amount with decimals is refused. The refund is sent in the environment the order was paid 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, WooCommerce shows the error and no refund is recorded; then refund in the Midtrans dashboard. A successful refund is added to the order notes.

Refunds made in the Midtrans dashboard arrive by the notification and are recorded as WooCommerce refunds automatically, with the reason Refunded in the Midtrans dashboard.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Midtrans. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site 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. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

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 store currency (or the order currency on the Pay for order page) is IDR. The settings page shows a warning for each of these problems.

The payment went through, but the order stays Pending payment: 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) 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 confirmed when the customer returns to the store 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 does not belong to an order of this store, for example from another store on the same Midtrans account. Give each store a different Order ID prefix.

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

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

The order is On hold: read the order note. The customer has not finished a delayed payment, the card payment is under fraud review, or the paid amount or currency did not match the order.

The customer sees an error when placing the order: open the order notes or turn on Debug log and look at WooCommerce > Status > Logs, source wcp_midtrans_payment_gateway. A non-IDR order gives Midtrans only supports payments in IDR (Indonesian Rupiah). Please choose another payment method.

Refund fails: the payment method or transaction state does not allow API refunds; refund in the Midtrans dashboard, and the refund is recorded in WooCommerce 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.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings and the logs are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes and transaction IDs.

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