VibeFox Midtrans for Adobe Commerce — सहायता

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

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. Allow IDR in Stores > Configuration > General > Currency Setup if your store 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

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

2. Run bin/magento module:enable Vibefox_MidtransPayment 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 Midtrans Payment 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 Server Keys and copy the notification URL into the Midtrans dashboard (see Configuration). Set Enable to Yes and click Save Config. Test in Sandbox, then switch Environment to Production.

The module adds the Midtrans 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 three tables for the Midtrans payment attempts, their events and refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Midtrans Payment Gateway, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website or a store view with the Scope switcher at the top of the page. Delete settings on uninstall should be set in the Default Config. Save Config saves the whole page.

If the Title is empty, Magento shows Enter a title for the payment method. and nothing on the page is saved. If Payment page expiry (minutes) is not a whole number, Magento shows Payment page expiry (minutes) must be a whole number of minutes. Leave it empty or 0 for the Midtrans default. and nothing on the page is saved either.

The row Setup at the top of the group shows the Notification URL (see Payment notification URL) and the line Add it in Midtrans Dashboard / Settings / Payment / Notification URL. Only the Server Key is required for Snap Redirect. While Enable is Yes, it also shows warnings: SANDBOX MODE: use test payment methods only. while Sandbox is selected, Enter the Server Key for the selected environment. when the key of the selected environment is missing (the payment method is then hidden at checkout) and Midtrans supports IDR only. This store currency is not IDR.

General

Enable: shows or hides the payment method at checkout. Default: No.

Title: the payment method name shown to the customer 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, above the line You will be redirected to Midtrans to complete your payment. Default: Pay securely via Midtrans — GoPay, QRIS, ShopeePay, cards, bank transfer and more. In Sandbox the customer also sees SANDBOX MODE: use test payment methods only.

API credentials

Copy the Server Key from Midtrans Dashboard > Settings > Access Keys.

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.

Production Server Key: the Server Key of the production dashboard. Keep it secret.

Clear saved production server key: set to Yes and click Save Config to delete the saved production key. The field goes back to No after saving.

Sandbox Server Key: the Server Key of the sandbox dashboard.

Clear saved sandbox server key: set to Yes and click Save Config to delete the saved sandbox key.

Magento stores the Server Keys encrypted and shows only a mask (******) after saving. Leave the mask or the empty field as it is to keep the saved key (Blank retains the saved key.), type a new value to change it. To delete a saved key, use the matching Clear saved … field.

Payment notification URL

The notification tells your store that a payment has been made. The Setup row shows the Notification URL: the storefront address of the store view of the selected scope (the default store view in the Default Config and for a website). It looks like https://your-store/wcpmidtranspaymentgateway/webhook/index. 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 answers Midtrans notification endpoint., 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 (the keys of the store view of the payment), 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 status in the notification itself is never trusted. The module handles these Midtrans transaction statuses:

Without the notification URL, a payment is confirmed only when the customer returns to the store after paying, and a delayed payment made later is not seen.

Payment settings

Midtrans charges in IDR only, and amounts are sent in whole rupiah (the order total is rounded). 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.

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 number sent to Midtrans, so several stores can share one Midtrans account. The number is the cart ID with a time stamp, for example MG-123-1700000000. Only letters, digits and - _ . ~, at most 20 characters. Other characters are removed on save. Notifications of other stores are ignored. Default: MG-.

Advanced

Debug logging: writes API calls and notifications to var/log/midtrans_p_debug.log.php in the Magento folder. The file cannot be opened from the web and is rotated at 5 MB. Errors and warnings are always logged, also while this setting is No. Server Keys are never logged; contacts and long numbers are masked. Default: No.

Delete settings 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 Midtrans payment records and refunds always stay, so orders paid before can still be refunded after a re-install. Default: No.

Debug log: shown in the Default Config. It shows the size and the last 50 KB of the log. Click Clear log to empty it.

Checkout

At the payment step the customer chooses the payment method (by default Midtrans), sees the description and clicks Place Order. Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module creates a Midtrans Snap transaction for the order total in whole rupiah, with the order lines, shipping, discounts, 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. The payment step is made for the standard Magento checkout (Luma); other checkout themes may need adaptation.

After paying, the customer returns to your store. 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. A confirmed payment creates the invoice with the Midtrans transaction ID, sets the order status from Status after payment and sends the order and invoice e-mails. The customer sees the standard order success page with Your Midtrans payment has been verified.

For a delayed payment, or when the customer came back without paying, the success page shows Awaiting Midtrans payment confirmation. Your order will be updated when payment is confirmed. and a Continue payment link back to the payment page. An unused or pending Snap of the same amount is reused; if the amount changed, the pending transaction is expired at Midtrans first. An order put on hold shows Your Midtrans payment requires review. Please do not pay again. If the payment was closed without payment, the order is cancelled, the cart is restored and the customer sees The Midtrans payment was closed without payment. Please place a new order or contact us. A customer who returns in another browser is sent to the home page with Midtrans payment confirmation was checked. Please view your order details or contact the store.

If Midtrans refuses to start the payment, the order is cancelled (the stock goes back), the cart is restored and the customer sees Midtrans could not create the payment. Please check your billing details or contact the store. in the cart, for example with a wrong Server Key. A non-IDR order gives Midtrans requires a positive order total in IDR. Other unexpected errors show Midtrans is temporarily unavailable. Please try again. If the result of the request is unknown or the cart is being updated at the same moment, a Payment confirmation page explains it with a Check again link, and no second transaction is created blindly. A cart that is already paid is never charged again: a new order of that cart is cancelled and the customer is sent to the paid order.

An order that stays unpaid may be cancelled by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). When an unpaid Midtrans order is cancelled, by the cron or by you, its pending Midtrans transaction, for example an issued virtual account, is expired so it can no longer be paid.

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. Midtrans is not offered for orders created in the Admin or for multishipping checkout.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer has not paid yet, or chose a delayed method (virtual account, convenience store) and Midtrans has not reported the payment. There is no invoice.

Processing, Complete or On Hold: the payment was confirmed. The status follows Status after payment. The invoice is created with the Midtrans transaction ID, and the note Midtrans payment verified: shows the amount, the payment method and the Midtrans order ID.

On Hold without an invoice: a card payment is under fraud review (challenge), or the paid amount or currency did not match the order (the note Midtrans amount/currency mismatch: shows the actual charge). Check the order, then approve the payment in the Midtrans dashboard or refund it (see Refunds without an invoice).

Canceled: the payment expired, was cancelled, denied or failed, or the payment could not be started. If a payment arrives for a cancelled order, the order is not re-opened and the note Midtrans payment received after cancellation. Reconcile or refund it; the order was not reopened. is added.

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

If another payment arrives for a cart that is already paid, the order is not changed and a note asks you to refund the extra payment in the Midtrans dashboard. The notes are order comments that the customer does not see.

Midtrans payment history

On the admin order page (Sales > Orders > View, Information tab) the section Midtrans payment history lists every payment attempt of the order: Midtrans order ID, transaction ID, mode (sandbox or production), result, detail, the requested amount in IDR and the amount and currency Midtrans received. It is shown also when the module is disabled. The customer sees only the payment method title.

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 Midtrans in IDR. 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 Midtrans.

Midtrans refunds in whole rupiah. Magento keeps totals with decimals, so the credit memo amount is rounded like the charge, and the credit memo that refunds the rest of the order refunds exactly what is left of the charge. You can refund up to the amount Midtrans actually charged. 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, Magento shows the error and the credit memo is not created; then refund in the Midtrans dashboard. A full refund closes the order.

Refunds made in the Midtrans dashboard arrive by the notification and are recorded automatically as an offline credit memo with the comment Verified Midtrans dashboard refund and a note. No money is sent again.

Refunds without an invoice

A charge without a paid invoice (an order On Hold after a mismatch, or a payment that arrived after cancellation) cannot be refunded with a credit memo. Under Midtrans payment history the order page then shows This received charge has no paid invoice. Refund it here; no artificial Invoice or Credit Memo will be created., an amount field with the amount not refunded yet and the button Refund received payment. Confirm This cannot be undone. Refund this amount?. You need the Admin permission to create credit memos. The amount must be whole rupiah. After Midtrans refund accepted. a note records the refund. When the whole charge is refunded, the order is cancelled.

License key

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

Midtrans does not appear at checkout: check that the license is active and Enable is Yes for the store, and that the selected Environment has its Server Key. Check that the cart currency is IDR. The Setup row shows a warning when the key is missing or the store currency is not IDR.

The payment went through, but the order stays Pending Payment: the notification is not working. Check that the 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 answers Midtrans notification endpoint. Set Debug logging to Yes to see the notifications. The payment 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, and that they are set for the store view where customers pay.

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

Notification answers Foreign order ignored.: the Midtrans order ID was not issued by this store, for example by 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 payment was made in.

Notification answers Verification unavailable, retry. or Busy, retry.: the Midtrans status API could not be reached, or the order was being updated by another request at the same moment. Midtrans retries the notification. Look at the log for the reason.

Notifications fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the notification URL too. Midtrans retries the notification later, and the payment is also confirmed when the customer returns.

Order is On Hold after payment: read the order notes and Midtrans payment history. The card payment is under fraud review, the paid amount or currency did not match the order, or Status after payment is On Hold.

The customer is back in the cart with Midtrans could not create the payment.: Midtrans refused the request, for example because of a wrong Server Key or customer data that Midtrans does not accept. Look at the log; errors are always logged.

Refund fails with The original charge cannot be verified for refund. or The saved Midtrans environment has no Server Key.: the Server Key of the environment the payment was made in is not set, or Midtrans could not be reached. Enter the key and try again.

Refund fails with Midtrans did not approve this refund. No native Credit Memo was saved.: the payment method or transaction state does not allow API refunds. Refund in the Midtrans dashboard; the refund is recorded on the order automatically.

Refund fails with Midtrans refund failed or its result is uncertain. No native Credit Memo was saved.: Midtrans did not answer clearly. Check the payment in the Midtrans dashboard before trying again. A retry with the same amount is matched to the earlier refund instead of sending a new one.

Refund fails with Provider refunds differ from native history. Verify or sync them first.: Midtrans has refunds that Magento has not recorded yet, for example a refund in the Midtrans dashboard whose notification has not arrived. Wait for the notification, or record the refund with a credit memo with Refund Offline.

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 is refunded with Refund received payment (see Refunds without an invoice).

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 data sent to Midtrans with the Magento event midtrans_p_snap_payload; the order ID, the amount and the return URL cannot be changed.

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

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

The license key and license status are always removed. If Delete settings 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 Midtrans payment records 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.

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