Payments service provider

Current version: 10.1

Service providers are wrapper objects designed to make it easier to interact with Connect pipelines. The providers implement no logic other than calling Connect pipelines. All of the business logic is implemented in the pipeline processors.

For each method in the provider, there is a corresponding Request and Result object used, for example, GetCarts takes a GetCartsRequest object and returns a GetCartsResult object. In some cases, the response objects are re-used when returning the same data.

Customized versions of the default request and result arguments can be used by calling the overloaded generics based versions of the methods.

The Payments service provider contains the following methods for interacting with payment data.

GetPaymentOptions method

The GetPaymentOptions method is used to query payment option data against the external commerce system and returns a collection of payment options.

Name:

GetPaymentOptions

Description:

Gets the carts that match the specified criteria. Calls the GetPaymentOptions pipeline.

Usage:

Called when a list of payment options is needed.

Examples include:

  • Getting the list if payment options for a shop.

Signature:

GetPaymentOptionsResult GetPaymentOptions([NotNull]GetPaymentOptionsRequest request)

Input:

ShopName – Optional. Name of shop to retrieve payment options for.

Output:

IEnumerable<PaymentOption> – A collection of payment options for the requested store.

SystemMessages - Collection of messages from the external system.

Usage example:

RequestResponse
var paymentService = new PaymentServiceProvider();
var request = new GetPaymentOptionsRequest("WebShop");
var result = paymentService.GetPaymentOptions(request);

GetPaymentMethods method

TheGetPaymentMethods method is used to query payment data against the external commerce system to retrieve all of the payment methods for a particular payment option.

Name:

GetPaymentMethods

Description:

Gets the payment methods that match the specified criteria. Calls the GetPaymentMethods pipeline.

Usage:

Called when a list of payment methods is needed.

Examples include:

  • Getting the payment methods for a particular payment option type.

Signature:

GetPaymentMethodsResult GetPaymentMethods([NotNull]GetPaymentMethodsRequest request)

Input:

PaymentOptionThe payment option to retrieve payment methods for.

ShopName - optional – The name of the shop.

Output:

IEnumerable<PaymentMethod> – A collection of payment methods for the requested option.

SystemMessages - Collection of messages from the external system.

Usage example:

RequestResponse
var paymentService = new PaymentServiceProvider();
var paymentOption = new PaymentOption
{
    Name = "Visa", 
    PaymentOptionType = new PaymentOptionType(1, "CreditCard"), 
    ShopName = "webShop"
};
var request = new GetPaymentMethodsRequest(paymentOption);
var result = paymentService.GetPaymentMethods(request);

GetPricesForPayments method

The GetPricesForPayments method is used to get a list of possible payment prices for all items in a cart.

Name:

GetPricesForPayments

Description:

Gets the payment costs that match the specified criteria. Calls the GetPricesForPayments pipeline.

Usage:

Called when a list of payment costs is needed.

Signature:

GetPricesForPaymentsResult GetPricesForPayments(GetPricesForPaymentsRequest request)

Input:

ShopName - MandatoryThe name of the current shop.

PaymentLookup – Mandatory – The combination of payment method and options to lookup

Cart – Mandatory – The cart containing the line items to look up.

Output:

ReadOnlyCollection<PaymentPrice> – A collection of payment prices mapped to items in the cart.

SystemMessages - Collection of messages from the external system.

Usage example:

RequestResponse
var paymentLookupList = new List<PaymentLookup>
{
    new PaymentLookup
    {
        OptionId = "{B83E4AA3-5F98-4FEE-95C0-BDE9CE572E7C}",
        LineItemIds = new List<string> {"1", "2"}.AsReadOnly()
    },
    new PaymentLookup
    {
        OptionId = "{B83E4AA3-5F98-4FEE-95C0-BDE9CE572E7C}",
        MethodId = "{8BC8E1DA-4FA8-4D20-AB53-53C104CCC2CC}"
    }
};
var cartProvider = (CartServiceProvider)Factory.CreateObject("cartServiceProvider", true);
var cartRequest = new LoadCartRequest("StarterKit", "cartid");
var cartResult = cartProvider.LoadCart(cartRequest);
var cart = cartResult.Cart;
var provider = (PaymentServiceProvider)Factory.CreateObject("paymentServiceProvider", true);
var request = new GetPricesForPaymentsRequest("StarterKit", paymentLookupList, cart);
var result = provider.GetPricesForPayments(request);
if (result.Success && result.PaymentPrices != null)
{
    foreach (var paymentPrice in result.PaymentPrices)
    {
        // handle payment price.
    }
}

GetPaymentServiceUrl method

The GetPaymentServiceUrl method is used to initialize a transaction with a payment service and retrieve the URL of the payment acceptance page of the payment service.

Name:

GetPaymentServiceUrl

Description:

Retrieves the URL to the payment acceptance page of a federated payment service.

Usage:

Called when a website is ready to retrieve payment information from a customer.

Examples include:

  • When rendering the payment acceptance page during a checkout.

Signature:

GetPaymentServiceUrlResult GetPaymentServiceUrl([NotNull] GetPaymentServiceUrlRequest request)

Input:

HostPageOrigin – Required. Specifies the root URL of the merchant website page that will host the payment acceptance page.

AllowPartialAuthorization – Optional. Specifies whether partial authorizations are allowed in the transaction.

AllowVoiceAuthorization – Optional. Specifies whether voice authorization is allowed in the transaction.

CardType – Optional. Specifies the type of payment cards that can be accepted in the transaction.

City – Optional. Specifies the city of the billing or shipping address.

ColumnNumber – Optional. Specifies the number of columns the payment acceptance page will use when displaying input fields.

Country – Optional. Specifies the country of the billing or shipping address.

CurrencyCode – Optional. Specifies the currency that will be used in the transaction. The format of the currency code is specific to the payment service provider being used.

DisabledTextBackgroundColor - Optional. Specifies the background color of the disabled text on the payment acceptance page.

FontFamily – Optional. Specifies the font family of the text on the payment acceptance page.

FontSize – Optional. Specifies the size of the text on the payment acceptance page.

IndustryType – Optional. Specifies the type of industry for the transaction.

LabelColor – Optional. Specifies the color of the label text on the payment acceptance page.

Locale – Optional. Specifies the region/locale/language of the payment acceptance page.

PageBackgroundColor – Optional. Specifies the background color of the payment acceptance page.

PageWidth – Optional. Specifies the width of the payment acceptance page.

PostalCode – Optional. Specifies the postal code of the billing or shipping address.

PurchaseLevel – Optional. Specifies the purchase level of the transaction being performed.

ShowSameAsShippingAddress – Optional. Specifies whether or not to display a check box that indicates the billing and shipping addresses are the same.

State – Optional. Specifies the state of the billing or shipping address.

StreetAddress – Optional. Specifies the street address of the billing or shipping address.

SupportCardSwipe – Optional. Specifies whether a card swipe is supported to complete the transaction.

SupportCardTokenization – Optional. Specifies whether the card information input during the transaction will be tokenized.

TextBackgroundColor – Optional. Specifies the background of the text on the payment acceptance page.

TextColor – Optional. Specifies the color of the text on the payment acceptance page.

TransactionType – Optional. Specifies the type of transaction being performed.

Output:

Url The URL of the payment acceptance page that will perform a transaction with the provided options.

SystemMessages - Collection of messages from the external system.

Usage example:

RequestResponse
var request = new GetPaymentServiceUrlRequest()
{
    AllowPartialAuthorization = false,
    AllowVoiceAuthorization = false,
    CardType = CardType.AllCardTypes,
    ColumnNumber = 1,
    CurrencyCode = "USD",
    DisabledTextBackgroundColor = "#E4E4E4",
    FontFamily = "\"Helvetica Neue\", Helvetica, Arial, sans-serif",
    FontSize = "14px",
    IndustryType = "Ecommerce",
    LabelColor = "black",
    Locale = Context.Culture.Name,
    PageBackgroundColor = "white",
    PageWidth = "429px",
    PurchaseLevel = PurchaseLevel.Level1,
    ShowSameAsShippingAddress = false,
    SupportCardSwipe = false,
    SupportCardTokenization = true,
    TextBackgroundColor = "white",
    TextColor = "black",
    TransactionType = TransactionType.Authorize,
};
if (HttpContext.Current != null && HttpContext.Current.Request != null)
{
    request.HostPageOrigin = string.Format(
        System.Globalization.CultureInfo.InvariantCulture,
        "{0}://{1}",
        HttpContext.Current.Request.Url.Scheme,
        HttpContext.Current.Request.Url.Authority);
}
var provider = (PaymentServiceProvider)Factory.CreateObject("paymentServiceProvider", true);
var result = provider.GetPaymentServiceUrl(request);

GetPaymentServiceActionResult method

The GetPaymentServiceActionResult method is used to retrieve the result of a transaction or action against a payment service.

Name:

GetPaymentServiceActionResult

Description:

Retrieves the result of a federated payment service transaction/action.

Usage:

Called when a website is ready to retrieve the result of a transaction.

Examples include:

  • Retrieving the result of a customer’s transaction with a federated payment service.

Signature:

GetPaymentServiceActionResultResult GetPaymentServiceActionResult([NotNull] GetPaymentServiceActionResultRequest request)

Input:

Locale Required.Specifies the locale of the merchant website.

PaymentAcceptResultAccessCode – Required. Specifies the result access code from the federated payment service. This code is typically sent to the merchant website through a cross page JavaScript event.

Output:

CardToken A card token that represents the payment information that the customer provided to the payment service.

AuthorizationResult – A value that identifies the result of the transaction with the payment service. The format of this string is specific to the payment service being used.

SystemMessages - Collection of messages from the external system.

Usage example:

RequestResponse
var request = new GetPaymentServiceActionResultRequest()
{
    Locale = Context.Culture.Name,
    PaymentAcceptResultAccessCode = "accessCode"
};
var provider = (PaymentServiceProvider) Factory.CreateObject("paymentServiceProvider", true);
var result = provider.GetPaymentServiceActionResult(request);

Do you have some feedback for us?

If you have suggestions for improving this article,