Cybersource

Connect CyberSource to Recurly using your Merchant ID, SOAP Toolkit key, and P12 certificate to process card, Apple Pay, and Google Pay transactions globally.

CyberSource is a full-service payment management platform. Integrating it with Recurly lets you securely process card payments, Apple Pay, and Google Pay globally, with 3DS2 support and flexible AVS configuration. You'll need your CyberSource Merchant ID, a SOAP Toolkit key, and a P12 certificate to complete the setup.

Available on all Recurly plans

1Definition 2Key details 3Configuring CyberSource in Recurly

Limitations

No gateway-level fraud management — Recurly does not support gateway-level fraud management behaviors for CyberSource.
No lifecycle or post-auth webhooks — Recurly does not support lifecycle or post-auth webhooks from CyberSource. If you're using gateway-level fraud review systems or making transaction actions directly at the gateway, Recurly and CyberSource can fall out of sync. Always capture, void, and process refunds from Recurly rather than directly in the gateway.

Definition

CyberSource is a full-service payment management platform that supports subscription billing, one-time transactions, and a wide range of card brands globally. The Recurly integration uses CyberSource's SOAP Toolkit API and P12 certificate-based authentication. You'll need your CyberSource Merchant ID, SOAP Toolkit key, and a P12 certificate file and password to connect.

Key details

Feature	Details
Services that work with Recurly	Payment processing
Supported operations	Purchase, Authorize and Capture, Void, Refund, AVS checks
Supported payment types	Credit/debit card, Apple Pay, Google Pay. Note: Apple Pay is not supported with the TSYS/Vital acquirer.
Supported card brands	Visa, Mastercard, American Express, Discover, Diners Club, JCB, Union Pay
Gateway-specific 3DS2 supported	Yes
Card on file supported	Yes
Regions	Global
Currencies	See all available

Address Verification System (AVS) settings

CyberSource merchants can configure AVS checks to one of three options — set this when configuring or editing the gateway in Recurly:

All transactions — AVS checks run on every transaction globally.
US and Canada only (recommended) — AVS checks run only for US and Canadian transactions.
Disabled — AVS checks are turned off entirely.

Recurly recommends enabling AVS for the US and Canada only. AVS works reliably in those regions but can be inconsistent or unsupported internationally — enabling it globally may cause unnecessary declines.

CyberSource processor configuration

CyberSource may require different integration parameters depending on the processor linked to your account. When configuring the CyberSource gateway in Recurly, you must select the correct processor in the Credit Card Processor dropdown.

Warning Do not leave the Credit Card Processor selection unset. Various compliance mandates rely on this value to pass the correct data to the gateway. Leaving it blank can cause transaction failures.

Configuring CyberSource in Recurly

Step 1: Access your CyberSource Business Gateway

Step 2: Generate a SOAP Toolkit key

Navigate to Key Management

In your CyberSource Business Center, go to Payment Configuration → Key Management and select Generate Key → SOAP Toolkit API.

Download the key

Click Download Key. If prompted for a password, use your Merchant ID.

Copy the key before leaving the page

Copy the generated key immediately — you'll need it in Step 4 to connect CyberSource with Recurly.

Important — P12 authentication required CyberSource is upgrading SOAP API authentication from username/password to P12 certificate-based authentication. You must remove username/password authentication and transition to certificate-based authentication by the following dates:

Sandbox: September 1, 2025
Production: September 15, 2025

Step 3: Generate your P12 certificate

Generate the certificate

In your CyberSource Business Center, go to Payment Configuration → Key Management, select Generate Key → REST Certificate, and click Download Key. Note where the file is saved — you'll need it in Step 4.

Set a certificate password

Enter a password in the New Password and Confirm Password fields, then click Generate Key. Keep this password — you'll need it in Step 4.

Step 4: Enter CyberSource credentials in Recurly

Open Payment Gateways

In Recurly, navigate to Payment Gateways, click Add a New Gateway, and select CyberSource.

Enter your Merchant ID and SOAP key

Enter your CyberSource Merchant ID in the Login field, and paste your SOAP Toolkit key into the Key field.

Upload your P12 certificate

Upload the P12 certificate file you generated in Step 3, then enter its password in the P12 File Password field.

Step 5: Configure 3DS2 support (optional)

Check Enable 3DS2 support if you want to support 3DS2 verification flows. Only enable this if 3DS is active on your CyberSource account.

To enforce 3DS challenges for subscription signups and one-time charges, contact Recurly Support to enable the challengeCode parameter for your implementation.

Warning Not all CyberSource processors support the challengeCode parameter. Confirm with your CyberSource representative before enabling it in Recurly — enabling it on an unsupported processor will cause payment failures.

Step 6: Set your credit card processor and card types

Under Accepted Card Types, enable only the card brands active on your CyberSource account. In the Credit Card Processor dropdown, select the main processor for your CyberSource account. If you're unsure which processor to select, consult your CyberSource account representative.

Step 7: Enable currencies

USD is enabled by default. Use the currency selection tool to add or remove currencies based on what your CyberSource gateway accepts.

Step 8: Enable Zero Dollar Authorizations

Enable Zero Dollar Authorizations (ZDA) for each applicable card type. ZDA is essential for validating card data before subscriptions start and when offering free trials.

Step 9: Configure AVS settings

Select your AVS preference for the CyberSource gateway — see the AVS settings section above for guidance on each option.

Step 10: Save and enable the gateway

Click Add Payment Gateway. CyberSource will appear in your Production Gateways list in Recurly with a status of Enabled.

Step 11: Test the configuration

Run a test transaction to confirm the integration is working correctly. Use your Recurly sandbox site in development mode before going live.

Step 12: Go live

Once testing passes, you're ready to accept live payments through CyberSource.

Tip Keep your CyberSource credentials secure and limit access to authorized personnel. Regularly review and regenerate your SOAP Toolkit keys for added security. Consult your CyberSource account representative to confirm your account is in good standing and compliant with all relevant regulations.