VibeFox Pin Payments for Adobe Commerce — Yardım

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

Pin Payments account: a Pin Payments merchant account (for businesses in Australia or New Zealand; customers can pay from anywhere). You need its publishable key and secret key, for live and, for testing, for the test environment. No webhook secret is needed: the module does not use webhooks. Card details are sent from the customer's browser straight to Pin Payments by Pin.js and never reach your store.

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

2. Run bin/magento module:enable Vibefox_PinpaymentsPayment 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 Pin Payments 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. In the Pin Payments dashboard open Account > API Keys and copy your test keys into Test publishable key and Test secret key. Keep Test mode at Yes, set Enable to Yes and click Save Config. Place a test order with a Pin Payments test card. When everything works, enter the live keys, set Test mode to No and click Save Config.

The module adds the Credit card (Pin Payments) 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 two tables for the Pin Payments charge attempts and refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Pin Payments Gateway, in the standard Magento configuration form. The fields form one list; below they are grouped by purpose. 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. The license block and Log are shown in the Default Config only, and Delete data on uninstall is read from the Default Config only. Save Config saves the whole page. Amounts accept "9.99" and "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.).

Gateway notices: this row shows warnings only while Enable is Yes in the Default Config, because the page is shared by all payment methods: Pin Payments: test mode is enabled., Pin Payments: enter both keys of the current environment. and Pin Payments: unsupported currency. Supported: with the list of currencies. It checks the Default Config values and the default display currency, not the scope selected at the top of the page.

General

Enable: shows or hides Pin Payments at checkout. It is shown only when both keys 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: Credit card (Pin Payments). Required, at most 128 characters.

Description: shown in the payment method list at checkout when the customer selects the method. Default: Pay with your credit card via Pin Payments.

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

API keys

Find your keys in the Pin Payments dashboard under Account > API Keys. Test keys work only with the test API, live keys only with the live API. The publishable key is used by Pin.js in the customer's browser. The secret key never leaves your server.

Test mode: uses the Pin Payments test environment (test-api.pinpayments.com) and the test keys. No real charges are made, and customers see TEST MODE — no real charges will be made. under the payment method. At No, the live API and the live keys are used. Default: Yes.

Test publishable key: the publishable key of your Pin Payments test account.

Test secret key: the secret key of your Pin Payments test account.

Live publishable key: the publishable key of your live Pin Payments account.

Live secret key: the secret key of your live Pin Payments account.

Spaces around the keys are ignored. Magento stores the secret keys 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 secret key, clear the field and click Save Config. The module does not check the format of the keys when saving.

Conditions

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

Payment from Specific Countries: offer Pin Payments only for billing addresses in these countries.

Minimum Order Total: offer Pin Payments only from this order total, in the base currency of your store. Empty means no minimum.

Maximum Order Total: offer Pin Payments only up to this order total, in the base currency. Empty means no maximum.

Advanced

Debug log: writes to var/log/wc_ppg_debug.log.php in the Magento folder. The file cannot be opened from the web. Errors and warnings are always logged; set this to Yes to log every API call as well. API keys, card tokens and customer data are never logged. Default: No.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Delete data on uninstall: only settings and log; payment history is retained. When Yes, uninstalling the module with its data deletes the gateway settings and the log (see Uninstall). The license key is always removed. The Pin Payments charges and refunds always stay. Default: No.

Checkout

The payment method is shown when it is enabled, the license is active, both keys of the current mode are set, the currency of the cart is one of the 14 supported currencies (AUD, USD, NZD, SGD, EUR, GBP, CAD, HKD, JPY, MYR, THB, PHP, ZAR, IDR), and the billing country and the order total match Conditions.

At the payment step the customer chooses the payment method (by default Credit card (Pin Payments)), sees the description and fills in Card number, Expiry month, Expiry year, CVC and Name on card. Before sending, the form checks the card number length (12 to 19 digits), a CVC of 3 or 4 digits and that the other fields are filled in; otherwise it shows Please enter your card details and try again.

When the customer clicks Place Order, Pin.js sends the card details and the billing address from the browser directly to Pin Payments and gets a single-use card token. If Pin Payments rejects the card details, the customer sees its message on the payment step and nothing is placed. Then Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. Only the token is sent to your store. The module then creates a captured charge for the order total in the order currency, with the customer's e-mail and the description <store name> - Order <order number>. In currencies without decimals (JPY) the total is rounded to a whole yen. Pin Payments answers in the same request.

After a successful charge Magento creates the invoice with the Pin Payments charge token as the transaction ID, the order becomes Processing and the order e-mail is sent. The customer sees the standard order success page with Your card payment has been received.

If Pin Payments charged a different amount or currency, or authorized the charge without capturing it, the order goes On Hold without an invoice, and the success page shows Your card payment has been received and is being reviewed. We will update your order as soon as the review is complete.

If Pin Payments does not answer (timeout, server error, unreadable answer), a charge may still have been created. The order goes On Hold without an invoice, and the success page shows We could not confirm your payment with Pin Payments. Please check your e-mail and card statement before paying again, or contact us. The order e-mail is also sent for orders that go On Hold. The same order is never charged again.

When the card is declined, the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart with one of these messages: Your card was declined. Please use another card or contact your bank.; Your card has insufficient funds. Please use another card.; Your card has expired. Please use another card.; An error occurred while processing your card. Please try again.; The card security code (CVC) is incorrect.; This card type is not accepted. Please use Visa, Mastercard or American Express.; Payment failed: with Pin Payments' reason for rejected details; Your card details have expired. Please enter them again. when the token cannot be used; Card payments are temporarily unavailable. Please try again later or choose another payment method. when Pin Payments rejects the secret key. The technical reason is written to the log. The secure card form could not be loaded. Please reload the page or choose another payment method. appears on the payment step when Pin.js does not load.

Only one payment attempt per cart runs at a time. A second submit gets This order is already being paid. Please wait and check your e-mail. A cart with an earlier attempt that took or may have taken money is not charged again. A new order of the same cart gets This cart already has a payment. Do not pay again. After a declined card the restored cart can be paid again with a new order and a new card token.

If the payment cannot be started at all, for example because the secret key was removed after the customer opened the checkout, no charge is made and the customer sees Pin Payments is temporarily unavailable. Please choose another payment method. on the payment step. In this case the order stays in Pending Payment until you cancel it or the Magento cron cancels it after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). The same cron cancels orders of customers who closed the browser before the charge.

The module works with the standard Magento checkout. It has no 3-D Secure flow. If your Pin Payments account requires 3-D Secure, the charge stays pending, the order is cancelled, the cart is restored and the customer sees Your card payment could not be completed (additional verification is required). Please use another payment method. There is no authorize-only mode with a later capture, no saved cards, no subscriptions, no Apple Pay or Google Pay and no webhooks. Pin Payments is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed, but the charge has not been made or could not be started. There is no invoice.

Processing: Pin Payments reported a successful, captured charge for exactly the order amount and currency. The invoice is created with the charge token as the transaction ID, and a note shows the charge token.

On Hold: the charge needs your review. No invoice is created. The note shows the reason in brackets and the charge token: review (Pin Payments charged an amount or currency different from the order), uncaptured (the charge is authorized but not captured) or unknown (Pin Payments gave no clear answer). Check the charge in the Pin Payments dashboard, then fulfil the order or refund the charge there.

Canceled: the card was declined, the charge needed 3-D Secure, or the order was cancelled in Magento. If a charge is reported for an order that no longer waits for payment, the order is not fulfilled automatically: a note asks you to review the charge in the dashboard.

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

The notes are order comments that the customer does not see.

Pin Payments payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, for the Pin Payments payment, Environment (test or live), Pin Payments charge (the charge token), Charged amount, Card (the card brand and last four digits) and, after a refund, Refund status. 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 Pin Payments. 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 Pin Payments.

The refund is made for the credit memo total in the order currency, up to the amount Pin Payments charged minus the amounts already refunded. In JPY a credit memo total with decimals is rounded so that all refunds add up to the amount charged, and the credit memo that refunds the order completely returns exactly what is left of the charge. The refund is sent in the mode the payment was made in (test or live), so that mode's secret key must be set. Pin Payments processes refunds asynchronously: Refund status shows Pending. After a successful request Magento records the refund on the order with the Pin Payments refund token as the transaction ID. A full refund closes the order.

If Pin Payments rejects the refund or does not answer, Magento shows Pin Payments did not confirm the refund. Check the charge in the dashboard before trying again. and the credit memo is not created. After an unclear answer, or when a refund was accepted but its credit memo could not be saved, the module refuses further online refunds of that order, so the money cannot be sent twice. Check the charge in the Pin Payments dashboard, finish the refund there if needed and create a credit memo with Refund Offline.

Refunds made in the Pin Payments dashboard are not synced back to Magento. Create a credit memo with Refund Offline or update the order manually if needed. An order without an invoice (On Hold) cannot be refunded online; refund it in the Pin Payments dashboard.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Pin Payments Gateway is the first row of the VibeFox Pin Payments 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-pinpayments 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, Pin Payments is not shown to customers at checkout. If a payment is started anyway, no charge is made, the customer sees This payment method is not available. Please choose another one. on the payment step, and the order stays in Pending Payment until it is cancelled. 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: refunds of orders paid before still 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

Pin Payments does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, that both keys of the current mode are filled in (Test publishable key and Test secret key in test mode, the live keys otherwise) and that the currency of the cart is one of the 14 supported currencies. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total.

The payment went through, but the order is On Hold: read the order notes (see Order statuses). If Pin Payments gave no clear answer, look in the Pin Payments dashboard for a charge with the order number in its description, then fulfil the order or refund the charge in the dashboard.

The order stays Pending Payment: the charge was not made, or Magento could not record the answer. The customer may have closed the browser before the charge, or may have seen We could not confirm your payment. Check your e-mail and card statement before trying again. Before you cancel such an order, look for its number in the Pin Payments dashboard. The module has no webhooks, so a later charge is not reported to Magento.

Customers see Card payments are temporarily unavailable: Pin Payments rejected the secret key. Test keys work only in test mode, live keys only in live mode. The log shows the reason. The order of that attempt is cancelled.

Orders fail with additional verification is required: your Pin Payments account requires 3-D Secure, which the module does not support. Ask Pin Payments to turn off mandatory 3-D Secure.

The secure card form could not be loaded: Pin.js from the Pin Payments CDN (cdn.pinpayments.com) did not load in the browser, for example because of a script blocker or a module that combines or changes scripts. Exclude the checkout from such optimizations. The module adds the Pin Payments addresses to the Magento Content Security Policy.

Payment failed with a Pin Payments reason: Pin Payments rejected the charge details, for example an amount below its minimum charge for the currency. The customer sees the reason, and the log has the error code. The order of that attempt is cancelled.

Refund fails with The secret key of the payment environment is not configured: the secret key of the mode the order was paid in is empty. Enter it and try again.

Refund fails with Refund exceeds the remaining charge or has an invalid currency/amount: the credit memo total is larger than the amount still refundable from the charge, or the order currency differs from the charged currency. Refund such an amount in the Pin Payments dashboard and create a credit memo with Refund Offline.

Refund fails with A previous refund is unconfirmed or its credit memo is missing: an earlier refund of this order got no clear answer, or Pin Payments accepted it and Magento could not save the credit memo. Check the charge in the Pin Payments dashboard and finish the refund there, then create 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 (for example On Hold) cannot be refunded online; refund it in the Pin Payments dashboard.

Test payments: test mode uses the test environment and the test keys. Use the test cards from the Pin Payments developer documentation. Orders keep the mode they were paid in, so refunds go to the right environment after you switch modes.

Where to find errors: errors are always written to the log; see the Log field on the settings page in the Default Config. Set Debug log to Yes to see every API call.

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

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

The license key and license status are always removed. If Delete 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 Pin Payments charges 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.

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