Skip to content
Optimizely CertificationOptimizely Certification Optimizely Certification

Commerce Payment API Reference

advanced
📜Corecommerce

Overview

Section titled “Overview”

The Payment API processes financial transactions during checkout. Implement IPaymentPlugin for custom payment gateways. The payment flow follows authorize, capture, void, and refund steps.

Namespace

Section titled “Namespace”

Optimizely.Commerce.Order

Key interfaces

Section titled “Key interfaces”
InterfacePurpose
IPaymentPluginCustom payment gateway integration
IPaymentManagerFacadeManage payment methods
IPaymentRepresents a payment on an order

IPaymentPlugin

Section titled “IPaymentPlugin”

Implement this interface to integrate a payment gateway.

ProcessPayment(IOrderGroup, IPayment)

Section titled “ProcessPayment(IOrderGroup, IPayment)”

Processes a payment transaction.

Parameters

NameTypeDescription
orderGroupIOrderGroupThe cart or order
paymentIPaymentPayment to process

Returns: PaymentProcessingResult

Implement a custom payment plugin
csharp 
public class CustomPaymentGateway : IPaymentPlugin
{
  public PaymentProcessingResult ProcessPayment(
      IOrderGroup orderGroup,
      IPayment payment)
  {
      var transactionType = payment.TransactionType;

      switch (transactionType)
      {
          case TransactionType.Authorization:
              return Authorize(payment);
          case TransactionType.Capture:
              return Capture(payment);
          case TransactionType.Void:
              return VoidPayment(payment);
          case TransactionType.Credit:
              return Refund(payment);
          default:
              return PaymentProcessingResult.CreateUnsuccessfulResult(
                  "Unsupported transaction type.");
      }
  }

  private PaymentProcessingResult Authorize(IPayment payment)
  {
      // Call external gateway
      payment.AuthorizationCode = "AUTH-12345";
      return PaymentProcessingResult
          .CreateSuccessfulResult("Authorized.");
  }

  private PaymentProcessingResult Capture(IPayment payment)
  {
      payment.TransactionID = "TXN-67890";
      return PaymentProcessingResult
          .CreateSuccessfulResult("Captured.");
  }

  private PaymentProcessingResult VoidPayment(IPayment payment)
  {
      return PaymentProcessingResult
          .CreateSuccessfulResult("Voided.");
  }

  private PaymentProcessingResult Refund(IPayment payment)
  {
      return PaymentProcessingResult
          .CreateSuccessfulResult("Refunded.");
  }
}

Transaction types

Section titled “Transaction types”
TransactionTypeDescription
AuthorizationVerifies funds and places a hold
CaptureCharges the authorized amount
SaleCombines authorization and capture
VoidCancels an authorization before capture
CreditRefunds a captured payment

Payment flow

Section titled “Payment flow”
Authorization → Capture → (optional) Credit
      ↓
     Void

IPayment properties

Section titled “IPayment properties”
PropertyTypeDescription
PaymentIdintUnique payment identifier
PaymentMethodIdGuidPayment method reference
PaymentMethodNamestringDisplay name
AmountdecimalTransaction amount
StatusstringCurrent payment status
TransactionTypestringAuthorization, Capture, Void, Credit
TransactionIDstringGateway transaction ID
AuthorizationCodestringAuthorization code from gateway
ValidationCodestringValidation code
BillingAddressIOrderAddressBilling address
ProviderTransactionIDstringProvider-specific transaction ID

PaymentProcessingResult

Section titled “PaymentProcessingResult”
PropertyTypeDescription
IsSuccessfulboolWhether the transaction succeeded
MessagestringResult message or error description
Factory methodDescription
CreateSuccessfulResult(string)Creates a successful result with message
CreateUnsuccessfulResult(string)Creates a failed result with error message

IPaymentManagerFacade

Section titled “IPaymentManagerFacade”

GetPaymentMethodsByMarket(MarketId)

Section titled “GetPaymentMethodsByMarket(MarketId)”

Returns available payment methods for a market.

Parameters

NameTypeDescription
marketIdMarketIdTarget market

Returns: IEnumerable<PaymentMethodDto.PaymentMethodRow>

Add payment to cart
csharp 
public void AddPayment(ICart cart, Guid paymentMethodId, decimal amount)
{
  var payment = cart.CreateCardPayment();
  payment.PaymentMethodId = paymentMethodId;
  payment.Amount = amount;
  payment.TransactionType = TransactionType.Authorization.ToString();

  cart.GetFirstForm().Payments.Add(payment);
  _orderRepository.Save(cart);
}

Registering a payment plugin

Section titled “Registering a payment plugin”
Register in dependency injection
csharp 
services.AddTransient<IPaymentPlugin, CustomPaymentGateway>();

Common exceptions

Section titled “Common exceptions”
ExceptionCause
PaymentExceptionGateway returned an error
InvalidOperationExceptionPayment method not configured for market
ArgumentExceptionInvalid amount or missing required fields
PaymentAuthorizationExceptionAuthorization declined by gateway