CyberSource Connector 

In this Article
Related Articles


With FormAssembly's CyberSource integration, you can accept credit card payments with your form. That means secure transactions in one step the credit card information is sent directly to CyberSource, and only the confirmation code is stored on FormAssembly.

We also recommend reading more about how you can use our reCAPTCHA feature to prevent spam submissions on your payment form.

Please note, the Cybersource connector is currently unable to run transactions with a $0 amount.  If you need to run $0 transactions, the only current workaround is to use an alternative payment connector.

Sensitive Data Notice

Credit Card Numbers and CVV Codes must be marked as Sensitive Data.  Please click here to read more about these fields.


You'll need a CyberSource account and FormAssembly's Premier, Enterprise Cloud or Compliance Cloud plan.

Required Fields

As you build your form, make sure you collect the following information:

  • Credit card number
  • Credit card expiration date (month and year)
  • Credit card security code
  • Billing first and last name
  • Billing postal address
  • Billing email address

Many of these items can already be found in our predefined content, to help you save time in the form-building process.

Typically, your form should also list billable items and allow quantities to be defined.

Configuration Steps

1. Access Authorization

Enter the Merchant ID and the Transaction Key for your CyberSource account.

You can generate the Transaction Key in CyberSource by choosing Payment Configuration and then Key Management from the left navigation menu. 

You'll then want to generate a new Key for Transaction Processing.

The Reference Code is a value that corresponds to the transaction reference in CyberSource.  You can find out more here under the "Merchant Reference Code" section in Table 3.

The Production Status must be set to "Live" in order to process credit cards. On "Test" mode, credit cards will not be charged.


2. Payment Information

Match your form's fields to the payment information required by CyberSource. In most cases, all fields will be "defined in the form," so you'll be able to select the corresponding fields in the drop-down menu.

If certain information isn't collected in the form, you can choose to provide that information here, by choosing the "defined here" option in the drop-down menu and entering the value in the text input.


3. Billing Information

Match your form's fields to the billing information required by CyberSource, as above.


4. Item(s) for Sale

With the Billing Action, you can create either one-time or recurring payments (subscriptions). To create both, you'll need to set up a second CyberSource connector.

You can then list your billable items. The setup depends on how you've built your form.

Make sure the Run Mode is set to Enabled at the top of the connector setup page, and don't forget to click Apply at the bottom right. You're good to go!

If you are working with repeated fields in your form, you can read more here about how those can be used with your payment connector.

Recurring Payments

In order to set up recurring payments through CyberSource, you will need to make sure that the Billing Action under Step 4 is set to recurring.

This can either be done in the connector, so that every purchase made is recurring, or triggered by a selection in your form so that users are able to choose if they would like to make a single or recurring payment.

Once you have selected the Billing Action as recurring, you will need to set the Billing Frequency (i.e. weekly, every two weeks, etc.) and if needed the Stop Billing After" (i.e. 12 months, 6 weeks, etc.).  These mappings can also be defined here in the connector, or by a selection within the form.

After you have set up these initial configuration details, the remainder of the setup for recurring billing is identical to the steps above for one-time purchases.  You will need to map the item name, price, and quantity, for the item(s) being purchased, and then save the connector.

Processing One-Time and Recurring Payments with a Form

It is possible to process both one-time and recurring payments within a form. In order to enable this setup, you will have to add two separate CyberSource connectors to your connector timeline. This way, you can configure one of the connectors to run for single payments, and the other connector to run for recurring payments.  You can read more about this setup here.

Test the CyberSource Connector

Before processing payments, it is a good idea to run several tests on your CyberSource connector to make sure that everything is set up correctly. On the CyberSource side, make sure you log in to the Business Center Test Environment

You will need to generate a test SOAP API key after logging in to the Test Business Center, and use that with your connector when Production Status is set to Test.

If you are running into errors with your connector, make sure that when production mode is set to "Test" you are using API keys from the Test Business Center, and when production mode is set to "Live" you are using API keys from the Live Business Center.

Form Fields Added by the Connector

Once you add the CyberSource connector to your timeline, the following form fields will be added as hidden fields to the bottom of your form:

  • tfa_CyberSource_Transaction_Reference
  • tfa_CyberSource_Transaction_Token
  • tfa_CyberSource_Auth_Success
  • tfa_CyberSource_Auth_Message
  • tfa_CyberSource_Subscription_Id

Sending Connector Data to Salesforce

If you would like to send the values of any of these four fields above through to Salesforce (or in any other connector) you must place the CyberSource connector before the other connector in the connector timeline.

Additionally, you should not map these fields in the connector, but instead select that the field gets its value from a formula or text, and use the alias for the field.

For example, if you wanted to send the Transaction Reference to Salesforce, you would use %%tfa_CYBERSOURCE_TRANSACTION_REFERENCE%% as the alias in the field mapping.

Payment Tokenization

In the current version of CyberSource Connector, payments are not tokenized using CyberSource API. Because of this, there will not be any payment token retrieved and saved in the log.

APIs Used

The CyberSource connector uses 3 APIs:

  1. Authorize - to authorize a credit card
  2. Capture - to make a one-time payment
  3. addSubscription - to create a new subscription

Troubleshooting the CyberSource Connector

If you receive an error that reads "Error: General System Failure" then you will want to log in to your CyberSource account and perform a general search for all transactions that occurred during the day or time the error was received.

After performing this search, you should be able to locate the attempted submission that caused this error. If you click on the Request ID for the specific response that caused the error, you will be able to find out additional details for why this error occurred.

Terms of Service · Privacy Policy