VibeFox Pin Payments for WooCommerce — Help
Requirements
WordPress: 6.2 or later.
WooCommerce: 7.1 or later, installed and active. The plugin refuses to activate without it.
PHP: 8.0 or later.
HTTPS: your checkout must use HTTPS, as needed for taking card payments (PCI DSS). Card details are sent from the customer's browser straight to Pin Payments by Pin.js and never reach your server, so the store falls under PCI SAQ A-EP.
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 plugin does not use webhooks.
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_pinpayments_gateway folder to /wp-content/plugins/ by FTP.
2. Click Activate.
3. Open the settings: WooCommerce > Settings > Payments > Pin Payments > Manage, or click Settings under the plugin name on the Plugins page.
4. Enter your VibeFox license key in the license block at the top of the page and click Activate.
5. 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 on, turn on Enable/Disable and save.
6. Place a test order with a Pin Payments test card. When everything works, enter the live keys, turn off Test mode and save.
Configuration
All settings are on one page: WooCommerce > Settings > Payments > Pin Payments. Above the fields the page shows a notice while test mode is on, an error while the publishable key or the secret key of the current mode is empty, and an error when Pin Payments does not support the store currency (with the list of supported currencies). In the last two cases the gateway is hidden at checkout. After you save, the notices already reflect the new mode and keys. In the list of payment methods the gateway is marked as needing setup until the current mode has both keys.
Enable/Disable: Enable Pin Payments turns the payment method on or off. Default: off.
Title: the payment method title shown at checkout. Default: Credit card (Pin Payments).
Description: the payment method description shown at checkout. Default: Pay with your credit card via Pin Payments.
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: Enable 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. in the card form. When it is off, the live API (api.pinpayments.com) and the live keys are used. Default: on.
Test publishable key: the publishable key of your Pin Payments test account.
Test secret key: the secret key of your Pin Payments test account. It is a password field.
Live publishable key: the publishable key of your live Pin Payments account.
Live secret key: the secret key of your live Pin Payments account. It is a password field.
Spaces around the keys are removed. Both keys of the current mode must be filled in, otherwise the gateway is not shown at checkout.
Advanced
Debug log: Log Pin Payments API calls to WooCommerce > Status > Logs, source wcp_pinpayments_gateway. Errors are always logged; turn this on to log every API call as well. Card data, API keys and customer personal data are never logged. Default: off.
Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted. Deactivating the plugin never deletes anything. Payment data stored on orders is always kept. Default: off.
Checkout
The customer chooses the payment method (by default Credit card (Pin Payments), with Visa, Mastercard and American Express icons) and fills in Card number, Expiry (MM / YY), CVC and Name on card on your checkout. Before sending, the card form checks the card number length, the expiry month and year, a CVC of 3 or 4 digits and the name.
When the order is placed, Pin.js sends the card details and the billing address from the browser directly to Pin Payments and gets a single-use card token. Only this token is sent to your server. Your server then creates a captured charge for the order total in the order currency, with the description <store name> - Order <number>. Pin Payments answers in the same request. The order is marked paid only after Pin Payments reports a successful charge, and only for exactly the order amount and currency. Then the customer lands on the order received page.
Only one payment attempt per order runs at a time. A second submit gets This order is already being paid. Please wait a moment and check your e-mail before trying again. An order that is already paid, or charged and held, is never charged again. A card token can be used once: after a failed attempt, or when the customer changes the card details, a new token is created.
Messages the customer may see: 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.; 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 and retry. when the token cannot be used; The secure card form could not be loaded. Please reload the page or choose another payment method. when Pin.js does not load; Card payments are temporarily unavailable. Please try again later or choose another payment method. when Pin Payments rejects the secret key; We could not confirm your payment with Pin Payments. Please check your e-mail and card statement before trying again, or contact us. when Pin Payments does not answer. Technical details go to the order notes and the log.
The payment method works on the classic checkout, on the Checkout block (with the same card fields) and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS).
The plugin has no 3-D Secure flow. If your Pin Payments account requires 3-D Secure, the charge stays pending and the plugin fails the order, so no money is taken by that attempt; the customer sees Your card payment could not be completed (additional verification is required). Please try another card or another payment method. There is no authorize-only mode with a later capture, no saved cards, no WooCommerce Subscriptions, no Apple Pay or Google Pay and no webhooks.
Orders and refunds
Order statuses
Processing: Pin Payments reported a successful, captured charge for exactly the order amount and currency. Orders with only virtual downloadable products become Completed, the WooCommerce default. The order note shows the amount and the charge token (and TEST MODE for test payments). The transaction ID is the Pin Payments charge token.
Failed: the card was declined, the charge stayed pending (3-D Secure), Pin Payments rejected the secret key or the request. Each failed attempt adds an order note with the Pin Payments error code and message, also when the order was already Failed from an earlier attempt. The customer can try again with the same order.
Pending payment: Pin Payments gave no clear answer (timeout, server error, unreadable answer). The order is not failed, because a charge may still have been created. The note tells you to look for the charge description in the Pin Payments dashboard before the customer pays again or the order ships.
On hold: Pin Payments charged an amount or currency different from the order (the note shows the expected and the charged amount), or the charge is authorized but not captured. Check the charge in the Pin Payments dashboard before fulfilling.
Refunds
Open the order, click Refund, enter the amount and click Refund via Credit card (Pin Payments) (the button shows your Title). Full and partial refunds are supported. The refund is sent to the environment (test or live) the order was paid in, so that mode's secret key must be set. A successful request adds an order note with the amount, the Pin Payments refund token and its status. Pin Payments processes refunds asynchronously, so the status is usually Pending. If Pin Payments rejects the refund or does not answer, WooCommerce shows the error and no refund is recorded.
Refunds made in the Pin Payments dashboard are not synced back to WooCommerce, so make them from WooCommerce.
License key
The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Pin Payments. 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, Pin Payments 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: refunds still 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
Pin Payments does not appear at checkout: check that the license is active, Enable/Disable is on, both keys of the current mode are filled in (Test publishable key and Test secret key in test mode, the live keys otherwise) and the cart currency is one of the 14 supported currencies. On the Pay for order page the order currency counts. The settings page shows an error for missing keys and for an unsupported currency.
The checkout says We could not confirm your payment: Pin Payments did not answer in time. The order stays Pending payment with a note. Look in the Pin Payments dashboard for a charge with the description <store name> - Order <number> before the customer pays again or the order ships. The plugin does not look up such a charge automatically, and a new attempt creates a new charge.
Customers see Card payments are temporarily unavailable: Pin Payments rejected the secret key. The order note says to check the keys of the current mode. Test keys work only in test mode, live keys only in live mode.
Orders fail with additional verification is required: your Pin Payments account requires 3-D Secure, which the plugin does not support. Ask Pin Payments to turn off mandatory 3-D Secure.
An order is On hold with a does not match note: Pin Payments reported a charge amount or currency different from the order. Check the charge in the Pin Payments dashboard and refund or complete the order manually.
The secure card form could not be loaded: Pin.js from the Pin Payments CDN did not load in the browser, for example because of a script blocker or a caching or optimization plugin that changes scripts. Exclude the checkout from such optimizations.
Refund fails: read the message. A message about TEST or LIVE mode means the secret key of the mode the order was paid in is empty. Pin Payments did not confirm the refund means no answer came; check the charge in the Pin Payments dashboard before trying again.
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 order note has the error code.
Test payments: test mode uses the test environment and test keys. Use the test cards from the Pin Payments developer documentation, for example 4200 0000 0000 0000 (succeeds) or 4100 0000 0000 0001 (declined), with any future expiry date and any CVC. 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 WooCommerce > Status > Logs, source wcp_pinpayments_gateway. Turn on Debug log to see every API call.
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.
For developers: the filter wc_ppg_supported_currencies changes the list of currencies, and wc_ppg_icon changes the icon in the WooCommerce list of payment methods.
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, the plugin's version options and its logs (log files, including rotated ones, and database log entries) are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. Payment data stored on orders, such as the Pin Payments charge token, is never deleted. Existing orders keep their payment notes and transaction IDs.
Pin Payments is a trademark of its respective owner. This plugin is not affiliated with or endorsed by Pin Payments.