VibeFox GMO 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: Japanese Yen (JPY). GMO-PG charges yen only, so the payment method is shown only when the customer's checkout currency is JPY. JPY must be an allowed currency of the store in Stores > Configuration > General > Currency Setup; when your base currency is not JPY, a JPY currency rate is needed in Stores > Currency Rates.
GMO Payment Gateway account: a GMO-PG merchant contract with Link Type Plus. You need the Shop ID, the Shop password and the Link Type Plus Config ID (設定ID) of the test and/or production environment, and the result notification (結果通知) turned on in the GMO-PG shop console (see Configuration). The Site ID and Site password are not used.
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-gmo-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/GmoPayment/, so that registration.php is directly in that folder.
2. Run bin/magento module:enable Vibefox_GmoPayment 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 GMO 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 Shop ID, Shop password and Config ID of the test and/or production environment and choose the Environment. In the GMO-PG shop console turn on 結果通知 (result notification) and set the notification URL shown in the settings (see Configuration). Set Enable to Yes and click Save Config. Make a test payment in the test environment, then switch Environment to Production (live).
The module adds the Credit card 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 GMO-PG payment attempts, their events and the capture, cancel and refund operations.
Configuration
All settings are in Stores > Configuration > Sales > Payment Methods > GMO Payment 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 set in the Default Config only. Save Config saves the whole page. Spaces around the values are removed when you save.
If a value is wrong, Magento shows an error and nothing on the page is saved: GMO-PG title is required and must not exceed 128 characters., Sort order must be a whole number., or Order total must be a number, 0 or greater. for a Minimum Order Total or Maximum Order Total that is not a number such as 1000 or 1000.5 (with a dot).
When Enable is Yes, Magento shows warnings after Save Config: GMO-PG credentials are missing: Shop ID, Shop password and Config ID are required. when the credentials of the current environment are not complete (the payment method is then hidden at checkout), and GMO-PG accepts Japanese Yen (JPY) only. It is hidden for other checkout currencies. when the currency of the default store view is not JPY. The warnings are shown only while the module is enabled, because the Payment Methods page is shared by all payment methods.
General
Enable: shows or hides the GMO-PG card payment at checkout. It is shown only when the current environment has its Shop ID, Shop password and Config ID. Default: No.
Title: the payment method name customers see at checkout. It is also stored in the order. Default: Credit card. Required, at most 128 characters.
Description: shown in the payment method list at checkout when the customer selects the method. Default: You will be redirected to the secure GMO Payment Gateway page to pay by credit card.
GMO-PG account
The Shop ID and Shop password are in the GMO-PG shop console under Shop management > Shop information, the Config ID under Link Type Plus > Settings (設定ID). The test and production environments have different credentials.
Environment: which GMO-PG environment takes new payments.
Test Shop ID: the Shop ID of the test environment.
Test Shop password: the Shop password of the test environment.
Test Config ID: the Link Type Plus config ID (設定ID) of the test environment.
Production Shop ID: the Shop ID of the production environment.
Production Shop password: the Shop password of the production environment.
Production Config ID: the Link Type Plus config ID (設定ID) registered in the GMO-PG console for production.
Magento stores the passwords encrypted and shows only a mask (******) after saving. Leave the mask as it is to keep the saved password, type a new value to change it. To delete a saved password, clear the field and click Save Config.
Payments already started stay in their environment: their refunds, captures and checks always use the credentials of the environment the payment was made in, so keep both sets of credentials while old payments may still need them.
Payment
Capture: when the card is charged.
Order status after payment: the status of a paid order.
Conditions
Payment from Applicable Countries: All Allowed Countries offers the card payment for every country your store allows, Specific Countries only for the countries below.
Payment from Specific Countries: offer the card payment only for billing addresses in these countries.
Minimum Order Total: offer the card payment only from this order total, in the base currency of your store. 0 or empty means no minimum.
Maximum Order Total: offer the card payment only up to this order total, in the base currency. 0 or empty means no maximum.
Sort Order: the position among the payment methods at checkout. A whole number.
Independently of these settings, GMO-PG accepts order totals from 1 to 9,999,999 JPY. Larger totals hide the payment method.
Payment notifications (結果通知)
Below the fields the group shows GMO-PG Link Type Plus: whole JPY, capture immediately or authorize and capture from the order. and the Result notification URL. It is the storefront address of the default store view and looks like https://your-store/wcpgmopayment/checkout/notify/. In the GMO-PG shop console of each environment you use, turn on 結果通知 (result notification) and set this URL. Copy the URL exactly as the settings show it. It must be reachable from the Internet.
GMO-PG notifications are not signed, so the module never trusts their content. The notification must come from a Shop ID entered in the settings and refer to a payment created by this store, in the environment the payment was made in. The module then asks GMO-PG for the transaction (SearchTrade) with your Shop password and changes the order only from that answer. A notification that does not match a real transaction changes nothing. Transactions not created by the store, for example ones made in the GMO-PG console, are acknowledged and ignored. When the module cannot check a notification, it answers so that GMO-PG sends it again.
Without the notification, an order is confirmed when the customer comes back to the store after paying, or by the scheduled check of the Magento cron, which asks GMO-PG about open payments every 5 minutes.
Advanced
Debug Log: writes API requests and notifications to var/log/gmo_pg_debug.log.php in the Magento folder. The file cannot be opened from the web. Errors and warnings are always logged, even while the switch is off. Passwords and customer data are masked. Default: No.
Log: shows the size and the latest entries of the log. Click Clear log to empty it.
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 GMO-PG payment history always stays, so old orders can still be captured and refunded. Default: No.
Checkout
At the payment step the customer chooses the payment method (by default Credit card) and sees its description and the note You will be redirected to GMO Payment Gateway. 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 GMO-PG Link Type Plus payment for the order total in yen, rounded to whole yen, and sends the customer to the GMO-PG payment page. There the customer pays by credit card. 3-D Secure 2.0 is handled by GMO-PG, and the customer's e-mail is passed to it for 3-D Secure. The payment page opens in Japanese, Chinese or English, following the locale of the store view. The payment shows at GMO-PG with a GMO OrderID made from the cart number. No other customer data is sent.
After paying, the customer returns to your store. The signed result is checked with the Shop password of the payment's environment, and the order is marked paid only after GMO-PG confirms it: by a server-side SearchTrade request when the customer returns, by the result notification or by the scheduled check. All of them use the same logic, so the order is never invoiced twice. Magento then creates the invoice with the GMO-PG transaction ID, sets the status from Order status after payment 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 GMO-PG has not confirmed the payment yet, the customer sees a GMO-PG payment confirmation page with Your payment is being confirmed. Please check again. and a Check again link; the notification or the scheduled check confirms the order as soon as GMO-PG reports the payment. With Authorize only the page shows Your card payment is authorized and awaiting capture by the store., and the order e-mail is sent. When the payment needs your review (see Orders and refunds), the page shows Your GMO-PG payment needs manual review. Contact the store.
If the card is declined, the unpaid payment link is closed, the order is cancelled (the stock goes back), the cart is restored and the customer sees Your GMO-PG card payment was declined. Please try again or choose another method. If the customer leaves the GMO-PG page without paying, the message is Your GMO-PG payment was not completed. Please try again or choose another method. Each new attempt for the same cart first checks the previous payment links at GMO-PG and closes the unpaid ones, so the cart cannot be paid twice.
If the payment cannot be started, for example because of wrong credentials, the order is cancelled, the cart is restored and the customer sees GMO-PG payment was not completed. Please try again or choose another method. If the result of the start request is uncertain, or an earlier payment of the same cart may already be paid, no new payment is started and the customer sees GMO-PG could not start or an earlier payment is uncertain. Contact the store before retrying. with a Check again link. The reason is written to the log.
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), its unpaid GMO-PG payment link is closed and can no longer be paid. A payment attempt whose start failed never got a link: it is marked failed and does not hold up the cancellation.
Before the cancellation, the module asks GMO-PG about the payment. If GMO-PG cannot be reached, the Shop password of the environment the payment was made in has been removed, or GMO-PG reports the payment as already made (the notification did not arrive), the Magento cron leaves the order in Pending Payment, adds a note that starts with GMO-PG could not confirm that this order is unpaid, so the automatic cancellation was skipped and goes on with the other expired orders. The next cron run tries again, and the scheduled check confirms a payment that was made. When you cancel such an order yourself in the Admin, the cancellation is refused with a message, for example GMO-PG transaction lookup failed. No new operation was sent. Use Check payment / reconcile refund (GMO-PG) first.
The module works with the standard Magento checkout. It takes credit card payments in JPY only, always on the GMO-PG page. It has no other GMO-PG payment methods, no other currencies, no saved cards or GMO-PG member registration, no installments, no subscriptions or recurring billing and no on-site card form. The card payment is not offered for orders created in the Admin or for checkout with multiple addresses.
Orders and refunds
Order statuses
Pending Payment: the order was placed and the customer was sent to GMO-PG, but GMO-PG has not confirmed the payment yet. There is no invoice.
Processing or Complete: the payment was confirmed. The status follows Order status after payment. The invoice is created with the GMO-PG TranID as the transaction ID, and a note shows the amount, the GMO-PG status and how it was confirmed (notification, return or cron).
On Hold (authorized): with Authorize only the amount was authorized. There is no invoice yet. Capture it with Capture payment (GMO-PG) before the authorization expires; the order then gets the invoice and the status from Order status after payment.
On Hold after a mismatch: GMO-PG reported a different amount than the order total. No invoice is created. The note says Manual review; no new native invoice. Check the payment, then fulfil the order or return the money with the review action of the GMO-PG block.
Canceled: the card was declined, the customer did not complete the payment, the payment could not be started, the payment or authorization was cancelled at GMO-PG, or the order was cancelled in Magento.
Closed: the payment was fully refunded with a credit memo.
A payment that arrives after the order was cancelled is not invoiced either; a note asks for review. If a second payment arrives for a cart whose order is already paid, no second invoice is created. The payment is marked duplicate and a note asks for review. The notes are order comments that the customer does not see.
GMO-PG payment information
On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, once known, GMO OrderID, Transaction, Environment and Payment status.
On the Information tab the GMO-PG payment history block lists every payment attempt of the order with the GMO OrderID and transaction, the environment, the requested amount and capture type, the amount taken and the amount remaining at GMO-PG, and the status. Below it, GMO-PG operation history lists the captures, cancellations and refunds with their amounts and the Magento document they belong to. The block buttons are:
Capture
Click Capture payment (GMO-PG) in the block of an authorized order. The module checks the transaction at GMO-PG, takes the order off hold and creates the invoice with online capture, which charges the authorized amount. Only the whole authorized amount can be captured, and the invoice must match it. On success the message is GMO-PG payment captured and native invoice created. If the capture fails, the order goes back on hold and Magento shows the reason, for example GMO-PG capture requires an AUTH and a native invoice matching the entire remaining authorization. When your base currency is not JPY, the full invoice is captured for the exact JPY order total.
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 GMO-PG. Full and partial refunds are supported, in whole yen: a credit memo total with a fraction of a yen is refused with Use a native Credit Memo for a whole-yen GMO-PG refund. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through GMO-PG.
The limit is the amount GMO-PG actually took and still holds. Refunding the whole remaining amount cancels the GMO-PG transaction; a partial refund lowers the transaction amount. The refund is sent to the environment the payment was made in, so that environment's Shop ID and Shop password must be set. Each refund is checked at GMO-PG before Magento records it. If GMO-PG does not accept the refund or its result is uncertain, Magento shows the error and the credit memo is not created. If GMO-PG accepted a refund that Magento could not record, the next check (notification, cron or Check payment / reconcile refund (GMO-PG)) creates the credit memo without refunding again. A full refund closes the order.
Refunds and cancellations made in the GMO-PG console are seen by the next notification or check and added to the order notes. The order and credit memos are not changed automatically, except that an unpaid order or authorization cancelled at GMO-PG cancels the order. Create a credit memo with Refund Offline or update the order manually if needed.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox GMO Payment Gateway is the first row of the GMO 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-gmo 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, the GMO-PG card payment is not shown to customers at checkout. If a payment is started anyway, no GMO-PG payment is created: the order is cancelled, the cart is restored and the customer sees GMO-PG payment was not completed. Please try again or choose another method. 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 captures 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
Credit card does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, that the customer's checkout currency is JPY and that the current Environment has its Shop ID, Shop password and Config ID. Order totals above 9,999,999 JPY cannot be paid by card. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total (in the base currency).
The payment went through, but the order stays Pending Payment: the result notification is not working. In the GMO-PG shop console of the environment you use, check that 結果通知 is on and that the URL is exactly the one shown in Result notification URL. Check that the Shop ID and Shop password of that environment are filled in for the website of the order, because the module verifies each notification with them. Check that the Magento cron is running: the scheduled check also confirms open payments every 5 minutes. The order is also confirmed when the customer returns to the store after paying. Turn on Debug Log and look at the Log field.
Notifications fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the notification URL too. GMO-PG sends the notification again, and the scheduled check and the customer's return also confirm the payment.
Notifications are rejected: the notification came with a Shop ID that is not in the settings, or the password of that environment is missing. Enter the Shop ID and Shop password of that environment. Test and production payments are kept apart: a test notification never confirms a production payment and the other way round.
The customer is back in the cart after Place Order: turn on Debug Log and look at the Log field. The log shows the GMO-PG error code (ErrCode, ErrInfo). A wrong Shop ID, Shop password or Config ID is the usual reason. The order of that attempt is cancelled.
The customer sees GMO-PG could not start or an earlier payment is uncertain: an earlier payment of the same cart could not be checked or closed at GMO-PG. Open the order in the Admin, click Check payment / reconcile refund (GMO-PG) and look at the GMO-PG payment history before the customer tries again.
Order is On Hold: read the order notes and the GMO-PG payment history block. The order was authorized only and waits for capture, or the paid amount differed from the order total and needs review.
Capture or refund fails: read the message. The payment may have been made in the other environment, whose Shop ID and password are not set (The original GMO-PG environment credentials are missing.), the transaction may already be cancelled at GMO-PG, or the amount may exceed what is left on the transaction. GMO-PG is busy. Please retry. means a notification was being processed at the same time. A GMO-PG operation is pending or uncertain. Check its status before retrying. means an earlier operation is not verified yet: click Check payment / reconcile refund (GMO-PG) first.
The native invoice amount cannot be represented in whole JPY: GMO-PG takes whole yen only. Orders whose JPY total has a fraction of a yen cannot be captured or refunded online; use the GMO-PG console and record the result in Magento.
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 (authorized only, or On Hold after a mismatch) cannot be refunded with a credit memo; use the actions of the GMO-PG block.
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.
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_GmoPayment. It removes the data and the code.
Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_GmoPayment to remove the data, then bin/magento module:disable Vibefox_GmoPayment, delete the folder app/code/Vibefox/GmoPayment 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 GMO-PG payment attempts, events and operations are always kept, so orders paid before can still be captured and refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.
GMO Payment Gateway is a trademark of its respective owner. This module is not affiliated with or endorsed by GMO Payment Gateway.