VibeFox Pin Payments for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

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 shop, so the shop falls under PCI SAQ A-EP.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox Pin Payments Gateway in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page 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 on, turn on Enable/Disable and click Save.

5. Place a test order with a Pin Payments test card. When everything works, enter the live keys, turn off Test mode and save.

On install the module creates the order status Pin Payments payment on hold. PrestaShop offers a new payment module for the currencies, customer groups and the countries that are active at install time. You can change this in Payment > Preferences; countries you activate later must be ticked there.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Pin Payments Gateway > Configure. Each section has its own Save button, which saves the whole page. Above the fields the page shows a warning 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 default currency of the shop (with the list of supported currencies). Without both keys of the current mode the payment method is hidden at checkout. An empty Title is not saved: the page shows Enter a title for the payment method.

Pin Payments

Enable/Disable: Enable Pin Payments turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. It is also the payment method name stored in the order. Default: Credit card (Pin Payments). Required.

Description: the text shown under the payment method 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: 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. When it is off, the live API 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.

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 removed. Saved secret keys are never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.

Clear saved secrets: tick a secret key and click Save to remove it. An empty field keeps the saved value.

Advanced

Debug log: writes to logs/wc_ppg_debug.log.php in the module folder. The file cannot be opened from the web. 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.

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

Delete data on uninstall: when on, uninstalling the module removes the gateway settings and the log. The payment data of orders (charges and refunds) and the order status Pin Payments payment on hold are always kept. Default: off.

Checkout

The payment method is shown when it is enabled, both keys of the current mode are set, the cart currency is one of the 14 supported currencies (AUD, USD, NZD, SGD, EUR, GBP, CAD, HKD, JPY, MYR, THB, PHP, ZAR, IDR) and the module is allowed for the cart in Payment > Preferences.

At the payment step 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. Before sending, the form checks the card number length, the expiry month and year, a CVC of 3 or 4 digits and the name.

When the customer places the order, Pin.js sends the card details and the billing address of the cart from the browser directly to Pin Payments and gets a single-use card token. Only this token is sent to your shop. The module then creates a captured charge for the cart total in the cart currency, with the customer's e-mail and the description <shop name> - Cart <cart number>. Pin Payments answers in the same request. No order exists before this answer.

After a successful charge the order is created and the customer sees the standard order confirmation page with Your card payment has been received. If the order went to Pin Payments payment on hold, the 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 is then created in Pin Payments payment on hold without a payment, and the confirmation 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. Submitting the same cart again never creates a second charge.

Only one payment attempt per cart 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. A cart that already has an order, or an earlier attempt that took or may have taken money, is not charged again; the order is created from that attempt instead. A card token can be used once: after a failed attempt, or when the customer changes the card details, a new token is created.

When the payment fails, no order is created. The customer stays at the payment step, the cart is kept and one of these messages is shown: 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; Your payment could not be processed. Please try again or choose another payment method. for other errors. The technical reason is written to the log.

The module has no 3-D Secure flow. If your Pin Payments account requires 3-D Secure, the charge stays pending, no order is created and 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 subscriptions, no Apple Pay or Google Pay and no webhooks.

Orders and refunds

Order statuses

No order yet: the card was declined, the charge needed 3-D Secure, or the customer has not paid. Only the cart exists.

Payment accepted: Pin Payments reported a successful, captured charge for exactly the cart amount and currency. The payment is recorded with the Pin Payments charge token as the transaction ID, and a note shows the amount and the charge token (and TEST MODE for test payments).

Pin Payments payment on hold: the charge needs your review. The note explains why: Pin Payments charged an amount or currency different from the cart (the payment of the charged amount is recorded), the cart changed during the payment, the charge is authorized but not captured (capture it in the Pin Payments dashboard, then set the order to Payment accepted), or Pin Payments gave no clear answer (no payment is recorded; look for the charge description in the Pin Payments dashboard before the order ships).

Refunded: the charge was fully refunded through the module.

If a second charge is made for a cart that already has an order, the order is not changed. A note asks you to check it and refund it in the Pin Payments dashboard.

Pin Payments block

The order page shows a Pin Payments block with a Test mode badge for test payments, the charge token, the status, the card brand and last four digits, the charged amount, the order total and the amount refunded, the Description at Pin Payments, the refund history and the Pin Payments notes of the order.

Refunds

In the Pin Payments block enter the amount (the amount not refunded yet is filled in), optionally a reason, and click Refund via Pin Payments. Confirm the question Refund this amount through Pin Payments? This cannot be undone. Full and partial refunds are supported. You need the right to edit orders. Refunds are limited to the amount and currency Pin Payments actually charged, so after an amount or currency mismatch you can refund up to what the customer paid, not the order total. The refund is sent to the environment (test or live) the order was paid in, so that mode's secret key must be set. Pin Payments processes refunds asynchronously, so the status is usually Pending. A successful request is added to the refund history and the notes with the Pin Payments refund token and its status. A full refund sets the order to Refunded. A partial refund does not change the status. If Pin Payments rejects the refund or does not answer, the block shows the error and no refund is recorded.

When no charge is recorded for the order (Pin Payments gave no clear answer), the block shows no refund form and tells you which description to look for in the Pin Payments dashboard.

The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through Pin Payments. Refunds made in the Pin Payments dashboard are not synced back to PrestaShop, so make them from the order page.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Pin Payments Gateway is the first block on Modules > Module Manager > VibeFox Pin Payments Gateway > Configure, 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 shop. Below them are the line Product: presta-payment-pinpayments and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (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 shop 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 main shop, also in a multistore setup. Removing the key from the shop 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. The PrestaShop storefront does not know that you are logged in to the back office, 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 Modules > Module Manager on the Alerts tab. 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 while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.

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. In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group. The settings page shows an error for missing keys and for an unsupported shop currency.

The payment went through, but the order is Pin Payments payment on hold: read the notes in the Pin Payments block (see Order statuses). If Pin Payments gave no clear answer, look in the Pin Payments dashboard for a charge with the description <shop name> - Cart <cart number>, then fulfil the order or refund the charge in the dashboard.

The customer sees Your payment was received, but the order could not be completed automatically: the card was charged, but PrestaShop could not create the order (for example, the module was disabled meanwhile). The reason is in the log. The customer is asked not to pay again; submitting the same cart again creates the order without a new charge.

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

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

Pin Payments did not respond: the card token was not created within 30 seconds in the browser. The customer can check the connection and try again; nothing was charged.

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.

Refund fails: read the message in the block. 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. at most shows the amount still refundable from the charge.

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 the log; see the Log field on the module page. Turn on Debug log to see every API call.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Pin Payments Gateway and choose Uninstall. The license key and license status of this module are always removed. If Delete data on uninstall is on, the gateway settings and the log are removed. If it is off, all settings are kept for a later re-install. The Pin Payments charges and refunds and the order status Pin Payments payment on hold are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their 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.