How to: Create a payment connector

Further reading
Microsoft Dynamics AX 2012 for Developers [AX 2012] SDK Download

What is a payment connector

We have introduced in AX 2012 new pluggable payments which works on all of the Dynamics channels. Once the connector is loaded all of the AX payment configuration pages will display the required fields to configure the selected payment connector. Once the connector is configured they can be validated and then pushed to the required channel. The new payment connector supports multi-channel payments meaning you can authorize a payment in POS and capture the payment in AX etc. The new payment connector can also support the new touch screen payment terminal devices (this is covered in another document).

How to create a payment connector

First install the RetailPOS.msi and then unzip the attached file (TemplateConnector.zip) Open up the TemplateConnector.csproj

Right click on the project and click on properties

Rename the assembly name to the name you want your assembly to be called.

Open up the TemplateConnector.cs and change the following properties, List the countries your connector supports.

To display a list of the TODOs in the code Ctrl + \, t will display all the Task List. This lists all the items that need to be changed before the connector can be used. All the properties in the response like AuthorizationResponse will be sent to the next operation by the client i.e. capture request will contain the AuthorizationResponse properties. By doing this you can store any state required by the payment provider. Please make sure not to store any PCI data in any of the response property bags.

Here is the property bag hierarchy for L2/3 if you dont support certain levels you should return an error message so the client can take action. Level 2
<L2Data> <OrderDatetime Namespace='L2Data' Type='DateTime' /> <OrderNumber Namespace='L2Data' Type='String' /> <InvoiceDatetime Namespace='L2Data' Type='DateTime' /> <InvoiceNumber Namespace='L2Data' Type='String' /> <OrderDescription Namespace='L2Data' Type='String' /> <SummaryCommodityCode Namespace='L2Data' Type='String' /> <MerchantContact Namespace='L2Data' Type='String' /> <MerchantTaxId Namespace='L2Data' Type='String' />

<MerchantType Namespace='L2Data' Type='String' /> <PurchaserId Namespace='L2Data' Type='String' /> <PurchaserTaxId Namespace='L2Data' Type='String' /> <ShipToCity Namespace='L2Data' Type='String' /> <ShipToCounty Namespace='L2Data' Type='String' /> <ShipToState_ProvinceCode Namespace='L2Data' Type='String' /> <ShipToPostalCode Namespace='L2Data' Type='String' /> <ShipToCountryCode Namespace='L2Data' Type='String' /> <ShipFromCity Namespace='L2Data' Type='String' /> <ShipFromCounty Namespace='L2Data' Type='String' /> <ShipFromState_ProvinceCode Namespace='L2Data' Type='String' /> <ShipFromPostalCode Namespace='L2Data' Type='String' /> <ShipFromCountryCode Namespace='L2Data' Type='String' /> <DiscountAmount Namespace='L2Data' Type='Decimal' /> <MiscCharge Namespace='L2Data' Type='Decimal' /> <DutyAmount Namespace='L2Data' Type='Decimal' /> <FreightAmount Namespace='L2Data' Type='Decimal' /> <HandlingCharge Namespace='L2Data' Type='Decimal' /> <IsTaxable Namespace='L2Data' Type='String' /> <TotalTaxAmount Namespace='L2Data' Type='Decimal' /> <TotalTaxRate Namespace='L2Data' Type='Decimal' /> <MerchantName Namespace='L2Data' Type='String' /> <MerchantStreet Namespace='L2Data' Type='String' /> <MerchantCity Namespace='L2Data' Type='String' /> <MerchantState Namespace='L2Data' Type='String' /> <MerchantCounty Namespace='L2Data' Type='String' /> <MerchantCountryCode Namespace='L2Data' Type='String' /> <MerchantZip Namespace='L2Data' Type='String' /> <TaxRate Namespace='L2Data' Type='Decimal' /> <TaxAmount Namespace='L2Data' Type='Decimal' /> <TaxDescription Namespace='L2Data' Type='String' /> <TaxTypeIdentifier Namespace='L2Data' Type='String' /> <RequesterName Namespace='L2Data' Type='String' /> <TotalAmount Namespace='L2Data' Type='Decimal' /> <PurchaseCardType Namespace='L2Data' Type='String' /> <AmexLegacyDescription1 Namespace='L2Data' Type='String' /> <AmexLegacyDescription2 Namespace='L2Data' Type='String' /> <AmexLegacyDescription3 Namespace='L2Data' Type='String' /> <AmexLegacyDescription4 Namespace='L2Data' Type='String' /> <TaxDetails> <TaxDetail> <TaxTypeIdentifier Namespace='TaxDetail' Type='String' /> <TaxRate Namespace='TaxDetail' Type='Decimal' /> <TaxDescription Namespace='TaxDetail' Type='String' /> <TaxAmount Namespace='TaxDetail' Type='Decimal' /> </TaxDetail> </TaxDetails> <MiscellaneousCharges> <MiscellaneousCharge> <ChargeType Namespace='MiscellaneousCharge' Type='String' /> <ChargeAmount Namespace='MiscellaneousCharge' Type='Decimal' /> </MiscellaneousCharge> </MiscellaneousCharges> </L2Data>

Level 3
<L3Data> <L3DataItems> <SequenceNumber Namespace='L3Data' Type='String' /> <CommodityCode Namespace='L3Data' Type='String' /> <ProductCode Namespace='L3Data' Type='String' /> <ProductName Namespace='L3Data' Type='String' /> <ProductSKU Namespace='L3Data' Type='String' /> <Descriptor Namespace='L3Data' Type='String' /> <UnitOfMeasure Namespace='L3Data' Type='String' /> <UnitPrice Namespace='L3Data' Type='Decimal' /> <Discount Namespace='L3Data' Type='Decimal' /> <DiscountRate Namespace='L3Data' Type='Decimal' /> <Quantity Namespace='L3Data' Type='Decimal' /> <MiscCharge Namespace='L3Data' Type='Decimal' /> <NetTotal Namespace='L3Data' Type='Decimal' /> <TaxAmount Namespace='L3Data' Type='Decimal' /> <TaxRate Namespace='L3Data' Type='Decimal' /> <TotalAmount Namespace='L3Data' Type='Decimal' /> <CostCenter Namespace='L3Data' Type='String' /> <FreightAmount Namespace='L3Data' Type='Decimal' /> <HandlingAmount Namespace='L3Data' Type='Decimal' /> <CarrierTrackingNumber Namespace='L3Data' Type='String' /> <MerchantTaxID Namespace='L3Data' Type='String' /> <MerchantCatalogNumber Namespace='L3Data' Type='String' /> <TaxCategoryApplied Namespace='L3Data' Type='String' /> <PickupAddress Namespace='L3Data' Type='String' /> <PickupCity Namespace='L3Data' Type='String' /> <PickupState Namespace='L3Data' Type='String' /> <PickupCounty Namespace='L3Data' Type='String' /> <PickupZip Namespace='L3Data' Type='String' /> <PickupCountry Namespace='L3Data' Type='String' /> <PickupDatetime Namespace='L3Data' Type='DateTime' /> <PickupRecordNumber Namespace='L3Data' Type='String' /> <CarrierShipmentNumber Namespace='L3Data' Type='String' /> <UNSPSCCode Namespace='L3Data' Type='String' /> <TaxDetails> <TaxDetail> <TaxTypeIdentifier Namespace='TaxDetail' Type='String' /> <TaxRate Namespace='TaxDetail' Type='Decimal' /> <TaxDescription Namespace='TaxDetail' Type='String' /> <TaxAmount Namespace='TaxDetail' Type='Decimal' /> </TaxDetail> </TaxDetails> <MiscellaneousCharges> <MiscellaneousCharge> <ChargeType Namespace='MiscellaneousCharge' Type='String' /> <ChargeAmount Namespace='MiscellaneousCharge' Type='Decimal' /> </MiscellaneousCharge> </MiscellaneousCharges> </L3DataItems> </L3Data>

Example of Authorize request and response using the Dynamics payment Connector
<Request> <AssemblyName Namespace='MerchantAccount' Type='String' /> <MerchantId Namespace='MerchantAccount' Type='String' /> <ServiceAccountId Namespace='MerchantAccount' Type='String' /> <WLID Namespace='MerchantAccount' Type='String' /> <Password Namespace='MerchantAccount' Type='String' /> <Environment Namespace='MerchantAccount' Type='String' /> <CertificatePassword Namespace='MerchantAccount' Type='String' /> <CertificatePrivateKey Namespace='MerchantAccount' Type='String' /> <CertificatePublicKey Namespace='MerchantAccount' Type='String' /> <CustomerPortal Namespace='MerchantAccount' Type='String' /> <SupportedCurrencies Namespace='MerchantAccount' Type='String' /> <SupportedTenderTypes Namespace='MerchantAccount' Type='String' /> <IndustryType Namespace='TransactionData' Type='String' /> <PurchaseLevel Namespace='TransactionData' Type='String' /> <AllowPartialAuthorization Namespace='TransactionData' Type='String' /> <SupportCardTokenization Namespace='TransactionData' Type='String' /> <Amount Namespace='TransactionData' Type='Decimal' /> <CurrencyCode Namespace='TransactionData' Type='String' /> <CardType Namespace='PaymentCard' Type='String' /> <CardNumber Namespace='PaymentCard' Type='String' /> <CardVerificationValue Namespace='PaymentCard' Type='String' /> <ExpirationYear Namespace='PaymentCard' Type='Decimal' /> <ExpirationMonth Namespace='PaymentCard' Type='Decimal' /> <StreetAddress Namespace='PaymentCard' Type='String' /> <PostalCode Namespace='PaymentCard' Type='String' /> </Request> <Response> <Properties> <AuthorizationResult Namespace='AuthorizationResponse' Type='String' /> <CardType Namespace='AuthorizationResponse' Type='String' /> <ApprovalCode Namespace='AuthorizationResponse' Type='String' /> <ApprovedAmount Namespace='AuthorizationResponse' Type='Decimal' /> <AvailableBalance Namespace='AuthorizationResponse' Type='Decimal' /> <AVSDetail Namespace='AuthorizationResponse' Type='String' /> <AVSResult Namespace='AuthorizationResponse' Type='String' /> <CashBackAmount Namespace='AuthorizationResponse' Type='Decimal' /> <CVV2Result Namespace='AuthorizationResponse' Type='String' /> <CardToken Namespace='AuthorizationResponse' Type='String' /> <ExternalInvoiceNumber Namespace='AuthorizationResponse' Type='String' /> <ExternalReferenceId Namespace='AuthorizationResponse' Type='String' /> <ProviderTransactionId Namespace='AuthorizationResponse' Type='String' /> <CurrencyCode Namespace='AuthorizationResponse' Type='String' /> <TransactionDateTime Namespace='AuthorizationResponse' Type='DateTime' /> <Last4Digits Namespace='AuthorizationResponse' Type='String' /> <IsSwiped Namespace='AuthorizationResponse' Type='String' /> <TransactionGuid Namespace='AuthorizationResponse' Type='String' /> <ResponseCode Namespace='AuthorizationResponse' Type='String' /> <TransactionType Namespace='AuthorizationResponse' Type='String' /> </Properties> <ServiceAccountId Namespace='MerchantAccount' Type='String' /> <ConnectorName Namespace='Connector' Type='String' />

</Response>

Example of Capture request and response using the Dynamics payment Connector
<Request> <AssemblyName Namespace='MerchantAccount' Type='String' /> <MerchantId Namespace='MerchantAccount' Type='String' /> <ServiceAccountId Namespace='MerchantAccount' Type='String' /> <WLID Namespace='MerchantAccount' Type='String' /> <Password Namespace='MerchantAccount' Type='String' /> <Environment Namespace='MerchantAccount' Type='String' /> <CertificatePassword Namespace='MerchantAccount' Type='String' /> <CertificatePrivateKey Namespace='MerchantAccount' Type='String' /> <CertificatePublicKey Namespace='MerchantAccount' Type='String' /> <CustomerPortal Namespace='MerchantAccount' Type='String' /> <SupportedCurrencies Namespace='MerchantAccount' Type='String' /> <SupportedTenderTypes Namespace='MerchantAccount' Type='String' /> <Properties> <AuthorizationResult Namespace='AuthorizationResponse' Type='String' /> <CardType Namespace='AuthorizationResponse' Type='String' /> <ApprovalCode Namespace='AuthorizationResponse' Type='String' /> <ApprovedAmount Namespace='AuthorizationResponse' Type='Decimal' /> <AvailableBalance Namespace='AuthorizationResponse' Type='Decimal' /> <AVSDetail Namespace='AuthorizationResponse' Type='String' /> <AVSResult Namespace='AuthorizationResponse' Type='String' /> <CashBackAmount Namespace='AuthorizationResponse' Type='Decimal' /> <CVV2Result Namespace='AuthorizationResponse' Type='String' /> <CardToken Namespace='AuthorizationResponse' Type='String' /> <ExternalInvoiceNumber Namespace='AuthorizationResponse' Type='String' /> <ExternalReferenceId Namespace='AuthorizationResponse' Type='String' /> <ProviderTransactionId Namespace='AuthorizationResponse' Type='String' /> <CurrencyCode Namespace='AuthorizationResponse' Type='String' /> <TransactionDateTime Namespace='AuthorizationResponse' Type='DateTime' /> <Last4Digits Namespace='AuthorizationResponse' Type='String' /> <IsSwiped Namespace='AuthorizationResponse' Type='String' /> <TransactionGuid Namespace='AuthorizationResponse' Type='String' /> <ResponseCode Namespace='AuthorizationResponse' Type='String' /> <TransactionType Namespace='AuthorizationResponse' Type='String' /> </Properties> <ConnectorName Namespace='Connector' Type='String' /> <IndustryType Namespace='TransactionData' Type='String' /> <PurchaseLevel Namespace='TransactionData' Type='String' /> <Amount Namespace='TransactionData' Type='Decimal' /> <CurrencyCode Namespace='TransactionData' Type='String' /> </Request> <Response> <Properties> <CaptureResult Namespace='CaptureResponse' Type='String' /> <Last4Digits Namespace='CaptureResponse' Type='String' /> <CardType Namespace='CaptureResponse' Type='String' /> <ExternalInvoiceNumber Namespace='CaptureResponse' Type='String' /> <ExternalReferenceId Namespace='CaptureResponse' Type='String' />

<ProviderTransactionId Namespace='CaptureResponse' Type='String' /> <CurrencyCode Namespace='CaptureResponse' Type='String' /> <TransactionDateTime Namespace='CaptureResponse' Type='DateTime' /> <IsSwiped Namespace='CaptureResponse' Type='String' /> <TransactionGuid Namespace='CaptureResponse' Type='String' /> <ResponseCode Namespace='CaptureResponse' Type='String' /> <TransactionType Namespace='CaptureResponse' Type='String' /> </Properties> <ServiceAccountId Namespace='MerchantAccount' Type='String' /> <ConnectorName Namespace='Connector' Type='String' /> </Response>

Example of Linked Refund request and response using the Dynamics payment Connector
<Request> <AssemblyName Namespace='MerchantAccount' Type='String' /> <MerchantId Namespace='MerchantAccount' Type='String' /> <ServiceAccountId Namespace='MerchantAccount' Type='String' /> <WLID Namespace='MerchantAccount' Type='String' /> <Password Namespace='MerchantAccount' Type='String' /> <Environment Namespace='MerchantAccount' Type='String' /> <CertificatePassword Namespace='MerchantAccount' Type='String' /> <CertificatePrivateKey Namespace='MerchantAccount' Type='String' /> <CertificatePublicKey Namespace='MerchantAccount' Type='String' /> <CustomerPortal Namespace='MerchantAccount' Type='String' /> <SupportedCurrencies Namespace='MerchantAccount' Type='String' /> <SupportedTenderTypes Namespace='MerchantAccount' Type='String' /> <Properties> <CaptureResult Namespace='CaptureResponse' Type='String' /> <Last4Digits Namespace='CaptureResponse' Type='String' /> <CardType Namespace='CaptureResponse' Type='String' /> <ExternalInvoiceNumber Namespace='CaptureResponse' Type='String' /> <ExternalReferenceId Namespace='CaptureResponse' Type='String' /> <ProviderTransactionId Namespace='CaptureResponse' Type='String' /> <CurrencyCode Namespace='CaptureResponse' Type='String' /> <TransactionDateTime Namespace='CaptureResponse' Type='DateTime' /> <IsSwiped Namespace='CaptureResponse' Type='String' /> <TransactionGuid Namespace='CaptureResponse' Type='String' /> <ResponseCode Namespace='CaptureResponse' Type='String' /> <TransactionType Namespace='CaptureResponse' Type='String' /> </Properties> <ConnectorName Namespace='Connector' Type='String' /> <IndustryType Namespace='TransactionData' Type='String' /> <PurchaseLevel Namespace='TransactionData' Type='String' /> <SupportCardTokenization Namespace='TransactionData' Type='String' /> <Amount Namespace='TransactionData' Type='Decimal' /> <CurrencyCode Namespace='TransactionData' Type='String' /> </Request> <Response> <Properties> <RefundResult Namespace='RefundResponse' Type='String' /> <Last4Digits Namespace='RefundResponse' Type='String' />

<CardType Namespace='RefundResponse' Type='String' /> <ApprovalCode Namespace='RefundResponse' Type='String' /> <ExternalInvoiceNumber Namespace='RefundResponse' Type='String' /> <ExternalReferenceId Namespace='RefundResponse' Type='String' /> <ProviderTransactionId Namespace='RefundResponse' Type='String' /> <CurrencyCode Namespace='RefundResponse' Type='String' /> <TransactionDateTime Namespace='RefundResponse' Type='DateTime' /> <IsSwiped Namespace='RefundResponse' Type='String' /> <TransactionGuid Namespace='RefundResponse' Type='String' /> <ResponseCode Namespace='RefundResponse' Type='String' /> <TransactionType Namespace='RefundResponse' Type='String' /> </Properties> <ServiceAccountId Namespace='MerchantAccount' Type='String' /> <ConnectorName Namespace='Connector' Type='String' /> </Response>

Example of Void request and response using the Dynamics payment Connector
<Request> <AssemblyName Namespace='MerchantAccount' Type='String' /> <MerchantId Namespace='MerchantAccount' Type='String' /> <ServiceAccountId Namespace='MerchantAccount' Type='String' /> <WLID Namespace='MerchantAccount' Type='String' /> <Password Namespace='MerchantAccount' Type='String' /> <Environment Namespace='MerchantAccount' Type='String' /> <CertificatePassword Namespace='MerchantAccount' Type='String' /> <CertificatePrivateKey Namespace='MerchantAccount' Type='String' /> <CertificatePublicKey Namespace='MerchantAccount' Type='String' /> <CustomerPortal Namespace='MerchantAccount' Type='String' /> <SupportedCurrencies Namespace='MerchantAccount' Type='String' /> <SupportedTenderTypes Namespace='MerchantAccount' Type='String' /> <Properties> <AuthorizationResult Namespace='AuthorizationResponse' Type='String' /> <CardType Namespace='AuthorizationResponse' Type='String' /> <ApprovalCode Namespace='AuthorizationResponse' Type='String' /> <ApprovedAmount Namespace='AuthorizationResponse' Type='Decimal' /> <AvailableBalance Namespace='AuthorizationResponse' Type='Decimal' /> <AVSDetail Namespace='AuthorizationResponse' Type='String' /> <AVSResult Namespace='AuthorizationResponse' Type='String' /> <CashBackAmount Namespace='AuthorizationResponse' Type='Decimal' /> <CVV2Result Namespace='AuthorizationResponse' Type='String' /> <CardToken Namespace='AuthorizationResponse' Type='String' /> <ExternalInvoiceNumber Namespace='AuthorizationResponse' Type='String' /> <ExternalReferenceId Namespace='AuthorizationResponse' Type='String' /> <ProviderTransactionId Namespace='AuthorizationResponse' Type='String' /> <CurrencyCode Namespace='AuthorizationResponse' Type='String' /> <TransactionDateTime Namespace='AuthorizationResponse' Type='DateTime' /> <Last4Digits Namespace='AuthorizationResponse' Type='String' /> <IsSwiped Namespace='AuthorizationResponse' Type='String' /> <TransactionGuid Namespace='AuthorizationResponse' Type='String' /> <ResponseCode Namespace='AuthorizationResponse' Type='String' /> <TransactionType Namespace='AuthorizationResponse' Type='String' /> </Properties>

<ConnectorName Namespace='Connector' Type='String' /> </Request> <Response> <Properties> <VoidResult Namespace='VoidResponse' Type='String' /> <Last4Digits Namespace='VoidResponse' Type='String' /> <CardType Namespace='VoidResponse' Type='String' /> <ExternalInvoiceNumber Namespace='VoidResponse' Type='String' /> <ExternalReferenceId Namespace='VoidResponse' Type='String' /> <ProviderTransactionId Namespace='VoidResponse' Type='String' /> <CurrencyCode Namespace='VoidResponse' Type='String' /> <TransactionDateTime Namespace='VoidResponse' Type='DateTime' /> <IsSwiped Namespace='VoidResponse' Type='String' /> <TransactionGuid Namespace='VoidResponse' Type='String' /> <ResponseCode Namespace='VoidResponse' Type='String' /> <TransactionType Namespace='VoidResponse' Type='String' /> </Properties> <ServiceAccountId Namespace='MerchantAccount' Type='String' /> <ConnectorName Namespace='Connector' Type='String' /> </Response>

Deployment
To use the connector in the following channels carry out the following: AX copy the connector assembly to your AX client and server Connectors directory o %Program Files (x86)%\Microsoft Dynamics AX\6.2\Client\Bin\Connectors o %Program Files%\Microsoft Dynamics AX\6.2\Server\AxaptaDev\bin\Connectors o Restart AOS POS copy the connector assembly to %Pos%\Connectors (To copy this dll to multiple installations of POS you can use System Center or similar). Once it is installed start POS. SharePoint you need to deploy the new assembly to the GAC o Best to include the assembly within the visual studio project 1. Open up the required SharePoint project and double click on the Package.package and then click on Advanced

2. Then add the new payment connector assembly to the list. An example of what the page looks like is below

3. Then build and deploy the new SharePoint site.

AX Setup Configuration
How to create and control modes of payment for individual channels