Difference between revisions of "2CheckOut"

From WHMCS Documentation

(→‎Skip 2CO Fraud Check)
(→‎Adding the 2CheckOut Payment Gateway)
 
(54 intermediate revisions by 9 users not shown)
Line 1: Line 1:
 +
== About this Module ==
 +
 +
The 2CheckOut payment gateway allows you to receive one-time and recurring payments, issue refunds, and other features.
 
{{gateways
 
{{gateways
 
| onetime = yes
 
| onetime = yes
 
| recurring = yes
 
| recurring = yes
 
| refunds = yes
 
| refunds = yes
 +
| updatecc = yes
 
}}
 
}}
  
−
==Setup==
+
== Adding the 2CheckOut Payment Gateway==
 +
 +
To set up the 2CheckOut payment gateway in WHMCS:
 +
 +
# Go to the appropriate location for your version of WHMCS:
 +
#* For WHMCS 8.0 and later, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > Apps & Integrations''' or '''Addons > [[Apps and Integrations|Apps & Integrations]]'''.
 +
#* For WHMCS 7.10 and earlier, go to '''Setup > Products/Services > [[Payment Gateways]]''' and choose '''All Payment Gateways'''.
 +
# Click '''2CheckOut'''.
 +
# Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.
 +
# Optionally, enter a new display name.
 +
# 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.
 +
# Choose your desired checkout style. We recommend always selecting '''Standard Checkout'''. For more information, see [[#Checkout_Style|Checkout Style]].
 +
# Enter your API username and password. You can create these in your 2CheckOut account:
 +
## Go to '''Settings > Manage User Access > View Roles > Add Role''' and enable '''Manage api access'''.
 +
## Go to '''Settings > Manage User Access > View Users > Add User''' and create a new user with the role you just created.
 +
# For enhanced security, enter a secret word. You can create the secret word in your 2CheckOut account:
 +
## In your 2CheckOut account, navigate to "''Integrations''".
 +
## Copy the '''INS Secret Word''' or generate a new one. The secret word is case-sensitive and can only contain the letters a-z.
 +
# Select a '''Recurring Billing''' setting. For more information, see the section below.
 +
# Check '''Skip 2CO Fraud Check''' to prevent 2Checkout from performing their fraud checks on payments. If a payment in WHMCS is later determined to be fraudulent, manual action would be required to reverse the payment  in WHMCS and suspend any services.
 +
# 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'''.
 +
# 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.
  
−
Begin by activating the payment gateway under '''Setup > Payments > Payment Gateways''' and choose 2CheckOut from the Available Gateways dropdown.
+
* 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 version.
 +
 +
<div class="docs-alert-warning">
 +
This applies to 2Checkout's legacy inline checkout style and '''not''' to their current [https://www.2checkout.com/lp/inline-cart.html InLine checkout] feature.
 +
</div>
 +
 +
=== 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:
 +
 +
# Log in to your 2CheckOut account.
 +
# Go to the '''Integrations''' tab.
 +
# To set the 2CheckOut callback process to automatically mark invoices paid:
 +
## Check '''Enable INS''' and '''Enable global URL'''.
 +
## In the '''Global URL''' field, enter <tt>https://www.example.com/whmcs/modules/gateways/callback/tco.php</tt>, where <tt>https://www.example.com/whmcs/</tt> is the URL of your WHMCS installation.
 +
# To configure Direct Return to return clients to your WHMCS installation after payment:
 +
## Under '''Redirect URL''' in the '''Approved URL''' field, set the URL to <tt>https://www.example.com/whmcs/modules/gateways/callback/2checkout.php</tt>, where <tt>https://www.example.com/whmcs/</tt> is the URL of your WHMCS installation.
 +
# Click '''Update'''.
 +
 +
===Demo Mode===
 +
 +
In order to use demo mode, set the '''Demo Setting''' in your 2CheckOut account to '''Parameter''' under '''Account > Site Management'''. Then, in WHMCS, enable demo mode by checking the checkbox at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Payment Gateways'''.
 +
 +
When you use demo mode, all callbacks from 2CheckOut will fail with the error MD5 Hash Failure if a secret word is specified. This is done intentionally by 2Checkout to protect sellers of digital goods from fraudulent purchases through their demo mode.
 +
 +
<div class="docs-alert-info">
 +
In Demo Mode, valid credit card data must be submitted in order to properly perform the request. Credit cards will not be charged during this process.
 +
</div>
  
−
Once activated, you can then enter the configuration details explained below. By default clients can chose between one-time and subscriptions payments and enter their own billing details on the 2Checkout site, the following options allow this behaviour to be changed.
+
==Troubleshooting==
  
−
===Notifications===
+
===MD5 Hash Failure===
−
 
 
−
[[File:2co_config3.png|thumb|2CO Notifications Setup]]
 
−
 
 
−
To setup the callback process for 2CheckOut to automatically mark invoices paid, you will need to login to your 2CheckOut account and click the '''Notifications''' tab:
 
−
* First click '''Enable All Notifications'''
 
−
* In the '''Global URL''' field, enter the url http://www.yourdomain.com/whmcs/modules/gateways/callback/tco.php . Replacing http://www.yourdomain.com/whmcs/ with the actual URL of your WHMCS installation.
 
−
* Click '''Apply'''
 
−
 
 
−
===Direct Return===
 
  
−
[[File:2co_config1.png|thumb|2CO Direct Return Setup]]
+
An MD5 Hash Failure error under '''Billing > [[Gateway Log]]''' indicates that the secret word in '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Payment Gateways''' does not match the secret word in the 2CheckOut control panel.
  
−
In order to return clients back to your WHMCS installation after a successful payment you can configure Direct Return within the 2CO 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
−
* Navigate to '''Account tab > Site Management
 
−
* Under the Direct Return heading, select the '''Direct Return''' option
 
−
* In the '''Approved URL''' field set the URL to http://www.yourdomain.com/whmcs/modules/gateways/callback/2checkout.php . Replacing http://www.yourdomain.com/whmcs/ with the actual URL of your WHMCS installation.
 
  
−
===Secret Word===
+
===Error Code PE101===
  
−
For added security, you can set a '''"Secret Word"''' inside your 2CheckOut account @ '''Account > Site Management'''. If set, this is then used to validate callbacks are authentic and it is therefore '''recommended''' that you do this.  If you choose to enable it, then you must also enter the exact same word that you set inside the 2CheckOut control panel into the WHMCS Secret Word field in '''Setup > Payments > Payment Gateways'''
+
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 [[#Adding_the_2CheckOut_Payment_Gateway|2CheckOut gateway configuration]].
  
−
===API Username/Password===
+
A PE101 error can also be due to an account-level issue that you must resolve with 2CheckOut:
 +
* <tt>Account is not approved to sell.</tt>
 +
* <tt>Account has been closed.</tt>
  
−
[[File:2co_config2.png|thumb|2CO API User Setup]]
+
It is possible that 2CheckOut is not allowing the use of inline checkout. Changing to [[#Adding_the_2CheckOut_Payment_Gateway|standard checkout]] can resolve this.
  
−
If you wish to be able to use the '''recurring billing and/or automatic refunds functionality''' within WHMCS, then you must setup a 2CheckOut API user and enter the details in these fields.
+
===Authentication failed===
−
 
 
−
To setup an API user, you will need to login to your 2CheckOut account and go to '''Account > User Management'''
 
−
* Click '''Create Username'''
 
−
* Enter an email address, username & password, security question & answer.
 
−
* Select the permissions for the user.  You just need to select '''API Access & API Updating''' for the permissions.
 
−
* Enter the same username & password that you just created into the appropriate API username and API password fields inside WHMCS.
 
−
 
 
−
===Disable Recurring===
 
−
When ticked clients will only be able to make one-time payments (subscriptions disabled). For recurring services they will be required to login and pay each invoice.
 
−
 
 
−
===Force Recurring===
 
−
When enabled clients will only be able to make recurring payments when applicable (one-time payments disabled). This means future payments will be sent automatically without the need for manual intervention.
 
−
 
 
−
===Purchase Routine===
 
−
When unticked the standard '''spurchase''' routine will be used. Tick this option to use the more modern '''purchase''' checkout process which includes the option for clients to pay via PayPal.
 
−
 
 
−
===Skip 2CO Fraud Check===
 
−
Ticking this option will prevent 2Checkout from performing their fraud checks on payments. It can result in faster processing of payments, but may potentially increase your exposure to fraudulent orders and charge-backs.
 
−
 
 
−
Should a payment that has been recorded in WHMCS later be determined to be fraudulent, manual action would be required to reverse the payment recorded in WHMCS and suspend any services as appropriate.
 
−
 
 
−
==Error Messages==
 
−
 
 
−
===Demo Mode===
 
−
 
 
−
In order to use demo mode, the "Demo Setting" in your 2CheckOut account should be set to "Parameter" under '''Account > Site Management'''. Demo mode can then be enabled by ticking the checkbox in WHMCS under '''Setup > Payments > Payment Gateways'''.
 
−
 
 
−
Please note that when using demo mode, all callbacks from 2CheckOut will fail with the error MD5 Hash Failure if a secret word is specified.  This is done intentionally by 2Checkout to protect those who sell digital goods from fraudulent purchases through their demo mode.
 
−
 
 
−
<div class="docs-alert-info">
 
−
In Demo Mode, valid credit card data must be submitted in order to properly perform the request. Credit cards will not be charged during this process.
 
−
</div>
 
−
 
 
−
===MD5 Hash Failure===
 
  
−
An MD5 Hash Failure error under '''Billing > Gateway Log''' indicates that the Secret Word in '''Setup > Payments > Payment Gateways''' does not match the Secret Word in the 2CheckOut control panel. Double check your entry is exactly right, and check for any invisible trailing spaces if so.
+
This error at '''Billing > [[Gateway Log]]''' indicates that the secret word, API username, or API password are incorrect. You can update these at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Payment Gateways'''.  
  
 +
For further information on this configuration, see above.
  
 
{{modules}}
 
{{modules}}

Latest revision as of 21:49, 26 January 2023

About this Module

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

Supported Features

Type One Time Recurring Refunds Reversals
3rd Party Yes Yes Yes

No


Adding the 2CheckOut Payment Gateway

To set up the 2CheckOut payment gateway in WHMCS:

  1. Go to the appropriate location for your version of WHMCS:
    • For WHMCS 8.0 and later, go to Configuration () > Apps & Integrations or Addons > Apps & Integrations.
    • For WHMCS 7.10 and earlier, go to Setup > Products/Services > Payment Gateways and choose All Payment Gateways.
  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.
  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, navigate 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 the section below.
  10. Check Skip 2CO Fraud Check to prevent 2Checkout from performing their fraud checks on payments. If a payment in WHMCS is later determined to be fraudulent, manual action would be required to 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 version.

This applies to 2Checkout's legacy inline checkout style and not to their current InLine checkout feature.

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. In the Global URL field, 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 configure Direct Return to return clients to your WHMCS installation after payment:
    1. Under Redirect URL in the Approved URL field, set the 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

In order to use demo mode, set the Demo Setting in your 2CheckOut account to Parameter under Account > Site Management. Then, in WHMCS, enable demo mode by checking the checkbox at Configuration () > System Settings > Payment Gateways or, prior to WHMCS 8.0, Setup > Payments > Payment Gateways.

When you use demo mode, all callbacks from 2CheckOut will fail with the error MD5 Hash Failure if a secret word is specified. This is done intentionally by 2Checkout to protect sellers of digital goods from fraudulent purchases through their demo mode.

In Demo Mode, valid credit card data must be submitted in order to properly perform the request. Credit cards will not be charged during this process.

Troubleshooting

MD5 Hash Failure

An MD5 Hash Failure error under Billing > Gateway Log indicates that the secret word in Configuration () > System Settings > Payment Gateways or, prior to WHMCS 8.0, Setup > Payments > 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 is possible that 2CheckOut is not allowing the use of inline checkout. Changing to standard checkout can resolve this.

Authentication failed

This error at Billing > Gateway Log indicates that the secret word, API username, or API password are incorrect. You can update these at Configuration () > System Settings > Payment Gateways or, prior to WHMCS 8.0, Setup > Payments > Payment Gateways.

For further information on this configuration, see above.

Server Modules
cPanel/WHM - DirectAdmin - Plesk - Helm 3 - Helm 4 - Ensim - InterWorx - WebsitePanel - Cloudmin
Lxadmin - Virtualmin Pro - XPanel - HyperVM - SolusVM - Cloudmin - WHMSonic - VPS.Net
CentovaCast - SCPanel - MediaCP - GameCP - TCAdmin - Reseller Central - Auto Release - Heart Internet

Registrar Modules
Enom - ResellerClub - Nominet - OpenSRS - ResellOne - OnlineNIC - PlanetDomain - Affordable Domains
TPP Wholesale - TPPInternet - Stargate - Namecheap - NetEarthOne - Bizcn - InternetBS - GMO Internet
12Register - Registercom - DotDNS - WebNIC - Dot.TK - HexoNet - Realtime Register - Registereu
RRPProxy - ResellerCamp - TransIP - Heart Internet - IPMirror - NetRegistry - OVH - VentraIP Wholesale
Email - 101Domain

Fraud Modules
MaxMind - VariLogiX FraudCall - Telesign

Gateway Modules
2CheckOut - AsiaPay - Auth.net Echeck - Authorize.net - Authorize.net CIM - Bank Transfer - BidPay
BluePay - BluePay Echeck - BluePay Remote - Boleto - CashU - CC Avenue - ChronoPay - Direct Debit
EMatters - E-Path - eProcessingNetwork - eWAY Tokens - F2B - Finansbank - GarantiBank - Gate2Shop
Inpay - InternetSecure - IP.Pay - Kuveytturk - Modulo Moip - Mail In Payment - Merchant Partners
Merchant Warrior - IDEALMollie - Moneris - Moneris Vault - Skrill 1-Tap - NaviGate - NETbilling
Netregistry Pay - NoChex - Offline Credit Card - Optimal Payments - PagSeguro - Payflow Pro - Pay Junction
Paymate AU and NZ - Payment Express - PayPal - PayPal Card Payments - PayPal Express Checkout
PayPal Payments - PayPal Payments Pro - PayPoint.net (SecPay) - Payson - Planet Authorize - ProtX VSP Form
PSIGate - Quantum Gateway - Quantum Vault - SagePay - SagePay Tokens v2 - SecurePay
SecurePay AU - Secure Trading - TrustCommerce - USA ePay - WorldPay - WorldPay Invisible


Retrieved from "http://3.17.75.209/index.php?title=2CheckOut&oldid=33845"