Set custom values for gateway-specific fields

6 min

Optimizely Configured Commerce's Payment Service lets you create a provider to configure specific fields for your gateway.

The following example takes the transaction type and dictionary of custom parameters as input parameters.

The transaction type is set automatically and depends on the current transaction's type.

The parameters are passed from the properties of the AddPaymentTransactionParameter object, which you can populate in the ProcessCreditCardTransactions handler.

There are two ways to customize gateway-specific fields:

Static fields – Create a custom GatewaySpecificFieldsProvider.

Flexible fields – Create a custom GatewaySpecificFieldsProvider and override the ProcessCreditCardTransactions handler and pass custom string values through AddPaymentTransactionParameter.

Structure of the GatewaySpecificFields object

GatewaySpecificFields is the outer container object. It has a property called GatewaySpecifics, which is a list of GatewaySpecific objects.

GatewaySpecific represents settings or parameters specific to a single payment gateway. In this example, the GatewayName is stripe_payment_intents, meaning these settings are for the Stripe Payment integration. Fields is a list of key-value pairs (GatewaySpecificField) that define specific options or behaviors for this gateway.

GatewaySpecificField represents a single setting for the payment gateway. In this example, Name is request_multicapture, and Value is if_available.

Example

public class CustomGatewaySpecificFieldsProvider : IGatewaySpecificFieldsProvider  
{  
    public GatewaySpecificFields GetGatewaySpecificFields(  
        TransactionType transactionType,  
        IDictionary\<string, string> parameters  
    )  
    {  
        return new GatewaySpecificFields  
        {  
            GatewaySpecifics = new List<GatewaySpecific>()  
            {  
                new GatewaySpecific  
                {  
                    GatewayName = "stripe_payment_intents",  
                    Fields = new List<GatewaySpecificField>  
                    {  
                        new GatewaySpecificField  
                        {  
                            Name = "request_multicapture",  
                            Value = "if_available"  
                        }  
                    }  
                }  
            }  
        };  
    }  
}

Override gateway properties at transaction time

The IGatewayPropertyResolver interface lets you override gateway properties at transaction time. Use this to route transactions to different payment gateways based on context such as currency, region, or website.

The interface is in the Insite.Core.Plugins.PaymentGateway namespace and extends IDependency and IExtension.

Interface definition

public interface IGatewayPropertyResolver : IDependency, IExtension
{
  T Resolve<T>(string propertyName, T defaultValue, GatewayPropertyContext context);
}

The Resolve<T> method receives the property name being resolved (for example, "GatewayToken"), its default value from Admin Console settings, and a GatewayPropertyContext with transaction details. Return a different value to override the default.

GatewayPropertyContext

The context object provides transaction-specific data:

public sealed class GatewayPropertyContext
{
    public TransactionType TransactionType { get; }
    public string CurrencyCode { get; }
    public decimal? Amount { get; }
    public string CustomerNumber { get; }
    public Guid? WebsiteId { get; }
    public Guid? CustomerOrderId { get; }
    public IReadOnlyDictionary<string, stringProperties { get; }
}

Instances are created via the static factory method GatewayPropertyContext.Create(...).

Example: Route transactions by currency

This example routes transactions to different Spreedly gateway tokens based on the order currency.

public class CurrencyBasedGatewayPropertyResolver : IGatewayPropertyResolver
{
    private readonly Dictionary<string, stringgatewayTokensByCurrency = new()
    {
        { "USD", "gateway-token-usd" },
        { "EUR", "gateway-token-eur" },
        { "GBP", "gateway-token-gbp" }
    };
>
    public T Resolve<T>(string propertyName, T defaultValue, GatewayPropertyContext context)
    {
        if (propertyName == "GatewayToken"
            && gatewayTokensByCurrency.TryGetValue(context.CurrencyCode, out var token))
        {
            return (T)(object)token;
        }
>
        return defaultValue;
    }
}

Register the resolver

The IGatewayPropertyResolver interface extends IDependency, so Configured Commerce discovers and registers your implementation automatically. No manual DI registration is required.

The default implementation (GatewayPropertyResolver) returns defaultValue unchanged. When a custom implementation is registered, the Payment Service calls Resolve before each transaction and uses the returned value.