Configure Payment Service

16 min

Spreedly standalone integration deprecated

Spreedly is no longer listed as a standalone payment gateway option in the gateway selector. Selecting Spreedly outside the Payment Service displays a provisioning message: "Payment Service must be provisioned to use Spreedly Payment Gateway IFrame. Please reach out to support team."

Storefronts using the direct Spreedly integration should migrate to the Payment Service. See Configure Payment Service for setup instructions.

With Optimizely Commerce's Payment Service, you can add payment gateway providers for your ecommerce. This uses Spreedly's iFrame to offer more flexibility and stability:

Use a payment platform without implementing new code.

Access more payment gateway options.

Implement multiple payment services on a single website.

Note

Although Payment Service supports multiple gateways for a single site, there is currently a limit of one gateway per site in Optimizely Configured Commerce. Work with your partner if you want to customize this.

Prerequisites

Before you enable Payment Service for Optimizely Configured Commerce or Optimizely Commerce Connect, you should look at the list of Spreedly-supported gateways.

The Spreedly integration is available for Spire sites only. If your site is on Classic, use the library of existing payment gateways until you upgrade to Spire.

After you select a gateway, note the following:

If an ERP or other third-party system needs payment tokens, such as to capture a payment after delivery, the gateway must support the Store operation. This should be listed under the Supported operations section for the payment gateway fact sheet. See the Stripe Payment Intents fact sheet as an example.

If the gateway requires 3DS2, the fact sheet displays Yes for Spreedly 3DS2 Global Support. This is what you configure in the Payment Service when adding a merchant profile and SCA provider.

Gateway Specific 3DS2 Supported refers to the gateway's native 3DS2 support, which Payment Service does not support at this time.

All payment gateways are different and require a different implementation in Spreedly and the Payment Service. You should read the Spreedly gateway guide for the steps you must take with the gateway provider, either configurable by the payment portal or by contacting support, to turn certain features on or off.

Some gateways have gateway_specific_fields. This passes gateway custom information from Optimizely and the Payment Service to the payment gateway provider. You or your partner can fully customize the gateway-specific fields. For example, you could send the necessary order information to the ERP system from the payment gateway.

If the gateway intended to be used is not part of this list, contact Optimizely support.

Enable Payment Service

Configured Commerce

To use the Payment Service, contact Optimizely Support to have the keys for a Payment Service instance added to your commerce environment.

After the keys are added and you restart the site, you can see the admin pages for Payment Service to continue the configuration.

Commerce Connect

To use the Payment Service, contact Optimizely Support to have the Payment Service instance created. They can then provide the instance keys that must be added to appsetting.json in Commerce Connect after downloading the Optimizely.PaymentService.Client NuGet package.

"PaymentServiceOptions": {
			"PaymentServiceIsEnabled": true,
			"PaymentServiceUrl": "https://xxx.xxx/",
			"AppKey": "xxxxx”,
			"SecretKey": "xxxxx”,
			"AuthenticationType": "HMAC”,
			"EnvironmentKey": "xxx",
			"SigningSecret": "xxx",
			"EnvironmentName": "abc"
			}

The supported authentication types are HMAC and OBO.

If the EnvironmentKey is empty, provide an EnvironmentName and add the following code to the Configure function of the Setup.cs file. The environment was automatically established during start-up and running.

app.SetupPaymentService();

After the keys are added and you restart the site, you can see the admin pages for Payment Service to continue the configuration.

Add gateways

Go to Administration > Payment Service in Configured Commerce or Commerce Administration > Settings > Payment Service in Commerce Connect.

Click Add Gateway.

Select the gateway from the drop-down list. The form populates additional fields depending on the gateway.

(Optional) Enter a Description.

(Optional) Select your Merchant Profile Key if you have already created a merchant profile.

Select whether to use this gateway in your Sandbox Site.

Fill in any additional information for your gateway.

Click Create.

Enable 3DS authentication

To enable 3DS authentication, create a merchant profile and an SCA provider. The merchant profile holds the SCA provider, which runs 3DS2 Global authentications on the authenticate endpoint or as part of authorize and purchase transactions.

Note

You cannot perform a new 3DS authorization or sales transaction through the Admin Console in Configured Commerce.

Add a merchant profile

Information for the merchant profile fields comes from your payment provider.

Go to Administration > Payment Service > Merchant Profiles in Configured Commerce or Commerce Administration > Settings > Payment Service > Merchant Profiles.

Click Add Merchant Profile.

(Optional) Enter a Description.

Enter a Sub-Merchant Key.

Select a credit card from the drop-down list.

Enter the Acquirer Merchant ID.

Enter the Merchant Name.

Enter a Country Code.

Enter the MCC. The MCC is the Merchant Category Code, which classifies the type of goods or services that the business sells. See Spreedly's documentation for information.

Repeat steps 5-9 for all card types your site supports.

Click Create.

Add an SCA provider

You must create a merchant profile first to add a Strong Customer Authentication (SCA) provider.

Go to Administration > Payment Service > SCA Providers in Configured Commerce or Commerce Administration > Settings > Payment Service > SCA Providers in Commerce Connect.

Click Add SCA Provider.

Select a Merchant Profile.

Enter the Type.

Select whether to use this SCA Provider in your sandbox.

Select a Credit Card from the drop-down list.

Enter the Acquirer BIN.

Enter the Merchant Url.

Enter the Merchant Brand Id.

Enter the Merchant Password.

Repeat steps 6-10 for all card types your site supports.

Click Create. You can also click Cancel to exit without saving.

Important

After you create the SCA provider, the SCA Provider Key displays. Copy this key because this is the only time this information is displayed. If you lose it, you must create another SCA provider.

Test 3DS integration

Before going to production, you should test your 3DS integration. See Testing your 3DS2 Global Integration in Spreedly's documentation for information.

Enter credentials under settings

Configured Commerce

When you have completed the previous steps, go to Administration > Settings > Spreedly and enter the following information:

Enter the gateway token from Add gateways. This can be website-specific.

Toggle on 3DS Enabled.

Enter the SCA Provider Key and Signing Secret from Add an SCA provider.

A website-specific setting, Payment Service Request/Response Logging, is available under Administration > Settings > Order Management > Payment. When enabled, the system logs request and response payloads exchanged with Payment Service. Sensitive data is automatically masked, and logging failures do not impact payment processing.

Commerce Connect

When you have completed the previous steps, go to Commerce Administration > Settings > Payments, click Create, and enter the following information:

Enter the Name.

Enter the System Keyword.

Enter the Description.

Select a Language.

Select a Class Name.

Select a Payment Class.

Select whether to use this payment in IsActive.

Select whether to use this payment in IsDefault.

Click Save. You can also click Cancel to exit without saving.

Select the payment method you just created and go to the Parameters tab. Click Add parameter.

Enter the parameter name as GatewayToken.

Enter the parameter value with the key that was created.

Click Save. You can also click Cancel to exit without saving.

Go to the payment method you just created. Go to Markets and select the active markets. Click Save if you made changes.

If you want to use 3DS, create two parameters with the following:

ThreeDsIsEnabled – True

ScaProviderKey – The key that was created

Click Save. You can also click Cancel to exit without saving.

Note

You can create other methods and sort by IsActive, IsDefault then Ordering values.

Implement verify a card transaction type (optional)

Commerce's Payment Service supports the Verify transaction type, which validates a payment method without placing a charge. Use Verify for scenarios such as saving a card on file or validating a payment method before a subscription begins.

Verify transactions are supported through Spreedly. This feature requires custom development through extensions. Override the appropriate payment processing handler to call the Verify endpoint instead of Authorize. See Verifying a card in Spreedly's documentation for information.

3D Secure is not supported for Verify transactions.

How it works

The following flowchart demonstrates the payment service process during cart submission.

AVS and CVV gateway provisioning

Some Spreedly-supported payment gateways let you configure Address Verification System (AVS) and Card Verification Value (CVV) behavior through the APIs or merchant portal. See AVS and CVV gateway provisioning for SpreedlyAVS and CVV gateway provisioning for Spreedly for information.