Editar

Compartilhar via

Create an end-to-end payment integration for a payment terminal

  • Artigo

This article describes how to create an end-to-end payment integration in Microsoft Dynamics 365 Commerce Store Commerce for a payment terminal that can directly communicate with the payment gateway.

Key terms

Term Description
Payment connector An extension library that is written to integrate the POS with a payment terminal.
Payment processor An extension library that is written to retrieve merchant properties that the payment connector uses.

Overview

The following illustration shows a high-level overview of the payment terminal integration through the POS. Although this illustration assumes that a local Hardware Station is used to communicate with the payment terminal, the same patterns apply to a shared Hardware Station.

Payment connector integration overview.

This article describes the following steps that are required to create an end-to-end payment integration for a payment terminal:

  • Write a payment connector: The payment connector is the main integration point between the POS and the payment terminal. The section for this step describes how to implement and configure a new payment connector that can relay payment requests (for example, authorize, refund, and void requests) to the payment terminal.
  • Write a payment processor: The payment processor is used to define the merchant properties that are used as part of the payment integration. The section for this step describes how to implement a new payment processor. It includes information about the interfaces that you should implement and patterns that you should follow.

Write a payment connector

This section describes how to write a new payment connector.

Understanding the payment flows

The following illustration shows a high-level overview of several payment flows (Begin Transaction, Update Cart Lines, Authorize, Capture, and End Transaction) across the POS, Hardware Station, and payment connector.

Payment flow overview.

Implement a payment connector

This section below describes how to implement a new payment connector. The examples that are shown here can be found in the PaymentDeviceSample class that is located under the SampleExtensions\HardwareStation\Extension.PaymentSample folder in the Retail software development kit (SDK).

Implement the INamedRequestHandler interface

All POS payment-related flows are handled through request/response patterns in the Hardware Station. The first step in the process of writing a new payment connector is to create a class that implements the INamedRequestHandler interface that is defined in the Microsoft.Dynamics.Commerce.Runtime.Framework library.

namespace Contoso.Commerce.HardwareStation.PaymentSample 
{ 
    public class PaymentDeviceSample : INamedRequestHandler
    {
        private const string PaymentTerminalDevice = "MOCKPAYMENTTERMINAL";

        /// <summary>
        /// Gets the specify the name of the request handler.
        /// </summary>
        public string HandlerName
        {
              get
            {
                return PaymentDeviceSample.PaymentTerminalDevice;
            }
        }
    }
}

The HandlerName string is used to configure the payment connector that is used on a given POS register through the client (see the information later in this article).

Implement supported payment requests

To process payment-related flows, the payment connector must define the supported request types that it can handle. Additionally, the Execute method must be implemented to route each request that the connector supports to a given method. The following example shows the complete list of supported request types and an example of a specific request (that is, an authorize request).

namespace Contoso.Commerce.HardwareStation.PaymentSample 
{ 
    /// <summary>
    /// <c>Simulator</c> manager payment device class.
    /// </summary>
    public class PaymentDeviceSample : INamedRequestHandler
    {
        /// <summary>
        /// Gets the collection of supported request types by this handler.
        /// </summary>
        public IEnumerable<Type> SupportedRequestTypes
        {
            get
            {
                return new[]
                {
                        typeof(LockPaymentTerminalDeviceRequest),
                        typeof(OpenPaymentTerminalDeviceRequest),
                        typeof(ClosePaymentTerminalDeviceRequest),
                        typeof(BeginTransactionPaymentTerminalDeviceRequest),
                        typeof(EndTransactionPaymentTerminalDeviceRequest),
                        typeof(UpdateLineItemsPaymentTerminalDeviceRequest),
                        typeof(AuthorizePaymentTerminalDeviceRequest),
                        typeof(CapturePaymentTerminalDeviceRequest),
                        typeof(VoidPaymentTerminalDeviceRequest),
                        typeof(RefundPaymentTerminalDeviceRequest),
                        typeof(FetchTokenPaymentTerminalDeviceRequest),
                        typeof(ExecuteTaskPaymentTerminalDeviceRequest),
                        typeof(ActivateGiftCardPaymentTerminalRequest),
                        typeof(AddBalanceToGiftCardPaymentTerminalRequest),
                        typeof(GetGiftCardBalancePaymentTerminalRequest),
                        typeof(GetPrivateTenderPaymentTerminalDeviceRequest),
                        typeof(CancelOperationPaymentTerminalDeviceRequest),
                        typeof(GetTransactionReferencePaymentTerminalDeviceRequest),
                        typeof(GetTransactionByTransactionReferencePaymentTerminalDeviceRequest),
                        typeof(CashoutGiftCardPaymentTerminalRequest)
                };
            }
        }


        /// <summary>
        /// Executes the payment device simulator operation based on the incoming request type.
        /// </summary>
        /// <param name="request">The payment terminal device simulator request message.</param>
        /// <returns>Returns the payment terminal device simulator response.</returns>
        public Response Execute(Microsoft.Dynamics.Commerce.Runtime.Messages.Request request)
        {
            ThrowIf.Null(request, "request");

            Type requestType = request.GetType();

            if (requestType == typeof(AuthorizePaymentTerminalDeviceRequest))
            {
                return this.AuthorizePayment((AuthorizePaymentTerminalDeviceRequest)request);
            }
            else if (...)
            {
                ...
            }

            return new NullResponse();
        }

        /// <summary>
        /// Authorize payment.
        /// </summary>
        /// <param name="request">The authorize payment request.</param>
        /// <returns>The authorize payment response.</returns>
        public AuthorizePaymentTerminalDeviceResponse AuthorizePayment(AuthorizePaymentTerminalDeviceRequest request)
        {
            ThrowIf.Null(request, "request");

            PaymentInfo paymentInfo = Utilities.WaitAsyncTask(() => this.AuthorizePaymentAsync(request.Amount, request.Currency, request.VoiceAuthorization, request.IsManualEntry, request.ExtensionTransactionProperties));

            return new AuthorizePaymentTerminalDeviceResponse(paymentInfo);
        }
    }
}

Full list of supported request types

The following table describes all supported requests types that a payment connector can implement.

Request class Payment flow description
OpenPaymentTerminalDeviceRequest This request is called before a sales transaction is initiated. It is used to establish a connection to the payment terminal.
BeginTransactionPaymentTerminalDeviceRequest This request is called when a new sales transaction is initiated. It is used to handle any initialization on the payment terminal (for example, by initializing the transaction screen).
LockPaymentTerminalDeviceRequest This request is called when a payment terminal is locked for a transaction.
UpdateLineItemsPaymentTerminalDeviceRequest This request is called when line items in the cart are updated.
AuthorizePaymentTerminalDeviceRequest This request is called when a payment is initiated in the POS payment view.
CancelOperationPaymentTerminalDeviceRequest This request is called when a user selects the Cancel button in the payment view dialog box after the payment is initiated but before the payment is completed on the payment terminal.
CapturePaymentTerminalDeviceRequest This request is called for each payment line when the whole amount in the cart is paid but before the sales transaction is concluded.
VoidPaymentTerminalDeviceRequest This request is called when a payment line is voided in the cart.
RefundPaymentTerminalDeviceRequest This request is called when a refund is issued.
FetchTokenPaymentTerminalDeviceRequest This request is called to fetch a payment token to support deferred payments for customer orders.
EndTransactionPaymentTerminalDeviceRequest This request is called when the sales transaction is concluded and all payments have been captured.
ClosePaymentTerminalDeviceRequest This request is called after the sales transaction is concluded. It is used to close the connection to the payment terminal.
ActivateGiftCardPaymentTerminalRequest This request is called when an external gift card is being activated through the POS.
AddBalanceToGiftCardPaymentTerminalRequest This request is called when a balance is being added to an external gift card.
GetGiftCardBalancePaymentTerminalRequest This request is called when the balance on the gift card is being retrieved.
GetPrivateTenderPaymentTerminalDeviceRequest This request is called when gift card numbers are retrieved from the payment terminal for gift card flows (for example, Issue gift card, Pay by gift card, or Add to gift card).
ExecuteTaskPaymentTerminalDeviceRequest This extension request can be invoked from the POS through customizations. It is used to enable additional payment-related flows.
GetTransactionReferencePaymentTerminalDeviceRequest This request is called to check the correlation ID. It is used for duplicate payment protection.
GetTransactionByTransactionReferencePaymentTerminalDeviceRequest This request is used to obtain the previous transaction by correlation ID.
CashoutGiftCardPaymentTerminalRequest This request is called when a the cash out gift card operation is executed from the POS.
OpenPaymentTerminalDeviceRequest
Signature
public OpenPaymentTerminalDeviceRequest(string token, string deviceName, SettingsInfo terminalSettings, PeripheralConfiguration deviceConfig, ExtensionTransaction extensionTransactionProperties);
Variables
Variable Description
token The unique token value that is generated when the payment terminal is initially locked for the transaction.
deviceName The name of the device, as defined on the POS hardware profile page in the client.
terminalSettings The set of payment terminal–specific configuration properties that are defined in the client, such as the minimum amount for signature capture and the debit cash-back limit.
deviceConfig The set of payment terminal–specific configuration properties in the form of name/value pairs, such as the IP address and port in the case of network devices.
extensionTransactionProperties The set of extension configuration properties in the form of name/value pairs.
BeginTransactionPaymentTerminalDeviceRequest
Signature
public BeginTransactionPaymentTerminalDeviceRequest(string token, string paymentConnectorName, string merchantInformation, string invoiceNumber, bool isTestMode, ExtensionTransaction extensionTransactionProperties)
Variables
Variable Description
token The unique token value that is generated when the payment terminal is initially locked for the transaction.
paymentConnectorName The name of the payment connector that is used as part of the payment flow. This variable is used if you plan to integrate with payment flows that use the IPaymentProcessor interface.
merchantInformation The merchant information that is defined on the POS hardware profile page in the client.
invoiceNumber The unique invoice number that the POS generates to track the sales transaction.
isTestMode A value that indicates whether the payment connector is being used in testing mode.
extensionTransactionProperties The set of extension configuration properties in the form of name/value pairs.
LockPaymentTerminalDeviceRequest
Signature
public LockPaymentTerminalDeviceRequest(string clientDeviceNumber, string deviceType, string deviceName, bool isExclusive, bool isOverride)
Variables
Variable Description
clientDeviceNumber The unique POS device number that is acquiring the lock.
deviceType The device type that the lock is acquired for as configured in the POS hardware profile (such as "Windows").
deviceName The device type that the lock is acquired for as configured in the POS hardware profile (such as "MOCKPAYMENTTERMINAL").
isExclusive Determines whether the lock that is acquired is exclusive.
isOverride Determines whether this request will override any existing lock.
UpdateLineItemsPaymentTerminalDeviceRequest
Signature
public UpdateLineItemsPaymentTerminalDeviceRequest(string token, string totalAmount, string taxAmount, string discountAmount, string subTotalAmount, IEnumerable<ItemInfo> items, ExtensionTransaction extensionTransactionProperties = null)
Variables
Variable Description
token The unique token value that is generated when the payment terminal is initially locked for the transaction.
totalAmount The total amount on the current sales transaction.
taxAmount The tax amount on the current sales transaction.
discountAmount The discount amount on the current sales transaction.
subTotalAmount The subtotal amount on the current sales transaction.
items The list of line items to show.
extensionTransactionProperties The set of extension configuration properties in the form of name/value pairs.
AuthorizePaymentTerminalDeviceRequest
Signature
public AuthorizePaymentTerminalDeviceRequest(string token, string paymentConnectorName, decimal amount, string currency, TenderInfo tenderInfo, string voiceAuthorization, bool isManualEntry, Retail.PaymentSDK.Portable.PaymentTransactionReferenceData transactionReferencedata, bool isTippingEnabled, ExtensionTransaction extensionTransactionProperties)
Variables
Variable Description
token The unique token value that is generated when the payment terminal is initially locked for the transaction.
paymentConnectorName The name of the payment connector that is used as part of the payment flow. This variable is used if there is an integration with payment flows that use the IPaymentProcessor interface.
amount The amount to authorize.
currency The currency for the amount to authorize.
tenderInfo The card information that is sent from the POS that is retrieved from an external source (if an external source is present).
voiceAuthorization The voice approval code that is sent from the POS if voice authorization is required.
isManualEntry A value that defines whether the card number was entered manually.
transactionReferenceData Merchant's transaction reference that is sent to the processor.
isTippingEnabled Indicates if tipping is supported by the payment connector. Optional. The default value is false.
extensionTransactionProperties The set of extension configuration properties in the form of name/value pairs. Optional. The default value is null.
Response

The AuthorizePaymentCardPaymentResponse response object must be returned when the AuthorizePaymentTerminalDeviceRequest request is handled. The response must contain an instance of the PaymentInfo object that has the following required properties.

Property Description
ApprovedAmount The amount that was approved for the transaction. Includes tip amount if tipping is enabled.
CardNumberMasked The masked credit card number. The value must contain at least the first digit of the credit card to support bin range lookup in the POS. (Most devices return the first six digits and the last four digits.)
CardType The type of card that was used for the payment (for example, Credit or Debit) by using the Microsoft.Dynamics.Commerce.HardwareStation.CardPayment.CardType entity.
CashbackAmount For debit transactions, the cash-back amount that was defined on the payment terminal.
Errors The list of errors that occurred during the authorize call.
IsApproved A flag that indicates whether the payment was approved.
PaymentSdkData The response data that is used to support state between the authorize/refund and capture/void calls or cross-channel payment operations.
TipAmount The tip amount that was selected by the customer on the device.

The PaymentSdkData property must contain the following data.

Namespace Name Description Sample value
Connector ConnectorName The name of the IPaymentProcessor interface that is used for the transactions, as described in the "Write a payment processor" section later in this article.
AuthorizationResponse Properties The list of authorization responses. See the next table.

The Properties field of the PaymentSdkData property must contain the following fields.

Namespace Name Description Sample value
AuthorizationResponse ApprovedAmount The amount that was approved for the transaction. 28.08m
AuthorizationResponse AvailableBalance The available balance on the card. 100.00m
AuthorizationResponse ApprovalCode The approval code for the transaction. Z123456
AuthorizationResponse ProviderTransactionId The transaction identifier of the payment provider. 123456789
AuthorizationResponse AuthorizationResult The result of the authorization call. AuthorizationResult.Success.ToString()
AuthorizationResponse ExternalReceipt The external receipt data from the payment provider. <ReceiptData>...</ReceiptData>
AuthorizationResponse TerminalId The unique identifier of the terminal that handled the payment. 000001

The following example shows how to construct the PaymentSdkData object.

List<PaymentProperty> paymentSdkProperties = new List<PaymentProperty>();
paymentSdkProperties.Add(new PaymentProperty(GenericNamespace.Connector, ConnectorProperties.ConnectorName, "TestConnector"));

List<PaymentProperty> paymentSdkAuthorizationProperties = new List<PaymentProperty>();
paymentSdkAuthorizationProperties.Add(new PaymentProperty(GenericNamespace.AuthorizationResponse, AuthorizationResponseProperties.ApprovedAmount, 28.08m));
paymentSdkAuthorizationProperties.Add(new PaymentProperty(GenericNamespace.AuthorizationResponse, AuthorizationResponseProperties.AvailableBalance, 100.00m));
paymentSdkAuthorizationProperties.Add(new PaymentProperty(GenericNamespace.AuthorizationResponse, AuthorizationResponseProperties.ApprovalCode, "Z123456"));
paymentSdkAuthorizationProperties.Add(new PaymentProperty(GenericNamespace.AuthorizationResponse, AuthorizationResponseProperties.ProviderTransactionId, "123456789"));
paymentSdkAuthorizationProperties.Add(new PaymentProperty(GenericNamespace.AuthorizationResponse, AuthorizationResponseProperties.AuthorizationResult, AuthorizationResult.Success.ToString()));
paymentSdkAuthorizationProperties.Add(new PaymentProperty(GenericNamespace.AuthorizationResponse, TransactionDataProperties.TerminalId, "000001"));

paymentSdkProperties.Add(new PaymentProperty(GenericNamespace.AuthorizationResponse, AuthorizationResponseProperties.Properties, paymentSdkAuthorizationProperties.ToArray()));

string paymentSdkData = PaymentProperty.ConvertPropertyArrayToXML(paymentSdkProperties.ToArray());

If the payment terminal returns a receipt, you can print it through the POS by setting the following data on the ExternalReceipt object that was described earlier.

<ReceiptData>
    <Receipt Type='Customer'>
        <Line>Line 1 of receipt.</Line>
        <Line>Line 2 of receipt.</Line>
    </Receipt>
    <Receipt Type='Merchant'>
        <Line>Line 1 of receipt.</Line>
        <Line>Line 2 of receipt.</Line>
    </Receipt>
</ReceiptData>
Other considerations

If the payment terminal handles the authorize and capture requests in a single call (that is, if immediate capture occurs), and the cashier wants to void the transaction, the payment terminal must support reversal of an immediate capture. When an immediate capture is voided, if the void request fails, the cashier will be asked whether they want to locally void the payment. If the cashier selects Yes, the tender is voided only in the POS. No call is made to the payment terminal to void the payment. Basically, this behavior lets the cashier unblock the POS if it can no longer void the payment on the payment terminal. However, this behavior can cause issues, because a lock lasts for three to five days, until the bank reverses it, but the payment is made for immediate capture. Therefore, duplicate payments can occur.

CancelOperationPaymentTerminalDeviceRequest
Signature
public CancelOperationPaymentTerminalDeviceRequest(string token)
Variables
Variable Description
token The unique token value that is generated when the payment terminal is initially locked for the transaction.
CapturePaymentTerminalDeviceRequest
Signature
public CapturePaymentTerminalDeviceRequest(string token, decimal amount, string currency, string paymentPropertiesXml, ExtensionTransaction extensionTransactionProperties)
Variables
Variable Description
token The unique token value that is generated when the payment terminal is initially locked for the transaction.
amount The amount to capture.
currency The currency for the amount to capture.
paymentPropertiesXml The content of the PaymentSdkData object that is returned by the AuthorizePaymentTerminalDeviceRequest or RefundPaymentTerminalDeviceRequest request, and that is used to support stateful properties between the requests.
extensionTransactionProperties The set of extension configuration properties in the form of name/value pairs.
Other considerations

If the payment terminal handles the authorize and capture requests in a single call, the CapturePaymentTerminalDeviceRequest request should be a no-op and should immediately return.

If the payment terminal requires state from the authorize requests to handle the capture call, the properties should be stored in the PaymentSdkData object of the AuthorizePaymentTerminalDeviceResponse request that is described earlier, and passed through the paymentPropertiesXml variable of the CapturePaymentTerminalDeviceRequest request.

VoidPaymentTerminalDeviceRequest
Signature
public VoidPaymentTerminalDeviceRequest(string token, string paymentConnectorName, decimal amount, string currency, TenderInfo tenderInfo, string paymentPropertiesXml, ExtensionTransaction extensionTransactionProperties)
Variables
Variable Description
token The unique token value that is generated when the payment terminal is initially locked for the transaction.
paymentConnectorName The name of the payment connector that is used as part of the payment flow. This variable is used if there is an integration with payment flows that use the IPaymentProcessor interface.
amount The amount for the payment to void.
currency The currency for the payment to void.
tenderInfo The card information that is sent from the POS that is retrieved from an external source (if an external source is present).
paymentPropertiesXml The content of the PaymentSdkData object that is returned by the AuthorizePaymentTerminalDeviceRequest or RefundPaymentTerminalDeviceRequest request, and that is used to support stateful properties between the requests.
extensionTransactionProperties The set of extension configuration properties in the form of name/value pairs.
RefundPaymentTerminalDeviceRequest
Signature
public RefundPaymentTerminalDeviceRequest(string token, string paymentConnectorName, TenderInfo tenderInfo, decimal amount, string currency, bool isManualEntry, ExtensionTransaction extensionTransactionProperties)
Variables
Variable Description
token The unique token value that is generated when the payment terminal is initially locked for the transaction.
paymentConnectorName The name of the payment connector that is used as part of the payment flow. This variable is used if there is an integration with payment flows that use the IPaymentProcessor interface.
tenderInfo The card information that is sent from the POS that is retrieved from an external source (if an external source is present).
amount The amount to refund.
currency The currency for the amount to refund.
isManualEntry A value that defines whether the card number was entered manually.
extensionTransactionProperties The set of extension configuration properties in the form of name/value pairs.
FetchTokenPaymentTerminalDeviceRequest
Signature
public FetchTokenPaymentTerminalDeviceRequest(string token, bool isManualEntry, ExtensionTransaction extensionTransactionProperties)
Variables
Variable Description
token The unique token value that is generated when the payment terminal is initially locked for the transaction.
isManualEntry A value that defines whether the card number was entered manually.
extensionTransactionProperties The set of extension configuration properties in the form of name/value pairs.
EndTransactionPaymentTerminalDeviceRequest
Signature
public EndTransactionPaymentTerminalDeviceRequest(string token, ExtensionTransaction extensionTransactionProperties)
Variables
Variable Description
token The unique token value that is generated when the payment terminal is initially locked for the transaction.
extensionTransactionProperties The set of extension configuration properties in the form of name/value pairs.
ClosePaymentTerminalDeviceRequest
Signature
public ClosePaymentTerminalDeviceRequest(string token, ExtensionTransaction extensionTransactionProperties)
Variables
Variable Description
token The unique token value that is generated when the payment terminal is initially locked for the transaction.
extensionTransactionProperties The set of extension configuration properties in the form of name/value pairs.
ActivateGiftCardPaymentTerminalRequest
Signature
public ActivateGiftCardPaymentTerminalRequest(string token, string paymentConnectorName, decimal amount, string currencyCode, TenderInfo tenderInfo, ExtensionTransaction extensionTransactionProperties)
Variables
Variable Description
token The unique token value that is generated when the payment terminal is initially locked for the transaction.
paymentConnectorName The name of the payment connector that is used as part of the payment flow. This variable is used if there is an integration with payment flows that use the IPaymentProcessor interface.
amount The initial amount to add to the gift card during activation.
currency The currency for the initial amount to add to the gift card during activation.
tenderInfo The card information that is sent from the POS that is retrieved from an external source (if an external source is present).
extensionTransactionProperties The set of extension configuration properties in the form of name/value pairs.
AddBalanceToGiftCardPaymentTerminalRequest
Signature
public AddBalanceToGiftCardPaymentTerminalRequest(string token, string paymentConnectorName, decimal amount, string currencyCode, TenderInfo tenderInfo, ExtensionTransaction extensionTransactionProperties)
Variables
Variable Description
token The unique token value that is generated when the payment terminal is initially locked for the transaction.
paymentConnectorName The name of the payment connector that is used as part of the payment flow. This variable is used if there is an integration with payment flows that use the IPaymentProcessor interface.
amount The amount to add to the gift card.
currency The currency for the amount to add to the gift card balance.
tenderInfo The card information that is sent from the POS that is retrieved from an external source (if an external source present).
extensionTransactionProperties The set of extension configuration properties in the form of name/value pairs.
GetGiftCardBalancePaymentTerminalRequest
Signature
public GetGiftCardBalancePaymentTerminalRequest(string token, string paymentConnectorName, string currencyCode, TenderInfo tenderInfo, ExtensionTransaction extensionTransactionProperties)
Variables
Variable Description
token The unique token value that is generated when the payment terminal is initially locked for the transaction.
paymentConnectorName The name of the payment connector that is used as part of the payment flow. This variable is used if there is an integration with payment flows that use the IPaymentProcessor interface.
currency The currency to retrieve the gift card balance in.
tenderInfo The card information that is sent from the POS that is retrieved from an external source (if an external source present).
extensionTransactionProperties The set of extension configuration properties in the form of name/value pairs.
GetPrivateTenderPaymentTerminalDeviceRequest
Signature
public GetPrivateTenderPaymentTerminalDeviceRequest(string token, decimal amount, bool declined, bool isSwipe, ExtensionTransaction extensionTransactionProperties)
Variables
Variable Description
token The unique token value that is generated when the payment terminal is initially locked for the transaction.
amount The amount that is set on the POS. (Typically, this variable is used to show the amount on the payment terminal when the card number is retrieved.)
declined This variable is obsolete.
isSwipe A value that determines whether the card number should be retrieved through a swipe or manual entry on the payment terminal.
extensionTransactionProperties The set of extension configuration properties in the form of name/value pairs.
ExecuteTaskPaymentTerminalDeviceRequest
Signature
public ExecuteTaskPaymentTerminalDeviceRequest(string token, string task, ExtensionTransaction extensionTransactionProperties)
Variables
Variable Description
token The unique token value that is generated when the payment terminal is initially locked for the transaction.
task The unique identifier for the task that is being run.
extensionTransactionProperties The set of extension configuration properties in the form of name/value pairs.
GetTransactionReferencePaymentTerminalDeviceRequest
Signature
 public GetTransactionReferencePaymentTerminalDeviceRequest(string lockToken, string posTerminalId, string eftTerminalId)
Variables
Variable Description
locktoken Gets the unique lock token that was generated when the payment terminal was initially locked for the transaction.
posTerminalId Gets the POS terminal ID associated with the lock token.
extensionTransactionProperties Gets the EFT terminal ID associated witht the transaction and lock token.
GetTransactionByTransactionReferencePaymentTerminalDeviceRequest
Signature
 public GetTransactionByTransactionReferencePaymentTerminalDeviceRequest(string lockToken, Retail.PaymentSDK.Portable.PaymentTransactionReferenceData transactionReferenceData)
Variables
Variable Description
locktoken Gets the unique lock token that was generated when the payment terminal was initially locked for the transaction.
Retail.PaymentSDK.Portable.PaymentTransactionReferenceData TransactionReferenceData Gets reference data for the for payment transactions in case the correlation ID is out of sync.
CashoutGiftCardPaymentTerminalRequest
Signature
 public CashoutGiftCardPaymentTerminalRequest(
            string paymentConnectorName,
            decimal amount,
            string currencyCode,
            TenderInfo tenderInfo,
            ExtensionTransaction extensionTransactionProperties)
Variables
Variable Description
paymentConnectorName The name of the payment connector that is used as part of the payment flow. This variable is used if there is an integration with payment flows that use the IPaymentProcessor interface.
amount The amount gift card cash out request.
currencyCode The currency for the gift card cash out request.
tenderinfo The card information that is sent from the POS that is retrieved from an external source (if an external source is present).
extensionTransactionProperties The set of extension configuration properties in the form of name/value pairs.

State in the payment connector

The payment connector can be hosted as part of the dllhost.exe process when it's hosted through the in-process Hardware Station inside the POS. Alternatively, the payment connector can be hosted as a w3wp.exe process when it's hosted in the Hardware Station that is based on Microsoft Internet Information Services (IIS). In some circumstances, both processes can be terminated or stop responding between or during payment flows. Therefore, we recommend that payment connectors not have state dependencies, and that they be able to recover if they are terminated at any point during the payment flow–related requests that are described earlier.

Configure the payment connector in the Hardware Station config

To help guarantee that the Hardware Station loads the payment connector, you must set the corresponding assembly reference in the HardwareStation.Extension.config file that is located in the Assets folder in the Retail SDK.

<?xml version="1.0" encoding="utf-8"?>
<hardwareStationExtension>
    <composition>
        <!-- 
        Register your own assemblies or types here. The following example registers NewPeripheralDevice 
        (and all its request handlers). Any other services are not being overridden:

        <add source="type" 
            value="Contoso.Commerce.HardwareStation.NewPeripheralDevice, Contoso.Commerce.HardwareStation.NewPeripheralDevice" />
        <add source="assembly" 
            value="Contoso.Commerce.HardwareStation.NewPeripheralDevice” />
        -->
        <add source="assembly" value="Contoso.Commerce.HardwareStation.PaymentSample" />
    </composition>
</hardwareStationExtension>

Configure the payment connector on the POS hardware profile page in the client

To determine the correct payment connector that should be loaded on the POS, you must set the value of the PaymentTerminalDevice property in the Device name field on the PIN pad FastTab of the POS hardware profile page in the client, as shown in the following illustration.

Configure payment connector on the POS hardware profile page in the client.

Write a payment processor

Payment processes are usually used only if a direct connection to a payment gateway is established. This scenario most often occurs in card-not-present sales transactions or more complex card-present scenarios. Additionally, the payment processor is used to process the merchant properties that are configured through the POS hardware profile page in the client.

Note

The payment processor is currently required, even if all payment requests are handled directly through the payment terminal and no merchant properties must be set through the POS. For more information about implementing the IPaymentProcessor interface, read the Implementing a payment connector and payment device white paper.

Understanding the merchant properties flows

The following sections describe how the merchant properties are set on the POS hardware profile page in the client, and how they are passed to the payment connector during payment flows on the POS.

Set merchant properties on the POS hardware profile page in the client

The following illustration shows how the merchant properties are set through the POS hardware profile page in the client. To enable the merchant properties to be set, the IPaymentProcessor interface that is defined in the Microsoft.Dynamics.Retail.PaymentSDK library must be implemented. Two interface methods are required: GetMerchantAccountPropertyMetadata and ValidateMerchantAccount.

Setting merchant properties on the POS hardware profile page in the client.

Set merchant properties on payment connector during POS sales transaction

The following illustration shows how the merchant properties are retrieved from the database through the Commerce Scale Unit and passed to the payment connector during the BeginTransactionPaymentTerminalDeviceRequest request.

Setting merchant properties on the payment connector during POS payment flows.

Implement the IPaymentProcessor interface

To handle merchant properties that are related to payment flows, the IPaymentProcessor interface that is defined in the Microsoft.Dynamics.Retail.PaymentSDK library must be implemented. The following example shows how to implement the two required interface methods, GetMerchantAccountPropertyMetadata and ValidateMerchantAccount. Other interface methods can be left blank (for example, they can return FeatureNotSupportedException).

/// <summary>
/// SampleConnector class (Portable Class Library version).
/// </summary>
public class SampleConnector : IPaymentProcessor
{
    /// <summary>
    /// GetMerchantAccountPropertyMetadata returns the merchant account properties need by the payment provider.
    /// </summary>
    /// <param name="request">Request object.</param>
    /// <returns>
    /// Response object.
    /// </returns>
    public Response GetMerchantAccountPropertyMetadata(Request request)
    {
        string methodName = "GetMerchantAccountPropertyMetadata";

        // Check null request
        List<PaymentError> errors = new List<PaymentError>();
        if (request == null)
        {
            errors.Add(new PaymentError(ErrorCode.InvalidRequest, "Request is null."));
            return PaymentUtilities.CreateAndLogResponseForReturn(methodName, this.Name, Platform, locale: null, properties: null, errors: errors);
        }

        // Prepare response
        List<PaymentProperty> properties = new List<PaymentProperty>();
        PaymentProperty property;
        property = new PaymentProperty(
            GenericNamespace.MerchantAccount,
            MerchantAccountProperties.AssemblyName,
            this.GetAssemblyName());
        property.SetMetadata("Assembly Name:", "The assembly name of the test provider", false, true, 0);
        properties.Add(property);

        Response response = new Response();
        response.Locale = request.Locale;
        response.Properties = properties.ToArray();
        if (errors.Count > 0)
        {
            response.Errors = errors.ToArray();
        }

        PaymentUtilities.LogResponseBeforeReturn(methodName, this.Name, Platform, response);
        return response;
    }

    /// <summary>
    /// ValidateMerchantAccount the passed merchant account properties with the payment provider.
    /// </summary>
    /// <param name="request">Request object to validate.</param>
    /// <returns>
    /// Response object.
    /// </returns>
    public Response ValidateMerchantAccount(Request request)
    {
        string methodName = "ValidateMerchantAccount";

        // Convert request
        ValidateMerchantAccountRequest validateRequest = null;
        try
        {
            validateRequest = ValidateMerchantAccountRequest.ConvertFrom(request);
        }
        catch (SampleException ex)
        {
            return PaymentUtilities.CreateAndLogResponseForReturn(methodName, this.Name, Platform, locale: request == null ? null : request.Locale, properties: null, errors: ex.Errors);
        }

        // Validate merchant account
        List<PaymentError> errors = new List<PaymentError>();
        ValidateMerchantProperties(validateRequest, errors);
        if (errors.Count > 0)
        {
            return PaymentUtilities.CreateAndLogResponseForReturn(methodName, this.Name, Platform, validateRequest.Locale, errors);
        }

        // Create response
        var validateResponse = new ValidateMerchantAccountResponse(validateRequest.Locale, validateRequest.ServiceAccountId, this.Name);

        // Convert response and return
        Response response = ValidateMerchantAccountResponse.ConvertTo(validateResponse);
        PaymentUtilities.LogResponseBeforeReturn(methodName, this.Name, Platform, response);
        return response;
    }
}

Required merchant property fields

The following table shows the required merchant property fields that must be set as part of the GetMerchantAccountPropertyMetadata method.

Namespace Name Sample value*
MerchantAccount PortableAssemblyName Contoso.Microsoft.PaymentsSample
MerchantAccount ServiceAccountId f35989c8-e571-4de1-862a-996c82a2e6b6
MerchantAccount SupportedCurrencies AUD;BRL;CAD;CHF;CNY;CZK;DKK;EUR;GBP;HKD;HUF;INR;JPY;KPW;KRW;MXN;NOK;NZD;PLN;SEK;SGD;TWD;USD;ZAR
MerchantAccount SupportedTenderTypes Visa;MasterCard;Amex;Discover;Debit

* You must replace the sample values in this column with unique values for your own payment processor.