Difference between revisions of "2CheckOut"

Revision as of 20:24, 18 March 2022

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:

Go to Configuration () > System Settings > Payment Gateways or, prior to WHMCS 8.0, Setup > Products/Services > Payment Gateways.
Choose the All Payment Gateways tab.
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. You can choose from the following checkout styles:
- Inline Checkout — An iframe payment option which displays a secure payment form as an overlay when your client is making payment.
  - This allows for payment to be taken from a client without them leaving your site.
  - WHMCS recommends this checkout style when using 2CheckOut.
- Standard Checkout — Standard Checkout will redirect a client to the 2CheckOut site to make payment before they are redirected back to your site.
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.
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.
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.

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:
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.
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.
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 inConfiguration () > 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

Authentication failed

This error in the Gateway Log indicates that either the secret word, API username, or API password are incorrect. These may be reconfigured 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

@@ 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
 | onetime = yes
 | recurring = yes
 | refunds = yes
+| updatecc = yes
 }}
-==Setup==
+== Adding the 2CheckOut Payment Gateway==
-To set up 2CheckOut:
+To set up the 2CheckOut payment gateway in WHMCS:
-# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup > Payments > Payment Gateways'''.
+# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' or, prior to WHMCS 8.0, '''Setup > Products/Services > Payment Gateways'''.
-# Choose '''2CheckOut''' from the '''All Payment Gateways''' tab.
+# Choose the '''All Payment Gateways''' tab.
-# Configure 2CheckOut as described below.
+# 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. You can choose from the following checkout styles:
+#* '''Inline Checkout''' — An iframe payment option which displays a secure payment form as an overlay when your client is making payment.
+#** This allows for payment to be taken from a client without them leaving your site.
+#** WHMCS recommends this checkout style when using 2CheckOut.
+#* '''Standard Checkout''' — Standard Checkout will redirect a client to the 2CheckOut site to make payment before they are redirected back to your site.
+# 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'''.
-[[File:2checkout-config.png|800px|2CO Configuration]]
+=== Recurring Billing ===
-===Notifications===
+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.
-[[File:2checkout notifications.png|thumb|2CO Notifications Setup]]
+If you choose '''Offer One Time Only''', you must configure it in your 2CheckOut account:
-To set up the 2CheckOut callback process to automatically mark invoices paid:
 # Log in to your 2CheckOut account.
-# Click the '''Integrations''' tab.
+# Go to the '''Integrations''' tab.
-# Check '''Enable INS''' and '''Enable global URL'''.
+# To set the 2CheckOut callback process to automatically mark invoices paid:
-# 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.
+## Check '''Enable INS''' and '''Enable global URL'''.
-# Click '''Update'''.
+## 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:
-===Direct Return===
+## 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'''.
-To return clients to your WHMCS installation after a successful payment, configure Direct Return within the 2CheckOut control panel:
-# Navigate to '''Integrations'''.
-# 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.
-[[File:2checkout_merchantid.png|thumb|2CO Vendor Account Number]]
-===Vendor Account  Number===
-You can find the vendor account number in your 2CheckOut account by clicking the gear icon and copying the '''Merchant Code''' into the '''Vendor Account Number''' field.
-===Checkout Style===
-Two checkout styles are made available as part of 2CheckOut configuration:
-* '''Inline Checkout''' — An iframe payment option which displays a secure payment form as an overlay when your client is making payment.
-** This allows for payment to be taken from a client without them leaving your site.
-** WHMCS recommends this checkout style when using 2CheckOut.
-* '''Standard Checkout''' — Standard Checkout will redirect a client to the 2CheckOut site to make payment before they are redirected back to your site.
-===API Username/Password===
-[[File:2co-api-new.JPG|thumb|2CO API User Setup]]
-To use the inline, recurring billing, and automatic refunds functionality within WHMCS, set up a 2CheckOut API user and enter the details in these fields.
-To set up an API user:
-# Log in to your 2CheckOut account.
-# Go to '''Settings > Manage User Access > View Roles > Add Role'''.
-# Enable  '''Manage api access'''.
-# Go to '''Settings > Manage User Access > View Users > Add User'''.
-# Create a new user, assigning it to the role just created.
-# Enter the username and password in the appropriate API username and API password fields in WHMCS.
-===Secret Word===
-<div class="docs-alert-info">
-<span class="title">Note</span><br />
-The secret word is case-sensitive and should contain the letters a-z only.
-</div>
-For security, you can set a secret word in your 2CheckOut account. You must enter this into WHMCS for notifications and client redirects.
-To do this:
-# In your 2Checkout Account, navigate to "''Integrations''".
-# Copy the '''INS Secret Word''' or generate a new one.
-# Paste the '''INS Secret Word''' into the ''Secret Word'' field of the 2CheckOut configuration in WHMCS.
-===Recurring Billing===
-This option allows you to choose your clients' payment options when viewing an invoice or going through the checkout process.
-WHMCS can change recurring payments with 2CheckOut without the need for the client to log in and pay again. No card details are saved in WHMCS when using 2CheckOut.
-====Offer Recurring and One-Time Payments====
-Allow choices for your clients by providing both recurring and one-time billing options.
-====Offer Recurring Only====
-Only provide a recurring button to your clients. The button will only appear when there is a recurring item on the invoice, and when the invoice is not overdue.
-====Offer One Time Only====
-Only provide the option for one-time payments to your clients. No automatic recurring payments will be received.
-===Skip 2CO Fraud Check===
-Check this to 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 chargebacks.
-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.
-===Convert To For Processing===
-This option will only appear in a multi-currency installation. If you use the '''Standard Checkout''' option, you '''must''' set this 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'''.
-If this is not set properly, your payments may fail.
-==Error Messages==
 ===Demo Mode===
@@ Line 121: / Line 62: @@
 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>
+==Troubleshooting==
 ===MD5 Hash Failure===
@@ Line 132: / Line 75: @@
 This error in the Gateway Log indicates that either the secret word, API username, or API password are incorrect. These may be reconfigured 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 [[#API_Username.2FPassword|see above]].
+For further information on this configuration, see above.
 {{modules}}

Documentation