The 2CheckOut payment gateway allows you to receive one-time and recurring payments, issue refunds, and other features.

Supported Features #

Type: Third-Party

Adding the 2CheckOut Payment Gateway #

To set up the 2CheckOut payment gateway in WHMCS:

1. Go to Configuration () > Apps & Integrations or Addons > Apps & Integrations.
2. Click 2CheckOut.
   
3. Check Show on Order Form to display this payment method in the Client Area during checkout.
4. Optionally, enter a new display name.
5. Enter your vendor account number. You can find the vendor account number in your 2Checkout account by clicking the gear icon and copying the Merchant Code value.
6. Choose your desired checkout style. We recommend always selecting Standard Checkout.
   For more information, see Checkout Style below.
7. Enter your API username and password. You can create these in your 2Checkout account:
   1. Go to Settings > Manage User Access > View Roles > Add Role and enable Manage api access.
   2. Go to Settings > Manage User Access > View Users > Add User and create a new user with the role you just created.
8. For enhanced security, enter a secret word. You can create the secret word in your 2Checkout account:
   1. In your 2Checkout account, go to Integrations.
   2. Copy the INS Secret Word or generate a new one. The secret word is case-sensitive and can only contain the letters a–z.
9. Select a Recurring Billing setting.
   For more information, see Recurring Billing below.
10. Check Skip 2CO Fraud Check to prevent 2Checkout from performing fraud checks on payments.
    If the system later determines that a payment in WHMCS is fraudulent, you must manually reverse the payment in WHMCS and suspend any services.
11. If you use multiple currencies, set Convert To For Processing to the value of the currency your 2Checkout account. For example, if your 2Checkout account is in USD, the Convert To For Processing setting must also be USD.
12. Click Save Changes.

Checkout Style #

The 2CheckOut module allows you to select between Inline Checkout and Standard Checkout checkout style options. However, 2Checkout has deprecated their legacy inline checkout style and it is no longer available.

• 2Checkout will use the standard checkout style regardless of your Checkout Style setting.
• We recommend always selecting Standard Checkout.
• We plan to remove this setting in a future WHMCS version.

Recurring Billing #

When you configure recurring billing, you can select the following options:

• Offer Recurring & One Time Payments — Provide both recurring and one-time billing options.
• Offer Recurring Only — Only provide a recurring option. This option will only appear when there is a recurring item on the invoice and the invoice is not overdue.
• Offer One Time Only — Only provide a one-time option. This option will not allow automatic recurring payments.

If you choose Offer One Time Only, you must configure it in your 2Checkout account:

1. Log in to your 2Checkout account.
2. Go to the Integrations tab.
3. To set the 2Checkout callback process to automatically mark invoices paid:
   1. Check Enable INS and Enable global URL.
   2. For Global URL, enter https://www.example.com/whmcs/modules/gateways/callback/tco.php, where https://www.example.com/whmcs/ is the URL of your WHMCS installation.
4. To return clients to your WHMCS installation after payment, set Approved URL under Redirect URL to https://www.example.com/whmcs/modules/gateways/callback/2checkout.php, where https://www.example.com/whmcs/ is the URL of your WHMCS installation.
5. Click Update.

Demo Mode #

To use demo mode:

1. Set the Demo Setting in your 2Checkout account to Parameter under Account () > Site Management.
2. In WHMCS, enable demo mode by checking the checkbox at Configuration () > System Settings > Payment Gateways.

When you use demo mode, all callbacks from 2Checkout will fail with the error MD5 Hash Failure if they specify a secret word. 2Checkout does this intentionally to protect sellers of digital goods from fraudulent purchases through their demo mode.

In demo mode, you must submit valid credit card data in order to properly perform the request. This process will not charge credit cards.

Troubleshooting #

MD5 Hash Failure #

A MD5 Hash Failure error at Billing > Gateway Log indicates that the secret word in Configuration () > System Settings > Payment Gateways does not match the secret word in the 2CheckOut control panel.

To resolve this issue, ensure that the secret word in 2Checkout contains only letters and numbers and does not contain any invisible trailing spaces. Then, update the secret word value in WHMCS to match the value in your 2Checkout account.

Error Code PE101 #

This error indicates that there are invalid details in the 2CheckOut module settings, such as an incorrect Vendor Account Number value. Ensure that you entered the details correctly in the 2CheckOut gateway configuration.

A PE101 error can also be due to an account-level issue that you must resolve with 2CheckOut:

• Account is not approved to sell.
• Account has been closed.

It may also be possible that 2CheckOut is not allowing the use of inline checkout. Changing to standard checkout can resolve this.

Authentication failed #

An Authentication failed error at Billing > Gateway Log indicates that the secret word, API username, or API password are incorrect.

You can update these in the 2CheckOut configuration at Configuration () > System Settings > Payment Gateways.

Last modified: December 5, 2024