FluxBilling
Payment Gateways

2Checkout (Verifone)

Set up the 2Checkout plugin: merchant code, secret key, buy-link secret word, the IPN address, checkout display, payment lifecycle, refunds and troubleshooting.

Updated · 2026-11-11

The 2Checkout plugin lets your customers pay FluxBilling invoices on 2Checkout's hosted checkout. When a customer chooses 2Checkout, FluxBilling sends them to a signed 2Checkout ConvertPlus checkout page for the amount due. The customer pays there with any payment method your 2Checkout account offers. 2Checkout then notifies FluxBilling through its Instant Payment Notification (IPN), FluxBilling checks the order with the 2Checkout API, and the invoice is marked paid. The plugin is free and is listed in the plugin marketplace of every FluxBilling panel.

This guide covers plugin version 2.6. It walks through the setup in the order you do it, then explains how payments, refunds and chargebacks work and what to check when something does not work.

Who supports this integration. The plugin is built and maintained by FluxBilling. If something does not work, contact FluxBilling support at contact@fluxbilling.app or through fluxbilling.app/contact. Questions about your 2Checkout account, its approval, payment methods, payouts or fees go to 2Checkout (Verifone) support.

What you need before you start

  • An approved 2Checkout merchant account and access to its Merchant Control Panel. The plugin has no separate test mode: it always opens 2Checkout's live checkout for your account.
  • Three values from the Merchant Control Panel: your Merchant Code, your Secret Key and your Buy Link Secret Word. Step 1 shows where they are.
  • A FluxBilling panel that 2Checkout can reach over HTTPS. Payments complete through 2Checkout's IPN, so your panel's public address must accept requests from the internet.
  • Invoices in a currency 2Checkout charges for you. FluxBilling charges an invoice in its own currency when that currency is USD, EUR or your base currency. Any other invoice currency is converted to your base currency before the customer is sent to 2Checkout.

Step 1: Collect your credentials in 2Checkout

  1. Sign in to the 2Checkout Merchant Control Panel.
  2. Open Integrations → Webhooks & API.
  3. Copy your Merchant Code and your Secret Key. FluxBilling uses them to sign every request it makes to the 2Checkout API.
  4. On the same page, copy the Buy Link Secret Word. FluxBilling uses it to sign each checkout link. 2Checkout rejects checkout links that are not signed with it.

2Checkout describes the Merchant Code and Secret Key in API Authentication, and the signed checkout links in ConvertPlus Buy-Links signature for dynamic products. The Control Panel's labels can differ slightly between account versions.

Step 2: Install the plugin

  1. In the FluxBilling admin panel, open Settings (the gear icon in the top bar).
  2. Under Integrations, open Marketplace. Stay on the Browse tab.
  3. Search for 2Checkout, open its card and click Get for Free.
Top of the 2Checkout listing in the marketplace: tagline, Plugin, Payment Gateway and v2.6 badges, the start of the overview and the Free price card showing Installed
The 2Checkout listing. Before you install it, the price card shows Get for Free; afterwards it shows Installed.

FluxBilling confirms with Plugin "2Checkout" installed and ready to use. The plugin is switched on straight away and appears under Settings → Integrations → Plugins, marked Active. Customers do not see 2Checkout at checkout yet: a gateway is offered only once its required settings are saved.

Step 3: Enter your credentials

  1. Open Settings → Integrations → Plugins.
  2. On the 2Checkout card, click Configure. The dialog opens on the Settings tab.
  3. Fill in the fields below.
  4. Click Save Configuration. FluxBilling shows Configuration saved successfully.
2Checkout Configure dialog, Settings tab, with Enabled ticked, an example Merchant Code and the masked Secret Key and Buy Link Secret Word
The Settings tab with example values. Secret fields are masked.
2Checkout settings
FieldRequiredWhat it does
EnabledYes, to take paymentsOffers 2Checkout at checkout. Untick it to hide the gateway without removing its settings.
Merchant CodeYesYour 2Checkout merchant code (seller ID). It identifies your account on the checkout link and in API requests.
Secret KeyYesThe secret key from Integrations → Webhooks & API. FluxBilling signs its API requests with it: reading orders, checking payments and refunds.
Buy Link Secret WordYesThe secret word from the same page. FluxBilling signs every checkout link with it.
Setup note and Webhook configuration required box-Not fields. The setup note is a short reminder; the Webhook configuration required box shows the IPN address of your panel to register in 2Checkout. See step 4.

The Secret Key and Buy Link Secret Word are stored encrypted, and the dialog shows them masked. To change one, type the new value; leaving a secret field empty keeps the stored value. If a required field is missing, FluxBilling saves the form but shows Saved, but the plugin is not configured until these are fixed: followed by the missing field, for example Buy Link Secret Word is required.

The dialog has no connection test button. The quickest check is a small real payment: see step 6.

Step 4: Register the IPN address in 2Checkout

Do not skip this step. The IPN is the only way FluxBilling learns that an order was refunded or charged back, and the quickest way it learns that an order is paid.

  1. In the Configure dialog, find the box Webhook configuration required. It shows the exact IPN address of your panel. Click Copy URL.
  2. In the 2Checkout Merchant Control Panel, open Integrations → Webhooks & API and the IPN Settings tab.
  3. Add the copied address as an IPN URL.
  4. Choose a SHA2 or SHA3 signature algorithm for the IPN, as 2Checkout recommends, and save.

2Checkout describes these screens in Instant Payment Notification (IPN) and IPN and LCN URL Settings.

FluxBilling does not trust the content of an IPN. For every notification it reads the order back from the 2Checkout API with your own credentials and takes the status, amount and currency only from that answer. A forged notification can therefore never mark an invoice paid.

Repeated IPN deliveries. 2Checkout expects a special read receipt in the reply to each IPN. FluxBilling does not send that receipt, so 2Checkout may keep retrying deliveries for up to two days. FluxBilling processes each order once: repeated deliveries for the same order change nothing. See 2Checkout's IPN POST failure recovery process.

The webhook box in the Configure dialog also shows what FluxBilling has seen on that address, for example No deliveries received yet, Receiving deliveries with a count, or Deliveries failing, and the time of the last delivery.

Step 5: Check how 2Checkout appears at checkout

Open Settings → Financial → Payment Gateways. Every installed gateway has a card there with an Enabled or Disabled badge and a switch. The switch turns the 2Checkout plugin itself on or off.

Settings, Payment Gateways, with the 2Checkout card marked Enabled and its switch
Settings → Financial → Payment Gateways. The card shows the display name and description from Checkout Display.

To change what customers see, open the plugin's Configure dialog again and switch to the Checkout Display tab:

  • Display Name: the name in the list of payment methods, for example Card or PayPal.
  • Description: an optional line under the name.
  • Icon: a preset icon or the address of your own image.

The Preview shows the result. Click Save Configuration to keep your changes.

Checkout Display tab with Display Name 2Checkout, its description, the preset icons and a preview
The Checkout Display tab with the values the plugin starts with.

2Checkout is not tied to products or categories. Once it is configured and enabled, it is offered for every invoice, order and credit top-up, next to your other gateways.

Step 6: Place a test payment

The plugin always creates checkout links for your live 2Checkout account. To check the whole path, pay a small invoice from a test client account, then refund it from FluxBilling if you like. Check that:

  1. the customer is sent to 2Checkout's checkout page and back to the client area;
  2. the webhook box in the Configure dialog changes to Receiving deliveries;
  3. the invoice turns paid.

A single charge must be at least 0.50 in the charge currency.

What your customers see

Client checkout page for an invoice with 2Checkout selected among the payment methods
The customer's checkout with 2Checkout selected.
  1. The customer chooses 2Checkout (under the display name you set) on the checkout page and clicks Checkout.
  2. FluxBilling sends them to 2Checkout's checkout page with the amount and a description already filled in. The order carries an internal FluxBilling reference for the invoice, which FluxBilling uses to match the payment. The customer enters their details and pays with any method your 2Checkout account offers.
  3. 2Checkout sends them back to the FluxBilling client area. FluxBilling checks the order with 2Checkout. If it is not complete yet, the customer sees Payment is being processed. This may take a moment... and then Payment is still processing. Please check back shortly.
  4. When the order is complete, the invoice is marked paid, the usual paid-invoice emails go out and any service on the order is set up.

2Checkout does not save the customer's payment method in FluxBilling. Each invoice is paid at checkout, and 2Checkout cannot be used for automatic payment of renewal invoices.

Payment lifecycle

When an IPN arrives, FluxBilling reads the order status from the 2Checkout API and acts on it as the table shows. When the customer returns from 2Checkout, and in its periodic check of pending payments, FluxBilling acts only on a COMPLETE order; any other status leaves the payment pending.

2Checkout order status and what FluxBilling does
2Checkout order statusIn FluxBilling
COMPLETEThe payment is completed and the invoice is marked paid.
PENDING, PAYMENT_AUTHORIZED, AUTHRECEIVED, PENDING_APPROVALThe payment stays pending. The invoice stays unpaid.
REFUND, REVERSEDThe payment is recorded as refunded.
CANCELED, INVALIDThe payment is marked failed. The invoice stays unpaid.
Chargeback openedThe payment is marked disputed and the invoice is put on hold for staff to review.

A 2Checkout order can stay pending for days, for example during 2Checkout's fraud review or for offline methods such as wire transfer. FluxBilling keeps such a payment pending and asks 2Checkout about it from time to time, for up to 14 days. After that it gives up on the payment, and the customer can pay the invoice again.

Once a payment completes, it carries the 2Checkout order reference in FluxBilling, so you can find the order in the Merchant Control Panel.

Chargebacks

When 2Checkout reports that a chargeback was opened, FluxBilling marks the payment disputed, puts the invoice on hold and takes back any account credit that payment added. When 2Checkout reports that the chargeback is closed, FluxBilling does not change anything automatically: check the outcome in the Merchant Control Panel and deal with the invoice yourself.

Refunds

You can refund a 2Checkout payment from the invoice in the admin panel: open the invoice, click Refund, choose Via Gateway under Refund Method, and enter an amount, or leave it empty for a full refund. Partial refunds are supported. FluxBilling shows Refund processed via gateway when 2Checkout accepts it.

  • Only a completed payment can be refunded. FluxBilling uses the 2Checkout order reference it stored when the payment completed.
  • 2Checkout refunds only orders in status COMPLETE that are no more than three months old, and never more than the order total. See Refunding an order.
  • FluxBilling sends the refund with the reason Other, one of 2Checkout's default refund reasons, and your own reason as the comment. Keep Other available as a refund reason in your 2Checkout account.
  • A refund made in the 2Checkout Control Panel reaches FluxBilling through the IPN and is recorded on the payment. Refunding from FluxBilling records the exact amount on the invoice.

Updating the plugin

Open Settings → Integrations → Marketplace, switch to Installed and click Check for Updates. When a new version is available, click Update to v…. Your settings are kept.

Troubleshooting

Common messages
Message or symptomWhat to check
2Checkout is not offered at checkoutA required field is missing, Enabled is unticked in the Configure dialog, or the plugin is switched off under Settings → Financial → Payment Gateways.
Saved, but the plugin is not configured until these are fixed: …Enter the field it names and save again.
2Checkout shows an error instead of its checkout pageThe checkout link signature did not match. Check that Buy Link Secret Word is exactly the secret word from Integrations → Webhooks & API and that Merchant Code belongs to the same account.
Minimum payment amount is 0.5 …The amount to pay is below the plugin's minimum of 0.50 in the charge currency.
The customer paid, but the invoice stays unpaidCheck the webhook box in the Configure dialog. No deliveries received yet: the IPN URL is missing in 2Checkout or points elsewhere. Also check the order status in the Merchant Control Panel: an order still in fraud review or waiting for an offline payment stays pending in FluxBilling too.
Could not load the 2Checkout order for refund - is the transaction reference a 2Checkout RefNo?, or a message from 2CheckoutFluxBilling could not load the order behind this payment from 2Checkout. Check that Merchant Code and Secret Key are correct and that the order exists in that 2Checkout account, or refund the order in the Merchant Control Panel.
Refund failed, or a 2Checkout message when refunding2Checkout refused the refund, for example because the order is older than three months or the refund reason Other is not available. 2Checkout's own message is shown when it gives one.
That payment has already been refunded in fullNothing is left to refund on this payment.
2Checkout keeps resending the same IPNExpected: see the note in step 4. Check that the webhook box in FluxBilling shows Receiving deliveries.

Limits

  • No saved payment methods: customers cannot store a card through 2Checkout, and 2Checkout cannot be used for automatic payment of renewal invoices.
  • No 2Checkout subscriptions. Every invoice, including a renewal, is a separate one-off 2Checkout order that the customer pays at checkout.
  • No sandbox switch. The plugin always works against your live 2Checkout account.
  • Each FluxBilling panel connects to one 2Checkout account.
  • The IPN URL is set up by hand in 2Checkout. The plugin does not create it for you.
  • Customers enter their payment details at 2Checkout, never in FluxBilling.
  • Invoices in a currency other than USD, EUR or your base currency are charged in your base currency.
  • A closed chargeback is not acted on automatically.
  • A refund is returned through 2Checkout to the customer's original payment method. To give account credit instead, use the To balance refund option on the invoice.

2Checkout is a trademark of Verifone, Inc. FluxBilling is not affiliated with Verifone, Inc.