Payments service provider
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 |
Usage: |
Called when a list of payment options is needed. Examples include:
|
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:
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 |
Usage: |
Called when a list of payment methods is needed. Examples include:
|
Signature: |
GetPaymentMethodsResult GetPaymentMethods([NotNull]GetPaymentMethodsRequest request) |
Input: | |
PaymentOption–The 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:
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 |
Usage: |
Called when a list of payment costs is needed. |
Signature: |
GetPricesForPaymentsResult GetPricesForPayments(GetPricesForPaymentsRequest request) |
Input: | |
ShopName - Mandatory – The 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:
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:
|
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:
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:
|
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:
var request = new GetPaymentServiceActionResultRequest()
{
Locale = Context.Culture.Name,
PaymentAcceptResultAccessCode = "accessCode"
};
var provider = (PaymentServiceProvider) Factory.CreateObject("paymentServiceProvider", true);
var result = provider.GetPaymentServiceActionResult(request);