支払ターミナルのエンドツーエンド支払統合の作成

この記事では、支払いゲートウェイと直接通信できる支払いターミナル用に、Microsoft Dynamics 365 Commerce Store Commerce でエンドツーエンドの支払い統合を作成する方法について説明します。

重要な用語

次の図は、POS を介した支払ターミナルの統合の概要を示しています。 この図では、ローカルのハードウェア ステーションを使用して支払端末と通信を使用することを前提にしていますが、同じパターンを共有のハードウェア ステーションにも適用できます。

この記事では、支払端末のエンド・ツー・エンド支払統合を作成するために必要な以下の手順について説明します。

• 支払コネクタの記述: 支払コネクタは POS と支払ターミナルの間の主要な統合ポイントです。 このステップのセクションでは、支払要求 (たとえば、承認、払い戻し、無効化要求) を支払端末に中継できる、新しい支払コネクタを実装し、設定する方法について説明します。
• 支払いプロセッサを記述します。 支払いプロセッサを使用して、支払い統合の一部であるマーチャント プロパティを定義します。 このステップのセクションでは、新しい支払プロセッサを実装する方法について説明します。 これには、実装する必要があるインターフェイスおよび従う必要があるパターンに関する情報が含まれています。

支払コネクタの記述

次のこのセクションでは、新しい支払コネクタを記述する方法について説明します。

支払いフローを理解する

次の図は、POS、ハードウェア ステーション、および支払コネクタ全体にわたるいくつかの支払フロー (トランザクションの開始、カート ラインの更新、承認、キャプチャ、および終了トランザクション) の概要を示しています。

支払コネクタの実装

次のセクションでは、新しい支払いコネクタを実装する方法について説明します。 ここに示す例は、Retail ソフトウェア開発キット (SDK) の SampleExtensions\HardwareStation\Extension.PaymentSample フォルダーにある PaymentDeviceSample クラスにあります。

INamedRequestHandler インターフェイスの実装

ハードウェア ステーションは、要求/応答パターンを通じて、すべての POS 支払関連フローを処理します。 新しい支払いコネクタを作成する最初の手順は、Microsoft.Dynamics.Commerce.Runtime.Framework ライブラリで定義されている INamedRequestHandler インターフェイスを実装するクラスを作成することです。

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;
            }
        }
    }
}

HandlerName 文字列を使用して、特定の POS レジスタがクライアントを介して使用する支払コネクタを構成します (この記事の後半の情報を参照)。

サポートされている支払要求の実装

支払関連フローを処理するには、支払コネクタが処理できる、サポートされている要求タイプを定義する必要があります。 さらに、 Execute メソッドを実装して、コネクタがサポートする各要求を特定のメソッドにルーティングします。 次の例は、サポートされている要求のタイプの完全な一覧と、特定の要求 (すなわち、承認要求) の例を示しています。

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);
        }
    }
}

サポートされる要求タイプの完全な一覧

次の表では、支払いコネクタが実装できるサポートされているすべての要求の種類について説明します。

OpenPaymentTerminalDeviceRequest

署名

public OpenPaymentTerminalDeviceRequest(string token, string deviceName, SettingsInfo terminalSettings, PeripheralConfiguration deviceConfig, ExtensionTransaction extensionTransactionProperties);

変数

BeginTransactionPaymentTerminalDeviceRequest

署名

public BeginTransactionPaymentTerminalDeviceRequest(string token, string paymentConnectorName, string merchantInformation, string invoiceNumber, bool isTestMode, ExtensionTransaction extensionTransactionProperties)

変数

LockPaymentTerminalDeviceRequest

署名

public LockPaymentTerminalDeviceRequest(string clientDeviceNumber, string deviceType, string deviceName, bool isExclusive, bool isOverride)

変数

UpdateLineItemsPaymentTerminalDeviceRequest

署名

public UpdateLineItemsPaymentTerminalDeviceRequest(string token, string totalAmount, string taxAmount, string discountAmount, string subTotalAmount, IEnumerable<ItemInfo> items, ExtensionTransaction extensionTransactionProperties = null)

変数

AuthorizePaymentTerminalDeviceRequest

署名

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)

変数

応答

AuthorizePaymentTerminalDeviceRequest 要求を処理するときに AuthorizePaymentCardPaymentResponse 応答オブジェクト を 返します。 応答には、次の必須プロパティを持つ PaymentInfo オブジェクトのインスタンスが含まれている必要があります。

PaymentSdkData プロパティには、次のデータを含める必要があります。

PaymentSdkData プロパティの プロパティ フィールドには、次のフィールドを含める必要があります。

次の例は、PaymentSdkData オブジェクトを作成する方法を示しています。

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());

支払端末がレシートを返す場合、先ほど説明した ExternalReceipt オブジェクトで次のデータを設定し、POS を介して印刷することができます。

<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>

その他の考慮事項

支払端末が 1 つの呼び出しでの要求を承認し、キャプチャし (つまり迅速なキャプチャが発生する場合)、出納係が取引を無効にすることを希望する場合、支払い端末では即時回収の取消がサポートされている必要があります。 即時キャプチャが無効になると、void 要求が失敗した場合、レジ担当者は支払いをローカルで無効にするかどうかを確認するメッセージが表示されます。 レジ担当者がはいと選択した場合、入札は POS でのみ無効になります。 支払を無効にするために支払ターミナルに対して行われる呼び出しはありません。 この動作により、支払いターミナルでの支払いを無効にできなくなった場合、レジ担当者は POS のブロックを解除できます。 ただし、銀行が取り消すまでロックが 3 日から 5 日間続くので、この動作によって問題が発生する可能性がありますが、支払いは即時キャプチャのために行われます。 したがって、重複した支払いが発生する可能性があります。

CancelOperationPaymentTerminalDeviceRequest

署名

public CancelOperationPaymentTerminalDeviceRequest(string token)

変数

CapturePaymentTerminalDeviceRequest

署名

public CapturePaymentTerminalDeviceRequest(string token, decimal amount, string currency, string paymentPropertiesXml, ExtensionTransaction extensionTransactionProperties)

変数

その他の考慮事項

支払端末が 1 つの呼び出しでの要求を承認およびキャプチャする場合、CapturePaymentTerminalDeviceRequest 要求はノーオーペレーションである必要があり、すぐに返す必要があります。

支払いターミナルでキャプチャ呼び出しを処理するために承認要求の状態が必要な場合は、前述の AuthorizePaymentTerminalDeviceResponse 要求の PaymentSdkData オブジェクトにプロパティを格納します。 CapturePaymentTerminalDeviceRequest 要求の paymentPropertiesXml 変数を使用して、これらのプロパティを渡します。

VoidPaymentTerminalDeviceRequest

署名

public VoidPaymentTerminalDeviceRequest(string token, string paymentConnectorName, decimal amount, string currency, TenderInfo tenderInfo, string paymentPropertiesXml, ExtensionTransaction extensionTransactionProperties)

変数

RefundPaymentTerminalDeviceRequest

署名

public RefundPaymentTerminalDeviceRequest(string token, string paymentConnectorName, TenderInfo tenderInfo, decimal amount, string currency, bool isManualEntry, ExtensionTransaction extensionTransactionProperties)

変数

FetchTokenPaymentTerminalDeviceRequest

署名

public FetchTokenPaymentTerminalDeviceRequest(string token, bool isManualEntry, ExtensionTransaction extensionTransactionProperties)

変数

EndTransactionPaymentTerminalDeviceRequest

署名

public EndTransactionPaymentTerminalDeviceRequest(string token, ExtensionTransaction extensionTransactionProperties)

変数

ClosePaymentTerminalDeviceRequest

署名

public ClosePaymentTerminalDeviceRequest(string token, ExtensionTransaction extensionTransactionProperties)

変数

ActivateGiftCardPaymentTerminalRequest

署名

public ActivateGiftCardPaymentTerminalRequest(string token, string paymentConnectorName, decimal amount, string currencyCode, TenderInfo tenderInfo, ExtensionTransaction extensionTransactionProperties)

変数

AddBalanceToGiftCardPaymentTerminalRequest

署名

public AddBalanceToGiftCardPaymentTerminalRequest(string token, string paymentConnectorName, decimal amount, string currencyCode, TenderInfo tenderInfo, ExtensionTransaction extensionTransactionProperties)

変数

GetGiftCardBalancePaymentTerminalRequest

署名

public GetGiftCardBalancePaymentTerminalRequest(string token, string paymentConnectorName, string currencyCode, TenderInfo tenderInfo, ExtensionTransaction extensionTransactionProperties)

変数

GetPrivateTenderPaymentTerminalDeviceRequest

署名

public GetPrivateTenderPaymentTerminalDeviceRequest(string token, decimal amount, bool declined, bool isSwipe, ExtensionTransaction extensionTransactionProperties)

変数

ExecuteTaskPaymentTerminalDeviceRequest

署名

public ExecuteTaskPaymentTerminalDeviceRequest(string token, string task, ExtensionTransaction extensionTransactionProperties)

変数

GetTransactionReferencePaymentTerminalDeviceRequest

署名

 public GetTransactionReferencePaymentTerminalDeviceRequest(string lockToken, string posTerminalId, string eftTerminalId)

変数

GetTransactionByTransactionReferencePaymentTerminalDeviceRequest

署名

 public GetTransactionByTransactionReferencePaymentTerminalDeviceRequest(string lockToken, Retail.PaymentSDK.Portable.PaymentTransactionReferenceData transactionReferenceData)

変数

CashoutGiftCardPaymentTerminalRequest

署名

 public CashoutGiftCardPaymentTerminalRequest(
            string paymentConnectorName,
            decimal amount,
            string currencyCode,
            TenderInfo tenderInfo,
            ExtensionTransaction extensionTransactionProperties)

変数

支払コネクタの状態

POS 内のインプロセス ハードウェア ステーションを介して支払コネクタをホストする場合は、dllhost.exe プロセスの一部として支払コネクタをホストできます。 または、Microsoft インターネット インフォメーション サービス (IIS) に基づくハードウェア ステーションで支払コネクタをホストするときに、w3wp.exe プロセスとして支払いコネクタをホストすることもできます。 状況によっては、両方のプロセスが、支払フローの間またはフロー中に終了または応答を停止することがあります。 そのため、状態の依存関係を持つ支払いコネクタを設計しないでください。 前に説明した支払フロー関連の要求の間に任意の時点で終了した場合に復旧するように設計します。

ハードウェア ステーションのコンフィギュレーションで支払コネクタをコンフィギュレーションする

ハードウェア ステーションが支払コネクタを確実に読み込むには、 HardwareStation.Extension.config ファイルに対応するアセンブリ参照を設定します。 このファイルは、Retail SDK の Assets フォルダーにあります。

<?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>

クライアントの POS ハードウェア プロファイル ページで支払コネクタをコンフィギュレーションする

POS が読み込む正しい支払コネクタを確認するには、次の図に示すように、クライアントの POS ハードウェア プロファイル ページの PIN パッド クイック タブの [デバイス名] フィールドで PaymentTerminalDevice プロパティの値を設定します。

支払プロセッサの記述

通常、支払いプロセッサは、支払いゲートウェイへの直接接続を確立する場合にのみ使用します。 このシナリオは、カードが存在しない販売取引またはより複雑なカードが存在するシナリオで最も頻繁に発生します。 さらに、支払プロセッサは、クライアントの POS ハードウェア プロファイル ページを使用して構成するマーチャント プロパティを処理します。

商社プロパティ フローを理解する

以降のセクションでは、クライアントの POS ハードウェア プロファイル ページでマーチャント プロパティを設定する方法と、POS が支払フロー中に支払コネクタにプロパティを渡す方法について説明します。

クライアントの POS ハードウェア プロファイル ページで商社プロパティを設定

次の図は、クライアントの POS ハードウェア プロファイル ページを使用してマーチャント プロパティを設定する方法を示しています。 マーチャント プロパティを設定できるようにするには、Microsoft.Dynamics.Retail.PaymentSDK ライブラリで定義されている IPaymentProcessor インターフェイスを実装します。 GetMerchantAccountPropertyMetadata と ValidateMerchantAccount の 2 つのインターフェイス メソッドが必要です。

POS 販売トランザクションの間に支払コネクタで商社プロパティを設定

次の図は、Commerce Scale Unit がデータベースからマーチャント プロパティを取得し、 BeginTransactionPaymentTerminalDeviceRequest 要求中に支払いコネクタに渡す方法を示しています。

IPaymentProcessor インターフェイスの実装

支払いフローに関連するマーチャント プロパティを処理するには、Microsoft.Dynamics.Retail.PaymentSDK ライブラリで定義されている IPaymentProcessor インターフェイスを実装します。 次の例は、2 つの必須インターフェイス メソッド、GetMerchantAccountPropertyMetadata と ValidateMerchantAccount を実装する方法を示しています。. 他のインターフェイス メソッドは空白のままにしておくことができます (たとえば、 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;
    }
}

必須商社プロパティ フィールド

次の表は、 GetMerchantAccountPropertyMetadata メソッドの一部として設定した必要なマーチャント プロパティ フィールドを示しています。

* この列のサンプル値を、独自の支払いプロセッサの一意の値に置き換えます。