Introduction
The Cybersource payment gateway is an authorized payment method that can be used with the e-commerce features of your platform.
This article covers how to configure an account profile for your platform in Cybersource, as well as how to set up the Cybersource integration in the platform.
Prerequisites
The Cybersource integration is available on the platform with the e-commerce pack. Contact your Docebo representative for information about how to obtain it.
To do the configurations described in this article you need to already have a Cybersource account:
- You can use a test account, created in the Cybersource developer center (opens in a new tab), to access the Cybersource test portal and configure an integration in a sandbox environment
- You will then need to contact Cybersource (opens in a new tab) to set up your merchant account. This will be used to access the Cybersource production portal, where you configure the “live” integration for accepting real payments.
Additionally, if you intend to use the Cybersource automatic tax calculation feature, you will need to contact Cybersource to activate tax calculation for your account.
Requirements and limitations
- Some currencies supported by Docebo may not be accepted by Cybersource, so remember to check if your currency is supported by both systems before proceeding. Check out the complete list of the currencies supported by Docebo.
Please note: At this time, when you are in sandbox mode, the Cybersource payment gateway only accepts U.S. Dollars. When you are in live mode, all supported currencies are accepted.
- When working with the Extended Enterprise, configure the settings of Cybersource in the root domain. If some domains require a different configuration, apply the configuration locally, in the E-Commerce tab of the Extended Enterprise app.
- Cybersource requires the purchaser’s first name and last name to complete the transaction. These fields are taken from the user’s profile in the platform, they are not entered in the billing information step. Therefore, to be able to use Cybersource, users must have the first name and last name fields populated in their profile.
- When using Cybersource’s automatic tax calculation, please note that the platform’s shopping cart will show the total without taxes added. But when the user is redirected to Cybersource to complete the payment they will also see the added taxes and the new total.
Configure a profile in Cybersource
This chapter covers the configurations that you need to do on the Cybersource side. You need to complete these settings before you can set up your Cybersource integration in the platform.
Create a Secure Acceptance profile
The first step is to create a Secure Acceptance profile for your platform in Cybersource.
Please note: You must create a separate Secure Acceptance profile for your live and sandbox environments.
- The sandbox profile, used for testing, is created in the portal https://ebc2test.cybersource.com/ebc2 (opens in a new tab)
- The production profile, used for real transactions, is created in the portal https://businesscenter.cybersource.com/ebc2/ (global) or https://businesscenter.in.cybersource.com/ebc2/ (India) (both open in a new tab)
You can access the test (sandbox portal) with a Cybersource test account. However to access the production portal you need to have a Cybersource merchant account. For more information see the Prerequisites.
To create a Secure Acceptance profile, log in to Cybersource (either the sandbox or production portal), and in the left menu navigate to Payment Configuration > Secure Acceptance settings. This will open the Secure Acceptance Settings page, listing all the profiles that already exist.
Note: To view or edit the settings of an existing profile, you can click the ellipsis button alongside its name in the list and select the corresponding action.
To create a new profile, click the New profile button and, in the Create profile panel that opens, enter the requested details for your the profile you are creating:
- In the Integration Methods area, select Hosted Checkout.
- Under Added value services, make sure the Payment tokenization and Decision manager options are disabled.
When you are ready click Submit.
Your new profile will be created and automatically opened to its settings page.
Generate a security key for the Secure Acceptance profile
You now need to generate a security key for your profile. On the settings page of your profile, select the Security tab and, in the Active Keys area, click Create key. In the panel that opens define a name for your key, then set the Signature Version to 1, and the Signature Method to HMAC_SHA256. When you are ready click Create, and in the window that opens click Confirm.
At the end of the creation procedure, Cybersource will show you the Secret Key and the Access Key needed to configure the integration between Docebo and Cybersource. Keys have a 2-year validity period.
You also can re-access these values at any time by clicking View key alongside the key name.
Tip: You will need to enter this Secret Key and Access Key, along with your Cybersource Profile ID (visible at the top of the profile page) when you configure Cybersource in the platform.
Payment settings
Now move on the Payment settings tab. Here you need to set up the different card types you want to accept and for each one set the supported currencies, and the card verification method.
Customer response
Move now to the Customer Response tab, set both the Transaction Response Page and the Custom Cancel Response Page options as Hosted by You, and configure them as follows:
Transaction response page: [your full platform URL]/ecommerce/v1/cybersource/validate
Custom cancel response page: [your full platform URL]/ecommerce/v1/cybersource/decline
Where [your full platform URL] can be:
- a docebosaas URL, eg https://myplatform.docebosaas.com
- a custom domain or secondary domain, eg https://learn.mycompany.net
- a folder-type extended enterprise client, eg https://myplatform.docebosaas.com/[folder_name]
Some examples are provided below.
Docebosaas platform URL
- Transaction Response Page = https://[platform_name].docebosaas.com/ecommerce/v1/cybersource/validate
- Custom Cancel Response Page = https://[platform_name].docebosaas.com/ecommerce/v1/cybersource/decline
Custom domain (or secondary domain)
- Transaction Response Page = https://[custom_domain]/ecommerce/v1/cybersource/validate
- Custom Cancel Response Page = https://[custom_domain]/ecommerce/v1/cybersource/decline
Folder-type extended enterprise client
- Transaction Response Page = https://[platform_name].docebosaas.com/[folder_name]/ecommerce/v1/cybersource/validate
- Custom Cancel Response Page = https://[platform_name].docebosaas.com/[folder_name]/ecommerce/v1/cybersource/decline
Merchant notifications
To improve the reliability of your integration, it is strongly recommended to configure the Merchant Notifications setting under the Notifications tab.
Enter the following URL in the Merchant notifications field: https://[platform_name].docebosaas.com/ecommerce/v1/cybersource/notify
Enabling this setting ensures that order status updates and transaction results are consistently delivered back to the platform. It helps prevent transactions from remaining in a Pending state due to network delays, timeouts, or other communication issues.
Set up Cybersource for automatic tax calculation
Complete these steps if you want to use the feature that automatically calculates taxes at checkout.
→ Remember that, to use this functionality, you need to ask Cybersource to enable the tax feature for your Cybersource account. See the Prerequisites.
Move to the Payment form tab of your profile and, under Purchase information:
- Select the check box Display the total tax amount in each step of the checkout process.
Next, for the automatic tax calculation, you need to generate a REST API key. Note that this is not done from your Secure Acceptance profile page, but from the general Key management page.
Important: You cannot use the same REST API key for the sandbox and production environments.
- In the left menu, navigate to Payment configuration > Key management, and in the Key management page click Generate key.
- In the Create key page that opens, under Key types select REST - Shared secret.
- Then scroll to the bottom of the page and click Generate key.
Once the key is generated, you will be able to access the Key and Shared secret. These are the values that you need to enter in the platform for the REST API credentials when you configure the Tax settings.
Tip: Download or copy the Shared secret securely at this point as you will not be able to retrieve it later.
Note: You can view your generated keys from the main Key management page. Change the filters to “All dates” to see the keys. However you cannot retrieve the Shared secret for previously-generated keys, this is only shown at the time of key generation.
Activate the Secure acceptance profile
Before you can use the profile for test or live transactions, it needs to have the Status = Active. You can check this on the profile list or directly from the profile page.
- To activate the profile, click the Promote profile button.
Configure Cybersource in the platform
→ Before you start to configure Cybersource in the platform, make sure you have completed the steps to set up a profile in Cybersource.
In order to set up the Cybersource integration, log in to your platform as a Superadmin. Then navigate to Navigation menu > Configuration (spanner icon) > E-commerce > Cybersource. This will open the Cybersource configuration page.
- If you have already configured Cybersource you will see here a page with all the existing settings: Cybersource account details, Tax settings, Deployment mode.
- Otherwise click Configure Cybersource to begin the configuration.
Cybersource account details
When you start to configure Cybersource, in the right panel that opens you are first of all prompted to enter the credentials of the Secure Acceptance profile (sandbox or production) that you created in Cybersource.
You can copy these values from the Secure Acceptance Setting page for the profile:
- The Profile ID is visible at the top of the page
- The Secret key and Access key can be viewed and copied from the Security tab, using the View key action.
When you are ready click Confirm. You will be taken to the Cybersource settings page. Note that, after this point, the account details you entered previously become read-only, and the Secret key and Access key are hidden for security.
→ If you need to change the account details you will need to reset the Cybersource configuration and start over.
Tip: Remember that, if the credentials entered are for a sandbox Secure Acceptance profile, then you must also select the Sandbox deployment mode. If you instead entered credentials for a production profile, then select the Production deployment mode.
Deployment mode
In this area, set whether you want to operate in the sandbox (test) or live environment.
The choice you make here must match the Cybersource account details that you entered previously.
- If those credentials were for a sandbox Secure Acceptance profile, then here select Cybersource sandbox mode.
- If those credentials were for a production Secure Acceptance profile, then here select Cybersource production mode.
Tax settings
If you want Cybersource to automatically calculate and apply taxes at checkout, you need to configure it here as follows:
- First of all, in your Cybersource Secure Acceptance profile (sandbox or production), make sure you have completed the steps to set up tax calculation: You should have enabled “Display total tax amount” in the Payment form tab, and created a REST API key. For more information, see the chapter: Settings for automatic tax calculation
- Also make sure that Cybersource has activated taxes for your account (contact Cybersource to do this).
Now, in the platform, select the check box Enable automatic tax calculation, and enter your Merchant VAT number.
When you enable automatic tax calculation, you will see that a REST API credentials field appears in the Deployment mode area.
Configure this as follows:
- First, make sure you have already selected the correct deployment mode (sandbox or production), matching the Secure Acceptance profile you are using.
- Then click the Configure REST API button.
- In the panel that opens, enter the Organization ID that you use to log in to the Cybersource portal. (Note, this is not the Profile ID)
- Then enter the API key and Shared secret of the REST API key that you created in Cybersource. See the chapter Set up Cybersource for automatic tax calculation.
When you are finished click Confirm.
Reset Cybersource configuration
Once Cybersource is configured in the platform, you cannot edit the credentials of the Secure Acceptance profile. Therefore, if you need to edit any of these values – for example, to switch from a sandbox to a production profile, which requires changing the account details – you will need to reset the Cybersource configuration and begin again.
To do this, in this area click the Reset Cybersource button. In the window that opens, select the check box to confirm and click Reset Cybersource again.
Best practices
In the shopping cart, when Cybersource is selected as the payment method, the Billing information needs to be filled out as follows:
- If Canada or the United States is set as the country, the State/Province/Region field becomes mandatory, and the user must select an item from the drop-down list.
- For other country selections, the State/Province/Region field is not mandatory. However, if users choose to fill it in they must insert a two-letter code.
- The first name of the user finalizing the payment must not include double quotes ( " ").